gramps/doc/gramps-manual/C/cmdline.xml

<appendix id="append-cmdline">

<!--
	  User Manual for Gramps - a GTK+/GNOME based genealogy program

	  Copyright (C) 2003-2005  Alexander Roitman

	  This document is free software; you can redistribute it and/or modify
	  it under the terms of the GNU General Public License as published by
	  the Free Software Foundation; either version 2 of the License, or
	  (at your option) any later version.

	  This document 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
	  GNU General Public License for more details.

	  You should have received a copy of the GNU General Public License
	  along with this program; if not, write to the Free Software
	  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-->

<!-- $Id$ -->

      <!-- =============== Appendices Subsection ================ -->
  <title>Command line reference</title>
  <para>This appendix provides the reference to the command line 
  capabilities available when launching &app; from the terminal. </para>
  
  <note><para>&app; was designed to be an interactive 
  program. Therefore it uses graphical display and cannot run from the 
  true non-graphical console. It would take an enormous amount of effort 
  to enable it to run in a text-only terminal. This is why the set of 
  command line options does not aim to completely get rid of dependency
  on the graphical display. Rather, it merely makes certain (typical) tasks 
  more convenient. It also allows one to execute these tasks from the scripts. 
  However, the graphical display must be accessible at all times! 
  </para></note>

  <tip><para>To summarize, the use of the command line options provides 
  non-interactive behavior, but does not get rid of graphical display
  dependency. Take it or leave it! 
  </para></tip>


      <sect1 id="cmdline-options">
      <title>Available options</title>

      <para>This section provides the reference list of all command line
      options available in &app;. If you want to know more than just
      a list of options, see next sections: <xref linkend="cmdline-operation"/>
      and <xref linkend="cmdline-examples"/>.
      </para>

          <sect2 id="cmdline-opt-format"><title>Format options</title>
          <para> The format of any file destined for opening, importing,
          or exporting can be specified with the 
          	<command>-f <replaceable>format</replaceable></command>
          option. The acceptable <replaceable>format</replaceable> values
          are listed below.</para>
          
          	<variablelist>

          	<varlistentry><term>grdb</term>
          	<listitem><para> &app; database. This format is available 
                for opening, import, and export. When not specified, it can be 
                guessed if the filename ends with .grdb 
                </para></listitem></varlistentry>

          	<varlistentry><term>gramps-xml</term>
          	<listitem><para> &app; XML database. This format is available 
                for opening, import, and export. When not specified, it can be 
                guessed if the filename represents a directory.
                </para></listitem></varlistentry>

          	<varlistentry><term>gedcom</term>
          	<listitem><para> GEDCOM file. This format is available 
                for opening, import, and export. When not specified, it can be 
                guessed if the filename ends with .ged
                </para></listitem></varlistentry>

          	<varlistentry><term>gramps-pkg</term>
          	<listitem><para> &app; package. This format is available 
                for import and export. When not specified, it can be 
                guessed if the filename ends with .tgz
                </para></listitem></varlistentry>

          	<varlistentry><term>geneweb</term>
          	<listitem><para> GeneWen file This format is available 
                for import and export. When not specified, it can be 
                guessed if the filename ends with gw
                </para></listitem></varlistentry>

          	<varlistentry><term>wft</term>
          	<listitem><para> Web Family Tree. This format is available 
                for export only. When not specified, it can be guessed 
                if the filename ends with .wft
                </para></listitem></varlistentry>

          	<varlistentry><term>iso</term>
          	<listitem><para> CD image. This format is available 
                for export only. It must always be specified explicitly. 
                </para></listitem></varlistentry>

          	</variablelist>

          </sect2>

          <sect2 id="cmdline-opt-open"><title>Opening options</title>
          <para>There are two ways to give &app; the name of the file to 
          be opened: </para>
          <itemizedlist>
          <listitem><para>supply bare file name</para></listitem>
          
          <listitem><para>use the
          <command>-O <filename>filename</filename></command> or
          <command>-open=<filename>filename</filename></command> option
          </para></listitem>

          </itemizedlist>

          <para>If the filename is given without any option flag, the attempt
          to open the file will be made, and then the interactive &app; session
          will be launched. 
          </para>
          
          <tip><para>If no option is given, just the file name, &app; will
          ignore the rest of the command line arguments. Use the -O flag
          to open the file and do something with the data.
          </para></tip>

          <para>The format can be specified with the 
          <command>-f <replaceable>format</replaceable></command> or 
          <command>--format=<replaceable>format</replaceable></command>
          option, immediately following the <filename>filename</filename>. 
          If not specified, the guess will be attempted based on 
          the <filename>filename</filename>. For gramps-xml 
          format, the <filename>filename</filename> is actually the 
          name of directory under which the gramps database resides. For 
          grdb and gedcom, 
          the <filename>filename</filename> is the name of the 
          corresponding file.
          </para>

          <tip><para>Only grdb, gramps-xml,
          and gedcom formats can be opened directly.
          For other formats, you will need to use the import option
          which will set up the empty database and then import data into it.
          </para></tip>
          
          <tip><para>Only a single file can be opened. If you need to combine
          data from several sources, you will need to use
          the import option.</para></tip>
                    
          </sect2>

          <sect2 id="cmdline-opt-import"><title>Import options</title>
          <para> The files destined for import can be specified with the 
          <command>-i <filename>filename</filename></command>
          or <command>--import=<filename>filename</filename></command>
          option. The format can be specified with the 
          <command>-f <replaceable>format</replaceable></command> or 
          <command>--format=<replaceable>format</replaceable></command>
          option, immediately following the <filename>filename</filename>. 
          If not specified, the guess will be attempted based on 
          the <filename>filename</filename>. For gramps-xml 
          format, the <filename>filename</filename> is actually the 
          name of directory under which the gramps database resides. For 
          grdb, gedcom, gramps-pkg, and geneweb,
          the <filename>filename</filename> is the name of the 
          corresponding file.
          </para>

          <tip><para>More than one file can be imported in one command.
          If this is the case, &app; will incorporate the data from 
          the next file into the database available at the moment.
          </para></tip>

          <para>When more than one input file is given, each has to be preceded
          by  <command>-i</command> flag. The files are imported in the 
          specified order, i.e. <command>
            -i <filename>file1</filename> 
            -i <filename>file2</filename>
          </command> and <command>
            -i <filename>file2</filename> 
            -i <filename>file1</filename>
          </command>
          might produce different gramps IDs in the resulting database.
          </para></sect2>

          <sect2 id="cmdline-opt-export"><title>Export options</title>
          <para> The files destined for export can be specified with the 
          <command>-o <filename>filename</filename></command> or
       	  <command>--output=<filename>filename</filename></command> 
          option. The format can be specified with the <command>-f</command> 
          option immediately following the <filename>filename</filename>. 
          If not specified, the guess will be attempted based on 
          the <filename>filename</filename>. For gramps-xml 
          and iso formats, the <filename>filename</filename> 
          is actually the name of directory the gramps database will be written 
          into. For grdb, gedcom, wft, geneweb,
          and gramps-pkg, the <filename>filename</filename> 
          is the name of the resulting file.
          </para>

          <tip><para>More than one file can be exported in one command.
          If this is the case, &app; will attempt to write several files
          using the data from the database available at the moment.
          </para></tip>

          <para> When more than one output file is given, each has to be 
          preceded by <command>-o</command> flag. The files are written one 
          by one, in the specified order.
          </para></sect2>

          <sect2 id="cmdline-opt-action"><title>Action options</title>
          <para> The action to perform on the imported data can be 
          specified with the 
          <command>-a <replaceable>action</replaceable></command> or
          <command>--action=<replaceable>action</replaceable></command>
          option. This is done after all imports are successfully completed. 
          </para>
          
          <para>Currently available actions are:</para>
          
          <variablelist>
          
          <varlistentry><term>summary</term>
          <listitem><para>This action is the same as 
          <menuchoice><guimenu>Reports</guimenu><guisubmenu>View</guisubmenu>
	      <guimenuitem>Summary</guimenuitem></menuchoice>
          </para></listitem></varlistentry>
      
          
          <varlistentry><term>check</term>
          <listitem><para>This action is the same as 
          <menuchoice><guimenu>Tools</guimenu>
          <guisubmenu>Database Processing</guisubmenu>
          <guimenuitem>Check and Repair</guimenuitem></menuchoice>.
          </para> </listitem> </varlistentry>

          <varlistentry><term>report</term>
          <listitem><para>This action allows producing reports
          from the command line. As reports generally have many options
          of their own, this action should be followed by the report option
          string. The string is given using the  
          <command>-p <replaceable>option_string</replaceable></command> or
          <command>--options=<replaceable>option_string</replaceable></command>
          option.        
          </para>
          
          <tip><para>
          The report option string should satisfy the following conditions:
          </para>
          
          <itemizedlist>
          
          <listitem><para>It must not contain any spaces. If some arguments
          need to include spaces, the string should be enclosed with 
          quotation marks.
          </para></listitem>
          
          <listitem><para>Option string must list pairs of option names
          and values. 
          </para></listitem>

          <listitem><para>Withing a pair, option name and value must be
          separated by the equal sign.
          </para></listitem>

          <listitem><para>Different pairs must be separated by commas.
          </para></listitem>

          </itemizedlist>
          </tip>
          
          
          <para>Most of the report options are specific for every report.
          However, there some common options.
          </para>

            <variablelist>         
          
            <varlistentry><term>name=report_name</term>
            <listitem> <para>
            This mandatory option determines which report will be 
            generated. If the supplied report_name does not correspond
            to any available report, the error message will be printed
            followed by the list of available reports.
            </para>
            </listitem> </varlistentry>

            <varlistentry><term>show=all</term>
            <listitem> <para>
            This will produce the list of names for all options available for
            a given report.
            </para>
            </listitem> </varlistentry>

            <varlistentry><term>show=option_name</term>
            <listitem> <para>
            This will print the description of the functionality supplied
            by the option_name, as well as what are the acceptable types
            and values for this option.
            </para>
            </listitem> </varlistentry>

            </variablelist>         

          <para>
          Use the above options to find out everything about a given report.
          </para>
          
          <tip><para>
          If an option is not supplied, the last used value will be used.
          If this report has never been generated before, then the 
          value from last generated report will be used when applicable.
          Otherwise, the default value will be used.
          </para></tip>

          </listitem> </varlistentry>

          </variablelist>

          <para>When more than one output action is given, each has to be 
          preceded by <command>-a</command> flag. The actions are performed 
          one by one, in the specified order.
          </para></sect2>

      </sect1>


      <sect1 id="cmdline-operation">
      <title>Operation</title>
      
       <itemizedlist>
       
       <listitem>
       <para>If the first argument on the command line does not start
       with dash (i.e. no flag), &app; will attempt to open the file
       with the name given by the first argument and start interactive
       session, ignoring the rest of the command line arguments.
       </para></listitem>
       
       <listitem>
       <para>If the <command>-O</command> flag is given, then &app; will
       try opening the
       supplied file name and then work with that data, as instructed by
       the further command line parameters.
       </para>
       
       <note><para>Only one file can be opened in a single invokation
       of &app;. If you need to get data from multiple sources, use
       the importing options by using <command>-i</command> flag.
       </para></note>
       </listitem>

       <listitem>
       <para>With or without the <command>-O</command> flag, there could
       be multiple imports, exports, and actions specified further on
       the command line by using <command>-i</command>, 
       <command>-o</command>, and <command>-a</command> flags.
       </para></listitem>
       
       <listitem>
       <para>The order of <command>-i</command>, <command>-o</command>, 
       or <command>-a</command> options with respect to each does not matter. 
       The actual execution order always is: all imports (if any) -> all 
       exports (if any) -> all actions (if any).</para>
       
       <note><para>But opening must always be first!</para></note>
       </listitem>
       
       <listitem>                                                                         
       <para>If no <command>-O</command> or <command>-i</command> 
       option is given, gramps will launch 
       its main window and start the usual interactive session with the empty 
       database, since there is no data to process, anyway.
       </para></listitem>
                                                                                
       <listitem>                                                                       
       <para>If no <command>-o</command> or <command>-a</command> options 
       are given, gramps will launch its main window and start the usual 
       interactive session with the database resulted from opening 
       and all imports (if any). This database resides in the  
       <filename>import_db.grdb</filename> file under the
       <filename>~/.gramps/import/</filename> directory.
       </para></listitem>
       
       <listitem>                                                                       
       <para>Any errors encountered during import, export, or action, will 
       be either dumped to stdout (if these are exceptions handled by gramps) 
       or or to stderr (if these are not handled). Use usual shell redirections 
       of stdout and stderr to save messages and errors in files.
       </para></listitem>
       
       </itemizedlist>

      </sect1>

      <sect1 id="cmdline-examples">
      <title>Examples</title>
        
        <variablelist>
        
        <varlistentry>
        <term>To import four databases (whose formats can be  determined from  
        their names) and then check the resulting database for errors, one may 
        type:</term>
        
        <listitem>
        <para><command>gramps 
            -i<filename>file1.ged</filename>
            -i <filename>file2.tgz</filename>
            -i <filename>~/db3</filename>
            -i <filename>file4.wft</filename>
            -a <filename>check</filename></command>
        </para> </listitem></varlistentry>
        
        <varlistentry>
        <term>To explicitly specify the formats in the above  example, append 
        filenames with appropriate <command>-f</command> options:</term>
        <listitem>
        <para><command>gramps 
            -i <filename>file1.ged</filename> 
            -f <replaceable>gedcom</replaceable> 
            -i <filename>file2.tgz</filename> 
            -f <replaceable>gramps-pkg</replaceable> 
            -i <filename>~/db3</filename> 
            -f <replaceable>gramps</replaceable> 
            -i <filename>file4.wft</filename> 
            -f <replaceable>wft</replaceable> 
            -a <replaceable>check</replaceable></command>
        </para></listitem>
        </varlistentry>

        <varlistentry>
       <term>To record the database resulting from all imports, supply 
       <command>-o</command> flag (use <command>-f</command>
       if the filename does not allow gramps to guess the format):</term>
       <listitem>
        <para><command>gramps 
            -i <filename>file1.ged</filename> 
            -i <filename>file2.tgz</filename> 
            -o <filename>~/new-package</filename> 
            -f <replaceable>gramps-pkg</replaceable></command> 
        </para></listitem>
        </varlistentry>
                                                                                
        <varlistentry>
       <term>To save any error messages of the above example into files
       <filename>outfile</filename> and 
       <filename>errfile</filename>, run:</term>
        <listitem>
        <para><command>gramps 
            -i <filename>file1.ged</filename> 
            -i <filename>file2.tgz</filename> 
            -o <filename>~/new-package</filename> 
            -f <replaceable>gramps-pkg</replaceable> 
        &gt;<filename>outfile</filename> 
        2&gt;<filename>errfile</filename> </command>
        </para></listitem>
        </varlistentry>

        <varlistentry>
       <term>To import three databases and start interactive gramps 
       session with the result:</term>
       <listitem>
        <para><command>gramps 
            -i <filename>file1.ged</filename> 
            -i <filename>file2.tgz</filename> 
            -i <filename>~/db3</filename>
        </command>
        </para> </listitem>
       </varlistentry>
                                                         
         <varlistentry>
       <term>To open a database and, based on that data, generate timeline
       report in PDF format putting the output into the
       <filename>my_timeline.pdf</filename> file:</term>
       <listitem>
        <para><command>gramps 
            -O <filename>file.grdb</filename> 
            -a <replaceable>report</replaceable> 
            -p <replaceable>name=timeline,off=pdf,of=my_timeline.pdf</replaceable>
        </command> 
        </para> 
        
        <tip><para>Use the <replaceable>name=timeline,show=all</replaceable> 
        to find out about all available options for the timeline report. To
        find out details of a particular option, use
        <replaceable>show=option_name</replaceable>,
        e.g. <replaceable>name=timeline,show=off</replaceable> 
        string.</para>
        
        <para>To learn about available report names, use
        <replaceable>name=show</replaceable> string.
        </para>
        </tip>

        </listitem>
       </varlistentry>

       <varlistentry>
       <term>Finally, to start normal interactive session type:</term>
       <listitem><para> <command>gramps </command></para></listitem>
              </varlistentry>
                                                                          
        </variablelist>

      </sect1>

</appendix>