glabels-data 2.2.8-3build1 / usr / share / gnome / help / glabels / C / glabels.xml

<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  <!ENTITY legal SYSTEM "legal.xml">
  <!ENTITY appversion "2.2.6">
  <!ENTITY manrevision "2.2.6">
  <!ENTITY date "December 2007">
  <!ENTITY app "<application>gLabels</application>">
  <!-- Information about the entities
       The legal.xml file contains legal information, there is no need to edit the file. 
       Use the appversion entity to specify the version of the application.
       Use the manrevision entity to specify the revision number of this manual.
       Use the date entity to specify the release date of this manual.
       Use the app entity to specify the name of the application. -->
]>


<!-- 
      (Do not remove this comment block.)
  Maintained by the GNOME Documentation Project
  http://developer.gnome.org/projects/gdp
  Template version: 2.0 beta
  Template last modified Apr 11, 2002
-->

<!-- =============Document Header ============================= -->
<article id="index" lang="en">
<!-- please do not change the id; for translations, change lang to -->
<!-- appropriate code -->
  <articleinfo> 
    <title>&app; Manual V&manrevision;</title>       
	<abstract role="description">
      	<para> 
        User manual for the &app; label and business card creation program
      	</para>
    </abstract>
    <copyright> 
      <year>2003-2009</year> 
      <holder>Jim Evins</holder> 
    </copyright>
    	<publisher> 
      		<publishername> Jim Evins </publishername> 
    	</publisher> 

   &legal;
   <!-- This file  contains link to license for the documentation (GNU FDL), and 
        other legal stuff such as "NO WARRANTY" statement. Please do not change 
	any of this. -->

    <authorgroup> 
      <author role="maintainer"> 
		<firstname>Jim</firstname> 
		<surname>Evins</surname> 
      </author> 
      
<!-- This is appropriate place for other contributors: translators,
     maintainers,  etc. Commented out by default.
     
      <othercredit role="translator">
		<firstname>Latin</firstname> 
		<surname>Translator 1</surname> 
		<affiliation> 
	  		<orgname>Latin Translation Team</orgname> 
	  		<address> <email>translator@gnome.org</email> </address> 
		</affiliation>
		<contrib>Latin translation</contrib>
      </othercredit>
-->
    </authorgroup>


<!-- According to GNU FDL, revision history is mandatory if you are -->
<!-- modifying/reusing someone else's document.  If not, you can omit it. -->
<!-- Remember to remove the &manrevision; entity from the revision entries other
-->
<!-- than the current revision. -->
<!-- The revision numbering system for GNOME manuals is as follows: -->
<!-- * the revision number consists of two components -->
<!-- * the first component of the revision number reflects the release version of the GNOME desktop. -->
<!-- * the second component of the revision number is a decimal unit that is incremented with each revision of the manual. -->
<!-- For example, if the GNOME desktop release is V2.x, the first version of the manual that -->
<!-- is written in that desktop timeframe is V2.0, the second version of the manual is V2.1, etc. -->
<!-- When the desktop release version changes to V3.x, the revision number of the manual changes -->
<!-- to V3.0, and so on. -->  
    <revhistory>
      <revision> 
		<revnumber>gLabels Manual V2.2.6</revnumber> 
		<date>October 2009</date> 
		<revdescription> 
	  		<para role="author">Mario Blättermann
	    	<email>mariobl@gnome.org</email>
	  		</para>
	  		<para role="publisher">Jim Evins</para>
		</revdescription> 
      </revision> 
      <revision> 
		<revnumber>gLabels Manual V2.2</revnumber> 
		<date>December 2007</date> 
		<revdescription> 
	  		<para role="author">Jim Evins
	    	<email>evins@snaught.com</email>
	  		</para>
	  		<para role="publisher">Jim Evins</para>
		</revdescription> 
      </revision> 
    </revhistory> 

    <releaseinfo>This manual describes version &appversion; of &app;.
    </releaseinfo> 
    <legalnotice> 
      <title>Feedback</title> 
      <para>To report a bug or make a suggestion regarding the &app; application or
      this manual, follow the directions in the <ulink url="http://glabels.sourceforge.net/contact/"
	  type="http">&app; Contact Page</ulink>. 
      </para>
<!-- Translators may also add here feedback address for translations -->
    </legalnotice> 
  </articleinfo> 

  <indexterm zone="index"> 
    <primary>gLabels</primary> 
  </indexterm> 
  <indexterm zone="index"> 
    <primary>glabels</primary> 
  </indexterm>




<!-- ============= Document Body ============================= -->
<!-- ============= Introduction ============================== -->
<!-- Use the Introduction section to give a brief overview of what
     the application is and what it does. -->
  <sect1 id="glabels-introduction"> 
    <title>Introduction</title> 

    <para>The &app; application is a lightweight program for creating labels
      and business cards for the <systemitem>GNOME desktop</systemitem>
      environment.  It is designed to work with various laser/ink-jet
      peel-off label and business card sheets that you'll find at most
      office supply stores.</para>

  </sect1>




<!-- =========== Getting Started ============================== -->
<!-- Use the Getting Started section to describe the steps required
     to start the application and to describe the user interface components
     of the application. If there is other information that it is important
     for readers to know before they start using the application, you should
     also include this information here. 
     If the information about how to get started is very short, you can 
     include it in the Introduction and omit this section. -->

  <sect1 id="glabels-getting-started"> 
    <title>Getting Started</title> 

    <sect2 id="glabels-start">
    <title>To Start &app;</title>
    <para>You can start &app; in the following ways:
    </para> 
    <variablelist>
    	<varlistentry>
    		<term><guimenu>Applications</guimenu> menu</term>
    		<listitem>
    		<para>Choose 
    		<menuchoice>
    		<guisubmenu>Office</guisubmenu>
    		<guimenuitem>gLabels</guimenuitem>
    		</menuchoice>. </para>
    		</listitem>
    	</varlistentry>
    	<varlistentry>
    		<term>Command line</term>
    		<listitem>
    		<para>Type <command>glabels</command>,
                then press <keycap>Return</keycap>:</para>
    		</listitem>
    	</varlistentry>
    </variablelist>
    </sect2>

    <sect2 id="glabels-when-start">
    <title>When You Start &app;</title>
    <para>When you start &app;, the following window is displayed.</para>

    <!-- ==== Figure ==== -->
      <figure id="mainwindow-fig"> 
	<title>&app; Start Up Window</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
		fileref="figures/main-window-empty.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
    <!-- ==== End of Figure ==== -->

    <!-- Include any descriptions of the GUI immediately after the screenshot of the main UI, -->
    <!-- for example, the items on the menubar and on the toolbar. This section is optional. -->

    <para>The &app; window contains the following elements:
    </para>
      <variablelist>
	<varlistentry>
	<term>Menubar. </term>
	<listitem>
	    <para>The menus on the menubar contain all of the commands you
              need to create and edit labels and business cards in 
	      &app;.</para>
	</listitem>
	</varlistentry>
	<varlistentry>
	<term>Main toolbar. </term>
	<listitem>
	    <para>The main toolbar contains a subset of common File and Edit
              commands that you can access from the menubar.</para>
	</listitem>
	</varlistentry>
	<varlistentry>
	<term>Drawing toolbar.</term>
	<listitem>
	    <para>The drawing toolbar contains a subset of commands for
              editing the current &app; document.</para>
	</listitem>
	</varlistentry>
	<varlistentry>
	<term>Display area.</term>
	<listitem>
	    <para>The display area is the main drawing interface to
              &app;.</para>
	</listitem>
	</varlistentry>
	<varlistentry>
	<term>Object sidebar.</term>
	<listitem>
	    <para>The object sidebar provides an interface for viewing and
              editing all properties of an individual object. </para>
	</listitem>
	</varlistentry>
	<varlistentry>
	<term>Properties toolbar. </term>
	<listitem>
	    <para>The properties toolbar contains a set of tools to
              manipulate the properties of selected objects and set default
              properties for new objects.</para>
	</listitem>
	</varlistentry>
	<varlistentry>
	<term>Statusbar. </term>
	<listitem>
	    <para>The statusbar displays information about current
              &app; activity and contextual
              information about the menu items. </para>
	</listitem>
	</varlistentry>
	</variablelist>
    </sect2>
  </sect1>




