* gpg.texi: New.

* gnupg.texi: Include gpg.texi

* tools.texi: Add a few @command markups.
* gpgsm.texi: Ditto
* gpg-agent.texi: Ditto.
* scdaemon.texi: Ditto.

7 files changed, 80 insertions, 59 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 4c2eaf216..c8e955ef2 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,13 @@
+2004-09-30  Werner Koch  <[email protected]>
+
+	* gpg.texi: New.
+	* gnupg.texi: Include gpg.texi
+
+	* tools.texi: Add a few @command markups.
+	* gpgsm.texi: Ditto 
+	* gpg-agent.texi: Ditto.
+	* scdaemon.texi: Ditto.
+
 2004-09-30  Marcus Brinkmann  <[email protected]>
 
 	* tools.texi (Changing options): Add documentation for gpgconf.
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 3ac312049..d44765a2e 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -21,8 +21,8 @@
 info_TEXINFOS = gnupg.texi
 
 gnupg_TEXINFOS = \
-	gpgsm.texi gpg-agent.texi scdaemon.texi assuan.texi tools.texi \
-	debugging.texi glossary.texi contrib.texi gpl.texi 
+	gpg.texi gpgsm.texi gpg-agent.texi scdaemon.texi assuan.texi \
+	tools.texi debugging.texi glossary.texi contrib.texi gpl.texi
 
 DISTCLEANFILES = gnupg.tmp gnupg.ops
 
diff --git a/doc/gnupg.texi b/doc/gnupg.texi
index ec82fe425..478bb4395 100644
--- a/doc/gnupg.texi
+++ b/doc/gnupg.texi
@@ -102,8 +102,8 @@ Boston, MA 02111-1307 USA
 This manual documents how to use the GNU Privay Guard system as well as
 the administration and the architecture.
 
-@c * Gpg::             Using the OpenPGP protocol.
 @menu
+* Invoking GPG::        Using the OpenPGP protocol.
 * Invoking GPGSM::      Using the S/MIME protocol.
 * Invoking GPG-AGENT::  How to launch the secret key daemon.
 * Invoking SCDAEMON::   How to handle Smartcards.
@@ -127,6 +127,7 @@ Indices
 * Index::	        Index of concepts and symbol names.
 @end menu
 
+@include gpg.texi
 @include gpgsm.texi
 @include gpg-agent.texi
 @include scdaemon.texi
diff --git a/doc/gpg-agent.texi b/doc/gpg-agent.texi
index 2b45a41c1..26b5634cc 100644
--- a/doc/gpg-agent.texi
+++ b/doc/gpg-agent.texi
@@ -10,9 +10,10 @@
 
 @c man begin DESCRIPTION
 
-@sc{gpg-agent} is a daemon to manage secret (private) keys independelty
-from any protocol.  It is used as a backend for @sc{gpg} and @sc{gpgsm}
-as well as for a couple of other utilities.
+@command{gpg-agent} is a daemon to manage secret (private) keys
+independelty from any protocol.  It is used as a backend for
+@command{gpg} and @command{gpgsm} as well as for a couple of other
+utilities.
 
 @noindent
 The usual way to run the agent is from the @code{~/.xsession} file:
@@ -24,8 +25,8 @@ eval `gpg-agent --daemon`
 @noindent
 If you don't use an X server, you can also put this into your regular
 startup file @code{~/.profile} or @code{.bash_profile}.  It is best not
-to run multiple instance of the gpg-agent, so you should make sure that
-only is running:  @sc{gpg-agent} uses an environment variable to inform
+to run multiple instance of the @command{gpg-agent}, so you should make sure that
+only is running:  @command{gpg-agent} uses an environment variable to inform
 clients about the communication parameters. You can write the
 content of this environment variable to a file so that you can test for
 a running agent.  This short script may do the job:
@@ -66,7 +67,7 @@ one (e.g. @file{/usr/bin/pinentry}).
 @c man end
 
 @noindent
