+++ /dev/null
-.\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler
-.\" (faith@cs.unc.edu and dwheeler@ida.org)
-.\"
-.\" %%%LICENSE_START(VERBATIM)
-.\" Permission is granted to make and distribute verbatim copies of this
-.\" manual provided the copyright notice and this permission notice are
-.\" preserved on all copies.
-.\"
-.\" Permission is granted to copy and distribute modified versions of this
-.\" manual under the conditions for verbatim copying, provided that the
-.\" entire resulting derived work is distributed under the terms of a
-.\" permission notice identical to this one.
-.\"
-.\" Since the Linux kernel and libraries are constantly changing, this
-.\" manual page may be incorrect or out-of-date. The author(s) assume no
-.\" responsibility for errors or omissions, or for damages resulting from
-.\" the use of the information contained herein. The author(s) may not
-.\" have taken the same level of care in the production of this manual,
-.\" which is licensed free of charge, as they might when working
-.\" professionally.
-.\"
-.\" Formatted or processed versions of this manual, if unaccompanied by
-.\" the source, must acknowledge the copyright and authors of this work.
-.\" %%%LICENSE_END
-.\"
-.\" 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 2012-08-05 "Linux" "Linux Programmer's Manual"
-.SH NAME
-man \- macros to format man pages
-.SH SYNOPSIS
-.B groff \-Tascii \-man
-.I file
-\&...
-.LP
-.B groff \-Tps \-man
-.I file
-\&...
-.LP
-.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.\\"\fP) should be
-.RS
-.sp
-.B \&.TH
-.I "title section date source manual"
-.sp
-.RE
-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.
-
-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:
-.RS
-.sp
-\&.SH NAME
-.br
-item \\- description
-.sp
-.RE
-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)
-.LP
-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.
-All of 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
-.PP
-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
-(Feature supported with
-.B groff
-only.)
-In order to use hypertext link macros, it is necessary to load the
-.B www.tmac
-macro package.
-Use the request
-.B .mso www.tmac
-to do this.
-.TP 9m
-.BI \&.URL " url link trailer"
-Inserts a hypertext link to the URI (URL)
-.IR url ,
-with
-.I link
-as the text of the link.
-The
-.I trailer
-will be printed immediately afterward.
-When generating HTML this should translate into the HTML command
-\fB<A HREF="\fP\fIurl\fP\fB">\fIlink\fP\fB</A>\fP\fItrailer\fP.
-.\" The following is a kludge to get a paragraph into the listing.
-.TP
-.B " "
-This and other related macros are new, and
-many tools won't do anything with them, but
-since many tools (including troff) will simply ignore undefined macros
-(or at worst insert their text) these are safe to insert.
-.\" The following is a kludge to get a paragraph into the listing.
-.TP
-.B " "
-It can be useful to define your own
-.B URL
-macro in manual pages for the benefit of those viewing it with a roff
-viewer other than
-.BR groff .
-That way, the URL, link text, and trailer text (if any) are still visible.
-.\" The following is a kludge to get a paragraph into the listing.
-.TP
-.B " "
-Here's an example:
-.RS 1.5i
-\&.de URL
-.br
-\\\\$2 \\(laURL: \\\\$1 \\(ra\\\\$3
-.br
-\&..
-.br
-\&.if \\n[.g] .mso www.tmac
-.br
-\&.TH
-.I ...
-.br
-.I (later in the page)
-.br
-This software comes from the
-.br
-\&.URL "http://www.gnu.org/" "GNU Project" " of the"
-.br
-\&.URL "http://www.fsf.org/" "Free Software Foundation" .
-.RE
-.\" The following is a kludge to get a paragraph into the listing.
-.TP
-.B " "
-In the above, if
-.B groff
-is being used, the
-.B www.tmac
-macro package's definition of the URL macro will supersede the locally
-defined one.
-.PP
-A number of other link macros are available.
-See
-.BR groff_www (7)
-for more details.
-.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:
-.IP \e*R
-Registration Symbol: \*R
-.IP \e*S
-Change to default font size
-.IP \e*(Tm
-Trademark Symbol: \*(Tm
-.IP \e*(lq
-Left angled double quote: \*(lq
-.IP \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' ,
-.BR \e` ,
-.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 \(aqt\(aq or \(aqn\(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
-.PP
-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 new
-.B URL
-macro to identify links to related information.
-If you include URLs, use the full URL
-(e.g.,
-.UR http://www.kernelnotes.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 (') 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\'\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
-.PP
-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.
-.LP
-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),
-.BR mdoc.samples (7)
-.SH COLOPHON
-This page is part of release 3.79 of the Linux
-.I man-pages
-project.
-A description of the project,
-information about reporting bugs,
-and the latest version of this page,
-can be found at
-\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
