| .\" 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 ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/ |
| Linux Kernel Archive |
| .UE . |