Adding upstream version 2.33.1.upstream/2.33.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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 .