Merging upstream version 6.7.

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

1 files changed, 1 insertions, 507 deletions

diff --git a/man7/man.7 b/man7/man.7
index b0788f3..f460f4a 100644
--- a/man7/man.7
+++ b/man7/man.7
@@ -1,507 +1 @@
-.\" (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)
+.so man7/groff_man.7