Remove last bits of using gettext instead of dgettext.
[kopensolaris-gnu/glibc.git] / argp / argp-help.c
1 /* Hierarchial argument parsing help output
2    Copyright (C) 1995, 1996, 1997, 1998 Free Software Foundation, Inc.
3    This file is part of the GNU C Library.
4    Written by Miles Bader <miles@gnu.ai.mit.edu>.
5
6    The GNU C Library is free software; you can redistribute it and/or
7    modify it under the terms of the GNU Library General Public License as
8    published by the Free Software Foundation; either version 2 of the
9    License, or (at your option) any later version.
10
11    The GNU C Library is distributed in the hope that it will be useful,
12    but WITHOUT ANY WARRANTY; without even the implied warranty of
13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14    Library General Public License for more details.
15
16    You should have received a copy of the GNU Library General Public
17    License along with the GNU C Library; see the file COPYING.LIB.  If not,
18    write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19    Boston, MA 02111-1307, USA.  */
20
21 #ifdef HAVE_CONFIG_H
22 #include <config.h>
23 #endif
24
25 #include <stddef.h>
26 #include <stdlib.h>
27 #include <string.h>
28 #include <assert.h>
29 #include <stdarg.h>
30 #include <malloc.h>
31 #include <ctype.h>
32
33 #ifndef _
34 /* This is for other GNU distributions with internationalized messages.  */
35 #ifdef HAVE_LIBINTL_H
36 # include <libintl.h>
37 #else
38 # define dgettext(domain, msgid) (msgid)
39 #endif
40 #endif
41
42 #include "argp.h"
43 #include "argp-fmtstream.h"
44 #include "argp-namefrob.h"
45 \f
46 /* User-selectable (using an environment variable) formatting parameters.
47
48    These may be specified in an environment variable called `ARGP_HELP_FMT',
49    with a contents like:  VAR1=VAL1,VAR2=VAL2,BOOLVAR2,no-BOOLVAR2
50    Where VALn must be a positive integer.  The list of variables is in the
51    UPARAM_NAMES vector, below.  */
52
53 /* Default parameters.  */
54 #define DUP_ARGS      0         /* True if option argument can be duplicated. */
55 #define DUP_ARGS_NOTE 1         /* True to print a note about duplicate args. */
56 #define SHORT_OPT_COL 2         /* column in which short options start */
57 #define LONG_OPT_COL  6         /* column in which long options start */
58 #define DOC_OPT_COL   2         /* column in which doc options start */
59 #define OPT_DOC_COL  29         /* column in which option text starts */
60 #define HEADER_COL    1         /* column in which group headers are printed */
61 #define USAGE_INDENT 12         /* indentation of wrapped usage lines */
62 #define RMARGIN      79         /* right margin used for wrapping */
63
64 /* User-selectable (using an environment variable) formatting parameters.
65    They must all be of type `int' for the parsing code to work.  */
66 struct uparams
67 {
68   /* If true, arguments for an option are shown with both short and long
69      options, even when a given option has both, e.g. `-x ARG, --longx=ARG'.
70      If false, then if an option has both, the argument is only shown with
71      the long one, e.g., `-x, --longx=ARG', and a message indicating that
72      this really means both is printed below the options.  */
73   int dup_args;
74
75   /* This is true if when DUP_ARGS is false, and some duplicate arguments have
76      been suppressed, an explanatory message should be printed.  */
77   int dup_args_note;
78
79   /* Various output columns.  */
80   int short_opt_col;
81   int long_opt_col;
82   int doc_opt_col;
83   int opt_doc_col;
84   int header_col;
85   int usage_indent;
86   int rmargin;
87
88   int valid;                    /* True when the values in here are valid.  */
89 };
90
91 /* This is a global variable, as user options are only ever read once.  */
92 static struct uparams uparams = {
93   DUP_ARGS, DUP_ARGS_NOTE,
94   SHORT_OPT_COL, LONG_OPT_COL, DOC_OPT_COL, OPT_DOC_COL, HEADER_COL,
95   USAGE_INDENT, RMARGIN,
96   0
97 };
98
99 /* A particular uparam, and what the user name is.  */
100 struct uparam_name
101 {
102   const char *name;             /* User name.  */
103   int is_bool;                  /* Whether it's `boolean'.  */
104   size_t uparams_offs;          /* Location of the (int) field in UPARAMS.  */
105 };
106
107 /* The name-field mappings we know about.  */
108 static const struct uparam_name uparam_names[] =
109 {
110   { "dup-args",       1, offsetof (struct uparams, dup_args) },
111   { "dup-args-note",  1, offsetof (struct uparams, dup_args_note) },
112   { "short-opt-col",  0, offsetof (struct uparams, short_opt_col) },
113   { "long-opt-col",   0, offsetof (struct uparams, long_opt_col) },
114   { "doc-opt-col",    0, offsetof (struct uparams, doc_opt_col) },
115   { "opt-doc-col",    0, offsetof (struct uparams, opt_doc_col) },
116   { "header-col",     0, offsetof (struct uparams, header_col) },
117   { "usage-indent",   0, offsetof (struct uparams, usage_indent) },
118   { "rmargin",        0, offsetof (struct uparams, rmargin) },
119   { 0 }
120 };
121
122 /* Read user options from the environment, and fill in UPARAMS appropiately.  */
123 static void
124 fill_in_uparams (const struct argp_state *state)
125 {
126   const char *var = getenv ("ARGP_HELP_FMT");
127
128 #define SKIPWS(p) do { while (isspace (*p)) p++; } while (0);
129
130   if (var)
131     /* Parse var. */
132     while (*var)
133       {
134         SKIPWS (var);
135
136         if (isalpha (*var))
137           {
138             size_t var_len;
139             const struct uparam_name *un;
140             int unspec = 0, val = 0;
141             const char *arg = var;
142
143             while (isalnum (*arg) || *arg == '-' || *arg == '_')
144               arg++;
145             var_len = arg - var;
146
147             SKIPWS (arg);
148
149             if (*arg == '\0' || *arg == ',')
150               unspec = 1;
151             else if (*arg == '=')
152               {
153                 arg++;
154                 SKIPWS (arg);
155               }
156
157             if (unspec)
158               if (var[0] == 'n' && var[1] == 'o' && var[2] == '-')
159                 {
160                   val = 0;
161                   var += 3;
162                   var_len -= 3;
163                 }
164               else
165                 val = 1;
166             else if (isdigit (*arg))
167               {
168                 val = atoi (arg);
169                 while (isdigit (*arg))
170                   arg++;
171                 SKIPWS (arg);
172               }
173
174             for (un = uparam_names; un->name; un++)
175               if (strlen (un->name) == var_len
176                   && strncmp (var, un->name, var_len) == 0)
177                 {
178                   if (unspec && !un->is_bool)
179                     __argp_failure (state, 0, 0,
180                                     dgettext (state->root_argp->argp_domain, "\
181 %.*s: ARGP_HELP_FMT parameter requires a value"),
182                                     (int) var_len, var);
183                   else
184                     *(int *)((char *)&uparams + un->uparams_offs) = val;
185                   break;
186                 }
187             if (! un->name)
188               __argp_failure (state, 0, 0,
189                               dgettext (state->root_argp->argp_domain, "\
190 %.*s: Unknown ARGP_HELP_FMT parameter"),
191                               (int) var_len, var);
192
193             var = arg;
194             if (*var == ',')
195               var++;
196           }
197         else if (*var)
198           {
199             __argp_failure (state, 0, 0,
200                             dgettext (state->root_argp->argp_domain,
201                                       "Garbage in ARGP_HELP_FMT: %s"), var);
202             break;
203           }
204       }
205 }
206 \f
207 /* Returns true if OPT hasn't been marked invisible.  Visibility only affects
208    whether OPT is displayed or used in sorting, not option shadowing.  */
209 #define ovisible(opt) (! ((opt)->flags & OPTION_HIDDEN))
210
211 /* Returns true if OPT is an alias for an earlier option.  */
212 #define oalias(opt) ((opt)->flags & OPTION_ALIAS)
213
214 /* Returns true if OPT is an documentation-only entry.  */
215 #define odoc(opt) ((opt)->flags & OPTION_DOC)
216
217 /* Returns true if OPT is the end-of-list marker for a list of options.  */
218 #define oend(opt) __option_is_end (opt)
219
220 /* Returns true if OPT has a short option.  */
221 #define oshort(opt) __option_is_short (opt)
222 \f
223 /*
224    The help format for a particular option is like:
225
226      -xARG, -yARG, --long1=ARG, --long2=ARG        Documentation...
227
228    Where ARG will be omitted if there's no argument, for this option, or
229    will be surrounded by "[" and "]" appropiately if the argument is
230    optional.  The documentation string is word-wrapped appropiately, and if
231    the list of options is long enough, it will be started on a separate line.
232    If there are no short options for a given option, the first long option is
233    indented slighly in a way that's supposed to make most long options appear
234    to be in a separate column.
235
236    For example, the following output (from ps):
237
238      -p PID, --pid=PID          List the process PID
239          --pgrp=PGRP            List processes in the process group PGRP
240      -P, -x, --no-parent        Include processes without parents
241      -Q, --all-fields           Don't elide unusable fields (normally if there's
242                                 some reason ps can't print a field for any
243                                 process, it's removed from the output entirely)
244      -r, --reverse, --gratuitously-long-reverse-option
245                                 Reverse the order of any sort
246          --session[=SID]        Add the processes from the session SID (which
247                                 defaults to the sid of the current process)
248
249     Here are some more options:
250      -f ZOT, --foonly=ZOT       Glork a foonly
251      -z, --zaza                 Snit a zar
252
253      -?, --help                 Give this help list
254          --usage                Give a short usage message
255      -V, --version              Print program version
256
257    The struct argp_option array for the above could look like:
258
259    {
260      {"pid",       'p',      "PID",  0, "List the process PID"},
261      {"pgrp",      OPT_PGRP, "PGRP", 0, "List processes in the process group PGRP"},
262      {"no-parent", 'P',       0,     0, "Include processes without parents"},
263      {0,           'x',       0,     OPTION_ALIAS},
264      {"all-fields",'Q',       0,     0, "Don't elide unusable fields (normally"
265                                         " if there's some reason ps can't"
266                                         " print a field for any process, it's"
267                                         " removed from the output entirely)" },
268      {"reverse",   'r',       0,     0, "Reverse the order of any sort"},
269      {"gratuitously-long-reverse-option", 0, 0, OPTION_ALIAS},
270      {"session",   OPT_SESS,  "SID", OPTION_ARG_OPTIONAL,
271                                         "Add the processes from the session"
272                                         " SID (which defaults to the sid of"
273                                         " the current process)" },
274
275      {0,0,0,0, "Here are some more options:"},
276      {"foonly", 'f', "ZOT", 0, "Glork a foonly"},
277      {"zaza", 'z', 0, 0, "Snit a zar"},
278
279      {0}
280    }
281
282    Note that the last three options are automatically supplied by argp_parse,
283    unless you tell it not to with ARGP_NO_HELP.
284
285 */
286 \f
287 /* Returns true if CH occurs between BEG and END.  */
288 static int
289 find_char (char ch, char *beg, char *end)
290 {
291   while (beg < end)
292     if (*beg == ch)
293       return 1;
294     else
295       beg++;
296   return 0;
297 }
298 \f
299 struct hol_cluster;             /* fwd decl */
300
301 struct hol_entry
302 {
303   /* First option.  */
304   const struct argp_option *opt;
305   /* Number of options (including aliases).  */
306   unsigned num;
307
308   /* A pointers into the HOL's short_options field, to the first short option
309      letter for this entry.  The order of the characters following this point
310      corresponds to the order of options pointed to by OPT, and there are at
311      most NUM.  A short option recorded in a option following OPT is only
312      valid if it occurs in the right place in SHORT_OPTIONS (otherwise it's
313      probably been shadowed by some other entry).  */
314   char *short_options;
315
316   /* Entries are sorted by their group first, in the order:
317        1, 2, ..., n, 0, -m, ..., -2, -1
318      and then alphabetically within each group.  The default is 0.  */
319   int group;
320
321   /* The cluster of options this entry belongs to, or 0 if none.  */
322   struct hol_cluster *cluster;
323
324   /* The argp from which this option came.  */
325   const struct argp *argp;
326 };
327
328 /* A cluster of entries to reflect the argp tree structure.  */
329 struct hol_cluster
330 {
331   /* A descriptive header printed before options in this cluster.  */
332   const char *header;
333
334   /* Used to order clusters within the same group with the same parent,
335      according to the order in which they occured in the parent argp's child
336      list.  */
337   int index;
338
339   /* How to sort this cluster with respect to options and other clusters at the
340      same depth (clusters always follow options in the same group).  */
341   int group;
342
343   /* The cluster to which this cluster belongs, or 0 if it's at the base
344      level.  */
345   struct hol_cluster *parent;
346
347   /* The argp from which this cluster is (eventually) derived.  */
348   const struct argp *argp;
349
350   /* The distance this cluster is from the root.  */
351   int depth;
352
353   /* Clusters in a given hol are kept in a linked list, to make freeing them
354      possible.  */
355   struct hol_cluster *next;
356 };
357
358 /* A list of options for help.  */
359 struct hol
360 {
361   /* An array of hol_entry's.  */
362   struct hol_entry *entries;
363   /* The number of entries in this hol.  If this field is zero, the others
364      are undefined.  */
365   unsigned num_entries;
366
367   /* A string containing all short options in this HOL.  Each entry contains
368      pointers into this string, so the order can't be messed with blindly.  */
369   char *short_options;
370
371   /* Clusters of entries in this hol.  */
372   struct hol_cluster *clusters;
373 };
374 \f
375 /* Create a struct hol from the options in ARGP.  CLUSTER is the
376    hol_cluster in which these entries occur, or 0, if at the root.  */
377 static struct hol *
378 make_hol (const struct argp *argp, struct hol_cluster *cluster)
379 {
380   char *so;
381   const struct argp_option *o;
382   const struct argp_option *opts = argp->options;
383   struct hol_entry *entry;
384   unsigned num_short_options = 0;
385   struct hol *hol = malloc (sizeof (struct hol));
386
387   assert (hol);
388
389   hol->num_entries = 0;
390   hol->clusters = 0;
391
392   if (opts)
393     {
394       int cur_group = 0;
395
396       /* The first option must not be an alias.  */
397       assert (! oalias (opts));
398
399       /* Calculate the space needed.  */
400       for (o = opts; ! oend (o); o++)
401         {
402           if (! oalias (o))
403             hol->num_entries++;
404           if (oshort (o))
405             num_short_options++;        /* This is an upper bound.  */
406         }
407
408       hol->entries = malloc (sizeof (struct hol_entry) * hol->num_entries);
409       hol->short_options = malloc (num_short_options + 1);
410
411       assert (hol->entries && hol->short_options);
412
413       /* Fill in the entries.  */
414       so = hol->short_options;
415       for (o = opts, entry = hol->entries; ! oend (o); entry++)
416         {
417           entry->opt = o;
418           entry->num = 0;
419           entry->short_options = so;
420           entry->group = cur_group =
421             o->group
422             ? o->group
423             : ((!o->name && !o->key)
424                ? cur_group + 1
425                : cur_group);
426           entry->cluster = cluster;
427           entry->argp = argp;
428
429           do
430             {
431               entry->num++;
432               if (oshort (o) && ! find_char (o->key, hol->short_options, so))
433                 /* O has a valid short option which hasn't already been used.*/
434                 *so++ = o->key;
435               o++;
436             }
437           while (! oend (o) && oalias (o));
438         }
439       *so = '\0';               /* null terminated so we can find the length */
440     }
441
442   return hol;
443 }
444 \f
445 /* Add a new cluster to HOL, with the given GROUP and HEADER (taken from the
446    associated argp child list entry), INDEX, and PARENT, and return a pointer
447    to it.  ARGP is the argp that this cluster results from.  */
448 static struct hol_cluster *
449 hol_add_cluster (struct hol *hol, int group, const char *header, int index,
450                  struct hol_cluster *parent, const struct argp *argp)
451 {
452   struct hol_cluster *cl = malloc (sizeof (struct hol_cluster));
453   if (cl)
454     {
455       cl->group = group;
456       cl->header = header;
457
458       cl->index = index;
459       cl->parent = parent;
460       cl->argp = argp;
461       cl->depth = parent ? parent->depth + 1 : 0;
462
463       cl->next = hol->clusters;
464       hol->clusters = cl;
465     }
466   return cl;
467 }
468 \f
469 /* Free HOL and any resources it uses.  */
470 static void
471 hol_free (struct hol *hol)
472 {
473   struct hol_cluster *cl = hol->clusters;
474
475   while (cl)
476     {
477       struct hol_cluster *next = cl->next;
478       free (cl);
479       cl = next;
480     }
481
482   if (hol->num_entries > 0)
483     {
484       free (hol->entries);
485       free (hol->short_options);
486     }
487
488   free (hol);
489 }
490 \f
491 static inline int
492 hol_entry_short_iterate (const struct hol_entry *entry,
493                          int (*func)(const struct argp_option *opt,
494                                      const struct argp_option *real,
495                                      const char *domain, void *cookie),
496                          const char *domain, void *cookie)
497 {
498   unsigned nopts;
499   int val = 0;
500   const struct argp_option *opt, *real = entry->opt;
501   char *so = entry->short_options;
502
503   for (opt = real, nopts = entry->num; nopts > 0 && !val; opt++, nopts--)
504     if (oshort (opt) && *so == opt->key)
505       {
506         if (!oalias (opt))
507           real = opt;
508         if (ovisible (opt))
509           val = (*func)(opt, real, domain, cookie);
510         so++;
511       }
512
513   return val;
514 }
515
516 static inline int
517 hol_entry_long_iterate (const struct hol_entry *entry,
518                         int (*func)(const struct argp_option *opt,
519                                     const struct argp_option *real,
520                                     const char *domain, void *cookie),
521                         const char *domain, void *cookie)
522 {
523   unsigned nopts;
524   int val = 0;
525   const struct argp_option *opt, *real = entry->opt;
526
527   for (opt = real, nopts = entry->num; nopts > 0 && !val; opt++, nopts--)
528     if (opt->name)
529       {
530         if (!oalias (opt))
531           real = opt;
532         if (ovisible (opt))
533           val = (*func)(opt, real, domain, cookie);
534       }
535
536   return val;
537 }
538 \f
539 /* Iterator that returns true for the first short option.  */
540 static inline int
541 until_short (const struct argp_option *opt, const struct argp_option *real,
542              const char *domain, void *cookie)
543 {
544   return oshort (opt) ? opt->key : 0;
545 }
546
547 /* Returns the first valid short option in ENTRY, or 0 if there is none.  */
548 static char
549 hol_entry_first_short (const struct hol_entry *entry)
550 {
551   return hol_entry_short_iterate (entry, until_short,
552                                   entry->argp->argp_domain, 0);
553 }
554
555 /* Returns the first valid long option in ENTRY, or 0 if there is none.  */
556 static const char *
557 hol_entry_first_long (const struct hol_entry *entry)
558 {
559   const struct argp_option *opt;
560   unsigned num;
561   for (opt = entry->opt, num = entry->num; num > 0; opt++, num--)
562     if (opt->name && ovisible (opt))
563       return opt->name;
564   return 0;
565 }
566
567 /* Returns the entry in HOL with the long option name NAME, or 0 if there is
568    none.  */
569 static struct hol_entry *
570 hol_find_entry (struct hol *hol, const char *name)
571 {
572   struct hol_entry *entry = hol->entries;
573   unsigned num_entries = hol->num_entries;
574
575   while (num_entries-- > 0)
576     {
577       const struct argp_option *opt = entry->opt;
578       unsigned num_opts = entry->num;
579
580       while (num_opts-- > 0)
581         if (opt->name && ovisible (opt) && strcmp (opt->name, name) == 0)
582           return entry;
583         else
584           opt++;
585
586       entry++;
587     }
588
589   return 0;
590 }
591 \f
592 /* If an entry with the long option NAME occurs in HOL, set it's special
593    sort position to GROUP.  */
594 static void
595 hol_set_group (struct hol *hol, const char *name, int group)
596 {
597   struct hol_entry *entry = hol_find_entry (hol, name);
598   if (entry)
599     entry->group = group;
600 }
601 \f
602 /* Order by group:  0, 1, 2, ..., n, -m, ..., -2, -1.
603    EQ is what to return if GROUP1 and GROUP2 are the same.  */
604 static int
605 group_cmp (int group1, int group2, int eq)
606 {
607   if (group1 == group2)
608     return eq;
609   else if ((group1 < 0 && group2 < 0) || (group1 >= 0 && group2 >= 0))
610     return group1 - group2;
611   else
612     return group2 - group1;
613 }
614
615 /* Compare clusters CL1 & CL2 by the order that they should appear in
616    output.  */
617 static int
618 hol_cluster_cmp (const struct hol_cluster *cl1, const struct hol_cluster *cl2)
619 {
620   /* If one cluster is deeper than the other, use its ancestor at the same
621      level, so that finding the common ancestor is straightforward.  */
622   while (cl1->depth < cl2->depth)
623     cl1 = cl1->parent;
624   while (cl2->depth < cl1->depth)
625     cl2 = cl2->parent;
626
627   /* Now reduce both clusters to their ancestors at the point where both have
628      a common parent; these can be directly compared.  */
629   while (cl1->parent != cl2->parent)
630     cl1 = cl1->parent, cl2 = cl2->parent;
631
632   return group_cmp (cl1->group, cl2->group, cl2->index - cl1->index);
633 }
634
635 /* Return the ancestor of CL that's just below the root (i.e., has a parent
636    of 0).  */
637 static struct hol_cluster *
638 hol_cluster_base (struct hol_cluster *cl)
639 {
640   while (cl->parent)
641     cl = cl->parent;
642   return cl;
643 }
644
645 /* Return true if CL1 is a child of CL2.  */
646 static int
647 hol_cluster_is_child (const struct hol_cluster *cl1,
648                       const struct hol_cluster *cl2)
649 {
650   while (cl1 && cl1 != cl2)
651     cl1 = cl1->parent;
652   return cl1 == cl2;
653 }
654 \f
655 /* Given the name of a OPTION_DOC option, modifies NAME to start at the tail
656    that should be used for comparisons, and returns true iff it should be
657    treated as a non-option.  */
658 static int
659 canon_doc_option (const char **name)
660 {
661   int non_opt;
662   /* Skip initial whitespace.  */
663   while (isspace (**name))
664     (*name)++;
665   /* Decide whether this looks like an option (leading `-') or not.  */
666   non_opt = (**name != '-');
667   /* Skip until part of name used for sorting.  */
668   while (**name && !isalnum (**name))
669     (*name)++;
670   return non_opt;
671 }
672
673 /* Order ENTRY1 & ENTRY2 by the order which they should appear in a help
674    listing.  */
675 static int
676 hol_entry_cmp (const struct hol_entry *entry1,
677                const struct hol_entry *entry2)
678 {
679   /* The group numbers by which the entries should be ordered; if either is
680      in a cluster, then this is just the group within the cluster.  */
681   int group1 = entry1->group, group2 = entry2->group;
682
683   if (entry1->cluster != entry2->cluster)
684     /* The entries are not within the same cluster, so we can't compare them
685        directly, we have to use the appropiate clustering level too.  */
686     if (! entry1->cluster)
687       /* ENTRY1 is at the `base level', not in a cluster, so we have to
688          compare it's group number with that of the base cluster in which
689          ENTRY2 resides.  Note that if they're in the same group, the
690          clustered option always comes laster.  */
691       return group_cmp (group1, hol_cluster_base (entry2->cluster)->group, -1);
692     else if (! entry2->cluster)
693       /* Likewise, but ENTRY2's not in a cluster.  */
694       return group_cmp (hol_cluster_base (entry1->cluster)->group, group2, 1);
695     else
696       /* Both entries are in clusters, we can just compare the clusters.  */
697       return hol_cluster_cmp (entry1->cluster, entry2->cluster);
698   else if (group1 == group2)
699     /* The entries are both in the same cluster and group, so compare them
700        alphabetically.  */
701     {
702       int short1 = hol_entry_first_short (entry1);
703       int short2 = hol_entry_first_short (entry2);
704       int doc1 = odoc (entry1->opt);
705       int doc2 = odoc (entry2->opt);
706       const char *long1 = hol_entry_first_long (entry1);
707       const char *long2 = hol_entry_first_long (entry2);
708
709       if (doc1)
710         doc1 = canon_doc_option (&long1);
711       if (doc2)
712         doc2 = canon_doc_option (&long2);
713
714       if (doc1 != doc2)
715         /* `documentation' options always follow normal options (or
716            documentation options that *look* like normal options).  */
717         return doc1 - doc2;
718       else if (!short1 && !short2 && long1 && long2)
719         /* Only long options.  */
720         return __strcasecmp (long1, long2);
721       else
722         /* Compare short/short, long/short, short/long, using the first
723            character of long options.  Entries without *any* valid
724            options (such as options with OPTION_HIDDEN set) will be put
725            first, but as they're not displayed, it doesn't matter where
726            they are.  */
727         {
728           char first1 = short1 ? short1 : long1 ? *long1 : 0;
729           char first2 = short2 ? short2 : long2 ? *long2 : 0;
730           int lower_cmp = tolower (first1) - tolower (first2);
731           /* Compare ignoring case, except when the options are both the
732              same letter, in which case lower-case always comes first.  */
733           return lower_cmp ? lower_cmp : first2 - first1;
734         }
735     }
736   else
737     /* Within the same cluster, but not the same group, so just compare
738        groups.  */
739     return group_cmp (group1, group2, 0);
740 }
741
742 /* Version of hol_entry_cmp with correct signature for qsort.  */
743 static int
744 hol_entry_qcmp (const void *entry1_v, const void *entry2_v)
745 {
746   return hol_entry_cmp (entry1_v, entry2_v);
747 }
748
749 /* Sort HOL by group and alphabetically by option name (with short options
750    taking precedence over long).  Since the sorting is for display purposes
751    only, the shadowing of options isn't effected.  */
752 static void
753 hol_sort (struct hol *hol)
754 {
755   if (hol->num_entries > 0)
756     qsort (hol->entries, hol->num_entries, sizeof (struct hol_entry),
757            hol_entry_qcmp);
758 }
759 \f
760 /* Append MORE to HOL, destroying MORE in the process.  Options in HOL shadow
761    any in MORE with the same name.  */
762 static void
763 hol_append (struct hol *hol, struct hol *more)
764 {
765   struct hol_cluster **cl_end = &hol->clusters;
766
767   /* Steal MORE's cluster list, and add it to the end of HOL's.  */
768   while (*cl_end)
769     cl_end = &(*cl_end)->next;
770   *cl_end = more->clusters;
771   more->clusters = 0;
772
773   /* Merge entries.  */
774   if (more->num_entries > 0)
775     if (hol->num_entries == 0)
776       {
777         hol->num_entries = more->num_entries;
778         hol->entries = more->entries;
779         hol->short_options = more->short_options;
780         more->num_entries = 0;  /* Mark MORE's fields as invalid.  */
781       }
782     else
783       /* Append the entries in MORE to those in HOL, taking care to only add
784          non-shadowed SHORT_OPTIONS values.  */
785       {
786         unsigned left;
787         char *so, *more_so;
788         struct hol_entry *e;
789         unsigned num_entries = hol->num_entries + more->num_entries;
790         struct hol_entry *entries =
791           malloc (num_entries * sizeof (struct hol_entry));
792         unsigned hol_so_len = strlen (hol->short_options);
793         char *short_options =
794           malloc (hol_so_len + strlen (more->short_options) + 1);
795
796         __mempcpy (__mempcpy (entries, hol->entries,
797                               hol->num_entries * sizeof (struct hol_entry)),
798                    more->entries,
799                    more->num_entries * sizeof (struct hol_entry));
800
801         __mempcpy (short_options, hol->short_options, hol_so_len);
802
803         /* Fix up the short options pointers from HOL.  */
804         for (e = entries, left = hol->num_entries; left > 0; e++, left--)
805           e->short_options += (short_options - hol->short_options);
806
807         /* Now add the short options from MORE, fixing up its entries too.  */
808         so = short_options + hol_so_len;
809         more_so = more->short_options;
810         for (left = more->num_entries; left > 0; e++, left--)
811           {
812             int opts_left;
813             const struct argp_option *opt;
814
815             e->short_options = so;
816
817             for (opts_left = e->num, opt = e->opt; opts_left; opt++, opts_left--)
818               {
819                 int ch = *more_so;
820                 if (oshort (opt) && ch == opt->key)
821                   /* The next short option in MORE_SO, CH, is from OPT.  */
822                   {
823                     if (! find_char (ch, short_options,
824                                      short_options + hol_so_len))
825                       /* The short option CH isn't shadowed by HOL's options,
826                          so add it to the sum.  */
827                       *so++ = ch;
828                     more_so++;
829                   }
830               }
831           }
832
833         *so = '\0';
834
835         free (hol->entries);
836         free (hol->short_options);
837
838         hol->entries = entries;
839         hol->num_entries = num_entries;
840         hol->short_options = short_options;
841       }
842
843   hol_free (more);
844 }
845 \f
846 /* Inserts enough spaces to make sure STREAM is at column COL.  */
847 static void
848 indent_to (argp_fmtstream_t stream, unsigned col)
849 {
850   int needed = col - __argp_fmtstream_point (stream);
851   while (needed-- > 0)
852     __argp_fmtstream_putc (stream, ' ');
853 }
854
855 /* Output to STREAM either a space, or a newline if there isn't room for at
856    least ENSURE characters before the right margin.  */
857 static void
858 space (argp_fmtstream_t stream, size_t ensure)
859 {
860   if (__argp_fmtstream_point (stream) + ensure
861       >= __argp_fmtstream_rmargin (stream))
862     __argp_fmtstream_putc (stream, '\n');
863   else
864     __argp_fmtstream_putc (stream, ' ');
865 }
866
867 /* If the option REAL has an argument, we print it in using the printf
868    format REQ_FMT or OPT_FMT depending on whether it's a required or
869    optional argument.  */
870 static void
871 arg (const struct argp_option *real, const char *req_fmt, const char *opt_fmt,
872      const char *domain, argp_fmtstream_t stream)
873 {
874   if (real->arg)
875     if (real->flags & OPTION_ARG_OPTIONAL)
876       __argp_fmtstream_printf (stream, opt_fmt, dgettext (domain, real->arg));
877     else
878       __argp_fmtstream_printf (stream, req_fmt, dgettext (domain, real->arg));
879 }
880 \f
881 /* Helper functions for hol_entry_help.  */
882
883 /* State used during the execution of hol_help.  */
884 struct hol_help_state
885 {
886   /* PREV_ENTRY should contain the previous entry printed, or 0.  */
887   struct hol_entry *prev_entry;
888
889   /* If an entry is in a different group from the previous one, and SEP_GROUPS
890      is true, then a blank line will be printed before any output. */
891   int sep_groups;
892
893   /* True if a duplicate option argument was suppressed (only ever set if
894      UPARAMS.dup_args is false).  */
895   int suppressed_dup_arg;
896 };
897
898 /* Some state used while printing a help entry (used to communicate with
899    helper functions).  See the doc for hol_entry_help for more info, as most
900    of the fields are copied from its arguments.  */
901 struct pentry_state
902 {
903   const struct hol_entry *entry;
904   argp_fmtstream_t stream;
905   struct hol_help_state *hhstate;
906
907   /* True if nothing's been printed so far.  */
908   int first;
909
910   /* If non-zero, the state that was used to print this help.  */
911   const struct argp_state *state;
912 };
913
914 /* If a user doc filter should be applied to DOC, do so.  */
915 static const char *
916 filter_doc (const char *doc, int key, const struct argp *argp,
917             const struct argp_state *state)
918 {
919   if (argp->help_filter)
920     /* We must apply a user filter to this output.  */
921     {
922       void *input = __argp_input (argp, state);
923       return (*argp->help_filter) (key, doc, input);
924     }
925   else
926     /* No filter.  */
927     return doc;
928 }
929
930 /* Prints STR as a header line, with the margin lines set appropiately, and
931    notes the fact that groups should be separated with a blank line.  ARGP is
932    the argp that should dictate any user doc filtering to take place.  Note
933    that the previous wrap margin isn't restored, but the left margin is reset
934    to 0.  */
935 static void
936 print_header (const char *str, const struct argp *argp,
937               struct pentry_state *pest)
938 {
939   const char *tstr = dgettext (argp->argp_domain, str);
940   const char *fstr = filter_doc (tstr, ARGP_KEY_HELP_HEADER, argp, pest->state);
941
942   if (fstr)
943     {
944       if (*fstr)
945         {
946           if (pest->hhstate->prev_entry)
947             /* Precede with a blank line.  */
948             __argp_fmtstream_putc (pest->stream, '\n');
949           indent_to (pest->stream, uparams.header_col);
950           __argp_fmtstream_set_lmargin (pest->stream, uparams.header_col);
951           __argp_fmtstream_set_wmargin (pest->stream, uparams.header_col);
952           __argp_fmtstream_puts (pest->stream, fstr);
953           __argp_fmtstream_set_lmargin (pest->stream, 0);
954           __argp_fmtstream_putc (pest->stream, '\n');
955         }
956
957       pest->hhstate->sep_groups = 1; /* Separate subsequent groups. */
958     }
959
960   if (fstr != tstr)
961     free ((char *) fstr);
962 }
963
964 /* Inserts a comma if this isn't the first item on the line, and then makes
965    sure we're at least to column COL.  If this *is* the first item on a line,
966    prints any pending whitespace/headers that should precede this line. Also
967    clears FIRST.  */
968 static void
969 comma (unsigned col, struct pentry_state *pest)
970 {
971   if (pest->first)
972     {
973       const struct hol_entry *pe = pest->hhstate->prev_entry;
974       const struct hol_cluster *cl = pest->entry->cluster;
975
976       if (pest->hhstate->sep_groups && pe && pest->entry->group != pe->group)
977         __argp_fmtstream_putc (pest->stream, '\n');
978
979       if (cl && cl->header && *cl->header
980           && (!pe
981               || (pe->cluster != cl
982                   && !hol_cluster_is_child (pe->cluster, cl))))
983         /* If we're changing clusters, then this must be the start of the
984            ENTRY's cluster unless that is an ancestor of the previous one
985            (in which case we had just popped into a sub-cluster for a bit).
986            If so, then print the cluster's header line.  */
987         {
988           int old_wm = __argp_fmtstream_wmargin (pest->stream);
989           print_header (cl->header, cl->argp, pest);
990           __argp_fmtstream_set_wmargin (pest->stream, old_wm);
991         }
992
993       pest->first = 0;
994     }
995   else
996     __argp_fmtstream_puts (pest->stream, ", ");
997
998   indent_to (pest->stream, col);
999 }
1000 \f
1001 /* Print help for ENTRY to STREAM.  */
1002 static void
1003 hol_entry_help (struct hol_entry *entry, const struct argp_state *state,
1004                 argp_fmtstream_t stream, struct hol_help_state *hhstate)
1005 {
1006   unsigned num;
1007   const struct argp_option *real = entry->opt, *opt;
1008   char *so = entry->short_options;
1009   int have_long_opt = 0;        /* We have any long options.  */
1010   /* Saved margins.  */
1011   int old_lm = __argp_fmtstream_set_lmargin (stream, 0);
1012   int old_wm = __argp_fmtstream_wmargin (stream);
1013   /* PEST is a state block holding some of our variables that we'd like to
1014      share with helper functions.  */
1015   struct pentry_state pest = { entry, stream, hhstate, 1, state };
1016
1017   if (! odoc (real))
1018     for (opt = real, num = entry->num; num > 0; opt++, num--)
1019       if (opt->name && ovisible (opt))
1020         {
1021           have_long_opt = 1;
1022           break;
1023         }
1024
1025   /* First emit short options.  */
1026   __argp_fmtstream_set_wmargin (stream, uparams.short_opt_col); /* For truly bizarre cases. */
1027   for (opt = real, num = entry->num; num > 0; opt++, num--)
1028     if (oshort (opt) && opt->key == *so)
1029       /* OPT has a valid (non shadowed) short option.  */
1030       {
1031         if (ovisible (opt))
1032           {
1033             comma (uparams.short_opt_col, &pest);
1034             __argp_fmtstream_putc (stream, '-');
1035             __argp_fmtstream_putc (stream, *so);
1036             if (!have_long_opt || uparams.dup_args)
1037               arg (real, " %s", "[%s]", state->root_argp->argp_domain, stream);
1038             else if (real->arg)
1039               hhstate->suppressed_dup_arg = 1;
1040           }
1041         so++;
1042       }
1043
1044   /* Now, long options.  */
1045   if (odoc (real))
1046     /* A `documentation' option.  */
1047     {
1048       __argp_fmtstream_set_wmargin (stream, uparams.doc_opt_col);
1049       for (opt = real, num = entry->num; num > 0; opt++, num--)
1050         if (opt->name && ovisible (opt))
1051           {
1052             comma (uparams.doc_opt_col, &pest);
1053             /* Calling gettext here isn't quite right, since sorting will
1054                have been done on the original; but documentation options
1055                should be pretty rare anyway...  */
1056             __argp_fmtstream_puts (stream,
1057                                    dgettext (state->root_argp->argp_domain,
1058                                              opt->name));
1059           }
1060     }
1061   else
1062     /* A real long option.  */
1063     {
1064       int first_long_opt = 1;
1065
1066       __argp_fmtstream_set_wmargin (stream, uparams.long_opt_col);
1067       for (opt = real, num = entry->num; num > 0; opt++, num--)
1068         if (opt->name && ovisible (opt))
1069           {
1070             comma (uparams.long_opt_col, &pest);
1071             __argp_fmtstream_printf (stream, "--%s", opt->name);
1072             if (first_long_opt || uparams.dup_args)
1073               arg (real, "=%s", "[=%s]", state->root_argp->argp_domain,
1074                    stream);
1075             else if (real->arg)
1076               hhstate->suppressed_dup_arg = 1;
1077           }
1078     }
1079
1080   /* Next, documentation strings.  */
1081   __argp_fmtstream_set_lmargin (stream, 0);
1082
1083   if (pest.first)
1084     /* Didn't print any switches, what's up?  */
1085     if (!oshort (real) && !real->name)
1086       /* This is a group header, print it nicely.  */
1087       print_header (real->doc, entry->argp, &pest);
1088     else
1089       /* Just a totally shadowed option or null header; print nothing.  */
1090       goto cleanup;             /* Just return, after cleaning up.  */
1091   else
1092     {
1093       const char *tstr = real->doc ? dgettext (state->root_argp->argp_domain,
1094                                                real->doc) : 0;
1095       const char *fstr = filter_doc (tstr, real->key, entry->argp, state);
1096       if (fstr && *fstr)
1097         {
1098           unsigned int col = __argp_fmtstream_point (stream);
1099
1100           __argp_fmtstream_set_lmargin (stream, uparams.opt_doc_col);
1101           __argp_fmtstream_set_wmargin (stream, uparams.opt_doc_col);
1102
1103           if (col > (unsigned int) (uparams.opt_doc_col + 3))
1104             __argp_fmtstream_putc (stream, '\n');
1105           else if (col >= (unsigned int) uparams.opt_doc_col)
1106             __argp_fmtstream_puts (stream, "   ");
1107           else
1108             indent_to (stream, uparams.opt_doc_col);
1109
1110           __argp_fmtstream_puts (stream, fstr);
1111         }
1112       if (fstr && fstr != tstr)
1113         free ((char *) fstr);
1114
1115       /* Reset the left margin.  */
1116       __argp_fmtstream_set_lmargin (stream, 0);
1117       __argp_fmtstream_putc (stream, '\n');
1118     }
1119
1120   hhstate->prev_entry = entry;
1121
1122 cleanup:
1123   __argp_fmtstream_set_lmargin (stream, old_lm);
1124   __argp_fmtstream_set_wmargin (stream, old_wm);
1125 }
1126 \f
1127 /* Output a long help message about the options in HOL to STREAM.  */
1128 static void
1129 hol_help (struct hol *hol, const struct argp_state *state,
1130           argp_fmtstream_t stream)
1131 {
1132   unsigned num;
1133   struct hol_entry *entry;
1134   struct hol_help_state hhstate = { 0, 0, 0 };
1135
1136   for (entry = hol->entries, num = hol->num_entries; num > 0; entry++, num--)
1137     hol_entry_help (entry, state, stream, &hhstate);
1138
1139   if (hhstate.suppressed_dup_arg && uparams.dup_args_note)
1140     {
1141       const char *tstr = dgettext (state->root_argp->argp_domain, "\
1142 Mandatory or optional arguments to long options are also mandatory or \
1143 optional for any corresponding short options.");
1144       const char *fstr = filter_doc (tstr, ARGP_KEY_HELP_DUP_ARGS_NOTE,
1145                                      state ? state->root_argp : 0, state);
1146       if (fstr && *fstr)
1147         {
1148           __argp_fmtstream_putc (stream, '\n');
1149           __argp_fmtstream_puts (stream, fstr);
1150           __argp_fmtstream_putc (stream, '\n');
1151         }
1152       if (fstr && fstr != tstr)
1153         free ((char *) fstr);
1154     }
1155 }
1156 \f
1157 /* Helper functions for hol_usage.  */
1158
1159 /* If OPT is a short option without an arg, append its key to the string
1160    pointer pointer to by COOKIE, and advance the pointer.  */
1161 static int
1162 add_argless_short_opt (const struct argp_option *opt,
1163                        const struct argp_option *real,
1164                        const char *domain, void *cookie)
1165 {
1166   char **snao_end = cookie;
1167   if (!(opt->arg || real->arg)
1168       && !((opt->flags | real->flags) & OPTION_NO_USAGE))
1169     *(*snao_end)++ = opt->key;
1170   return 0;
1171 }
1172
1173 /* If OPT is a short option with an arg, output a usage entry for it to the
1174    stream pointed at by COOKIE.  */
1175 static int
1176 usage_argful_short_opt (const struct argp_option *opt,
1177                         const struct argp_option *real,
1178                         const char *domain, void *cookie)
1179 {
1180   argp_fmtstream_t stream = cookie;
1181   const char *arg = opt->arg;
1182   int flags = opt->flags | real->flags;
1183
1184   if (! arg)
1185     arg = real->arg;
1186
1187   if (arg && !(flags & OPTION_NO_USAGE))
1188     {
1189       arg = dgettext (domain, arg);
1190
1191       if (flags & OPTION_ARG_OPTIONAL)
1192         __argp_fmtstream_printf (stream, " [-%c[%s]]", opt->key, arg);
1193       else
1194         {
1195           /* Manually do line wrapping so that it (probably) won't
1196              get wrapped at the embedded space.  */
1197           space (stream, 6 + strlen (arg));
1198           __argp_fmtstream_printf (stream, "[-%c %s]", opt->key, arg);
1199         }
1200     }
1201
1202   return 0;
1203 }
1204
1205 /* Output a usage entry for the long option opt to the stream pointed at by
1206    COOKIE.  */
1207 static int
1208 usage_long_opt (const struct argp_option *opt,
1209                 const struct argp_option *real,
1210                 const char *domain, void *cookie)
1211 {
1212   argp_fmtstream_t stream = cookie;
1213   const char *arg = opt->arg;
1214   int flags = opt->flags | real->flags;
1215
1216   if (! arg)
1217     arg = real->arg;
1218
1219   if (! (flags & OPTION_NO_USAGE))
1220     if (arg)
1221       {
1222         arg = dgettext (domain, arg);
1223         if (flags & OPTION_ARG_OPTIONAL)
1224           __argp_fmtstream_printf (stream, " [--%s[=%s]]", opt->name, arg);
1225         else
1226           __argp_fmtstream_printf (stream, " [--%s=%s]", opt->name, arg);
1227       }
1228     else
1229       __argp_fmtstream_printf (stream, " [--%s]", opt->name);
1230
1231   return 0;
1232 }
1233 \f
1234 /* Print a short usage description for the arguments in HOL to STREAM.  */
1235 static void
1236 hol_usage (struct hol *hol, argp_fmtstream_t stream)
1237 {
1238   if (hol->num_entries > 0)
1239     {
1240       unsigned nentries;
1241       struct hol_entry *entry;
1242       char *short_no_arg_opts = alloca (strlen (hol->short_options) + 1);
1243       char *snao_end = short_no_arg_opts;
1244
1245       /* First we put a list of short options without arguments.  */
1246       for (entry = hol->entries, nentries = hol->num_entries
1247            ; nentries > 0
1248            ; entry++, nentries--)
1249         hol_entry_short_iterate (entry, add_argless_short_opt,
1250                                  entry->argp->argp_domain, &snao_end);
1251       if (snao_end > short_no_arg_opts)
1252         {
1253           *snao_end++ = 0;
1254           __argp_fmtstream_printf (stream, " [-%s]", short_no_arg_opts);
1255         }
1256
1257       /* Now a list of short options *with* arguments.  */
1258       for (entry = hol->entries, nentries = hol->num_entries
1259            ; nentries > 0
1260            ; entry++, nentries--)
1261         hol_entry_short_iterate (entry, usage_argful_short_opt,
1262                                  entry->argp->argp_domain, stream);
1263
1264       /* Finally, a list of long options (whew!).  */
1265       for (entry = hol->entries, nentries = hol->num_entries
1266            ; nentries > 0
1267            ; entry++, nentries--)
1268         hol_entry_long_iterate (entry, usage_long_opt,
1269                                 entry->argp->argp_domain, stream);
1270     }
1271 }
1272 \f
1273 /* Make a HOL containing all levels of options in ARGP.  CLUSTER is the
1274    cluster in which ARGP's entries should be clustered, or 0.  */
1275 static struct hol *
1276 argp_hol (const struct argp *argp, struct hol_cluster *cluster)
1277 {
1278   const struct argp_child *child = argp->children;
1279   struct hol *hol = make_hol (argp, cluster);
1280   if (child)
1281     while (child->argp)
1282       {
1283         struct hol_cluster *child_cluster =
1284           ((child->group || child->header)
1285            /* Put CHILD->argp within its own cluster.  */
1286            ? hol_add_cluster (hol, child->group, child->header,
1287                               child - argp->children, cluster, argp)
1288            /* Just merge it into the parent's cluster.  */
1289            : cluster);
1290         hol_append (hol, argp_hol (child->argp, child_cluster)) ;
1291         child++;
1292       }
1293   return hol;
1294 }
1295 \f
1296 /* Calculate how many different levels with alternative args strings exist in
1297    ARGP.  */
1298 static size_t
1299 argp_args_levels (const struct argp *argp)
1300 {
1301   size_t levels = 0;
1302   const struct argp_child *child = argp->children;
1303
1304   if (argp->args_doc && strchr (argp->args_doc, '\n'))
1305     levels++;
1306
1307   if (child)
1308     while (child->argp)
1309       levels += argp_args_levels ((child++)->argp);
1310
1311   return levels;
1312 }
1313
1314 /* Print all the non-option args documented in ARGP to STREAM.  Any output is
1315    preceded by a space.  LEVELS is a pointer to a byte vector the length
1316    returned by argp_args_levels; it should be initialized to zero, and
1317    updated by this routine for the next call if ADVANCE is true.  True is
1318    returned as long as there are more patterns to output.  */
1319 static int
1320 argp_args_usage (const struct argp *argp, const struct argp_state *state,
1321                  char **levels, int advance, argp_fmtstream_t stream)
1322 {
1323   char *our_level = *levels;
1324   int multiple = 0;
1325   const struct argp_child *child = argp->children;
1326   const char *tdoc = dgettext (argp->argp_domain, argp->args_doc), *nl = 0;
1327   const char *fdoc = filter_doc (tdoc, ARGP_KEY_HELP_ARGS_DOC, argp, state);
1328
1329   if (fdoc)
1330     {
1331       const char *cp = fdoc;
1332       nl = strchr (cp, '\n');
1333       if (nl)
1334         /* This is a `multi-level' args doc; advance to the correct position
1335            as determined by our state in LEVELS, and update LEVELS.  */
1336         {
1337           int i;
1338           multiple = 1;
1339           for (i = 0; i < *our_level; i++)
1340             cp = nl + 1, nl = strchr (cp, '\n');
1341           (*levels)++;
1342         }
1343       if (! nl)
1344         nl = cp + strlen (cp);
1345
1346       /* Manually do line wrapping so that it (probably) won't get wrapped at
1347          any embedded spaces.  */
1348       space (stream, 1 + nl - cp);
1349
1350       __argp_fmtstream_write (stream, cp, nl - cp);
1351     }
1352   if (fdoc && fdoc != tdoc)
1353     free ((char *)fdoc);        /* Free user's modified doc string.  */
1354
1355   if (child)
1356     while (child->argp)
1357       advance = !argp_args_usage ((child++)->argp, state, levels, advance, stream);
1358
1359   if (advance && multiple)
1360     /* Need to increment our level.  */
1361     if (*nl)
1362       /* There's more we can do here.  */
1363       {
1364         (*our_level)++;
1365         advance = 0;            /* Our parent shouldn't advance also. */
1366       }
1367     else if (*our_level > 0)
1368       /* We had multiple levels, but used them up; reset to zero.  */
1369       *our_level = 0;
1370
1371   return !advance;
1372 }
1373 \f
1374 /* Print the documentation for ARGP to STREAM; if POST is false, then
1375    everything preceeding a `\v' character in the documentation strings (or
1376    the whole string, for those with none) is printed, otherwise, everything
1377    following the `\v' character (nothing for strings without).  Each separate
1378    bit of documentation is separated a blank line, and if PRE_BLANK is true,
1379    then the first is as well.  If FIRST_ONLY is true, only the first
1380    occurance is output.  Returns true if anything was output.  */
1381 static int
1382 argp_doc (const struct argp *argp, const struct argp_state *state,
1383           int post, int pre_blank, int first_only,
1384           argp_fmtstream_t stream)
1385 {
1386   const char *text;
1387   const char *inp_text;
1388   void *input = 0;
1389   int anything = 0;
1390   size_t inp_text_limit = 0;
1391   const char *doc = dgettext (argp->argp_domain, argp->doc);
1392   const struct argp_child *child = argp->children;
1393
1394   if (doc)
1395     {
1396       char *vt = strchr (doc, '\v');
1397       inp_text = post ? (vt ? vt + 1 : 0) : doc;
1398       inp_text_limit = (!post && vt) ? (vt - doc) : 0;
1399     }
1400   else
1401     inp_text = 0;
1402
1403   if (argp->help_filter)
1404     /* We have to filter the doc strings.  */
1405     {
1406       if (inp_text_limit)
1407         /* Copy INP_TEXT so that it's nul-terminated.  */
1408         inp_text = strndup (inp_text, inp_text_limit);
1409       input = __argp_input (argp, state);
1410       text =
1411         (*argp->help_filter) (post
1412                               ? ARGP_KEY_HELP_POST_DOC
1413                               : ARGP_KEY_HELP_PRE_DOC,
1414                               inp_text, input);
1415     }
1416   else
1417     text = (const char *) inp_text;
1418
1419   if (text)
1420     {
1421       if (pre_blank)
1422         __argp_fmtstream_putc (stream, '\n');
1423
1424       if (text == inp_text && inp_text_limit)
1425         __argp_fmtstream_write (stream, inp_text, inp_text_limit);
1426       else
1427         __argp_fmtstream_puts (stream, text);
1428
1429       if (__argp_fmtstream_point (stream) > __argp_fmtstream_lmargin (stream))
1430         __argp_fmtstream_putc (stream, '\n');
1431
1432       anything = 1;
1433     }
1434
1435   if (text && text != inp_text)
1436     free ((char *) text);       /* Free TEXT returned from the help filter.  */
1437   if (inp_text && inp_text_limit && argp->help_filter)
1438     free ((char *) inp_text);   /* We copied INP_TEXT, so free it now.  */
1439
1440   if (post && argp->help_filter)
1441     /* Now see if we have to output a ARGP_KEY_HELP_EXTRA text.  */
1442     {
1443       text = (*argp->help_filter) (ARGP_KEY_HELP_EXTRA, 0, input);
1444       if (text)
1445         {
1446           if (anything || pre_blank)
1447             __argp_fmtstream_putc (stream, '\n');
1448           __argp_fmtstream_puts (stream, text);
1449           free ((char *) text);
1450           if (__argp_fmtstream_point (stream)
1451               > __argp_fmtstream_lmargin (stream))
1452             __argp_fmtstream_putc (stream, '\n');
1453           anything = 1;
1454         }
1455     }
1456
1457   if (child)
1458     while (child->argp && !(first_only && anything))
1459       anything |=
1460         argp_doc ((child++)->argp, state,
1461                   post, anything || pre_blank, first_only,
1462                   stream);
1463
1464   return anything;
1465 }
1466 \f
1467 /* Output a usage message for ARGP to STREAM.  If called from
1468    argp_state_help, STATE is the relevent parsing state.  FLAGS are from the
1469    set ARGP_HELP_*.  NAME is what to use wherever a `program name' is
1470    needed. */
1471 static void
1472 _help (const struct argp *argp, const struct argp_state *state, FILE *stream,
1473        unsigned flags, char *name)
1474 {
1475   int anything = 0;             /* Whether we've output anything.  */
1476   struct hol *hol = 0;
1477   argp_fmtstream_t fs;
1478
1479   if (! stream)
1480     return;
1481
1482   if (! uparams.valid)
1483     fill_in_uparams (state);
1484
1485   fs = __argp_make_fmtstream (stream, 0, uparams.rmargin, 0);
1486   if (! fs)
1487     return;
1488
1489   if (flags & (ARGP_HELP_USAGE | ARGP_HELP_SHORT_USAGE | ARGP_HELP_LONG))
1490     {
1491       hol = argp_hol (argp, 0);
1492
1493       /* If present, these options always come last.  */
1494       hol_set_group (hol, "help", -1);
1495       hol_set_group (hol, "version", -1);
1496
1497       hol_sort (hol);
1498     }
1499
1500   if (flags & (ARGP_HELP_USAGE | ARGP_HELP_SHORT_USAGE))
1501     /* Print a short `Usage:' message.  */
1502     {
1503       int first_pattern = 1, more_patterns;
1504       size_t num_pattern_levels = argp_args_levels (argp);
1505       char *pattern_levels = alloca (num_pattern_levels);
1506
1507       memset (pattern_levels, 0, num_pattern_levels);
1508
1509       do
1510         {
1511           int old_lm;
1512           int old_wm = __argp_fmtstream_set_wmargin (fs, uparams.usage_indent);
1513           char *levels = pattern_levels;
1514
1515           if (first_pattern)
1516             __argp_fmtstream_printf (fs, "%s %s",
1517                                      dgettext (argp->argp_domain, "Usage:"),
1518                                      name);
1519           else
1520             __argp_fmtstream_printf (fs, "%s %s",
1521                                      dgettext (argp->argp_domain, "  or: "),
1522                                      name);
1523
1524           /* We set the lmargin as well as the wmargin, because hol_usage
1525              manually wraps options with newline to avoid annoying breaks.  */
1526           old_lm = __argp_fmtstream_set_lmargin (fs, uparams.usage_indent);
1527
1528           if (flags & ARGP_HELP_SHORT_USAGE)
1529             /* Just show where the options go.  */
1530             {
1531               if (hol->num_entries > 0)
1532                 __argp_fmtstream_puts (fs, dgettext (argp->argp_domain,
1533                                                      " [OPTION...]"));
1534             }
1535           else
1536             /* Actually print the options.  */
1537             {
1538               hol_usage (hol, fs);
1539               flags |= ARGP_HELP_SHORT_USAGE; /* But only do so once.  */
1540             }
1541
1542           more_patterns = argp_args_usage (argp, state, &levels, 1, fs);
1543
1544           __argp_fmtstream_set_wmargin (fs, old_wm);
1545           __argp_fmtstream_set_lmargin (fs, old_lm);
1546
1547           __argp_fmtstream_putc (fs, '\n');
1548           anything = 1;
1549
1550           first_pattern = 0;
1551         }
1552       while (more_patterns);
1553     }
1554
1555   if (flags & ARGP_HELP_PRE_DOC)
1556     anything |= argp_doc (argp, state, 0, 0, 1, fs);
1557
1558   if (flags & ARGP_HELP_SEE)
1559     {
1560       __argp_fmtstream_printf (fs, dgettext (argp->argp_domain, "\
1561 Try `%s --help' or `%s --usage' for more information.\n"),
1562                                name, name);
1563       anything = 1;
1564     }
1565
1566   if (flags & ARGP_HELP_LONG)
1567     /* Print a long, detailed help message.  */
1568     {
1569       /* Print info about all the options.  */
1570       if (hol->num_entries > 0)
1571         {
1572           if (anything)
1573             __argp_fmtstream_putc (fs, '\n');
1574           hol_help (hol, state, fs);
1575           anything = 1;
1576         }
1577     }
1578
1579   if (flags & ARGP_HELP_POST_DOC)
1580     /* Print any documentation strings at the end.  */
1581     anything |= argp_doc (argp, state, 1, anything, 0, fs);
1582
1583   if ((flags & ARGP_HELP_BUG_ADDR) && argp_program_bug_address)
1584     {
1585       if (anything)
1586         __argp_fmtstream_putc (fs, '\n');
1587       __argp_fmtstream_printf (fs, dgettext (argp->argp_domain,
1588                                              "Report bugs to %s.\n"),
1589                                argp_program_bug_address);
1590       anything = 1;
1591     }
1592
1593   if (hol)
1594     hol_free (hol);
1595
1596   __argp_fmtstream_free (fs);
1597 }
1598 \f
1599 /* Output a usage message for ARGP to STREAM.  FLAGS are from the set
1600    ARGP_HELP_*.  NAME is what to use wherever a `program name' is needed. */
1601 void __argp_help (const struct argp *argp, FILE *stream,
1602                   unsigned flags, char *name)
1603 {
1604   _help (argp, 0, stream, flags, name);
1605 }
1606 #ifdef weak_alias
1607 weak_alias (__argp_help, argp_help)
1608 #endif
1609
1610 /* Output, if appropriate, a usage message for STATE to STREAM.  FLAGS are
1611    from the set ARGP_HELP_*.  */
1612 void
1613 __argp_state_help (const struct argp_state *state, FILE *stream, unsigned flags)
1614 {
1615   if ((!state || ! (state->flags & ARGP_NO_ERRS)) && stream)
1616     {
1617       if (state && (state->flags & ARGP_LONG_ONLY))
1618         flags |= ARGP_HELP_LONG_ONLY;
1619
1620       _help (state ? state->root_argp : 0, state, stream, flags,
1621              state ? state->name : program_invocation_short_name);
1622
1623       if (!state || ! (state->flags & ARGP_NO_EXIT))
1624         {
1625           if (flags & ARGP_HELP_EXIT_ERR)
1626             exit (argp_err_exit_status);
1627           if (flags & ARGP_HELP_EXIT_OK)
1628             exit (0);
1629         }
1630   }
1631 }
1632 #ifdef weak_alias
1633 weak_alias (__argp_state_help, argp_state_help)
1634 #endif
1635 \f
1636 /* If appropriate, print the printf string FMT and following args, preceded
1637    by the program name and `:', to stderr, and followed by a `Try ... --help'
1638    message, then exit (1).  */
1639 void
1640 __argp_error (const struct argp_state *state, const char *fmt, ...)
1641 {
1642   if (!state || !(state->flags & ARGP_NO_ERRS))
1643     {
1644       FILE *stream = state ? state->err_stream : stderr;
1645
1646       if (stream)
1647         {
1648           va_list ap;
1649
1650           fputs (state ? state->name : program_invocation_short_name, stream);
1651           putc (':', stream);
1652           putc (' ', stream);
1653
1654           va_start (ap, fmt);
1655           vfprintf (stream, fmt, ap);
1656           va_end (ap);
1657
1658           putc ('\n', stream);
1659
1660           __argp_state_help (state, stream, ARGP_HELP_STD_ERR);
1661         }
1662     }
1663 }
1664 #ifdef weak_alias
1665 weak_alias (__argp_error, argp_error)
1666 #endif
1667 \f
1668 /* Similar to the standard gnu error-reporting function error(), but will
1669    respect the ARGP_NO_EXIT and ARGP_NO_ERRS flags in STATE, and will print
1670    to STATE->err_stream.  This is useful for argument parsing code that is
1671    shared between program startup (when exiting is desired) and runtime
1672    option parsing (when typically an error code is returned instead).  The
1673    difference between this function and argp_error is that the latter is for
1674    *parsing errors*, and the former is for other problems that occur during
1675    parsing but don't reflect a (syntactic) problem with the input.  */
1676 void
1677 __argp_failure (const struct argp_state *state, int status, int errnum,
1678                 const char *fmt, ...)
1679 {
1680   if (!state || !(state->flags & ARGP_NO_ERRS))
1681     {
1682       FILE *stream = state ? state->err_stream : stderr;
1683
1684       if (stream)
1685         {
1686           fputs (state ? state->name : program_invocation_short_name, stream);
1687
1688           if (fmt)
1689             {
1690               va_list ap;
1691
1692               putc (':', stream);
1693               putc (' ', stream);
1694
1695               va_start (ap, fmt);
1696               vfprintf (stream, fmt, ap);
1697               va_end (ap);
1698             }
1699
1700           if (errnum)
1701             {
1702               putc (':', stream);
1703               putc (' ', stream);
1704               fputs (strerror (errnum), stream);
1705             }
1706
1707           putc ('\n', stream);
1708
1709           if (status && (!state || !(state->flags & ARGP_NO_EXIT)))
1710             exit (status);
1711         }
1712     }
1713 }
1714 #ifdef weak_alias
1715 weak_alias (__argp_failure, argp_failure)
1716 #endif