doc: Update from master
authorWerner Koch <wk@gnupg.org>
Tue, 3 Jun 2014 07:02:00 +0000 (09:02 +0200)
committerWerner Koch <wk@gnupg.org>
Tue, 3 Jun 2014 07:05:25 +0000 (09:05 +0200)
--

doc/gpg.texi
doc/gpgsm.texi
doc/tools.texi
doc/yat2m.c

index f1dee58..a263690 100644 (file)
@@ -906,6 +906,24 @@ Signs a public key with your secret key but marks it as
 non-exportable. This is a shortcut version of the subcommand "lsign"
 from @option{--edit-key}.
 
+@ifset gpgtwoone
+@item --quick-sign-key @code{fpr} [@code{names}]
+@itemx --quick-lsign-key @code{name}
+@opindex quick-sign-key
+@opindex quick-lsign-key
+Directly sign a key from the passphrase without any further user
+interaction.  The @code{fpr} must be the verified primary fingerprint
+of a key in the local keyring. If no @code{names} are given, all
+useful user ids are signed; with given [@code{names}] only useful user
+ids matching one of theses names are signed.  The command
+@option{--quick-lsign-key} marks the signatures as non-exportable.
+
+This command uses reasonable defaults and thus does not provide the
+full flexibility of the "sign" subcommand from @option{--edit-key}.
+Its intended use to help unattended signing using a list of verified
+fingerprints.
+@end ifset
+
 @ifclear gpgone
 @item --passwd @var{user_id}
 @opindex passwd
@@ -1431,7 +1449,9 @@ Set what trust model GnuPG should follow. The models are:
   trusted. You generally won't use this unless you are using some
   external validation scheme. This option also suppresses the
   "[uncertain]" tag printed with signature checks when there is no
-  evidence that the user ID is bound to the key.
+  evidence that the user ID is bound to the key.  Note that this
+  trust model still does not allow the use of expired, revoked, or
+  disabled keys.
 
   @item auto
   @opindex trust-mode:auto
@@ -1482,6 +1502,10 @@ mechanisms, in the order they are to be tried:
   position of this mechanism in the list does not matter.  It is not
   required if @code{local} is also used.
 
+  @item clear
+  Clear all defined mechanisms.  This is useful to override
+  mechanisms given in a config file.
+
 @end table
 
 @item --keyid-format @code{short|0xshort|long|0xlong}
@@ -1606,16 +1630,29 @@ are available for all keyserver types, some common options are:
   program uses internally (libcurl, openldap, etc).
 
   @item check-cert
+@ifset gpgtwoone
+  This option has no more function since GnuPG 2.1.  Use the
+  @code{dirmngr} configuration options instead.
+@end ifset
+@ifclear gpgtwoone
   Enable certificate checking if the keyserver presents one (for hkps or
   ldaps).  Defaults to on.
+@end ifclear
 
   @item ca-cert-file
+@ifset gpgtwoone
+  This option has no more function since GnuPG 2.1.  Use the
+  @code{dirmngr} configuration options instead.
+@end ifset
+@ifclear gpgtwoone
   Provide a certificate store to override the system default.  Only
   necessary if check-cert is enabled, and the keyserver is using a
   certificate that is not present in a system default certificate list.
 
   Note that depending on the SSL library that the keyserver helper is
   built with, this may actually be a directory or a file.
+@end ifclear
+
 @end table
 
 @item --completes-needed @code{n}
@@ -1696,6 +1733,25 @@ been given.  Given that this option is not anymore used by
 @command{gpg2}, it should be avoided if possible.
 @end ifset
 
