<?xml version="1.0" standalone="no"?>
<!DOCTYPE book PUBLIC "-//OASIS/DTD DocBookXML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"[
  <!ENTITY legal SYSTEM "legal.xml">
  <!ENTITY appversion "0.14.0">
  <!ENTITY manrevision "0.4">
  <!ENTITY date "July 2012">
  <!ENTITY app "GChem3d">
]>
<!-- 
      (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>2006-2012</year>
       <holder>Jean Br&#233;fort</holder>
     </copyright>

  <!-- translators: uncomment this and add lang=".." to the <book> 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.3</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.2</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.1</revnumber>
		  <date>February 2006</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>
	 </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/gchemutils" 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 display molecular structures.</para>
	</abstract>
  </bookinfo>  

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

<!-- ============= Introduction ============================= -->
 <preface id="gchem3d-intro">
    <title>Introduction</title>
	<para>The <application>&app;</application> application is a simple
	molecular structures visualizer.</para>

 </preface>

<!-- ============= Getting started ============================= -->
 <chapter id="gchem3d-getting-started">
    <title>Getting started</title>
	<sect1 id="gchem3d-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>Molecules Viewer</quote>. It might be listed either in the Education or
            Science category.</para>
    		</listitem>
    		</varlistentry>
    		<varlistentry>
    		<term>Command line</term>
    		<listitem>
    		<para>Type <command>gchem3d</command>, then press <keycap>Return</keycap>.</para>
    		</listitem>
    		</varlistentry>
    		</variablelist>
	</sect1>
	<sect1 id="gchem3d-when-you-start">
		<title>When You Start &app;</title>
		<para>When you start <application>&app;</application>, the following window is displayed:</para>
 			<figure id="gchem3d-main-window"> 
			  <title>&app; main window</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the <application>&app;</application> main window.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/main-window.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
	
		<para>The <application>&app;</application> 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>Display area</term> 
			 <listitem> 
				<para> The display area contains the contents of an opened file
				if any. </para>
			 </listitem>
		  </varlistentry>
		</variablelist>
	</sect1>
	<sect1 id="gchem3d-open-file">
		<title>To Open a File</title>
		<para>To open a file, choose 
		  <menuchoice> <guimenu>File</guimenu> <guimenuitem>Open</guimenuitem>
			 </menuchoice>
		  to display the <guilabel>Open File</guilabel> dialog. Select the file
		  that you want to open, then click <guibutton>OK</guibutton>. The file is
		  displayed in the <application>&app;</application> main window. </para>
		<para><application>&app;</application> can open files on a distant server.</para>
		<para><application>&app;</application> can open several file formats. Available formats are:</para>
		<itemizedlist> 
		  <listitem><para>ChemML files (*.cml)</para>
		  </listitem>
		  <listitem><para>MDL MOL files, MDL Structure Data files (*.mol;*.sd;*.sdf)</para>
		  </listitem>
		  <listitem><para>PDB files (*.pdb;*.ent)</para>
		  </listitem>
		  <listitem><para>XYZ Coordinate Format files (*.xyz)</para>
		  </listitem>
	  </itemizedlist>
	  <para>You can open multiple files in <application>&app;</application>.
	  The application displays each file in its own window.</para>
	  <para>Recently opened file appear in the <menuchoice> <guimenu>File</guimenu>
	   <guimenu>Open recent</guimenu></menuchoice> sub-menu.</para>
      <para>A molecule can also be loaded from it's InChI or a SMILES representation as described
      in the <link linkend="gchem3d-string-input">
		To Load a Molecule from a String</link> section.</para>
	</sect1>
	<sect1 id="gchem3d-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>gchem3d <replaceable>file1 file2 file3</replaceable></command></para>
	</sect1>
</chapter>

<chapter id="gchem3d-usage">
    <title>Usage</title>
	<sect1 id="gchem3d-save-as-image">
		<title>To Save the View as an Image</title>
		  <para>To open a file, choose 
		  <menuchoice> <guimenu>File</guimenu> <guimenuitem>Save as Image...</guimenuitem>
			 </menuchoice>
		  to display the <guilabel>Save as image</guilabel> dialog. Select a
		  file name and, if wanted, a file type and a size, then click
		  <guibutton>OK</guibutton>. Default image size is 300 pixels wide and 300
		  pixels high.</para>
		  <para>Supported types are VRML, Postscript, Encapsulated Postscript, PDF,
		  and all types that GdkPixbuf can export.
		  You'll find an exact list in the drop-down file type menu.</para>
		  <para>If no file type is specified, <application>&app;</application>
		  tries to determine the type from the file name. If it does not succeed,
		  the default type (VRML) will be used.</para>
		  <para>An appropriate extension will be added to the file name if none
		  is found.</para>
		  <para>PostScript and PDF files can also be obtained with the <link
 		  linkend="gchem3d-print">Print command</link>.</para>
	</sect1>
	<sect1 id="gchem3d-string-input">
		<title>To Load a molecule from an InChI or a SMILES</title>
        <para>To import a molecule from a string, choose 
		  <menuchoice> <guimenu>Tools</guimenu> <guimenuitem>Import molecule...
          </guimenuitem></menuchoice>. A dialog box pops up:</para>
			<figure id="gchem3d-smiles1"> 
			  <title>The string input dialog box.</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the empty
							string input dialog box.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/smiles1.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
			<para>You need to input a valid string such as this SMILES:</para>
			<figure id="gchem3d-smiles2"> 
			  <title>The string input dialog box with a SMILES inside.</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the
							string input dialog box with the SMILES for toluene.
							</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/smiles2.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
			<para>Please note that if you use an InChI as input, you must not skip
			the <quote>InChI=</quote> prefix.</para>
			<para>After activating the <guibutton>Apply</guibutton> button you get:</para>
			<figure id="gchem3d-smiles3"> 
			  <title>The 3D View.</title>
			  <screenshot> 
					<mediaobject>
						<imageobject>
							<objectinfo> <abstract><para>Screenshot of the 3d view
							corresponding to the input SIMLES.</para></abstract>
							</objectinfo> 
							<imagedata fileref="figures/smiles3.png"/>
						</imageobject>
					</mediaobject>
				</screenshot>
			</figure>
	</sect1>
	<sect1 id="gchem3d-tools-menu">
		<title>To Use the Tools Menu with a molecule.</title>
        <para>When a molecule is displayed, several menu items appear in the
        <guimenu>Tools menu</guimenu>:</para>
		<variablelist>
		  <varlistentry> <term>Open in GChemPaint</term> 
			 <listitem> 
				<para>Opens the 2D editor <ulink type="help" url="ghelp:gchempaint-0.14"><application>GChemPaint</application></ulink> with a copy of the molecule.
				The molecule has been converted to a 2D representation using the
				<ulink type="http" url="http://openbabel.sourceforge.net/"><application>OpenBabel</application></ulink> library.</para>
				<para>With the <emphasis>trans</emphasis>-1,2-dimethylcyclohexane molecule, you get:</para>
					<figure id="gchem3d-3dview"> 
					  <title>Initial view in GChem3D.</title>
					  <screenshot> 
							<mediaobject>
								<imageobject>
									<objectinfo> <abstract><para>Screenshot of the initial view in GChem3D.</para></abstract>
									</objectinfo> 
									<imagedata fileref="figures/gchempaint1.png"/>
								</imageobject>
							</mediaobject>
						</screenshot>
					</figure>
				<para>And after conversion in GChemPaint:</para>
					<figure id="gchem3d-2dview"> 
					  <title>The molecule in GChemPaint.</title>
					  <screenshot> 
							<mediaobject>
								<imageobject>
									<objectinfo> <abstract><para>Screenshot of the 2D-model of
									trans-1,2-cyclohexane molecule after conversion.</para></abstract>
									</objectinfo> 
									<imagedata fileref="figures/gchempaint2.png"/>
								</imageobject>
							</mediaobject>
						</screenshot>
					</figure>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Open in GChemCalc</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.
				With the same molecule as above, you get:</para>
					<figure id="gchem3d-calc"> 
					  <title>The molecule in GChemCalc.</title>
					  <screenshot> 
							<mediaobject>
								<imageobject>
									<objectinfo> <abstract><para>Screenshot of
									trans-1,2-cyclohexane molecule in GChemCalc.</para></abstract>
									</objectinfo> 
									<imagedata fileref="figures/gchemcalc.png"/>
								</imageobject>
							</mediaobject>
						</screenshot>
					</figure>
			 </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 SMILES for the molecule and displays it in a popup window.</para>
			 </listitem>
		  </varlistentry>
		  <varlistentry> <term>Search in an online database</term> 
			 <listitem> 
				<para>The molecule can be searched for in online databases, either
				predefined or user defined.</para>
				<para>To add custom databases, you need to create an xml file listing them.
				The file must be named .gchemutils/databases.xml in you home directory.</para>
				<para>Entries inside the file must be inside a databases top node, each entry being a database node
				with children name, uri, and class, like for the NIST webbook (which is predefined):</para>
				<para><literallayout>
  &lt;database&gt;
    &lt;name&gt;NIST webbook&lt;/name&gt;
    &lt;uri&gt;http://webbook.nist.gov/cgi/cbook.cgi?Name=%K&amp;Units=SI"&lt;/uri&gt;
    &lt;class&gt;molecule&lt;/class&gt;
  &lt;/database&gt;
				</literallayout></para>
				<para>where %K will be replaced by the InChIKey. Tou use the InChI, the
				code is %I and for the SMILES, %S.</para>
				<para>The class node is for future usages and must contain <quote>molecule</quote>.</para>
			 </listitem>
		  </varlistentry>
		</variablelist> 
	</sect1>
	<sect1 id="gchem3d-print">
		<title>To Print the View</title>
		  <para>To print a file, choose 
		  <menuchoice> <guimenu>File</guimenu> <guimenuitem>Print...</guimenuitem>
			 </menuchoice>.</para>
		<para><application>&app;</application> uses a 300 dpi resolution
		when printing.</para>
		<para>You might want to <link linkend="gchem3d-background">
		change the background color</link> before printing.</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="gchem3d-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="gchem3d-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="gchem3d-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>
	<sect1 id="gchem3d-mode">
		<title>To Change the Model Options</title>
		<para><application>&app;</application> is able to display a molecule
		using four model types: the ball and stick model, the compact
		model, the cylinders model, and the wireframe model. The first one is the default.
		Multiple bonds are displayed as such in the ball and stick model.</para>
		<figure id="gchem3d-ball-and-stick"> 
		  <title>The Balls and Sticks model.</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the balls and sticks model.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/ball-and-stick.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<figure id="gchem3d-spacefill"> 
		  <title>The Spacefill model.</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the spacefill model.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/spacefill.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<figure id="gchem3d-cylinders"> 
		  <title>The Cylinders model.</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the cylinders model.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/cylinders.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<figure id="gchem3d-wireframe"> 
		  <title>The Wireframe model.</title>
		  <screenshot> 
				<mediaobject>
					<imageobject>
						<objectinfo> <abstract><para>Screenshot of the wireframe model.</para></abstract>
						</objectinfo> 
						<imagedata fileref="figures/wireframe.png"/>
					</imageobject>
				</mediaobject>
			</screenshot>
		</figure>
		<para>To change the mode, choose either <menuchoice> <guimenu>View</guimenu> <guimenuitem>Balls and sticks</guimenuitem>
			 </menuchoice>, <menuchoice> <guimenu>View</guimenu><guimenuitem>Space filling</guimenuitem>
			 </menuchoice>, <menuchoice> <guimenu>View</guimenu><guimenuitem>Cylinders</guimenuitem>
			 </menuchoice>, or <menuchoice> <guimenu>View</guimenu><guimenuitem>Wireframe</guimenuitem>
			 </menuchoice>.</para>
		<para>The model can also be selected from the command line:
		<command>gchem3d --display3d=cylinders</command> or <command>gchem3d -d cylinders</command>
		will open <application>&app;</application> with the cylinders model active. The other models are entered as
		ball&amp;stick, spacefill, and wireframe.</para>
		<para>You can also change the orientation. Just click somewhere in
		the view and drag the mouse until you get the wanted orientation.</para>
	</sect1>
	<sect1 id="gchem3d-background">
		<title>To Change the Background Color</title>
		<para>To change the backgound color, choose 
		  <menuchoice> <guimenu>View</guimenu> <guimenuitem>Background color</guimenuitem>
			 </menuchoice> and select the appropriate color in the palette, or
			 choose a custom color.</para>
		<para>The background color can also be selected from the command line:
		<command>gchem3d --bgcolor=white</command> or <command>gchem3d -b white</command>
		will open <application>&app;</application> with a white background in windows. Recognized strings are black (the default),
		white, and #rrggbb where r, g, and b are hexadecimal digits.</para>
	</sect1>
	<sect1 id="gchem3d-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:gchemutils-main@nongnu.org">Gnome Chemistry Utils
		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="gchem3d-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://gchemutils.nongnu.org">http://gchemutils.nongnu.org</ulink> and the project
		page at savannah <ulink type="http" url="http://savannah.nongnu.org/projects/gchemutils">http://savannah.nongnu.org/projects/gchemutils</ulink>.</para>
	</sect1>
	<sect1 id="gchem3d-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=gchemutils">https://savannah.nongnu.org/bugs/?group=gchemutils</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>
