Commit d482c65e d482c65ebc371b07d64450d169b513d389185d0d by Sergey Poznyakoff

Add new file

1 parent 75072662
1 @c This is part of the GNU Mailutils manual.
2 @c Copyright (C) 1999,2000,2001,2002,2003,2004,2005,2006,2007,2008
3 @c Free Software Foundation, Inc.
4 @c See file mailutils.texi for copying conditions.
5 @comment *******************************************************************
6 @node Usage Vars
7 @appendix Configuring Help Summary
8
9 Running @command{@var{prog} --help} displays the short usage summary
10 for @var{prog} utility (@pxref{Common Options}). This summary is
11 organized by @dfn{groups} of semantically close options. The options
12 within each group are printed in the following order: a short option,
13 eventually followed by a list of corresponding long option names,
14 followed by a short description of the option. For example, here is an
15 excerpt from the actual @kbd{sieve --help} output:
16
17 @verbatim
18 -c, --compile-only Compile script and exit
19 -d, --debug[=FLAGS] Debug flags
20 -e, --email=ADDRESS Override user email address
21 @end verbatim
22
23 @vrindex ARGP_HELP_FMT, environment variable
24 The exact visual representation of the help output is configurable via
25 @env{ARGP_HELP_FMT} environment variable. The value of this variable
26 is a comma-separated list of @dfn{format variable} assignments. There
27 are two kinds of format variables. An @dfn{offset variable} keeps the
28 offset of some part of help output text from the leftmost column on
29 the screen. A @dfn{boolean} variable is a flag that toggles some
30 output feature on or off. Depending on the type of the corresponding
31 variable, there are two kinds of assignments:
32
33 @table @asis
34 @item Offset assignment
35
36 The assignment to an offset variable has the following syntax:
37
38 @smallexample
39 @var{variable}=@var{value}
40 @end smallexample
41
42 @noindent
43 where @var{variable} is the variable name, and @var{value} is a
44 numeric value to be assigned to the variable.
45
46 @item Boolean assignment
47
48 To assign @code{true} value to a variable, simply put this variable name. To
49 assign @code{false} value, prefix the variable name with @samp{no-}. For
50 example:
51
52 @smallexample
53 @group
54 # Assign @code{true} value:
55 dup-args
56 # Assign @code{false} value:
57 no-dup-args
58 @end group
59 @end smallexample
60 @end table
61
62 Following variables are declared:
63
64 @deftypevr {Help Output} boolean dup-args
65 If true, arguments for an option are shown with both short and long
66 options, even when a given option has both forms, for example:
67
68 @smallexample
69 -e ADDRESS, --email=ADDRESS Override user email address
70 @end smallexample
71
72 If false, then if an option has both short and long forms, the
73 argument is only shown with the long one, for example:
74
75 @smallexample
76 -e, --email=ADDRESS Override user email address
77 @end smallexample
78
79 @noindent
80 and a message indicating that the argument is applicable to both
81 forms is printed below the options. This message can be disabled
82 using @code{dup-args-note} (see below).
83
84 The default is false.
85 @end deftypevr
86
87 @deftypevr {Help Output} boolean dup-args-note
88 If this variable is true, which is the default, the following notice
89 is displayed at the end of the help output:
90
91 @quotation
92 Mandatory or optional arguments to long options are also mandatory or
93 optional for any corresponding short options.
94 @end quotation
95
96 Setting @code{no-dup-args-note} inhibits this message. Normally, only
97 one of variables @code{dup-args} or @code{dup-args-note} should be set.
98 @end deftypevr
99
100 @deftypevr {Help Output} offset short-opt-col
101 Column in which short options start. Default is 2.
102
103 @smallexample
104 @group
105 $ @kbd{sieve --help|grep ADDRESS}
106 -e, --email=ADDRESS Override user email address
107 $ @kbd{ARGP_HELP_FMT=short-opt-col=6 sieve --help|grep ARCHIVE}
108 -e, --email=ADDRESS Override user email address
109 @end group
110 @end smallexample
111 @end deftypevr
112
113 @deftypevr {Help Output} offset long-opt-col
114 Column in which long options start. Default is 6. For example:
115
116 @smallexample
117 @group
118 $ @kbd{sieve --help|grep ADDRESS}
119 -e, --email=ADDRESS Override user email address
120 $ @kbd{ARGP_HELP_FMT=long-opt-col=16 sieve --help|grep ADDRESS}
121 -e, --email=ADDRESS Override user email address
122 @end group
123 @end smallexample
124 @end deftypevr
125
126 @deftypevr {Help Output} offset doc-opt-col
127 Column in which @dfn{doc options} start. A doc option isn't actually
128 an option, but rather an arbitrary piece of documentation that is
129 displayed in much the same manner as the options. For example, in
130 the output of @command{folder --help}:
131
132 @verbatim
133 Usage: folder [OPTION...] [action] [msg]
134 GNU MH folder
135 Actions are:
136 --list List the contents of the folder stack
137 ...
138 @end verbatim
139
140 @noindent
141 the string @samp{Actions are:} is a doc option. Thus, if you set
142 @kbd{ARGP_HELP_FMT=doc-opt-col=6} the above part of the help output
143 will look as follows:
144
145 @verbatim
146 Usage: folder [OPTION...] [action] [msg]
147 GNU MH folder
148 Actions are:
149 --list List the contents of the folder stack
150 ...
151 @end verbatim
152 @end deftypevr
153
154 @deftypevr {Help Output} offset opt-doc-col
155 Column in which option description starts. Default is 29.
156
157 @smallexample
158 @group
159 $ @kbd{sieve --help|grep ADDRESS}
160 -e, --email=ADDRESS Override user email address
161 $ @kbd{ARGP_HELP_FMT=opt-doc-col=19 sieve --help|grep ADDRESS}
162 -e, --email=ADDRESS Override user email address
163 $ @kbd{ARGP_HELP_FMT=opt-doc-col=9 sieve --help|grep -i ADDRESS}
164 -e, --email=ADDRESS
165 Override user email address
166 @end group
167 @end smallexample
168
169 @noindent
170 Notice, that the description starts on a separate line if
171 @code{opt-doc-col} value is too small.
172 @end deftypevr
173
174 @deftypevr {Help Output} offset header-col
175 Column in which @dfn{group headers} are printed. A group header is a
176 descriptive text preceding an option group. For example, in the
177 following text:
178
179 @verbatim
180 Sieve options
181 -I, --includedir=DIR Append directory DIR to the
182 list of include directories
183 @end verbatim
184 @noindent
185 the text @samp{Sieve options} is a group header.
186
187 The default value is 1.
188 @end deftypevr
189
190 @deftypevr {Help Output} offset usage-indent
191 Indentation of wrapped usage lines. Affects @option{--usage}
192 output. Default is 12.
193 @end deftypevr
194
195 @deftypevr {Help Output} offset rmargin
196 Right margin of the text output. Used for wrapping.
197 @end deftypevr