<?xml version="1.0" standalone="no"?>
<!DOCTYPE book PUBLIC "-//OASIS/DTD DocBookXML V4.5//EN"
               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
  <!ENTITY legal SYSTEM "legal.xml">
  <!ENTITY appversion "0.14.0">
  <!ENTITY manrevision "0.14.0">
  <!ENTITY date "September 2012">
  <!ENTITY app "GChemPaint">
]>
<!-- 
      (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 Jan 30, 2002
-->
<!-- =============Document Header ============================= -->
<book id="index" lang="en">
  <title>&app; manual.</title>
<!-- please do not change the id; for translations, change lang to -->
<!-- appropriate code -->
  <bookinfo> 
	 <title>&app; Manual V&manrevision;</title>
	 <copyright> 
       <year>2005-2010</year>
       <holder>Jean Br&#233;fort</holder>
     </copyright>

  <!-- translators: uncomment this and add lang=".." to the <article> tag:

  <copyright>
   <year>2002</year>
   <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  </copyright>

   -->

	&legal;

	<publisher role="maintainer">
		<publishername>GNOME Documentation Project</publishername>
	</publisher>

	 <authorgroup> 
		<author> 
		  <firstname>Jean</firstname>
		  <surname>Br&#233;fort</surname>
		  <affiliation> 
			 <address> <email>jean.brefort@normalesup.org</email> </address>
		  </affiliation>
		</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. -->
	 <revhistory>
<!-- Remember to remove the &manrevision; entity from the revision entries other
   than the current revision. -->
   		<revision> 
		  <revnumber>&app; Manual V&manrevision;</revnumber>
		  <date>&date;</date> 
		  <revdescription> 
			 <para role="author">Jean Br&#233;fort
				<email>jean.brefort@normalesup.org</email> </para>
			 <para role="publisher">GNOME Documentation Project</para>
		  </revdescription>
		</revision>
   		<revision> 
		  <revnumber>&app; Manual V0.12.0</revnumber>
		  <date>April 2010</date> 
		  <revdescription> 
			 <para role="author">Jean Br&#233;fort
				<email>jean.brefort@normalesup.org</email> </para>
			 <para role="publisher">GNOME Documentation Project</para>
		  </revdescription>
		</revision>
   		<revision> 
		  <revnumber>&app; Manual V0.10.0</revnumber>
		  <date>September 2008</date> 
		  <revdescription> 
			 <para role="author">Jean Br&#233;fort
				<email>jean.brefort@normalesup.org</email> </para>
			 <para role="publisher">GNOME Documentation Project</para>
		  </revdescription>
		</revision>
   		<revision> 
		  <revnumber>&app; Manual V0.8.2</revnumber>
		  <date>July 2007</date> 
		  <revdescription> 
			 <para role="author">Jean Br&#233;fort
				<email>jean.brefort@normalesup.org</email> </para>
			 <para role="publisher">GNOME Documentation Project</para>
		  </revdescription>
		</revision>
  		<revision> 
		  <revnumber>&app; Manual V0.8.0</revnumber>
		  <date>June 2007</date> 
		  <revdescription> 
			 <para role="author">Jean Br&#233;fort
				<email>jean.brefort@normalesup.org</email> </para>
			 <para role="publisher">GNOME Documentation Project</para>
		  </revdescription>
		</revision>
    		<revision> 
		  <revnumber>&app; Manual V0.6</revnumber>
		  <date>August 2005</date> 
		  <revdescription> 
			 <para role="author">Jean Br&#233;fort
				<email>jean.brefort@normalesup.org</email> </para>
			 <para role="publisher">GNOME Documentation Project</para>
		  </revdescription>
		</revision>
  		<revision> 
		  <revnumber>&app; Manual V0.4</revnumber>
		  <date>January 2004</date> 
		  <revdescription> 
			 <para role="author">Jean Br&#233;fort
				<email>jean.brefort@ac-dijon.fr</email> </para>
			 <para role="publisher">GNOME Documentation Project</para>
		  </revdescription>
		</revision>
   		<revision> 
		  <revnumber>&app; Manual V0.2</revnumber>
		  <date>July 2002</date> 
		  <revdescription> 
			 <para role="author">Jean Br&#233;fort
				<email>jean.brefort@ac-dijon.fr</email> </para>
			 <para role="publisher">GNOME Documentation Project</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 <application>&app;</application> application or
		this manual, go to the
		<ulink url="http://savannah.nongnu.org/projects/gchempaint" type="html"><application>&app;</application> home page</ulink>. 
      </para>
<!-- Translators may also add here feedback address for translations -->
	 </legalnotice>
	<abstract role="description">
		<para>&app; allows you to draw and display 2D
		chemical structures.</para>
	</abstract>
  </bookinfo>  

<!-- ============= Document Body ============================= -->

<!-- ============= Introduction ============================= -->
 <preface id="gchempaint-intro">
    <title>Introduction</title>

	 <para>The <application>&app;</application> application is a simple chemical 2D-structures
		editor. You can use <application>&app;</application> to create and edit chemistry related
		files.</para>
 </preface>

<!-- ============= Getting started ============================= -->
 <chapter id="gchempaint-getting-started">
    <title>Getting started</title>
	<sect1 id="gchempaint-to-start">
		<title>To Start &app;</title>
		<para>You can start <application>&app;</application> in the following ways:</para>
		<variablelist>
    		<varlistentry>
    		<term>Applications list</term>
    		<listitem>
    		<para>Choose 
    		<quote>Chemical Structures Editor</quote>. It might be listed either in the Education or
            Science category.</para>
    		</listitem>
    		</varlistentry>
    		<varlistentry>
    		<term>Command line</term>
    		<listitem>
    		<para>Type <command>gchempaint</command>, then press <keycap>Return</keycap>.</para>
    		</listitem>
    		</varlistentry>
		</variablelist>
		<para>GChemPaint can also be run as a Goffice component.
		This makes possible to embed some chemistry in Abiword.</para>
		<para>When using the command line, some options are available:</para>
		<variablelist>
			<varlistentry>
				<term><option>-e</option></term>
				<term><option>--edit-residue</option></term>
				<listitem>
					<para>Open <link linkend="gchempaint-residues">residues dialog</link>.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-F</option></term>
				<term><option>--full-screen</option></term>
				<listitem>
					<para>Open new windows full screen.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-M</option></term>
				<term><option>--maximize</option></term>
				<listitem>
					<para>Open new window maximized.</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term><option>-?</option></term>
				<term><option>--help</option></term>
				<listitem>
					<para>Show application help options.</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</sect1>
	<sect1 id="gchempaint-when-you-start">
		<title>When You Start &app;</title>
		<para>When you start <application>&app;</application>, an empty document window
		and a toolbox are displayed:</para>
 			<figure id="gchempaint-document-window"> 
			  <title>&app; main window</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the GChemPaint document window.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/main-window.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
	
		<para>A <application>&app;</application> document 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 work with files in <application>&app;</application>.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Toolbar</term> 
			 <listitem> 
				<para>The toolbar contains a subset of the commands that you can
				  access from the menubar.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Display area</term> 
			 <listitem> 
				<para> The display area contains the contents of the file that you are
				  editing. </para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Statusbar</term> 
			 <listitem> 
				<para>The statusbar displays information about current
				  <application>&app;</application> activity and contextual information about the
				  menu items. </para>
			 </listitem>
		  </varlistentry>
		</variablelist>
 			<figure id="gchempaint-tools-window"> 
			  <title>&app; toolbox</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the GChemPaint toolbox.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/toolbox.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
		<para>The toobox contains buttons for every available tool, a current element selector
		and a property page for the currently selected element. The screenshot shows the box
		with the selection tool selected (this is the default); its property box contains
		four buttons.</para>
		<para>The toolbox is always displayed along with the active document window.</para>
	</sect1>
	<sect1 id="gchempaint-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 a new <application>&app;</application> document window. </para>
		<para>To Open a recently opened file, choose the appropriate entry
		in <menuchoice> <guimenu>File</guimenu> <guimenuitem>Open recent</guimenuitem>
		</menuchoice></para>
		<para>GChemPaint can open files on a distant server using the Gnome Virtual
		File System. If the file is read-only, the <menuchoice> <guimenu>File</guimenu> <guimenuitem>Save</guimenuitem>
			 </menuchoice> menu item and the corresponding tool button are disabled.</para>
		<para>GChemPaint can open several file formats. Available formats are:</para>
		<itemizedlist> 
		  <listitem><para>Native format (*.gchempaint)</para>
		  </listitem>
		  <listitem><para>Chemical Markup Language files (*.cml)</para>
		  </listitem>
		  <listitem><para>MDL MOL files (*.mol;*.mdl)</para>
		  </listitem>
		  <listitem><para>PDB files (*.pdb;*.ent)</para>
		  </listitem>
		  <listitem><para>ChemDraw eXchange files (*.cdx)</para>
		  </listitem>
		  <listitem><para>ChemDraw eXchange XML files (*.cdxml)</para>
		  </listitem>
		  <listitem><para>PubChem ASN.1 ASCII Format files (*.asn)</para>
		  </listitem>
		  <listitem><para>PubChem ASN.1 Binary Format files (*.asn;*.val)</para>
		  </listitem>
		  <listitem><para>PubChem ASN.1 XML Format files (*.pc)</para>
		  </listitem>
		  <listitem><para>XYZ Co-ordinate Animation Format (*.xyz)</para>
		  </listitem>
		</itemizedlist>
		<para>For some formats, only reading might be supported.</para>
		<para>GChemPaint can also support formats not listed here provided they have a
		known mime type, they are supported by OpenBabel and you add the mime type, one
		per line to the $HOME/.gchempaint/mime-types file.</para>
		<para>Only native format files are opened in the embedded version.</para>
		<para>You can open multiple files in <application>&app;</application>.
		  The application displays each file in its own window.</para>
	</sect1>
	<sect1 id="gchempaint-run-from-cmd-line">
		<title>To Open Multiple Files from a Command Line</title>
		<para>You can run <application>&app;</application> 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>gchempaint <replaceable>file1 file2 file3</replaceable></command>
		where file1 and others are relative or absolut paths or uris.</para>
		<para>When the application starts, the files that you specified are
		  displayed in the <application>&app;</application> main window.</para>
	</sect1>
 </chapter>

<!-- ============= General Usage ============================= -->

<chapter id="gchempaint-usage">
	 <title>General operations</title>

<!-- ============= To Create a New File ======================== -->
	 <sect1 id="gchempaint-newfile"> 
		<title>To Create a New File</title>
		<para>To create a new file, choose 
		  <menuchoice> <guimenu>File</guimenu> <guimenuitem>New</guimenuitem>
			 </menuchoice>. The application displays a new file in the
		  <application>&app;</application> window. The new file uses
		the default theme.</para>
		<para>To create a new file with a differnet theme,
		choose <menuchoice> <guimenu>File</guimenu> <guimenuitem>New File with theme...</guimenuitem>
		</menuchoice>, choose the appropriate theme and valid.</para>
		<figure id="gchempaint-newfile-dialog"> 
		  <title>New File with Theme Dialog</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the New File with Theme Dialog Box.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/newfile.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>This version of <application>&app;</application> is
		shipped with only one theme, the default one.</para>
		<para>For more informations about <application>&app;</application>
		themes, see the <link linkend="gchempaint-themes">Themes editing section</link>.</para>
	 </sect1>
<!-- ============= To Save a File ============================== -->
	 <sect1 id="gchempaint-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 the current file, choose 
				<menuchoice> <guimenu>File</guimenu>
				  <guimenuitem>Save</guimenuitem> </menuchoice> or click <guibutton>Save</guibutton>
				  on the toolbar. If the file does not have a filename, <application>&app;</application> 
					 displays the <guilabel>Save As</guilabel> dialog. Enter a name for the file in the 
<guilabel>Save
				As</guilabel> dialog, choose a file format, then click <guibutton>OK</guibutton>.</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, choose a file format, then click <guibutton>OK</guibutton>. </para>
		  </listitem>
		</itemizedlist>
		<para>Available file formats are:</para>
		<itemizedlist> 
		  <listitem><para>Native format (*.gchempaint)</para>
		  </listitem>
		  <listitem><para>Chemical Markup Language files (*.cml)</para>
		  </listitem>
		  <listitem><para>MDL MOL files (*.mol;*.mdl)</para>
		  </listitem>
		  <listitem><para>PDB files (*.pdb;*.ent)</para>
		  </listitem>
		  <listitem><para>XYZ Co-ordinate Animation Format (*.xyz)</para>
		  </listitem>
		</itemizedlist>
		<para>Of course, only 2D data are exported, even if most
		formats support 3D coordinates.</para>
		<para>The native format is supported directly by GChemPaint, Chemdraw formats
		and CML are supported through plugins, and other files are saved (and read)
		using the <citetitle>OpenBabel library</citetitle>
		<ulink url="http://openbabel.sourceforge.net"></ulink>.</para>
		<para>Saving in a file format other than the native format is unsafe because not all features are
			supported either by the plugins or the OpenBabel library.</para>
		<para>Other formats might be supported, depending on the OpenBabel
		version as explained in the section <link linkend="gchempaint-open-file">
		To Open a File</link>.</para>
	 </sect1>
<!-- ============= Document properties================ -->
	<sect1 id="gchempaint-properties">
		<title>To Edit the Document Properties</title>
		<para>You can edit the document properties as follows:</para>
		<para>Use the menu item <menuchoice>
    		<guisubmenu>View</guisubmenu>
    		<guimenuitem>Tools</guimenuitem>
    		</menuchoice> to open the document properties dialog box.</para>
		<figure id="gchempaint-properties-dialog"> 
		  <title>Document Properties Dialog</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Periodic Table Dialog Box.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/properties.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>The fields in this dialog box are:</para>
		<variablelist> 
		  <varlistentry> <term>Title</term> 
			 <listitem> 
				<para>The title of the document.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Author's Name</term> 
			 <listitem> 
				<para> The default value is the environment variable USERNAME.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Author's E-Mail Address</term> 
			 <listitem> 
				<para>The default value is the environment variable E_MAIL if it exists.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Creation Date</term> 
			 <listitem> 
				<para>The time when the file was created. This field cannot be edited.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Revision Date</term> 
			 <listitem> 
				<para>The last time the file was saved. This field cannot be edited.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Theme</term> 
			 <listitem> 
				<para>The theme used by the document. Changing the theme of
				an existing document is not a recommended operation. Bond lengths
				and some other data will not be updated according to the
				new theme.</para>
				<para>For more informations about <application>&app;</application>
				themes, see the <link linkend="gchempaint-themes">Themes editing section</link>.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Comments</term> 
			 <listitem> 
				<para>This field can contain any useful text.</para>
			 </listitem>
		  </varlistentry>
		</variablelist>
		<para>Dates are created automatically and saved with the file. The other fields are optionnal
		and are saved only if they are not empty.</para>
	</sect1>
<!-- ============= To Print a File============================== -->
	<sect1 id="gchempaint-print">
		<title>To Print the Document</title>
		  <para>To print a document, choose 
		  <menuchoice> <guimenu>File</guimenu> <guimenuitem>Print...</guimenuitem>
			 </menuchoice>.</para>
		 <para><menuchoice> <guimenu>File</guimenu> <guimenuitem>Preview</guimenuitem>
			 </menuchoice> opens a window with a preview of the printed output.</para>
		<para>To tune the printed output, choose<menuchoice>
		<guimenu>File</guimenu> <guimenuitem>Page setup...</guimenuitem>
		 </menuchoice> as explained below.</para>
		<sect2 id="gchempaint-print-setup">
		  <title>The page setup dialog.</title>
		  <para>the first tab of the dialog concerns the paper and margins setup.
		  Headers and footers are not supported in the version of <application>&app;</application></para>
		  <figure id="gchempaint-page-setup"> 
			<title>The Page Setup tab.</title>
			<screenshot> 
			  <mediaobject>
				<imageobject>
				  <objectinfo> <abstract><para>Screenshot of page setup dialog.</para></abstract>
				  </objectinfo> 
				  <imagedata fileref="figures/page-setup.png"/>
				</imageobject>
			  </mediaobject>
			</screenshot>
		  </figure>
		  <para>The second tab allows you to choose the scale of the output. With  no scaling or
		  scaling at 100%, the output will have the same size in points as the size in pixels on
		  the screen. If you choose automatic scaling, you can make the output fill the available
		  space either horizontally, vertically, or both (none of the options is equivalent to no scaling).</para>
		  <para>Printing to more than one page is not supported in this version of <application>&app;</application></para>
		  <figure id="gchempaint-print-scale"> 
			<title>The Print Scale tab.</title>
			<screenshot> 
			  <mediaobject>
				 <imageobject>
					<objectinfo> <abstract><para>Screenshot of the printing scale page.</para></abstract>
					</objectinfo> 
					<imagedata fileref="figures/print-scale.png"/>
				 </imageobject>
			  </mediaobject>
			</screenshot>
		  </figure>
	  </sect2>
	</sect1>
<!-- ============= To Save a File as an Image============================== -->
	 <sect1 id="gchempaint-export-image"> 
		<title>To Export an image</title>
		<para>To export the current file to an image, use 
		  <menuchoice> <guimenu>File</guimenu> <guimenuitem>Save As Image</guimenuitem>
			 </menuchoice>.</para>
		<para>Available formats are SVG, EPS, PS, PDF, and the formats with write support in
		GdkPixbuf.</para>
		<para>To choose a format, you can use an appropriate extension
		in the file name, or explicitly select a format in the combo box.
		With the first method, if <application>&app;</application> does
		not recognize an extension, the exported file will be a SVG
		file. <application>&app;</application> will add an extension
		to the file name if needed.</para>
	 </sect1>
<!-- ============= Preferences ================ -->
	<sect1 id="gchempaint-preferences">
		<title>To Edit the Preferences</title>
		<para>You can change the current settings using
		<menuchoice> <guimenu>Edit</guimenu> <guimenuitem>Preferences</guimenuitem>
			 </menuchoice>:</para>
		<figure id="gchempaint-preferences-dialog"> 
		  <title>Preferences Dialog</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Preferences Dialog Box.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/preferences.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<sect2 id="gchempaint-settings">
			<title>Global settings</title>
			<para><application>&app;</application> has two global settings:</para>
		<variablelist> 
		  <varlistentry> <term>Compression level</term> 
			 <listitem> 
				<para>The compression level used when saving native
				files. If not 0 the file will be compressed using gzip.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Invert wedge hashes</term> 
			 <listitem> 
				<para>If set, the wedge hashes bonds will follow the usual
				convention which put the narrow end at start and the large end
				at the farest end. Default convention in <application>&app;</application>
				is just the inverse, because it is more consistent with perspective
				rules.See the <link linkend="gchempaint-stereobonds">Stereo bond tools</link>
				section for more information.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Use colored atomic symbols in new documents</term> 
			 <listitem> 
				<para>Whether atomic symbol should use the element symbolic color when displayed.
				Attached hydrogen atoms will use the same color.</para>
			 </listitem>
		  </varlistentry>
		</variablelist>
		</sect2>
		<sect2 id="gchempaint-themes">
			<title>Editing Themes.</title>
			<para>Each document has an associated theme. When a document
			is opened, <application>&app;</application> searches
			if a theme already exists with the same name and the same
			settings. If found the existing theme is used, otherwise
			a new theme is added to the themes set and used only for
			this file. It is possible, although not recomended, to change
			the theme associated with the file using it's
			<link linkend="gchempaint-properties">Properties Dialog</link>.</para>
			<para>When the Preferences Dialog Box is opened, the active
			document theme is selected.</para>
			<para>For each theme, the various settings are spread on
			several pages.</para>
			<sect3>
				<title>General settings.</title>
				<para>This page presents the settings which
				did not fit well elsewhere.</para>
				<variablelist> 
				  <varlistentry><term>Name</term> 
					 <listitem> 
						<para>The name of the theme. This name can
						be changed for user define themes and 
						themes specific to a file. Not for the
						default Theme or other pre-defined ones.</para>
					 </listitem>
				  </varlistentry>
				  <varlistentry><term>Scale</term> 
					 <listitem> 
						<para>Scale used to convert real distance to
						canvas distance expressed in pm per pixel.</para>
					 </listitem>
				  </varlistentry>
				  <varlistentry><term>General padding</term> 
					 <listitem> 
						<para>Padding used around text objects such as atoms,
						texts and other typographic signs in pixels.</para>
					 </listitem>
				  </varlistentry>
				  <varlistentry><term>Object padding</term> 
					 <listitem> 
						<para>Default padding in pixels added between consecutive
						objects during an alignment operation.</para>
					 </listitem>
				  </varlistentry>
				  <varlistentry><term>Stoichiometry padding</term> 
					 <listitem> 
						<para>Extra padding between a stoichiometric coefficient
						and its associated molecule in pixels.</para>
					 </listitem>
				  </varlistentry>
				  <varlistentry><term>Sign padding</term> 
					 <listitem> 
						<para>Padding between a '+' sign in a reaction equation
						and reactants symbols in pixels.</para>
					 </listitem>
				  </varlistentry>
				</variablelist>
			</sect3>
			<sect3>
				<title>Arrows related settings.</title>
				<figure id="gchempaint-prefs-arrows-dialog"> 
				  <title>Arrows Page</title>
				  <screenshot> 
						<mediaobject>
							<imageobject>
								<objectinfo> <abstract><para>Screenshot of the Arrows page in the Preferences Dialog Box.</para></abstract>
								</objectinfo> 
								<imagedata fileref="figures/prefs-arrows.png"/>
							</imageobject>
						</mediaobject>
					</screenshot>
				</figure>
				<para></para>
				<variablelist> 
				  <varlistentry><term>Length</term> 
					 <listitem> 
						<para>Default arrow length (in pm just like bond lengths).
						Changing this parameter will have no effect on the lengths
						of exisiting arrows.</para>
					 </listitem>
				  </varlistentry>
				  <varlistentry><term>Width</term> 
					 <listitem> 
						<para>Arrow line width (in pixels).</para>
					 </listitem>
				  </varlistentry>
				  <varlistentry><term>Distance</term> 
					 <listitem> 
						<para>Distance in pixels between two parallel lines (either two arrows or one arrow with two lines).</para>
					 </listitem>
				  </varlistentry>
				  <varlistentry><term>Padding</term> 
					 <listitem> 
						<para>Padding added at each end of an arrow (in pixels).</para>
					 </listitem>
				  </varlistentry>
				  <varlistentry><term>Arrow head A</term> 
					 <listitem> 
						<para>Distance in pixels from tip of arrowhead to center.</para>
					 </listitem>
				  </varlistentry>
				  <varlistentry><term>Arrow head B</term> 
					 <listitem> 
						<para>Distance in pixels from tip of arrowhead to trailing point, measured along shaft.</para>
					 </listitem>
				  </varlistentry>
				  <varlistentry><term>Arrow head C</term> 
					 <listitem> 
						<para>Distance in pixels of arrowhead trailing points from outside edge of shaft.</para>
					 </listitem>
				  </varlistentry>
				</variablelist>
			</sect3>
			<sect3>
				<title>Atoms related settings.</title>
				<figure id="gchempaint-prefs-atoms-fonts-dialog"> 
				  <title>Atoms Font Page</title>
				  <screenshot> 
						<mediaobject>
							<imageobject>
								<objectinfo> <abstract><para>Screenshot of the Atoms font page in the Preferences Dialog Box.</para></abstract>
								</objectinfo> 
								<imagedata fileref="figures/prefs-atoms-font.png"/>
							</imageobject>
						</mediaobject>
					</screenshot>
				</figure>
				<para>Using this property page, it is possible to select
				the font used for atoms and other residues.</para>
				<figure id="gchempaint-prefs-atoms-other-dialog"> 
				  <title>Atoms Extra Page</title>
				  <screenshot> 
						<mediaobject>
							<imageobject>
								<objectinfo> <abstract><para>Screenshot of the Atoms extra page in the Preferences Dialog Box.</para></abstract>
								</objectinfo> 
								<imagedata fileref="figures/prefs-atoms-other.png"/>
							</imageobject>
						</mediaobject>
					</screenshot>
				</figure>
				<variablelist> 
				  <varlistentry><term>Charge sign size</term> 
					 <listitem> 
						<para>The size in pixels of a localized charge sign,
						including the surrounding circle.</para>
					 </listitem>
				  </varlistentry>
				</variablelist>
			</sect3>
			<sect3>
				<title>Bonds related settings.</title>
				<figure id="gchempaint-prefs-bonds-dialog"> 
				  <title>Bonds Page</title>
				  <screenshot> 
						<mediaobject>
							<imageobject>
								<objectinfo> <abstract><para>Screenshot of the Bonds page in the Preferences Dialog Box.</para></abstract>
								</objectinfo> 
								<imagedata fileref="figures/prefs-bonds.png"/>
							</imageobject>
						</mediaobject>
					</screenshot>
				</figure>
				<para></para>
				<variablelist> 
				  <varlistentry><term>Length</term> 
					 <listitem> 
						<para>Default bond length (pm).
						Changing this parameter will have no effect on the lengths
						of exisiting bonds</para>
					 </listitem>
				  </varlistentry>
				  <varlistentry><term>Angle</term> 
					 <listitem> 
						<para>Default angle between two consecutive bonds in a chain.</para>
					 </listitem>
				  </varlistentry>
				  <varlistentry><term>Width</term> 
					 <listitem> 
						<para>Bond line width (in pixels).</para>
					 </listitem>
				  </varlistentry>
				  <varlistentry><term>Distance</term> 
					 <listitem> 
						<para>Distance in pixels between two lines representing a multiple bond.</para>
					 </listitem>
				  </varlistentry>
				  <varlistentry><term>Stereo bond width</term> 
					 <listitem> 
						<para>Width in pixels at the largest end.</para>
					 </listitem>
				  </varlistentry>
				  <varlistentry><term>Hash width</term> 
					 <listitem> 
						<para>Width of hashes in pixels.</para>
					 </listitem>
				  </varlistentry>
				  <varlistentry><term>Hash distance</term> 
					 <listitem> 
						<para>Distance between hashes in pixels.</para>
					 </listitem>
				  </varlistentry>
				</variablelist>
			</sect3>
			<sect3>
				<title>Text related settings.</title>
				<figure id="gchempaint-prefs-text-dialog"> 
				  <title>Text Page</title>
				  <screenshot> 
						<mediaobject>
							<imageobject>
								<objectinfo> <abstract><para>Screenshot of the Text page in the Preferences Dialog Box.</para></abstract>
								</objectinfo> 
								<imagedata fileref="figures/prefs-text.png"/>
							</imageobject>
						</mediaobject>
					</screenshot>
				</figure>
				<para>This font selector gives the default font selected
				when creating a new text object, unless an other font
				has been selected in the
				<link linkend="gchempaint-text">text tool</link> property page.</para>
			</sect3>
		</sect2>
	</sect1>
<!-- ============= Selection ================ -->
	<sect1 id="gchempaint-selection">
		<title>To Select and Move Objects</title>
		<para>To select objects, you can either use the
		<menuchoice> <guimenu>Edit</guimenu>
		<guimenuitem>Select All</guimenuitem> </menuchoice> menu command
		or activate the Selection Tool. With the selection tool, you can also move or rotate objects.
		When you use the <menuchoice> <guimenu>Edit</guimenu>
		<guimenuitem>Select All</guimenuitem> </menuchoice> menu command,
		the Selection Tool is automatically activated.</para>
		<figure id="gchempaint-selection-tool"> 
		  <title>Selection Tool</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Selection Tool button.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/selection.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>This tool is used to select one or several molecules or objects. To select an object,
		just click on it. Molecules and other groups of objects are considered single objects and
		you cannot select only some part of a molecule with this tool. To selct only a portion of
		an object, use the lasso tool:</para>
		<figure id="selection-lasso-tool"> 
		  <title>Lasso Tool</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Lasso Tool button.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/lasso.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>The allowed  actions for a partial selection depend upon what is selected.
		The main use it for <link linkend="gchempaint-lasso-tool">modifying a molecule</link>
		by translating or rotating a portion of it.</para>
		<para>Otherwise, you can select
		all objects at least partially lying inside a rectangle by pressing the
		left button, dragging the mouse from one corner of the rectangle to the opposite one
		and releasing the button. Selected objects have their color changed from black to cyan.</para>
		<para>Selected objects can be moved with the mouse,
		<link linkend="gchempaint-rotate">flipped, rotated</link>, deleted by pressing the delete key, or
		<link linkend="gchempaint-edit">copied</link>.</para>
		<para>When the selection tool is selected, the tools box looks like:</para>
		<figure id="gchempaint-selection-window"> 
		  <title><application>&app;</application> toolbox when the selection tool is selected</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the <application>&app;</application> toolbox when the selection tool is selected.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/toolbox.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>The property page of this tools contains four buttons:</para>
		<variablelist> 
		  <varlistentry><term>Horizontal flip button</term> 
			 <listitem> 
				<para>Use this button to <link linkend="gchempaint-rotate">flip</link> horizontally the current selection.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term>Vertical flip button</term> 
			 <listitem> 
				<para>Use this button to <link linkend="gchempaint-rotate">flip</link> vertically the current selection.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term>Rotate button</term> 
			 <listitem> 
				<para>When this toggle button is active, dragging the mouse over the
				selecton will <link linkend="gchempaint-rotate">rotate</link> it
				instead of moving it to a new position.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term>Molecules merging button</term> 
			 <listitem> 
				<para>Use this button to <link linkend="gchempaint-merge">merge</link> the two selected
				molecules. When the selection does not consist in just two molecules,
				the button is not sensitive.</para>
			 </listitem>
		  </varlistentry>
		</variablelist>
	</sect1>

<!-- ============= Edition ================ -->
	<sect1 id="gchempaint-edit">
		<title>To Copy, Cut, and Paste Objects</title>
		<para>To add, modify or delete objects, you can use the appropriate tool. You can also
		use the <menuchoice> <guimenu>Edit</guimenu>
			 </menuchoice> menu.</para>
			 <para>To copy objects to a buffer, you can choose <menuchoice> <guimenu>Edit</guimenu> <guimenuitem>Copy</guimenuitem>
				  </menuchoice>. If you select objets with the mouse they will also be copied to another buffer.</para>
			<para>If you choose <menuchoice> <guimenu>Edit</guimenu> <guimenuitem>Cut</guimenuitem>
				  </menuchoice> the selected objects will be copied and deleted.</para>
			<para>To paste an object, choose <menuchoice> <guimenu>Edit</guimenu> <guimenuitem>Paste</guimenuitem>
				  </menuchoice>. The pasted objects will appear selected and centered in the window.
		You can also paste objects by clicking with the middle button, objects
		will appear centered at the point where you clicked. Text can also be pasted in a text zone if you paste while editing a text object. You cannot paste
		anything inside a fragment.  Unless if you paste text in an already existing text, the
		<link linkend="gchempaint-selection">Selection Tool</link> will be activated on
		pasting.</para>
	</sect1>

<!-- ============= Undo / Redo ================ -->
	<sect1 id="gchempaint-undo-redo">
		<title>To Undo or Redo Operations</title>
		<para>To undo a change, choose 
		  <menuchoice> <guimenu>Edit</guimenu> <guimenuitem>Undo</guimenuitem>
			 </menuchoice>. To redo an change, choose 
		  <menuchoice> <guimenu>Edit</guimenu> <guimenuitem>Redo</guimenuitem>
			 </menuchoice>. The number of previous changes that you can undo is unlimited in <application>&app;</application></para>
		<para>If you are editing a text or a fragment, you can undo/redo each change done since
		the begin of your edition operation. If you end the edition of such an object, you can only undo
		or redo the whole edition operation.</para>
	</sect1>

<!-- ============= Eraser ================ -->
	<sect1 id="gchempaint-eraser">
		<title>To Delete Objects</title>
		<para>To delete objects, you can activate the Eraser Tool:</para>
			<figure id="gchempaint-eraser-tool"> 
			  <title>Eraser Tool</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the Eraser Tool button.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/eraser.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
			<para>When you drag the mouse cursor, this tool being active, the objects which
			would be deleted after clicking are highlighted in red.</para>
			<para>To erase a bond or an atom, click on it when this tool is active. An atom is suppressed
			with all its bonds. While the button is	pressed, the objects to delete appear coloured in red if
			the pointer remains near them and revert to black if the mouse pointer is moved away.
			When the left button is released, the objects coloured in red are deleted.</para>
			<para>You can also delete whole molecules and groups of objects at once with the help of the
			<link linkend="gchempaint-selection">Selection Tool</link>.</para>
			<para>Automatic objects cannot be deleted with this tool.</para>
			<para>The eraser tool has an empty property page.</para>
	</sect1>

<!-- ============= Flip and rotate ================ -->
	<sect1 id="gchempaint-rotate">
		<title>To Flip or Rotate Objects</title>
		<para>To flip or rotate objects, you can use the following buttons:</para>
		<figure id="gchempaint-rotate-tools"> 
		  <title>Flip and Rotate Buttons</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Flip and Rotate Buttons.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/rotate.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>To flip or rotate objects, select them and click on the appropriate button.</para>
		<para>To rotate the selected objects, drag the mouse on the view until you obtain
		the wanted orientation. Grouped objects cannot be rotated or flipped in this
		version of <application>&app;</application></para>
	</sect1>

<!-- ============= Group and/or align ================ -->
	<sect1 id="gchempaint-group">
		<title>To Group and/or Align Objects</title>
		<para>To group and/or align object, choose <menuchoice>
		<guimenuitem>Group and/or align objects</guimenuitem></menuchoice>
		in the popup menu. The dialog box below will pop up.</para>
		<figure id="gchempaint-group-dialog"> 
		  <title>Group and/or Align Dialog Box.</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Group and/or Align Dialog Box.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/group.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>The fields in this dialog box are:</para>
		<variablelist> 
		  <varlistentry><term><guibutton>Group</guibutton></term>
			 <listitem> 
				<para>Whether to create or not a group.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term><guibutton>Align</guibutton></term>
			 <listitem> 
				<para>Whether to align selected objects or not.</para>
				<para>If you choose to align the objects, you must select
				the alignment mode in the list. Available modes are:</para>
				<variablelist>
				  <varlistentry><term>Normal</term>
				    <listitem>
					  <para>This is the most usual mode. Texts will have the same
					  baseline and other objects will be aligned on a horizontal line passing in the middle of a C character
					  in the font used for chemical symbols.</para>
					  <para>You can choose which part of a molecule (bond, atom or fragment) will be used for
					  normal alignment: move the mouse cursor to the bond, atom, or fragment, right click and select
					  <menuchoice><guimenuitem>Select alignment item</guimenuitem></menuchoice> in the popup menu.</para>
					</listitem>
				  </varlistentry>
				  <varlistentry><term>Top</term>
				    <listitem>
					  <para>Align object according to their top borders.</para>
					</listitem>
				  </varlistentry>
				  <varlistentry><term>Mid-height</term>
				    <listitem>
					  <para>Align object according to their vertical centers.</para>
					</listitem>
				  </varlistentry>
				  <varlistentry><term>Bottom</term>
				    <listitem>
					  <para>Align object according to their bottom borders.</para>
					</listitem>
				  </varlistentry>
				  <varlistentry><term>Left</term>
				    <listitem>
					  <para>Align object according to their left borders.</para>
					</listitem>
				  </varlistentry>
				  <varlistentry><term>Center</term>
				    <listitem>
					  <para>Align object according to their horizontal centers.</para>
					</listitem>
				  </varlistentry>
				  <varlistentry><term>Right</term>
				    <listitem>
					  <para>Align object according to their right borders.</para>
					</listitem>
				  </varlistentry>
				</variablelist>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term><guibutton>Space evenly</guibutton></term>
			 <listitem> 
				<para>Whether to space evenly aligned objects or not. This option is available only
				if you align the objects. You must choose the distance to use to space the objects
				in the spin button on the right.</para>
			 </listitem>
		  </varlistentry>
		</variablelist> 
		<para>If grouped, objects will stay aligned when a change occur.</para>
		<para>Groups cannot be flipped or rotated in this version
		of <application>&app;</application>.</para>
		<para>To ungroup objects or change alignment, choose <menuchoice>
		<guimenuitem>Group properties</guimenuitem></menuchoice> in the
		contextual menu to display the dialog, uncheck
		<guibutton>Group</guibutton> and validate.</para>
	</sect1>
</chapter>

<!-- ============= Molecules ================ -->
<chapter id="gchempaint-molecules">
	<title>Editing molecules.</title>

<!-- ============= Document properties================ -->
	<sect1 id="gchempaint-mendeleiev">
	  <title>To Change the Current Element</title>
	  <para>You can change the current element with the keyboard or with the Periodic Table Combo Button
	  in the tools box.</para>
	  <sect2 id="gchempaint-mendeleiev-kbd">
		<title>Using the keyboard.</title>
		<para>When no text is being edited, typing a lowercase character will change
		the current element. Only 26 elements can be selected this way:
		</para>
		<table><title>One character shortcuts for elements.</title>
		  <tgroup cols="4" align="left" colsep="1" rowsep="1"><tbody>
		  <row><entry>a: Al</entry><entry>b: B</entry><entry>c: C</entry><entry>d: Na</entry></row>
		  <row><entry>e: Se</entry><entry>f: F</entry><entry>g: Ge</entry><entry>h:H</entry></row>
		  <row><entry>i: I</entry><entry>j: Ti</entry><entry>k: K</entry><entry>l: Li</entry></row>
		  <row><entry>m: Mg</entry><entry>n: N</entry><entry>o: O</entry><entry>p: P</entry></row>
		  <row><entry>q: Si</entry><entry>r: Br</entry><entry>s: S</entry><entry>t: Pt</entry></row>
		  <row><entry>u: Cu</entry><entry>v: V</entry><entry>w: W</entry><entry>x: Cl</entry></row>
		  <row><entry>y: Y</entry><entry>z: Zr</entry><entry></entry><entry></entry></row>
		  </tbody></tgroup>
		</table>
		<para>All elements can be accessed by typing an uppercase character. A popup
		menu appears which list all the known symbols starting with this character.
		The second character is used as a shortcut in the menu. As a sample, this is what
		you get when you type 'P':</para>
		<figure id="gchempaint-choose-elt-menu"> 
		  <title>Element popup menu.</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Element popup menu.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/elt-menu.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>Changing the current element using the keyboard might modify
		the atom under the mouse cursor if any, see <link linkend="gchempaint-element">Modifying Atoms</link>.</para>
	  </sect2>
	  <sect2 id="gchempaint-mendeleiev-box">
		<title>Using the Periodic Table Combo Button.</title>
		<figure id="gchempaint-choose-elt"> 
		  <title>Chosing an element</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Periodic Table combo button poped up.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/choose-elt.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>Just click on the wanted element, and it becomes the current element.</para>
		<para>The symbol of the selected element also appears on the
		<link linkend="gchempaint-element">Element tool button</link>.
		Every new atom created with all tools are atoms of the default element.
		Carbon is the selected element when the application starts.</para>
	  </sect2>
	</sect1>

<!-- ============= Templates ================ -->
	<sect1 id="gchempaint-templates">
		<title>To Use or Manage Templates</title>
		<para>To use or manage templates, you can activate the Template Tool:</para>
		<figure id="gchempaint-template-toolbar"> 
		  <title>Templates Tool</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Templates Toolbar.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/templates-tools.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>When the template tool is activated, the tools box looks like:</para>
		  <figure id="gchempaint-templates-dialog"> 
		    <title><application>&app;</application>Toolbox when the templates tool is selected</title>
		    <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the <application>&app;</application> toolbox when the selection tool is selected.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/templates.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		  </figure>
		<para>When the template tool is active, yo can add the molecule corresponding to the active template in your
		document by clicking where you want to add it unless the
		<link linkend="gchempaint-new-template">new template dialog</link> is opened.
		The new molecule will be centered around where you release
		the mouse button. The molecule will be scaled so that it's median bond length
		is equal to the current document theme bond length.</para>
		<sect2 id="gchempaint-managing-templates">
		  <title>Managing Templates</title>
		<para>To select a template, use the drop down list.</para>
		<para>When a template is selected in the tree, a preview is available in the toolbox.</para>
		<para>User's templates can be deleted with the <guibutton>Remove</guibutton> button. For system wide
		installed templates, the button is deactivated.</para>
		<para>To add a new template, choose <guibutton>Add</guibutton>. The
		<link linkend="gchempaint-new-template">New Template dialog</link> will be opened.</para>
		</sect2>
		<sect2 id="gchempaint-new-template">
		  <title>Adding a New Template</title>
		  <figure id="gchempaint-new-template-dialog"> 
		    <title>New Template Dialog</title>
		    <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the New Template Dialog.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/new-template.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		  </figure>
		<para>To add a new template, you must provide a name, a category (you can choose an existing
		category or create a new one), and a molecule.</para>
		<para>To create the molecule for the template, draw it in a document and while the dialog is opened and the
		templates tool is active, click on the molecule. The molecule is copied to the new template dialog.</para>
		</sect2>
	</sect1>
<!-- ============= Residues ================ -->
	<sect1 id="gchempaint-residues">
		<title>To Manage Residues</title>
		<para>In <application>&app;</application>, Residues are atoms groups with a symbol, such as Ph for phenyl. <application>&app;</application>
		comes with a list of predefined group symbols, but you can define new residues in needed. When
		importing a file with unknown symbols, either a <application>&app;</application> file, or a ChemDraw® file,
		new symobls are added to the user define symbols list.</para>
        <para>To define a new symbol, choose <menuchoice>
		<guimenuitem>Tools/Edit residues...</guimenuitem></menuchoice>, the following dialog
		will pop up:</para>
		  <figure id="gchempaint-residue-dialog"> 
		    <title>Residues dialog</title>
		    <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Residues dialog box.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/residues.png"/>
					</imageobject>
				</mediaobject>
			  </screenshot>
		  </figure>
		<para>You can choose either a new residue (the default) or an already known
		symbol in the dropdown list at top left of the dialog box. Selecting "Ph" leads to:</para>
		  <figure id="gchempaint-phenyl-residue"> 
		    <title>Phenyl residue</title>
		    <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Residues dialog showing the phenyl residue.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/phenyl-residue.png"/>
					</imageobject>
				</mediaobject>
			  </screenshot>
		  </figure>
		<para>The entries and the check box are greyed because this residue is standard and can't be edited.</para>
		<para>The name must be unique, but several symbols can be defined. The various symbols
		must be separated by semicolons. Generic residues correspond to symbols which may represent
		various structures such as R for alkyle, Ar for aryle, X for a halogen atom, or M for a metal atom.</para>
		<para>If you display the structure page for the phenyl aresidue, you get:</para>
		  <figure id="gchempaint-phenyl-strucure"> 
		    <title>Phenyl structure</title>
		    <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Residues dialog showing the phenyl structure.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/phenyl-structure.png"/>
					</imageobject>
				</mediaobject>
			  </screenshot>
		  </figure>
		<para>The bullet represents the attachment point of th residue. It is linked to the first atom
		by a single bond. Multiple bonds are not allowed in this version of <application>&app;</application>.</para>
		<para>When you want to create a new residue, you might first select an existing one
		with a similar structure. When you select "New" in the list, the structure is conserved.
		When the dialog box is created, the default structure is a methyl. For generic residues
		the structure should represent a simple case.</para>
		<para>When you have the new strucutre and filled the name and symbol for it, you have
		to click on the <guibutton>Save</guibutton> button to save it to the database.</para>
		<para>The <guibutton>Delete</guibutton> button is used for removing the selected
		residue from the database and is enabled only when the residue can be securely deleted.
		</para>
	</sect1>
<!-- ============= Add or modify an atom ================ -->
	<sect1 id="gchempaint-element">
		<title>To Add or Modify an Atom</title>
		<para>To add or modify an atom, you can activate the Element Tool or the Fragment Tool:</para>
		<sect2 id="gchempaint-atom">
			<title>To Add or Modify an Single Atom</title>
			<figure id="gchempaint-element-tool"> 
			  <title>Element Tool</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the Element Tool button.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/element.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
			<para>With this tool, you can add an atom everywhere on the canvas or
			change the nature of an already existing atom. The element is chosen with the
			periodic table available in the view menu or by double clicking on
			the tool's button. The symbol of the currently
			selected element appears in the button of this tool. By default, carbon is
			the current element as shown on the screenshot above. While the left button
			remains pressed, the new atom or label appears coloured in green. If you move the
			mouse away from where the left button was pressed, the new atom disappears. The changes
			are effective when the button is released while the pointer stays on the new or changed atom.
			Attached hydrogens are automatically added for non metals.</para>
			<para>To change the default element,use the <link linkend="gchempaint-mendeleiev">
			Periodic Table Button</link>.</para>
			<para>It is also possible to change the nature of an atom using
			the keyboard: put the mouse cursor on the atom you want to
			modify, and then select the new element as described
			<link linkend="gchempaint-mendeleiev-kbd">there</link>. Note
			that this will also change the current element.</para>
			<para>A <link linkend="gchempaint-charge">local charge</link> and
			<link linkend="gchempaint-electrons">explicit single
			electrons or electrons pairs</link> can be added
			to the atom with the appropriate tool.</para>
			<para>Carbon atom are normally not displayed when they have at
			least one bond. You can change this behaviour for each carbon atom
			using <menuchoice> <guimenu>File</guimenu> <guimenuitem>Display symbol</guimenuitem>
			</menuchoice> in the contextual menu.</para>
			<para id="gchempaint-Hposdlg">When a non metal has implicit hydrogen
			atoms, <application>&app;</application> tries to infer if they should
			appear on the left or the right of the atomic symbol. If the automatic
			behavior is not what you wish, you can force a left or right position
			using <menuchoice> <guimenu>File</guimenu> <guimenuitem>Hydrogen atoms position</guimenuitem>
			</menuchoice> in the contextual menu. The following dialog will pop up:</para>
			<figure id="gchempaint-H-pos-dialog"> 
			  <title>Hydrogen atoms position dialog box</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Hydrogen atoms position dialog box.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/Hposdlg.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
			<para>Choose one of the options (Left, Right, Top, Bottom, or Auto).
			The chosen option will be instantly applied.</para>
		</sect2>
		<sect2 id="gchempaint-fragment">
			<title>To Add or Modify a Group of Atoms</title>
			<figure id="gchempaint-fragment-tool"> 
			  <title>Fragment Tool</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the Fragment Tool button.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/fragment.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
			<para>With this tool, you can add a formula just by typing some text. In
			<application>&app;</application>, such text 
			representing atoms is called a fragment. What you type with this tool is only partially analyzed. You
			must first type a valid atomic or <link linkend="gchempaint-residues">group</link> symbol. The fragment will be aligned on the center of this symbol
			and this allows you to include the fragment in a molecule by adding a bond. Fragments cannot have
			more than one single bond in the present version of <application>&app;</application>. The bond
			can be added to any atom in the fragment. The bonded atom is the reference atom of the fragment.
			When editing, you must always have a valid symbol at its position.</para>
			<para>This tool has several input modes. To switch between modes, you
			need to use the appropriate key combinations. Current mode is displayed in the status bar.
			Typing the shortcut for current mode always select normal mode.</para>
			<para>Available modes:</para>
				<itemizedlist> 
				  <listitem><para>Normal mode (<keycombo><keycap>Control</keycap><keycap>Space</keycap></keycombo>):
				  in this mode, <application>&app;</application> tries to interpret the string according to knwon rules.
				  </para>
				  </listitem>			  
				  <listitem><para>Stoichiometry mode (<keycombo><keycap>Control</keycap><keycap>n</keycap></keycombo>):
				  text entered in this mode is displayed as subscript and considered as a stoichiometric coefficient.
				  <application>&app;</application> does not check what is entered in this version, but
				  this will change in the future.
				  </para>
				  </listitem>
				  <listitem><para>Charge mode (<keycombo><keycap>Control</keycap><keycap>+</keycap></keycombo>):
				  text entered in this mode is considered as charge and displayed as superscript.
				  <application>&app;</application> checks what is entered and complains when it
				  does not cosider the entered text as a valid charge. Currently, a valid charge
				  is either a number or a single character (might be a unicode character like &#948;
				  followed by either + or &#8722;.
				  </para>
				  </listitem>
				  <listitem><para>Subscript mode (<keycombo><keycap>Control</keycap><keycap>_</keycap></keycombo>):
				  text entered as subscript, but with no stoichiometry meaning. Should nevertheless
				  have a chemical meaning since <application>&app;</application> might check it in the future.
				  </para>
				  </listitem>
				  <listitem><para>Superscript mode (<keycombo><keycap>Control</keycap><keycap>^</keycap></keycombo>):
				  text entered as superscript, but with no charge meaning. Should nevertheless
				  have a chemical meaning since <application>&app;</application> might check it in the future.
				  </para>
				  </listitem>
				</itemizedlist>
			<para>In normal mode, figures are automatically displayed smaller than symbols and slightly lowered unless they
			are part of a charge. To add a charge in the fragment, first type the sign and then, either the figures
			or other signs: typing a + increments the current charge and typing a - decrements it.</para>
			<para>To obtain Fe<superscript>2+</superscript>, you can type Fe+2 or Fe++.</para>
			<para>Fragments also support <link linkend="gchempaint-charge">local charges</link>,
			but only if no charge is indicated in the fragment itself.</para>
			<para>It is also possible to force some text to appear and be considered as a charge
			by switching to the charge input mode. Inside charges the - sign is replaced by an unicode
			minus character (&#8722;). <application>&app;</application> will check if the entered text looks like
			a charge.</para>
			<para>The fragment tool also converts existing atoms to fragment. This might be useful
			to change the position of attached hydrogens or to display terminal carbon atoms.
			In the other way, the Element Tool can also be used on fragments. It tries to replace the symbol
			at the position of the click by the current element symbol if there is no bond. If there is a bond,
			the symbol of the bonded atom is changed whereever you click. To transform a whole fragment
			into an ordinary atom, press the Control key while clicking on the fragment.</para>
			<warning><para>Saving a file containing fragments in a format different from the native one
			is very unsafe.</para></warning>
		</sect2>
	</sect1>
<!-- ============= Add or modify a charge ================ -->
	<sect1 id="gchempaint-charge">
		<title>To Add or Modify a Local Charge</title>
		<para>To add or modify a localized charge, you can activate one of the following tools:</para>
		<figure id="gchempaint-charge-tool"> 
		  <title>Charge Tools</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Charge Tools button.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/charges.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>The tools can be used to increment or decrement the local charge of an atom
		by clicking on the atom while the appropriate tool is active. Local charges can also be added
		to atoms located in <link linkend="gchempaint-fragment">fragments</link> with
		the following restrictions: only one atom in a fragment can bear a local charge; if the fragment
		has a bond, only the bonded atom can bear the charge; and if charges are already present in
		the fragment, no other local charge can be supported by the fragment.
		In fragments, local charges are limited to -1 and +1 in this version
		of <application>&app;</application>.</para>
		<para>To display the charge at a position different from the default one,
		drag the charge to the wanted position while pressing the mouse button.
		Pressing the Shift key and/or the Control key change the behavior while
		dragging.</para>
	</sect1>
<!-- ============= Add unbound electrons to atoms ================ -->
	<sect1 id="gchempaint-electrons">
		<title>To Add Unbound Electrons to Atoms</title>
		<para>To add unbound electrons to an atom, you can activate one of the following tools:</para>
		<figure id="gchempaint-electrons-tools"> 
		  <title>Electrons Tools</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Electrons Tools button.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/electrons.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>The tools can be used to add explicit electrons to an atom
		by clicking on the atom while the appropriate tool is active.</para>
		<para>To display the electron or the electron pair at a position
		different from the default one,
		drag the charge to the wanted position while pressing the mouse button.
		Pressing the Shift key and/or the Control key change the behavior while
		dragging.</para>
	</sect1>
<!-- ============= Add orbitals to atoms ================ -->
	<sect1 id="gchempaint-orbital">
		<title>To Add or Modify Orbitals representations</title>
		<para>It is possible to add an orbital representation to an atom such as:</para>
		<figure id="gchempaint-orbital-sample"> 
	  	  <title>Orbital sample</title>
		  <screenshot>
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of an orbital representation.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/orbital-sample.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>To add one such representation, select the orbital tool:</para>
		<figure id="gchempaint-orbital-tool"> 
		  	<title>Orbital tool</title>
 		    <screenshot>
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the orbital tool.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/orbital.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>When this tool is selected the toolbox looks like:</para>
		<figure id="gchempaint-orbital-toolbox"> 
		  	<title>Toolbox with orbital tool selected</title>
		    <screenshot>
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the toolbox with the orbitaltool selected.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/orbital-toolbox.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>The available options are:</para>
		<variablelist> 
		  <varlistentry> <term>Coefficient</term> 
			 <listitem> 
				<para>A coefficient which affects the size and sign of the orbital.
				Acceptable valies are -1. to +1.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Rotation</term> 
			 <listitem> 
				<para>The rotation relative to the vertical. This option is, of course,
				not available for s-type orbitals.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Type</term> 
			 <listitem> 
				<para>The type of the new orbital.</para>
			 </listitem>
		  </varlistentry>
		</variablelist> 
		<para>To modify an existing orbital, right click on it or on the corresponding
		atomic symbol, select the orbital in the popup menu, and choose <menuchoice>
		<guimenuitem>Properties</guimenuitem> </menuchoice>.</para>
		<para>This pops up the following window with the same options as in the toolbox:</para>
		<figure id="gchempaint-orbital-properties"> 
		  <title>Orbital properties dialog</title>
		  <screenshot>
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the orbital properties dialog.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/orbital-prop.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
	</sect1>
<!-- ============= Add or modify a bond ================ -->
	<sect1 id="gchempaint-bond">
		<title>To Add or Modify a Bond</title>
		<para>To add or modify an atom, you can activate one of the following tools:</para>
		<sect2 id="gchempaint-normal-bond">
			<title>Bond tool</title>
			<figure id="gchempaint-bond-tool"> 
			  <title>Bond Tool</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the Bond Tool button.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/bond.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
			<para>This tool allows to draw new bonds and to change the multiplicity of an
			existing bond. The changes become permanent only when the mouse button is released.</para>
			<para>To add a new bond, click on an existing atom or fragment or on the background (an atom will be
			defined at the position of the click) with the left button.</para>
			<para>On clicking, the new bond appears in the default direction. This
			direction depends on the number of preexisting bonds:</para>
			<itemizedlist> 
			  <listitem><para>No bond or more than two: horizontal, to the right.</para>
			  </listitem>
			  <listitem><para>One bond: the new bond will form with the first bond
			  an angle equal to the current setting in the <link linkend="gchempaint-bond-options">tool options</link>,
			  to the right if the caps lock is on, to the left otherwise.</para>
			  </listitem>
			  <listitem><para>Two bonds: the direction will be the external bisector
			  of the angle of the two bonds.</para>
			  </listitem>
			</itemizedlist> 
			<para>If the default direction is not what you want, drag the mouse in the direction
			of the bond and release the mouse when the green line is where you want the bond lie.
			Current orientation is indicated in the status bar.
			If you drag to an existing atom, and if the <guibutton>Merge with existing atoms</guibutton> button
			in the <link linkend="gchempaint-bond-options">tool options</link> is checked, the bond will end on that atom and if you return the mouse
			to the original position, no bond will be added (the green line disappears). Release
			the button to draw the bond. <application>&app;</application> creates new atoms of the
			<link linkend="gchempaint-mendeleiev">current element</link>.</para>
			<para>When the new bond does not end at a preexisting atom, the bond length is fixed and the bond
			angle from horizontal is a multiple of 5. Pressing the Shift key removes the fixed length
			restriction and pressing the Control removes the restriction about the angle.
			</para>
			<para>To change a bond multiplicity, click on the bond with the left button. If you change
			your mind, drag the mouse away from the bond before releasing the button. A single bond
			will become a double bond, a double will become a triple and a triple bond will revert to
			a single bond. If the bond was a stereo bond, it becomes a normal single bond.</para>
		</sect2>
		<sect2 id="gchempaint-stereobonds">
			<title>Stereo bond tools</title>
			<figure id="gchempaint-stereo-bond-tool"> 
			  <title>Stereo Bond Tools</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the Stereo Bonds Tools buttons.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/stereobonds.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
			<para>These tools allow to draw single stereo bonds. If you click on an existing bond
			when this tool is active, the bond becomes a stereo bond. If it is already that sort
			of bond, extremities are exchanged, except for squiggle bonds for which it has no effect.
			Otherwise these tools work as the
			<link linkend="gchempaint-normal-bond">normal bond tool</link>.</para>
			<para>Convention for the wedge hashes start and end widths in <application>&app;</application>
			puts the largest end at start, because it is the nearest from the viewer perspective. This
			is contrary to the usual convention. To use the usual convention, check the appropriate
			box in the <link linkend="gchempaint-preferences">Preferences dialog</link>.</para>
			<para>The current convention is reflected by the icon displayed in the tool button.
			The bottom left end represents the start bond position and top right the end bond
			position. When the usual convention is used, the tool button will look like:</para>
			<figure id="gchempaint-downbond-tool"> 
			  <title>Inverted convention.</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the Down bond tool
							when the invert wedge hashes option is selected.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/downbond.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
		</sect2>
		<sect2 id="gchempaint-bond-options">
			<title>Bond tools options</title>
			<figure id="gchempaint-bond-window"> 
			  <title><application>&app;</application> toolbox when a bond tool is selected</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the <application>&app;</application> toolbox when a bond tool is selected.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/bond-opts.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
			<para>The available options are:</para>
			<variablelist> 
			  <varlistentry> <term>Bond length</term> 
				 <listitem> 
					<para>The default length of a new bond.</para>
				 </listitem>
			  </varlistentry>
			  <varlistentry> <term>Bond angle</term> 
				 <listitem> 
					<para>The default angle between two consecutive bonds in a chain.</para>
				 </listitem>
			  </varlistentry>
			  <varlistentry> <term>Merge with existing atoms</term> 
				 <listitem> 
					<para>If checked, exiting atoms will be used when present at
					the end of the new bond. Otherwise, a new atom will be created
					even if it results to two atoms at the same position.</para>
				 </listitem>
			  </varlistentry>
			</variablelist> 
		</sect2>
	</sect1>
<!-- ============= Add a chain ================ -->
	<sect1 id="gchempaint-chain">
		<title>To Add a Chain</title>
		<para>To add a chain, activate the chain tool.</para>
		<figure id="gchempaint-chain-tool"> 
			<title>Fixed Size Cycle Tools buttons</title>
			<screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Fixed Size Cycle Tools buttons.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/chain.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>This tool allows to add a new chain at once. The changes become permanent only when the mouse button is released.</para>
		<para>To add a new chain, click on an existing atom or fragment or on the background (an atom will be
		defined at the position of the click) with the left button.</para>
		<para>On clicking, the new chain appears in the default direction. The direction
		of the chain is not that of its first bond, but the direction from
		the start of the chain to the end of the second bond. This
		direction depends on the number of preexisting bonds:</para>
		<itemizedlist> 
		  <listitem><para>No bond or more than two: horizontal, to the right.
		  The second bond will turn to the left if the caps lock is on,
		  to the right otherwise.</para>
		  </listitem>
		  <listitem><para>One bond: the fisrt bond of the new chain will form with the first bond
		  an angle equal to the current setting in the <link linkend="gchempaint-chain-options">tool options</link>,
		  to the right if the caps lock is on, to the left otherwise.</para>
		  </listitem>
		  <listitem><para>Two bonds: the direction of the first bond will be the external bisector
		  of the angle of the two bonds. The direction of the second bond depends on the
		  status of the caps lock as before.</para>
		  </listitem>
		</itemizedlist>
		<para>If the default direction is not what you want, drag the mouse in the direction
		of the bond and release the mouse when the green chain is where you want the chain lie.
		Current orientation is indicated in the status bar.
		If you drag to an existing atom, and if the <guibutton>Merge with existing atoms</guibutton> button
		in the <link linkend="gchempaint-chain-options">tool options</link> is checked, the bond will end on that atom and if you return the mouse
		to the original position, no bond will be added (the green chain disappears). Release
		the button to draw the chain. <application>&app;</application> creates new atoms of the
		<link linkend="gchempaint-mendeleiev">current element</link>.</para>
		<para>When the new chain does not end at a preexisting atom, the bond length is fixed and the chain
		angle from horizontal is a multiple of 5. Pressing the Control key removes the restriction about the angle.
		</para>
		<para>The chain length is either set in the <link linkend="gchempaint-chain-options">options</link>
		or calculated according to the mouse position. A new chain has at least two bonds.</para>
		<para>Pressing the Shift key removes the constraint about the bond lengths, but fixes
		the bonds number.</para>
		<para id="gchempaint-chain-options">When the chain tool
		is active, the toolbox looks like:</para>
		<figure id="gchempaint-chain-window"> 
		  <title><application>&app;</application> toolbox when the chain tool is selected</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the <application>&app;</application> toolbox when the chain tool is selected.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/chain-opt.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>The available options are:</para>
		<variablelist> 
		  <varlistentry> <term>Bond length</term> 
			 <listitem> 
				<para>The default length of a new bond.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Bond angle</term> 
			 <listitem> 
				<para>The default angle between two consecutive bonds in a chain.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Bond number</term> 
			 <listitem> 
				<para>The number of bonds to add in the new chain.
				If the <guibutton>Auto</guibutton> is checked, the bond
				length is determined from the mouse position while dragging,
				otherwise, the number in the entry is used, which is quite
				useful when adding a chain with just one click.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Merge with existing atoms</term> 
			 <listitem> 
				<para>If checked, exiting atoms will be used when present at
				the end of a new bond. Otherwise, a new atom will be created
				even if it results to two atoms at the same position.</para>
			 </listitem>
		  </varlistentry>
		</variablelist> 
	</sect1>
<!-- ============= Add a cycle ================ -->
	<sect1 id="gchempaint-cycle">
		<title>To Add a Cycle</title>
		<para>To add a cycle, you can activate one of the following tools:</para>
		<sect2 id="gchempaint-fixed-size-cycle">
			<title>Fixed size cycle tools</title>
			<figure id="gchempaint-fixed-size-cycle-tool"> 
			  <title>Fixed Size Cycle Tool</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the Fixed Size Cycle Tools buttons.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/cycletools.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
			<para>These tools allow to draw a whole cycle at once. If the click occurs on an atom or on the
			background, dragging the mouse will change the orientation of the cycle. When the click occurs
			on a preexisting atom, the default orientation is chosen relatively to preexisting bonds.
			Shift and Control keys have the same effect than with the bonds tools.</para>
			<para>If the click occurs on a bond, the new cycle will contain this bond. The new cycle  appears by
			default on the less hindered size of the bond. Drag the mouse on the other size before releasing
			the button if you want to draw the cycle on the other side. Pressing the Shift key and
			moving the mouse to an adjacent bond will include this bond in the new cycle if the size of the
			new cycle is large enough (at least two new bonds will be created).</para>
			<para id="gchempaint-cycle-options">When one of the cycle tools
			is active, the toolbox looks like:</para>
			<figure id="gchempaint-cycle-window"> 
			  <title><application>&app;</application> toolbox when a cycle tool is selected</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the <application>&app;</application> toolbox when a cycle tool is selected.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/cycle-opt.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
			<para>The available options are:</para>
			<variablelist> 
			  <varlistentry> <term>Bond length</term> 
				 <listitem> 
					<para>The default length of a new bond.</para>
				 </listitem>
			  </varlistentry>
			  <varlistentry> <term>Merge with existing atoms</term> 
				 <listitem> 
					<para>If checked, exiting atoms will be used when present at
					the end of the new bond. Otherwise, a new atom will be created
					even if it results to two atoms at the same position.</para>
				 </listitem>
			  </varlistentry>
			</variablelist> 
		</sect2>
		<sect2 id="gchempaint-variable-size-cycle">
			<title>Variable size cycle tool</title>
			<figure id="gchempaint-variable-size-cycle-tool"> 
			  <title>Variable Size Cycle Tool</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the Variable Size Cycle Tool button.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/cyclentool.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
			<para>This tool works the same as the other cycle tools. The size or the new cycles can be changed
			in the property box associated with this tool. The default size is nine and the largest possible
			size is one hundred.</para>
			<para id="gchempaint-cyclen-options">When the variable size cycle tool
			is active, the toolbox looks like:</para>
			<figure id="gchempaint-cyclen-window"> 
			  <title><application>&app;</application> toolbox when the variable size cycle tool is selected</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the <application>&app;</application> toolbox when the variable size cycle tool is selected.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/cyclentool-opt.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
			<para>The available options are:</para>
			<variablelist> 
			  <varlistentry> <term>Bond length</term> 
				 <listitem> 
					<para>The default length of a new bond.</para>
				 </listitem>
			  </varlistentry>
			  <varlistentry> <term>Cycle Size</term> 
				 <listitem> 
					<para>The size of the new cycles.</para>
				 </listitem>
			  </varlistentry>
			  <varlistentry> <term>Merge with existing atoms</term> 
				 <listitem> 
					<para>If checked, exiting atoms will be used when present at
					the end of the new bond. Otherwise, a new atom will be created
					even if it results to two atoms at the same position.</para>
				 </listitem>
			  </varlistentry>
			</variablelist> 
		</sect2>
	</sect1>
<!-- ============= Add a Newman projection ================ -->
	<sect1 id="gchempaint-newman">
		<title>To Add a Newman Projection</title>
		<para>To add a Newman projection, use the following tool:</para>
		<figure id="molecule-newman-tool"> 
		  <title>Newman Projection Tool</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Newman Projection Tool button.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/newman.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>This tool allows to add a Newman projection. The changes become permanent only when the mouse button is released.</para>
		<para>To add a Newman projection, click on the background. Contrarily to other tools existing atoms
		are never used by this tool. It creates new atoms of the current element.</para>
		<para id="gchempaint-newman-options">When the Neman projection tool
		is active, the toolbox looks like:</para>
		<figure id="gchempaint-newman-window"> 
		  <title><application>&app;</application> toolbox when the Newman projection tool is selected</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the <application>&app;</application> toolbox when the Newman projection tool is selected.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/newman-opt.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>The available options are:</para>
		<para>For the main bond:</para>
		<variablelist> 
		  <varlistentry> <term>Bond length</term> 
			 <listitem> 
				<para>The default length of the new projected bond. This has no influence ion the drawing,
				but might be important when exporting to a 3d model.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Bond order</term> 
			 <listitem> 
				<para>The bond order.</para>
			 </listitem>
		  </varlistentry>
		</variablelist> 
		<para>And for each atom:</para>
		<variablelist> 
		  <varlistentry> <term>Bonds number</term> 
			 <listitem> 
				<para>Number of other bonds for the atom.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>First bond angle</term> 
			 <listitem> 
				<para>The direction of the first bond. Angles are measured
				counter clockwise from horizontal right.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Angle between bonds</term> 
			 <listitem> 
				<para>The angle between two consecutive bonds.</para>
			 </listitem>
		  </varlistentry>
		</variablelist> 
		<warning><para>This version of &app; does not correctly support Newman projections with eclipsed bonds.</para></warning>
	</sect1>
<!-- ============= Polymers ================ -->
	<sect1 id="gchempaint-polymers">
		<title>To Edit a Polymer Molecule</title>
		<para>To edit a polymer molecule, use the brackets tool:</para>
		<figure id="molecule-brackets"> 
		  <title>Brackets Tool</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Brackets Tool button.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/brackets.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>Drag the mouse so as to select the polymer unit and release the
		mouse button. You can then add a stoichiometric coefficient using the
		contextual menu for the brackets.</para>
		<para id="gchempaint-polymers-options">When the brackets tool
		is active, the toolbox looks like:</para>
		<figure id="molecule-brackets-window"> 
		  <title><application>&app;</application> toolbox when the brackets tool is selected</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the <application>&app;</application> toolbox when the brackets tool is selected.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/brackets-opt.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>The available options are:</para>
		<variablelist> 
		  <varlistentry> <term>Brackets type</term> 
			 <listitem> 
				<para>Choose between curved, square and curly brackets using the dropdown list.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Used brackets</term> 
			 <listitem> 
				<para>Choose whether to use opening, closing, or both brackets. For polymers both should be used.</para>
			 </listitem>
		  </varlistentry>
		</variablelist> 
	</sect1>

<!-- ============= Modify molecules ================ -->
	<sect1 id="gchempaint-lasso-tool">
		<title>To Modify a Molecule using the Lasso Tool</title>
		<figure id="molecule-lasso-tool"> 
		  <title>Lasso Tool</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Lasso Tool button.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/lasso.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>It is possible to select only part of a molecule using the lasso tool. You just need to
		click and drag the mouse around the objects you want to select. Selected objects
		will be highlighted. Actually, it is possible to select any objects collection using this tool.
		In some cases, the result of transforming a complex selection might have unwanted effects.
		</para>
		<para>When a collection of objects has been selected, you can translate the selection by clicking
		on one of the selectged objects and dragging with the mouse. When the objects are in an appropriate
		position, release the mouse.
		</para>
		<para>It is also possible to use one of the buttons in the toolbox:
		</para>
		<figure id="molecule-lasso-window"> 
		  <title><application>&app;</application> toolbox when the lasso tool is selected</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the <application>&app;</application> toolbox when the lasso tool is selected.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/lasso-opt.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>The property page of this tools contains three buttons:</para>
		<variablelist> 
		  <varlistentry><term>Horizontal flip button</term> 
			 <listitem> 
				<para>Use this button to <link linkend="gchempaint-rotate">flip</link> horizontally the current selection.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term>Vertical flip button</term> 
			 <listitem> 
				<para>Use this button to <link linkend="gchempaint-rotate">flip</link> vertically the current selection.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term>Rotate button</term> 
			 <listitem> 
				<para>When this toggle button is active, dragging the mouse over the
				selecton will <link linkend="gchempaint-rotate">rotate</link> it
				instead of moving it to a new position. The rotation center is the position
				of the object at the click position. For a bond, it is actually the bond center.</para>
			 </listitem>
		  </varlistentry>
		</variablelist> 
	</sect1>

<!-- ============= Merge molecules ================ -->
	<sect1 id="gchempaint-merge">
		<title>To Merge two Molecules</title>
		<para>To merge two molecules, you can add a bond betwwen two atoms, one from
		each molecule. The drawback is that this method will not align properly the two parts of your
		new molecule.</para>
		<para>Another and much better method is to use the Merge button:</para>
			<figure id="gchempaint-merge-tool"> 
			  <title>Merge Button</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the Merge Tool button.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/merge.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
			<para>Suppose you want to draw a naphtalene molecule starting from 
			two benzene molecules:</para>
			<informalfigure id="gchempaint-merge1"> 
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Two benzene molecules.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/merge1.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</informalfigure>
			<para>Move one of the molecules so that at least one atom from each
			molecule lies at the same place. These atoms must be identical (same element).
			In the examples, two atoms and a bond conincide:</para>
			<informalfigure id="gchempaint-merge2"> 
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>The two molecules after alignment.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/merge2.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</informalfigure>
			<para>Then, select the two molecules. The Merge button becomes sensitive. If
			you click on it, you obtain:</para>
			<informalfigure id="gchempaint-merge3"> 
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>The resulting naphtalene molecule.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/merge3.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</informalfigure>
		<warning><para>If one of the molecule has two or more atoms at the
		same position than an atom of the second molecule, the result is not
		easily preditable.</para></warning>
	</sect1>

	<sect1>
		<title>Using the Molecules contextual menu.</title>
		<figure id="gchempaint-mol-menu"> 
		  <title>Molecules contextual menu</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Molecule contextual menu.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/mol-menu.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>The available commands are:</para>
		<variablelist>
		  <varlistentry> <term>Open 3D model in</term> 
			 <listitem> 
				<para>This is a submenu containig items for opening the model in
				one of <ulink type="http" url="http://avogadro.openmolecules.net"><application>Avogadro</application></ulink>,
				<ulink type="http" url="http://www.uku.fi/~thassine/projects/ghemical/"><application>Ghemical</application></ulink>,
				or  <ulink type="help" url="ghelp:gchem3d-0.14"><application>GChem3D</application></ulink>.
				The actually present items correspond to the installed applications. If none
				is available, the menu will be hidden. When all are present, this gives:</para>
					<figure id="gchempaint-molecule-3dmenu"> 
					  <title>Export to 3D menu.</title>
					  <screenshot> 
							<mediaobject>
								<imageobject>
									<objectinfo> <abstract><para>Screenshot of the export to 3D menu.</para></abstract>
									</objectinfo> 
									<imagedata fileref="figures/mol-menu3d.png"/>
								</imageobject>
							</mediaobject>
						</screenshot>
					</figure>
				<para>The model is converted to 3D using <application>OpenBabel</application>. This might fail with some
				polycyclic molecules because of a 
				<ulink type="html" url="http://sourceforge.net/tracker/?func=detail&amp;aid=3187084&amp;group_id=40728&amp;atid=428740">bug</ulink> in <application>OpenBabel</application>.</para>
				<para>With the cyclohexane molecule, you get in <application>Ghemical</application>:</para>
					<figure id="gchempaint-ghemical"> 
					  <title>Cyclohexane ghemical view.</title>
					  <screenshot> 
							<mediaobject>
								<imageobject>
									<objectinfo> <abstract><para>Screenshot of the initial cyclohexane ghemical view.</para></abstract>
									</objectinfo> 
									<imagedata fileref="figures/ghemical.png"/>
								</imageobject>
							</mediaobject>
						</screenshot>
					</figure>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Find in databases</term> 
			 <listitem> 
				<para>This is another submenu containing a list of databases where the molecule
				might be searched for. This list can be extended by the user adding an entry to
				<filename>$HOME/.gchemutils/databases.xml</filename>. This file needs to have a
				<code>databases</code> root node, and each entry should look like the one for
				ChemSpider in the predefined databases:</para>
				<para><code language="xml">&lt;database&gt;&lt;name&gt;ChemSpider&lt;/name&gt;&lt;uri&gt;http://www.chemspider.com/InChIKey=%K&lt;/uri&gt;&lt;class&gt;molecule&lt;/class&gt;&lt;/database&gt;
				</code></para>
				<para>"<code>%K</code>" will be replaced by the InChiKey when querying. Other available
				codes are "<code>%I</code>" to use the InChI, and "<code>%S</code>" to use the
				canonical SMILES as generated by OpenBabel.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Generate InChI</term> 
			 <listitem> 
				<para>Generates the InChI for the molecule and displays it in a popup window.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Generate InChIKey</term> 
			 <listitem> 
				<para>Generates the InChIKey for the molecule and displays it in a popup window.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Generate SMILES</term> 
			 <listitem> 
				<para>Generates the canonical SMILES for the molecule and displays it in a popup window.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Open in Calculator</term> 
			 <listitem> 
				<para>Opens the chemical calculator <ulink type="help" url="ghelp:gchemcalc-0.14"><application>GChemCalc</application></ulink> with a copy of the molecule
				formula and performs the available calculations</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Select alignment item</term> 
			 <listitem> 
				<para>If clicked, the object which was at the position of
				the mouse cursor when the right button was clicked becomes
				the element taken into account for horizontal alignment. If
				it is an atom, its baseline will be aligned with the other objects
				baselines, and if it is a bond, the center of the bond will be
				used.</para>
			 </listitem>
		  </varlistentry>
		</variablelist> 
	</sect1>
</chapter>

<!-- ============= Other objects ===================== -->
<chapter id="gchempaint-other">
	<title>Other objects.</title>

<!-- ============= Add an arrow ================ -->
	<sect1 id="gchempaint-arrow">
		<title>To Add an Arrow</title>
		<para>To add an arrow, activate the appropriate tool.</para>
		<figure id="gchempaint-arrow-tool">
			<title>Arrow Tools buttons</title>
			<screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Arrow Tools buttons.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/arrows.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>Select the appropriate tool according to the type of arrow
		you want to add.</para>
		<para>When you click, a new horizontal arrow appears. You can move the
		mouse pointer to change it's orientation by steps of 5°. You can remove this
		restriction by pressing the Shift key. The length of the new bond is given
		by the value displayed in the toolbox, unless you press the Control key, in which
		case, the position of the mouse will be the end of the arrow.</para>
		<para>If you drag the mouse cursor to it's original position before
		releasing the button, the green arrow disappears and if you release the button
		without moving the mouse anymore, no arrow is added to the document.</para>
		<para>When an arrow tool (except the reversible rraction arrow tool) is
		selected, the tolbox looks like:</para>
		<figure id="gchempaint-reaction-arrow-opts"> 
		  <title><application>&app;</application> toolbox when an arrow tool is selected</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the <application>&app;</application> toolbox when an arrow tool is selected.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/arrow-opts.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>Only one option is available:</para>
		<variablelist> 
		  <varlistentry> <term>Arrow length</term> 
			 <listitem> 
				<para>The default length of a new arrow.</para>
			 </listitem>
		  </varlistentry>
		</variablelist> 
		<para>For reversible reaction arrows, the heads used are by default half-heads. It is possible to change
		the heads to full heads in the property box of the tool and even make your choice the default.</para>
		<para>The toolbox will look like:</para>
		<figure id="gchempaint-reaction-arrows-heads"> 
		  <title><application>&app;</application> toolbox when the reversible reaction arrow tool is selected</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the <application>&app;</application> toolbox when the reversible reaction arrow tool is selected.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/arrow-heads.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
	</sect1>


<!-- ============= Attach objects to reaction arrows ================ -->
	<sect1 id="gchempaint-reaction-prop">
		<title>To Attach an Object to a Reaction Arrow</title>
		<para>Objects such as text and molecules can be attached to reaction arrows to give more
		information about the reaction. In the current version of <application>&app;</application>, only one object can
		be attached to a given reaction arrow. Attaching the object to the arrow ensures
		that the object will be correctly aligned, and the arrow length is large enough.</para>
		<para>To attach an object to a reaction arrow, fiorst select the object.</para>
		<figure id="gchempaint-reaction-object1"> 
		  <title>Object selection.</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the object selection step.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/arrow-object1.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>Then right click on the reaction arrow to show the contextual menu, and
		choose <menuchoice><guimenuitem>Attach selection to arrow...</guimenuitem></menuchoice></para>
		<figure id="gchempaint-reaction-object2"> 
		  <title>Contextual menu.</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the arrow contextual menu.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/arrow-object2.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>A dialog box pops up where you can select a role for the object.</para>
		<figure id="gchempaint-reaction-object-dialog"> 
		  <title>Dialog box.</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the attached object dialog box.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/arrow-object-dlg.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>And things are done.</para>
		<figure id="gchempaint-reaction-object3"> 
		  <title>Attached object.</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the attached object.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/arrow-object3.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
	</sect1>

<!-- ============= Add or edit curved arrow ============== -->
	<sect1 id="gchempaint-curved-arrow">
		<title>To Add or Edit a Curved Arrow</title>
		<para>To add a curved arrow, activate the appropriate tool.</para>
		<figure id="gchempaint-curved-arrow-tool">
			<title>Arrow Tools buttons</title>
			<screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Curved Arrow Tools buttons.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/curved-arrow.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>Curved arrows are used to depict electrons position changes in reaction
		mechanisms. If the arrow head is a full head, the arrow symbolize the move of an
		electrons pair, while half-headed arrows represent single electron moves.
		Select the appropriate tool according to the type of a curved arrow
		you want to add.</para>
		<para>To add a curved arrow, go where you want the arrow to start, the mouse cursor
		should change to a drawing pencil. If not, then the framework does not allow
		an arrow at this position. The object owning the electron or electron pair should
		be highlighted. Then click and, if the new arrow does not end where you want or if no
		new arrow is displayed, drag the mouse to the target of the electron deplacement.
		When you see an arrow at the wanted position, release the mouse button.</para>
		<para>When possible, the arrow initial orientation is choosen according
		to the mouse cursor position relative to the source of the electrons.</para>
		<para>When the full headed curve arrow tool is selected, the toolbox looks
		like:</para>
		<figure id="gchempaint-curved-arrow-tool-opts">
			<title>Toolbox when the full headed curved arrow tool is selected</title>
			<screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Full Headed Curved Arrow Tool.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/curved-arrow-opts.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>Only one option is present:</para>
		<variablelist> 
		  <varlistentry> <term>End arrow at center of new bond</term> 
			 <listitem> 
				<para>When a new bond is created during a mechanism step, you can end the
				curved arrow either at the other atom position, or at the center of
				the future bond. The result of the two possibilities are displayed in
				the following figure:</para>
				<figure id="gchempaint-curved-arrow-ends">
					<title>Alternative positions.</title>
					<screenshot> 
						<mediaobject>
							<imageobject>
								<objectinfo> <abstract><para>Alternative positions of a curved arrow end.</para></abstract>
								</objectinfo> 
								<imagedata fileref="figures/curved-arrow-end.png"/>
							</imageobject>
						</mediaobject>
					</screenshot>
				</figure>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term><guibutton>Default</guibutton></term> 
			 <listitem> 
				<para>Clicking the <guibutton>Default</guibutton> button will make
				the current option the default.</para>
			 </listitem>
		  </varlistentry>
		</variablelist>
		<para>Half-headed arrows will always end near the center of the future bond, because
		a second electron should come from the other side.</para>
		<para>Curved arrows can be edited to some extents. Only the intermediate control points can
		be moved. In order to do that, select the appropriate tool, click on the arrow
		that you wish to edit, the control points will be displayed, drag the mouse until
		it reaches one of the control points. When you are there, the control point
		will follow any further mouse move. When done, release the mouse button.</para>
		<para>Curved arrows can be created inside a reaction or a mesomery. It is also possible
		to add the curved arrow to the molecule before creating the reaction or the mesomery.
		If you add a curved arrow between two molecules, and then create a reaction,
		the two molecules will be considered as only one reactant and no + sign will
		be added between them, and the molecules will not be realigned.</para>
	</sect1>

<!-- ============= Add or edit a reaction ================ -->
	<sect1 id="gchempaint-reaction">
		<title>To Add or Edit a Reaction</title>
		<para>To create a reaction, you must first draw the molecules and an arrow.</para>
		<para>Two tools are present to add an arrow (go to the section "<link linkend="gchempaint-arrow">To Add an Arrow</link>" for more information):</para>
		<figure id="gchempaint-reaction-arrows-tool"> 
		  <title>Reaction Arrows Tools</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Reaction Arrows Tools buttons.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/reaction-arrows.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>Use these tools to add the corresponding graphical objects where appropriate
		to represent a reaction.</para>
		<para>When you have the molecules and the arrow, you can create a reaction.
		As an example, if you want to represent the benzene hydrogenation reaction,
		you must first obtain something as:</para>
		<informalfigure id="gchempaint-reaction1"> 
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>The molecules and arrow before grouping.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/reaction1.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</informalfigure>
		<para>You must now select the molecules and click with the mouse right button.
		A popup menu appears which contains the appropriate item:</para>
		<informalfigure id="gchempaint-reaction2"> 
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Creating the reaction.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/reaction2.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</informalfigure>
		<para>Select the <guimenu>Create a new reaction</guimenu> item, you obtain:</para>
		<informalfigure id="gchempaint-reaction3"> 
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>The reaction.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/reaction3.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</informalfigure>
		<para>After the reaction has been created, you can add a stoichiometry coefficient.
		Click with the mouse right button on the appropriate reagent or product and 
		choose <menuchoice><guimenuitem>Add a stoichiometry coefficient</guimenuitem></menuchoice>
		in the popup menu.</para>
		<informalfigure id="gchempaint-reaction4"> 
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Adding a stoichiometry coefficient.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/reaction4.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</informalfigure>
		<para>Now, edit the stoichiometry coefficient. In the current version, <application>&app;</application> does not
		check what you type, but future versions might analyze and reject incorrect texts.</para>
		<informalfigure id="gchempaint-reaction5"> 
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Editing a stoichiometry coefficient.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/reaction5.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</informalfigure>
		<para>When inside a reaction, molecules and arrows cannot be selected
		indidually, except for operations available in the contextual menu.</para>
		<para>You can destroy the reaction by selecting the
		<menuchoice><guimenuitem>Destroy the reaction</guimenuitem></menuchoice>
		in the popup menu. The "+" signs and the stoichiometry coefficients
		will be deleted, and the molecules and arrows will be ungrouped.</para>
		<para>Reactions cannot be flipped or rotated.</para>
		<para>&app; also supports reactions with several steps and unsing any
		string to symbolize a molecule like the following samples:</para>
		<para>A linear reaction scheme.</para>
		<informalfigure id="gchempaint-multiple-reaction1"> 
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>A multiple steps reaction scheme.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/linear-scheme.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</informalfigure>
		<para>A cyclic reaction scheme.</para>
		<informalfigure id="gchempaint-multiple-reaction2"> 
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>A cyclic multiple steps reaction scheme.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/cyclic-scheme.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</informalfigure>
	</sect1>
<!-- ============= Add or edit a mesomery relationship ================ -->
	<sect1 id="gchempaint-mesomery">
		<title>To Add or Edit a Mesomery Relationship</title>
		<para>Mesomery is indicated by a double headed arrow. The appropriate tool to add this type of arrow
		is (go to the section "<link linkend="gchempaint-arrow">To Add an Arrow</link>" for more information):</para>
		<figure id="gchempaint-mesomery-arrow-tool"> 
		  <title>Mesomery Arrow Tool</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Mesomery Arrow Tool button.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/mesomery-arrow.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>Use this tool to draw a double headed arrow between two mesomeric stuctures.
		This version of <application>&app;</application> has an incomplete support for mesomery.
		The validity of what you draw is not checked.</para>
		<para>To build a mesomery relationship, first create all useful molecules and arrows.</para>
		<figure id="gchempaint-mesomery1"> 
		  <title>Creation of the molecules and arrows.</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Create the molecules and arrows.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/mesomery1.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>Then, select the appropriate objects, right click, and select
		<menuchoice><guimenuitem>Create a new mesomery relationship</guimenuitem></menuchoice></para>
		<figure id="gchempaint-mesomery2"> 
		  <title>Selection of the popup menu entry.</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Select the menu.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/mesomery2.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>If <application>&app;</application> is unable to build a mesomery relationship from the selected objects,
		an error message is displayed.</para>
		<para>The mesomery is created with a default object alignment. You can change
		how mesomers are aligned by selecting a bond or an atom with the
		<menuchoice><guimenuitem>Select alignment item</guimenuitem></menuchoice>
		menu entry as explained in the section
		<link linkend="gchempaint-group">To Group and/or Align Objects</link>.
		With this version of <application>&app;</application>, you must repeat the
		operation for each mesomer.</para>
		<figure id="gchempaint-mesomery3"> 
		  <title>Built mesomery relationship.</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>The mesomery relationship is built.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/mesomery3.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>You can destroy the mesomery relationship path by selecting the
		<menuchoice><guimenuitem>Destroy the mesomery relationship</guimenuitem></menuchoice>
		in the popup menu. The molecules and arrows will be ungrouped.</para>
		<para>Mesomery relationships cannot be flipped or rotated.</para>
	</sect1>
<!-- ============= Add or edit a retrosynthesis pathway ================ -->
	<sect1 id="gchempaint-retrosynthesis">
		<title>To Add or Edit a Retrosynthesis Pathway</title>
		<para>The appropriate tool to add a retrosynthesis arrow is
		(go to the section "<link linkend="gchempaint-arrow">To Add an Arrow</link>" for more information):</para>
		<figure id="gchempaint-retrosynthesis-arrow-tool"> 
		  <title>Retrosynthesis Arrow Tool</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Retrosynthesis Arrow Tool button.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/retrosynthesis.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>Use this tool to draw a retrosynthesis arrow between two steps of the pathway.</para>
		<para>To build a path, first create all useful molecules and arrows.</para>
		<figure id="gchempaint-retrosynthesis1"> 
		  <title>Creation of the molecules and arrows.</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Create the molecules and arrows.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/retrosynthesis1.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>Then, select the appropriate objects, right click, and select
		<menuchoice><guimenuitem>Create a new retrosynthesis path</guimenuitem></menuchoice></para>
		<figure id="gchempaint-retrosynthesis2"> 
		  <title>Selection of the popup menu entry.</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Select the menu.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/retrosynthesis2.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>If <application>&app;</application> is unable to build a retrosynthesis path from the selected objects,
		an error message is displayed.</para>
		<para>There are some limitations to what is supported currently :</para>
		<itemizedlist> 
		  <listitem><para>You cannot have more than one target molecule.</para>
		  </listitem>
		  <listitem><para>Cyclic paths are not allowed.</para>
		  </listitem>
		  <listitem><para>If a step leads to several precursors, you must use
		  one arrow for each.</para>
		  </listitem>
		</itemizedlist>
		<para>The path is created with a default object alignment. You can change
		how molecules are aligned by selecting a bond or an atom with the
		<menuchoice><guimenuitem>Select alignment item</guimenuitem></menuchoice>
		menu entry as explained in the section
		<link linkend="gchempaint-group">To Group and/or Align Objects</link></para>
		<figure id="gchempaint-retrosynthesis3"> 
		  <title>Built retrosynthesis path.</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>The retrosynthesis path is built.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/retrosynthesis3.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>In the sample, one of the vertical bonds of the cycle has been selected.</para>
		<figure id="gchempaint-retrosynthesis4"> 
		  <title>Custom aligned retrosynthesis path.</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>The retrosynthesis path after alignment.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/retrosynthesis4.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>You can destroy the retrosynthesis path by selecting the
		<menuchoice><guimenuitem>Destroy the retrosynthesis path</guimenuitem></menuchoice>
		in the popup menu. The molecules and arrows will be ungrouped.</para>
		<para>Retrosynthesis paths cannot be flipped or rotated.</para>
	</sect1>
<!-- ============= Add or edit text ================ -->
	<sect1 id="gchempaint-text">
		<title>To Add or Edit some Text</title>
		<para>To add or edit text, use the text tool:</para>
		<figure id="gchempaint-text-tool"> 
		  <title>Text tool</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the text tool button.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/text.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>When this tool is selected, you can select an existing text and edit it or add a new text
		by clicking on the background.</para>
		<para>The text tool property page looks like:</para>
		<figure id="gchempaint-text-tools-bar"> 
		  <title>Toolbox when the templates tool is selected</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the <application>&app;</application> toolbox when the text tool is selected.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/text-opt.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>You can decorate the text by changing the selection in
		the various widgets.</para>
		<para><application>&app;</application> also recognize some keyboard
		shortcuts specific to text edition. Some of these shortcuts are:</para>
		<variablelist> 
		  <varlistentry><term><guibutton>Ctrl+b</guibutton></term>
			 <listitem> 
				<para>Toggles between bold and normal text if current
				font family exists for both weights.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term><guibutton>Ctrl+i</guibutton></term>
			 <listitem> 
				<para>Toggles between italic and normal text if current
				font family exists for both styles.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term><guibutton>Ctrl+k</guibutton></term>
			 <listitem> 
				<para>Toggles between strikethrough and normal.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term><guibutton>Ctrl+u</guibutton></term>
			 <listitem> 
				<para>Toggles between single underscore and normal.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term><guibutton>Ctrl+^ or Ctrl++</guibutton></term>
			 <listitem> 
				<para>Toggles between superscript and normal. The size of
				the font will be reduced to two thirds of the original value and the position raised
				to the new font size.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term><guibutton>Ctrl+_ or Ctrl+=</guibutton></term>
			 <listitem> 
				<para>Toggles between subscript and normal.</para>
				<para>Toggles between superscript and normal. The size of
				the font will be reduced to two thirds of the original value and the position lowered
				to the half of the new font size.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry><term><guibutton>Ctrl+Space</guibutton></term>
			 <listitem> 
				<para>Restores default values according to the theme
				associated to the active document.</para>
			 </listitem>
		  </varlistentry>
		</variablelist> 
	</sect1>
<!-- ============= Add brackets ================ -->
	<sect1 id="gchempaint-brackets">
		<title>To Add Brackets around an Object</title>
		<para>To add brackets around an object, use this tool:</para>
		<figure id="object-brackets"> 
		  <title>Brackets Tool</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the Brackets Tool button.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/brackets.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>To add brackets around an object, choose the appropriate brackets
		using the toolbox, click and drag the mouse so as to select the whole object.
		When the mouse button is released the brackets appear around the object.</para>
		<para>The brackets don't modify the nature of the embedded object which can be
		used with the same logic as withiout the brackets. A bracketted molecule
		can be inserted inside a reaction, a retrosynthesis, or a mesomery relationship</para>
		<figure id="object-brackets-window"> 
		  <title><application>&app;</application> toolbox when the brackets tool is selected</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the <application>&app;</application> toolbox when the brackets tool is selected.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/brackets-opt.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>The available options are:</para>
		<variablelist> 
		  <varlistentry> <term>Brackets type</term> 
			 <listitem> 
				<para>Choose between curved, square and curly brackets using the dropdown list.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Used brackets</term> 
			 <listitem> 
				<para>Choose whether to use opening, closing, or both brackets. For polymers both should be used.</para>
			 </listitem>
		  </varlistentry>
		</variablelist> 
	</sect1>

 </chapter>

<!-- ============= Support ========================================= -->

 <chapter id="gchempaint-support">
    <title>Support.</title>
	<sect1 id="gchempaint-question">
		<title>To Ask a Question</title>
		<para>If you choose <menuchoice> <guimenu>Help</guimenu> <guimenuitem>Ask a question</guimenuitem></menuchoice>,
		your mail agent should pop up with a new message to the <ulink type="mail" url="mailto:gchempaint-main@nongnu.org">GChemPaint
		mailing list</ulink>.</para>
		<para>Another way to get some help is to connect on the <ulink url="irc://irc.gimp.net/gchemutils">#gchemutils channel</ulink>
		at irc.gimp.net and ask your question there (if you are not alone on the channel).</para>
	</sect1>
	<sect1 id="gchempaint-web">
		<title>To Find the Gnome Chemistry Utils on the Web.</title>
		<para>If you choose <menuchoice> <guimenu>Help</guimenu> <guimenuitem>Gnome Chemistry Utils on the web</guimenuitem></menuchoice>,
		the default web browser should pop up and display the main page for the Gnome Chemsitry Utils.</para>
		<para>The main page is
		<ulink type="http" url="http://gchempaint.nongnu.org">http://gchempaint.nongnu.org</ulink> and the project
		page at savannah <ulink type="http" url="http://savannah.nongnu.org/projects/gchempaint">http://savannah.nongnu.org/projects/gchempaint</ulink>.</para>
	</sect1>
	<sect1 id="gchempaint-bug">
		<title>To Report a Bug</title>
		<para>To report a bug, you must use the bug page for the Gnome Chemistry
		Utils at Savannah. You can access it by choosing
		<menuchoice> <guimenu>Help</guimenu> <guimenuitem>Report Bugs</guimenuitem></menuchoice>
		(hopefully you'll have only one at once to report).</para>
		<para>You can also type the bug report page address directly in
		the browser. The bug repository is at
		<ulink type="http" url="https://savannah.nongnu.org/bugs/?group=gchempaint">https://savannah.nongnu.org/bugs/?group=gchempaint</ulink></para>
	</sect1>
  </chapter>

<!-- ============= Application License ============================= -->

 <chapter id="license">
  <title>License</title>
  <para>
   This program is free software; you can redistribute it and/or
   modify it under the terms of the  <ulink type="help" url="ghelp:gpl">GNU
   General Public License</ulink> as
   published by the Free Software Foundation; 
   either version 3 of the License, or (at your option) any later
   version.
  </para>
  <para>
   This program is distributed in the hope that it will be useful, but
   WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   <citetitle>GNU General Public License</citetitle> for more details.
  </para>
  <para>
   A copy of the <citetitle>GNU General Public License</citetitle> is
   included as an appendix to the <citetitle>GNOME Users
   Guide</citetitle>.  You may also obtain a copy of the
   <citetitle>GNU General Public License</citetitle> from the Free
   Software Foundation by visiting <ulink type="http"
   url="http://www.fsf.org">their Web site</ulink> or by writing to
   <address>
    Free Software Foundation, Inc.
    <street>51 Franklin St</street> - Fifth Floor
    <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>
    <country>USA</country>
   </address>
  </para>
 </chapter>

</book>