-@xref{Option Index}, for an index to GPG-AGENTS's commands and options.
+@xref{Option Index}, for an index to @command{GPG-AGENT}'s commands and options.
 
 @menu
 * Agent Commands::      List of all commands.
@@ -254,7 +255,7 @@ harder for users to inadvertly accept Root-CA keys.
 
 @item --ignore-cache-for-signing
 @opindex ignore-cache-for-signing
-This option will let gpg-agent bypass the passphrase cache for all
+This option will let @command{gpg-agent} bypass the passphrase cache for all
 signing operation.  Note that there is also a per-session option to
 control this behaviour but this command line option takes precedence.
 
@@ -372,13 +373,13 @@ $ eval `gpg-agent --daemon`
 @node Agent Protocol
 @section Agent's Assuan Protocol
 
-The gpg-agent should be started by the login shell and set an
+The @command{gpg-agent} should be started by the login shell and set an
 environment variable to tell clients about the socket to be used.
 Clients should deny to access an agent with a socket name which does
 not match its own configuration.  An application may choose to start
 an instance of the gpgagent if it does not figure that any has been
 started; it should not do this if a gpgagent is running but not
-usable.  Because gpg-agent can only be used in background mode, no
+usable.  Because @command{gpg-agent} can only be used in background mode, no
 special command line option is required to activate the use of the
 protocol.
 
@@ -416,7 +417,7 @@ appropriate secret key or to delegate it to a smartcard.
 @end example
 
 Tell the server about the key to be used for decryption.  If this is
-not used, gpg-agent may try to figure out the key by trying to
+not used, @command{gpg-agent} may try to figure out the key by trying to
 decrypt the message with each key available.
 
 @example
@@ -528,8 +529,8 @@ The operation is affected by the option
 @end example
 
 The default of @code{1} uses the cache.  Setting this option to @code{0}
-will lead gpg-agent to ignore the passphrase cache.  Note, that there is
-also a global command line option for gpg-agent to globally disable the
+will lead @command{gpg-agent} to ignore the passphrase cache.  Note, that there is
+also a global command line option for @command{gpg-agent} to globally disable the
 caching.
 
 
diff --git a/doc/gpgsm.texi b/doc/gpgsm.texi
index 05c351cd8..94e6936ad 100644
--- a/doc/gpgsm.texi
+++ b/doc/gpgsm.texi
@@ -10,15 +10,15 @@
 
 @c man begin DESCRIPTION
 
-@sc{gpgsm} is a tool similar to @sc{gpg} to provide digital encryption
-and signing servicesd on X.509 certificates and the CMS protocoll.  It
-is mainly used as a backend for S/MIME mail processing.  @sc{gpgsm}
-includes a full features certificate management and complies with all
-rules defined for the German Sphinx project.
+@command{gpgsm} is a tool similar to @command{gpg} to provide digital
+encryption and signing servicesd on X.509 certificates and the CMS
+protocoll.  It is mainly used as a backend for S/MIME mail processing.
+@command{gpgsm} includes a full features certificate management and
+complies with all rules defined for the German Sphinx project.
 
 @c man end
 
-@xref{Option Index}, for an index to GPGSM's commands and options.
+@xref{Option Index}, for an index to @command{GPGSM}'s commands and options.
 
 @menu
 * GPGSM Commands::        List of all commands.
@@ -26,7 +26,7 @@ rules defined for the German Sphinx project.
 * GPGSM Examples::        Some usage examples.
 
 Developer information:
-* Unattended Usage::      Using @sc{gpgsm} from other programs.
+* Unattended Usage::      Using @command{gpgsm} from other programs.
 * GPGSM Protocol::        The protocol the server mode uses.
 @end menu
 
@@ -106,7 +106,7 @@ is not possible to pass data via stdin to the Dirmngr.  @var{command}
 should not contain spaces.
 
 This is command is required for certain maintaining tasks of the dirmngr
