Subversion Repositories wimsdev

Rev

Rev 12963 | Blame | Compare with Previous | Last modification | View Log | RSS feed

  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <?xml-stylesheet type="text/xsl"
  3.         href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
  4. <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  5.         "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
  6.  
  7. <!-- Process this file with an XSLT processor, e.g. xsltproc:    -->
  8. <!-- `xsltproc \
  9.       -''-nonet \
  10.       -''-param man.charmap.use.subset "0" \
  11.       -''-param make.year.ranges "1" \
  12.       -''-param make.single.year.ranges "1" \
  13.       manpage.xml'                                               -->
  14.  
  15.  <!-- Fill in your name for FIRSTNAME and SURNAME.              -->
  16.  <!ENTITY dhfirstname "Georges">
  17.  <!ENTITY dhsurname   "Kaznadar">
  18.  <!ENTITY dhemail     "georgesk@debian.org">
  19.  <!-- dhusername could also be set to "&firstname; &surname;".  -->
  20.  <!ENTITY dhusername  "&dhfirstname; &dhsurname;">
  21.  
  22.  <!-- The version information can also be suppressed (just      -->
  23.  <!-- remove it or comment it out.                              -->
  24.  <!ENTITY dhrelease   "2.10">
  25.  
  26.  <!-- TITLE should be something like "User commands",           -->
  27.  <!-- "&dhpackage; command-line reference" or similar (see e.g. -->
  28.  <!-- http://www.tldp.org/HOWTO/Man-Page/q2.html). But limit    -->
  29.  <!-- the length to 30 chars.                                   -->
  30.  <!ENTITY dhtitle     "User Manuals">
  31.  
  32.  <!-- This is the application/package name.                     -->
  33.  <!ENTITY dhucpackage "CHEMEQ">
  34.  <!ENTITY dhpackage   "chemeq">
  35.  
  36.  <!-- If the application e.g. belongs to a package like X.org,  -->
  37.  <!-- this should be set to the package/suite name instead of   -->
  38.  <!-- dhpackage.                                                -->
  39.  <!ENTITY dhproduct   "&dhpackage;">
  40.  
  41.  <!-- SECTION should be 1-8, maybe w/ subsection other          -->
  42.  <!-- parameters are allowed: see man(7), man(1) and            -->
  43.  <!-- http://www.tldp.org/HOWTO/Man-Page/q2.html.               -->
  44.  <!ENTITY dhsection   "1">
  45.  
  46. ]>
  47.  
  48. <refentry>
  49.         <refentryinfo>
  50.                 <title>&dhtitle;</title>
  51.                 <!-- Better put a suite name instead of &dhpackage; into productname -->
  52.                 <productname>&dhproduct;</productname>
  53.                 <releaseinfo role="version">&dhrelease;</releaseinfo>
  54.                 <authorgroup>
  55.                         <author>
  56.                                 <firstname>Georges</firstname>
  57.                                 <surname>Khaznadar</surname>
  58.                                 <contrib>Wrote this manpage.</contrib>
  59.                                 <address>
  60.                                         <email>georgesk@debian.org</email>
  61.                                 </address>
  62.                         </author>
  63.                 <copyright>
  64.                         <year>2000-2013</year>
  65.                         <holder>Georges Khaznadar</holder>
  66.                 </copyright>
  67.                 <legalnotice>
  68.                         <para>Redistribution and use of this manpage in source and binary forms, with or without modification, are permitted under the terms of the GNU General Public Licenses, version 2</para>
  69.                         <para>THIS SOFTWARE IS PROVIDED BY THE AUTHOR &quot;AS IS&quot; AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</para>
  70.                 </legalnotice>
  71.                 </authorgroup>
  72.         </refentryinfo>
  73.         <refmeta>
  74.                 <refentrytitle>&dhucpackage;</refentrytitle>
  75.                 <manvolnum>&dhsection;</manvolnum>
  76.         </refmeta>
  77.         <refnamediv>
  78.                 <refname>&dhpackage;</refname>
  79.                 <refpurpose>Chemical Equation Parser and Renderer</refpurpose>
  80.         </refnamediv>
  81.         <refsynopsisdiv>
  82.                 <cmdsynopsis>
  83.                         <command>&dhpackage;</command>
  84.                         <arg choice="opt"><option>-M</option></arg>
  85.                         <arg choice="opt"><option>-m</option></arg>
  86.                         <arg choice="opt"><option>-l</option></arg>
  87.                         <arg choice="opt"><option>-c</option></arg>
  88.                         <arg choice="opt"><option>-w</option></arg>
  89.                         <arg choice="opt"><option>-C</option></arg>
  90.                         <arg choice="opt"><option>-e</option></arg>
  91.                         <arg choice="opt"><option>-s</option></arg>
  92.                         <arg choice="opt"><option>-n</option></arg>
  93.                         <arg choice="opt"><option>-W</option></arg>
  94.                 </cmdsynopsis>
  95.                 <cmdsynopsis>
  96.                         <command>&dhpackage;</command>
  97.                         <arg choice="opt"><option>-h</option></arg>
  98.                         <arg choice="opt"><option>-v</option></arg>
  99.                 </cmdsynopsis>
  100.         </refsynopsisdiv>
  101.         <refsect1 id="description">
  102.                 <title>DESCRIPTION</title>
  103.                 <para><command>&dhpackage;</command>
  104.                 is a chemical equation analyzer. It is a fast lexical
  105.                 and syntaxic analyser which helps to find out chemical
  106. informations embedded in source chemical equations. Data can be output
  107. in various sophisticated formats, depending on options.  'chemeq'
  108. defaults to 'chemeq -mlcwCn'. </para>
  109.         </refsect1>
  110.         <refsect1 id="options">
  111.                 <title>OPTIONS</title>
  112.                 <variablelist>
  113.                         <varlistentry>
  114.                                 <term><option>-M</option></term>
  115.                                 <listitem>
  116.                                         <para>
  117. Outputs al list of space separated molecular weights.</para>
  118.                                 </listitem>
  119.                         </varlistentry>
  120.                         <varlistentry>
  121.                                 <term><option>-m</option></term>
  122.                                 <listitem>
  123.                                         <para>
  124. Outputs a <option>m</option>inimal output. It allows  chemeq  to  be  idempotent,
  125. i.e. the command 'chemeq | chemeq' is equivalent to 'chemeq'.</para>
  126.                                 </listitem>
  127.                         </varlistentry>
  128.                         <varlistentry>
  129.                                 <term><option>-l</option></term>
  130.                                 <listitem>
  131.                                         <para>
  132. Outputs a <option>L</option>aTeX string representing the chemical equation.</para>
  133.                                 </listitem>
  134.                         </varlistentry>
  135.                         <varlistentry>
  136.                                 <term><option>-c</option></term>
  137.                                 <listitem>
  138.                                         <para>
  139. Outputs  a message giving informations about the Conservation of
  140.              elements and charges in the equation. 'OK' means that both
  141.               elements and electric charges are balanced.</para>
  142.                                 </listitem>
  143.                         </varlistentry>
  144.                         <varlistentry>
  145.                                 <term><option>-w</option></term>
  146.                                 <listitem>
  147.                                         <para>
  148. Outputs the LaTeX string representing the
  149. Gulder-<option>W</option>aage equation related to the input chemical
  150. equation, or the Nernst equation, if the input equation is a redox
  151. semi-equation.</para>
  152.                                 </listitem>
  153.                         </varlistentry>
  154.                         <varlistentry>
  155.                                 <term><option>-C</option></term>
  156.                                 <listitem>
  157.                                         <para>
  158. Outputs a detailed <option>C</option>ount of the molecules and atoms
  159. contained in each member of the chemical equation.  For example for
  160. the equation "H2_g + 1/2 O2_g --> H2O" it outputs: "H2_g|H:1*2, 1/2
  161. O2_g|O:1/2*2; H2O|H:1*2 O:1*1"</para>
  162.                                 </listitem>
  163.                         </varlistentry>
  164.                         <varlistentry>
  165.                                 <term><option>-e</option></term>
  166.                                 <listitem>
  167.                                         <para>
  168. Outputs a detailed count of the <option>E</option>lectrical charges.</para>
  169.                                 </listitem>
  170.                         </varlistentry>
  171.                         <varlistentry>
  172.                                 <term><option>-s</option></term>
  173.                                 <listitem>
  174.                                         <para>
  175. Outputs a list of the chemical <option>S</option>pecies.</para>
  176.                                 </listitem>
  177.                         </varlistentry>
  178.                         <varlistentry>
  179.                                 <term><option>-n</option></term>
  180.                                 <listitem>
  181.                                         <para>
  182. Outputs a <option>N</option>ormalized string accounting for the input
  183. equation.  Two chemical equations having the same normalized string
  184. are chemically equivalent, even if the molecules are scrambled around
  185. and the coefficient are not equal but proportionnal.</para>
  186.                                 </listitem>
  187.                         </varlistentry>
  188.                         <varlistentry>
  189.                                 <term><option>-W</option></term>
  190.                                 <listitem>
  191.                                         <para>
  192. Changes the behavior of the renderer for some versions of
  193. <option>W</option>ims : works around a bug whith the macro \rightarrow.</para>
  194.                                 </listitem>
  195.                         </varlistentry>
  196.                         <varlistentry>
  197.                                 <term><option>-h</option></term>
  198.                                 <listitem>
  199.                                         <para>
  200. Displays <option>H</option>elp.</para>
  201.                                 </listitem>
  202.                         </varlistentry>
  203.                         <varlistentry>
  204.                                 <term><option>-v</option></term>
  205.                                 <listitem>
  206.                                         <para>
  207. Displays the <option>V</option>ersion number</para>
  208.                                 </listitem>
  209.                         </varlistentry>
  210.                 </variablelist>
  211.         </refsect1>
  212.         <refsect1 id="environment">
  213.                 <title>ENVIRONMENT</title>
  214.                 <variablelist>
  215.                         <varlistentry>
  216.                         <term><envar>chemeq_input</envar></term>
  217.                                 <listitem>
  218.                                         <para>
  219. if set, this variables's value overrides the standard input. If this
  220. variable is not set, the variable w_chemeq_input is taken in account
  221. (useful for the WIMS server).</para>
  222.                                 </listitem>
  223.                         <term><envar>w_chemeq_input</envar></term>
  224.                                 <listitem>
  225.                                         <para>
  226. See above (useful for the WIMS server).</para>
  227.                                 </listitem>
  228.                         </varlistentry>
  229.                         <varlistentry>
  230.                         <term><envar>chemeq_option</envar></term>
  231.                                 <listitem>
  232.                                         <para>
  233. if set, this variable's value overrides the options.If this variable
  234. is not set, the variable w_chemeq_option is taken in account (useful
  235. for the WIMS server).</para>
  236.                                 </listitem>
  237.                         </varlistentry>
  238.                         <varlistentry>
  239.                         <term><envar>w_chemeq_option</envar></term>
  240.                                 <listitem>
  241.                                         <para>
  242. See above (useful for the WIMS server).</para>
  243.                                 </listitem>
  244.                         </varlistentry>
  245.                 </variablelist>
  246.         </refsect1>
  247.         <refsect1 id="examples">
  248.                 <title>EXAMPLES</title>
  249.                 <variablelist>
  250.                   <varlistentry>
  251.                     <term><option>echo "1/2 Cu^2+ + OH- ->  1/2Cu(OH)2s" | chemeq</option></term>
  252.                     <listitem><para>
  253. will display informations about the reaction of hydroxyde and Cu
  254. II ions.</para>
  255.                     </listitem>
  256.                   </varlistentry>
  257.                   <varlistentry>
  258.                     <term><option>echo "MnO4^- + 8H3O^+ + 5e- --> Mn^2+ + 12 H2O" | chemeq</option></term>
  259.                     <listitem><para>
  260. will display informations about the  reaction  of  reduction  of
  261.              permanganate ions in an acid environment.</para>
  262.                     </listitem>
  263.                   </varlistentry>
  264.                   <varlistentry>
  265.                     <term><option>echo "MnO4^- + 8H3O^+ + 5e- --> Mn^2+ + 12 H2O" | chemeq -w</option></term>
  266.                     <listitem><para>
  267. will  display the LaTeX format for the Nernst law related to the
  268.              reduction of permanganate ions in an acid environment.</para>
  269.                     </listitem>
  270.                   </varlistentry>
  271.                   <varlistentry>
  272.                     <term><option>echo "MnO4^- + 8H3O^+ + 5e- --> Mn^2+ + 8 H2O" | chemeq -c</option></term>
  273.                     <listitem><para>
  274. will highlight the lack of conservation  of  elements  H  and  O
  275.              (water molecules are not well balanced).</para>
  276.                     </listitem>
  277.                   </varlistentry>
  278.                 </variablelist>
  279.         </refsect1>
  280.         <refsect1 id="notes">
  281.                 <title>NOTES</title>
  282.                 <variablelist>
  283.                   <varlistentry>
  284.                     <term><option>syntax of ions</option></term>
  285.                     <listitem><para>
  286. allthough in some cases, shorter expressions are sucessfully parsed, it
  287.       is safer to consider that an "up arrow" (^)  must  be  put  before  the
  288.       charge symbols of an ion.  Examples : H3O^+, Fe(CN)6^4-, OH^-</para>
  289.                     </listitem>
  290.                   </varlistentry>
  291.                   <varlistentry>
  292.                     <term><option>Composing chemical equations</option></term>
  293.                     <listitem><para>
  294.       Two  operators are defined, # as an additive oprator and ~ (tilde) as a
  295.       substractive operator: they allow to compose several chemical equations
  296.     </para>
  297.     <para><option>
  298.       echo "MnO4^- + 8H3O^+ + 5e- --> Mn^2+ + 8 H2O ~ 5Fe^3+ + 5e- -> 5Fe^2+"
  299.       | chemeq</option>
  300.       </para>
  301.       <para>
  302.              will  display  the  pure redox equation from the first equation,
  303.              minus the second one. Electrons are simplified. So  it  will  be
  304.              equivalent to:
  305.       </para>
  306.       <para><option>
  307.       echo "MnO4^- + 8H3O^+ + 5Fe^2+--> Mn^2+ + 8 H2O + 5Fe^3+" | chemeq
  308.       </option>
  309.              which is their combination.</para>
  310.                     </listitem>
  311.                   </varlistentry>
  312.                   <varlistentry>
  313.                     <term><option>Mutiplying a chemical equation by one coefficient</option></term>
  314.                     <listitem><para>
  315. The  operator * permits to multiply a whole equation by one coefficient
  316.       which may be a fraction. Here is an example:
  317. </para><para><option>
  318.       echo "5 * Fe^3+ + e- -> Fe^2+" | chemeq
  319. </option></para><para>            will be equivalent to
  320. </para><para><option>
  321.       echo "5Fe^3+ + 5e- -> 5Fe^2+" | chemeq</option></para>
  322.                     </listitem>
  323.                   </varlistentry>
  324.                   <varlistentry>
  325.                     <term><option>Combining chemical equations, with coefficients</option></term>
  326.                     <listitem><para>
  327. The two previous techniques can be used at the same time, which enables
  328.       you to make more comlicated combinations, like this one:
  329. </para><para><option>
  330.       echo  "Fe^3+  +  e^-  ->  Fe^2+  (0.77 V) # Fe^2+ + 6CN^- -> Fe(CN)6^4-
  331.       (Kfa=1e24) ~ Fe^3+ + 6CN^- -> Fe(CN)6^3- (Kfb=1e31)" | chemeq
  332. </option></para><para>
  333.              which will work as expected, and yeld a good value for the stan‐
  334.              dard  potential  of  the redox couple of hexacyanoferrate II and
  335.              III ions.</para>
  336.                     </listitem>
  337.                   </varlistentry>
  338.                 </variablelist>
  339.         </refsect1>
  340.         <refsect1 id="bugs">
  341.           <title>KNOWN BUGS</title>
  342.           <para>
  343.       When not specified, chemical entities coming from  the  standard  input
  344.       are believed to be in aqueous solutions. Water is considered by default
  345.       as the main solvent. Only one liquid (aqueous) phase is currently taken
  346.       in  account.   All  solid  chemical entities are considered as parts of
  347.       separated phases.  Suffixes _s, _g and _aq can be used to  enforce  the
  348.       type of some chemical entities.
  349.  
  350.       There may be problemes when you write a standard potential with no
  351.       decimal dot. For example, the entry <option>Mn^2+ + 2e^-  ->  Mn_s  (-1  V)</option>  would
  352.       trigger  an error. Then write <option>Mn^2+ + 2e^- -> Mn_s (-1.0 V)</option> or the more
  353.       accurate value <option>Mn^2+ + 2e^- -> Mn_s (-1.18 V)</option>  and  there  will  be  no
  354.       error.
  355.           </para>
  356.         </refsect1>
  357. </refentry>
  358.  
  359.