Cyclone-Team/gramps
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve syntax of English manpage

Browse Source
This commit is contained in:
Anthony J. Bentley 2020-04-03 01:29:28 -06:00 committed by Nick Hall
parent 4039427e80
commit 31175616c1
1 changed files with 258 additions and 252 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

430
data/man/en.rst
View File

@ -1,269 +1,275 @@
English gramps
======= ======
gramps(1) @VERSION@ gramps(1) -----------------------------------------------------------------
Genealogical Research and Analysis Management Programming System.
-----------------------------------------------------------------
:Manual section: 1
:Manual group: @VERSION@
########
SYNOPSIS
########
**NAME** **gramps**
gramps - Genealogical Research and Analysis Management Programming Sys‐ \ [\ **-?** | **--help**]
tem. \ [\ **--usage**]
\ [\ **--version**]
\ [\ **-l**]
\ [\ **-L**]
\ [\ **-u** | **--force-unlock**]
\ [\ **-O** | **--open**\ =\ *DATABASE* [\ **-f** | **--format**\ =\ *FORMAT*]]
\ [\ **-i** | **--import**\ =\ *FILE* [\ **-f** | **--format**\ =\ *FORMAT*]]
\ [\ **--remove**\ =\ *FAMILY_TREE_PATTERN*]
\ [\ **-e** | **--export**\ =\ *FILE* [**-f** | **--format**\ =\ *FORMAT*]]
\ [\ **-a** | **--action**\ =\ *ACTION*]
\ [\ **-p** | **--options**\ =\ *OPTION-STRING*]]
\ [\ *FILE*]
\ [\ **--version**]
###########
DESCRIPTION
###########
**SYNOPSIS** Gramps is a Free/OpenSource genealogy program.
**gramps** [**-?** | **--help**] [**--usage**] [**--version**] It is written in Python, using the GTK+/GNOME interface.
[**-l**] [**-L**] [**-u** | **--force-unlock**] [**-O** | **--open=** *DATABASE* Gramps should seem familiar to anyone who has used other genealogy programs
[**-f** | **--format=** *FORMAT*] [**-i** | **--import=** *FILE* before such as Family Tree Maker (TM), Personal Ancestral Files (TM),
[**-f** | **--format=** *FORMAT*]] [**--remove=** *FAMILY_TREE_PATTERN*] or the GNU Geneweb.
[**-e** | **--export=** *FILE* [**-f** | **--format=** *FORMAT*]] It supports importing of the ever popular GEDCOM format which is used world wide
[**-a** | **--action=** *ACTION*] [*-p* | **--options=** *OPTION‐ by almost all other genealogy software.
STRING*]] [*FILE*] [**--version**]
#######
OPTIONS
#######
**DESCRIPTION** **gramps** *FILE*
Gramps is a Free/OpenSource genealogy program. It is written in Python, When *FILE* is given (without any flags) as a family tree name or as a
using the GTK+/GNOME interface. Gramps should seem familiar to anyone family tree database directory, then it is opened and an interactive
who has used other genealogy programs before such as Family Tree Maker session is started.
(TM), Personal Ancestral Files (TM), or the GNU Geneweb. It supports If *FILE* is a file format understood by Gramps, an empty family tree is
importing of the ever popular GEDCOM format which is used world wide by created whose name is based on the *FILE* name and the data is imported
almost all other genealogy software. into it.
The rest of the options is ignored.
This way of launching is suitable for using gramps as a handler for
genealogical data in e.g. web browsers.
This invocation can accept any data format native to gramps, see below.
**-f**, **--format**\ =\ *FORMAT*
Explicitly specify format of *FILE* given by preceding **-i**, or **-e**
option.
If the **-f** option is not given for any *FILE*, the format of that file
is guessed according to its extension or MIME-type.
**OPTIONS** Formats available for export are **gramps-xml** (guessed if *FILE* ends
**gramps** *FILE* with `.gramps`), **gedcom** (guessed if *FILE* ends with `.ged`), or any
When *FILE* is given (without any flags) as a family tree name or file export available through the Gramps plugin system.
as a family tree database directory, then it is opened and an
interactive session is started. If *FILE* is a file format under‐
stood by Gramps, an empty family tree is created whose name is
based on the *FILE* name and the data is imported into it. The
rest of the options is ignored. This way of launching is suit‐
able for using gramps as a handler for genealogical data in e.g.
web browsers. This invocation can accept any data format native
to gramps, see below.
Formats available for import are **gramps-xml**, **gedcom**, **gramps-pkg**
(guessed if *FILE* ends with `.gpkg`), and **geneweb** (guessed if *FILE*
ends with `.gw`).
**-f** , **--format=** *FORMAT* Formats available for export are **gramps-xml**, **gedcom**,
Explicitly specify format of *FILE* given by preceding **-i** , **gramps-pkg**, **wft** (guessed if *FILE* ends with `.wft`),
or **-e** option. If the **-f** option is not given for any
*FILE* , the format of that file is guessed according to its extension
or MIME-type.
Formats available for export are **gramps-xml** (guessed if *FILE*
ends with **.gramps** ), **gedcom** (guessed if *FILE* ends with
**.ged** ), or any file export available through the Gramps plugin
system.
Formats available for import are **gramps-xml** , **gedcom** ,
**gramps-pkg** (guessed if *FILE* ends with **.gpkg** ),
and **geneweb** (guessed if *FILE* ends with **.gw** ).
Formats available for export are **gramps-xml** , **gedcom** ,
**gramps-pkg** , **wft** (guessed if *FILE* ends with **.wft** ),
**geneweb**. **geneweb**.
**-l**
**-l**
Print a list of known family trees. Print a list of known family trees.
**-L**
**-L**
Print a detailed list of known family trees. Print a detailed list of known family trees.
**-u**, **--force-unlock**
**-u** , **--force-unlock**
Unlock a locked database. Unlock a locked database.
**-O**, **--open**\ =\ *DATABASE*
Open *DATABASE* which must be an existing database directory or existing
family tree name.
If no action, import or export options are given on the command line then
an interactive session is started using that database.
**-O** , **--open=** *DATABASE* **-i**, **--import**\ =\ *FILE*
Open *DATABASE* which must be an existing database directory or Import data from *FILE*.
existing family tree name. If no action, import or export If you haven't specified a database, then an empty database is created for
options are given on the command line then an interactive ses‐ you called Family Tree *x* (where *x* is an incrementing number).
sion is started using that database.
When more than one input file is given,
**-i** , **--import=** *FILE* each has to be preceded by **-i** flag.
Import data from *FILE* . If you haven't specified a database, then The files are imported in the specified order, i.e.
an empty database is created for you called Family Tree x **-i** *FILE1* **-i** *FILE2*
(where x is an incrementing number). and
**-i** *FILE2* **-i** *FILE1*
When more than one input file is given, each has to be preceded
by **-i** flag. The files are imported in the specified order, i.e.
**-i** *FILE1* **-i** *FILE2* and **-i** *FILE2* **-i** *FILE1*
might produce different gramps IDs in the resulting database. might produce different gramps IDs in the resulting database.
**-e**, **--export**\ =\ *FILE*
Export data into *FILE*.
For **gramps-xml**, **gedcom**, **wft**, **gramps-pkg**, and **geneweb**,
the *FILE* is the name of the resulting file.
**-e** , **--export=** *FILE* When more than one output file is given,
Export data into *FILE* . For **gramps-xml** , **gedcom** each has to be preceded by **-e** flag.
, **wft** , **gramps-pkg** , and **geneweb** , the *FILE* is the The files are written one by one, in the specified order.
name of the resulting file.
When more than one output file is given, each has to be preceded **-a**, **--action**\ =\ *ACTION*
by **-e** flag. The files are written one by one, in the specified order. Perform *ACTION* on the imported data.
This is done after all imports are successfully completed.
Currently available actions are **summary** (same as
Reports->View->Summary), **check** (same as Tools->Database
Processing->Check and Repair), **report** (generates report), and tool
(runs a plugin tool).
Both **report** and **tool** need the *OPTION-STRING* supplied by the
**-p** flag).
The *OPTION-STRING* should satisfy the following conditions:
**-a** , **--action=** *ACTION* It must not contain any spaces.
Perform *ACTION* on the imported data. This is done after all If some arguments need to include spaces, the string should be enclosed
imports are successfully completed. Currently available actions with quotation marks, i.e., follow the shell syntax.
are **summary** (same as Reports->View->Summary), **check** (same as Option string is a list of pairs with name and value (separated by the
Tools->Database Processing->Check and Repair), **report** (generates equality sign).
report), and tool (runs a plugin tool). Both **report** and **tool**
need the *OPTIONSTRING* supplied by the **-p** flag).
The *OPTIONSTRING* should satisfy the following conditions:
It must not contain any spaces. If some arguments need to
include spaces, the string should be enclosed with quotation
marks, i.e., follow the shell syntax. Option string is a list
of pairs with name and value (separated by the equality sign).
The name and value pairs must be separated by commas. The name and value pairs must be separated by commas.
Most of the report or tools options are specific for each report Most of the report or tools options are specific for each report or tool.
or tool. However, there are some common options. However, there are some common options.
**name=name** **name**\ =\ *name*
This mandatory option determines which report or tool will be This mandatory option determines which report or tool will be run.
run. If the supplied name does not correspond to any available If the supplied *name* does not correspond to any available report or
report or tool, an error message will be printed followed by the tool, an error message will be printed followed by the list of
list of available reports or tools (depending on the *ACTION* ). available reports or tools (depending on the *ACTION*).
**show=all** **show**\ =\ **all**
This will produce the list of names for all options available This will produce the list of names for all options available for a
for a given report or tool. given report or tool.
**show=optionname** **show**\ =\ *optionname*
This will print the description of the functionality supplied by This will print the description of the functionality supplied by
*optionname*, as well as what are the acceptable types and values *optionname*, as well as what are the acceptable types and values for
for this option. this option.
Use the above options to find out everything about a given
report.
Use the above options to find out everything about a given report.
When more than one output action is given, each has to be preceded by When more than one output action is given, each has to be preceded by
**-a** flag. The actions are performed one by one, in the specified order. **-a** flag.
The actions are performed one by one, in the specified order.
**-d**, **--debug**\ =\ *LOGGER_NAME*
Enables debug logs for development and testing.
Look at the source code for details.
**-d** , **--debug=** *LOGGER_NAME* **--version**
Enables debug logs for development and testing. Look at the Prints the version number of gramps and then exits.
source code for details
**--version** #########
Prints the version number of gramps and then exits OPERATION
#########
If the first argument on the command line does not start with dash (i.e. no
flag), gramps 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.
If the **-O** flag is given, then gramps will try opening the supplied database
and then work with that data, as instructed by the further command line
parameters.
With or without the **-O** flag, there could be multiple imports, exports, and
actions specified further on the command line by using **-i**, **-e**, and
**-a** flags.
**Operation** The order of **-i**, **-e**, or **-a** options does not matter.
If the first argument on the command line does not start with dash The actual order always is:
(i.e. no flag), gramps will attempt to open the file with the name all imports (if any) -> all actions (if any) -> all exports (if any).
given by the first argument and start interactive session, ignoring the But opening must always be first!
rest of the command line arguments.
If no **-O** or **-i** 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.
If the **-O** flag is given, then gramps will try opening the supplied If no **-e** or **-a** options are given,
database and then work with that data, as instructed by the further gramps will launch its main window and start the usual interactive session with
command line parameters. the database resulted from all imports.
This database resides in the *import_db.grdb* under *~/.gramps/import*
directory.
The error encountered during import, export, or action,
will be either dumped to *stdout* (if these are exceptions handled by gramps)
or to *stderr* (if these are not handled).
Use usual shell redirections of *stdout* and *stderr* to save messages and
errors in files.
With or without the **-O** flag, there could be multiple imports, exports, ########
and actions specified further on the command line by using **-i** , EXAMPLES
**-e** , and **-a** flags. ########
To open an existing family tree and import an xml file into it, one may type::
The order of **-i** , **-e** , or **-a** options does not matter. The actual order gramps -O 'My Family Tree' -i ~/db3.gramps
always is: all imports (if any) -> all actions (if any) -> all exports
(if any). But opening must always be first!
The above changes the opened family tree, to do the same, but import both in a
temporary family tree and start an interactive session, one may type::
If no **-O** or **-i** option is given, gramps will launch its main window and gramps -i 'My Family Tree' -i ~/db3.gramps
start the usual interactive session with the empty database, since
there is no data to process, anyway.
To import four databases (whose formats can be determined from their names) and
then check the resulting database for errors, one may type::
If no **-e** or **-a** options are given, gramps will launch its main window gramps -i file1.ged -i file2.tgz -i ~/db3.gramps -i file4.wft -a check
and start the usual interactive session with the database resulted from
all imports. This database resides in the **import_db.grdb** under
**~/.gramps/import** directory.
To explicitly specify the formats in the above example, append filenames with
appropriate **-f** options::
The error encountered during import, export, or action, will be either gramps -i file1.ged -f gedcom -i file2.tgz -f gramps-pkg \
dumped to stdout (if these are exceptions handled by gramps) or to -i ~/db3.gramps -f gramps-xml -i file4.wft -f wft -a check
*stderr* (if these are not handled). Use usual shell redirections of
*stdout* and *stderr* to save messages and errors in files.
To record the database resulting from all imports, supply **-e** flag (use
**-f** if the filename does not allow gramps to guess the format)::
**EXAMPLES** gramps -i file1.ged -i file2.tgz -e ~/new-package -f gramps-pkg
To open an existing family tree and import an xml file into it, one
may type:
**gramps -O** *'My Family Tree'* **-i** *~/db3.gramps* To import three databases and start interactive gramps session with the result::
The above changes the opened family tree, to do the same, but import gramps -i file1.ged -i file2.tgz -i ~/db3.gramps
both in a temporary family tree and start an interactive session, one
may type:
**gramps -i** *'My Family Tree'* **-i** *~/db3.gramps* To run the Verify tool from the commandline and output the result to
**stdout**::
To import four databases (whose formats can be determined from their gramps -O 'My Family Tree' -a tool -p name= verify
names) and then check the resulting database for errors, one may type:
**gramps -i** *file1.ged* **-i** *file2.tgz* **-i** *~/db3.gramps* Finally, to start normal interactive session type::
**-i** *file4.wft* **-a** *check*
To explicitly specify the formats in the above example, append file‐ gramps
names with appropriate **-f** options:
**gramps -i** *file1.ged* **-f** *gedcom* **-i** *file2.tgz* **-f** #####################
*gramps-pkg* **-i** *~/db3.gramps* **-f** *gramps-xml* **-i** *file4.wft* ENVIRONMENT VARIABLES
**-f** *wft* **-a** *check* #####################
To record the database resulting from all imports, supply **-e** flag (use The program checks whether these environment variables are set:
**-f** if the filename does not allow gramps to guess the format):
**gramps -i** *file1.ged* **-i** *file2.tgz* **-e** *~/new-package* ``LANG``
**-f** *gramps-pkg* describe, which language to use:
Ex.: for polish language this variable has to be set to `pl_PL.UTF-8`.
To import three databases and start interactive gramps session with the ``GRAMPSHOME``
result: if set, force Gramps to use the specified directory to keep program
settings and databases there.
By default, this variable is not set and gramps assumes that the folder
with all databases and profile settings should be created within the user
profile folder (described by environment variable *HOME* for Linux or
*USERPROFILE* for Windows 2000/XP).
**gramps -i** *file1.ged* **-i** *file2.tgz* **-i** *~/db3.gramps* ``CONCEPTS``
Supports a python-based plugin system, allowing import and export writers,
To run the Verify tool from the commandline and output the result to report generators, tools, and display filters to be added without
stdout:
**gramps -O** *'My Family Tree'* **-a** *tool* **-p name=** *verify*
Finally, to start normal interactive session type:
**gramps**
**ENVIRONMENT VARIABLES**
The program checks whether these environment variables are set:
**LANG** - describe, which language to use: Ex.: for polish language this
variable has to be set to pl_PL.UTF-8.
**GRAMPSHOME** - if set, force Gramps to use the specified directory to
keep program settings and databases there. By default, this variable is
not set and gramps assumes that the folder with all databases and pro‐
file settings should be created within the user profile folder
(described by environment variable HOME for Linux or USERPROFILE for
Windows 2000/XP).
**CONCEPTS**
Supports a python-based plugin system, allowing import and export writ‐
ers, report generators, tools, and display filters to be added without
modification of the main program. modification of the main program.
In addition to generating direct printer output, report generators also In addition to generating direct printer output, report generators also
target other systems, such as *LibreOffice.org* , *AbiWord* , *HTML*, target other systems, such as *LibreOffice.org*, *AbiWord*, *HTML*, or
or *LaTeX* to allow the users to modify the format to suit their needs. *LaTeX* to allow the users to modify the format to suit their needs.
#####
**KNOWN BUGS AND LIMITATIONS** FILES
#####
**FILES**
*${PREFIX}/bin/gramps* *${PREFIX}/bin/gramps*
@ -273,27 +279,27 @@ gramps(1) @VERSION@ gramps(1)
*${HOME}/.gramps* *${HOME}/.gramps*
#######
AUTHORS
#######
**AUTHORS** Donald Allingham <don@gramps-project.org>
Donald Allingham <don@gramps-project.org> http://gramps-project.org/
http://gramps-project.org/
This man page was originally written by: This man page was originally written by:
Brandon L. Griffith <brandon@debian.org> Brandon L. Griffith <brandon@debian.org>
for inclusion in the Debian GNU/Linux system. for inclusion in the Debian GNU/Linux system.
This man page is currently maintained by: This man page is currently maintained by:
Gramps project <xxx@gramps-project.org> Gramps project <xxx@gramps-project.org>
#############
DOCUMENTATION
#############
**DOCUMENTATION** The user documentation is available through standard web browser in the form of
The user documentation is available through standard web browser Gramps Manual.
in the form of Gramps Manual.
The developer documentation can be found on the The developer documentation can be found on the
http://www.gramps-project.org/wiki/index.php?title=Portal:Developers http://www.gramps-project.org/wiki/index.php?title=Portal:Developers
portal. portal.
gramps(1) @VERSION@ gramps(1)