-where a dirmngr must be able to call back to gpgsm.  See the Dirmngr
+where a dirmngr must be able to call back to @command{gpgsm}.  See the Dirmngr
 manual for details.
 
 @item --call-protect-tool @var{arguments}
@@ -169,7 +169,7 @@ This is a debugging aid to reset certain flags in the key database
 which are used to cache certain certificate stati.  It is especially
 useful if a bad CRL or a weird running OCSP reponder did accidently
 revoke certificate.  There is no security issue with this command
-because gpgsm always make sure that the validity of a certificate is
+because @command{gpgsm} always make sure that the validity of a certificate is
 checked right before it is used.
 
 @item --delete-keys @var{pattern}
@@ -208,7 +208,7 @@ smartcard is not yet supported.
 @node GPGSM Options
 @section Option Summary
 
-GPGSM comes features a bunch ofoptions to control the exact behaviour
+@command{GPGSM} comes features a bunch ofoptions to control the exact behaviour
 and to change the default configuration.
 
 @menu 
@@ -242,7 +242,7 @@ below the home directory of the user.
 @opindex verbose
 Outputs additional information while running.
 You can increase the verbosity by giving several
-verbose commands to @sc{gpgsm}, such as @samp{-vv}.
+verbose commands to @command{gpgsm}, such as @samp{-vv}.
 
 @item --policy-file @var{filename}
 @opindex policy-file
@@ -463,7 +463,7 @@ Same as @code{--debug=0xffffffff}
 
 @item --debug-allow-core-dump
 @opindex debug-allow-core-dump
-Usually gpgsm tries to avoid dumping core by well written code and by
+Usually @command{gpgsm} tries to avoid dumping core by well written code and by
 disabling core dumps for security reasons.  However, bugs are pretty
 durable beasts and to squash them it is sometimes useful to have a core
 dump.  This option enables core dumps unless the Bad Thing happened
@@ -472,12 +472,12 @@ before the option parsing.
 @item --debug-no-chain-validation
 @opindex debug-no-chain-validation
 This is actually not a debugging option but only useful as such.  It
-lets gpgsm bypass all certificate chain validation checks.
+lets @command{gpgsm} bypass all certificate chain validation checks.
 
 @item --debug-ignore-expiration
 @opindex debug-ignore-expiration
 This is actually not a debugging option but only useful as such.  It
-lets gpgsm ignore all notAfter dates, this is used by the regresssion
+lets @command{gpgsm} ignore all notAfter dates, this is used by the regresssion
 tests.
 
 @item --fixed-passphrase @var{string}
@@ -515,7 +515,7 @@ $ gpgsm -er goo@@bar.net <plaintext >ciphertext
 @node Unattended Usage
 @section Unattended Usage
 
-@sc{gpgsm} is often used as a backend engine by other software.  To help
+@command{gpgsm} is often used as a backend engine by other software.  To help
 with this a machine interface has been defined to have an unambiguous
 way to do this.  This is most likely used with the @code{--server} command
 but may also be used in the standard operation mode by using the
@@ -541,7 +541,7 @@ certificates are all sane.  However there are two subcases with
 important information:  One of the certificates may have expired or a
 signature of a message itself as expired.  It is a sound practise to
 consider such a signature still as valid but additional information
-should be displayed.  Depending on the subcase @sc{gpgsm} will issue
+should be displayed.  Depending on the subcase @command{gpgsm} will issue
 these status codes:
   @table @asis 
   @item signature valid and nothing did expire
@@ -556,7 +556,7 @@ these status codes:
 @item The signature is invalid
 This means that the signature verification failed (this is an indication
 of af a transfer error, a programm error or tampering with the message).
-@sc{gpgsm} issues one of these status codes sequences:
+@command{gpgsm} issues one of these status codes sequences:
   @table @code
   @item  @code{BADSIG}
   @item  @code{GOODSIG}, @code{VALIDSIG} @code{TRUST_NEVER}
