More man pages. Added include files for 2 common paragraphs.
authorWerner Koch <wk@gnupg.org>
Fri, 18 Aug 2006 13:05:39 +0000 (13:05 +0000)
committerWerner Koch <wk@gnupg.org>
Fri, 18 Aug 2006 13:05:39 +0000 (13:05 +0000)
NEWS
README
doc/Makefile.am
doc/gpg-agent.texi
doc/gpg.texi
doc/gpgsm.texi
doc/opt-homedir.texi [new file with mode: 0644]
doc/scdaemon.texi
doc/see-also-note.texi [new file with mode: 0644]
doc/tools.texi
doc/yat2m.c

diff --git a/NEWS b/NEWS
index 2979dda..4c3863b 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,13 @@
 Noteworthy changes in version 1.9.23
 -------------------------------------------------
 
+ * man pages for most tools are now build directly from the texinfo
+   source.
+
+ * The gpg code from 1.4.5 has been fully merged into this release.
+   The configure option --enable-gpg is still required to build this
+   gpg part.  For production use of OpenPGP the gpg version 1.4.5 is
+   still recommended.
 
 
 Noteworthy changes in version 1.9.22 (2006-07-27)
diff --git a/README b/README
index 35832f4..6ae0e79 100644 (file)
--- a/README
+++ b/README
@@ -55,11 +55,12 @@ that this package won't conflict with a GnuPG 1.2 or 1.3
 installation. gpg2 behaves just like gpg; it is however suggested to
 keep using gpg 1.2.x or 1.3.x. gpg2 is not even build by default.
 
-In case of problem please ask on gpa-dev@gnupg.org for advise.  Note
+In case of problem please ask on gnupg-dev@gnupg.org for advise.  Note
 that this release is only expected to build on GNU and *BSD systems.
 
-A texinfo manual named `gnupg.info' will get installed.  Some commands
-and options given below.  See also the section `SMARTCARD INTRO'.
+A texinfo manual named `gnupg.info' will get installed. man pages for
+all major components are also provided. Some commands and options
+given below.  See also the section `SMARTCARD INTRO'.
 
 
 COMMANDS
index 872a744..8c1cdd7 100644 (file)
@@ -22,7 +22,8 @@
 EXTRA_DIST = gnupg-badge-openpgp.eps gnupg-badge-openpgp.jpg \
              gnupg-badge-openpgp.pdf \
              gnupg-card-architecture.eps gnupg-card-architecture.png \
-             gnupg-card-architecture.pdf
+             gnupg-card-architecture.pdf \
+             opt-homedir.texi see-also-note.texi
 
 BUILT_SOURCES = gnupg-card-architecture.eps gnupg-card-architecture.png \
                 gnupg-card-architecture.pdf
@@ -38,12 +39,16 @@ gnupg_TEXINFOS = \
        tools.texi debugging.texi glossary.texi contrib.texi gpl.texi \
        sysnotes.texi gnupg-card-architecture.fig
 
-YAT2M_OPTIONS = \
+AM_MAKEFINFOFLAGS = -I $(srcdir)
+
+YAT2M_OPTIONS = -I $(srcdir) \
         --release "GnuPG @PACKAGE_VERSION@" --source "GNU Privacy Guard"
 
 myman_sources = gpg.texi gpgsm.texi gpg-agent.texi scdaemon.texi tools.texi
 myman_pages   = gpg2.1 gpgsm.1 gpg-agent.1 scdaemon.1 \
-                watchgnupg.1 gpgconf.1 addgnupghome.8
+                watchgnupg.1 gpgconf.1 addgnupghome.8 gpg-preset-passphrase.1 \
+               gpg-connect-agent.1 gpgparsemail.1 symcryptrun.1 \
+               gpgsm-gencert.sh.1
 
 man_MANS = $(myman_pages)
 
index 74f9aa5..cb5032e 100644 (file)
@@ -168,14 +168,8 @@ per-user configuration file.  The default configuration file is named
 below the home directory of the user.
 
 @anchor{option --homedir}
-@item --homedir @var{dir}
-@opindex homedir
-Set the name of the home directory to @var{dir}. If his option is not
-used, the home directory defaults to @file{~/.gnupg}.  It is only
-recognized when given on the command line.  It also overrides any home
-directory stated through the environment variable @env{GNUPGHOME} or
-(on W32 systems) by means on the Registry entry
-@var{HKCU\Software\GNU\GnuPG:HomeDir}.
+@include opt-homedir.texi
+
 
 @item -v
 @item --verbose
