From 6a23bf93fd83caa6d37c3e9b3c4936ee1ba17954 Mon Sep 17 00:00:00 2001 From: Karel Zak Date: Mon, 29 Mar 2021 15:04:15 +0200 Subject: [PATCH] docs: update Documentation/howto-man-page.txt Signed-off-by: Karel Zak --- Documentation/howto-man-page.txt | 198 +------------------------------ 1 file changed, 2 insertions(+), 196 deletions(-) diff --git a/Documentation/howto-man-page.txt b/Documentation/howto-man-page.txt index f2b352dac7..d0ebd01bab 100644 --- a/Documentation/howto-man-page.txt +++ b/Documentation/howto-man-page.txt @@ -1,196 +1,2 @@ -.\" 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. -- 2.47.3