<!-- ================ Usage ================================ -->
<!-- Use this section to describe how to use the application to perform the tasks for 
  which the application is designed. -->
  <sect1 id="glabels-usage"> 
    <title>Usage</title> 

<!-- ============= To create a new file ============================= -->
    <sect2 id="glabels-open-new"> 
      <title>To Create a New Label or Card</title>

      <para>To create a new label or business card, choose 
        <menuchoice> <guimenu>File</guimenu> <guimenuitem>New</guimenuitem>
	</menuchoice>
	to display the <guilabel>New Label or Card</guilabel> dialog. Select
        the media type and orientation for the new document,
	then click <guibutton>OK</guibutton>. A new document is
	displayed in the display area of the &app;
        window. </para>

      <para>If your particular media type is missing from this dialog,
        see <xref linkend="glabels-create-template"/></para>

    </sect2>

<!-- ============= To Open a File ============================= -->
    <sect2 id="glabels-open-file"> 
      <title>To Open a File</title>

      <para>To open a file, choose 
        <menuchoice> <guimenu>File</guimenu> <guimenuitem>Open</guimenuitem>
	</menuchoice> to display the <guilabel>Open File</guilabel> dialog.
        Select the file that you want to open, then click
        <guibutton>OK</guibutton>. The file is displayed in the display area
        of the &app; window. </para>

      <para>You can also open multiple files in
        &app;. The application creates a separate
        application window for each open file.</para>

      <para>The application records the paths and filenames of the
        most recent files that you have edited and displays the files as menu
        items on the <menuchoice>
        <guimenu>File</guimenu><guisubmenu>Recent Files</guisubmenu>
        </menuchoice> menu.</para>

    </sect2>

<!-- ============= To Open Multiple Files from the Command Line ========= -->
    <sect2 id="glabels-run-from-cmd-line"> 
      <title>To Open Multiple Files from a Command Line</title>

      <para>You can run &app; from a command line
	and open a single file or multiple files. To open multiple files from
        a command line, type the following command, then press
        <keycap>Return</keycap>:</para>

      <para><command>glabels
      <replaceable>file1.glabels file2.glabels file3.glabels</replaceable>
      </command></para>

      <para>When the application starts, the files that you specify are
	displayed in separate &app; windows.</para>

    </sect2>

<!-- ============= To Save a File ========= -->
    <sect2 id="glabels-save-file"> 
      <title>To Save a File</title>

      <para>You can save files in the following ways:</para>

      <itemizedlist> 
	<listitem>

	  <para>To save changes to an existing file, choose 
            <menuchoice> <guimenu>File</guimenu>
            <guimenuitem>Save</guimenuitem> </menuchoice>. </para>

	</listitem>
	<listitem>

	  <para>To save a new file or to save an existing file under a new
            filename, choose <menuchoice> <guimenu>File</guimenu>
            <guimenuitem>Save As</guimenuitem> </menuchoice>. Enter a name
            for the file in the <guilabel>Save As</guilabel> dialog box,
            then click <guibutton>OK</guibutton>.</para>

	</listitem>
      </itemizedlist>

    </sect2>

<!-- ============= To Change Label Properties ========= -->
    <sect2 id="glabels-label-properties"> 
      <title>To Change Label Properties</title>

      <para>To change the media type and/or orientation of a label, choose
        <menuchoice> <guimenu>File</guimenu>
        <guimenuitem>Properties</guimenuitem> </menuchoice> to display the
        <guilabel>Label properties</guilabel> dialog.  Select the
        new media type and orientation for the document, then click
        <guibutton>OK</guibutton>.</para>

    </sect2>

<!-- ============= To create a custom template ======================= -->
    <sect2 id="glabels-create-template"> 
      <title>To Create a Custom Template</title>

      <para>To create a new custom template, choose 
        <menuchoice> <guimenu>File</guimenu>
	<guimenuitem>Template Designer ...</guimenuitem> </menuchoice>
	to display the <guilabel>Template Designer</guilabel> dialog.
        This dialog will assist you in creating a custom template for
        most types of label or card stationery that you may encounter.</para>

      <para>If you prefer, you can create your templates manually.
        For this option see <xref linkend="glabels-manual-create-template"/>
      </para>

    </sect2>

<!-- ============= To Close a File ========= -->
    <sect2 id="glabels-close-file"> 
      <title>To Close a File</title>

      <para>To close the current document, choose
        <menuchoice> <guimenu>File</guimenu>
        <guimenuitem>Close</guimenuitem> </menuchoice> to close the application
        window.  If the current document is modified, a confirmation dialog
        will be presented, allowing you to save the document or cancel
        the command.  If the window being closed is the only open window,
        &app; will exit.</para>

    </sect2>

<!-- ============= To Quit ========= -->
    <sect2 id="glabels-quit"> 
      <title>To Quit &app;</title>

      <para>To quit &app;, choose
        <menuchoice> <guimenu>File</guimenu>
        <guimenuitem>Quit</guimenuitem> </menuchoice>. This is equivalent
        to closing all open windows.  See
        <xref linkend="glabels-close-file"/>.</para>

    </sect2>

<!-- ============= To Print Labels and Cards ========= -->
    <sect2 id="glabels-print-file"> 
      <title>To Print Labels or Cards</title>

      <para>To print labels or cards, choose
        <menuchoice> <guimenu>File</guimenu> <guimenuitem>Print</guimenuitem>
	</menuchoice> to display the <guilabel>Print</guilabel> dialog.
        Once print options have been selected, click <guilabel>Print</guilabel>
        to print the labels or cards.  To simply preview the results,
        click <guilabel>Print Preview</guilabel> instead.</para>

      <para>The <guilabel>Print</guilabel> dialog allows you to specify the
        following print options:</para>
		
      <sect3 id="print-dialog-job">
	<title>The Labels Tab of the Print Dialog</title>

	<variablelist>

	  <varlistentry>
            <term><guilabel>Print control (Simple)</guilabel></term>
	    <listitem> 

	      <para>For simple labels or cards (no document merge), the <guilabel>labels</guilabel>
                tabbed section contains the following copy controls.</para>

	      <!-- ==== Figure ==== -->
	      <figure id="print-copies-fig"> 
		<title>Print Copy Controls</title> 
		<screenshot> 
		  <mediaobject> 
		    <imageobject><imagedata
		       fileref="figures/print-copies.png" format="PNG"/> 
		    </imageobject>
		  </mediaobject> 
		</screenshot> 
	      </figure>
	      <!-- ==== End of Figure ==== -->

	      <para>The number of copies of the label can be selected by
                choosing the number of full sheets to print, or a specific
                subset of labels on a single sheet.</para>

	      <para>The mini-preview can also be used to graphically select
                the subset of labels by clicking the first label on the
                mini-preview and dragging to the last label.</para>

	    </listitem>
	  </varlistentry>

	  <varlistentry>
            <term><guilabel>Print control (Merge)</guilabel></term>
	    <listitem> 

	      <para>For labels or cards using the document merge (also known
                as "mail merge") capability, the <guilabel>labels</guilabel> tabbed section contains
                the following merge controls instead of copy controls.</para>

	      <!-- ==== Figure ==== -->
	      <figure id="print-merge-fig"> 
		<title>Print Document Merge Controls</title> 
		<screenshot> 
		  <mediaobject> 
		    <imageobject><imagedata
		       fileref="figures/print-merge.png" format="PNG"/> 
		    </imageobject>
		  </mediaobject> 
		</screenshot> 
	      </figure>
	      <!-- ==== End of Figure ==== -->

	      <para>The total number of labels or cards printed is the
                product of the number of records in the merge source and
                the number of copies selected.  If multiple copies are
                selected, these can be either collated (copies of the
                same record grouped together) or un-collated (one copy
                each record is printed before next copy).</para>

	      <para>Printing can begin on any label on the first sheet.
                This can be selected with the <guilabel>Start on
                label</guilabel> spinbutton.</para>

	      <para>The mini-preview can also be used to graphically select
                this first label, by clicking on the desired label in the
                mini-preview.</para>

	    </listitem>
	  </varlistentry>

	  <varlistentry> <term><guilabel>Options</guilabel> </term> 
	    <listitem> 
	      <para>The following options can also be selected.</para>
	      <itemizedlist>
		<listitem>
		  <para><guilabel>print outlines</guilabel></para>
		  <para>Print outlines of labels.  This option is useful for
                    dry-runs, to test printer alignment.</para>
		</listitem>
		<listitem>
		  <para><guilabel>print in reverse</guilabel></para>
		  <para>Prints the labels as mirror images.  This option is
                    useful for printing on clear labels that will be viewed
                    from the reverse side (e.g. in a car window).</para>
		</listitem>
		<listitem>
		  <para><guilabel>print crop marks</guilabel></para>
		  <para>Prints crop marks along the edge of the sheet.
                    This option is useful for printing on blank stock, to
                    be cut after printing.  This option does not work well
                    with all templates.</para>
		</listitem>
	      </itemizedlist>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </sect3>
		
    </sect2>

