504 lines
21 KiB
XML
504 lines
21 KiB
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 ends with .gramps
|
|
</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 .gpkg
|
|
</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>.
|
|
</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>.
|
|
</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 iso format,
|
|
the <filename>filename</filename>
|
|
is actually the name of directory the &app; database will be written
|
|
into. For grdb, gramps-xml, 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>Within 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 invocation
|
|
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, &app; 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, &app; 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 &app;)
|
|
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.gpkg</filename>
|
|
-i <filename>~/db3.gramps</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.gpkg</filename>
|
|
-f <replaceable>gramps-pkg</replaceable>
|
|
-i <filename>~/db3.gramps</filename>
|
|
-f <replaceable>gramps-xml</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 &app; to guess the format):</term>
|
|
<listitem>
|
|
<para><command>gramps
|
|
-i <filename>file1.ged</filename>
|
|
-i <filename>file2.gpkg</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.dpkg</filename>
|
|
-o <filename>~/new-package</filename>
|
|
-f <replaceable>gramps-pkg</replaceable>
|
|
><filename>outfile</filename>
|
|
2><filename>errfile</filename> </command>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>To import three databases and start interactive &app;
|
|
session with the result:</term>
|
|
<listitem>
|
|
<para><command>gramps
|
|
-i <filename>file1.ged</filename>
|
|
-i <filename>file2.gpkg</filename>
|
|
-i <filename>~/db3.gramps</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>
|