doc: Add files and envvars to a new index.

* doc/gnupg.texi: Define new index "ef". (Environment Index): New. Signed-off-by: Werner Koch <wk@gnupg.org>
2016-06-14 14:57:49 +02:00 · 2016-06-14 14:57:49 +02:00 · 2423238ee4
parent f980cd2e0e
commit 2423238ee4
8 changed files with 75 additions and 29 deletions
--- a/doc/dirmngr.texi
+++ b/doc/dirmngr.texi
@ -312,6 +312,7 @@ value to access HTTP servers.

@item --http-proxy @var{host}[:@var{port}]
@opindex http-proxy
+@efindex http_proxy
 Use @var{host} and @var{port} to access HTTP servers.  The use of this
 option overrides the environment variable @env{http_proxy} regardless
 whether @option{--honor-http-proxy} has been set.
--- a/doc/gnupg.texi
+++ b/doc/gnupg.texi
@ -15,13 +15,22 @@
@macro mancont
@end macro

+
+
@c Create a separate index for command line options.
@defcodeindex op
-@c Merge the standard indexes into a single one.
+@c Create an index vor environment variables and files.
+@defcodeindex ef
+
+@c Merge the function index into the concept index.
@syncodeindex fn cp
+@c Merge the variable index into the concept index.
@syncodeindex vr cp
+@c Merge the keystroke index into the concept index.
@syncodeindex ky cp
+@c Merge the program index into the concept index.
@syncodeindex pg cp
+@c Merge the data type index into the concept index.
@syncodeindex tp cp
@c %**end of header
@copying
@ -144,6 +153,7 @@ the administration and the architecture.

 * Glossary::            Short description of terms used.
 * Option Index::        Index to command line options.
+* Environment Index::   Index to environment variables and files.
 * Index::	        Index of concepts and symbol names.
@end menu

@ -192,6 +202,11 @@ the administration and the architecture.

@printindex op

+@node Environment Index
+@unnumbered Environment Variable and File Index
+
+@printindex ef
+
@node Index
@unnumbered Index

--- a/doc/gpg-agent.texi
+++ b/doc/gpg-agent.texi
@ -85,6 +85,7 @@ gpg-connect-agent /bye
@end example

@noindent
+@efindex GPG_TTY
 You should always add the following lines to your @code{.bashrc} or
 whatever initialization file is used for all shell invocations:

@ -295,6 +296,7 @@ debugging.
@itemx --csh
@opindex sh
@opindex csh
+@efindex SHELL
 Format the info output in daemon mode for use with the standard Bourne
 shell or the C-shell respectively.  The default is to guess it based on
 the environment variable @code{SHELL} which is correct in almost all
@ -309,6 +311,7 @@ should in general not be used to avoid X-sniffing attacks.
@anchor{option --log-file}
@item --log-file @var{file}
@opindex log-file
+@efindex HKCU\Software\GNU\GnuPG:DefaultLogFile
 Append all logging output to @var{file}.  This is very helpful in seeing
 what the agent actually does.  If neither a log file nor a log file
 descriptor has been set on a Windows platform, the Registry entry
@ -613,7 +616,7 @@ agent. By default they may all be found in the current home directory
@table @file

@item gpg-agent.conf
-@cindex gpg-agent.conf
+@efindex gpg-agent.conf
  This is the standard configuration file read by @command{gpg-agent} on
  startup.  It may contain any valid long option; the leading
  two dashes may not be entered and the option may not be abbreviated.
@ -623,6 +626,7 @@ agent. By default they may all be found in the current home directory
  You should backup this file.

@item trustlist.txt
+@efindex trustlist.txt
  This is the list of trusted keys.  You should backup this file.

  Comment lines, indicated by a leading hash mark, as well as empty
@ -684,7 +688,7 @@ fails, try again using the chain validation model.


