Bug#296367: argp_*(): OPTION_DOC should imply OPTION_NO_USAGE

[Daniel Hartwig <mandyke@gmail.com>]

tags 296367 + patch
quit

> argp options marked as OPTION_DOC are displayed (with the leading --, even)
> on --usage output.  This does not make sense, these are not to be treated as
> options by the parser, so they certainly should not be displayed by --usage,
> let alone with the unexistent leading double-dashes.
>
> This problem can be worked around by always using OPTION_DOC |
> OPTION_NO_USAGE, but the correct behaviour would be for OPTION_DOC to imply
> also OPTION_NO_USAGE.

It would be more flexible to just have the usage messages display
`OPTION_DOC' entries the same way that help messages do (e.g.,
without the `--' prefix).  `OPTION_NO_USAGE' still works to
prevent these options from displaying in the usage.

`OPTION_DOC' is useful to specify the format of complex options
that are not displayed properly by default.  Having them appear
in the usage message in these cases keeps things consistent.

Index: eglibc-2.11.2/argp/argp-help.c
===================================================================
--- eglibc-2.11.2.orig/argp/argp-help.c	2011-08-20 01:15:48.905748547 +0800
+++ eglibc-2.11.2/argp/argp-help.c	2011-08-20 01:23:06.077743593 +0800
@@ -1293,7 +1293,9 @@
 
   if (! (flags & OPTION_NO_USAGE))
     {
-      if (arg)
+      if (flags & OPTION_DOC)
+	__argp_fmtstream_printf (stream, " [%s]", opt->name);
+      else if (arg)
 	{
 	  arg = dgettext (domain, arg);
 	  if (flags & OPTION_ARG_OPTIONAL)

/* Argp OPTION_DOC test */

/* This program makes use of various types of OPTION_DOC options
   to investigate how `--help' and `--usage' behave. */

#include <argp.h>

static struct argp_option options[] = {
  { "arbitrary doc", 0, 0, OPTION_DOC, "Arbitrary option doc" },

  { "--fake-option", 0, 0, OPTION_DOC, "Pretend long option" },
  { "-f",            0, 0, OPTION_DOC, "Pretend short option" },
  { "--no-usage",    0, 0, OPTION_DOC | OPTION_NO_USAGE,
                                       "Option doc with no usage" },

  { "hidden doc",    0, 0, OPTION_DOC | OPTION_HIDDEN,
                                       "Oops! Hidden documentation" },
  { "hidden-nu",     0, 0, OPTION_DOC | OPTION_HIDDEN | OPTION_NO_USAGE,
                                       "Oops! Hidden, with no usage either" },

  { 0,               0, 0, OPTION_DOC, "Group header for tricky cases:" },
  { "--with-key",    'k', 0, OPTION_DOC, "Careful! Contains a key" },
  { "--with-arg",    0, "ARG", OPTION_DOC, "Careful! Contains an arg" },

  { 0 }
};

static struct argp argp = { options };

int
main (int argc, char **argv)
{
  argp_parse (&argp, argc, argv, 0, 0, 0);
  return 0;
}