*** Passepartout 0.7 User's Guide ***

    WHAT IS PASSEPARTOUT?

    Passepartout is an
      open source
      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
      WYSIWYG layout editor with a high-quality
      typesetting engine.  Passepartout is released under a 
      
      BSD license.  The Passepartout webpage can be found at
      
      http://www.stacken.kth.se/project/pptout/.
    
    

    Passepartout is not a word processor

    You do not use Passepartout for writing text, because it
	is only a layout 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 EPS files. You write the text in your
	favorite text editor (e.g. Emacs or
	VI) in an XML-based
	format. The XML file is then typeset using
	a typesetting engine called xml2ps.
    

    INSTALLATION

    See the INSTALL file for installation
      instructions.
    

    USING PASSEPARTOUT

    

    Starting the program

    You start Passepartout by typing
        "passepartout &" in your terminal
        window. You are then presented with an empty document window
        (no document has been created).
    You can get a list of command line options accepted by
	Passepartout with "passepartout --help".
    

    Creating a new document

    To create an empty document, select
          New ... from the
          File 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 Properties ... from
          the File menu.
      
    

    Adding pages

    To add a page to the document, select
        Insert Before ... or
        Insert After ... from the
        Page menu. If the document was created from
        a template, you will be asked to select a template
        page.
    

    Turning pages

    You can change the active page with the page selector in
	the lower right hand corner of the main window.
    

    Importing images

    You can add an image to a page by selecting 
	Insert Image ... from the
	Edit menu. Passepartout accepts
	EPS, PNG,
	RAS, BMP,
	XPM, PNM,
	TIF, JPG and
	GIF files.
      
    

    Text frames & text streams

    A text frame can be added to a page by selecting
	Insert Text Frame ... from the
	Edit menu.  The text shown in a text frame
	is read from an XML file, but the text
	frame is not connected directly to the file. Instead, each
	text frame is connected to a text
	stream, which in turn is connected to an
	XML 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.
    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 XML
	file to associated with the frame. If the
	XML file is not in the xml2ps
	DTD, you will also have to specify a
	stylesheet that translates the file to the xml2ps
	format.
    You can change the stream connected to a text frame in the
	Object Properties window. Text streams
	may be manipulated in the Text Streams
	window, accessible from the Streams
	item on the View menu.
      
    

    Manipulating objects

    Any object can be moved or resized using the mouse.  The
	properties of an object can also be manipulated explicitly in
	the Object Properties window which is
	accessible through the Properties
	item on the View 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.
    An object can be locked, preventing you
	from accidentally moving or resizing it with the mouse.
	Locked frames have a gray border.
    You can also choose whether text should flow around a
	frame or not.
    

    Arranging & grouping

    Several frames may be combined into a
	group by selecting more than one frame
	(using CTRL-button 1) and selecting
	Group from the
	Arrange submenu in the
	Edit menu.  Frames can also be moved up
	or down relative to other frames using the items in the
	Arrange submenu.
    

    Opening and saving files

    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.
      
    Note: Passepartout does not (yet) ask before writing
	over existing files! There is also no warning before closing
	an unsaved file.
    

    Printing

    Passepartout can print PostScript or
	EPS files.  (EPS files
	may only contain one page.)  The file can be piped to a
	printing command, such as "lpr", or saved to
	a file.
    Select Print ...
	from the File menu. There is also a
	Print Preview item that will start
	an external PostScript viewer (if one has been
	defined).
    

    Multiple views

    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.
    A view can be duplicated by selecting
	New View from the
	File menu. A document will not be closed
	until all its views has been closed.
    

    CREATING THE XML FILES

    XML 
      (http://www.w3.org/XML/) 
      is an acronym for "Extensible Markup Language".  XML is a
      meta-language for describing different kinds of file formats in
      a standardized fashion.  An XML file is an
      ordinary text file, but the text is formatted according to
      strict rules.  If you have written HTML
      before, then you are already familiar with some of the key
      concepts.  If you don't have any previous experience with
      XML, we would recommend reading an online
      tutorial:
      
	      http://www.w3schools.com/xml/
    
	      http://www.spiderpro.com/bu/buxmlm001.html
    
    

    The typesetting engine

    The typesetting engine of Passepartout is called
	xml2ps and is also available as a
	stand-alone program. It has its own DTD.
	XSLT
	stylesheets can be used to translate any XML file to
	the format that xml2ps will accept.
    There are two basic approaches to writing text for
	Passepartout:
	
	Write the text in XML
	      conforming directly to the typography-level xml2ps
	      DTD.
    Write the text in XML
	      conforming to a high level, logically stuctured
	      DTD (either an existing one, such as
	      XHTML or DocBook, or one of your own
	      design), and use an XSLT stylesheet
	      to transform the text into a document conforming to the
	      xml2ps DTD.
    
	
	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
	XHTML 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.
      
    

    A description of the xml2ps DTD

    

    Nodes allowed in an xml2ps file:

    <block-container>Root node and parent node of
	      <para> or other
	      <block-container> nodes.
    Parameters:
    margin-top, margin-bottom, margin-left,
		margin-right: Margins (lengths).
    All <font> parameters are also accepted.
    <bp>Mark a point in a word where hyphenation is
	      allowed.
    <font>Change font inside a
	      <para>.
    Parameters:
    underline:
	      The only accepted value is "1".
    font-family:
	      Accepted values are PostScript font (not font family)
	      names.
    font-size: 
	      Font size (a length or a percentage).
    letter-spacing:
	      Extra character spacing (a length).
    <leader>Explicit whitespace
    Parameters:
    width:
	      Width of whitespace (a length).
    <linebreak>Explicit linebreak
    <para>A "paragraph". All text must be contained
	      within paragraphs. Paragraphs may not be nested.
    Parameters:
    align:
	      Text alignment. Accepted values are "left", "right",
	      "center" and "justify".
    line-height: 
	      Distance between lines as a factor relative to the font
	      size.
    All <font> and <block-container>
	      parameters are also accepted.
    Lengths may be specified in points ("12pt", "-0.3pt") or
	in relation to the font size ("2em", "-0.3em").
    

    A short example

    <?xml version="1.0"?><block-container font-family="Bookman-Light"
	font-size="12pt"><para font-family="AvantGarde-Demi" font-size="36.3pt" 
	  align="center" margin-bottom="20pt">
	This is a centered headline in Avant Garde demi-bold 36.3 points
	</para><para align="justify"> This is text in
	Bookman Light 12 points.  <font
	font-size="50%">This is text in Bookman Light 6
	points.</font> Some words may be
	typeset in an <font
	font-family="Bookman-LightItalic">italic</font>
	typeface. The word
	"hyphen<bp/>ated" may be
	hyphen<bp/>ated.
	</para><para margin-left="12pt" align="left"
	  line-height="1.5"> This is a left-justified
	  indented paragraph with a line height of 18 points.
	  <font underline="1">This sentence is
	  underlined.</font> In this sentence,
	  there is an unnecessary <leader
	  width="5em"/> space.
	  </para></block-container>

    CONFIGURATION

    Passepartout gets its configuration options from the file
      .pptout 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.
    Note: you should not edit this file while
    Passepartout is running, because it will be overwritten when the
    program ends.
    

    Settings that may be of interest:

    DefaultResolutionDefault resolution for images, in pixels per
	inch
    LengthUnitDefault length unit. Default is pt (points).
    PaperNameDefault paper name. Default is A4.
    PSInterpreterCommand to run ghostscript.
    PrintCommandDefault command used for printing. (Default is
	"lpr".)
    StylesheetPathDefault path to look for
	XSLT stylesheets in.
    