+
+@ifclear gpgone
+@item --agent-program @var{file}
+@opindex agent-program
+Specify an agent program to be used for secret key operations.  The
+default value is the @file{/usr/bin/gpg-agent}.  This is only used
+as a fallback when the environment variable @code{GPG_AGENT_INFO} is not
+set or a running agent cannot be connected.
+@end ifclear
+
+@ifset gpgtwoone
+@item --dirmngr-program @var{file}
+@opindex dirmngr-program
+Specify a dirmngr program to be used for keyserver access.  The
+default value is @file{/usr/sbin/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.
+@end ifset
+
 @item --lock-once
 @opindex lock-once
 Lock the databases the first time a lock is requested
@@ -2053,6 +2109,15 @@ Since GnuPG 2.0.10, this mode is always used and thus this option is
 obsolete; it does not harm to use it though.
 @end ifclear
 
+@ifset gpgtwoone
+@item --legacy-list-mode
+@opindex legacy-list-mode
+Revert to the pre-2.1 public key list mode.  This only affects the
+human readable output and not the machine interface
+(i.e. @code{--with-colons}).  Note that the legacy format does not
+allow to convey suitable information for elliptic curves.
+@end ifset
+
 @item --with-fingerprint
 @opindex with-fingerprint
 Same as the command @option{--fingerprint} but changes only the format
@@ -2245,8 +2310,8 @@ available, but the MIT release is a good common baseline.
 
 This option implies @option{--rfc1991 --disable-mdc
 --no-force-v4-certs --escape-from-lines --force-v3-sigs
---allow-weak-digest-algos --cipher-algo IDEA --digest-algo
-MD5--compress-algo ZIP}. It also disables @option{--textmode} when
+--allow-weak-digest-algos --cipher-algo IDEA --digest-algo MD5
+--compress-algo ZIP}. It also disables @option{--textmode} when
 encrypting.
 
 @item --pgp6
index f7cedaf..3d2594f 100644 (file)
@@ -350,7 +350,7 @@ as a fallback when the environment variable @code{GPG_AGENT_INFO} is not
 set or a running agent cannot be connected.
 
 @item --dirmngr-program @var{file}
-@opindex dirmnr-program
+@opindex dirmngr-program
 Specify a dirmngr program to be used for @acronym{CRL} checks.  The
 default value is @file{/usr/sbin/dirmngr}.  This is only used as a
 fallback when the environment variable @code{DIRMNGR_INFO} is not set or
index be1233b..32ab1e4 100644 (file)
@@ -305,12 +305,22 @@ Reload all or the given component. This is basically the same as sending
 a SIGHUP to the component.  Components which don't support reloading are
 ignored.
 
+@ifset gpgtwoone
+@item --launch [@var{component}]
+@opindex launch
+If the @var{component} is not already running, start it.
+@command{component} must be a daemon.  This is in general not required
+because the system starts these daemons as needed.  However, external
+software making direct use of @command{gpg-agent} or @command{dirmngr}
+may use this command to ensure that they are started.
+
 @item --kill [@var{component}]
 @opindex kill
 Kill the given component.  Components which support killing are
 gpg-agent and scdaemon.  Components which don't support reloading are
 ignored.  Note that as of now reload and kill have the same effect for
 scdaemon.
+@end ifset
 
 @end table
 
@@ -1190,6 +1200,18 @@ Try to be as quiet as possible.
 @opindex agent-program
 Specify the agent program to be started if none is running.
 
+@ifset gpgtwoone
+@item --dirmngr-program @var{file}
+@opindex dirmngr-program
+Specify the directory manager (keyserver client) program to be started
+if none is running.  This has only an effect if used together with the
+option @option{--dirmngr}.
+
+@item --dirmngr
+@opindex dirmngr
+Connect to a running directory manager (keyserver client) instead of
+to the gpg-agent.  If a dirmngr is not running, start it.
+@end ifset
 
 @item -S
 @itemx --raw-socket @var{name}
index 5dc81bf..2ac4390 100644 (file)
@@ -1,5 +1,5 @@
 /* yat2m.c - Yet Another Texi 2 Man converter
- *     Copyright (C) 2005 g10 Code GmbH
+ *     Copyright (C) 2005, 2013 g10 Code GmbH
  *      Copyright (C) 2006, 2008, 2011 Free Software Foundation, Inc.
  *
  * This program is free software; you can redistribute it and/or modify
@@ -17,7 +17,7 @@
  */
 
 /*
-    This is a simple textinfo to man page converter.  It needs some
+    This is a simple texinfo to man page converter.  It needs some
     special markup in th e texinfo and tries best to get a create man
     page.  It has been designed for the GnuPG man pages and thus only
     a few texinfo commands are supported.
    character. */
 #define LINESIZE 1024
 