index 49d332f..7d7e09c 100644 (file)
@@ -1501,11 +1501,8 @@ directory. If the filename does not contain a slash, it is assumed to
 be in the GnuPG home directory ("~/.gnupg" if --homedir or $GNUPGHOME
 is not used).
 
-@item --homedir @code{directory}
-Set the name of the home directory to @code{directory} If this option is not
-used it defaults to "~/.gnupg". It does not make sense to use this in
-a options file. This also overrides the environment variable
-$GNUPGHOME.
+@include opt-homedir.texi
+
 
 @item --pcsc-driver @code{file}
 Use @code{file} to access the smartcard reader. The current default is
index 63b1f74..720e3e7 100644 (file)
@@ -286,14 +286,7 @@ per-user configuration file.  The default configuration file is named
 @file{gpgsm.conf} and expected in the @file{.gnupg} directory directly
 below the home directory of the user.
 
-@item --homedir @var{dir}
-@opindex homedir
-Set the name of the home directory to @var{dir}. If his option is not
-used, the home directory defaults to @file{~/.gnupg}.  It is only
-recognized when given on the command line.  It also overrides any home
-directory stated through the environment variable @env{GNUPGHOME} or
-(on W32 systems) by means on the Registry entry
-@var{HKCU\Software\GNU\GnuPG:HomeDir}.
+@include opt-homedir.texi
 
 
 @item -v
diff --git a/doc/opt-homedir.texi b/doc/opt-homedir.texi
new file mode 100644 (file)
index 0000000..387bd02
--- /dev/null
@@ -0,0 +1,14 @@
+@c This option is included at several places.
+@item --homedir @var{dir}
+@opindex homedir
+Set the name of the home directory to @var{dir}. If his option is not
+used, the home directory defaults to @file{~/.gnupg}.  It is only
+recognized when given on the command line.  It also overrides any home
+directory stated through the environment variable @env{GNUPGHOME} or
+(on W32 systems) by means on the Registry entry
+@ifset isman
+@var{HKCU\\Software\\GNU\\GnuPG:HomeDir}.
+@end ifset
+@ifclear isman
+@var{HKCU\Software\GNU\GnuPG:HomeDir}.
+@end ifclear
index 9a9e278..f507520 100644 (file)
@@ -114,14 +114,8 @@ per-user configuration file.  The default configuration file is named
 @file{scdaemon.conf} and expected in the @file{.gnupg} directory directly
 below the home directory of the user.
 
-@item --homedir @var{dir}
-@opindex homedir
-Set the name of the home directory to @var{dir}. If his option is not
-used, the home directory defaults to @file{~/.gnupg}.  It is only
-recognized when given on the command line.  It also overrides any home
-directory stated through the environment variable @env{GNUPGHOME} or
-(on W32 systems) by means on the Registry entry
-@var{HKCU\Software\GNU\GnuPG:HomeDir}.
+@include opt-homedir.texi
+
 
 @item -v
 @item --verbose
diff --git a/doc/see-also-note.texi b/doc/see-also-note.texi
new file mode 100644 (file)
index 0000000..b18efc3
--- /dev/null
@@ -0,0 +1,14 @@
+@c We append this note to all ``see also'' sections of the man pages
+
+@ifset isman
+The full documentation for this tool is maintained as a Texinfo manual.
+If GnuPG and the info program are properly installed at your site, the
+command
+
+@example
+info gnupg
+@end example
+
+should give you access to the complete manual including a menu structure
+and an index.
+@end ifset
index ec14760..d4f6984 100644 (file)
@@ -138,15 +138,17 @@ addgnupghome account1 account2 ... accountn
 @ifset manverb
 .B gpgconf
 .RI [ options ]
-.BI --list-components
+.B \-\-list-components
 .br
 .B gpgconf
 .RI [ options ]
-.BI --list-options component
+.B \-\-list-options 
+.I component
 .br
 .B gpgconf
 .RI [ options ]
-.BI --change-options component
+.B \-\-change-options
+.I component
 @end ifset
 
 
