diff options
Diffstat (limited to 'Documentation/howto-man-page.txt')
| -rw-r--r-- | Documentation/howto-man-page.txt | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/Documentation/howto-man-page.txt b/Documentation/howto-man-page.txt new file mode 100644 index 0000000..55734af --- /dev/null +++ b/Documentation/howto-man-page.txt @@ -0,0 +1,188 @@ +.\" This is a util-linux manual page example in troff format. +.\" +.\" The .TH macro expects the following arguments: +.\" title section date footer header +.\" The title is usually the command name. +.\" The section must match the filename extension. +.\" The date is the month and year when the last update happened. +.\" The footer is fixed to "util-linux". +.\" The header is a textual description of the section: +.\" 1 "User Commands" +.\" 2 "System calls" +.\" 3 "Programmer's Manual" +.\" 4 "Special Files" +.\" 5 "File Formats" +.\" 6 "Games" +.\" 7 "Miscellanea" +.\" 8 "System Administration" +.\" +.\" Please read `man 7 groff_man' to see how to use the various macros. +.\" +.TH EXAMPLE "1" "April 2016" "util-linux" "User Commands" +.SH NAME +example \- a util-linux man-page howto +.SH SYNOPSIS +.B example +[options] +.I argument +.SH DESCRIPTION +Each manual page needs some sort of description of the command. +Write such here. +.SH OPTIONS +.TP +\fB\-n\fR, \fB\-\-no\-argument\fR +This option does not use an argument. +.TP +\fB\-\-optional\fR[\fI=argument\fR] +Tell in this description that the +.I argument +is optional, and what happens when it is or is not given. Notice that the word +.I argument +is not abbreviated as is customary in the usage text. For example, when the +usage text uses the argument +.IR num , +the manual page should say +.IR number . +.IP +Notice that after release v2.28 it was decided that introducing new options +taking optional arguments should be limited to long-only options. This is +done primarily to avoid problematic behaviour of short options. Imagine for +example normal option +.B \-n +and optional option +.BR \-o . +One will expect +.B command \ \-no +and +.B command \ \-on +to be the same, but in fact the former is two separate options while the +later will use +.B n +as option argument of +.BR -o . +So it is best to avoid short forms of optional options altogether. +.TP +\fB\-r\fR, \fB\-\-required\fR \fIargument\fR +Tell in this description that the +.I argument +is required. +.TP +\fB\-V\fR, \fB\-\-version\fR +Display version information and exit. +.TP +\fB\-h\fR, \fB\-\-help\fR +Display help text and exit. +.SH NOTES +Tell details that users might need to know. For example, kernel feature or +version requirements. +.PP +The man-page source lines should not exceed 80 characters in length. +.PP +Do not leave empty lines in the groff input. If you need a break or a new +paragraph, use the appropriate groff macros. See +.BR groff_man (7) +how to use man page macros. +.PP +The use cases of +.I italic +(which is underlined on a terminal) and +.B bold +are not strictly defined. The main convention is that +.I symbolic arguments +use italic, and +.B commands +and +.B literal arguments +use bold, and +.I other highlights +use +.B either +one. +.\" +.\" The manual page comments are undervalued way of adding clarifications +.\" quite not belong to the manual, questions, TODO items etc. Feel free +.\" to use them. +.\" +.PP +When in the source a new sentence begins somewhere midline, it should use a +double space before its initial letter. This is done because \fBgroff\fR +uses a double space after a sentence when this sentence ends at the end of +an input line and the next sentence begins on the next line. +Unless a double space is used before other sentence starts as well, the +spacing style will be inconsistent. +.SH ENVIRONMENT +Tell which environment variables affect, and how, the execution of the command. +.TP +.B EXAMPLE_PATH +Configuration file path. Notice that well-known environment variables, such as +.BR HOME , +do not need explanation. +.SH FILES +Tell which file(s) the command uses. +.TP +.B $EXAMPLE_PATH +.TQ +.B $HOME/.example.conf +.TQ +.B /etc/example.conf +What are these files, in which order are they read, and will the evaluation +end or continue if one of them is found. +In case the explanation is not simple, write a separate "Special Files" +manual page that tells about syntax, meaning of key-value settings, etc. +This "Special Files" manual page then needs to be referred in the +.B SEE ALSO +section. +.TP +.B /var/log/example.log +Another file. +.SH EXAMPLES +Write typical and/or clever use examples here. The below examples are stupid, +and you should never write them in a real man page. +.TP +.B example -h +Output help screen. +.TP +.B example -V +Output version information. +.SH "EXIT STATUS" +This section can be left out if the command has only two return values, +.B 0 +for success and +.B 1 +for failure. Use of +.B sysexits.h +return values must be mentioned, but does not need to be explained. +.PP +.RS +.PD 0 +.TP +.B 0 +success +.TP +.B 1 +failure +.TP +.B 2 +tell why this could happen +.TP +.B 3 +etc +.PD +.RE +.SH AUTHORS +.MT rjh@\:example.org +Random J. Hacker +.ME +.br +.MT fred@\:example.com +Fred Foobar +.ME +.SH "SEE ALSO" +.BR groff_man (7), +.BR foo (1), +.BR bar (8) +.SH AVAILABILITY +The example command is part of the util-linux package and is available from +.UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ +Linux Kernel Archive +.UE . |