+/* Number of allowed condition nestings.  */
+#define MAX_CONDITION_NESTING  10
+
 /* Option flags. */
 static int verbose;
 static int quiet;
@@ -117,10 +120,6 @@ static const char *opt_select;
 static const char *opt_include;
 static int opt_store;
 
-/* The only define we understand is -D gpgone.  Thus we need a simple
-   boolean tro track it. */
-static int gpgone_defined;
-
 /* Flag to keep track whether any error occurred.  */
 static int any_error;
 
@@ -129,7 +128,7 @@ static int any_error;
 struct macro_s
 {
   struct macro_s *next;
-  char *value;  /* Malloced value. */
+  char *value;    /* Malloced value. */
   char name[1];
 };
 typedef struct macro_s *macro_t;
@@ -137,6 +136,24 @@ typedef struct macro_s *macro_t;
 /* List of all defined macros. */
 static macro_t macrolist;
 
+/* List of global macro names.  The value part is not used.  */
+static macro_t predefinedmacrolist;
+
+/* Object to keep track of @isset and @ifclear.  */
+struct condition_s
+{
+  int manverb;   /* "manverb" needs special treatment.  */
+  int isset;     /* This is an @isset condition.  */
+  char name[1];  /* Name of the condition macro.  */
+};
+typedef struct condition_s *condition_t;
+
+/* The stack used to evaluate conditions.  And the current states. */
+static condition_t condition_stack[MAX_CONDITION_NESTING];
+static int condition_stack_idx;
+static int cond_is_active;     /* State of ifset/ifclear */
+static int cond_in_verbatim;   /* State of "manverb".  */
+
 
 /* Object to store one line of content.  */
 struct line_buffer_s
@@ -313,7 +330,158 @@ isodatestring (void)
 }
 
 