@@ -192,7 +194,7 @@ throughout this section.
 * Changing options::      Changing options of a component.
 @end menu
 
-
+@manpause
 @node Invoking gpgconf
 @subsection Invoking gpgconf
 
@@ -210,7 +212,6 @@ List all options of the component @var{component}.
 
 @item --change-options @var{component}
 Change the options of the component @var{component}.
-@manpause
 @end table
 
 @mansect options
@@ -650,21 +651,48 @@ $ echo 'force:16:' | gpgconf --change-options dirmngr
 The @code{--runtime} option can influence when the changes take
 effect.
 
+@mansect see also
+@command{gpg}(1), 
+@command{gpgsm}(1), 
+@command{gpg-agent}(1), 
+@command{scdaemon}(1),
+@command{dirmngr}(1)
+@include see-also-note.texi
+
+
 @manpause
 @c
 @c    GPGSM-GENCERT.SH
 @c
 @node gpgsm-gencert.sh
 @section Generate an X.509 certificate request
+@manpage gpgsm-gencert.sh.1
+@ifset manverb
+.B gpgsm-gencert.sh
+\- Generate an X.509 certificate request
+@end ifset 
 
+@mansect synopsis
+@ifset manverb
+.B  gpgsm-gencert.sh
+@end ifset
+
+@mansect description
 This is a simple tool to interactivly generate a certificate request
 which will be printed to stdout.
 
+@manpause
 @noindent
 @command{gpgsm-gencert.sh} is invoked as:
 
 @samp{gpgsm-cencert.sh}
 
+@mansect see also
+@command{gpgsm}(1), 
+@command{gpg-agent}(1), 
+@command{scdaemon}(1)
+@include see-also-note.texi
+
 
 
 @c
@@ -672,7 +700,21 @@ which will be printed to stdout.
 @c
 @node gpg-preset-passphrase
 @section Put a passphrase into the cache.
+@manpage gpg-preset-passphrase.1
+@ifset manverb
+.B gpg-preset-passphrase
+\- Put a passphrase into gpg-agent's cache
+@end ifset
 
+@mansect synopsis
+@ifset manverb
+.B  gpg-preset-passphrase
+.RI [ options ]
+.RI [ command ]
+.I keygrip
+@end ifset
+
+@mansect description
 The @command{gpg-preset-passphrase} is a utility to seed the internal
 cache of a running @command{gpg-agent} with passphrases.  It is mainly
 useful for unattended machines, where the usual @command{pinentry} tool
@@ -690,9 +732,10 @@ starting @command{gpg-agent} with the
 * Invoking gpg-preset-passphrase::   List of all commands and options.
 @end menu
 
-
+@manpause
 @node Invoking gpg-preset-passphrase
 @subsection List of all commands and options.
+@mancont
 
 @noindent
 @command{gpg-preset-passphrase} is invoked this way:
@@ -709,11 +752,13 @@ must be given:
 
 @table @gnupgtabopt
 @item --preset
+@opindex preset
 Preset a passphrase. This is what you usually will
 use. @command{gpg-preset-passphrase} will then read the passphrase from
 @code{stdin}.
 
 @item --forget
+@opindex forget
 Flush the passphrase for the given keygrip from the cache.
 
 @end table
@@ -735,6 +780,12 @@ Instead of reading the passphrase from @code{stdin}, use the supplied
 for other users.
 @end table
 
+@mansect see also
+@command{gpg}(1), 
+@command{gpgsm}(1), 
+@command{gpg-agent}(1), 
+@command{scdaemon}(1)
+@include see-also-note.texi
 
 
 
@@ -743,8 +794,20 @@ for other users.
 @c   GPG-CONNECT-AGENT
 @c
 @node gpg-connect-agent
-@section Communicate with a runnig agent.
+@section Communicate with a running agent.
+@manpage gpg-connect-agent.1
+@ifset manverb
+.B gpg-connect-agent
+\- Communicate with a running agent
+@end ifset
 
+@mansect synopsis
+@ifset manverb
+.B  gpg-connect-agent
+.RI [ options ]
+@end ifset
+
+@mansect description
 The @command{gpg-connect-agent} is a utility to communicate with a
 running @command{gpg-agent}.  It is useful to check out the commands
 gpg-agent provides using the Assuan interface.  It might also be useful