@item sshcontrol
-@cindex sshcontrol
+@efindex sshcontrol
 This file is used when support for the secure shell agent protocol has
 been enabled (@pxref{option --enable-ssh-support}). Only keys present in
 this file are used in the SSH protocol.  You should backup this file.
@ -718,6 +722,7 @@ implicitly added to this list; i.e. there is no need to list them.
@end cartouche

@item private-keys-v1.d/
+@efindex private-keys-v1.d

  This is the directory where gpg-agent stores the private keys.  Each
  key is stored in a file with the name made up of the keygrip and the
@ -794,7 +799,7 @@ This signal is used for internal purposes.
@node Agent Examples
@section Examples

-It is important to set the GPG_TTY environment variable in
+It is important to set the environment variable @code{GPG_TTY} in
 your login shell, for example in the @file{~/.bashrc} init script:

@cartouche
--- a/doc/gpg.texi
+++ b/doc/gpg.texi
@ -1341,9 +1341,10 @@ executing it from GnuPG does not make it secure.

@item --exec-path @code{string}
@opindex exec-path
+@efindex PATH
 Sets a list of directories to search for photo viewers and keyserver
 helpers. If not provided, keyserver helpers use the compiled-in
-default directory, and photo viewers use the $PATH environment
+default directory, and photo viewers use the @code{PATH} environment
 variable.
 Note, that on W32 system this value is ignored when searching for
 keyserver helpers.
@ -1886,9 +1887,7 @@ file name.
@item --dirmngr-program @var{file}
@opindex dirmngr-program
 Specify a dirmngr program to be used for keyserver access.  The
-default value is @file{@value{BINDIR}/dirmngr}.  This is only used as a
-fallback when the environment variable @code{DIRMNGR_INFO} is not set or
-a running dirmngr cannot be connected.
+default value is @file{@value{BINDIR}/dirmngr}.

@item --no-autostart
@opindex no-autostart
@ -3162,7 +3161,7 @@ current home directory (@pxref{option --homedir}).
@table @file

  @item gpg.conf
-  @cindex gpg.conf
+  @efindex gpg.conf
  This is the standard configuration file read by @command{@gpgname} on
  startup.  It may contain any valid long option; the leading two dashes
  may not be entered and the option may not be abbreviated.  This default
