summaryrefslogtreecommitdiff
path: root/doc/texinfo/usage.texi
blob: f351f0d3b421c49c85bc2a5a231fd18375abd207 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
@c This is part of the GNU Mailutils manual.
@c Copyright (C) 1999-2008, 2010-2012, 2014-2017 Free Software
@c Foundation, Inc.
@c See file mailutils.texi for copying conditions.
@comment *******************************************************************

Running @command{@var{prog} --help} displays the short usage summary
for @var{prog} utility (@pxref{Common Options}).  This summary is
organized by @dfn{groups} of semantically close options.  The options
within each group are printed in the following order: a short option,
eventually followed by a list of corresponding long option names,
followed by a short description of the option.  For example, here is an
excerpt from the actual @kbd{sieve --help} output:

@verbatim
  -c, --compile-only         Compile script and exit
  -d, --debug[=FLAGS]        Debug flags
  -e, --email=ADDRESS        Override user email address
@end verbatim

@vrindex ARGP_HELP_FMT, environment variable
The exact visual representation of the help output is configurable via
@env{ARGP_HELP_FMT} environment variable.  The value of this variable
is a comma-separated list of @dfn{format variable} assignments.  There
are two kinds of format variables.  An @dfn{offset variable} keeps the
offset of some part of help output text from the leftmost column on
the screen.  A @dfn{boolean} variable is a flag that toggles some
output feature on or off.  Depending on the type of the corresponding
variable, there are two kinds of assignments:

@table @asis
@item Offset assignment

The assignment to an offset variable has the following syntax:

@smallexample
@var{variable}=@var{value}
@end smallexample

@noindent
where @var{variable} is the variable name, and @var{value} is a
numeric value to be assigned to the variable.

@item Boolean assignment

To assign @code{true} value to a variable, simply put this variable name.  To
assign @code{false} value, prefix the variable name with @samp{no-}.  For
example:

@smallexample
@group
# Assign @code{true} value:
dup-args
# Assign @code{false} value:
no-dup-args
@end group
@end smallexample
@end table

Following variables are declared:

@deftypevr {Help Output} boolean dup-args
If true, arguments for an option are shown with both short and long
options, even when a given option has both forms, for example:

@smallexample
  -e ADDRESS, --email=ADDRESS        Override user email address
@end smallexample

If false, then if an option has both short and long forms, the
argument is only shown with the long one, for example:

@smallexample
  -e, --email=ADDRESS        Override user email address
@end smallexample

@noindent
and a message indicating that the argument is applicable to both
forms is printed below the options.  This message can be disabled
using @code{dup-args-note} (see below).

The default is false.
@end deftypevr

@deftypevr {Help Output} boolean dup-args-note
If this variable is true, which is the default, the following notice
is displayed at the end of the help output:

@quotation
Mandatory or optional arguments to long options are also mandatory or
optional for any corresponding short options.
@end quotation

Setting @code{no-dup-args-note} inhibits this message.  Normally, only
one of variables @code{dup-args} or @code{dup-args-note} should be set.
@end deftypevr

@deftypevr {Help Output} offset short-opt-col
Column in which short options start.  Default is 2.

@smallexample
@group
$ @kbd{sieve --help|grep ADDRESS}
  -e, --email=ADDRESS        Override user email address
$ @kbd{ARGP_HELP_FMT=short-opt-col=6 sieve --help|grep ARCHIVE}
      -e, --email=ADDRESS        Override user email address
@end group
@end smallexample
@end deftypevr

@deftypevr {Help Output} offset long-opt-col
Column in which long options start.  Default is 6.  For example:

@smallexample
@group
$ @kbd{sieve --help|grep ADDRESS}
  -e, --email=ADDRESS        Override user email address
$ @kbd{ARGP_HELP_FMT=long-opt-col=16 sieve --help|grep ADDRESS}
  -e,           --email=ADDRESS        Override user email address
@end group
@end smallexample
@end deftypevr

@deftypevr {Help Output} offset doc-opt-col
Column in which @dfn{doc options} start.  A doc option isn't actually
an option, but rather an arbitrary piece of documentation that is
displayed in much the same manner as the options.  For example, in
the output of @command{folder --help}:

@verbatim
Usage: folder [OPTION...] [action] [msg]
GNU MH folder
  Actions are:
      --list                 List the contents of the folder stack
  ...
@end verbatim

@noindent
the string @samp{Actions are:} is a doc option.  Thus, if you set
@kbd{ARGP_HELP_FMT=doc-opt-col=6} the above part of the help output
will look as follows:

@verbatim
Usage: folder [OPTION...] [action] [msg]
GNU MH folder
      Actions are:
      --list                 List the contents of the folder stack
  ...
@end verbatim
@end deftypevr

@deftypevr {Help Output} offset opt-doc-col
Column in which option description starts.  Default is 29.

@smallexample
@group
$ @kbd{sieve --help|grep ADDRESS}
  -e, --email=ADDRESS        Override user email address
$ @kbd{ARGP_HELP_FMT=opt-doc-col=19 sieve --help|grep ADDRESS}
  -e, --email=ADDRESS   Override user email address
$ @kbd{ARGP_HELP_FMT=opt-doc-col=9 sieve --help|grep -i ADDRESS}
  -e, --email=ADDRESS
         Override user email address
@end group
@end smallexample

@noindent
Notice, that the description starts on a separate line if
@code{opt-doc-col} value is too small.
@end deftypevr

@deftypevr {Help Output} offset header-col
Column in which @dfn{group headers} are printed.  A group header is a
descriptive text preceding an option group.  For example, in the
following text:

@verbatim
 Sieve options
  -I, --includedir=DIR       Append directory DIR to the
                             list of include directories
@end verbatim
@noindent
the text @samp{Sieve options} is a group header.

The default value is 1.
@end deftypevr

@deftypevr {Help Output} offset usage-indent
Indentation of wrapped usage lines.  Affects @option{--usage}
output.  Default is 12.
@end deftypevr

@deftypevr {Help Output} offset rmargin
Right margin of the text output.  Used for wrapping.
@end deftypevr

Return to:

Send suggestions and report system problems to the System administrator.