-.\" 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
-.BR \-n ,\ \-\-no\-argument
-.\" \fB\-n\fR, \fB\-\-no\-argument\fR
-This option does not use an argument.
-.TP
-.BR \-\-optional [ =\c
-.IR argument ]
-.\" \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
-.BR \-r ,\ \-\-required\ \c
-.I argument
-.\"\fB\-r\fR, \fB\-\-required\fR \fIargument\fR
-Tell in this description that the
-.I argument
-is required.
-.TP
-.BR \-V ", " \-\-version
-.\"\fB\-V\fR, \fB\-\-version\fR
-Display version information and exit.
-.TP
-.BR \-h ,\ \-\-help
-.\"\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
-.B groff
-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 .
+Since v2.37 util-linux project uses asciidoc format to maintain man pages.
+See man-common/manpage-stub.adoc for more details.
projects / thirdparty / util-linux.git / commitdiff