@ -3184,13 +3183,21 @@ files; They all live in in the current home directory (@pxref{option


@table @file
+  @item ~/.gnupg
+  @efindex ~/.gnupg
+  This is the default home directory which is used if neither the
+  environment variable @code{GNUPGHOME} nor the option
+  @option{--homedir} is given.
+
  @item ~/.gnupg/pubring.gpg
+  @efindex pubring.gpg
  The public keyring.  You should backup this file.

  @item ~/.gnupg/pubring.gpg.lock
  The lock file for the public keyring.

  @item ~/.gnupg/pubring.kbx
+  @efindex pubring.kbx
  The public keyring using a different format.  This file is sharred
  with @command{gpgsm}.  You should backup this file.

@ -3198,13 +3205,19 @@ files; They all live in in the current home directory (@pxref{option
  The lock file for @file{pubring.kbx}.

  @item ~/.gnupg/secring.gpg
+  @efindex secring.gpg
  A secret keyring as used by GnuPG versions before 2.1.  It is not
  used by GnuPG 2.1 and later.

+  @item ~/.gnupg/secring.gpg.lock
+  The lock file for the secret keyring.
+
  @item ~/.gnupg/.gpg-v21-migrated
+  @efindex .gpg-v21-migrated
  File indicating that a migration to GnuPG 2.1 has been done.

  @item ~/.gnupg/trustdb.gpg
+  @efindex trustdb.gpg
  The trust database.  There is no need to backup this file; it is better
  to backup the ownertrust values (@pxref{option --export-ownertrust}).

@ -3212,12 +3225,11 @@ files; They all live in in the current home directory (@pxref{option
  The lock file for the trust database.

  @item ~/.gnupg/random_seed
+  @efindex random_seed
  A file used to preserve the state of the internal random pool.

-  @item ~/.gnupg/secring.gpg.lock
-  The lock file for the secret keyring.
-
  @item ~/.gnupg/openpgp-revocs.d/
+  @efindex openpgp-revocs.d
  This is the directory where gpg stores pre-generated revocation
  certificates.  The file name corresponds to the OpenPGP fingerprint of
  the respective key.  It is suggested to backup those certificates and
@ -3228,11 +3240,9 @@ files; They all live in in the current home directory (@pxref{option
  this backup closed away.

  @item @value{DATADIR}/options.skel
+  @efindex options.skel
  The skeleton options file.

-  @item @value{LIBDIR}/
-  Default location for extensions.
-
@end table

@c man:.RE
@ -3241,24 +3251,29 @@ Operation is further controlled by a few environment variables:
@table @asis

  @item HOME
+  @efindex HOME
  Used to locate the default home directory.

  @item GNUPGHOME
+  @efindex GNUPGHOME
  If set directory used instead of "~/.gnupg".

  @item GPG_AGENT_INFO
-  This variable was used by GnuPG versions before 2.1
+  This variable is obsolete; it was used by GnuPG versions before 2.1.

  @item PINENTRY_USER_DATA
+  @efindex PINENTRY_USER_DATA
  This value is passed via gpg-agent to pinentry.  It is useful to convey
  extra information to a custom pinentry.

  @item COLUMNS
  @itemx LINES
+  @efindex COLUMNS
+  @efindex LINES
  Used to size some displays to the full size of the screen.

-
  @item LANGUAGE
+  @efindex LANGUAGE
  Apart from its use by GNU, it is used in the W32 version to override the
  language selection done through the Registry.  If used and set to a
  valid and available language name (@var{langid}), the file with the
--- a/doc/gpgsm.texi
+++ b/doc/gpgsm.texi
@ -357,9 +357,7 @@ suite hack and may thus not be used in the file name.
@item --dirmngr-program @var{file}
@opindex dirmngr-program
 Specify a dirmngr program to be used for @acronym{CRL} checks.  The
-default value is @file{@value{BINDIR}/dirmngr}.  This is only used as a
-fallback when the environment variable @code{DIRMNGR_INFO} is not set or
-a running dirmngr cannot be connected.
+default value is @file{@value{BINDIR}/dirmngr}.

@item --prefer-system-dirmngr
@opindex prefer-system-dirmngr
@ -800,7 +798,7 @@ current home directory (@pxref{option --homedir}).
@table @file

@item gpgsm.conf
-@cindex gpgsm.conf
+@efindex gpgsm.conf
 This is the standard configuration file read by @command{gpgsm} on
 startup.  It may contain any valid long option; the leading two dashes
 may not be entered and the option may not be abbreviated.  This default
@ -809,7 +807,7 @@ You should backup this file.


@item policies.txt
-@cindex policies.txt
+@efindex policies.txt
 This is a list of allowed CA policies.  This file should list the
 object identifiers of the policies line by line.  Empty lines and
 lines starting with a hash mark are ignored.  Policies missing in this
@ -829,7 +827,7 @@ like this:
@c man:.RE

@item qualified.txt
-@cindex qualified.txt
+@efindex qualified.txt
 This is the list of root certificates used for qualified certificates.
 They are defined as certificates capable of creating legally binding
 signatures in the same way as handwritten signatures are.  Comments
@ -865,7 +863,7 @@ Because this software has not yet been approved for use with such
 certificates, appropriate notices will be shown to indicate this fact.

@item help.txt
-@cindex help.txt
+@efindex help.txt
 This is plain text file with a few help entries used with
@command{pinentry} as well as a large list of help items for
@command{gpg} and @command{gpgsm}.  The standard file has English help
@ -879,7 +877,7 @@ For a reference of the help file's syntax, please see the installed


@item com-certs.pem
-@cindex com-certs.pem
+@efindex com-certs.pem
 This file is a collection of common certificates used to populated a
 newly created @file{pubring.kbx}.  An administrator may replace this
 file with a custom one.  The format is a concatenation of PEM encoded
@ -901,20 +899,20 @@ they all live in in the current home directory (@pxref{option

@table @file
@item pubring.kbx
-@cindex pubring.kbx
+@efindex pubring.kbx
 This a database file storing the certificates as well as meta
 information.  For debugging purposes the tool @command{kbxutil} may be
 used to show the internal structure of this file.  You should backup
 this file.

@item random_seed
-@cindex random_seed
+@efindex random_seed
 This content of this file is used to maintain the internal state of the
 random number generator across invocations.  The same file is used by
 other programs of this software too.

@item S.gpg-agent
-@cindex S.gpg-agent
+@efindex S.gpg-agent
 If this file exists
@command{gpgsm} will first try to connect to this socket for
 accessing @command{gpg-agent} before starting a new @command{gpg-agent}
@ -1535,18 +1533,25 @@ set to the empty string, and if @code{<STRING>} is given it is set to
 that string.

@item display
+@efindex DISPLAY
 Set the session environment variable @code{DISPLAY} is set to @var{value}.
@item ttyname
+@efindex GPG_TTY
 Set the session environment variable @code{GPG_TTY} is set to @var{value}.
@item ttytype
+@efindex TERM
 Set the session environment variable @code{TERM} is set to @var{value}.
@item lc-ctype
+@efindex LC_CTYPE
 Set the session environment variable @code{LC_CTYPE} is set to @var{value}.
@item lc-messages
+@efindex LC_MESSAGES
 Set the session environment variable @code{LC_MESSAGES} is set to @var{value}.
@item xauthority
+@efindex XAUTHORITY
 Set the session environment variable @code{XAUTHORITY} is set to @var{value}.
@item pinentry-user-data
+@efindex PINENTRY_USER_DATA
 Set the session environment variable @code{PINENTRY_USER_DATA} is set
 to @var{value}.

--- a/doc/opt-homedir.texi
+++ b/doc/opt-homedir.texi
@ -1,6 +1,8 @@
@c This option is included at several places.
@item --homedir @var{dir}
@opindex homedir
+@efindex GNUPGHOME
+@efindex HKCU\Software\GNU\GnuPG:HomeDir
 Set the name of the home directory to @var{dir}. If this 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
@ -12,6 +14,7 @@ On Windows systems it is possible to install GnuPG as a portable
 application.  In this case only this command line option is
 considered, all other ways to set a home directory are ignored.

+@efindex gpgconf.ctl
 To install GnuPG as a portable application under Windows, create an
 empty file name @file{gpgconf.ctl} in the same directory as the tool
@file{gpgconf.exe}.  The root of the installation is than that
--- a/doc/scdaemon.texi
+++ b/doc/scdaemon.texi
@ -222,11 +222,12 @@ This option appends a thread ID to the PID in the log output.

@item --debug-assuan-log-cats @var{cats}
@opindex debug-assuan-log-cats
+@efindex ASSUAN_DEBUG
 Changes the active Libassuan logging categories to @var{cats}.  The
 value for @var{cats} is an unsigned integer given in usual C-Syntax.
 A value of of 0 switches to a default category.  If this option is not
 used the categories are taken from the environment variable
-@samp{ASSUAN_DEBUG}.  Note that this option has only an effect if the
+@code{ASSUAN_DEBUG}.  Note that this option has only an effect if the
 Assuan debug flag has also been with the option @option{--debug}.  For
 a list of categories see the Libassuan manual.

--- a/doc/yat2m.c
+++ b/doc/yat2m.c
@ -705,6 +705,7 @@ proc_texi_cmd (FILE *fp, const char *command, const char *rest, size_t len,
    { "emph",    0, "\\fI", "\\fR" },
    { "w",       1 },
    { "c",       5 },
+    { "efindex", 1 },
    { "opindex", 1 },
    { "cpindex", 1 },
    { "cindex",  1 },