@@ -576,12 +576,13 @@ this is a missing certificate.
 @node GPGSM Protocol
 @section The Protocol the Server Mode Uses.
 
-Description of the protocol used to access GPGSM.  GPGSM does implement
-the Assuan protocol and in addition provides a regular command line
-interface which exhibits a full client to this protocol (but uses
-internal linking).  To start gpgsm as a server the commandline "gpgsm
---server" must be used.  Additional options are provided to select the
-communication method (i.e. the name of the socket).
+Description of the protocol used to access @command{GPGSM}.
+@command{GPGSM} does implement the Assuan protocol and in addition
+provides a regular command line interface which exhibits a full client
+to this protocol (but uses internal linking).  To start
+@command{gpgsm} as a server the command line the option
+@code{--server} must be used.  Additional options are provided to
+select the communication method (i.e. the name of the socket).
 
 We assume that the connection has already been established; see the
 Assuan manual for details.
@@ -658,7 +659,7 @@ It takes the plaintext from the @code{INPUT} command, writes to the
 ciphertext to the file descriptor set with the @code{OUTPUT} command,
 take the recipients from all the recipients set so far.  If this command
 fails the clients should try to delete all output currently done or
-otherwise mark it as invalid.  GPGSM does ensure that there won't be any
+otherwise mark it as invalid.  @command{GPGSM} does ensure that there won't be any
 security problem with leftover data on the output in this case.
 
 This command should in general not fail, as all necessary checks have
@@ -671,7 +672,7 @@ closed.
 
 Input and output FDs are set the same way as in encryption, but
 @code{INPUT} refers to the ciphertext and output to the plaintext. There
-is no need to set recipients.  GPGSM automatically strips any
+is no need to set recipients.  @command{GPGSM} automatically strips any
 @acronym{S/MIME} headers from the input, so it is valid to pass an
 entire MIME part to the INPUT pipe.
 
@@ -697,7 +698,7 @@ Signing is usually done with these commands:
   INPUT FD=@var{n} [--armor|--base64|--binary]
 @end example
 
-This tells GPGSM to read the data to sign from file descriptor @var{n}.
+This tells @command{GPGSM} to read the data to sign from file descriptor @var{n}.
 
 @example
   OUTPUT FD=@var{m} [--armor|--base64]
@@ -755,14 +756,14 @@ client must provide it.
 This is used to generate a new keypair, store the secret part in the
 @acronym{PSE} and the public key in the key database.  We will probably
 add optional commands to allow the client to select whether a hardware
-token is used to store the key.  Configuration options to GPGSM can be
+token is used to store the key.  Configuration options to @command{GPGSM} can be
 used to restrict the use of this command.
 
 @example
   GENKEY 
 @end example
 
-GPGSM checks whether this command is allowed and then does an
+@command{GPGSM} checks whether this command is allowed and then does an
 INQUIRY to get the key parameters, the client should then send the
 key parameters in the native format:
 
diff --git a/doc/scdaemon.texi b/doc/scdaemon.texi
index 3e11a8930..42dedb6b4 100644
--- a/doc/scdaemon.texi
+++ b/doc/scdaemon.texi
@@ -10,7 +10,7 @@
 
 @c man begin DESCRIPTION
 
-The @sc{scdaemon} is a daemon to manage smartcards.  It is usually
+The @command{scdaemon} is a daemon to manage smartcards.  It is usually
 invoked by gpg-agent and in general not used directly.
 
 @c man end
@@ -87,7 +87,7 @@ below the home directory of the user.
 @opindex verbose
 Outputs additional information while running.
 You can increase the verbosity by giving several
-verbose commands to @sc{gpgsm}, such as @samp{-vv}.
+verbose commands to @command{gpgsm}, such as @samp{-vv}.
 
 @item --debug-level @var{level}
 @opindex debug-level
@@ -200,7 +200,7 @@ stripping off the two leading dashes.
 @node Card applications
 @section Description of card applications
 