+/* Add NAME to the list of predefined macros which are global for all
+   files.  */
+static void
+add_predefined_macro (const char *name)
+{
+  macro_t m;
+
+  for (m=predefinedmacrolist; m; m = m->next)
+    if (!strcmp (m->name, name))
+      break;
+  if (!m)
+    {
+      m = xcalloc (1, sizeof *m + strlen (name));
+      strcpy (m->name, name);
+      m->next = predefinedmacrolist;
+      predefinedmacrolist = m;
+    }
+}
+
+
+/* Create or update a macro with name MACRONAME and set its values TO
+   MACROVALUE.  Note that ownership of the macro value is transferred
+   to this function.  */
+static void
+set_macro (const char *macroname, char *macrovalue)
+{
+  macro_t m;
+
+  for (m=macrolist; m; m = m->next)
+    if (!strcmp (m->name, macroname))
+      break;
+  if (m)
+    free (m->value);
+  else
+    {
+      m = xcalloc (1, sizeof *m + strlen (macroname));
+      strcpy (m->name, macroname);
+      m->next = macrolist;
+      macrolist = m;
+    }
+  m->value = macrovalue;
+  macrovalue = NULL;
+}
+
+
+/* Return true if the macro NAME is set, i.e. not the empty string and
+   not evaluating to 0.  */
+static int
+macro_set_p (const char *name)
+{
+  macro_t m;
+
+  for (m = macrolist; m ; m = m->next)
+    if (!strcmp (m->name, name))
+      break;
+  if (!m || !m->value || !*m->value)
+    return 0;
+  if ((*m->value & 0x80) || !isdigit (*m->value))
+    return 1; /* Not a digit but some other string.  */
+  return !!atoi (m->value);
+}
+
+
+/* Evaluate the current conditions.  */
+static void
+evaluate_conditions (const char *fname, int lnr)
+{
+  int i;
+
+  /* for (i=0; i < condition_stack_idx; i++) */
+  /*   inf ("%s:%d:   stack[%d] %s %s %c", */
+  /*        fname, lnr, i, condition_stack[i]->isset? "set":"clr", */
+  /*        condition_stack[i]->name, */
+  /*        (macro_set_p (condition_stack[i]->name) */
+  /*         ^ !condition_stack[i]->isset)? 't':'f'); */
+
+  cond_is_active = 1;
+  cond_in_verbatim = 0;
+  if (condition_stack_idx)
+    {
+      for (i=0; i < condition_stack_idx; i++)
+        {
+          if (condition_stack[i]->manverb)
+            cond_in_verbatim = (macro_set_p (condition_stack[i]->name)
+                                ^ !condition_stack[i]->isset);
+          else if (!(macro_set_p (condition_stack[i]->name)
+                     ^ !condition_stack[i]->isset))
+            {
+              cond_is_active = 0;
+              break;
+            }
+        }
+    }
+
+  /* inf ("%s:%d:   active=%d verbatim=%d", */
+  /*      fname, lnr, cond_is_active, cond_in_verbatim); */
+}
+
+
+/* Push a condition with condition macro NAME onto the stack.  If
+   ISSET is true, a @isset condition is pushed.  */
+static void
+push_condition (const char *name, int isset, const char *fname, int lnr)
+{
+  condition_t cond;
+  int manverb = 0;
 
+  if (condition_stack_idx >= MAX_CONDITION_NESTING)
+    {
+      err ("%s:%d: condition nested too deep", fname, lnr);
+      return;
+    }
+
+  if (!strcmp (name, "manverb"))
+    {
+      if (!isset)
+        {
+          err ("%s:%d: using \"@ifclear manverb\" is not allowed", fname, lnr);
+          return;
+        }
+      manverb = 1;
+    }
+
+  cond = xcalloc (1, sizeof *cond + strlen (name));
+  cond->manverb = manverb;
+  cond->isset = isset;
+  strcpy (cond->name, name);
+
+  condition_stack[condition_stack_idx++] = cond;
+  evaluate_conditions (fname, lnr);
+}
+
+
+/* Remove the last condition from the stack.  ISSET is used for error
+   reporting.  */
+static void
+pop_condition (int isset, const char *fname, int lnr)
+{
+  if (!condition_stack_idx)
+    {
+      err ("%s:%d: unbalanced \"@end %s\"",
+           fname, lnr, isset?"isset":"isclear");
+      return;
+    }
+  condition_stack_idx--;
+  free (condition_stack[condition_stack_idx]);
+  condition_stack[condition_stack_idx] = NULL;
+  evaluate_conditions (fname, lnr);
+}
+
+
+\f
 /* Return a section buffer for the section NAME.  Allocate a new buffer
    if this is a new section.  Keep track of the sections in THEPAGE.
    This function may reallocate the section array in THEPAGE.  */
@@ -862,14 +1030,8 @@ parse_file (const char *fname, FILE *fp, char **section_name, int in_pause)
   int lnr = 0;
   /* Fixme: The following state variables don't carry over to include
      files. */
-  int in_verbatim = 0;
   int skip_to_end = 0;        /* Used to skip over menu entries. */
   int skip_sect_line = 0;     /* Skip after @mansect.  */
-  int ifset_nesting = 0;      /* How often a ifset has been seen. */
-  int ifclear_nesting = 0;    /* How often a ifclear has been seen. */
-  int in_gpgone = 0;          /* Keep track of "@ifset gpgone" parts.  */
-  int not_in_gpgone = 0;      /* Keep track of "@ifclear gpgone" parts.  */
-  int not_in_man = 0;         /* Keep track of "@ifclear isman" parts.  */
   int item_indent = 0;        /* How far is the current @item indented.  */
 
   /* Helper to define a macro. */