@@ -758,9 +821,10 @@ here we connect to a running instance.
 * Invoking gpg-connect-agent::   List of all commands and options.
 @end menu
 
-
+@manpause
 @node Invoking gpg-connect-agent
 @subsection List of all commands and options.
+@mancont
 
 @noindent
 @command{gpg-connect-agent} is invoked this way:
@@ -784,15 +848,7 @@ Output additional information while running.
 @opindex quiet
 Try to be as quiet as possible.
 
-@item --homedir @var{dir}
-@opindex homedir
-Set the name of the home directory to @var{dir}. If his option is not
-used, the home directory defaults to @file{~/.gnupg}.  It is only
-recognized when given on the command line.  It also overrides any home
-directory stated through the environment variable @env{GNUPGHOME} or
-(on W32 systems) by means on the Registry entry
-@var{HKCU\Software\GNU\GnuPG:HomeDir}.
-
+@include opt-homedir.texi
 
 @item -S
 @itemx --raw-socket @var{name}
@@ -802,16 +858,36 @@ Connect to socket @var{name} assuming this is an Assuan style server.
 Do not run any special initializations or environment checks.  This may
 be used to directly connect to any Assuan style socket server.
 
-
 @end table
 
+@mansect see also
+@command{gpg-agent}(1), 
+@command{scdaemon}(1)
+@include see-also-note.texi
+
+
+
 @c
 @c   GPGPARSEMAIL
 @c
 @node gpgparsemail
 @section Parse a mail message into an annotated format
 
-The @command{gpgparsemail} is a utility currentlu only useful for
+@manpage gpgparsemail.1
+@ifset manverb
+.B gpgparsemail
+\- Parse a mail message into an annotated format
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B  gpgparsemail
+.RI [ options ]
+.RI [ file ]
+@end ifset
+
+@mansect description
+The @command{gpgparsemail} is a utility currently only useful for
 debugging.  Run it with @code{--help} for usage information.
 
 
@@ -821,7 +897,26 @@ debugging.  Run it with @code{--help} for usage information.
 @c
 @node symcryptrun
 @section Call a simple symmetric encryption tool.
+@manpage symcryptrun.1
+@ifset manverb
+.B symcryptrun
+\- Call a simple symmetric encryption tool
+@end ifset
+
+@mansect synopsis
+@ifset manverb
+.B  symcryptrun
+.B \-\-class
+.I class
+.B \-\-program
+.I program
+.B \-\-keyfile
+.I keyfile
+.RB [ --decrypt | --encrypt ]
+.RI [ inputfile ]
+@end ifset
 
+@mansect description
 Sometimes simple encryption tools are already in use for a long time and
 there might be a desire to integrate them into the GnuPG framework.  The
 protocols and encryption methods might be non-standard or not even
@@ -838,7 +933,7 @@ configured with @samp{--enable-symcryptrun} at build time.
 * Invoking symcryptrun::   List of all commands and options.
 @end menu
 
-
+@manpause
 @node Invoking symcryptrun
 @subsection List of all commands and options.
 
@@ -849,6 +944,7 @@ configured with @samp{--enable-symcryptrun} at build time.
 symcryptrun --class CLASS --program PROGRAM --keyfile KEYFILE 
    [--decrypt | --encrypt] [inputfile]
 @end example
+@mancont
 
 For encryption, the plain text must be provided on STDIN or as the
 argument @var{inputfile}, and the ciphertext will be output to STDOUT.
@@ -882,14 +978,8 @@ Output additional information while running.
 @opindex quiet
 Try to be as quiet as possible.
 
-@item --homedir @var{dir}
-@opindex homedir
-Set the name of the home directory to @var{dir}. If his option is not
-used, the home directory defaults to @file{~/.gnupg}.  It is only
-recognized when given on the command line.  It also overrides any home
-directory stated through the environment variable @env{GNUPGHOME} or
-(on W32 systems) by means on the Registry entry
-@var{HKCU\Software\GNU\GnuPG:HomeDir}.
+@include opt-homedir.texi
+
 
 @item --log-file @var{file}
 @opindex log-file
@@ -913,3 +1003,9 @@ The possible exit status codes of @command{symcryptrun} are:
 
 @end table
 