-@sc{scdaemon} supports the card applications as described below.
+@command{scdaemon} supports the card applications as described below.
 
 @menu
 * OpenPGP Card::          The OpenPGP card application
@@ -212,8 +212,8 @@ stripping off the two leading dashes.
 @node OpenPGP Card
 @subsection The OpenPGP card application ``openpgp''
 
-This application is currently only used by @sc{gpg} but may in
-future also be useful with @sc{gpgsm}. 
+This application is currently only used by @command{gpg} but may in
+future also be useful with @command{gpgsm}. 
 
 The specification for such a card is available at
 @uref{http://g10code.com/docs/openpgp-card-1.0.pdf}.
@@ -223,7 +223,7 @@ The specification for such a card is available at
 
 This is the main application of the Telesec cards as available in
 Germany.  It is a superset of the German DINSIG card.  The card is
-used by @sc{gpgsm}.
+used by @command{gpgsm}.
 
 @node DINSIG Card
 @subsection The DINSIG card application ``dinsig''
@@ -237,7 +237,7 @@ the German signature law and its bylaws (SigG and SigV).
 
 This is common fraqmework for smart card applications; support is only
 available if compiled with support for the OpenSC library.  It is used
-by @sc{gpgsm}.
+by @command{gpgsm}.
 
 
 
@@ -375,7 +375,7 @@ To sign some data the caller should use the command
  SETDATA @var{hexstring}
 @end example
 
-to tell scdaemon about the data to be signed.  The data must be given in
+to tell @command{scdaemon} about the data to be signed.  The data must be given in
 hex notation.  The actual signing is done using the command
 
 @example
@@ -395,8 +395,9 @@ To decrypt some data the caller should use the command
  SETDATA @var{hexstring}
 @end example
 
-to tell scdaemon about the data to be decrypted.  The data must be given in
-hex notation.  The actual decryption is then done using the command
+to tell @command{scdaemon} about the data to be decrypted.  The data
+must be given in hex notation.  The actual decryption is then done
+using the command
 
 @example
   PKDECRYPT @var{keyid}
diff --git a/doc/tools.texi b/doc/tools.texi
index 72707639c..79ae85d90 100644
--- a/doc/tools.texi
+++ b/doc/tools.texi
@@ -13,18 +13,20 @@ GnuPG comes with a couple of smaller tools:
 * gpgconf::               Modify .gnupg home directories.
 @end menu
 
-
+@c
+@c  WATHCGNUPG
+@c
 @node watchgnupg
 @section Read logs from a socket
 
 Most of the main utilities are able to write there log files to a
-Unix Domain socket if configured that way.  watchgnupg is a simple
+Unix Domain socket if configured that way.  @command{watchgnupg} is a simple
 listener for such a socket.  It ameliorates the output with a time
 stamp and makes sure that long lines are not interspersed with log
 output from other utilities.
 
 @noindent
-watchgnupg is commonly invoked as
+@command{watchgnupg} is commonly invoked as
 
 @samp{watchgnupg --force ~/.gnupg/S.log}
 
@@ -33,7 +35,7 @@ This starts it on the current terminal for listening on the socket
 @file{~/.gnupg/S.log}.  
 
 @noindent
-watchgnupg understands these options:
+@command{watchgnupg} understands these options:
 
 @table @gnupgtabopt
 
@@ -56,7 +58,9 @@ Display a brief help page and exit
 @end table
 
 
-
+@c
+@c    ADDGNUPGHOME
+@c
 @node addgnupghome
 @section Create .gnupg home directories.
 
@@ -69,11 +73,14 @@ directories of the accounts given on the command line.  It takes care
 not to overwrite existing GnuPG home directories.
 
 @noindent
-addgnupghome is invoked by root as:
+@command{addgnupghome} is invoked by root as:
 
 @samp{addgnupghome account1 account2 ... accountn}
 
 
+@c
+@c   GPGCONF
+@c
 @node gpgconf
 @section Modify .gnupg home directories.