[BACK]Return to man.7 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/man.7, Revision 1.24

1.24    ! kristaps    1: .\"    $Id: man.7,v 1.23 2009/08/13 12:15:58 kristaps Exp $
1.1       kristaps    2: .\"
1.11      kristaps    3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
1.1       kristaps    4: .\"
                      5: .\" Permission to use, copy, modify, and distribute this software for any
1.10      kristaps    6: .\" purpose with or without fee is hereby granted, provided that the above
                      7: .\" copyright notice and this permission notice appear in all copies.
                      8: .\"
                      9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
                     10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
                     11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
                     12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
                     13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
                     14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
                     15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1.1       kristaps   16: .\"
                     17: .Dd $Mdocdate$
1.9       kristaps   18: .Dt MAN 7
1.1       kristaps   19: .Os
                     20: .\" SECTION
                     21: .Sh NAME
                     22: .Nm man
                     23: .Nd man language reference
                     24: .\" SECTION
                     25: .Sh DESCRIPTION
                     26: The
                     27: .Nm man
1.20      kristaps   28: language was historically used to format
1.1       kristaps   29: .Ux
1.19      kristaps   30: manuals.  This reference document describes its syntax, structure, and
                     31: usage.
1.1       kristaps   32: .Pp
1.20      kristaps   33: .Bf -emphasis
                     34: Do not use
1.1       kristaps   35: .Nm
1.20      kristaps   36: to write your manuals.
1.19      kristaps   37: .Ef
                     38: Use the
1.1       kristaps   39: .Xr mdoc 7
                     40: language, instead.
                     41: .\" PARAGRAPH
                     42: .Pp
                     43: An
                     44: .Nm
                     45: document follows simple rules:  lines beginning with the control
1.20      kristaps   46: character
1.2       kristaps   47: .Sq \&.
1.1       kristaps   48: are parsed for macros.  Other lines are interpreted within the scope of
                     49: prior macros:
1.4       kristaps   50: .Bd -literal -offset indent
1.1       kristaps   51: \&.SH Macro lines change control state.
                     52: Other lines are interpreted within the current state.
                     53: .Ed
                     54: .\" SECTION
                     55: .Sh INPUT ENCODING
                     56: .Nm
1.14      kristaps   57: documents may contain only graphable 7-bit ASCII characters, the
1.19      kristaps   58: space character, and the tabs character.  All manuals must have
1.5       kristaps   59: .Ux
1.20      kristaps   60: line termination.
1.1       kristaps   61: .Pp
1.5       kristaps   62: Blank lines are acceptable; where found, the output will assert a
1.1       kristaps   63: vertical space.
1.4       kristaps   64: .Pp
                     65: The
                     66: .Sq \ec
                     67: escape is common in historical
                     68: .Nm
                     69: documents; if encountered at the end of a word, it ensures that the
                     70: subsequent word isn't off-set by whitespace.
1.1       kristaps   71: .\" SUB-SECTION
1.13      kristaps   72: .Ss Comments
1.21      kristaps   73: Text following a
1.22      kristaps   74: .Sq \e\*" ,
1.21      kristaps   75: whether in a macro or free-form text line, is ignored to the end of
                     76: line.  A macro line with only a control character and comment escape,
                     77: .Sq \&.\e" ,
1.22      kristaps   78: is also ignored.  Macro lines with only a control charater and
                     79: optionally whitespace are stripped from input.
1.13      kristaps   80: .\" SUB-SECTION
1.1       kristaps   81: .Ss Special Characters
1.21      kristaps   82: Special characters may occur in both macro and free-form lines.
                     83: Sequences begin with the escape character
