<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
	"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> 
<article>
  <articleinfo>
    <title>Passepartout 0.7 User's Guide</title>
  </articleinfo>

  <graphic fileref="pptout.png"/>
  
  <section><title>What is Passepartout?</title>

    <para>Passepartout is an
      <ulink url="http://www.opensource.org/">open source</ulink>
      desktop publishing application for X-Windows (Unix). The goal is
      to provide a simple and user-friendly, yet powerful tool for
      creating printed material. Passepartout combines a
      <acronym>WYSIWYG</acronym> layout editor with a high-quality
      typesetting engine.  Passepartout is released under a 
      <ulink url="http://www.opensource.org/licenses/bsd-license.php">
      BSD license</ulink>.  The Passepartout webpage can be found at
      <ulink url="http://www.stacken.kth.se/project/pptout/">
      http://www.stacken.kth.se/project/pptout/</ulink>.
    </para>
  
    <section><title>Passepartout is not a word processor</title>
      
      <para>You do not use Passepartout for writing text, because it
	is only a <emphasis>layout</emphasis> editor. Basically
	speaking, Passepartout is in the business of taking the
	different parts that make up a page, such as text, photos,
	graphics, and "gluing" them on a piece of paper. Passepartout
	can import from several different bitmapped image formats as
	well as <acronym>EPS</acronym><footnote><para>Encapsulated
	PostScript</para></footnote> files. You write the text in your
	favorite text editor (e.g. <acronym>Emacs</acronym> or
	<acronym>VI</acronym>) in an <acronym>XML</acronym>-based
	format. The <acronym>XML</acronym> file is then typeset using
	a typesetting engine called <acronym>xml2ps</acronym>.</para>
    </section>
  </section>
  
  <section>
    <title>Installation</title>
    <para>See the <filename>INSTALL</filename> file for installation
      instructions.</para>
  </section>

  <section>
    <title>Using Passepartout</title>
    <section>
      <title>Starting the program</title>

      <para>You start Passepartout by typing
        <command>passepartout&#160;&amp;</command> in your terminal
        window. You are then presented with an empty document window
        (no document has been created).</para>

      <para>You can get a list of command line options accepted by
	Passepartout with <command>passepartout&#160;--help</command>.</para>
    </section>

    <section>
      <title>Creating a new document</title>

      <para>To create an empty document, select
          <guimenuitem>New&#160;...</guimenuitem> from the
          <guimenu>File</guimenu> menu. In the dialog that will
          appear, you can choose between creating a document from an
          existing template (any Passepartout document can be used as
          a template) or by specifying the paper format. You can
          also specify the page number the first page in the document
          should have.  These settings can be changed at a later point
          by selecting <guimenuitem>Properties&#160;...</guimenuitem> from
          the <guimenu>File</guimenu> menu.
      </para>
    </section>

    <section>
      <title>Adding pages</title>

      <para>To add a page to the document, select
        <guimenuitem>Insert Before&#160;...</guimenuitem> or
        <guimenuitem>Insert After&#160;...</guimenuitem> from the
        <guimenu>Page</guimenu> menu. If the document was created from
        a template, you will be asked to select a template
        page.</para>
    </section>
    
    <section><title>Turning pages</title>
      <para>You can change the active page with the page selector in
	the lower right hand corner of the main window.</para>
    </section>
    
    <section><title>Importing images</title>

      <para>You can add an image to a page by selecting 
	<guimenuitem>Insert Image&#160;...</guimenuitem> from the
	<guimenu>Edit</guimenu> menu. Passepartout accepts
	<acronym>EPS</acronym>, <acronym>PNG</acronym>,
	<acronym>RAS</acronym>, <acronym>BMP</acronym>,
	<acronym>XPM</acronym>, <acronym>PNM</acronym>,
	<acronym>TIF</acronym>, <acronym>JPG</acronym> and
	<acronym>GIF</acronym> files.
      </para>
    </section>
    
    <section><title>Text frames &amp; text streams</title> 
      <para>A text frame can be added to a page by selecting
	<guimenuitem>Insert Text Frame&#160;...</guimenuitem> from the
	<guimenu>Edit</guimenu> menu.  The text shown in a text frame
	is read from an <acronym>XML</acronym> file, but the text
	frame is not connected directly to the file. Instead, each
	text frame is connected to a <glossterm>text
	stream</glossterm>, which in turn is connected to an
	<acronym>XML</acronym> file. The reason for this is that a
	text may span several frames, possibly on several pages. All
	frames that are meant to be part of of the same text are
	connected to the same text stream. The stream splits the text
	into parts and puts them in the appropriate frames.</para>
      
      <para>When you add a text frame you are presented with a dialog
	that lets you choose between creating a new text stream or
	using an existing stream (or none). If you choose to create a
	new stream, you have to specify the <acronym>XML</acronym>
	file to associated with the frame. If the
	<acronym>XML</acronym> file is not in the xml2ps
	<acronym>DTD</acronym>, you will also have to specify a
	stylesheet that translates the file to the xml2ps
	format.</para>

      <para>You can change the stream connected to a text frame in the
	<guilabel>Object Properties</guilabel> window. Text streams
	may be manipulated in the <guilabel>Text Streams</guilabel>
	window, accessible from the <guimenuitem>Streams</guimenuitem>
	item on the <guimenu>View</guimenu> menu.
      </para>
    </section>
    
    <section id="objectproperties">
      <title>Manipulating objects</title>
      
      <para>Any object can be moved or resized using the mouse.  The
	properties of an object can also be manipulated explicitly in
	the <guilabel>Object Properties</guilabel> window which is
	accessible through the <guimenuitem>Properties</guimenuitem>
	item on the <guimenu>View</guimenu> menu. When an object is
	selected, its properties can be edited in the window. Not all
	properties apply to all types of object. The properties that
	are unique to certain kinds of object are displayed in
	separate tabs.</para>

      <para>An object can be <emphasis>locked</emphasis>, preventing you
	from accidentally moving or resizing it with the mouse.
	Locked frames have a gray border.</para>

      <para>You can also choose whether text should flow around a
	frame or not.</para>
    </section>

    <section>
      <title>Arranging &amp; grouping</title>

      <para>Several frames may be combined into a
	<emphasis>group</emphasis> by selecting more than one frame
	(using CTRL-button&#160;1) and selecting
	<guimenuitem>Group</guimenuitem> from the
	<guimenu>Arrange</guimenu> submenu in the
	<guimenu>Edit</guimenu> menu.  Frames can also be moved up
	or down relative to other frames using the items in the
	<guimenu>Arrange</guimenu> submenu.</para>
    </section>
    
    <section>
      <title>Opening and saving files</title>
      
      <para>Opening and saving files works much like in most other
	applications. 
	The text and images imported into the document are not saved
	as a part of the document.
      </para>
      <para>
	<emphasis>Note: Passepartout does not (yet) ask before writing
	over existing files! There is also no warning before closing
	an unsaved file.</emphasis>
      </para>
    </section>

    <section>
      <title>Printing</title>

      <para>Passepartout can print PostScript or
	<acronym>EPS</acronym> files.  (<acronym>EPS</acronym> files
	may only contain one page.)  The file can be piped to a
	printing command, such as <command>lpr</command>, or saved to
	a file.</para>
      
      <para>Select <guimenuitem>Print&#160;...</guimenuitem>
	from the <guimenu>File</guimenu> menu. There is also a
	<guimenuitem>Print Preview</guimenuitem> item that will start
	an external PostScript viewer (if one has been
	defined).</para>
    </section>

    <section>
      <title>Multiple views</title> 

      <para>A single document can be seen through more than one view. This
	lets you work with different pages of a document at the same
	time. You can also see the the same page at different zoom
	levels.</para>

      <para>A view can be duplicated by selecting
	<guimenuitem>New&#160;View</guimenuitem> from the
	<guimenu>File</guimenu> menu. A document will not be closed
	until all its views has been closed.</para>
    </section>
  </section>
  
  <section id="xml">
    <title>Creating the XML files</title>

    <para><acronym>XML</acronym> 
      (<ulink url="http://www.w3.org/XML/">http://www.w3.org/XML/</ulink>) 
      is an acronym for "Extensible Markup Language".  XML is a
      meta-language for describing different kinds of file formats in
      a standardized fashion.  An <acronym>XML</acronym> file is an
      ordinary text file, but the text is formatted according to
      strict rules.  If you have written <acronym>HTML</acronym>
      before, then you are already familiar with some of the key
      concepts.  If you don't have any previous experience with
      <acronym>XML</acronym>, we would recommend reading an online
      tutorial:
      <itemizedlist>
	<listitem><para>
	    <ulink url="http://www.w3schools.com/xml/">
	      http://www.w3schools.com/xml/</ulink>
	  </para></listitem>
	<listitem><para>
	    <ulink url="http://www.spiderpro.com/bu/buxmlm001.html">
	      http://www.spiderpro.com/bu/buxmlm001.html</ulink>
	  </para></listitem>
      </itemizedlist>
    </para>
    
    <section>
      <title>The typesetting engine</title>
      
      <para>The typesetting engine of Passepartout is called
	<application>xml2ps</application> and is also available as a
	stand-alone program. It has its own <acronym>DTD</acronym>
	<footnote><para>Document Type Definition.</para></footnote>.
	<ulink url="http://www.w3.org/TR/xslt"><acronym>XSLT</acronym>
	stylesheets</ulink> can be used to translate any XML file to
	the format that xml2ps will accept.</para>

      <para>There are two basic approaches to writing text for
	Passepartout:
	
	<orderedlist>
	  <listitem><para>Write the text in <acronym>XML</acronym>
	      conforming directly to the typography-level xml2ps
	      <acronym>DTD</acronym>.</para></listitem>
	  
	  <listitem><para>Write the text in <acronym>XML</acronym>
	      conforming to a high level, logically stuctured
	      <acronym>DTD</acronym> (either an existing one, such as
	      <acronym>XHTML</acronym> or DocBook, or one of your own
	      design), and use an <acronym>XSLT</acronym> stylesheet
	      to transform the text into a document conforming to the
	      xml2ps <acronym>DTD</acronym>.</para></listitem>
	</orderedlist>
	
	The advantage with the former approach is that you get
	superior control over the result, while the latter method is
	more suitable when writing longer texts. Stylesheets for
	<acronym>XHTML</acronym> and DocBook are supplied as
	examples. This document is in fact formatted in DocBook
	itself.  A good exercise for the reader is to modify the
	behaviour of these examples.
      </para>
    </section>
    
    <section>
      <title>A description of the xml2ps DTD</title>
      <variablelist>
	<title>Nodes allowed in an xml2ps file:</title>
	<varlistentry>
	  <term><markup>&lt;block-container&gt;</markup></term>
	  <listitem><para>Root node and parent node of
	      <markup>&lt;para&gt;</markup> or other
	      <markup>&lt;block-container&gt;</markup> nodes.</para>
	    
	    <para>Parameters:</para>
	    <para><markup>margin-top, margin-bottom, margin-left,
		margin-right</markup>: Margins (lengths).</para>
	    <para>All &lt;font&gt; parameters are also accepted.</para>
	  </listitem></varlistentry>
	
	<varlistentry>
	  <term><markup>&lt;bp&gt;</markup></term>
	  <listitem><para>Mark a point in a word where hyphenation is
	      allowed.</para></listitem></varlistentry>
	
	<varlistentry>
	  <term><markup>&lt;font&gt;</markup></term>
	  <listitem><para>Change font inside a
	      <markup>&lt;para&gt;</markup>.</para>
	    <para>Parameters:</para>
	    <para><markup>underline</markup>:
	      The only accepted value is "1".</para> 
	    <para><markup>font-family</markup>:
	      Accepted values are PostScript font (not font family)
	      names.</para>
	    <para><markup>font-size</markup>: 
	      Font size (a length or a percentage).</para>
	    <para><markup>letter-spacing</markup>:
	      Extra character spacing (a length).</para>
	  </listitem></varlistentry>
	
	<varlistentry>
	  <term><markup>&lt;leader&gt;</markup></term>
	  <listitem><para>Explicit whitespace</para>
	    <para>Parameters:</para>
	    <para><markup>width</markup>:
	      Width of whitespace (a length).</para></listitem></varlistentry>

	<varlistentry>
	  <term><markup>&lt;linebreak&gt;</markup></term>
	  <listitem><para>Explicit linebreak</para>
	  </listitem></varlistentry>

	<varlistentry>
	  <term><markup>&lt;para&gt;</markup></term>
	  <listitem><para>A "paragraph". All text must be contained
	      within paragraphs. Paragraphs may not be nested.</para>

	    <para>Parameters:</para>
	    <para><markup>align</markup>:
	      Text alignment. Accepted values are "left", "right",
	      "center" and "justify".</para>
	    <para><markup>line-height</markup>: 
	      Distance between lines as a factor relative to the font
	      size.</para>
	    <para>All &lt;font&gt; and &lt;block-container&gt;
	      parameters are also accepted.</para>
	  </listitem></varlistentry>
      </variablelist>

      <para>Lengths may be specified in points ("12pt", "-0.3pt") or
	in relation to the font size ("2em", "-0.3em").</para>
    </section>
    
    <section>
      <title>A short example</title>
      <programlisting>
	<markup>&lt;?xml version="1.0"?&gt;</markup>
	<markup>&lt;block-container font-family="Bookman-Light"
	font-size="12pt"&gt;</markup>

	<markup>&lt;para font-family="AvantGarde-Demi" font-size="36.3pt" 
	  align="center" margin-bottom="20pt"&gt;</markup>
	This is a centered headline in Avant Garde demi-bold 36.3 points
	<markup>&lt;/para&gt;</markup>

	<markup>&lt;para align="justify"&gt;</markup> This is text in
	Bookman Light 12 points.  <markup>&lt;font
	font-size="50%"&gt;</markup>This is text in Bookman Light 6
	points.<markup>&lt;/font&gt;</markup> Some words may be
	typeset in an <markup>&lt;font
	font-family="Bookman-LightItalic"&gt;</markup>italic<markup>&lt;/font&gt;</markup>
	typeface. The word
	&quot;hyphen<markup>&lt;bp/&gt;</markup>ated&quot; may be
	hyphen<markup>&lt;bp/&gt;</markup>ated.
	<markup>&lt;/para&gt;</markup>

	<markup>&lt;para margin-left="12pt" align="left"
	  line-height="1.5"&gt;</markup> This is a left-justified
	  indented paragraph with a line height of 18 points.
	  <markup>&lt;font underline="1"&gt;</markup>This sentence is
	  underlined.<markup>&lt;/font&gt;</markup> In this sentence,
	  there is an unnecessary <markup>&lt;leader
	  width="5em"/&gt;</markup> space.
	  <markup>&lt;/para&gt;</markup>

	<markup>&lt;/block-container&gt;</markup>
      </programlisting>
    </section>
  </section>
  
  <section>
    <title>Configuration</title>

    <para>Passepartout gets its configuration options from the file
      <filename>.pptout</filename> in your home directory.
      If the file does not already exist, Passepartout will create one
      with default values for all settings.
      If you want to, you can change these settings.</para>

    <para><emphasis>Note: you should not edit this file while
    Passepartout is running, because it will be overwritten when the
    program ends.</emphasis></para>

    <variablelist>
      <title>Settings that may be of interest:</title>

      <varlistentry>
      	<term><varname>DefaultResolution</varname></term>
	<listitem><para>Default resolution for images, in pixels per
	inch</para> </listitem></varlistentry>
      
      <varlistentry>
	<term><varname>LengthUnit</varname></term>
	<listitem><para>Default length unit. Default is pt (points).</para>
	</listitem></varlistentry>

      <varlistentry>
	<term><varname>PaperName</varname></term>
	<listitem><para>Default paper name. Default is A4.</para>
	</listitem></varlistentry>
      
      <varlistentry>
	<term><varname>PSInterpreter</varname></term>
	<listitem><para>Command to run ghostscript.</para></listitem>
      </varlistentry>
      
      <varlistentry>
	<term><varname>PrintCommand</varname></term>
	<listitem><para>Default command used for printing. (Default is
	<command>lpr</command>.)</para></listitem></varlistentry>

      <varlistentry>
	<term><varname>StylesheetPath</varname></term>
	<listitem><para>Default path to look for
	<acronym>XSLT</acronym> stylesheets in.</para></listitem>
      </varlistentry>

  </variablelist>

  </section>

</article>