@@ -883,7 +1045,7 @@ parse_file (const char *fname, FILE *fp, char **section_name, int in_pause)
     {
       size_t n = strlen (line);
       int got_line = 0;
-      char *p;
+      char *p, *pend;
 
       lnr++;
       if (!n || line[n-1] != '\n')
@@ -930,26 +1092,12 @@ parse_file (const char *fname, FILE *fp, char **section_name, int in_pause)
               && !strncmp (p, "macro", 5)
               && (p[5]==' '||p[5]=='\t'||!p[5]))
             {
-              macro_t m;
-
               if (macrovalueused)
                 macrovalue[--macrovalueused] = 0; /* Kill the last LF. */
               macrovalue[macrovalueused] = 0;     /* Terminate macro. */
               macrovalue = xrealloc (macrovalue, macrovalueused+1);
 
-              for (m= macrolist; m; m = m->next)
-                if (!strcmp (m->name, macroname))
-                  break;
-              if (m)
-                free (m->value);
-              else
-                {
-                  m = xcalloc (1, sizeof *m + strlen (macroname));
-                  strcpy (m->name, macroname);
-                  m->next = macrolist;
-                  macrolist = m;
-                }
-              m->value = macrovalue;
+              set_macro (macroname, macrovalue);
               macrovalue = NULL;
               free (macroname);
               macroname = NULL;
@@ -997,23 +1145,33 @@ parse_file (const char *fname, FILE *fp, char **section_name, int in_pause)
           if (n == 6 && !memcmp (line, "@ifset", 6)
                    && (line[6]==' '||line[6]=='\t'))
             {
-              ifset_nesting++;
-
-              if (!strncmp (p, "manverb", 7) && (p[7]==' '||p[7]=='\t'||!p[7]))
+              for (p=line+7; *p == ' ' || *p == '\t'; p++)
+                ;
+              if (!*p)
                 {
-                  if (in_verbatim)
-                    err ("%s:%d: nested \"@ifset manverb\"", fname, lnr);
-                  else
-                    in_verbatim = ifset_nesting;
+                  err ("%s:%d: name missing after \"@ifset\"", fname, lnr);
+                  continue;
                 }
-              else if (!strncmp (p, "gpgone", 6)
-                       && (p[6]==' '||p[6]=='\t'||!p[6]))
+              for (pend=p; *pend && *pend != ' ' && *pend != '\t'; pend++)
+                ;
+              *pend = 0;  /* Ignore rest of the line.  */
+              push_condition (p, 1, fname, lnr);
+              continue;
+            }
+          else if (n == 8 && !memcmp (line, "@ifclear", 8)
+                   && (line[8]==' '||line[8]=='\t'))
+            {
+              for (p=line+9; *p == ' ' || *p == '\t'; p++)
+                ;
+              if (!*p)
                 {
-                  if (in_gpgone)
-                    err ("%s:%d: nested \"@ifset gpgone\"", fname, lnr);
-                  else
-                    in_gpgone = ifset_nesting;
+                  err ("%s:%d: name missing after \"@ifsclear\"", fname, lnr);
+                  continue;
                 }
+              for (pend=p; *pend && *pend != ' ' && *pend != '\t'; pend++)
+                ;
+              *pend = 0;  /* Ignore rest of the line.  */
+              push_condition (p, 0, fname, lnr);
               continue;
             }
           else if (n == 4 && !memcmp (line, "@end", 4)
@@ -1021,40 +1179,7 @@ parse_file (const char *fname, FILE *fp, char **section_name, int in_pause)
                    && !strncmp (p, "ifset", 5)
                    && (p[5]==' '||p[5]=='\t'||!p[5]))
             {
-              if (in_verbatim && ifset_nesting == in_verbatim)
-                in_verbatim = 0;
-              if (in_gpgone && ifset_nesting == in_gpgone)
-                in_gpgone = 0;
-
-              if (ifset_nesting)
-                ifset_nesting--;
-              else
-                err ("%s:%d: unbalanced \"@end ifset\"", fname, lnr);
-              continue;
-            }
-          else if (n == 8 && !memcmp (line, "@ifclear", 8)
-                   && (line[8]==' '||line[8]=='\t'))
-            {
-              ifclear_nesting++;
-
-              if (!strncmp (p, "gpgone", 6)
-                  && (p[6]==' '||p[6]=='\t'||!p[6]))
-                {
-                  if (not_in_gpgone)
-                    err ("%s:%d: nested \"@ifclear gpgone\"", fname, lnr);
-                  else
-                    not_in_gpgone = ifclear_nesting;
-                }
-
-              else if (!strncmp (p, "isman", 5)
-                       && (p[5]==' '||p[5]=='\t'||!p[5]))
-                {
-                  if (not_in_man)
-                    err ("%s:%d: nested \"@ifclear isman\"", fname, lnr);
-                  else
-                    not_in_man = ifclear_nesting;
-                }
-
+              pop_condition (1, fname, lnr);
               continue;
             }
           else if (n == 4 && !memcmp (line, "@end", 4)
@@ -1062,23 +1187,13 @@ parse_file (const char *fname, FILE *fp, char **section_name, int in_pause)
                    && !strncmp (p, "ifclear", 7)
                    && (p[7]==' '||p[7]=='\t'||!p[7]))
             {
-              if (not_in_gpgone && ifclear_nesting == not_in_gpgone)
-                not_in_gpgone = 0;
-              if (not_in_man && ifclear_nesting == not_in_man)
-                not_in_man = 0;
-
-              if (ifclear_nesting)
-                ifclear_nesting--;
-              else
-                err ("%s:%d: unbalanced \"@end ifclear\"", fname, lnr);
+              pop_condition (0, fname, lnr);
               continue;
             }
         }
 
       /* Take action on ifset/ifclear.  */