1.2       kristaps   84: .Sq \e
1.20      kristaps   85: followed by either an open-parenthesis
1.1       kristaps   86: .Sq \&(
                     87: for two-character sequences; an open-bracket
                     88: .Sq \&[
                     89: for n-character sequences (terminated at a close-bracket
                     90: .Sq \&] ) ;
1.21      kristaps   91: or a single one-character sequence.  See
                     92: .Xr mandoc_char 7
                     93: for a complete list.  Examples include
                     94: .Sq \e(em
                     95: .Pq em-dash
                     96: and
                     97: .Sq \ee
                     98: .Pq back-slash .
                     99: .\" SUB-SECTION----------------------
                    100: .Ss Text Decoration
                    101: Terms may be text-decorated using the
1.18      kristaps  102: .Sq \ef
1.21      kristaps  103: escape followed by an indicator: B (bold), I, (italic), or P and R
                    104: (Roman, or reset).
                    105: .\" SUB-SECTION----------------------
1.17      kristaps  106: .Ss Whitespace
                    107: Unless specifically escaped, consecutive blocks of whitespace are pruned
                    108: from input.  These are later re-added, if applicable, by a front-end
                    109: utility such as
                    110: .Xr mandoc 1 .
1.1       kristaps  111: .\" SECTION
1.22      kristaps  112: .Sh MANUAL STRUCTURE
1.16      kristaps  113: Each
                    114: .Nm
                    115: document must contain contains at least the
1.22      kristaps  116: .Sq \&TH
1.16      kristaps  117: macro describing the document's section and title.  It may occur
                    118: anywhere in the document, although conventionally, it appears as the
                    119: first macro.
                    120: .Pp
1.22      kristaps  121: Beyond
                    122: .Sq \&TH ,
                    123: at least one macro or text node must appear in the document.  Documents
                    124: are generally structured as follows:
                    125: .Bd -literal -offset indent
                    126: \&.TH FOO 1 "13 Aug 2009"
                    127: \&.
                    128: \&.SH NAME
                    129: foo \e- a description goes here
                    130: \&.
                    131: \&.SH SYNOPSIS
                    132: \efBfoo\efR [\efB\e-options\efR] arguments...
                    133: \&.
                    134: \&.SH DESCRIPTION
                    135: The \efBfoo\efR utility does...
                    136: \&.
                    137: \&.\e\*q .SH RETURN VALUES
                    138: \&.\e\*q .SH ENVIRONMENT
                    139: \&.\e\*q .SH FILES
                    140: \&.\e\*q .SH EXAMPLES
                    141: \&.\e\*q .SH DIAGNOSTICS
                    142: \&.\e\*q .SH ERRORS
                    143: \&.\e\*q .SH SEE ALSO
                    144: \&.\e\*q \efBbar\efR(1)
                    145: \&.\e\*q .SH STANDARDS
                    146: \&.\e\*q .SH HISTORY
                    147: \&.\e\*q .SH AUTHORS
                    148: \&.\e\*q .SH CAVEATS
                    149: \&.\e\*q .SH BUGS
                    150: .Ed
1.16      kristaps  151: .\" SECTION
1.22      kristaps  152: .Sh MACRO SYNTAX
1.2       kristaps  153: Macros are one to three three characters in length and begin with a
1.4       kristaps  154: control character ,
                    155: .Sq \&. ,
1.2       kristaps  156: at the beginning of the line.  An arbitrary amount of whitespace may
                    157: sit between the control character and the macro name.  Thus,
1.4       kristaps  158: .Sq \&.PP
1.2       kristaps  159: and
                    160: .Sq \&.\ \ \ \&PP
                    161: are equivalent.
                    162: .Pp
1.1       kristaps  163: The
1.4       kristaps  164: .Nm
1.22      kristaps  165: macros are classified by scope: line scope or block scope.  Line-scoped
                    166: macros are only scoped to the current line (and, in some situations,
                    167: the subsequent line).  Block macros are scoped to the current line and
                    168: subsequent lines until closed by another block macro.
                    169: .\" SUBSECTION
                    170: .Ss Line Macros
                    171: Line-macros are scoped to the current line, with the body consisting of
                    172: zero or more arguments.  If a macro is next-line scoped and the line
                    173: arguments are empty, the next line is used instead.  Thus:
1.20      kristaps  174: .Bd -literal -offset indent
                    175: \&.RI
1.4       kristaps  176: foo
                    177: .Ed
1.22      kristaps  178: .\" PARAGRAPH
1.4       kristaps  179: .Pp
1.20      kristaps  180: is equivalent to
1.8       kristaps  181: .Sq \&.RI foo .
1.22      kristaps  182: .\" PARAGRAPH
                    183: Consecutive next-line invocations are disallowed.
1.20      kristaps  184: .Bd -literal -offset indent
1.22      kristaps  185: \&.YO \(lBbody...\(rB
                    186: \(lBbody...\(rB
1.4       kristaps  187: .Ed
1.22      kristaps  188: .\" PARAGRAPH
1.4       kristaps  189: .Pp
1.22      kristaps  190: .Bl -column -compact -offset indent "MacroX" "ArgumentsX" "ScopeXXXXX"
                    191: .It Em Macro Ta Em Arguments Ta Em Scope
                    192: .It  \&B     Ta    n         Ta    next-line
                    193: .It  \&BI    Ta    n         Ta    current
                    194: .It  \&BR    Ta    n         Ta    current
                    195: .It  \&I     Ta    n         Ta    next-line
                    196: .It  \&IB    Ta    n         Ta    current
                    197: .It  \&IR    Ta    n         Ta    current
                    198: .It  \&R     Ta    n         Ta    next-line
                    199: .It  \&RB    Ta    n         Ta    current
                    200: .It  \&RI    Ta    n         Ta    current
                    201: .It  \&SB    Ta    n         Ta    next-line
                    202: .It  \&SM    Ta    n         Ta    next-line
                    203: .It  \&TH    Ta    >1, <6    Ta    current
                    204: .It  \&br    Ta    0         Ta    current
                    205: .It  \&fi    Ta    0         Ta    current
                    206: .It  \&i     Ta    n         Ta    current
                    207: .It  \&na    Ta    0         Ta    current
                    208: .It  \&nf    Ta    0         Ta    current
                    209: .It  \&r     Ta    0         Ta    current
                    210: .It  \&sp    Ta    1         Ta    current
1.1       kristaps  211: .El
1.22      kristaps  212: .\" PARAGRAPH
1.7       kristaps  213: .Pp
1.22      kristaps  214: The lower-case
                    215: .Sq \&br ,
                    216: .Sq \&fi ,
                    217: .Sq \&i ,
                    218: .Sq \&na ,
                    219: .Sq \&nf ,
                    220: .Sq \&r ,
                    221: and
                    222: .Sq \&sp
                    223: macros aren't historically part of
1.7       kristaps  224: .Nm
1.22      kristaps  225: and should not be used.  They're included for compatibility.
                    226: .\" SUBSECTION
                    227: .Ss Block Macros
                    228: Block macros are comprised of a head and body.  The head is scoped to
                    229: the current line and, in one circumstance, the next line; the body is
                    230: scoped to subsequent lines and is closed out by a subsequent block macro
                    231: invocation.
                    232: .Bd -literal -offset indent
                    233: \&.YO \(lBhead...\(rB
                    234: \(lBhead...\(rB
                    235: \(lBbody...\(rB
                    236: .Ed
                    237: .\" PARAGRAPH
                    238: .Pp
                    239: If a block macro is next-line scoped, it may only be followed by in-line
                    240: macros (excluding
                    241: .Sq na ,
                    242: .Sq sp ,
                    243: .Sq nf ,
                    244: .Sq fi ,
                    245: and
                    246: .Sq TH ) .
                    247: .\" PARAGRAPH
1.7       kristaps  248: .Pp
1.22      kristaps  249: .Bl -column "MacroX" "Arguments" "ScopeXXXX" -compact -offset indent
                    250: .It Em Macro Ta Em Arguments Ta Em Scope
                    251: .It \&HP     Ta    <2        Ta    current
                    252: .It \&IP     Ta    <3        Ta    current
                    253: .It \&LP     Ta    0         Ta    current
                    254: .It \&P      Ta    0         Ta    current
                    255: .It \&PP     Ta    0         Ta    current
                    256: .It \&SH     Ta    >0        Ta    current
                    257: .It \&SS     Ta    >0        Ta    current
                    258: .It \&TP     Ta    n         Ta    next-line
1.7       kristaps  259: .El
1.22      kristaps  260: .\" SECTION
                    261: .Sh REFERENCE
                    262: This section is a canonical reference to all macros, arranged
                    263: alphabetically.  For the scoping of individual macros, see
                    264: .Sx MACRO SYNTAX .
1.23      kristaps  265: .Bl -tag -width Ds
1.22      kristaps  266: .It \&B
                    267: Text is rendered in bold face.
                    268: .It \&BI
                    269: Text is rendered alternately in bold face and italic.  Thus,
                    270: .Sq \&.BI this word and that
                    271: causes
                    272: .Sq this
                    273: and
                    274: .Sq and
                    275: to render in bold face, while
                    276: .Sq word
                    277: and
                    278: .Sq that
                    279: render in italics.  Whitespace between arguments is omitted in output.
                    280: .It \&BR
                    281: Text is rendered alternately in bold face and roman (the default font).
                    282: Whitespace between arguments is omitted in output.
                    283: .It \&HP
1.23      kristaps  284: Begin a paragraph whose initial output line is left-justified, but
                    285: subsequent output lines are indented.
1.22      kristaps  286: .\" TODO.
                    287: .It \&I
                    288: Text is rendered in italics.
                    289: .It \&IB
                    290: Text is rendered alternately in italics and bold face.  Whitespace
                    291: between arguments is omitted in output.
                    292: .It \&IP
                    293: .\" TODO.
                    294: .It \&IR
                    295: Text is rendered alternately in italics and roman (the default font).
                    296: Whitespace between arguments is omitted in output.
                    297: .It \&LP, \&P, \&PP
                    298: Begin an undecorated paragraph.  The scope of a paragraph is closed by a
                    299: subsequent paragraph, sub-section, section, or end of file.
                    300: .It \&R
                    301: Text is rendered in roman (the default font).
                    302: .It \&RB
                    303: Text is rendered alternately in roman (the default font) and bold face.
                    304: Whitespace between arguments is omitted in output.
                    305: .It \&RI
                    306: Text is rendered alternately in roman (the default font) and italics.
                    307: Whitespace between arguments is omitted in output.
                    308: .It \&SB
                    309: Text is rendered in small size (one point smaller than the default font)
                    310: bold face.
                    311: .It \&SH
                    312: Begin a section.  The scope of a section is only closed by another
                    313: section or the end of file.
                    314: .It \&SM
                    315: Text is rendered in small size (one point smaller than the default
                    316: font).
                    317: .It \&SS
                    318: Begin a sub-section.  The scope of a sub-section is closed by a
                    319: subsequent sub-section, section, or end of file.
                    320: .It \&TH
                    321: Sets the title of the manual page with the following syntax:
                    322: .Bd -literal -offset indent
                    323: \&.TH title section date source volume
                    324: .Ed
1.8       kristaps  325: .Pp
1.22      kristaps  326: At least the
                    327: .Va title
                    328: and
                    329: .Va section
                    330: arguments must be provided.  The
                    331: .Va date
                    332: argument should be formatted as
                    333: .Qq %b [%d] %Y
                    334: format, described in
                    335: .Xr strptime 3 .
                    336: The
                    337: .Va source
                    338: string specifies the organisation providing the utility.  The
                    339: .Va volume
                    340: replaces the default rendered volume as dictated by the manual section.
                    341: .It \&TP
1.24    ! kristaps  342: Begin a paragraph where the head, if exceeding the indentation point, is
        !           343: followed by a newline; if not, the body follows on the same line after a
        !           344: buffer to the indentation point.  Subsequent output lines are indented.
1.22      kristaps  345: .It \&br
                    346: Breaks the current line.  Consecutive invocations have no further effect.
                    347: .\" TODO.
                    348: .It \&fi
                    349: End literal mode begun by
                    350: .Sq \&nf .
                    351: .It \&i
                    352: Italicise arguments.  If no arguments are specified, all subsequent text
                    353: is italicised.
                    354: .It \&na
                    355: No alignment to the right margin.
                    356: .It \&nf
                    357: Begin literal mode: all subsequent free-form lines have their end of
                    358: line boundaries preserved.  May be ended by
                    359: .Sq \&fi .
                    360: .It \&r
                    361: Fonts and styles (bold face, italics) reset to roman (default font).
                    362: .It \&sp
                    363: Insert n spaces, where n is the macro's positive numeric argument.  If
                    364: 0, this is equivalent to the
                    365: .Sq br
                    366: macro.
                    367: .El
1.1       kristaps  368: .\" SECTION
1.18      kristaps  369: .Sh COMPATIBILITY
1.23      kristaps  370: This section documents compatibility with other roff implementations, at
                    371: this time limited to
                    372: .Xr groff 1 .
                    373: .Bl -hyphen
                    374: .It
                    375: In quoted literals, groff allowed pair-wise double-quotes to produce a
                    376: standalone double-quote in formatted output.  This idiosyncratic
                    377: behaviour is no longer applicable.
                    378: .It
                    379: The
                    380: .Sq \&sp
                    381: macro does not accept negative numbers.
                    382: .It
                    383: Blocks of whitespace are stripped from both macro and free-form text
                    384: lines (except when in literal mode), while groff would retain whitespace
                    385: in free-form text lines.
                    386: .El
1.18      kristaps  387: .\" SECTION
1.1       kristaps  388: .Sh SEE ALSO
1.6       kristaps  389: .Xr mandoc 1 ,
                    390: .Xr mandoc_char 7
1.1       kristaps  391: .\" SECTION
                    392: .Sh AUTHORS
                    393: The
                    394: .Nm
1.23      kristaps  395: reference was written by
1.12      kristaps  396: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.1       kristaps  397: .\" SECTION
                    398: .Sh CAVEATS
                    399: Do not use this language.  Use
                    400: .Xr mdoc 7 ,
                    401: instead.

CVSweb