<!-- ============= To Create New Objects ========= -->
    <sect2 id="glabels-new-objects"> 
      <title>To Create New Objects</title>

      <para>Objects are created by choosing the appropriate selection under
        the <menuchoice> <guimenu>Objects</guimenu>
        <guimenuitem>Create Object</guimenuitem> </menuchoice> submenu or
        the <guilabel>Drawing Toolbar</guilabel>.  This will place the
        display area into object creation mode as indicated by its cursor.
        To return to the default object selection mode without creating
        an object, choose <menuchoice> <guimenu>Objects</guimenu>
        <guimenuitem>Select Mode</guimenuitem> </menuchoice>.  This will
        return the display area's cursor to the default selection arrow.</para>

      <para>The following describes the object creation mode for each object
        type:</para>

      <variablelist>

	<varlistentry>
	  <term>Text</term>
	  <listitem>
	    <para>Click the desired location of the upper left corner of the
              text object.  New text objects are initialized with the
              string "Text."  To change this text, or other properties, see
              <xref linkend="glabels-object-properties"/>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Box</term>
	  <listitem>
	    <para>Click the desired location of the upper left corner of the
              box object and drag to the desired location of the lower right
              corner.  If you simply click in a single location, a square
              box will be created. To change properties of the box object, see
              <xref linkend="glabels-object-properties"/>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Line</term>
	  <listitem>
	    <para>Click the desired location of one end of the
              line object and drag to the desired location of the other end.
              If you simply click in a single location, a diagonal line
              will be created. To change properties of the line object, see
              <xref linkend="glabels-object-properties"/>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Ellipse</term>
	  <listitem>
	    <para>Click the desired location of the upper left corner of the
              ellipse object and drag to the desired location of the lower
              right corner.  If you simply click in a single location, a circle
              will be created. To change properties of the ellipse object, see
              <xref linkend="glabels-object-properties"/>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Image</term>
	  <listitem>
	    <para>Click the desired location of the upper left corner of the
              image object and drag to the desired location of the lower
              right corner.  If you simply click in a single location, a square
              will be created.  New image objects are initialized with a
              simple checkerboard image.  To change this image, or other
              properties of the image object, see
              <xref linkend="glabels-object-properties"/>.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Barcode</term>
	  <listitem>
	    <para>Click the desired location of the upper left corner of the
              barcode object.  New barcode objects are initialized to a
              POSTNET barcode with representative data.  To change data
              and properties of the barcode object, see
              <xref linkend="glabels-object-properties"/>.</para>
	  </listitem>
	</varlistentry>

      </variablelist>


    </sect2>

<!-- ============= To Select Objects ========= -->
    <sect2 id="glabels-select-objects"> 
      <title>To Select Objects</title>

      <para>A prerequisite for performing operations on objects is the
        selection of individual objects or groups of objects.  The
        display area must be in the object selection mode to create new
        selections, as indicated by an arrow cursor.  The object
        selection mode is selected by the
        <menuchoice> <guimenu>Objects</guimenu>
        <guimenuitem>Select Mode</guimenuitem> </menuchoice> menu item,
        or the corresponding command on the <guilabel>Drawing
        Toolbar</guilabel>.</para>

      <variablelist>

	<varlistentry>
	  <term>Selecting a single object</term>
	  <listitem>
	    <para>A single object can be selected simply by clicking
             on the desired object in the display area.
             Once selected the object will be highlighted with a set of
             resizing handles.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Aggregate object selections</term>
	  <listitem>
	    <para>Multiple objects can be selected by first selecting the first
              object as above and then by holding the <keycap>Ctrl</keycap>
              key while selecting additional objects.
              Individual objects can be added to an existing selection
              at any time by holding the <keycap>Ctrl</keycap> key while
              selecting the desired objects.  All objects can also be
              selected by using the <menuchoice> <guimenu>Edit</guimenu>
              <guimenuitem>Select All</guimenuitem> </menuchoice>
              menu item.  All objects in an aggregate object selection will be
              highlighted.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Area selections</term>
	  <listitem>
	    <para>Multiple objects can also be selected by clicking an empty
              area and dragging to form a rectangular area.  When released,
              all objects contained in the area will form an aggregate
              selection.  An area selection can be used to add to an existing
              selection by holding the <keycap>Ctrl</keycap> key while
              performing the selection.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>Unselecting objects</term>
	  <listitem>
	    <para>Individual objects can be removed from an existing
              selection by holding the <keycap>Ctrl</keycap> key while
              clicking on a previously selected object.  An entire selection
              can be dismissed by using the <menuchoice>
	      <guimenu>Edit</guimenu> <guimenuitem>Un-select All</guimenuitem>
              </menuchoice> menu item
              or by simply clicking any empty space in the display area.
              Once an object is unselected its highlight is removed.</para>
	  </listitem>
	</varlistentry>

      </variablelist>

    </sect2>

<!-- ============= Clipboard Commands ========= -->
    <sect2 id="glabels-clipboard"> 
      <title>Clipboard Commands</title>

      <para>Object selections can be manipulated using the standard clipboard
        operations <guimenuitem>Cut</guimenuitem>,
        <guimenuitem>Copy</guimenuitem>, <guimenuitem>Paste</guimenuitem>,
        and <guimenuitem>Delete</guimenuitem>.</para>

      <variablelist>

	<varlistentry>
	  <term>
            <menuchoice>
	      <shortcut>
		<keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo>
	      </shortcut>
	      <guimenuitem>Cut</guimenuitem>
	    </menuchoice>
          </term>
	  <listitem>
	    <para>Moves selected objects to the clipboard.  The objects are
              then available for pasting back into the current document or
              another document.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
            <menuchoice>
	      <shortcut>
		<keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
	      </shortcut>
	      <guimenuitem>Copy</guimenuitem>
	    </menuchoice>
          </term>
	  <listitem>
	    <para>Copies selected objects to the clipboard without deleting
              them.  The objects are then available for pasting back into
              the current document or another document.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
            <menuchoice>
	      <shortcut>
		<keycombo><keycap>Ctrl</keycap><keycap>V</keycap></keycombo>
	      </shortcut>
	      <guimenuitem>Paste</guimenuitem>
	    </menuchoice>
          </term>
	  <listitem>
	    <para>Pastes objects from the clipboard into the current document.
              &app; can only paste objects from
              another &app; document.</para>
	  </listitem>
	</varlistentry>

	<varlistentry>
	  <term>
            <menuchoice>
	      <shortcut>
		<keycap>Delete</keycap>
	      </shortcut>
	      <guimenuitem>Delete</guimenuitem>
	    </menuchoice>
          </term>
	  <listitem>
	    <para>Deletes selected objects without placing them on the
              clipboard.</para>
	  </listitem>
	</varlistentry>

      </variablelist>

    </sect2>