-      if ( (in_gpgone && !gpgone_defined)
-           || (not_in_gpgone && gpgone_defined)
-           || not_in_man)
+      if (!cond_is_active)
         continue;
 
       /* Process commands. */
@@ -1090,7 +1205,7 @@ parse_file (const char *fname, FILE *fp, char **section_name, int in_pause)
             {
               skip_to_end = 0;
             }
-          else if (in_verbatim)
+          else if (cond_in_verbatim)
             {
                 got_line = 1;
             }
@@ -1182,7 +1297,7 @@ parse_file (const char *fname, FILE *fp, char **section_name, int in_pause)
       else if (!skip_to_end)
         got_line = 1;
 
-      if (got_line && in_verbatim)
+      if (got_line && cond_in_verbatim)
         add_content (*section_name, line, 1);
       else if (got_line && thepage.name && *section_name && !in_pause)
         add_content (*section_name, line, 0);
@@ -1201,6 +1316,8 @@ top_parse_file (const char *fname, FILE *fp)
 {
   char *section_name = NULL;  /* Name of the current section or NULL
                                  if not in a section.  */
+  macro_t m;
+
   while (macrolist)
     {
       macro_t next = macrolist->next;
@@ -1208,6 +1325,10 @@ top_parse_file (const char *fname, FILE *fp)
       free (macrolist);
       macrolist = next;
     }
+  for (m=predefinedmacrolist; m; m = m->next)
+    set_macro (m->name, xstrdup ("1"));
+  cond_is_active = 1;
+  cond_in_verbatim = 0;
 
   parse_file (fname, fp, &section_name, 0);
   free (section_name);
@@ -1223,6 +1344,12 @@ main (int argc, char **argv)
   opt_source = "GNU";
   opt_release = "";
 
+  /* Define default macros.  The trick is that these macros are not
+     defined when using the actual texinfo renderer. */
+  add_predefined_macro ("isman");
+  add_predefined_macro ("manverb");
+
+  /* Option parsing.  */
   if (argc)
     {
       argc--; argv++;
@@ -1327,8 +1454,7 @@ main (int argc, char **argv)
           argc--; argv++;
           if (argc)
             {
-              if (!strcmp (*argv, "gpgone"))
-                gpgone_defined = 1;
+              add_predefined_macro (*argv);
               argc--; argv++;
             }
         }