Suggested-by: Alejandro Colomar <alx@xxxxxxxxxx> Acked-by: Ingo Schwarze <schwarze@xxxxxxx> Signed-off-by: "G. Branden Robinson" <g.branden.robinson@xxxxxxxxx> --- man7/man.7 | 508 +---------------------------------------------------- 1 file changed, 1 insertion(+), 507 deletions(-) diff --git a/man7/man.7 b/man7/man.7 index 583fe354f..f460f4ad3 100644 --- a/man7/man.7 +++ b/man7/man.7 @@ -1,507 +1 @@ -.\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler -.\" (faith@xxxxxxxxxx and dwheeler@xxxxxxx) -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.\" Modified Sun Jul 25 11:06:05 1993 by Rik Faith (faith@xxxxxxxxxx) -.\" Modified Sat Jun 8 00:39:52 1996 by aeb -.\" Modified Wed Jun 16 23:00:00 1999 by David A. Wheeler (dwheeler@xxxxxxx) -.\" Modified Thu Jul 15 12:43:28 1999 by aeb -.\" Modified Sun Jan 6 18:26:25 2002 by Martin Schulze <joey@xxxxxxxxxxxx> -.\" Modified Tue Jul 27 20:12:02 2004 by Colin Watson <cjwatson@xxxxxxxxxx> -.\" 2007-05-30, mtk: various rewrites and moved much text to new man-pages.7. -.\" -.TH man 7 (date) "Linux man-pages (unreleased)" -.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@xxxxxxxxxx) wrote the implementation of the macro package. -.\" .IP \[em] -.\" Rickard E. Faith (faith@xxxxxxxxxx) wrote the initial version of -.\" this manual page. -.\" .IP \[em] -.\" Jens Schweikhardt (schweikh@xxxxxxxxxx) wrote the Linux Man-Page Mini-HOWTO -.\" (which influenced this manual page). -.\" .IP \[em] -.\" David A. Wheeler (dwheeler@xxxxxxx) 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 -- 2.30.2
Attachment:
signature.asc
Description: PGP signature