<!-- ============= To Edit object Properties ========= -->
    <sect2 id="glabels-object-properties"> 
      <title>To Edit Object Properties</title>

      <para>Most object properties can be modified through the object
        editor sidebar, illustrated below.  To use the object editor,
        a single object must first be selected.  See
        <xref linkend="glabels-select-objects" />.</para>

      <!-- ==== Figure ==== -->
      <figure id="object-editor-sidebar-fig"> 
	<title>Object Editor Sidebar</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
	      fileref="figures/object-editor-sidebar.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
      <!-- ==== End of Figure ==== -->

      <para>The object editor will contain a subset of the following
        tabbed sections, depending on object type:</para>

      <sect3 id="object-editor-text">
	<title>Text Tabbed Section (Text objects)</title>

	<para>This section contains a small editor for changing the content
          of a text object.  It also contains a dropdown menu of available
          document merge keys, that can be inserted into text.</para>

      </sect3>

      <sect3 id="object-editor-image">
	<title>Image Tabbed Section (Image objecs)</title>

	<para>This section contains a file entry with preview to select
          image files.  The browse button can be used to easily locate
          image files.  Alternatively, a document merge key can be used
          instead to provide a filename at print time.</para>

      </sect3>

      <sect3 id="object-editor-data">
	<title>Data Tabbed Section (Barcode objecs)</title>

	<para>This section contains a text entry to enter literal barcode
          data. Alternatively, a document merge key can be used to
          provide this data at print time.</para>

      </sect3>

      <sect3 id="object-editor-style">
	<title>Style Tabbed Section (Text objects)</title>

	<para>This section contains controls to select text properties,
          including font family, font size, font weight, color, and
          text justification.</para>

      </sect3>

      <sect3 id="object-editor-barcode">
	<title>Style Tabbed Section (Barcode objecs)</title>

	<para>This section contains controls to select barcode properties,
          including barcode style, color, whether to print text, and whether
          to include a checksum digit.</para>

      </sect3>

      <sect3 id="object-editor-line">
	<title>Line Tabbed Section</title>

	<para>This section contains controls to select properties of lines
          and outlines.  These properties include line width and color.</para>

      </sect3>

      <sect3 id="object-editor-fill">
	<title>Fill Tabbed Section</title>

	<para>This section contains controls to select fill properties of box
          and ellipse objects.  Currently the only fill property is fill
          color.</para>

      </sect3>

      <sect3 id="object-editor-size">
	<title>Size Tabbed Section (All except line objects)</title>

	<para>This section contains controls to select the width and height
          of an object.  A checkbox is provided, so that the current aspect
          ratio can be locked while manipulating the width and height controls.
          Image objects also provide a button to reset the size to the
          image's natural size (Assumes 72DPI).</para>

      </sect3>

      <sect3 id="object-editor-size-line">
	<title>Size Tabbed Section (Line objects)</title>

	<para>This section contains controls to select the length and angle
          of a line object.</para>

      </sect3>

      <sect3 id="object-editor-position">
	<title>Position Tabbed Section</title>

	<para>This section contains controls to change the position of an
          object.</para>

      </sect3>


      <sect3 id="object-editor-shadow">
	<title>Shadow Tabbed Section (All except image and barcode objects)</title>

	<para>This section contains controls to add a shadow to an object.</para>

      </sect3>


    </sect2>

<!-- ============= Other Manipulations of Objects ========= -->
    <sect2 id="glabels-object-manipulation"> 
      <title>Other Manipulations of Objects</title>

      <para>Objects can also be manipulated in the following ways.</para>

      <sect3 id="other-moving-resizing">
	<title>Moving and Resizing Objects</title>

	<para>Objects can be moved by simply clicking on a selected
          object and dragging the object to its new location.  If the object
          is part of an aggregate selection, all objects in the selection
          will move with the object being dragged, maintaining their relative
          positions to one another.  If no object is selected, clicking on
          an object will create a new selection containing that object.
          See <xref linkend="glabels-select-objects" />.</para>

	<para>A selected object can be resized by clicking one of its resize
          handle and dragging it to obtain the new size.</para>

      </sect3>

      <sect3 id="other-stacking-order">
	<title>Changing Stacking Order</title>

	<para>Stacking order refers to relative position in the z-axis of
          objects.  That is when objects overlap, which object will appear
          on top of the other.  By default, newer objects will appear above
          older objects.  To change this order, select one or more objects
          and choose <menuchoice> <guimenu>Objects</guimenu>
          <guimenuitem>Order</guimenuitem>
          <guimenuitem>Bring to Front</guimenuitem> </menuchoice>
          to raise the selection to the top of the stacking
          order, or choose <menuchoice> <guimenu>Objects</guimenu>
          <guimenuitem>Order</guimenuitem>
          <guimenuitem>Send to Back</guimenuitem> </menuchoice>
          to lower the selection to the bottom of the
          stacking order.  These menuitems are also available by right-clicking
          the display area when there is a non-empty selection.</para>

      </sect3>

      <sect3 id="other-rotating-flipping">
	<title>Rotating and Flipping Objects</title>

	<para>Objects can be rotated 90 degrees in either direction, or flipped
          horizontally or vertically, by choosing the appropriate menuitem
          in the  <menuchoice> <guimenu>Objects</guimenu>
          <guimenuitem>Rotate/Flip</guimenuitem> </menuchoice> sub-menu.  These
          menuitems are also available by right-clicking
          the display area when there is a non-empty selection.</para>

      </sect3>

      <sect3 id="other-alignment">
	<title>Aligning Objects</title>

	<para>Objects can be aligned horizontally or vertically, relative to
          one another, or relative to the center line of the label, by
          choosing the appropriate menuitem from the  <menuchoice>
          <guimenu>Objects</guimenu>
          <guimenuitem>Align Horizontal</guimenuitem>
          </menuchoice> or  <menuchoice> <guimenu>Objects</guimenu>
          <guimenuitem>Align Horizontal</guimenuitem> </menuchoice> sub-menus.
          These menuitems are also available by right-clicking
          the display area when there is a non-empty selection.</para>

      </sect3>

      <sect3 id="other-property-bar">
	<title>Using the Property Bar</title>

	<para>The property bar can be used to change some common properties
          of objects en-masse.  These properties include font family, font
          size, font weight, text alignment, text color, fill color, line
          or outline color, and line width.  The property bar also controls
          the defaults for these properties for any newly created objects.
          </para>

      </sect3>



    </sect2>

<!-- ============= Document Merge Features ========= -->
    <sect2 id="glabels-merge"> 
      <title>Performing a Document Merge</title>

      <para>Document Merge (sometimes called "Mail Merge") is a powerful
        feature that allows a unique label or card to be printed for each
        record in an external data source.</para>

      <para>The first step to performing a document merge is to prepare
        a source document that contains your merge data.  This data could
        be mailing addresses or any other data that you wish to create
        unique labels or cards for.  Currently back-ends only exist for
        text files and the evolution data server -- others are planned.  The currently
        supported text-file format is very simple:  each line is a record;
        fields are delimited by commas (CSV), tabs, or colons; and newlines
        can be embedded into fields by using the "\n" entity.  This file
        could be created using any text editor or could be created by
        another program or script.  A common way of creating CSV files is
	to export them from a spreadsheet program.</para>

      <para>A label must then be configured to "point at" this data file.
        To configure the merge properties of a document, choose
        <menuchoice> <guimenu>Objects</guimenu>
        <guimenuitem>Merge Properties</guimenuitem> </menuchoice> menu item
        to display the <guilabel>merge properties</guilabel> dialog.  This
        dialog is used to select the exact data file format and file
        name (location) of the merge data.</para>

      <para>Finally, once the label has been configured for a data file,
        field keys can be inserted into text objects and used as source
        or data for barcode objects and image filenames for image objects.
        See <xref linkend="glabels-object-properties" /> for more information
        on using merge data for these object types.</para>

      <para>Now that your label is configured, &app; will print a unique
        label for each record in your source document -- substituting fields
        from each record for field keys in the all text, barcode, and
        image objects.</para>

      <para>See <xref linkend="glabels-merge-tutorial" /> for a detailed
        tutorial on the document merge feature.</para>


    </sect2>


  </sect1>




  <!-- ============= Customization ============================= -->
  <!-- Use this section to describe how to customize the application. -->
  <sect1 id="glabels-prefs"> 
    <title>Settings</title> 
    <para>To configure &app;, choose 
      <menuchoice> 
	<guimenu>Settings</guimenu> 
	<guimenuitem>Preferences</guimenuitem> 
      </menuchoice>. The 
      <guilabel>Preferences</guilabel> dialog contains the following tabbed
      sections:</para> 
    <itemizedlist> 
      <listitem> 
	<para> 
	  <xref linkend="glabels-prefs-locale"/></para> 
      </listitem> 
      <listitem> 
	<para> 
	  <xref linkend="glabels-prefs-object-defaults"/></para> 
      </listitem> 
    </itemizedlist>