+@mansect see also
+@command{gpg}(1), 
+@command{gpgsm}(1), 
+@command{gpg-agent}(1), 
+@include see-also-note.texi
+
index e45168a..39feea9 100644 (file)
@@ -85,6 +85,7 @@ static int debug;
 static const char *opt_source; 
 static const char *opt_release; 
 static const char *opt_select;
+static const char *opt_include;
 static int opt_store;
 
 
@@ -335,7 +336,6 @@ add_content (const char *sectname, char *line, int verbatim)
   section_buffer_t sect;
   line_buffer_t lb;
 
-  
   sect = get_section_buffer (sectname);
   if (sect->last_line && !sect->last_line->verbatim == !verbatim)
     {
@@ -447,6 +447,7 @@ proc_texi_cmd (FILE *fp, const char *command, const char *rest, size_t len,
     { "end",     4 },
     { "quotation",1, ".RS\n\\fB" },
     { "ifset",   1 },
+    { "ifclear",   1 },
     { NULL }
   };
   size_t n;
@@ -501,6 +502,11 @@ proc_texi_cmd (FILE *fp, const char *command, const char *rest, size_t len,
             {
               fputs ("\\fR\n.RE\n", fp);
             }
+          else if (n >= 5 && !memcmp (s, "ifset", 5)
+              && (!n || s[5] == ' ' || s[5] == '\t' || s[5] == '\n'))
+            {
+              fputs ("\\fR\n.RE\n", fp);
+            }
           /* Now throw away the entire line. */
           s = memchr (rest, '\n', len);
           return s? (s-rest)+1 : len;  
@@ -815,8 +821,8 @@ parse_file (const char *fname, FILE *fp, char **section_name)
           while (*p == ' ' || *p == '\t')
             p++;
 
-          if (skip_to_end 
-              &&n == 4 && !memcmp (line, "@end", 4)
+          if (skip_to_end
+              && n == 4 && !memcmp (line, "@end", 4)
               && (line[4]==' '||line[4]=='\t'||!line[4]))
             {
               skip_to_end = 0;
@@ -881,12 +887,29 @@ parse_file (const char *fname, FILE *fp, char **section_name)
             {
               skip_to_end = 1;
             }
+          else if (n == 8 && !memcmp (line, "@ifclear", 8)
+              && !strncmp (p, "isman", 5) && (p[5]==' '||p[5]=='\t'||!p[5]))
+            {
+              skip_to_end = 1;
+            }
           else if (n == 8 && !memcmp (line, "@include", 8)
                    && (line[8]==' '||line[8]=='\t'||!line[8]))
             {
               char *incname = xstrdup (p);
               FILE *incfp = fopen (incname, "r");
 
+              if (!incfp && opt_include && *opt_include && *p != '/')
+                {
+                  free (incname);
+                  incname = xmalloc (strlen (opt_include) + 1
+                                     + strlen (p) + 1);
+                  strcpy (incname, opt_include);
+                  if ( incname[strlen (incname)-1] != '/' )
+                    strcat (incname, "/");
+                  strcat (incname, p);
+                  incfp = fopen (incname, "r");
+                }
+
               if (!incfp)
                 err ("can't open include file `%s':%s",
                      incname, strerror (errno));
@@ -895,8 +918,9 @@ parse_file (const char *fname, FILE *fp, char **section_name)
                   parse_file (incname, incfp, section_name);
                   fclose (incfp);
                 }
+              free (incname);
             }
-          else
+          else if (!skip_to_end)
             got_line = 1;
         }
       else if (!skip_to_end)
@@ -956,7 +980,8 @@ main (int argc, char **argv)
                 "  --select NAME    only output pages with @manpage NAME\n"
                 "  --verbose        enable extra informational output\n"
                 "  --debug          enable additional debug output\n"
-                "  --help           display this help and exit\n\n"
+                "  --help           display this help and exit\n"
+                "  -I DIR           also search in include DIR\n\n"
                 "With no FILE, or when FILE is -, read standard input.\n\n"
                 "Report bugs to <bugs@g10code.com>.");
           exit (0);
@@ -1021,6 +1046,15 @@ main (int argc, char **argv)
               argc--; argv++;
             }
         }
+      else if (!strcmp (*argv, "-I"))
+        {
+          argc--; argv++;
+          if (argc)
+            {
+              opt_include = *argv;
+              argc--; argv++;
+            }
+        }
     }          
  
   if (argc > 1)