diff options
| -rw-r--r-- | ChangeLog | 5 | ||||
| -rw-r--r-- | localedata/ChangeLog | 9 | ||||
| -rw-r--r-- | localedata/Makefile | 32 | ||||
| -rw-r--r-- | localedata/SUPPORTED | 293 | ||||
| -rw-r--r-- | manual/argp.texi | 876 |
5 files changed, 626 insertions, 589 deletions
diff --git a/ChangeLog b/ChangeLog index ef2c31e204..86804e90fd 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2001-06-28 Ulrich Drepper <drepper@redhat.com> + + * manual/argp.texi: Tons of cleanups. + Patch by Clifford U. Smith <cuel@swbell.net>. + 2001-06-28 Mark Kettenis <kettenis@gnu.org> * manual/users.texi (Setting Groups): Correct initgroups diff --git a/localedata/ChangeLog b/localedata/ChangeLog index e5bf6976f9..908059e2b0 100644 --- a/localedata/ChangeLog +++ b/localedata/ChangeLog @@ -1,3 +1,12 @@ +2001-06-28 H.J. Lu <hjl@gnu.org> + + * Makefile: Include SUPPORTED. + (INSTALL-SUPPORTED-LOCALES): New. + ($(INSTALL-SUPPORTED-LOCALES)): New target. + (install-locales-dir): Likewise. + (install-locales): Depend on $(INSTALL-SUPPORTED-LOCALES). + * SUPPORTED: Changed the format for parallel install. + 2001-06-27 Ulrich Drepper <drepper@redhat.com> * Makefile: Add rules to build and run tst-leaks. diff --git a/localedata/Makefile b/localedata/Makefile index e7e15ebfef..1f5bf3b092 100644 --- a/localedata/Makefile +++ b/localedata/Makefile @@ -191,22 +191,30 @@ $(objpfx)tst-langinfo.out: tst-langinfo.sh $(objpfx)tst-langinfo \ $(objpfx)tst-digits.out: $(objpfx)tst-locale.out endif +include SUPPORTED + +INSTALL-SUPPORTED-LOCALES=$(addprefix install-, $(SUPPORTED-LOCALES)) + # Sometimes the whole collection of locale files should be installed. LOCALEDEF=I18NPATH=. GCONV_PATH=$(common-objpfx)iconvdata LC_ALL=C \ $(common-objpfx)elf/ld.so --library-path $(rpath-link) $(common-objpfx)locale/localedef -install-locales: +install-locales: $(INSTALL-SUPPORTED-LOCALES) + +install-locales-dir: $(..)./scripts/mkinstalldirs $(inst_localedir) - while read locale charset; do \ - case $$locale in \#*) continue;; esac; \ - echo -n `echo $$locale | sed 's/\([^.\@]*\).*/\1/'`; \ - echo -n ".$$charset"; \ - echo -n `echo $$locale | sed 's/\([^\@]*\)\(\@.*\)*/\2/'`; \ - echo -n '...'; \ - input=`echo $$locale | sed 's/\([^.]*\)[^@]*\(.*\)/\1\2/'`; \ - $(LOCALEDEF) -i locales/$$input -c -f charmaps/$$charset \ - $(addprefix --prefix=,$(install_root)) $$locale; \ - echo ' done'; \ - done < SUPPORTED + +$(INSTALL-SUPPORTED-LOCALES): install-locales-dir + @locale=`echo $@ | sed -e 's/^install-//'`; \ + charset=`echo $$locale | sed -e 's,.*/,,'`; \ + locale=`echo $$locale | sed -e 's,/[^/]*,,'`; \ + echo -n `echo $$locale | sed 's/\([^.\@]*\).*/\1/'`; \ + echo -n ".$$charset"; \ + echo -n `echo $$locale | sed 's/\([^\@]*\)\(\@.*\)*/\2/'`; \ + echo -n '...'; \ + input=`echo $$locale | sed 's/\([^.]*\)[^@]*\(.*\)/\1\2/'`; \ + $(LOCALEDEF) -i locales/$$input -c -f charmaps/$$charset \ + $(addprefix --prefix=,$(install_root)) $$locale; \ + echo ' done'; \ # The mbwc-tests need some environment setup to find the locale data files TEST_MBWC_ENV:= LOCPATH=$(common-objpfx)localedata diff --git a/localedata/SUPPORTED b/localedata/SUPPORTED index a7909462a5..d4fde8adad 100644 --- a/localedata/SUPPORTED +++ b/localedata/SUPPORTED @@ -1,149 +1,150 @@ # This file names the currently supported and somewhat tested locales. # If you have any additions please use the glibcbug script to send an # appropriate message. -af_ZA ISO-8859-1 -ar_AE ISO-8859-6 -ar_BH ISO-8859-6 -ar_DZ ISO-8859-6 -ar_EG ISO-8859-6 -ar_IN UTF-8 -ar_IQ ISO-8859-6 -ar_JO ISO-8859-6 -ar_KW ISO-8859-6 -ar_LB ISO-8859-6 -ar_LY ISO-8859-6 -ar_MA ISO-8859-6 -ar_OM ISO-8859-6 -ar_QA ISO-8859-6 -ar_SA ISO-8859-6 -ar_SD ISO-8859-6 -ar_SY ISO-8859-6 -ar_TN ISO-8859-6 -ar_YE ISO-8859-6 -be_BY CP1251 -bg_BG CP1251 -ca_ES ISO-8859-1 -ca_ES@euro ISO-8859-15 -cs_CZ ISO-8859-2 -da_DK ISO-8859-1 -de_AT ISO-8859-1 -de_AT@euro ISO-8859-15 -de_BE ISO-8859-1 -de_BE@euro ISO-8859-15 -de_CH ISO-8859-1 -de_DE ISO-8859-1 -de_DE@euro ISO-8859-15 -de_LU ISO-8859-1 -de_LU@euro ISO-8859-15 -el_GR ISO-8859-7 -en_AU ISO-8859-1 -en_BW ISO-8859-1 -en_CA ISO-8859-1 -en_DK ISO-8859-1 -en_GB ISO-8859-1 -en_HK ISO-8859-1 -en_IE ISO-8859-1 -en_IE@euro ISO-8859-15 -en_IN UTF-8 -en_NZ ISO-8859-1 -en_PH ISO-8859-1 -en_SG ISO-8859-1 -en_US ISO-8859-1 -en_ZA ISO-8859-1 -en_ZW ISO-8859-1 -es_AR ISO-8859-1 -es_BO ISO-8859-1 -es_CL ISO-8859-1 -es_CO ISO-8859-1 -es_CR ISO-8859-1 -es_DO ISO-8859-1 -es_EC ISO-8859-1 -es_ES ISO-8859-1 -es_ES@euro ISO-8859-15 -es_GT ISO-8859-1 -es_HN ISO-8859-1 -es_MX ISO-8859-1 -es_NI ISO-8859-1 -es_PA ISO-8859-1 -es_PE ISO-8859-1 -es_PR ISO-8859-1 -es_PY ISO-8859-1 -es_SV ISO-8859-1 -es_US ISO-8859-1 -es_UY ISO-8859-1 -es_VE ISO-8859-1 -et_EE ISO-8859-1 -eu_ES ISO-8859-1 -eu_ES@euro ISO-8859-15 -fa_IR UTF-8 -fi_FI ISO-8859-1 -fi_FI@euro ISO-8859-15 -fo_FO ISO-8859-1 -fr_BE ISO-8859-1 -fr_BE@euro ISO-8859-15 -fr_CA ISO-8859-1 -fr_CH ISO-8859-1 -fr_FR ISO-8859-1 -fr_FR@euro ISO-8859-15 -fr_LU ISO-8859-1 -fr_LU@euro ISO-8859-15 -ga_IE ISO-8859-1 -ga_IE@euro ISO-8859-15 -gl_ES ISO-8859-1 -gl_ES@euro ISO-8859-15 -gv_GB ISO-8859-1 -he_IL ISO-8859-8 -hi_IN UTF-8 -hr_HR ISO-8859-2 -hu_HU ISO-8859-2 -id_ID ISO-8859-1 -is_IS ISO-8859-1 -it_CH ISO-8859-1 -it_IT ISO-8859-1 -it_IT@euro ISO-8859-15 -iw_IL ISO-8859-8 -ja_JP.EUC-JP EUC-JP -kl_GL ISO-8859-1 -ko_KR.EUC-KR EUC-KR -ko_KR.UTF-8 UTF-8 -kw_GB ISO-8859-1 -lt_LT ISO-8859-13 -lv_LV ISO-8859-13 -mk_MK ISO-8859-5 -mr_IN UTF-8 -ms_MY ISO-8859-1 -mt_MT ISO-8859-3 -nl_BE ISO-8859-1 -nl_BE@euro ISO-8859-15 -nl_NL ISO-8859-1 -nl_NL@euro ISO-8859-15 -nn_NO ISO-8859-1 -no_NO ISO-8859-1 -pl_PL ISO-8859-2 -pt_BR ISO-8859-1 -pt_PT ISO-8859-1 -pt_PT@euro ISO-8859-15 -ro_RO ISO-8859-2 -ru_RU ISO-8859-5 -ru_RU.KOI8-R KOI8-R -ru_UA KOI8-U -sk_SK ISO-8859-2 -sl_SI ISO-8859-2 -sq_AL ISO-8859-1 -sr_YU ISO-8859-2 -sr_YU@cyrillic ISO-8859-5 -sv_FI ISO-8859-1 -sv_FI@euro ISO-8859-15 -sv_SE ISO-8859-1 -ta_IN UTF-8 -te_IN UTF-8 -th_TH TIS-620 -tr_TR ISO-8859-9 -uk_UA KOI8-U -vi_VN UTF-8 -zh_CN GB2312 -zh_CN.GB18030 GB18030 -zh_CN.GBK GBK -zh_HK BIG5-HKSCS -zh_TW BIG5 -zh_TW.EUC-TW EUC-TW +SUPPORTED-LOCALES=\ +af_ZA/ISO-8859-1 \ +ar_AE/ISO-8859-6 \ +ar_BH/ISO-8859-6 \ +ar_DZ/ISO-8859-6 \ +ar_EG/ISO-8859-6 \ +ar_IN/UTF-8 \ +ar_IQ/ISO-8859-6 \ +ar_JO/ISO-8859-6 \ +ar_KW/ISO-8859-6 \ +ar_LB/ISO-8859-6 \ +ar_LY/ISO-8859-6 \ +ar_MA/ISO-8859-6 \ +ar_OM/ISO-8859-6 \ +ar_QA/ISO-8859-6 \ +ar_SA/ISO-8859-6 \ +ar_SD/ISO-8859-6 \ +ar_SY/ISO-8859-6 \ +ar_TN/ISO-8859-6 \ +ar_YE/ISO-8859-6 \ +be_BY/CP1251 \ +bg_BG/CP1251 \ +ca_ES/ISO-8859-1 \ +ca_ES@euro/ISO-8859-15 \ +cs_CZ/ISO-8859-2 \ +da_DK/ISO-8859-1 \ +de_AT/ISO-8859-1 \ +de_AT@euro/ISO-8859-15 \ +de_BE/ISO-8859-1 \ +de_BE@euro/ISO-8859-15 \ +de_CH/ISO-8859-1 \ +de_DE/ISO-8859-1 \ +de_DE@euro/ISO-8859-15 \ +de_LU/ISO-8859-1 \ +de_LU@euro/ISO-8859-15 \ +el_GR/ISO-8859-7 \ +en_AU/ISO-8859-1 \ +en_BW/ISO-8859-1 \ +en_CA/ISO-8859-1 \ +en_DK/ISO-8859-1 \ +en_GB/ISO-8859-1 \ +en_HK/ISO-8859-1 \ +en_IE/ISO-8859-1 \ +en_IE@euro/ISO-8859-15 \ +en_IN/UTF-8 \ +en_NZ/ISO-8859-1 \ +en_PH/ISO-8859-1 \ +en_SG/ISO-8859-1 \ +en_US/ISO-8859-1 \ +en_ZA/ISO-8859-1 \ +en_ZW/ISO-8859-1 \ +es_AR/ISO-8859-1 \ +es_BO/ISO-8859-1 \ +es_CL/ISO-8859-1 \ +es_CO/ISO-8859-1 \ +es_CR/ISO-8859-1 \ +es_DO/ISO-8859-1 \ +es_EC/ISO-8859-1 \ +es_ES/ISO-8859-1 \ +es_ES@euro/ISO-8859-15 \ +es_GT/ISO-8859-1 \ +es_HN/ISO-8859-1 \ +es_MX/ISO-8859-1 \ +es_NI/ISO-8859-1 \ +es_PA/ISO-8859-1 \ +es_PE/ISO-8859-1 \ +es_PR/ISO-8859-1 \ +es_PY/ISO-8859-1 \ +es_SV/ISO-8859-1 \ +es_US/ISO-8859-1 \ +es_UY/ISO-8859-1 \ +es_VE/ISO-8859-1 \ +et_EE/ISO-8859-1 \ +eu_ES/ISO-8859-1 \ +eu_ES@euro/ISO-8859-15 \ +fa_IR/UTF-8 \ +fi_FI/ISO-8859-1 \ +fi_FI@euro/ISO-8859-15 \ +fo_FO/ISO-8859-1 \ +fr_BE/ISO-8859-1 \ +fr_BE@euro/ISO-8859-15 \ +fr_CA/ISO-8859-1 \ +fr_CH/ISO-8859-1 \ +fr_FR/ISO-8859-1 \ +fr_FR@euro/ISO-8859-15 \ +fr_LU/ISO-8859-1 \ +fr_LU@euro/ISO-8859-15 \ +ga_IE/ISO-8859-1 \ +ga_IE@euro/ISO-8859-15 \ +gl_ES/ISO-8859-1 \ +gl_ES@euro/ISO-8859-15 \ +gv_GB/ISO-8859-1 \ +he_IL/ISO-8859-8 \ +hi_IN/UTF-8 \ +hr_HR/ISO-8859-2 \ +hu_HU/ISO-8859-2 \ +id_ID/ISO-8859-1 \ +is_IS/ISO-8859-1 \ +it_CH/ISO-8859-1 \ +it_IT/ISO-8859-1 \ +it_IT@euro/ISO-8859-15 \ +iw_IL/ISO-8859-8 \ +ja_JP.EUC-JP/EUC-JP \ +kl_GL/ISO-8859-1 \ +ko_KR.EUC-KR/EUC-KR \ +ko_KR.UTF-8/UTF-8 \ +kw_GB/ISO-8859-1 \ +lt_LT/ISO-8859-13 \ +lv_LV/ISO-8859-13 \ +mk_MK/ISO-8859-5 \ +mr_IN/UTF-8 \ +ms_MY/ISO-8859-1 \ +mt_MT/ISO-8859-3 \ +nl_BE/ISO-8859-1 \ +nl_BE@euro/ISO-8859-15 \ +nl_NL/ISO-8859-1 \ +nl_NL@euro/ISO-8859-15 \ +nn_NO/ISO-8859-1 \ +no_NO/ISO-8859-1 \ +pl_PL/ISO-8859-2 \ +pt_BR/ISO-8859-1 \ +pt_PT/ISO-8859-1 \ +pt_PT@euro/ISO-8859-15 \ +ro_RO/ISO-8859-2 \ +ru_RU/ISO-8859-5 \ +ru_RU.KOI8-R/KOI8-R \ +ru_UA/KOI8-U \ +sk_SK/ISO-8859-2 \ +sl_SI/ISO-8859-2 \ +sq_AL/ISO-8859-1 \ +sr_YU/ISO-8859-2 \ +sr_YU@cyrillic/ISO-8859-5 \ +sv_FI/ISO-8859-1 \ +sv_FI@euro/ISO-8859-15 \ +sv_SE/ISO-8859-1 \ +ta_IN/UTF-8 \ +te_IN/UTF-8 \ +th_TH/TIS-620 \ +tr_TR/ISO-8859-9 \ +uk_UA/KOI8-U \ +vi_VN/UTF-8 \ +zh_CN/GB2312 \ +zh_CN.GB18030/GB18030 \ +zh_CN.GBK/GBK \ +zh_HK/BIG5-HKSCS \ +zh_TW/BIG5 \ +zh_TW.EUC-TW/EUC-TW \ diff --git a/manual/argp.texi b/manual/argp.texi index 329213ee50..1966c5ca20 100644 --- a/manual/argp.texi +++ b/manual/argp.texi @@ -1,7 +1,7 @@ @ignore Documentation for the argp argument parser - Copyright (C) 1995, 1996, 1997, 1998, 2000 Free Software Foundation, Inc. + Copyright (C) 1995,1996,1997,1998,2000,2001 Free Software Foundation, Inc. This file is part of the GNU C Library. Written by Miles Bader <miles@gnu.ai.mit.edu>. @@ -28,60 +28,61 @@ @cindex argument parsing with argp @cindex option parsing with argp -@dfn{Argp} is an interface for parsing unix-style argument vectors -(@pxref{Program Arguments}). +@dfn{Argp} is an interface for parsing unix-style argument vectors. +@xref{Program Arguments}. -Unlike the more common @code{getopt} interface, it provides many related -convenience features in addition to parsing options, such as -automatically producing output in response to @samp{--help} and -@samp{--version} options (as defined by the GNU coding standards). -Doing these things in argp results in a more consistent look for -programs that use it, and makes less likely that implementors will -neglect to implement them or keep them up-to-date. +Argp provides features unavailable in the more commonly used +@code{getopt} interface. These features include automatically producing +output in response to the @samp{--help} and @samp{--version} options, as +described in the GNU coding standards. Using argp makes it less likely +that programmers will neglect to implement these additional options or +keep them up to date. Argp also provides the ability to merge several independently defined -option parsers into one, mediating conflicts between them, and making -the result appear seamless. A library can export an argp option parser, -which programs can easily use in conjunction with their own option -parser. This results in less work for user programs (indeed, some may -use only argument parsers exported by libraries, and have no options of -their own), and more consistent option-parsing for the abstractions -implemented by the library. +option parsers into one, mediating conflicts between them and making the +result appear seamless. A library can export an argp option parser that +user programs might employ in conjunction with their own option parsers, +resulting in less work for the user programs. Some programs may use only +argument parsers exported by libraries, thereby achieving consistent and +efficient option-parsing for abstractions implemented by the libraries. @pindex argp.h The header file @file{<argp.h>} should be included to use argp. @subsection The @code{argp_parse} Function -The main interface to argp is the @code{argp_parse} function; often, a -call to @code{argp_parse} is the only argument-parsing code needed in -@code{main} (@pxref{Program Arguments}). +The main interface to argp is the @code{argp_parse} function. In many +cases, calling @code{argp_parse} is the only argument-parsing code +needed in @code{main}. +@xref{Program Arguments}. @comment argp.h @comment GNU @deftypefun {error_t} argp_parse (const struct argp *@var{argp}, int @var{argc}, char **@var{argv}, unsigned @var{flags}, int *@var{arg_index}, void *@var{input}) The @code{argp_parse} function parses the arguments in @var{argv}, of -length @var{argc}, using the argp parser @var{argp} (@pxref{Argp -Parsers}); a value of zero is the same as a @code{struct argp} -containing all zeros. @var{flags} is a set of flag bits that modify the -parsing behavior (@pxref{Argp Flags}). @var{input} is passed through to -the argp parser @var{argp}, and has meaning defined by it; a typical -usage is to pass a pointer to a structure which can be used for -specifying parameters to the parser and passing back results from it. +length @var{argc}, using the argp parser @var{argp}. @xref{Argp +Parsers}. + +A value of zero is the same as a @code{struct argp}containing all +zeros. @var{flags} is a set of flag bits that modify the parsing +behavior. @xref{Argp Flags}. @var{input} is passed through to the argp +parser @var{argp}, and has meaning defined by @var{argp}. A typical +usage is to pass a pointer to a structure which is used for specifying +parameters to the parser and passing back the results. Unless the @code{ARGP_NO_EXIT} or @code{ARGP_NO_HELP} flags are included in @var{flags}, calling @code{argp_parse} may result in the program -exiting---for instance when an unknown option is encountered. -@xref{Program Termination}. +exiting. This behavior is true if an error is detected, or when an +unknown option is encountered. @xref{Program Termination}. If @var{arg_index} is non-null, the index of the first unparsed option -in @var{argv} is returned in it. +in @var{argv} is returned as a value. The return value is zero for successful parsing, or an error code -(@pxref{Error Codes}) if an error was detected. Different argp parsers -may return arbitrary error codes, but standard ones are @code{ENOMEM} if -a memory allocation error occurred, or @code{EINVAL} if an unknown option -or option argument was encountered. +(@pxref{Error Codes}) if an error is detected. Different argp parsers +may return arbitrary error codes, but the standard error codes are: +@code{ENOMEM} if a memory allocation error occurred, or @code{EINVAL} if +an unknown option or option argument is encountered. @end deftypefun @menu @@ -97,40 +98,41 @@ or option argument was encountered. @node Argp Global Variables, Argp Parsers, , Argp @subsection Argp Global Variables -These variables make it very easy for every user program to implement -the @samp{--version} option and provide a bug-reporting address in the -@samp{--help} output (which is implemented by argp regardless). +These variables make it easy for user programs to implement the +@samp{--version} option and provide a bug-reporting address in the +@samp{--help} output. These are implemented in argp by default. @comment argp.h @comment GNU @deftypevar {const char *} argp_program_version If defined or set by the user program to a non-zero value, then a -@samp{--version} option is added when parsing with @code{argp_parse} -(unless the @code{ARGP_NO_HELP} flag is used), which will print this -string followed by a newline and exit (unless the @code{ARGP_NO_EXIT} -flag is used). +@samp{--version} option is added when parsing with @code{argp_parse}, +which will print the @samp{--version} string followed by a newline and +exit. The exception to this is if the @code{ARGP_NO_EXIT} flag is used. @end deftypevar @comment argp.h @comment GNU @deftypevar {const char *} argp_program_bug_address If defined or set by the user program to a non-zero value, -@code{argp_program_bug_address} should point to a string that is the -bug-reporting address for the program. It will be printed at the end of -the standard output for the @samp{--help} option, embedded in a sentence -that says something like @samp{Report bugs to @var{address}.}. +@code{argp_program_bug_address} should point to a string that will be +printed at the end of the standard output for the @samp{--help} option, +embedded in a sentence that says @samp{Report bugs to @var{address}.}. @end deftypevar @need 1500 @comment argp.h @comment GNU @defvar argp_program_version_hook -If defined or set by the user program to a non-zero value, then a -@samp{--version} option is added when parsing with @code{argp_parse} -(unless the @code{ARGP_NO_HELP} flag is used), which calls this function -to print the version, and then exits with a status of 0 (unless the -@code{ARGP_NO_EXIT} flag is used). It should point to a function with -the following type signature: +If defined or set by the user program to a non-zero value, a +@samp{--version} option is added when parsing with @code{arg_parse}, +which prints the program version and exits with a status of zero. This +is not the case if the @code{ARGP_NO_HELP} flag is used. If the +@code{ARGP_NO_EXIT} flag is set, the exit behavior of the program is +suppressed or modified, as when the argp parser is going to be used by +other programs. + +It should point to a function with this type of signature: @smallexample void @var{print-version} (FILE *@var{stream}, struct argp_state *@var{state}) @@ -139,16 +141,16 @@ void @var{print-version} (FILE *@var{stream}, struct argp_state *@var{state}) @noindent @xref{Argp Parsing State}, for an explanation of @var{state}. -This variable takes precedent over @code{argp_program_version}, and is -useful if a program has version information that cannot be easily -specified as a simple string. +This variable takes precedence over @code{argp_program_version}, and is +useful if a program has version information not easily expressed in a +simple string. @end defvar @comment argp.h @comment GNU @deftypevar error_t argp_err_exit_status -The exit status that argp will use when exiting due to a parsing error. -If not defined or set by the user program, this defaults to +This is the exit status used when argp exits due to a parsing error. If +not defined or set by the user program, this defaults to: @code{EX_USAGE} from @file{<sysexits.h>}. @end deftypevar @@ -156,7 +158,7 @@ If not defined or set by the user program, this defaults to @subsection Specifying Argp Parsers The first argument to the @code{argp_parse} function is a pointer to a -@code{struct argp}, which known as an @dfn{argp parser}: +@code{struct argp}, which is known as an @dfn{argp parser}: @comment argp.h @comment GNU @@ -174,49 +176,49 @@ options at all. @xref{Argp Option Vectors}. @item argp_parser_t parser A pointer to a function that defines actions for this parser; it is called for each option parsed, and at other well-defined points in the -parsing process. A value of zero is the same as a pointer to a -function that always returns @code{ARGP_ERR_UNKNOWN}. -@xref{Argp Parser Functions}. +parsing process. A value of zero is the same as a pointer to a function +that always returns @code{ARGP_ERR_UNKNOWN}. @xref{Argp Parser +Functions}. @item const char *args_doc -If non-zero, a string describing what non-option arguments are wanted by -this parser; it is only used to print the @samp{Usage:} message. If it -contains newlines, the strings separated by them are considered -alternative usage patterns, and printed on separate lines (lines after -the first are prefixed by @samp{ or: } instead of @samp{Usage:}). +If non-zero, a string describing what non-option arguments are called by +this parser. This is only used to print the @samp{Usage:} message. If +it contains newlines, the strings separated by them are considered +alternative usage patterns and printed on separate lines. Lines after +the first are prefixed by @samp{ or: } instead of @samp{Usage:}. @item const char *doc If non-zero, a string containing extra text to be printed before and after the options in a long help message, with the two sections separated by a vertical tab (@code{'\v'}, @code{'\013'}) character. By convention, the documentation before the options is just a short string -saying what the program does, and that afterwards is longer, describing -the behavior in more detail. +explaining what the program does. Documentation printed after the +options describe behavior in more detail. @item const struct argp_child *children -A pointer to a vector of @code{argp_children} structures specifying -additional argp parsers that should be combined with this one. -@xref{Argp Children}. +A pointer to a vector of @code{argp_children} structures. This pointer +specifies which additional argp parsers should be combined with this +one. @xref{Argp Children}. @item char *(*help_filter)(int @var{key}, const char *@var{text}, void *@var{input}) -If non-zero, a pointer to a function to filter the output of help +If non-zero, a pointer to a function that filters the output of help messages. @xref{Argp Help Filtering}. @item const char *argp_domain If non-zero, the strings used in the argp library are translated using -the domain described by this string. Otherwise the currently installed -default domain is used. +the domain described by this string. If zero, the current default domain +is used. @end table @end deftp -The @code{options}, @code{parser}, @code{args_doc}, and @code{doc} -fields are usually all that are needed. If an argp parser is defined as -an initialized C variable, only the used fields need be specified in -the initializer---the rest will default to zero due to the way C -structure initialization works (this fact is exploited for most argp -structures, grouping the most-used fields near the beginning, so that -unused fields can simply be left unspecified). +Of the above group, @code{options}, @code{parser}, @code{args_doc}, and +the @code{doc} fields are usually all that are needed. If an argp +parser is defined as an initialized C variable, only the fields used +need be specified in the initializer. The rest will default to zero due +to the way C structure initialization works. This design is exploited in +most argp structures; the most-used fields are grouped near the +beginning, the unused fields left unspecified. @menu * Options: Argp Option Vectors. Specifying options in an argp parser. @@ -230,70 +232,72 @@ unused fields can simply be left unspecified). The @code{options} field in a @code{struct argp} points to a vector of @code{struct argp_option} structures, each of which specifies an option -that argp parser supports (actually, sometimes multiple entries may used -for a single option if it has many names). It should be terminated by -an entry with zero in all fields (note that when using an initialized C -array for options, writing @code{@{ 0 @}} is enough to achieve this). +that the argp parser supports. Multiple entries may be used for a single +option provided it has multiple names. This should be terminated by an +entry with zero in all fields. Note that when using an initialized C +array for options, writing @code{@{ 0 @}} is enough to achieve this. @comment argp.h @comment GNU @deftp {Data Type} {struct argp_option} This structure specifies a single option that an argp parser -understands, and how to parse and document it. It has the following fields: +understands, as well as how to parse and document that option. It has +the following fields: @table @code @item const char *name The long name for this option, corresponding to the long option -@samp{--@var{name}}; this field can be zero if this option only has a -short name. To specify multiple names for an option, additional entries -may follow this one, with the @code{OPTION_ALIAS} flag set (@pxref{Argp -Option Flags}). +@samp{--@var{name}}; this field may be zero if this option @emph{only} +has a short name. To specify multiple names for an option, additional +entries may follow this one, with the @code{OPTION_ALIAS} flag +set. @xref{Argp Option Flags}. @item int key -The integer key that is provided to the argp parser's parsing function -when this option is being parsed. Also, if @var{key} has a value that -is a printable @sc{ascii} character (i.e., @code{isascii (@var{key})} is -true), it @emph{also} specifies a short option @samp{-@var{char}}, where -@var{char} is the @sc{ascii} character with the code @var{key}. +The integer key provided by the current option to the option parser. If +@var{key} has a value that is a printable @sc{ascii} character (i.e., +@code{isascii (@var{key})} is true), it @emph{also} specifies a short +option @samp{-@var{char}}, where @var{char} is the @sc{ascii} character +with the code @var{key}. @item const char *arg If non-zero, this is the name of an argument associated with this option, which must be provided (e.g., with the @samp{--@var{name}=@var{value}} or @samp{-@var{char} @var{value}} -syntaxes) unless the @code{OPTION_ARG_OPTIONAL} flag (@pxref{Argp Option -Flags}) is set, in which case it @emph{may} be provided. +syntaxes), unless the @code{OPTION_ARG_OPTIONAL} flag (@pxref{Argp +Option Flags}) is set, in which case it @emph{may} be provided. @item int flags -Flags associated with this option (some of which are referred to above). +Flags associated with this option, some of which are referred to above. @xref{Argp Option Flags}. @item const char *doc A documentation string for this option, for printing in help messages. If both the @code{name} and @code{key} fields are zero, this string -will be printed out-dented from the normal option column, making it -useful as a group header (it will be the first thing printed in its -group); in this usage, it's conventional to end the string with a +will be printed tabbed left from the normal option column, making it +useful as a group header. This will be the first thing printed in its +group. In this usage, it's conventional to end the string with a @samp{:} character. @item int group -The group this option is in. +Group identity for this option. In a long help message, options are sorted alphabetically within each group, and the groups presented in the order 0, 1, 2, @dots{}, @var{n}, -@minus{}@var{m}, @dots{}, @minus{}2, @minus{}1. Every entry in an -options array with this -field 0 will inherit the group number of the previous entry, or zero if -it's the first one, unless its a group header (@code{name} and -@code{key} fields both zero), in which case, the previous entry + 1 is -the default. Automagic options such as @samp{--help} are put into group -@minus{}1. - -Note that because of C structure initialization rules, this field -often need not be specified, because 0 is the right value. +@minus{}@var{m}, @dots{}, @minus{}2, @minus{}1. + +Every entry in an options array with this field 0 will inherit the group +number of the previous entry, or zero if it's the first one. If it's a +group header with @code{name} and @code{key} fields both zero, the +previous entry + 1 is the default. Automagic options such as +@samp{--help} are put into group @minus{}1. + +Note that because of C structure initialization rules, this field often +need not be specified, because 0 is the correct value. @end table @end deftp + @menu * Flags: Argp Option Flags. Flags for options. @end menu @@ -302,8 +306,9 @@ often need not be specified, because 0 is the right value. @subsubsection Flags for Argp Options The following flags may be or'd together in the @code{flags} field of a -@code{struct argp_option}, and control various aspects of how that -option is parsed or displayed in help messages: +@code{struct argp_option}. These flags control various aspects of how +that option is parsed or displayed in help messages: + @vtable @code @comment argp.h @@ -321,33 +326,35 @@ This option isn't displayed in any help messages. @item OPTION_ALIAS This option is an alias for the closest previous non-alias option. This means that it will be displayed in the same help entry, and will inherit -fields other than @code{name} and @code{key} from the aliased option. +fields other than @code{name} and @code{key} from the option being +aliased. + @comment argp.h @comment GNU @item OPTION_DOC -This option isn't actually an option (and so should be ignored by the -actual option parser), but rather an arbitrary piece of documentation -that should be displayed in much the same manner as the options (known -as a @dfn{documentation option}). +This option isn't actually an option and should be ignored by the actual +option parser. It is an arbitrary section of documentation that should +be displayed in much the same manner as the options. This is known as a +@dfn{documentation option}. If this flag is set, then the option @code{name} field is displayed -unmodified (e.g., no @samp{--} prefix is added) at the left-margin -(where a @emph{short} option would normally be displayed), and the -documentation string in the normal place. For purposes of sorting, any -leading whitespace and punctuation is ignored, except that if the first -non-whitespace character is not @samp{-}, this entry is displayed after -all options (and @code{OPTION_DOC} entries with a leading @samp{-}) in -the same group. +unmodified (e.g., no @samp{--} prefix is added) at the left-margin where +a @emph{short} option would normally be displayed, and this +documentation string is left in it's usual place. For purposes of +sorting, any leading whitespace and punctuation is ignored, unless the +first non-whitespace character is @samp{-}. This entry is displayed +after all options, after @code{OPTION_DOC} entries with a leading +@samp{-}, in the same group. @comment argp.h @comment GNU @item OPTION_NO_USAGE -This option shouldn't be included in `long' usage messages (but is still -included in help messages). This is mainly intended for options that -are completely documented in an argp's @code{args_doc} field -(@pxref{Argp Parsers}), in which case including the option -in the generic usage list would be redundant. +This option shouldn't be included in `long' usage messages, but should +still be included in other help messages. This is intended for options +that are completely documented in an argp's @code{args_doc} +field. @xref{Argp Parsers}. Including this option in the generic usage +list would be redundant, and should be avoided. For instance, if @code{args_doc} is @code{"FOO BAR\n-x BLAH"}, and the @samp{-x} option's purpose is to distinguish these two cases, @samp{-x} @@ -359,9 +366,8 @@ should probably be marked @code{OPTION_NO_USAGE}. The function pointed to by the @code{parser} field in a @code{struct argp} (@pxref{Argp Parsers}) defines what actions take place in response -to each option or argument that is parsed, and is also used as a hook, -to allow a parser to do something at certain other points during -parsing. +to each option or argument parsed. It is also used as a hook, allowing a +parser to perform tasks at certain other points during parsing. @need 2000 Argp parser functions have the following type signature: @@ -377,40 +383,40 @@ where the arguments are as follows: @table @var @item key For each option that is parsed, @var{parser} is called with a value of -@var{key} from that option's @code{key} field in the option vector -(@pxref{Argp Option Vectors}). @var{parser} is also called at other -times with special reserved keys, such as @code{ARGP_KEY_ARG} for +@var{key} from that option's @code{key} field in the option +vector. @xref{Argp Option Vectors}. @var{parser} is also called at +other times with special reserved keys, such as @code{ARGP_KEY_ARG} for non-option arguments. @xref{Argp Special Keys}. @item arg -If @var{key} is an option, @var{arg} is the value given for it, or zero -if no value was specified. Only options that have a non-zero @code{arg} -field can ever have a value, and those must @emph{always} have a value, -unless the @code{OPTION_ARG_OPTIONAL} flag was specified (if the input -being parsed specifies a value for an option that doesn't allow one, an -error results before @var{parser} ever gets called). +If @var{key} is an option, @var{arg} is its given value. This defaults +to zero if no value is specified. Only options that have a non-zero +@code{arg} field can ever have a value. These must @emph{always} have a +value unless the @code{OPTION_ARG_OPTIONAL} flag is specified. If the +input being parsed specifies a value for an option that doesn't allow +one, an error results before @var{parser} ever gets called. -If @var{key} is @code{ARGP_KEY_ARG}, @var{arg} is a non-option argument; -other special keys always have a zero @var{arg}. +If @var{key} is @code{ARGP_KEY_ARG}, @var{arg} is a non-option +argument. Other special keys always have a zero @var{arg}. @item state @var{state} points to a @code{struct argp_state}, containing useful -information about the current parsing state for use by @var{parser}. -@xref{Argp Parsing State}. +information about the current parsing state for use by +@var{parser}. @xref{Argp Parsing State}. @end table When @var{parser} is called, it should perform whatever action is -appropriate for @var{key}, and return either @code{0} for success, -@code{ARGP_ERR_UNKNOWN}, if the value of @var{key} is not handled by -this parser function, or a unix error code if a real error occurred -(@pxref{Error Codes}). +appropriate for @var{key}, and return @code{0} for success, +@code{ARGP_ERR_UNKNOWN} if the value of @var{key} is not handled by this +parser function, or a unix error code if a real error +occurred. @xref{Error Codes}. @comment argp.h @comment GNU @deftypevr Macro int ARGP_ERR_UNKNOWN Argp parser functions should return @code{ARGP_ERR_UNKNOWN} for any @var{key} value they do not recognize, or for non-option arguments -(@code{@var{key} == ARGP_KEY_ARG}) that they do not wish to handle. +(@code{@var{key} == ARGP_KEY_ARG}) that they are not equipped to handle. @end deftypevr @need 3000 @@ -444,8 +450,8 @@ parse_opt (int key, char *arg, struct argp_state *state) In addition to key values corresponding to user options, the @var{key} argument to argp parser functions may have a number of other special -values (@var{arg} and @var{state} refer to parser function arguments; -@pxref{Argp Parser Functions}): +values. In the following example @var{arg} and @var{state} refer to +parser function arguments. @xref{Argp Parser Functions}. @vtable @code @comment argp.h @@ -454,19 +460,19 @@ values (@var{arg} and @var{state} refer to parser function arguments; This is not an option at all, but rather a command line argument, whose value is pointed to by @var{arg}. -When there are multiple parser functions (due to argp parsers being -combined), it's impossible to know which one wants to handle an -argument, so each is called in turn, until one returns 0 or an error -other than @code{ARGP_ERR_UNKNOWN}; if an argument is handled by no one, +When there are multiple parser functions in play due to argp parsers +being combined, it's impossible to know which one will handle a specific +argument. Each is called until one returns 0 or an error other than +@code{ARGP_ERR_UNKNOWN}; if an argument is not handled, @code{argp_parse} immediately returns success, without parsing any more arguments. Once a parser function returns success for this key, that fact is -recorded, and the @code{ARGP_KEY_NO_ARGS} case won't be used. -@emph{However}, if while processing the argument, a parser function +recorded, and the @code{ARGP_KEY_NO_ARGS} case won't be +used. @emph{However}, if while processing the argument a parser function decrements the @code{next} field of its @var{state} argument, the option won't be considered processed; this is to allow you to actually modify -the argument (perhaps into an option), and have it processed again. +the argument, perhaps into an option, and have it processed again. @comment argp.h @comment GNU @@ -477,10 +483,11 @@ If a parser function returns @code{ARGP_ERR_UNKNOWN} for convenient for consuming all remaining arguments. @var{arg} is 0, and the tail of the argument vector may be found at @code{@var{state}->argv + @var{state}->next}. If success is returned for this key, and -@code{@var{state}->next} is unchanged, then all remaining arguments are -considered to have been consumed, otherwise, the amount by which -@code{@var{state}->next} has been adjust indicates how many were used. -For instance, here's an example that uses both, for different args: +@code{@var{state}->next} is unchanged, all remaining arguments are +considered to have been consumed. Otherwise, the amount by which +@code{@var{state}->next} has been adjusted indicates how many were used. +Here's an example that uses both, for different args: + @smallexample ... @@ -501,131 +508,132 @@ case ARGP_KEY_ARGS: @comment argp.h @comment GNU @item ARGP_KEY_END -There are no more command line arguments at all. The parser functions -are called in different order (means children first) for this value -which allows each parser to clean up its state for the parent. +This indicates that there are no more command line arguments. Parser +functions are called in a different order, children first. This allows +each parser to clean up its state for the parent. @comment argp.h @comment GNU @item ARGP_KEY_NO_ARGS -Because it's common to want to do some special processing if there -aren't any non-option args, parser functions are called with this key if -they didn't successfully process any non-option arguments. Called just -before @code{ARGP_KEY_END} (where more general validity checks on -previously parsed arguments can take place). +Because it's common to do some special processing if there aren't any +non-option args, parser functions are called with this key if they +didn't successfully process any non-option arguments. This is called +just before @code{ARGP_KEY_END}, where more general validity checks on +previously parsed arguments take place. @comment argp.h @comment GNU @item ARGP_KEY_INIT -Passed in before any parsing is done. Afterwards, the values of each -element of the @code{child_input} field of @var{state}, if any, are +This is passed in before any parsing is done. Afterwards, the values of +each element of the @code{child_input} field of @var{state}, if any, are copied to each child's state to be the initial value of the @code{input} when @emph{their} parsers are called. @comment argp.h @comment GNU @item ARGP_KEY_SUCCESS -Passed in when parsing has successfully been completed (even if there are -still arguments remaining). +Passed in when parsing has successfully been completed, even if +arguments remain. @comment argp.h @comment GNU @item ARGP_KEY_ERROR -Passed in if an error has occurred, and parsing terminated (in which case -a call with a key of @code{ARGP_KEY_SUCCESS} is never made). +Passed in if an error has occurred and parsing is terminated. In this +case a call with a key of @code{ARGP_KEY_SUCCESS} is never made. @comment argp.h @comment GNU @item ARGP_KEY_FINI -The final key ever seen by any parser (even after -@code{ARGP_KEY_SUCCESS} and @code{ARGP_KEY_ERROR}). Any resources -allocated by @code{ARGP_KEY_INIT} may be freed here (although sometimes -certain resources allocated there are to be returned to the caller after -a successful parse; in that case, those particular resources can be -freed in the @code{ARGP_KEY_ERROR} case). +The final key ever seen by any parser, even after +@code{ARGP_KEY_SUCCESS} and @code{ARGP_KEY_ERROR}. Any resources +allocated by @code{ARGP_KEY_INIT} may be freed here. At times, certain +resources allocated are to be returned to the caller after a successful +parse. In that case, those particular resources can be freed in the +@code{ARGP_KEY_ERROR} case. @end vtable In all cases, @code{ARGP_KEY_INIT} is the first key seen by parser -functions, and @code{ARGP_KEY_FINI} the last (unless an error was -returned by the parser for @code{ARGP_KEY_INIT}). Other keys can occur -in one the following orders (@var{opt} refers to an arbitrary option -key): +functions, and @code{ARGP_KEY_FINI} the last, unless an error was +returned by the parser for @code{ARGP_KEY_INIT}. Other keys can occur +in one the following orders. @var{opt} refers to an arbitrary option +key: @table @asis @item @var{opt}@dots{} @code{ARGP_KEY_NO_ARGS} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS} -The arguments being parsed contained no non-option arguments at all. +The arguments being parsed did not contain any non-option arguments. @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_END} @code{ARGP_KEY_SUCCESS} -All non-option arguments were successfully handled by a parser function -(there may be multiple parser functions if multiple argp parsers were -combined). +All non-option arguments were successfully handled by a parser +function. There may be multiple parser functions if multiple argp +parsers were combined. @item ( @var{opt} | @code{ARGP_KEY_ARG} )@dots{} @code{ARGP_KEY_SUCCESS} -Some non-option argument was unrecognized. +Some non-option argument went unrecognized. This occurs when every parser function returns @code{ARGP_KEY_UNKNOWN} -for an argument, in which case parsing stops at that argument. If -@var{arg_index} is a null pointer otherwise an error occurs. +for an argument, in which case parsing stops at that argument if +@var{arg_index} is a null pointer. Otherwise an error occurs. @end table -In all cases, if a non-null value for @var{arg_index} was passed to +In all cases, if a non-null value for @var{arg_index} gets passed to @code{argp_parse}, the index of the first unparsed command-line argument -is passed back in it. +is passed back in that value. -If an error occurs (either detected by argp, or because a parser -function returned an error value), then each parser is called with -@code{ARGP_KEY_ERROR}, and no further calls are made except the final -call with @code{ARGP_KEY_FINI}. +If an error occurs and is either detected by argp or because a parser +function returned an error value, each parser is called with +@code{ARGP_KEY_ERROR}. No further calls are made, except the final call +with @code{ARGP_KEY_FINI}. @node Argp Helper Functions, , Argp Parsing State, Argp Parser Functions @subsubsection Functions For Use in Argp Parsers -Argp provides a number of functions for the user of argp parser -functions (@pxref{Argp Parser Functions}), mostly for producing error -messages. These take as their first argument the @var{state} argument -to the parser function (@pxref{Argp Parsing State}). +Argp provides a number of functions available to the user of argp +(@pxref{Argp Parser Functions}), mostly for producing error messages. +These take as their first argument the @var{state} argument to the +parser function. @xref{Argp Parsing State}. + @cindex usage messages, in argp @comment argp.h @comment GNU @deftypefun void argp_usage (const struct argp_state *@var{state}) -Output the standard usage message for the argp parser referred to by +Outputs the standard usage message for the argp parser referred to by @var{state} to @code{@var{state}->err_stream} and terminate the program -with @code{exit (argp_err_exit_status)} (@pxref{Argp Global Variables}). +with @code{exit (argp_err_exit_status)}. @xref{Argp Global Variables}. @end deftypefun @cindex syntax error messages, in argp @comment argp.h @comment GNU @deftypefun void argp_error (const struct argp_state *@var{state}, const char *@var{fmt}, @dots{}) -Print the printf format string @var{fmt} and following args, preceded by -the program name and @samp{:}, and followed by a @w{@samp{Try @dots{} ---help}} message, and terminate the program with an exit status of -@code{argp_err_exit_status} (@pxref{Argp Global Variables}). +Prints the printf format string @var{fmt} and following args, preceded +by the program name and @samp{:}, and followed by a @w{@samp{Try @dots{} +--help}} message, and terminates the program with an exit status of +@code{argp_err_exit_status}. @xref{Argp Global Variables}. @end deftypefun @cindex error messages, in argp @comment argp.h @comment GNU @deftypefun void argp_failure (const struct argp_state *@var{state}, int @var{status}, int @var{errnum}, const char *@var{fmt}, @dots{}) -Similarly to the standard gnu error-reporting function @code{error}, -print the printf format string @var{fmt} and following args, preceded by -the program name and @samp{:}, and followed by the standard unix error -text for @var{errnum} if it is non-zero; then if @var{status} is -non-zero, terminate the program with that as its exit status. +Similar to the standard gnu error-reporting function @code{error}, this +prints the program name and @samp{:}, the printf format string +@var{fmt}, and the appropriate following args. If it is non-zero, the +standard unix error text for @var{errnum} is printed. If @var{status} is +non-zero, it terminates the program with that value as its exit status. -The difference between this function and @code{argp_error} is that +The difference between @code{argp_failure} and @code{argp_error} is that @code{argp_error} is for @emph{parsing errors}, whereas @code{argp_failure} is for other problems that occur during parsing but -don't reflect a syntactic problem with the input---such as illegal -values for options, bad phase of the moon, etc. +don't reflect a syntactic problem with the input, such as illegal values +for options, bad phase of the moon, etc. @end deftypefun @comment argp.h @comment GNU @deftypefun void argp_state_help (const struct argp_state *@var{state}, FILE *@var{stream}, unsigned @var{flags}) -Output a help message for the argp parser referred to by @var{state} to -@var{stream}. The @var{flags} argument determines what sort of help +Outputs a help message for the argp parser referred to by @var{state}, +to @var{stream}. The @var{flags} argument determines what sort of help message is produced. @xref{Argp Help Flags}. @end deftypefun @@ -633,15 +641,15 @@ Error output is sent to @code{@var{state}->err_stream}, and the program name printed is @code{@var{state}->name}. The output or program termination behavior of these functions may be -suppressed if the @code{ARGP_NO_EXIT} or @code{ARGP_NO_ERRS} flags, -respectively, were passed to @code{argp_parse}. @xref{Argp Flags}. +suppressed if the @code{ARGP_NO_EXIT} or @code{ARGP_NO_ERRS} flags are +passed to @code{argp_parse}. @xref{Argp Flags}. This behavior is useful if an argp parser is exported for use by other programs (e.g., by a library), and may be used in a context where it is -not desirable to terminate the program in response to parsing errors. -In argp parsers intended for such general use, calls to any of these -functions should be followed by code return of an appropriate error code -for the case where the program @emph{doesn't} terminate; for example: +not desirable to terminate the program in response to parsing errors. In +argp parsers intended for such general use, and for the case where the +program @emph{doesn't} terminate, calls to any of these functions should +be followed by code that returns the appropriate error code: @smallexample if (@var{bad argument syntax}) @@ -652,8 +660,8 @@ if (@var{bad argument syntax}) @end smallexample @noindent -If it's known that a parser function will only be used when -@code{ARGP_NO_EXIT} is not set, the return may be omitted. +If a parser function will @emph{only} be used when @code{ARGP_NO_EXIT} +is not set, the return may be omitted. @node Argp Parsing State, Argp Helper Functions, Argp Special Keys, Argp Parser Functions @subsubsection Argp Parsing State @@ -671,53 +679,54 @@ This structure has the following fields, which may be modified as noted: @item const struct argp *const root_argp The top level argp parser being parsed. Note that this is often @emph{not} the same @code{struct argp} passed into @code{argp_parse} by -the invoking program (@pxref{Argp}), but instead an internal argp parser -that contains options implemented by @code{argp_parse} itself (such as -@samp{--help}). +the invoking program. @xref{Argp}. It is an internal argp parser that +contains options implemented by @code{argp_parse} itself, such as +@samp{--help}. @item int argc @itemx char **argv -The argument vector being parsed. May be modified. +The argument vector being parsed. This may be modified. @item int next -The index in @code{argv} of the next argument to be parsed. May be modified. +The index in @code{argv} of the next argument to be parsed. This may be +modified. One way to consume all remaining arguments in the input is to set -@code{@var{state}->next = @var{state}->argc} (perhaps after recording -the value of the @code{next} field to find the consumed arguments). -Also, you can cause the current option to be re-parsed by decrementing -this field, and then modifying -@code{@var{state}->argv[@var{state}->next]} to be the option that should -be reexamined. +@code{@var{state}->next = @var{state}->argc}, perhaps after recording +the value of the @code{next} field to find the consumed arguments. The +current option can be re-parsed immediately by decrementing this field, +then modifying @code{@var{state}->argv[@var{state}->next]} to reflect +the option that should be reexamined. @item unsigned flags -The flags supplied to @code{argp_parse}. May be modified, although some -flags may only take effect when @code{argp_parse} is first invoked. -@xref{Argp Flags}. +The flags supplied to @code{argp_parse}. These may be modified, although +some flags may only take effect when @code{argp_parse} is first +invoked. @xref{Argp Flags}. @item unsigned arg_num While calling a parsing function with the @var{key} argument -@code{ARGP_KEY_ARG}, this is the number of the current arg, starting at -0, and incremented after each such call returns. At all other times, -this is the number of such arguments that have been processed. +@code{ARGP_KEY_ARG}, this represents the number of the current arg, +starting at 0. It is incremented after each @code{ARGP_KEY_ARG} call +returns. At all other times, this is the number of @code{ARGP_KEY_ARG} +arguments that have been processed. @item int quoted If non-zero, the index in @code{argv} of the first argument following a -special @samp{--} argument (which prevents anything following being -interpreted as an option). Only set once argument parsing has proceeded -past this point. +special @samp{--} argument. This prevents anything that follows from +being interpreted as an option. It is only set after argument parsing +has proceeded past this point. @item void *input An arbitrary pointer passed in from the caller of @code{argp_parse}, in the @var{input} argument. @item void **child_inputs -Values to pass to child parsers. This vector will be the same length as -the number of children in the current parser, and each child parser will -be given the value of @code{@var{state}->child_inputs[@var{i}]} as -@emph{its} @code{@var{state}->input} field, where @var{i} is the index -of the child in the this parser's @code{children} field. @xref{Argp -Children}. +These are values that will be passed to child parsers. This vector will +be the same length as the number of children in the current parser. Each +child parser will be given the value of +@code{@var{state}->child_inputs[@var{i}]} as @emph{its} +@code{@var{state}->input} field, where @var{i} is the index of the child +in the this parser's @code{children} field. @xref{Argp Children}. @item void *hook For the parser function's use. Initialized to 0, but otherwise ignored @@ -725,15 +734,15 @@ by argp. @item char *name The name used when printing messages. This is initialized to -@code{argv[0]}, or @code{program_invocation_name} if that is +@code{argv[0]}, or @code{program_invocation_name} if @code{argv[0]} is unavailable. @item FILE *err_stream @itemx FILE *out_stream -Stdio streams used when argp prints something; error messages are -printed to @code{err_stream}, and all other output (such as -@samp{--help} output) to @code{out_stream}. These are initialized to -@code{stderr} and @code{stdout} respectively (@pxref{Standard Streams}). +The stdio streams used when argp prints. Error messages are printed to +@code{err_stream}, all other output, such as @samp{--help} output) to +@code{out_stream}. These are initialized to @code{stderr} and +@code{stdout} respectively. @xref{Standard Streams}. @item void *pstate Private, for use by the argp implementation. @@ -743,45 +752,48 @@ Private, for use by the argp implementation. @node Argp Children, Argp Help Filtering, Argp Parser Functions, Argp Parsers @subsection Combining Multiple Argp Parsers -The @code{children} field in a @code{struct argp} allows other argp -parsers to be combined with the referencing one to parse a single set of -arguments. It should point to a vector of @code{struct argp_child}, -terminated by an entry having a value of zero in the @code{argp} field. +The @code{children} field in a @code{struct argp} enables other argp +parsers to be combined with the referencing one for the parsing of a +single set of arguments. This field should point to a vector of +@code{struct argp_child}, which is terminated by an entry having a value +of zero in the @code{argp} field. -Where conflicts between combined parsers arise (for instance, if two -specify an option with the same name), they are resolved in favor of -the parent argp parsers, or earlier argp parsers in the list of children. +Where conflicts between combined parsers arise, as when two specify an +option with the same name, the parser conflicts are resolved in favor of +the parent argp parser(s), or the earlier of the argp parsers in the +list of children. @comment argp.h @comment GNU @deftp {Data Type} {struct argp_child} An entry in the list of subsidiary argp parsers pointed to by the -@code{children} field in a @code{struct argp}. The fields are as follows: +@code{children} field in a @code{struct argp}. The fields are as +follows: @table @code @item const struct argp *argp -The child argp parser, or zero to end the list. +The child argp parser, or zero to end of the list. @item int flags Flags for this child. @item const char *header -If non-zero, an optional header to be printed in help output before the -child options. As a side-effect, a non-zero value forces the child -options to be grouped together; to achieve this effect without actually -printing a header string, use a value of @code{""}. As with header -strings specified in an option entry, the value conventionally has -@samp{:} as the last character. @xref{Argp Option Vectors}. +If non-zero, this is an optional header to be printed within help output +before the child options. As a side-effect, a non-zero value forces the +child options to be grouped together. To achieve this effect without +actually printing a header string, use a value of @code{""}. As with +header strings specified in an option entry, the conventional value of +the last character is @samp{:}. @xref{Argp Option Vectors}. @item int group -Where to group the child options relative to the other (`consolidated') -options in the parent argp parser. The values are the same as the -@code{group} field in @code{struct argp_option} (@pxref{Argp Option -Vectors}), but all child-groupings follow parent options at a particular -group level. If both this field and @code{header} are zero, then the -child's options aren't grouped together at all, but rather merged with -the parent options (merging the child's grouping levels with the -parents). +This is where the child options are grouped relative to the other +`consolidated' options in the parent argp parser. The values are the +same as the @code{group} field in @code{struct argp_option}. @xref{Argp +Option Vectors}. All child-groupings follow parent options at a +particular group level. If both this field and @code{header} are zero, +then the child's options aren't grouped together, they are merged with +parent options at the parent option group level. + @end table @end deftp @@ -798,10 +810,9 @@ modify these defaults, the following flags may be or'd together in the @comment GNU @item ARGP_PARSE_ARGV0 Don't ignore the first element of the @var{argv} argument to -@code{argp_parse}. Normally (and always unless @code{ARGP_NO_ERRS} is -set) the first element of the argument vector is skipped for option -parsing purposes, as it corresponds to the program name in a command -line. +@code{argp_parse}. Unless @code{ARGP_NO_ERRS} is set, the first element +of the argument vector is skipped for option parsing purposes, as it +corresponds to the program name in a command line. @comment argp.h @comment GNU @@ -809,44 +820,44 @@ line. Don't print error messages for unknown options to @code{stderr}; unless this flag is set, @code{ARGP_PARSE_ARGV0} is ignored, as @code{argv[0]} is used as the program name in the error messages. This flag implies -@code{ARGP_NO_EXIT} (on the assumption that silent exiting upon errors -is bad behavior). +@code{ARGP_NO_EXIT}. This is based on the assumption that silent exiting +upon errors is bad behavior. @comment argp.h @comment GNU @item ARGP_NO_ARGS -Don't parse any non-option args. Normally non-option args are parsed by -calling the parse functions with a key of @code{ARGP_KEY_ARG}, and the -actual arg as the value. This flag needn't normally be set, as the -normal behavior is to stop parsing as soon as some argument isn't -accepted by a parsing function. @xref{Argp Parser Functions}. +Don't parse any non-option args. Normally these are parsed by calling +the parse functions with a key of @code{ARGP_KEY_ARG}, the actual +argument being the value. This flag needn't normally be set, as the +default behavior is to stop parsing as soon as an argument fails to be +parsed. @xref{Argp Parser Functions}. @comment argp.h @comment GNU @item ARGP_IN_ORDER Parse options and arguments in the same order they occur on the command -line---normally they're rearranged so that all options come first +line. Normally they're rearranged so that all options come first. @comment argp.h @comment GNU @item ARGP_NO_HELP Don't provide the standard long option @samp{--help}, which ordinarily -causes usage and option help information to be output to @code{stdout}, -and @code{exit (0)} called. +causes usage and option help information to be output to @code{stdout} +and @code{exit (0)}. @comment argp.h @comment GNU @item ARGP_NO_EXIT -Don't exit on errors (they may still result in error messages). +Don't exit on errors, although they may still result in error messages. @comment argp.h @comment GNU @item ARGP_LONG_ONLY -Use the gnu getopt `long-only' rules for parsing arguments. This -allows long-options to be recognized with only a single @samp{-} (for -instances, @samp{-help}), but results in a generally somewhat less -useful interface, that conflicts with the way most GNU programs work. -For this reason, its use is discouraged. +Use the gnu getopt `long-only' rules for parsing arguments. This allows +long-options to be recognized with only a single @samp{-} +(i.e. @samp{-help}). This results in a less useful interface, and its +use is discouraged as it conflicts with the way most GNU programs work +as well as the GNU coding standards. @comment argp.h @comment GNU @@ -860,27 +871,28 @@ Turns off any message-printing/exiting options, specifically @subsection Customizing Argp Help Output The @code{help_filter} field in a @code{struct argp} is a pointer to a -function to filter the text of help messages before displaying them. -They have a function signature like: +function that filters the text of help messages before displaying +them. They have a function signature like: @smallexample char *@var{help-filter} (int @var{key}, const char *@var{text}, void *@var{input}) @end smallexample + @noindent -where @var{key} is either a key from an option, in which case @var{text} -is that option's help text (@pxref{Argp Option Vectors}), or one of the -special keys with names beginning with @samp{ARGP_KEY_HELP_}, describing -which other help text @var{text} is (@pxref{Argp Help Filter Keys}). - -The function should return either @var{text}, if it should be used -as-is, a replacement string, which should be allocated using -@code{malloc}, and will be freed by argp, or zero, meaning `print -nothing'. The value of @var{text} supplied is @emph{after} any -translation has been done, so if any of the replacement text also needs -translation, that should be done by the filter function. @var{input} is -either the input supplied to @code{argp_parse}, or zero, if -@code{argp_help} was called directly by the user. +Where @var{key} is either a key from an option, in which case @var{text} +is that option's help text. @xref{Argp Option Vectors}. Alternately, one +of the special keys with names beginning with @samp{ARGP_KEY_HELP_} +might be used, describing which other help text @var{text} will contain. +@xref{Argp Help Filter Keys}. + +The function should return either @var{text} if it remains as-is, or a +replacement string allocated using @code{malloc}. This will be either be +freed by argp or zero, which prints nothing. The value of @var{text} is +supplied @emph{after} any translation has been done, so if any of the +replacement text needs translation, it will be done by the filter +function. @var{input} is either the input supplied to @code{argp_parse} +or it is zero, if @code{argp_help} was called directly by the user. @menu * Keys: Argp Help Filter Keys. Special @var{key} values for help filter functions. @@ -890,66 +902,63 @@ either the input supplied to @code{argp_parse}, or zero, if @subsubsection Special Keys for Argp Help Filter Functions The following special values may be passed to an argp help filter -function as the first argument, in addition to key values for user -options, and specify which help text the @var{text} argument contains: +function as the first argument in addition to key values for user +options. They specify which help text the @var{text} argument contains: @vtable @code @comment argp.h @comment GNU @item ARGP_KEY_HELP_PRE_DOC -Help text preceding options. +The help text preceding options. @comment argp.h @comment GNU @item ARGP_KEY_HELP_POST_DOC -Help text following options. +The help text following options. @comment argp.h @comment GNU @item ARGP_KEY_HELP_HEADER -Option header string. +The option header string. @comment argp.h @comment GNU @item ARGP_KEY_HELP_EXTRA -After all other documentation; @var{text} is zero for this key. +This is used after all other documentation; @var{text} is zero for this key. @comment argp.h @comment GNU @item ARGP_KEY_HELP_DUP_ARGS_NOTE -The explanatory note emitted when duplicate option arguments have been -suppressed. +The explanatory note printed when duplicate option arguments have been suppressed. @comment argp.h @comment GNU @item ARGP_KEY_HELP_ARGS_DOC -The argument doc string (the @code{args_doc} field from the argp parser; -@pxref{Argp Parsers}). +The argument doc string; formally the @code{args_doc} field from the argp parser. @xref{Argp Parsers}. @end vtable @node Argp Help, Argp Examples, Argp Flags, Argp @subsection The @code{argp_help} Function -Normally programs using argp need not worry too much about printing -argument-usage-type help messages, because the standard @samp{--help} -option is handled automatically by argp, and the typical error cases can -be handled using @code{argp_usage} and @code{argp_error} (@pxref{Argp -Helper Functions}). - -However, if it's desirable to print a standard help message in some -context other than parsing the program options, argp offers the -@code{argp_help} interface. +Normally programs using argp need not be written with particular +printing argument-usage-type help messages in mind as the standard +@samp{--help} option is handled automatically by argp. Typical error +cases can be handled using @code{argp_usage} and +@code{argp_error}. @xref{Argp Helper Functions}. However, if it's +desirable to print a help message in some context other than parsing the +program options, argp offers the @code{argp_help} interface. @comment argp.h @comment GNU @deftypefun void argp_help (const struct argp *@var{argp}, FILE *@var{stream}, unsigned @var{flags}, char *@var{name}) -Output a help message for the argp parser @var{argp} to @var{stream}. -What sort of messages is printed is determined by @var{flags}. +This outputs a help message for the argp parser @var{argp} to +@var{stream}. The type of messages printed will be determined by +@var{flags}. Any options such as @samp{--help} that are implemented automatically by argp itself will @emph{not} be present in the help output; for this -reason, it is better to use @code{argp_state_help} if calling from -within an argp parser function. @xref{Argp Helper Functions}. +reason it is best to use @code{argp_state_help} if calling from within +an argp parser function. @xref{Argp Helper Functions}. @end deftypefun @menu @@ -959,73 +968,74 @@ within an argp parser function. @xref{Argp Helper Functions}. @node Argp Help Flags, , , Argp Help @subsection Flags for the @code{argp_help} Function -When calling @code{argp_help} (@pxref{Argp Help}), or -@code{argp_state_help} (@pxref{Argp Helper Functions}), exactly what is -output is determined by the @var{flags} argument, which should consist -of any of the following flags, or'd together: +When calling @code{argp_help} (@pxref{Argp Help}) or +@code{argp_state_help} (@pxref{Argp Helper Functions}) the exact output +is determined by the @var{flags} argument. This should consist of any of +the following flags, or'd together: @vtable @code @item ARGP_HELP_USAGE A unix @samp{Usage:} message that explicitly lists all options. @item ARGP_HELP_SHORT_USAGE -A unix @samp{Usage:} message that displays only an appropriate -placeholder to indicate where the options go; useful for showing -the non-option argument syntax. +A unix @samp{Usage:} message that displays an appropriate placeholder to +indicate where the options go; useful for showing the non-option +argument syntax. @item ARGP_HELP_SEE A @samp{Try @dots{} for more help} message; @samp{@dots{}} contains the program name and @samp{--help}. @item ARGP_HELP_LONG -A verbose option help message that gives each option understood along +A verbose option help message that gives each option available along with its documentation string. @item ARGP_HELP_PRE_DOC -The part of the argp parser doc string that precedes the verbose option help. +The part of the argp parser doc string preceding the verbose option help. @item ARGP_HELP_POST_DOC -The part of the argp parser doc string that follows the verbose option help. +The part of the argp parser doc string that following the verbose option help. @item ARGP_HELP_DOC @code{(ARGP_HELP_PRE_DOC | ARGP_HELP_POST_DOC)} @item ARGP_HELP_BUG_ADDR -A message saying where to report bugs for this program, if the -@code{argp_program_bug_address} variable contains one. +A message that prints where to report bugs for this program, if the +@code{argp_program_bug_address} variable contains this information. @item ARGP_HELP_LONG_ONLY -Modify any output appropriately to reflect @code{ARGP_LONG_ONLY} mode. +This will modify any output to reflect the @code{ARGP_LONG_ONLY} mode. @end vtable The following flags are only understood when used with -@code{argp_state_help}, and control whether the function returns after +@code{argp_state_help}. They control whether the function returns after printing its output, or terminates the program: @vtable @code @item ARGP_HELP_EXIT_ERR -Terminate the program with @code{exit (argp_err_exit_status)}. +This will terminate the program with @code{exit (argp_err_exit_status)}. @item ARGP_HELP_EXIT_OK -Terminate the program with @code{exit (0)}. +This will terminate the program with @code{exit (0)}. @end vtable -The following flags are combinations of the basic ones for printing +The following flags are combinations of the basic flags for printing standard messages: @vtable @code @item ARGP_HELP_STD_ERR -Assuming an error message for a parsing error has already printed, -prints a note on how to get help, and terminates the program with an +Assuming that an error message for a parsing error has printed, this +prints a message on how to get help, and terminates the program with an error. @item ARGP_HELP_STD_USAGE -Prints a standard usage message and terminates the program with an -error. This is used when no more specific error message is appropriate. +This prints a standard usage message and terminates the program with an +error. This is used when no other specific error messages are +appropriate or available. @item ARGP_HELP_STD_HELP -Prints the standard response for a @samp{--help} option, and terminates -the program successfully. +This prints the standard response for a @samp{--help} option, and +terminates the program successfully. @end vtable @node Argp Examples, Argp User Customization, Argp Help, Argp @@ -1043,9 +1053,9 @@ These example programs demonstrate the basic usage of argp. @node Argp Example 1, Argp Example 2, , Argp Examples @subsubsection A Minimal Program Using Argp -This is (probably) the smallest possible program that uses argp. -It won't do much except give an error messages and exit when there are any -arguments, and print a (rather pointless) message for @samp{--help}. +This is perhaps the smallest program possible that uses argp. It won't +do much except give an error messages and exit when there are any +arguments, and prints a rather pointless message for @samp{--help}. @smallexample @include argp-ex1.c.texi @@ -1054,22 +1064,23 @@ arguments, and print a (rather pointless) message for @samp{--help}. @node Argp Example 2, Argp Example 3, Argp Example 1, Argp Examples @subsubsection A Program Using Argp with Only Default Options -This program doesn't use any options or arguments, but uses argp to be +This program doesn't use any options or arguments, it uses argp to be compliant with the GNU standard command line format. -In addition to making sure no arguments are given, and implementing a -@samp{--help} option, this example will have a @samp{--version} option, -and will put the given documentation string and bug address in the -@samp{--help} output, as per GNU standards. - -The variable @code{argp} contains the argument parser specification; -adding fields to this structure is the way most parameters are passed to -@code{argp_parse} (the first three fields are usually used, but not in -this small program). There are also two global variables that argp -knows about defined here, @code{argp_program_version} and -@code{argp_program_bug_address} (they are global variables because they -will almost always be constant for a given program, even if it uses -different argument parsers for various tasks). +In addition to giving no arguments and implementing a @samp{--help} +option, this example has a @samp{--version} option, which will put the +given documentation string and bug address in the @samp{--help} output, +as per GNU standards. + +The variable @code{argp} contains the argument parser +specification. Adding fields to this structure is the way most +parameters are passed to @code{argp_parse}. The first three fields are +normally used, but they are not in this small program. There are also +two global variables that argp can use defined here, +@code{argp_program_version} and @code{argp_program_bug_address}. They +are considered global variables because they will almost always be +constant for a given program, even if they use different argument +parsers for various tasks. @smallexample @include argp-ex2.c.texi @@ -1078,20 +1089,20 @@ different argument parsers for various tasks). @node Argp Example 3, Argp Example 4, Argp Example 2, Argp Examples @subsubsection A Program Using Argp with User Options -This program uses the same features as example 2, and adds user options +This program uses the same features as example 2, adding user options and arguments. -We now use the first four fields in @code{argp} (@pxref{Argp Parsers}), -and specifies @code{parse_opt} as the parser function (@pxref{Argp -Parser Functions}). +We now use the first four fields in @code{argp} (@pxref{Argp Parsers}) +and specify @code{parse_opt} as the parser function. @xref{Argp Parser +Functions}. Note that in this example, @code{main} uses a structure to communicate with the @code{parse_opt} function, a pointer to which it passes in the -@code{input} argument to @code{argp_parse} (@pxref{Argp}), and is -retrieved by @code{parse_opt} through the @code{input} field in its -@code{state} argument (@pxref{Argp Parsing State}). Of course, it's -also possible to use global variables instead, but using a structure -like this is somewhat more flexible and clean. +@code{input} argument to @code{argp_parse}. @xref{Argp}. It is retrieved +by @code{parse_opt} through the @code{input} field in its @code{state} +argument. @xref{Argp Parsing State}. Of course, it's also possible to +use global variables instead, but using a structure like this is +somewhat more flexible and clean. @smallexample @include argp-ex3.c.texi @@ -1101,26 +1112,27 @@ like this is somewhat more flexible and clean. @subsubsection A Program Using Multiple Combined Argp Parsers This program uses the same features as example 3, but has more options, -and somewhat more structure in the @samp{--help} output. It also shows -how you can `steal' the remainder of the input arguments past a certain -point, for programs that accept a list of items, and the special -@var{key} value @code{ARGP_KEY_NO_ARGS}, which is only given if no -non-option arguments were supplied to the program (@pxref{Argp Special -Keys}). - -For structuring the help output, two features are used: @emph{headers}, -which are entries in the options vector (@pxref{Argp Option Vectors}) -with the first four fields being zero, and a two part documentation -string (in the variable @code{doc}), which allows documentation both -before and after the options (@pxref{Argp Parsers}); the -two parts of @code{doc} are separated by a vertical-tab character -(@code{'\v'}, or @code{'\013'}). By convention, the documentation -before the options is just a short string saying what the program does, -and that afterwards is longer, describing the behavior in more detail. -All documentation strings are automatically filled for output, although -newlines may be included to force a line break at a particular point. -All documentation strings are also passed to the @code{gettext} -function, for possible translation into the current locale. +and presents more structure in the @samp{--help} output. It also +illustrates how you can `steal' the remainder of the input arguments +past a certain point for programs that accept a list of items. It also +illustrates the @var{key} value @code{ARGP_KEY_NO_ARGS}, which is only +given if no non-option arguments were supplied to the +program. @xref{Argp Special Keys}. + +For structuring help output, two features are used: @emph{headers} and a +two part option string. The @emph{headers} are entries in the options +vector. @xref{Argp Option Vectors}. The first four fields are zero. The +two part documentation string are in the variable @code{doc}, which +allows documentation both before and after the options. @xref{Argp +Parsers}; the two parts of @code{doc} are separated by a vertical-tab +character (@code{'\v'}, or @code{'\013'}). By convention, the +documentation before the options is a short string stating what the +program does, and after any options it is longer, describing the +behavior in more detail. All documentation strings are automatically +filled for output, although newlines may be included to force a line +break at a particular point. In addition, documentation strings are +passed to the @code{gettext} function, for possible translation into the +current locale. @smallexample @include argp-ex4.c.texi @@ -1130,47 +1142,49 @@ function, for possible translation into the current locale. @subsection Argp User Customization @cindex ARGP_HELP_FMT environment variable -The way formatting of argp @samp{--help} output may be controlled to -some extent by a program's users, by setting the @code{ARGP_HELP_FMT} -environment variable to a comma-separated list (whitespace is ignored) -of the following tokens: +The formatting of argp @samp{--help} output may be controlled to some +extent by a program's users, by setting the @code{ARGP_HELP_FMT} +environment variable to a comma-separated list of tokens. Whitespace is +ignored: @table @samp @item dup-args @itemx no-dup-args -Turn @dfn{duplicate-argument-mode} on or off. In duplicate argument -mode, if an option which accepts an argument has multiple names, the -argument is shown for each name; otherwise, it is only shown for the -first long option, and a note is emitted later so the user knows that it -applies to the other names as well. The default is @samp{no-dup-args}, +These turn @dfn{duplicate-argument-mode} on or off. In duplicate +argument mode, if an option that accepts an argument has multiple names, +the argument is shown for each name. Otherwise, it is only shown for the +first long option. A note is subsequently printed so the user knows that +it applies to other names as well. The default is @samp{no-dup-args}, which is less consistent, but prettier. @item dup-args-note @item no-dup-args-note -Enable or disable the note informing the user of suppressed option -argument duplication. The default is @samp{dup-args-note}. +These will enable or disable the note informing the user of suppressed +option argument duplication. The default is @samp{dup-args-note}. @item short-opt-col=@var{n} -Show the first short option in column @var{n} (default 2). +This prints the first short option in column @var{n}. The default is 2. @item long-opt-col=@var{n} -Show the first long option in column @var{n} (default 6). +This prints the first long option in column @var{n}. The default is 6. @item doc-opt-col=@var{n} -Show `documentation options' (@pxref{Argp Option Flags}) in column -@var{n} (default 2). +This prints `documentation options' (@pxref{Argp Option Flags}) in +column @var{n}. The default is 2. @item opt-doc-col=@var{n} -Show the documentation for options starting in column @var{n} (default 29). +This prints the documentation for options starting in column +@var{n}. The default is 29. @item header-col=@var{n} -Indent group headers (which document groups of options) to column -@var{n} (default 1). +This will indent the group headers that document groups of options to +column @var{n}. The default is 1. @item usage-indent=@var{n} -Indent continuation lines in @samp{Usage:} messages to column @var{n} -(default 12). +This will indent continuation lines in @samp{Usage:} messages to column +@var{n}. The default is 12. @item rmargin=@var{n} -Word wrap help output at or before column @var{n} (default 79). +This will word wrap help output at or before column @var{n}. The default +is 79. @end table |