<!-- =============== Customization Subsection ================ -->
<!-- Use a new section to describe different tabbed sections on the Settings or Preferences
	     dialog. -->
    <sect2 id="glabels-prefs-locale"> 
      <title>Locale</title> 
      <variablelist> 
	<varlistentry> 
	  <term> 
	    <guilabel>Units</guilabel> </term> 
	  <listitem> 
	    <para>Use this radio button group to specify your preferred units.
              Select one of the following options:</para>
	    <itemizedlist> 
	      <listitem> 
		<para> 
		  <guilabel>Points</guilabel> </para> 
		<para>Use points (1 point = 1/72 in = 0.352778 mm).</para> 
	      </listitem> 
	      <listitem> 
		<para> 
		  <guilabel>Inches</guilabel> </para> 
		<para>Use inches.</para>
	      </listitem> 
	      <listitem> 
		<para> 
		  <guilabel>Millimeters</guilabel> </para> 
		<para>Use millimeters.</para>
	      </listitem> 
	    </itemizedlist> 
	    <para>Default: 
	      <guilabel>Inches</guilabel>.</para> 
	  </listitem> 
	</varlistentry> 
	<varlistentry> 
	  <term> 
	    <guilabel>Default page size</guilabel> </term> 
	  <listitem> 
	    <para>Use this radio button group to specify your preferred page size.
              This will make it quicker for you to locate media types when creating a new
              label or card.</para>
	    <itemizedlist> 
	      <listitem> 
		<para> 
		  <guilabel>US Letter</guilabel> </para> 
		<para>Most of your media will be of the US Letter page size (8.5 x 11 inches).</para> 
	      </listitem> 
	      <listitem> 
		<para> 
		  <guilabel>ISO A4</guilabel> </para> 
		<para>Most of your media will be of the ISO A4 page size (210 x 297 mm).</para>
	      </listitem> 
	    </itemizedlist> 
	    <para>Default: 
	      <guilabel>US Letter</guilabel>.</para> 
	  </listitem> 
	</varlistentry> 
      </variablelist> 
    </sect2>
    <!-- ============= Customization Subsection ===================== -->
    <!-- Another tabbed section on the Preferences dialog. -->
    <sect2 id="glabels-prefs-object-defaults"> 
      <title>Object defaults</title> 
      <variablelist> 
	<varlistentry> 
	  <term> 
	    <guilabel>Text</guilabel> </term> 
	  <listitem> 
	    <para>Use these controls to set the default properties of new text objects.
              These properties are</para>
	    <itemizedlist> 
	      <listitem> 
		<para> 
		  <guilabel>Font</guilabel> </para> 
		<para>These controls are used to select font family and font size, and
                  whether the font should bold or in italics.</para> 
	      </listitem> 
	      <listitem> 
		<para> 
		  <guilabel>Color</guilabel> </para> 
		<para>This control selects the default text color.</para>
	      </listitem> 
	      <listitem> 
		<para> 
		  <guilabel>Alignment</guilabel> </para> 
		<para>These controls are used to select the default text alignment (left, center or right).</para>
	      </listitem> 
	    </itemizedlist> 
	  </listitem> 
	</varlistentry> 
	<varlistentry> 
	  <term> 
	    <guilabel>Line</guilabel> </term> 
	  <listitem> 
	    <para>Use these controls to set the default properties of lines and outlines of
              new objects.  These properties are</para>
	    <itemizedlist> 
	      <listitem> 
		<para> 
		  <guilabel>Width</guilabel> </para> 
		<para>This control selects the default line width.</para>
	      </listitem> 
	      <listitem> 
		<para> 
		  <guilabel>Color</guilabel> </para> 
		<para>This control selects the default line color.</para>
	      </listitem> 
	    </itemizedlist> 
	  </listitem> 
	</varlistentry> 
	<varlistentry> 
	  <term> 
	    <guilabel>Fill</guilabel> </term> 
	  <listitem> 
	    <para>Use these controls to set the default fill properties of
              new objects.  These properties are</para>
	    <itemizedlist> 
	      <listitem> 
		<para> 
		  <guilabel>Color</guilabel> </para> 
		<para>This control selects the default fill color.</para>
	      </listitem> 
	    </itemizedlist> 
	  </listitem> 
	</varlistentry> 
      </variablelist> 
    </sect2> 
  </sect1>




<!-- ============= Document Merge Tutorial ================================== -->
  <sect1 id="glabels-merge-tutorial"> 
    <title>Document Merge Tutorial</title>

    <para>Document Merge (sometimes called "Mail Merge") is a powerful
      feature that allows a unique label or card to be printed for each
      record in an external data source.  It is however, the most mis-understood
      feature of &app;.  The following examples
      will step through a couple of common tasks using the document merge
      feature.</para>

    <sect2 id="merge-ex1">
      <title>Example 1: Name Tags Using a CSV File</title>
  
      <para>In this example we are organizing an orientation party for the new
        crew members of our ship.  We have a list of freshman crew members that we
        created in <application>gnumeric</application> and exported as the following
        CSV file.  We could have created this file by using a text editor, but heck it
        is the 23rd century.</para>

      <programlisting>
Name,Department,SN
"Jim Kirk",Management,"SC937-0176 CEC"
"Mr. Spock",Sciences,S179-276SP
"Leonard McCoy",Medicine,unknown
"Montgomery Scott",Engineering,SE-197-54T
      </programlisting>

      <para>In &app; we have created a new &app;
        document using the Avery 5395 "Name Badge Labels" template.  Next we use the
        <menuchoice> <guimenu>Objects</guimenu>
        <guimenuitem>Merge Properties</guimenuitem> </menuchoice> menu item to display
        the <guilabel>merge properties</guilabel> dialog.  We use this dialog to
        select the source type (in our case CSV) and the merge source (filename) as
        shown.</para>

      <!-- ==== Figure ==== -->
      <figure id="merge-ex1-1-fig"> 
	<title>Merge properties dialog</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
	       fileref="figures/merge-ex1-1.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
      <!-- ==== End of Figure ==== -->

      <para>Before applying the merge source, we uncheck the first record since it is only
        column headers from our original <application>gnumeric</application> spreadsheet
        and would simply waste our first label.  We could also unselect any other records
        that we didn't want to print a label for.</para>

      <para>We can also view each record in more detail by clicking on the appropriate
        expander (the little triangles) as shown.  Once we are satisfied with the
        selections in this dialog we click <guibutton>OK</guibutton> to accept the
        changes.</para>

      <para>Now we start adding objects to our &app; document as shown.</para>

      <!-- ==== Figure ==== -->
      <figure id="merge-ex1-2-fig"> 
	<title>Adding objects</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
	       fileref="figures/merge-ex1-2.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
      <!-- ==== End of Figure ==== -->

      <para>In this example we have added three text objects and a barcode object.  The
        first text object contains only simple literal text ("Hello, my name is").  The
        second text object contains a single merge field ("${1}") corresponding to the
        first field of a record (first column of a line) which contains the new crew
        member's full name.  The third text field contains both literal text
        ("Department: ") followed by a single merge field ("${2}") corresponding to
        the second field or the crew member's department.  The barcode object is
        configured to use field (or key) "3" which contains our crew member's
        starfleet serial number.</para>

      <para>Now we can print our name tags by selecting the
        <menuchoice> <guimenu>File</guimenu>
        <guimenuitem>Print</guimenuitem> </menuchoice> menu item.  This will display
        print dialog as shown below.</para>

      <!-- ==== Figure ==== -->
      <figure id="merge-ex1-3-fig"> 
	<title>Printing name tags</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
	       fileref="figures/merge-ex1-3.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
      <!-- ==== End of Figure ==== -->

      <para>Just to make sure our labels are going to look okay, we select the
        <guilabel>Print outlines</guilabel> option and click
        <guibutton>Print Preview</guibutton>.  This will display a print preview dialog
        as shown below.</para>

      <!-- ==== Figure ==== -->
      <figure id="merge-ex1-4-fig"> 
	<title>Name tags preview</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
	       fileref="figures/merge-ex1-4.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
      <!-- ==== End of Figure ==== -->

      <para>Everything looks good, so we can now load up our printer with
        the appropriate label stock, print our name tags and start beaming our guests
        aboard.</para>

    </sect2>

    <sect2 id="merge-ex2">
      <title>Example 2: Address Labels Using a CSV File</title>
  
      <para>In this example we are going to throw a party and need to print mailing
        address labels for our invitations.  We have a list of our closest friends
        that we created in <application>gnumeric</application> and exported as the
        following CSV file.  It should be noted that not everyone has a middle initial or
        a two line address.</para>

      <programlisting>
