2008-01-12 Cedric Scott <cedric@not2.be>

Benny Malengier <benny.malengier@gramps-project.org>
	* data/man/gramps.1.in: new man file


svn: r9808

ChangeLog

@@ -1,3 +1,6 @@
+2008-01-12  Cedric Scott <cedric@not2.be>
+            Benny Malengier <benny.malengier@gramps-project.org>
+	* data/man/gramps.1.in: new man file
 
 2008-01-14 Peter Landgren <peter.talken@telia.com>
         * _DateDisplay.py: ISO-date shows only year if month=0 and day=0

data/man/gramps.1.in

@@ -8,7 +8,7 @@ gramps \- Genealogical Research and Analysis Management Programming System.
 .RB [ \-\^\-usage ]
 .RB [ \-\^\-version ]
 .RB [ \-O|\-\^\-open=
-.IR FILE 
+.IR DATABASE 
 .RB [ \-f|\-\^\-format= 
 .IR FORMAT ]] 
 .RB [ \-i|\-\^\-import=
@@ -28,6 +28,9 @@ gramps \- Genealogical Research and Analysis Management Programming System.
 .RB [
 .IR FILE
 .RB ]
+.if 0 .RB [ bonobo\ options ]
+.if 0 .RB [ sound\ options ]
+.RB [ \-\-version ]
 
 .SH DESCRIPTION
 .PP 
@@ -42,25 +45,31 @@ wide by almost all other genealogy software.
 .SH OPTIONS
 .TP 
 .BI gramps " FILE" 
-When \fIFILE\fR is given (without any flags) then it is
+When \fIFILE\fR is given (without any flags) as a family tree name or as
-opened and an interactive session is started. The rest of the options
+a family tree database directory, then it is opened and an interactive 
-is ignored. This way of launching is suitable for using gramps
+session is started. If FILE is a file format understood by GRAMPS, an empty
+family tree is created  whose name is based on the \fIFILE\fP name
+and the data is imported 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.
 .br
 
 .TP 
 .BI \-f,\-\^\-format= " FORMAT"
-Explicitly specify format of \fIFILE\fR given by preceding \fB\-O\fR,
+Explicitly specify format of \fIFILE\fR given by preceding
+.ig
+\fB\-O\fR,
+..
 \fB\-i\fR, or 
 \fB\-o\fR option. If the \fB\-f\fR option is not given for any \fIFILE\fR, 
-the format of that file is guessed according to its extension. 
+the format of that file is guessed according to its extension or MIME-type. 
 .br
 
 Formats 
-available for opening are \fBgrdb\fR (guessed if \fIFILE\fR ends with
+available for output are \fBgramps\-xml\fR (guessed if \fIFILE\fR ends with
-\fB.grdb\fR), \fBgramps\-xml\fR (guessed if \fIFILE\fR ends with
+\fB.gramps\fR), \fBgedcom\fR (guessed if \fIFILE\fR ends with \fB.ged\fR), or
-\fB.gramps\fR), and \fBgedcom\fR (guessed if \fIFILE\fR ends with \fB.ged\fR).
+any file export available through the GRAMPS plugin system.
 .br
 
 Formats 
@@ -69,25 +78,23 @@ available for import are \fBgrdb\fR, \fBgramps\-xml\fR, \fBgedcom\fR,
 \fBgeneweb\fR (guessed if \fIFILE\fR ends with \fB.gw\fR). 
 .br
 
-Formats available for export are  \fBgrdb\fR, \fBgramps\-xml\fR, \fBgedcom\fR,
+Formats available for export are
+.ig
+\fBgrdb\fR,
+..
+\fBgramps\-xml\fR, \fBgedcom\fR,
 \fBgramps\-pkg\fR, \fBwft\fR (guessed if \fIFILE\fR ends with \fB.wft\fR),
 \fBgeneweb\fR, and \fBiso\fR (never guessed, always specify with
 \fB\-f\fR option).
 
 .TP 
-.BI \-O,\-\^\-open= " FILE"
+.BI \-O,\-\^\-open= " DATABASE"
-Open \fIFILE\fR. 
+Open \fIDATABASE\fR which must be an existing database directory or existing family tree name.
-Only \fBgrdb\fR, \fBgramps\-xml\fR, and \fBgedcom\fR formats can be
+If no action, import or export options are given on the command line then an interactive session is started using that database.
-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.
-.br
-
-Only a single file can be opened. If you need to combine data from several
-sources, you will need to use the import option. 
 
 .TP 
 .BI \-i,\-\^\-import= " FILE"
-Import data from \fIFILE\fR.
+Import data from \fIFILE\fR. If you haven't specified a database then a temporary database is used; this is deleted when you exit gramps.
 .br
 
 When more than one input file is given, each has to be preceded by \fB\-i\fR 
@@ -100,7 +107,11 @@ gramps IDs in the resulting database.
 .BI \-o,\-\^\-output= " FILE"
 Export data into \fIFILE\fR. For \fBiso\fR format, the \fIFILE\fR is actually
 the name of directory the gramps database will be written into. 
-For \fBgrdb\fR, \fBgramps\-xml\fR, \fBgedcom\fR, \fBwft\fR, \fBgramps\-pkg\fR, 
+For
+.ig
+\fBgrdb\fR,
+..
+\fBgramps\-xml\fR, \fBgedcom\fR, \fBwft\fR, \fBgramps\-pkg\fR, 
 and \fBgeneweb\fR, the \fIFILE\fR is the name of the resulting file. 
 .br
 
@@ -155,7 +166,42 @@ everything about a given report.
 When more than one output action is given, each has to be preceded 
 by \fB\-a\fR flag. The actions are performed one by one, in the specified order.
 
-.BI "Operation"
+.TP 
+.BI \-d,\-\^\-debug= " LOGGER_NAME"
+Enables debug logs for development and testing. Look at the source code for details
+.TP
+.BI \-\^\-version
+Prints the version number of gramps and then exits
+\" change 0 to 1 to enable output of OAF options
+.if 0 \{
+.PP
+The following options are used for Bonobo activation.
+.TP 
+.BI \-\^\-oaf-ior-fd= "FD"
+File descriptor to print the OAF IOR on
+.TP 
+.BI \-\^\-oaf-activate-iid= " IID"
+OAF IID to activate
+.TP 
+.BI \-\^\-oaf-private
+Prevent registering of server with OAF
+\}
+\" change 0 to 1 to enable output of Gnome sound options
+.if 0 \{
+.PP
+The following options are used for controlling sound using the Gnome Library.
+.TP
+.BI \-\^\-disable-sound
+Disable sound server usage
+.TP
+.BI \-\^\-enable-sound
+Enable sound server usage
+.TP
+.BI \-\^\-espeaker= " HOSTNAME:PORT"
+Host:port on which the sound server to use is running
+\}
+
+.SH "Operation"
 .br
 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
@@ -164,7 +210,7 @@ arguments.
 
 .LP
 If the \fB\-O\fR flag is given, then gramps will try opening
-the supplied file name and then work with that data, as instructed by the
+the supplied database and then work with that data, as instructed by the
 further command line parameters.
 
 .LP
@@ -196,6 +242,12 @@ of \fIstdout\fR and \fIstderr\fR to save messages and errors in files.
 
 .SH EXAMPLES
 .TP 
+To open an existing family tree and import an xml file  into it, one may type: 
+\fBgramps\fR \fB\-O\fR \fI'My Family Tree'\fR \fB\-i\fR \fI~/db3.gramps\fR
+.TP 
+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: 
+\fBgramps\fR \fB\-i\fR \fI'My Family Tree'\fR \fB\-i\fR \fI~/db3.gramps\fR
+.TP 
 To import four databases (whose formats can be determined from their names) and then check the resulting database for errors, one may type: 
 \fBgramps\fR \fB\-i\fR \fIfile1.ged\fR \fB\-i\fR \fIfile2.tgz\fR \fB\-i\fR \fI~/db3.gramps\fR \fB\-i\fR \fIfile4.wft\fR \fB\-a\fR \fIcheck\fR 
 .TP