]>
Commit | Line | Data |
---|---|---|
72727e28 WP |
1 | |
2 | Example file | |
3 | ------------ | |
4 | ||
5 | Refer to the ./boilerplate.c example file while reading this howto. | |
6 | ||
e1271f8d | 7 | |
83eda778 BS |
8 | How a usage text is supposed to look |
9 | ------------------------------------ | |
e1271f8d | 10 | |
72727e28 WP |
11 | The usage() output format is: Usage section, command description one-liner, |
12 | Options section (see below), special sections like 'Available columns', and | |
8e953778 | 13 | the last line is either the man page reference or an empty line. The output |
72727e28 WP |
14 | begins with, and each of the above are separated by, one empty line. |
15 | ||
16 | The Usage section contains the synopsis line that describes how to compose | |
17 | the command. Sometimes you may need multiple synopsis lines (see below). | |
e1271f8d | 18 | |
72727e28 WP |
19 | Only the synopsis and option lines are indented. Indent is one space (0x40). |
20 | Option lines do not use line-ending punctuation. Other sentences do. | |
e1271f8d | 21 | |
72727e28 WP |
22 | Notations: diamond brackets are used to mark an argument to be filled in; |
23 | square brackets are used to mark anything that is optional, such as optional | |
24 | command arguments, or optional option arguments. In the later case the '=' | |
25 | character is required in between the option and argument with no whitespace; | |
26 | three consecutive dots means the unlimited repetition of the preceding. | |
e1271f8d | 27 | |
83eda778 BS |
28 | The short option is always written first, followed by the long option. They |
29 | are separated with a comma and one space. Lonely short or long options do | |
8e953778 | 30 | not affect their alignment. That is, they must be in their respective column. |
e1271f8d | 31 | |
83eda778 | 32 | Below, in between the snips, is an example of what the usage output should |
e1271f8d SK |
33 | look like. |
34 | ||
35 | -- snip | |
36 | ||
37 | Usage: | |
38 | program [options] <file> [...] | |
39 | ||
9e258f38 KZ |
40 | Short program description, ideally one line only. |
41 | ||
e1271f8d | 42 | Options: |
e1271f8d | 43 | -n, --no-argument option does not use argument |
326c5c93 | 44 | --optional[=<arg>] option argument is optional |
e1271f8d SK |
45 | -r, --required <arg> option requires an argument |
46 | -z no long option | |
47 | --xyzzy a long option only | |
48 | -e, --extremely-long-long-option | |
49 | use next line for description when needed | |
50 | -l, --long-explanation an example of very verbose, and chatty option | |
51 | description on two, or multiple lines, where the | |
83eda778 | 52 | continuation lines are indented by two spaces |
e1271f8d | 53 | -f, --foobar next option description resets indent |
6f162034 | 54 | |
e1271f8d SK |
55 | -h, --help display this help and exit |
56 | -V, --version output version information and exit | |
57 | ||
58 | For more details see program(1). | |
59 | -- snip | |
60 | ||
e1271f8d | 61 | |
83eda778 BS |
62 | Option descriptions |
63 | ------------------- | |
e1271f8d | 64 | |
72727e28 WP |
65 | This information also applies to other option-like arguments. That is, |
66 | arguments starting with '-'. Such as: functions, commands, and so forth. | |
67 | ||
83eda778 BS |
68 | An option description should not exceed the width of 80 characters. If |
69 | you need a longer description, use multiple lines and indentation. | |
e1271f8d | 70 | |
83eda778 | 71 | The description text begins from the point of the longest option plus two |
72727e28 WP |
72 | spaces. If adding a new option would necessitate a re-indentation of the |
73 | descriptions, it either has to be done, or the new option should begin its | |
8e953778 | 74 | description on the next line. Usually the later is better. |
e1271f8d | 75 | |
83eda778 BS |
76 | An argument is preferably worded appropriately. For example, if an option |
77 | expects a number as argument, '<num>' is a suitable argument indicator. | |
e1271f8d | 78 | |
83eda778 BS |
79 | The order of the options has no special meaning, with the exception of |
80 | --help and --version which are expected to be last ones in the list. | |
e1271f8d | 81 | |
e1271f8d SK |
82 | |
83 | Usage function | |
84 | -------------- | |
85 | ||
8e953778 WP |
86 | The usage() function will never return. It must only be called by -h/--help. |
87 | All other cases use errtryhelp(EXIT_FAILURE). | |
e1271f8d | 88 | |
72727e28 WP |
89 | Section headers, man page, version, help, and other components of usage() |
90 | have string constants defined in 'include/c.h' which must be used. See the | |
8e953778 WP |
91 | example file listed at the top of this document. The help and version options |
92 | are combined into a single macro which takes an argument for the column that | |
93 | their descriptions will begin on: USAGE_HELP_OPTIONS(<num>). This allows | |
94 | them to align properly with the other options. | |
72727e28 | 95 | |
8e953778 | 96 | In the code, all option strings must start at the same position. |
83eda778 | 97 | See here what this means: |
e1271f8d | 98 | |
8e953778 WP |
99 | printf(out, _(" -x[=<foo>] default foo is %s"), x); |
100 | puts( _(" -y some text"), out); | |
e1271f8d | 101 | |
83eda778 BS |
102 | Be nice to translators. One gettext entry should be one option, no more, |
103 | no less. For example: | |
24f109e3 | 104 | |
8e953778 WP |
105 | puts(_(" --you-there be nice\n"), out); |
106 | puts(_(" -2 <whom> translators\n"), out); | |
107 | puts(_(" -t, --hey are doing a job that we probably cannot," | |
24f109e3 SK |
108 | " or how is your klingon?\n"), out); |
109 | ||
83eda778 | 110 | When existing usage output is changed, and it happens to be one big text, |
72727e28 WP |
111 | split it into chunks the size of one option. The extra work this will entail |
112 | for translators will pay off later; the next string change will not force a | |
113 | search of the long fuzzy text for what was changed, where, how, and whether | |
114 | it was the only change. | |
e1271f8d | 115 | |
2671bcd6 | 116 | |
e1271f8d SK |
117 | Synopsis |
118 | -------- | |
119 | ||
83eda778 | 120 | You may need to use multiple synopsis lines to show that a command does |
72727e28 | 121 | fundamentally different things depending on the options and/or arguments. |
83eda778 BS |
122 | For example, ionice either changes the priority of a running command, or |
123 | executes a program with a defined priority. Therefore it is reasonable | |
124 | to have two synopsis lines: | |
e1271f8d | 125 | |
83eda778 BS |
126 | ionice [options] -p <pid> ... |
127 | ionice [options] <command> [<arg> ...] | |
e1271f8d | 128 | |
83eda778 | 129 | Note that the synopsis is not meant to be a repetition of the options |
72727e28 WP |
130 | section. The fundamental difference in execution is a bit difficult to |
131 | define. The command author, package maintainer or patch submitter will | |
132 | usually know when it should be done that way. | |
e1271f8d SK |
133 | |
134 |