diff options
Diffstat (limited to 'man7/man.7')
| -rw-r--r-- | man7/man.7 | 507 |
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) |