LAST,FIRST,MI,ADDR1,ADDR2,CITY,STATE,ZIP
,,,,,,,
Critter,Ess,S,"123 Faux St.",,Alexandria,VA,22310
Doe,John,,"Apt 1X","451 Mystery St.",Trenton,NJ,08601
Summers,Joyce,,"1630 Revello Dr",,Sunnydale,CA,95037
McGarret,Steve,O,"404 Piikoi Street",,Honolulu,HI,96813
Kramer,Cosmo,,"Apt 5B","129 W. 81 St.","New York",NY,10024-7207
      </programlisting>

      <para>In &app; we have created a new &app;
        document using the Avery 5512 "Address Labels" template.  Next we use the
        <menuchoice> <guimenu>Objects</guimenu>
        <guimenuitem>Merge Properties</guimenuitem> </menuchoice> menu item to display
        the <guilabel>merge properties</guilabel> dialog.  We use this dialog to
        select the source type (in our case CSV) and the merge source (filename) as
        shown.</para>

      <!-- ==== Figure ==== -->
      <figure id="merge-ex2-1-fig"> 
	<title>Merge properties dialog</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
	       fileref="figures/merge-ex2-1.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
      <!-- ==== End of Figure ==== -->

      <para>Before applying the merge source, we uncheck the first record since it is only
        column headers from our original <application>gnumeric</application> spreadsheet
        and would simply waste our first label.  We also unselect the second record
        which is empty (an artifact of our original spreadsheet).  We could also unselect
        any other records that we didn't want to print a label for.</para>

      <para>We can also view each record in more detail by clicking on the appropriate
        expander (the little triangles) as shown.  Once we are satisfied with the
        selections in this dialog we click <guibutton>OK</guibutton> to accept the
        changes.</para>

      <para>Now we start adding objects to our &app; document as shown.</para>

      <!-- ==== Figure ==== -->
      <figure id="merge-ex2-2-fig"> 
	<title>Adding objects</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
	       fileref="figures/merge-ex2-2.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
      <!-- ==== End of Figure ==== -->

      <para>In this example we have a single text object.  This text object contains
        all of our merge fields organized on multiple lines as a mailing address.
        Notice that fields ${4} and ${5} (corresponding to ADDR1 and ADDR2) are each
        located with no other text on their own lines.  When
        &app; encounters a field as the only text on
        a line, it will not expand the line if the field is empty.</para>

      <para>Now we can print our address labels by selecting the
        <menuchoice> <guimenu>File</guimenu>
        <guimenuitem>Print</guimenuitem> </menuchoice> menu item.  This will display
        print dialog as shown below.</para>

      <!-- ==== Figure ==== -->
      <figure id="merge-ex2-3-fig"> 
	<title>Printing address labels</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
	       fileref="figures/merge-ex2-3.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
      <!-- ==== End of Figure ==== -->

      <para>Just to make sure our labels are going to look okay, we select the
        <guilabel>Print outlines</guilabel> option and click
        <guibutton>Print Preview</guibutton>.  This will display a print preview dialog
        as shown below.</para>

      <!-- ==== Figure ==== -->
      <figure id="merge-ex2-4-fig"> 
	<title>Address labels preview</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
	       fileref="figures/merge-ex2-4.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
      <!-- ==== End of Figure ==== -->

      <para>Everything looks good, so we can now load up our printer with
        the appropriate label stock, print our address labels and start mailing
        our party invitations.</para>

    </sect2>

