Adding upstream version 6.05.01.upstream/6.05.01

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

1 files changed, 507 insertions, 0 deletions

diff --git a/man7/man.7 b/man7/man.7
new file mode 100644
index 0000000..b0788f3
--- /dev/null
+++ b/man7/man.7
@@ -0,0 +1,507 @@
+.\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler
+.\" (faith@cs.unc.edu and dwheeler@ida.org)
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Modified Sun Jul 25 11:06:05 1993 by Rik Faith (faith@cs.unc.edu)
+.\" Modified Sat Jun  8 00:39:52 1996 by aeb
+.\" Modified Wed Jun 16 23:00:00 1999 by David A. Wheeler (dwheeler@ida.org)
+.\" Modified Thu Jul 15 12:43:28 1999 by aeb
+.\" Modified Sun Jan  6 18:26:25 2002 by Martin Schulze <joey@infodrom.org>
+.\" Modified Tue Jul 27 20:12:02 2004 by Colin Watson <cjwatson@debian.org>
+.\" 2007-05-30, mtk: various rewrites and moved much text to new man-pages.7.
+.\"
+.TH man 7 2023-07-29 "Linux man-pages 6.05.01"
+.SH NAME
+man \- macros to format man pages
+.SH SYNOPSIS
+.B groff \-Tascii \-man
+.I file
+\&...
+.br
+.B groff \-Tps \-man
+.I file
+\&...
+.PP
+.B man
+.RI [ section ]
+.I title
+.SH DESCRIPTION
+This manual page explains the
+.B "groff an.tmac"
+macro package (often called the
+.B man
+macro package).
+This macro package should be used by developers when
+writing or porting man pages for Linux.
+It is fairly compatible with other
+versions of this macro package, so porting man pages should not be a major
+problem (exceptions include the NET-2 BSD release, which uses a totally
+different macro package called mdoc; see
+.BR mdoc (7)).
+.PP
+Note that NET-2 BSD mdoc man pages can be used with
+.B groff
+simply by specifying the
+.B \-mdoc
+option instead of the
+.B \-man
+option.
+Using the
+.B \-mandoc
+option is, however, recommended, since this will automatically detect which
+macro package is in use.
+.PP
+For conventions that should be employed when writing man pages
+for the Linux \fIman-pages\fP package, see
+.BR man\-pages (7).
+.SS Title line
+The first command in a man page (after comment lines,
+that is, lines that start with \fB.\e"\fP) should be
+.PP
+.RS
+.B .TH
+.I "title section date source manual"
+.RE
+.PP
+For details of the arguments that should be supplied to the
+.B TH
+command, see
+.BR man\-pages (7).
+.PP
+Note that BSD mdoc-formatted pages begin with the
+.B Dd
+command, not the
+.B TH
+command.
+.SS Sections
+Sections are started with
+.B .SH
+followed by the heading name.
+.\" The following doesn't seem to be required (see Debian bug 411303),
+.\" If the name contains spaces and appears
+.\" on the same line as
+.\" .BR .SH ,
+.\" then place the heading in double quotes.
+.PP
+The only mandatory heading is NAME, which should be the first section and
+be followed on the next line by a one-line description of the program:
+.PP
+.RS
+\&.SH NAME
+.br
+item \e- description
+.RE
+.PP
+It is extremely important that this format is followed, and that there is a
+backslash before the single dash which follows the item name.
+This syntax is used by the
+.BR mandb (8)
+program to create a database of short descriptions for the
+.BR whatis (1)
+and
+.BR apropos (1)
+commands.
+(See
+.BR lexgrog (1)
+for further details on the syntax of the NAME section.)
+.PP
+For a list of other sections that might appear in a manual page, see
+.BR man\-pages (7).
+.SS Fonts
+The commands to select the type face are:
+.TP 4
+.B .B
+Bold
+.TP
+.B .BI
+Bold alternating with italics
+(especially useful for function specifications)
+.TP
+.B .BR
+Bold alternating with Roman
+(especially useful for referring to other
+manual pages)
+.TP
+.B .I
+Italics
+.TP
+.B .IB
+Italics alternating with bold
+.TP
+.B .IR
+Italics alternating with Roman
+.TP
+.B .RB
+Roman alternating with bold
+.TP
+.B .RI
+Roman alternating with italics
+.TP
+.B .SB
+Small alternating with bold
+.TP
+.B .SM
+Small (useful for acronyms)
+.PP
+Traditionally, each command can have up to six arguments, but the GNU
+implementation removes this limitation (you might still want to limit
+yourself to 6 arguments for portability's sake).
+Arguments are delimited by spaces.
+Double quotes can be used to specify an argument which contains spaces.
+For the macros that produce alternating type faces,
+the arguments will be printed next to each other without
+intervening spaces, so that the
+.B .BR
+command can be used to specify a word in bold followed by a mark of
+punctuation in Roman.
+If no arguments are given, the command is applied to the following line
+of text.
+.SS Other macros and strings
+Below are other relevant macros and predefined strings.
+Unless noted otherwise, all macros
+cause a break (end the current line of text).
+Many of these macros set or use the "prevailing indent".
+The "prevailing indent" value is set by any macro with the parameter
+.I i
+below;
+macros may omit
+.I i
+in which case the current prevailing indent will be used.
+As a result, successive indented paragraphs can use the same indent without
+respecifying the indent value.
+A normal (nonindented) paragraph resets the prevailing indent value
+to its default value (0.5 inches).
+By default, a given indent is measured in ens;
+try to use ens or ems as units for
+indents, since these will automatically adjust to font size changes.
+The other key macro definitions are:
+.SS Normal paragraphs
+.TP 9m
+.B .LP
+Same as
+.B .PP
+(begin a new paragraph).
+.TP
+.B .P
+Same as
+.B .PP
+(begin a new paragraph).
+.TP
+.B .PP
+Begin a new paragraph and reset prevailing indent.
+.SS Relative margin indent
+.TP 9m
+.BI .RS " i"
+Start relative margin indent: moves the left margin
+.I i
+to the right (if
+.I i
+is omitted, the prevailing indent value is used).
+A new prevailing indent is set to 0.5 inches.
+As a result, all following paragraph(s) will be
+indented until the corresponding
+.BR .RE .
+.TP
+.B .RE
+End relative margin indent and
+restores the previous value of the prevailing indent.
+.SS Indented paragraph macros
+.TP 9m
+.BI .HP " i"
+Begin paragraph with a hanging indent
+(the first line of the paragraph is at the left margin of
+normal paragraphs, and the rest of the paragraph's lines are indented).
+.TP
+.BI .IP " x i"
+Indented paragraph with optional hanging tag.
+If the tag
+.I x
+is omitted, the entire following paragraph is indented by
+.IR i .
+If the tag
+.I x
+is provided, it is hung at the left margin
+before the following indented paragraph
+(this is just like
+.B .TP
+except the tag is included with the command instead of being on the
+following line).
+If the tag is too long, the text after the tag will be moved down to the
+next line (text will not be lost or garbled).
+For bulleted lists, use this macro with \e(bu (bullet) or \e(em (em dash)
+as the tag, and for numbered lists, use the number or letter followed by
+a period as the tag;
+this simplifies translation to other formats.
+.TP
+.BI .TP " i"
+Begin paragraph with hanging tag.
+The tag is given on the next line, but
+its results are like those of the
+.B .IP
+command.
+.SS Hypertext link macros
+.TP
+.BI .UR " url"
+Insert a hypertext link to the URI (URL)
+.IR url ,
+with all text up to the following
+.B .UE
+macro as the link text.
+.TP
+.BR .UE \~\c
+.RI [ trailer ]
+Terminate the link text of the preceding
+.B .UR
+macro, with the optional
+.I trailer
+(if present, usually a closing parenthesis and/or end-of-sentence
+punctuation) immediately following.
+For non-HTML output devices (e.g.,
+.BR "man \-Tutf8" ),
+the link text is followed by the URL in angle brackets; if there is no
+link text, the URL is printed as its own link text, surrounded by angle
+brackets.
+(Angle brackets may not be available on all output devices.)
+For the HTML output device, the link text is hyperlinked to the URL; if
+there is no link text, the URL is printed as its own link text.
+.PP
+These macros have been supported since GNU Troff 1.20 (2009-01-05) and
+Heirloom Doctools Troff since 160217 (2016-02-17).
+.SS Miscellaneous macros
+.TP 9m
+.B .DT
+Reset tabs to default tab values (every 0.5 inches);
+does not cause a break.
+.TP
+.BI .PD " d"
+Set inter-paragraph vertical distance to d
+(if omitted, d=0.4v);
+does not cause a break.
+.TP
+.BI .SS " t"
+Subheading
+.I t
+(like
+.BR .SH ,
+but used for a subsection inside a section).
+.SS Predefined strings
+The
+.B man
+package has the following predefined strings:
+.TP
+\e*R
+Registration Symbol: \*R
+.TP
+\e*S
+Change to default font size
+.TP
+\e*(Tm
+Trademark Symbol: \*(Tm
+.TP
+\e*(lq
+Left angled double quote: \*(lq
+.TP
+\e*(rq
+Right angled double quote: \*(rq
+.SS Safe subset
+Although technically
+.B man
+is a troff macro package, in reality a large number of other tools
+process man page files that don't implement all of troff's abilities.
+Thus, it's best to avoid some of troff's more exotic abilities
+where possible to permit these other tools to work correctly.
+Avoid using the various troff preprocessors
+(if you must, go ahead and use
+.BR tbl (1),
+but try to use the
+.B IP
+and
+.B TP
+commands instead for two-column tables).
+Avoid using computations; most other tools can't process them.
+Use simple commands that are easy to translate to other formats.
+The following troff macros are believed to be safe (though in many cases
+they will be ignored by translators):
+.BR \e" ,
+.BR . ,
+.BR ad ,
+.BR bp ,
+.BR br ,
+.BR ce ,
+.BR de ,
+.BR ds ,
+.BR el ,
+.BR ie ,
+.BR if ,
+.BR fi ,
+.BR ft ,
+.BR hy ,
+.BR ig ,
+.BR in ,
+.BR na ,
+.BR ne ,
+.BR nf ,
+.BR nh ,
+.BR ps ,
+.BR so ,
+.BR sp ,
+.BR ti ,
+.BR tr .
+.PP
+You may also use many troff escape sequences (those sequences beginning
+with \e).
+When you need to include the backslash character as normal text,
+use \ee.
+Other sequences you may use, where x or xx are any characters and N
+is any digit, include:
+.BR \e\[aq] ,
+.BR \e\[ga] ,
+.BR \e- ,
+.BR \e. ,
+.BR \e" ,
+.BR \e% ,
+.BR \e*x ,
+.BR \e*(xx ,
+.BR \e(xx ,
+.BR \e$N ,
+.BR \enx ,
+.BR \en(xx ,
+.BR \efx ,
+and
+.BR \ef(xx .
+Avoid using the escape sequences for drawing graphics.
+.PP
+Do not use the optional parameter for
+.B bp
+(break page).
+Use only positive values for
+.B sp
+(vertical space).
+Don't define a macro
+.RB ( de )
+with the same name as a macro in this or the
+mdoc macro package with a different meaning; it's likely that
+such redefinitions will be ignored.
+Every positive indent
+.RB ( in )
+should be paired with a matching negative indent
+(although you should be using the
+.B RS
+and
+.B RE
+macros instead).
+The condition test
+.RB ( if,ie )
+should only have \[aq]t\[aq] or \[aq]n\[aq] as the condition.
+Only translations
+.RB ( tr )
+that can be ignored should be used.
+Font changes
+.RB ( ft
+and the \fB\ef\fP escape sequence)
+should only have the values 1, 2, 3, 4, R, I, B, P, or CW
+(the ft command may also have no parameters).
+.PP
+If you use capabilities beyond these, check the
+results carefully on several tools.
+Once you've confirmed that the additional capability is safe,
+let the maintainer of this
+document know about the safe command or sequence
+that should be added to this list.
+.SH FILES
+.IR /usr/share/groff/ [*/] tmac/an.tmac
+.br
+.I /usr/man/whatis
+.SH NOTES
+By all means include full URLs (or URIs) in the text itself;
+some tools such as
+.BR man2html (1)
+can automatically turn them into hypertext links.
+You can also use the
+.B UR
+and
+.B UE
+macros to identify links to related information.
+If you include URLs, use the full URL
+(e.g.,
+.UR http://www.kernel.org
+.UE )
+to ensure that tools can automatically find the URLs.
+.PP
+Tools processing these files should open the file and examine the first
+nonwhitespace character.
+A period (.) or single quote (\[aq]) at the beginning
+of a line indicates a troff-based file (such as man or mdoc).
+A left angle bracket (<) indicates an SGML/XML-based
+file (such as HTML or Docbook).
+Anything else suggests simple ASCII
+text (e.g., a "catman" result).
+.PP
+Many man pages begin with \fB\[aq]\e"\fP followed by a
+space and a list of characters,
+indicating how the page is to be preprocessed.
+For portability's sake to non-troff translators we recommend
+that you avoid using anything other than
+.BR tbl (1),
+and Linux can detect that automatically.
+However, you might want to include this information so your man page
+can be handled by other (less capable) systems.
+Here are the definitions of the preprocessors invoked by these characters:
+.TP 3
+.B e
+eqn(1)
+.TP
+.B g
+grap(1)
+.TP
+.B p
+pic(1)
+.TP
+.B r
+refer(1)
+.TP
+.B t
+tbl(1)
+.TP
+.B v
+vgrind(1)
+.SH BUGS
+Most of the macros describe formatting (e.g., font type and spacing) instead
+of marking semantic content (e.g., this text is a reference to another page),
+compared to formats like mdoc and DocBook (even HTML has more semantic
+markings).
+This situation makes it harder to vary the
+.B man
+format for different media,
+to make the formatting consistent for a given media, and to automatically
+insert cross-references.
+By sticking to the safe subset described above, it should be easier to
+automate transitioning to a different reference page format in the future.
+.PP
+The Sun macro
+.B TX
+is not implemented.
+.\" .SH AUTHORS
+.\" .IP \[em] 3m
+.\" James Clark (jjc@jclark.com) wrote the implementation of the macro package.
+.\" .IP \[em]
+.\" Rickard E. Faith (faith@cs.unc.edu) wrote the initial version of
+.\" this manual page.
+.\" .IP \[em]
+.\" Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux Man-Page Mini-HOWTO
+.\" (which influenced this manual page).
+.\" .IP \[em]
+.\" David A. Wheeler (dwheeler@ida.org) heavily modified this
+.\" manual page, such as adding detailed information on sections and macros.
+.SH SEE ALSO
+.BR apropos (1),
+.BR groff (1),
+.BR lexgrog (1),
+.BR man (1),
+.BR man2html (1),
+.BR whatis (1),
+.BR groff_man (7),
+.BR groff_www (7),
+.BR man\-pages (7),
+.BR mdoc (7)