2017-06-23 18:57:46 -05:00
|
|
|
|
|
|
|
Example file
|
|
|
|
------------
|
|
|
|
|
|
|
|
Refer to the ./boilerplate.c example file while reading this howto.
|
|
|
|
|
2011-08-12 13:35:27 -05:00
|
|
|
|
2014-04-29 10:33:04 -05:00
|
|
|
How a usage text is supposed to look
|
|
|
|
------------------------------------
|
2011-08-12 13:35:27 -05:00
|
|
|
|
2017-06-23 18:57:46 -05:00
|
|
|
The usage() output format is: Usage section, command description one-liner,
|
|
|
|
Options section (see below), special sections like 'Available columns', and
|
2017-07-23 09:03:18 -05:00
|
|
|
the last line is either the man page reference or an empty line. The output
|
2017-06-23 18:57:46 -05:00
|
|
|
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).
|
2011-08-12 13:35:27 -05:00
|
|
|
|
2017-06-23 18:57:46 -05:00
|
|
|
Only the synopsis and option lines are indented. Indent is one space (0x40).
|
|
|
|
Option lines do not use line-ending punctuation. Other sentences do.
|
2011-08-12 13:35:27 -05:00
|
|
|
|
2017-06-23 18:57:46 -05:00
|
|
|
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.
|
2011-08-12 13:35:27 -05:00
|
|
|
|
2014-04-29 10:33:04 -05:00
|
|
|
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
|
2017-07-23 09:03:18 -05:00
|
|
|
not affect their alignment. That is, they must be in their respective column.
|
2011-08-12 13:35:27 -05:00
|
|
|
|
2014-04-29 10:33:04 -05:00
|
|
|
Below, in between the snips, is an example of what the usage output should
|
2011-08-12 13:35:27 -05:00
|
|
|
look like.
|
|
|
|
|
|
|
|
-- snip
|
|
|
|
|
|
|
|
Usage:
|
|
|
|
program [options] <file> [...]
|
|
|
|
|
2017-06-21 04:25:55 -05:00
|
|
|
Short program description, ideally one line only.
|
|
|
|
|
2011-08-12 13:35:27 -05:00
|
|
|
Options:
|
|
|
|
-n, --no-argument option does not use argument
|
2016-04-16 09:30:39 -05:00
|
|
|
--optional[=<arg>] option argument is optional
|
2011-08-12 13:35:27 -05:00
|
|
|
-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
|
2014-04-29 10:33:04 -05:00
|
|
|
continuation lines are indented by two spaces
|
2011-08-12 13:35:27 -05:00
|
|
|
-f, --foobar next option description resets indent
|
2011-09-17 05:52:32 -05:00
|
|
|
|
2011-08-12 13:35:27 -05:00
|
|
|
-h, --help display this help and exit
|
|
|
|
-V, --version output version information and exit
|
|
|
|
|
|
|
|
For more details see program(1).
|
|
|
|
-- snip
|
|
|
|
|
|
|
|
|
2014-04-29 10:33:04 -05:00
|
|
|
Option descriptions
|
|
|
|
-------------------
|
2011-08-12 13:35:27 -05:00
|
|
|
|
2017-06-23 18:57:46 -05:00
|
|
|
This information also applies to other option-like arguments. That is,
|
|
|
|
arguments starting with '-'. Such as: functions, commands, and so forth.
|
|
|
|
|
2014-04-29 10:33:04 -05:00
|
|
|
An option description should not exceed the width of 80 characters. If
|
|
|
|
you need a longer description, use multiple lines and indentation.
|
2011-08-12 13:35:27 -05:00
|
|
|
|
2014-04-29 10:33:04 -05:00
|
|
|
The description text begins from the point of the longest option plus two
|
2017-06-23 18:57:46 -05:00
|
|
|
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
|
2017-07-23 09:03:18 -05:00
|
|
|
description on the next line. Usually the later is better.
|
2011-08-12 13:35:27 -05:00
|
|
|
|
2014-04-29 10:33:04 -05:00
|
|
|
An argument is preferably worded appropriately. For example, if an option
|
|
|
|
expects a number as argument, '<num>' is a suitable argument indicator.
|
2011-08-12 13:35:27 -05:00
|
|
|
|
2014-04-29 10:33:04 -05:00
|
|
|
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.
|
2011-08-12 13:35:27 -05:00
|
|
|
|
|
|
|
|
|
|
|
Usage function
|
|
|
|
--------------
|
|
|
|
|
2017-07-23 09:03:18 -05:00
|
|
|
The usage() function will never return. It must only be called by -h/--help.
|
|
|
|
All other cases use errtryhelp(EXIT_FAILURE).
|
2011-08-12 13:35:27 -05:00
|
|
|
|
2017-06-23 18:57:46 -05:00
|
|
|
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
|
2017-07-23 09:03:18 -05:00
|
|
|
example file listed at the top of this document. The help and version options
|
|
|
|
are combined into a single macro which takes an argument for the column that
|
|
|
|
their descriptions will begin on: USAGE_HELP_OPTIONS(<num>). This allows
|
|
|
|
them to align properly with the other options.
|
2017-06-23 18:57:46 -05:00
|
|
|
|
2017-07-23 09:03:18 -05:00
|
|
|
In the code, all option strings must start at the same position.
|
2014-04-29 10:33:04 -05:00
|
|
|
See here what this means:
|
2011-08-12 13:35:27 -05:00
|
|
|
|
2017-07-23 09:03:18 -05:00
|
|
|
printf(out, _(" -x[=<foo>] default foo is %s"), x);
|
|
|
|
puts( _(" -y some text"), out);
|
2011-08-12 13:35:27 -05:00
|
|
|
|
2014-04-29 10:33:04 -05:00
|
|
|
Be nice to translators. One gettext entry should be one option, no more,
|
|
|
|
no less. For example:
|
docs: usage function and gettext
I made following survey which was sent to all email addresses in po/
directory that had the on-going millenium as time when translator had
been active.
There are two quite common styles to write a command usage print out,
which one you prefer?
1. Each option as separated translatable string. 18 votes
2. Or the whole thing as one big output. 1 vote
3. No preference. 1 vote
The questionaire had also free text field asking 'Why do you prefer
that?', and here are the answers.
[Separately] It is easier to follow changes with the translations. If
you change only one line or two, the big string would change to fuzzy
and I have to check the whole thing to see what was changed in the
original. If the changed line is a single string, the string to check
is a lot shorter.
[No preference] Usually, if there is no reason to separate strings,
better keep them together so that the context is obvious. In the case at
hand, it might help if in some language e.g. one translated line is too
wide for the screen. This is unlikely, but... OTOH, with this solution,
if you change one string the whole translation will be discarded until a
translator comes and updates it...
[Separately] It may be a bit harder to get the formatting right, but it
is much easier in maintenance. With one option changing, the
translator immediately sees the spot. And even with a lazy translator,
program author will have all the options translated that have not
changed at all.
[Separately] First one would be more in elegant I believe
[Separately] I prefer to have them separately because they don't form a
single text paragraph. In other words, they can be translated
separately because they are complete and separate "sentences". Of
course consistency of format and word choices need to be taken care of,
but the fact that the messages appear next to each other in the PO file
should be enough. Also if the options are not translated separately,
adding or editing one option causes the translation of all options to
become fuzzy and if for some reason it isn't checked before next
release (happens sometimes), all of them will show untranslated to the
user.
[Separately] Translations are a lot easier to update that way. If an
option is added, removed or changed, only a small amount of text
becomes fuzzy. If everything is in one big output, a lot of text
becomes fuzzy, and you have to read a lot more text to discover what
exactly changed.
[Separately] When updating a fuzzy translation, with one big output
it's very tedious and error-prone to find out the reason for fuzziness,
i.e. what actually has changed in the msgid.
[Separately] Way easier to translate, and especially to spot
translation updates when one string gets removed, added or modified.
[Separately] Makes translation memory more efficient. Some hard terms
in the list don't prevent translation of the whole block. Actually the
beginning of the strings don't need any translation ta all before []
part. Information about the context can be provided in comments or the
context parameter.
[Separately] Please consider the case when a part of string, (= msgid)
is changed. It is marked as fuzzy in the .po files, we translators
have to check whole sentences for the difference between it and
previous version.
[Separately] Every sentence must be a separate translation unit.
[One big output] for performance to ouput strings
[Separately] In the second case, if only one option changes (or a new
one is added), the translator will see as if all of the options
changed, having to find out which one of them is really new or has
actually changed. Also, if the translator has had no time to update
the string, only one of the options will be shown in the original
language (which is arguably ugly, but better than nothing for many
users).
[Separately] It's easier to translate the options separately using
translation memory.
[Separately] Easier to separate and see changes
[Separately] more translator friendly
[Separately] From the user POV I found the separeted version more
interesting because if a maintainer can't update the translation fast
enough between releases the user will still get the current translated
string with the new ones untraslated. From the translator POV the big
output will give more context information as one can see the whole
command options. With a new string added while the rest is translated
having some context can be more difficult.
[Separately] Additions to the list or changes to one options means you
don't have to check all lines each time.
So unless you have very, _very_ good reason you should not output all
usage as one big table. This implies also that when large usage output
is changed it should be split to small hunks. That may be a bit more
work once, but the next change will pay the extrawork off so never
hesitate when splitting.
Reference: http://www.surveymonkey.com/s/QKZ75HK
Signed-off-by: Sami Kerola <kerolasa@iki.fi>
2013-01-22 17:27:00 -06:00
|
|
|
|
2017-07-23 09:03:18 -05:00
|
|
|
puts(_(" --you-there be nice\n"), out);
|
|
|
|
puts(_(" -2 <whom> translators\n"), out);
|
|
|
|
puts(_(" -t, --hey are doing a job that we probably cannot,"
|
docs: usage function and gettext
I made following survey which was sent to all email addresses in po/
directory that had the on-going millenium as time when translator had
been active.
There are two quite common styles to write a command usage print out,
which one you prefer?
1. Each option as separated translatable string. 18 votes
2. Or the whole thing as one big output. 1 vote
3. No preference. 1 vote
The questionaire had also free text field asking 'Why do you prefer
that?', and here are the answers.
[Separately] It is easier to follow changes with the translations. If
you change only one line or two, the big string would change to fuzzy
and I have to check the whole thing to see what was changed in the
original. If the changed line is a single string, the string to check
is a lot shorter.
[No preference] Usually, if there is no reason to separate strings,
better keep them together so that the context is obvious. In the case at
hand, it might help if in some language e.g. one translated line is too
wide for the screen. This is unlikely, but... OTOH, with this solution,
if you change one string the whole translation will be discarded until a
translator comes and updates it...
[Separately] It may be a bit harder to get the formatting right, but it
is much easier in maintenance. With one option changing, the
translator immediately sees the spot. And even with a lazy translator,
program author will have all the options translated that have not
changed at all.
[Separately] First one would be more in elegant I believe
[Separately] I prefer to have them separately because they don't form a
single text paragraph. In other words, they can be translated
separately because they are complete and separate "sentences". Of
course consistency of format and word choices need to be taken care of,
but the fact that the messages appear next to each other in the PO file
should be enough. Also if the options are not translated separately,
adding or editing one option causes the translation of all options to
become fuzzy and if for some reason it isn't checked before next
release (happens sometimes), all of them will show untranslated to the
user.
[Separately] Translations are a lot easier to update that way. If an
option is added, removed or changed, only a small amount of text
becomes fuzzy. If everything is in one big output, a lot of text
becomes fuzzy, and you have to read a lot more text to discover what
exactly changed.
[Separately] When updating a fuzzy translation, with one big output
it's very tedious and error-prone to find out the reason for fuzziness,
i.e. what actually has changed in the msgid.
[Separately] Way easier to translate, and especially to spot
translation updates when one string gets removed, added or modified.
[Separately] Makes translation memory more efficient. Some hard terms
in the list don't prevent translation of the whole block. Actually the
beginning of the strings don't need any translation ta all before []
part. Information about the context can be provided in comments or the
context parameter.
[Separately] Please consider the case when a part of string, (= msgid)
is changed. It is marked as fuzzy in the .po files, we translators
have to check whole sentences for the difference between it and
previous version.
[Separately] Every sentence must be a separate translation unit.
[One big output] for performance to ouput strings
[Separately] In the second case, if only one option changes (or a new
one is added), the translator will see as if all of the options
changed, having to find out which one of them is really new or has
actually changed. Also, if the translator has had no time to update
the string, only one of the options will be shown in the original
language (which is arguably ugly, but better than nothing for many
users).
[Separately] It's easier to translate the options separately using
translation memory.
[Separately] Easier to separate and see changes
[Separately] more translator friendly
[Separately] From the user POV I found the separeted version more
interesting because if a maintainer can't update the translation fast
enough between releases the user will still get the current translated
string with the new ones untraslated. From the translator POV the big
output will give more context information as one can see the whole
command options. With a new string added while the rest is translated
having some context can be more difficult.
[Separately] Additions to the list or changes to one options means you
don't have to check all lines each time.
So unless you have very, _very_ good reason you should not output all
usage as one big table. This implies also that when large usage output
is changed it should be split to small hunks. That may be a bit more
work once, but the next change will pay the extrawork off so never
hesitate when splitting.
Reference: http://www.surveymonkey.com/s/QKZ75HK
Signed-off-by: Sami Kerola <kerolasa@iki.fi>
2013-01-22 17:27:00 -06:00
|
|
|
" or how is your klingon?\n"), out);
|
|
|
|
|
2014-04-29 10:33:04 -05:00
|
|
|
When existing usage output is changed, and it happens to be one big text,
|
2017-06-23 18:57:46 -05:00
|
|
|
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.
|
2011-08-12 13:35:27 -05:00
|
|
|
|
2017-06-18 12:31:36 -05:00
|
|
|
|
2011-08-12 13:35:27 -05:00
|
|
|
Synopsis
|
|
|
|
--------
|
|
|
|
|
2014-04-29 10:33:04 -05:00
|
|
|
You may need to use multiple synopsis lines to show that a command does
|
2017-06-23 18:57:46 -05:00
|
|
|
fundamentally different things depending on the options and/or arguments.
|
2014-04-29 10:33:04 -05:00
|
|
|
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:
|
2011-08-12 13:35:27 -05:00
|
|
|
|
2014-04-29 10:33:04 -05:00
|
|
|
ionice [options] -p <pid> ...
|
|
|
|
ionice [options] <command> [<arg> ...]
|
2011-08-12 13:35:27 -05:00
|
|
|
|
2014-04-29 10:33:04 -05:00
|
|
|
Note that the synopsis is not meant to be a repetition of the options
|
2017-06-23 18:57:46 -05:00
|
|
|
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.
|
2011-08-12 13:35:27 -05:00
|
|
|
|
|
|
|
|