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
|
Example file
------------
Refer to the ./boilerplate.c example file while reading this howto.
Well-known options
------------------
The following options are well-known, and should not be used for any
other purpose:
-h, --help display usage and exit
-V, --version display version and exit
The rule of thumb with other options is that once they exist, you may
not change them, nor change how they work, nor remove them.
See Legacy options below.
How a usage text is supposed to look
------------------------------------
The usage() output format is: Usage section, command description one-liner,
Options section (see below), special sections like 'Available columns', and
the last line is either the man page reference or and empty line. The output
begins with, and each of the above are separated by, one empty line.
The Usage section contains the synopsis line that describes how to compose
the command. Sometimes you may need multiple synopsis lines (see below).
Only the synopsis and option lines are indented. Indent is one space (0x40).
Option lines do not use line-ending punctuation. Other sentences do.
Notations: diamond brackets are used to mark an argument to be filled in;
square brackets are used to mark anything that is optional, such as optional
command arguments, or optional option arguments. In the later case the '='
character is required in between the option and argument with no whitespace;
three consecutive dots means the unlimited repetition of the preceding.
The short option is always written first, followed by the long option. They
are separated with a comma and one space. Lonely short or long options do
not affect where the writing of the option begins.
Below, in between the snips, is an example of what the usage output should
look like.
-- snip
Usage:
program [options] <file> [...]
Short program description, ideally one line only.
Options:
-n, --no-argument option does not use argument
--optional[=<arg>] option argument is optional
-r, --required <arg> option requires an argument
-z no long option
--xyzzy a long option only
-e, --extremely-long-long-option
use next line for description when needed
-l, --long-explanation an example of very verbose, and chatty option
description on two, or multiple lines, where the
continuation lines are indented by two spaces
-f, --foobar next option description resets indent
-h, --help display this help and exit
-V, --version output version information and exit
For more details see program(1).
-- snip
Option descriptions
-------------------
This information also applies to other option-like arguments. That is,
arguments starting with '-'. Such as: functions, commands, and so forth.
An option description should not exceed the width of 80 characters. If
you need a longer description, use multiple lines and indentation.
The description text begins from the point of the longest option plus two
spaces. If adding a new option would necessitate a re-indentation of the
descriptions, it either has to be done, or the new option should begin its
description on the next line. Usually the later is better. The --help and
--version options do not follow this rule, since they are defined as
constants to ease translation work.
An argument is preferably worded appropriately. For example, if an option
expects a number as argument, '<num>' is a suitable argument indicator.
The order of the options has no special meaning, with the exception of
--help and --version which are expected to be last ones in the list.
Usage function
--------------
The standard usage() function takes either stderr or stdout as an argument.
The argument will determine whether the program will exit with an error or
with success. The usage() function will never return.
Section headers, man page, version, help, and other components of usage()
have string constants defined in 'include/c.h' which must be used. See the
example file listed at the top of this document.
In the code all the strings with options have to start at the same position.
See here what this means:
fprintf(out, _(" -x[=<foo>] default foo is %s"), x);
fputs( _(" -y some text"), out);
Be nice to translators. One gettext entry should be one option, no more,
no less. For example:
fputs(_(" --you-there be nice\n"), out);
fputs(_(" -2 <whom> translators\n"), out);
fputs(_(" -t, --hey are doing a job that we probably cannot,"
" or how is your klingon?\n"), out);
When existing usage output is changed, and it happens to be one big text,
split it into chunks the size of one option. The extra work this will entail
for translators will pay off later; the next string change will not force a
search of the long fuzzy text for what was changed, where, how, and whether
it was the only change.
Synopsis
--------
You may need to use multiple synopsis lines to show that a command does
fundamentally different things depending on the options and/or arguments.
For example, ionice either changes the priority of a running command, or
executes a program with a defined priority. Therefore it is reasonable
to have two synopsis lines:
ionice [options] -p <pid> ...
ionice [options] <command> [<arg> ...]
Note that the synopsis is not meant to be a repetition of the options
section. The fundamental difference in execution is a bit difficult to
define. The command author, package maintainer or patch submitter will
usually know when it should be done that way.
Legacy options
--------------
Some commands use peculiar options and arguments. These will continue
to be supported, but anything like them will not be accepted as new
additions. A short list of examples:
- Characters other than '-' to start an option. See '+' in 'more'.
- Using a number as an option. See '-<number>' in 'more'.
- Long options that start with a single '-'. See 'setterm'.
- '-?' is not expected to be a synonym of '--help', but is an unknown
option resulting in a suggestion to try --help due to a getopt failure.
|
