Add new file
Showing
1 changed file
with
197 additions
and
0 deletions
doc/texinfo/usage.texi
0 → 100644
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 |
-
Please register or sign in to post a comment