<sect2 id="merge-ex3">
      <title>Example 3: Address Labels Using the <application>Evolution</application> Addressbook</title>
  
      <para>Our last party was a great success, and now we need to print mailing
        address labels for the invitations to a new one. To simplify this, we can use
	the <application>Evolution</application> addressbook, because the address
	data of	all our friends is stored there.</para>

      <note>
	<para>Depending on how your copy of &app; was packaged, this option could be unavailable.
	  Support for the <application>Evolution</application> addressbook will only be available
	  if the <application>evolution-data-server</application> and its development files
	  were present when &app; was built. Please keep this in mind if you build &app;
	  directly from source.</para>
	
	<para>If the &app; package from your distribution lacks this support,
	  you may wish to contact the package maintainer or file a bug against the package
	  to request it.</para>
      </note>

      <para>In <application>glabels</application> we have created a new &app;
        document using the Avery 5512 "Address Labels" template. Next we use the
        <menuchoice> <guimenu>Objects</guimenu>
        <guimenuitem>Merge Properties</guimenuitem></menuchoice> menu item to display
        the <guilabel>Merge properties</guilabel> dialog. We use this dialog to
        select the source type (in our case <guilabel>Data from default Evolution
	addressbook</guilabel>) as shown.</para>

      <!-- ==== Figure ==== -->
      <figure id="merge-ex3-1-fig"> 
	<title>Merge properties dialog</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
	       fileref="figures/merge-ex3-1.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
      <!-- ==== End of Figure ==== -->

      <para>Once we have chosen <guilabel>Data from default Evolution addressbook
	</guilabel> as our merge source, we will get a full list of its content. Initially,
	all entries are checked. Assuming we were planning a really big party, we could
	leave this selection untouched (but let's keep our budget in mind). We will now select or
	unselect certain entries by clicking on the appropriate checkboxes, or we could use
	the <guibutton>Select all</guibutton> and <guibutton>Unselect all
	</guibutton> buttons to activate or deactivate all entries in the address book.</para>
 
      <para>We can also view each entry in more detail by clicking on the appropriate
        expander (the little triangles) as shown. Once we are satisfied with the
        selections in this dialog, we will click the <guibutton>OK</guibutton> button to
	accept the changes.</para>

      <para>Now we start adding objects to our glabels document as shown.</para>

      <!-- ==== Figure ==== -->
      <figure id="merge-ex3-2-fig"> 
	<title>Adding objects</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
	       fileref="figures/merge-ex3-2.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
      <!-- ==== End of Figure ==== -->

      <para>In this example we have a single text object again. This text object contains
        all of our merge fields organized on multiple lines as a mailing address.</para>

      <para>Now we can print our address labels by selecting the
        <menuchoice> <guimenu>File</guimenu>
        <guimenuitem>Print</guimenuitem> </menuchoice> menu item. This will display
        the print dialog as shown below.</para>

      <!-- ==== Figure ==== -->
      <figure id="merge-ex3-3-fig"> 
	<title>Printing address labels</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
	       fileref="figures/merge-ex2-3.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
      <!-- ==== End of Figure ==== -->

      <para>Just to make sure our labels are going to look okay, we select the
        <guilabel>Print outlines</guilabel> option and click
        <guibutton>Print Preview</guibutton>. This will display a print preview dialog
        as shown below.</para>

      <!-- ==== Figure ==== -->
      <figure id="merge-ex3-4-fig"> 
	<title>Address labels preview</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
	       fileref="figures/merge-ex2-4.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
      <!-- ==== End of Figure ==== -->

      <para>Everything looks good, so we can now load up our printer with
        the appropriate label stock, print our address labels and start mailing
        our party invitations.</para>

    </sect2>

  </sect1>




<!-- ============= Creating templates ================================== -->
  <sect1 id="glabels-manual-create-template"> 
    <title>Manually Creating New Templates</title> 

    <para>Predefined templates are defined by XML files located in
      <filename>${prefix}/share/glabels/</filename>,
      where <filename>${prefix}</filename> is usually something like
      <filename>/usr/local</filename> or <filename>/usr</filename> depending
      on the configuration option <filename>prefix</filename>.  &app; will
      use all files of the form <filename>*-templates.xml</filename>
      or <filename>*.template</filename>, that it finds in
      <filename>${prefix}/share/glabels/</filename> and
      <filename>${HOME}/.glabels/</filename>.
      Additional templates can be added by creating additional
      <filename>*.template</filename> files in either of these directories.
      </para>

    <para>The format for these files is defined in the DTD:
      <ulink url="http://glabels.sourceforge.net/doc/glabels-2.0.dtd.txt"
       type="http">glabels-2.2.dtd</ulink>. (This DTD also describes other
       XML formats used by &app;.)</para>

    <sect2 id="template-assumptions">
      <title>Assumptions/caveats</title>
      <itemizedlist>
	<listitem>
	  <para>A sheet contains only one size of label or card (if a sheet
            contains more than one size of item, it can be split into
             multiple templates for multiple pass printing)</para>
	</listitem>
	<listitem>
	  <para>Distances can be expressed in units of <emphasis>pt</emphasis>,
            <emphasis>in</emphasis>, <emphasis>mm</emphasis>,
            <emphasis>cm</emphasis>, or <emphasis>pc</emphasis>.  For example:
            "<literal>1.0in</literal>" or "<literal>2.54cm</literal>".  If no
            units are specified, computer points (<emphasis>pt</emphasis>) will
            be assumed (1 <emphasis>pt</emphasis> =
            1/72 <emphasis>in</emphasis> = 0.352778 <emphasis>mm</emphasis>).
            </para>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2 id="template-file">
      <title>Template Files</title>

      <programlisting>
&lt;?xml version="1.0"?&gt;
&lt;Glabels-templates&gt;

   <replaceable>...templates...</replaceable>

&lt;/Glabels-templates&gt;
      </programlisting>
    </sect2>


    <sect2 id="template-example">
      <title>Example Template</title>
      <programlisting>
  &lt;Template brand="Avery" part="8160" size="US-Letter" description="Mailing Labels"&gt;
    &lt;Label-rectangle id="0" width="189pt" height="72pt" round="5pt"&gt;
      &lt;Markup-margin size="5pt"/&gt;
      &lt;Layout nx="3" ny="10" x0="11.25pt" y0="36pt" dx="200pt" dy="72pt"/&gt;
    &lt;/Label-rectangle&gt;
    &lt;Alias brand="Avery" part="5160"/&gt;
    &lt;Alias brand="Avery" part="6233"/&gt;
  &lt;/Template&gt;
      </programlisting>
    </sect2>

    <sect2 id="template-template-node">
      <title>Template Node</title>

      <para>A <emphasis>Template</emphasis> node describes a single stationary
        product.  It must contain one instance of any type of Label node
        (<emphasis>Label-rectangle</emphasis>,
        <emphasis>Label-round</emphasis>, or <emphasis>Label-cd</emphasis>).
        This node can be followed by zero or more 
        <emphasis>Alias</emphasis> nodes.</para>

      <informaltable frame="topbot">
	<tgroup cols="2">
	  <colspec colname="col1"/>
	  <colspec colname="col2"/>
	  <thead>
	    <row valign="top">
	      <entry colname="col1" colsep="0" valign="top">
                <para>Property</para>
              </entry>
	      <entry colname="col2" valign="top">
                <para>Description</para>
              </entry>
	    </row>
	  </thead>
	  <tbody>
	    <row valign="top">
	      <entry><para>brand</para></entry>
	      <entry>
                <para>Brand or manufacturer of stationary product.
                  E.g. "Avery"</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>part</para></entry>
	      <entry>
                <para>Part number or name of stationary product.
                  E.g. "8160"</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>size</para></entry>
	      <entry>
                <para>Size of sheet.  E.g., "US-Letter," "A4", ...</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>description</para></entry>
	      <entry>
                <para>Description of stationary product.  E.g,
                   "Mailing Labels."</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>_description</para></entry>
	      <entry>
                <para>Translatable description of stationary product.
                  E.g, "Mailing Labels." (Only useful for predefined
                  templates)</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>width</para></entry>
	      <entry>
                <para>Page width.  Only valid if size="Other"</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>height</para></entry>
	      <entry>
                <para>Page height.  Only valid if size="Other"</para>
               </entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

    </sect2>

    <sect2 id="template-label-rectangle-node">
      <title>Label-rectangle Node</title>

      <para>A <emphasis>Label-rectangle</emphasis> node describes the
        dimensions of a single label or business card that is rectangular
        in shape (may have rounded edges).</para>

      <informaltable frame="topbot">
	<tgroup cols="2">
	  <colspec colname="col1"/>
	  <colspec colname="col2"/>
	  <thead>
	    <row valign="top">
	      <entry colname="col1" colsep="0" valign="top">
                <para>Property</para>
              </entry>
	      <entry colname="col2" valign="top">
                <para>Description</para>
              </entry>
	    </row>
	  </thead>
	  <tbody>
	    <row valign="top">
	      <entry><para>id</para></entry>
	      <entry>
                <para>Reserved for future use.  Should always be 0.</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>width</para></entry>
	      <entry><para>Width of label/card</para></entry>
            </row>
	    <row valign="top">
	      <entry><para>height</para></entry>
	      <entry><para>Height of label/card</para></entry>
	    </row>
	    <row valign="top">
	      <entry><para>round</para></entry>
	      <entry>
                <para>Radius of corners.  For items with square edges
                  (business cards), the radius should be 0.</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>x_waste</para></entry>
	      <entry>
                <para>Amount of horizontal waste (over-print) to allow.  This is useful
                  for minimizing alignment problems when using non-white
                  backgrounds (e.g. images).</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>y_waste</para></entry>
	      <entry>
                <para>Amount of vertical waste (over-print) to allow.  This is useful
                  for minimizing alignment problems when using non-white
                  backgrounds (e.g. images).</para>
              </entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <!-- ==== Figure ==== -->
      <figure id="template-label-fig"> 
	<title>Label-rectangle Parameters</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
		fileref="figures/glabels-template-label.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
      <!-- ==== End of Figure ==== -->

    </sect2>

    <sect2 id="template-label-round-node">
      <title>Label-round Node</title>

      <para>A <emphasis>Label-round</emphasis> node describes the dimensions
        of a simple round label (not a CD).</para>

      <informaltable frame="topbot">
	<tgroup cols="2">
	  <colspec colname="col1"/>
	  <colspec colname="col2"/>
	  <thead>
	    <row valign="top">
	      <entry colname="col1" colsep="0" valign="top">
                <para>Property</para>
              </entry>
	      <entry colname="col2" valign="top">
                <para>Description</para>
              </entry>
	    </row>
	  </thead>
	  <tbody>
	    <row valign="top">
	      <entry><para>id</para></entry>
	      <entry>
                <para>Reserved for future use.  Should always be 0.</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>radius</para></entry>
	      <entry><para>Radius (1/2 diameter) of label</para></entry>
            </row>
	    <row valign="top">
	      <entry><para>waste</para></entry>
	      <entry>
                <para>Amount of waste (over-print) to allow.  This is useful
                  for minimizing alignment problems when using non-white
                  backgrounds (e.g. images).</para>
              </entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

    </sect2>

    <sect2 id="template-label-cd-node">
      <title>Label-cd Node</title>

      <para>A <emphasis>Label-cd</emphasis> node describes the dimensions
        of a CD, DVD, or business card CD.</para>

      <informaltable frame="topbot">
	<tgroup cols="2">
	  <colspec colname="col1"/>
	  <colspec colname="col2"/>
	  <thead>
	    <row valign="top">
	      <entry colname="col1" colsep="0" valign="top">
                <para>Property</para>
              </entry>
	      <entry colname="col2" valign="top">
                <para>Description</para>
              </entry>
	    </row>
	  </thead>
	  <tbody>
	    <row valign="top">
	      <entry><para>id</para></entry>
	      <entry>
                <para>Reserved for future use.  Should always be 0.</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>radius</para></entry>
	      <entry><para>Outer radius of label</para></entry>
	    </row>
	    <row valign="top">
	      <entry><para>hole</para></entry>
	      <entry><para>Radius of concentric hole</para></entry>
	    </row>
	    <row valign="top">
	      <entry><para>width</para></entry>
	      <entry>
                <para>If present, the label is clipped to the given width.
                  (Useful for "business card CDs").</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>height</para></entry>
	      <entry>
                <para>If present, the label is clipped to the given height.
                  (Useful for "business card CDs").</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>waste</para></entry>
	      <entry>
                <para>Amount of waste (over-print) to allow.  This is useful
                  for minimizing alignment problems when using non-white
                  backgrounds (e.g. images).</para>
              </entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <!-- ==== Figure ==== -->
      <figure id="template-label-cd-fig"> 
	<title>CD Label Parameters</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
		fileref="figures/glabels-template-cd.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
      <!-- ==== End of Figure ==== -->

    </sect2>

    <sect2 id="template-markup-margin-node">
      <title>Markup-margin Node</title>

      <para>A <emphasis>Markup-margin</emphasis> describes a margin along
        all edges of a label.</para>

      <informaltable frame="topbot">
	<tgroup cols="2">
	  <colspec colname="col1"/>
	  <colspec colname="col2"/>
	  <thead>
	    <row valign="top">
	      <entry colname="col1" colsep="0" valign="top">
                <para>Property</para>
              </entry>
	      <entry colname="col2" valign="top">
                <para>Description</para>
              </entry>
	    </row>
	  </thead>
	  <tbody>
	    <row valign="top">
	      <entry><para>size</para></entry>
	      <entry>
                <para>Size of the margin.  I.e. the distance of the margin
                  line from the edge of the card/label.</para>
              </entry>
            </row>
	  </tbody>
	</tgroup>
      </informaltable>

    </sect2>

    <sect2 id="template-markup-line-node">
      <title>Markup-line Node</title>

      <para>A <emphasis>Markup-line</emphasis> describes a markup line.</para>

      <informaltable frame="topbot">
	<tgroup cols="2">
	  <colspec colname="col1"/>
	  <colspec colname="col2"/>
	  <thead>
	    <row valign="top">
	      <entry colname="col1" colsep="0" valign="top">
                <para>Property</para>
              </entry>
	      <entry colname="col2" valign="top">
                <para>Description</para>
              </entry>
	    </row>
	  </thead>
	  <tbody>
	    <row valign="top">
	      <entry><para>x1</para></entry>
	      <entry>
                <para>x coordinate of 1st endpoint of the line segment.</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>y1</para></entry>
	      <entry>
                <para>y coordinate of 1st endpoint of the line segment.</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>x2</para></entry>
	      <entry>
                <para>x coordinate of 2nd endpoint of the line segment.</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>y2</para></entry>
	      <entry>
                <para>y coordinate of 2nd endpoint of the line segment.</para>
              </entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

    </sect2>

    <sect2 id="template-markup-circle-node">
      <title>Markup-circle Node</title>

      <para>A <emphasis>Markup-circle</emphasis> describes a markup circle.
        </para>

      <informaltable frame="topbot">
	<tgroup cols="2">
	  <colspec colname="col1"/>
	  <colspec colname="col2"/>
	  <thead>
	    <row valign="top">
	      <entry colname="col1" colsep="0" valign="top">
                <para>Property</para>
              </entry>
	      <entry colname="col2" valign="top">
                <para>Description</para>
              </entry>
	    </row>
	  </thead>
	  <tbody>
	    <row valign="top">
	      <entry><para>x0</para></entry>
	      <entry>
                <para>x coordinate of circle origin (center).</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>y0</para></entry>
	      <entry>
                <para>y coordinate of circle origin (center).</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>radius</para></entry>
	      <entry><para>Radius of circle.</para></entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

    </sect2>

    <sect2 id="template-markup-rect-node">
      <title>Markup-rect Node</title>

      <para>A <emphasis>Markup-rect</emphasis> describes a markup rectangle.
        </para>

      <informaltable frame="topbot">
	<tgroup cols="2">
	  <colspec colname="col1"/>
	  <colspec colname="col2"/>
	  <thead>
	    <row valign="top">
	      <entry colname="col1" colsep="0" valign="top">
                <para>Property</para>
              </entry>
	      <entry colname="col2" valign="top">
                <para>Description</para>
              </entry>
	    </row>
	  </thead>
	  <tbody>
	    <row valign="top">
	      <entry><para>x1</para></entry>
	      <entry>
                <para>x coordinate of upper left corner of rectangle.</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>y1</para></entry>
	      <entry>
                <para>y coordinate of upper left corner of rectangle.</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>w</para></entry>
	      <entry>
                <para>Width of rectangle.</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>h</para></entry>
	      <entry>
                <para>Height of rectangle.</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>r</para></entry>
	      <entry><para>Radius of rounded corners of rectangle.</para></entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

    </sect2>

    <sect2 id="template-layout-node">
      <title>Layout Node</title>

      <para>A label node may contain multiple <emphasis>Layout</emphasis>
        children.  If labels are arranged in a simple grid pattern, only
        one layout is needed.  However, if labels are arranged in multiple
        grids, such as a running bond pattern, multiple
        <emphasis>layout</emphasis> tags can be used.  Note: a single label
        can always be treated as a grid of one.</para>

      <informaltable frame="topbot">
	<tgroup cols="2">
	  <colspec colname="col1"/>
	  <colspec colname="col2"/>
	  <thead>
	    <row valign="top">
	      <entry colname="col1" colsep="0" valign="top">
                <para>Property</para>
              </entry>
	      <entry colname="col2" valign="top">
                <para>Description</para>
              </entry>
	    </row>
	  </thead>
	  <tbody>
	    <row valign="top">
	      <entry><para>nx</para></entry>
	      <entry>
                <para>Number of labels/cards across in the grid
                  (horizontal)</para>
              </entry>
            </row>
	    <row valign="top">
	      <entry><para>ny</para></entry>
	      <entry>
                <para>Number of labels/cards up and down in the grid
                  (vertical)</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>x0</para></entry>
	      <entry>
                <para>Distance from left edge of sheet to the left edge of
                  the left column of cards/labels in the layout.</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>y0</para></entry>
	      <entry>
                <para>Distance from the top edge of sheet to the top edge of
                  the top row of labels/cards in the layout.</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>dx</para></entry>
	      <entry><para>Horizontal pitch of grid.</para></entry>
	    </row>
	    <row valign="top">
	      <entry><para>dy</para></entry>
	      <entry><para>Vertical pitch of grid.</para></entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      <!-- ==== Figure ==== -->
      <figure id="template-layout-fig"> 
	<title>Layout Parameters</title> 
	<screenshot> 
	  <mediaobject> 
	    <imageobject><imagedata
		fileref="figures/glabels-template-layout.png" format="PNG"/> 
	    </imageobject>
	  </mediaobject> 
	</screenshot> 
      </figure>
      <!-- ==== End of Figure ==== -->

    </sect2>

    <sect2 id="template-alias-node">
      <title>Alias Node</title>

      <para>An <emphasis>Alias</emphasis> node provides the name of a
        product with the same size and layout characteristics as the
        parent template.</para>

      <informaltable frame="topbot">
	<tgroup cols="2">
	  <colspec colname="col1"/>
	  <colspec colname="col2"/>
	  <thead>
	    <row valign="top">
	      <entry colname="col1" colsep="0" valign="top">
                <para>Property</para>
              </entry>
	      <entry colname="col2" valign="top">
                <para>Description</para>
              </entry>
	    </row>
	  </thead>
	  <tbody>
	    <row valign="top">
	      <entry><para>brand</para></entry>
	      <entry>
                <para>The brand or manufacturer of the equivalent product.</para>
              </entry>
	    </row>
	    <row valign="top">
	      <entry><para>part</para></entry>
	      <entry>
                <para>The part number or name of the equivalent product.</para>
              </entry>
	    </row>
	  </tbody>
	</tgroup>
      </informaltable>

      </sect2>

  </sect1>




<!-- ============= Bugs ================================== -->
<!-- This section is optional and is commented out by default. 
     You can use it to describe known bugs and limitations of the 
	  program if there are any - please be frank and list all
     problems you know of. 
  
  <sect1 id="mayapp-bugs">
  <title>Known Bugs and Limitations</title>
  <para> </para>
 </sect1>
-->




<!-- ============= About ================================== -->
<!-- This section contains info about the program (not docs), such as
      author's name(s), web page, license, feedback address. This
      section is optional: primary place for this info is "About.." box of
      the program. However, if you do wish to include this info in the
      manual, this is the place to put it. Alternatively, you can put this information in the title page.-->
  <sect1 id="glabels-about"> 
    <title>About &app;</title> 
    <para> &app; was written by Jim Evins
      (<email>evins@snaught.com</email>). To find more information about
      &app;, please visit the 
      <ulink url="http://glabels.sourceforge.net" type="http">gLabels Web
	page</ulink>. </para>
    <para>
      To report a bug or make a suggestion regarding this application or
      this manual, follow the directions at the
      <ulink url="http://glabels.sourceforge.net/contact/" type="http">&app; Contact Page</ulink>.
    </para>

    <para> This program is distributed under the terms of the GNU
      General Public license as published by the Free Software
      Foundation; either version 2 of the License, or (at your option)
      any later version. A copy of this license can be found at this
      <ulink url="ghelp:gpl" type="help">link</ulink>, or in the file
      COPYING included with the source code of this program. </para>

  </sect1> 





</article>