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

Annotation of mandoc/man.7, Revision 1.17

1.17    ! kristaps    1: .\"    $Id: man.7,v 1.16 2009/06/25 10:48:21 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
                     28: language was historically used to format
                     29: .Ux
1.8       kristaps   30: manuals.  This reference document describes the syntax and structure of
                     31: this language.
1.1       kristaps   32: .Pp
1.8       kristaps   33: .Em \&Do not
1.1       kristaps   34: use
                     35: .Nm
                     36: to write your manuals.  Use the
                     37: .Xr mdoc 7
                     38: language, instead.
                     39: .\" PARAGRAPH
                     40: .Pp
                     41: An
                     42: .Nm
                     43: document follows simple rules:  lines beginning with the control
                     44: character
1.2       kristaps   45: .Sq \&.
1.1       kristaps   46: are parsed for macros.  Other lines are interpreted within the scope of
                     47: prior macros:
1.4       kristaps   48: .Bd -literal -offset indent
1.1       kristaps   49: \&.SH Macro lines change control state.
                     50: Other lines are interpreted within the current state.
                     51: .Ed
                     52: .\" SECTION
                     53: .Sh INPUT ENCODING
                     54: .Nm
1.14      kristaps   55: documents may contain only graphable 7-bit ASCII characters, the
1.1       kristaps   56: space character
1.14      kristaps   57: .Sq \  ,
                     58: and tabs
                     59: .Sq \et .
1.1       kristaps   60: All manuals must have
1.5       kristaps   61: .Ux
1.1       kristaps   62: .Sq \en
                     63: line termination.
                     64: .Pp
1.5       kristaps   65: Blank lines are acceptable; where found, the output will assert a
1.1       kristaps   66: vertical space.
1.4       kristaps   67: .Pp
                     68: The
                     69: .Sq \ec
                     70: escape is common in historical
                     71: .Nm
                     72: documents; if encountered at the end of a word, it ensures that the
                     73: subsequent word isn't off-set by whitespace.
1.1       kristaps   74: .\" SUB-SECTION
1.13      kristaps   75: .Ss Comments
                     76: Anything following a
                     77: .Sq \e"
                     78: delimiter is considered a comment (unless the
                     79: .Sq \e
                     80: itself has been escaped) and is ignored to the end of line.
                     81: Furthermore, a macro line with only a control character
                     82: .Sq \. ,
                     83: optionally followed by whitespace, is ignored.
                     84: .\" SUB-SECTION
1.1       kristaps   85: .Ss Special Characters
                     86: Special character sequences begin with the escape character
1.2       kristaps   87: .Sq \e
1.1       kristaps   88: followed by either an open-parenthesis
                     89: .Sq \&(
                     90: for two-character sequences; an open-bracket
                     91: .Sq \&[
                     92: for n-character sequences (terminated at a close-bracket
                     93: .Sq \&] ) ;
                     94: or a single one-character sequence.
                     95: .Pp
                     96: Characters may alternatively be escaped by a slash-asterisk,
1.2       kristaps   97: .Sq \e* ,
1.1       kristaps   98: with the same combinations as described above.  This form is deprecated.
1.17    ! kristaps   99: .\" SUB-SECTION
        !           100: .Ss Whitespace
        !           101: Unless specifically escaped, consecutive blocks of whitespace are pruned
        !           102: from input.  These are later re-added, if applicable, by a front-end
        !           103: utility such as
        !           104: .Xr mandoc 1 .
1.1       kristaps  105: .\" SECTION
1.16      kristaps  106: .Sh STRUCTURE
                    107: Each
                    108: .Nm
                    109: document must contain contains at least the
                    110: .Sq \&.TH
                    111: macro describing the document's section and title.  It may occur
                    112: anywhere in the document, although conventionally, it appears as the
                    113: first macro.
                    114: .Pp
                    115: Beyond the
                    116: .Sq \&.TH ,
                    117: at least one macro or text node must appear in the document.
                    118: .\" SECTION
1.15      kristaps  119: .Sh SYNTAX
1.2       kristaps  120: Macros are one to three three characters in length and begin with a
1.4       kristaps  121: control character ,
                    122: .Sq \&. ,
1.2       kristaps  123: at the beginning of the line.  An arbitrary amount of whitespace may
                    124: sit between the control character and the macro name.  Thus,
1.4       kristaps  125: .Sq \&.PP
1.2       kristaps  126: and
                    127: .Sq \&.\ \ \ \&PP
                    128: are equivalent.
                    129: .Pp
1.4       kristaps  130: All
                    131: .Nm
                    132: macros follow the same structural rules:
                    133: .Bd -literal -offset indent
                    134: \&.YO \(lBbody...\(rB
1.1       kristaps  135: .Ed
                    136: .Pp
                    137: The
                    138: .Dq body
                    139: consists of zero or more arguments to the macro.
1.4       kristaps  140: .Pp
                    141: .Nm
                    142: has a primitive notion of multi-line scope for the following macros:
                    143: .Sq \&.TM ,
                    144: .Sq \&.SM ,
                    145: .Sq \&.SB ,
                    146: .Sq \&.BI ,
                    147: .Sq \&.IB ,
                    148: .Sq \&.BR ,
                    149: .Sq \&.RB ,
                    150: .Sq \&.R ,
                    151: .Sq \&.B ,
                    152: .Sq \&.I ,
                    153: .Sq \&.IR
                    154: and
                    155: .Sq \&.RI .
                    156: When these macros are invoked without arguments, the subsequent line is
                    157: considered a continuation of the macro.  Thus:
                    158: .Bd -literal -offset indent
                    159: \&.RI
                    160: foo
                    161: .Ed
                    162: .Pp
1.5       kristaps  163: is equivalent to
1.8       kristaps  164: .Sq \&.RI foo .
1.5       kristaps  165: If two consecutive lines exhibit the latter behaviour,
                    166: an error is raised.  Thus, the following is not acceptable:
1.4       kristaps  167: .Bd -literal -offset indent
                    168: \&.RI
                    169: \&.I
                    170: Hello, world.
                    171: .Ed
                    172: .Pp
                    173: The
                    174: .Sq \&.TP
1.5       kristaps  175: macro is similar, but does not need an empty argument line to trigger
                    176: the behaviour.
1.15      kristaps  177: .\" SECTION
1.1       kristaps  178: .Sh MACROS
                    179: This section contains a complete list of all
                    180: .Nm
1.5       kristaps  181: macros and corresponding number of arguments.
1.1       kristaps  182: .Pp
1.4       kristaps  183: .Bl -column "MacroX" "Arguments" -compact -offset indent
1.1       kristaps  184: .It Em Macro Ta Em Arguments
1.4       kristaps  185: .It \&.TH    Ta    >1, <6
                    186: .It \&.SH    Ta    >0
                    187: .It \&.SS    Ta    >0
1.1       kristaps  188: .It \&.TP    Ta    n
1.4       kristaps  189: .It \&.LP    Ta    0
                    190: .It \&.PP    Ta    0
                    191: .It \&.P     Ta    0
                    192: .It \&.IP    Ta    <3
                    193: .It \&.HP    Ta    <2
1.1       kristaps  194: .It \&.SM    Ta    n
                    195: .It \&.SB    Ta    n
                    196: .It \&.BI    Ta    n
                    197: .It \&.IB    Ta    n
                    198: .It \&.BR    Ta    n
                    199: .It \&.RB    Ta    n
                    200: .It \&.R     Ta    n
                    201: .It \&.B     Ta    n
                    202: .It \&.I     Ta    n
                    203: .It \&.IR    Ta    n
1.3       kristaps  204: .It \&.RI    Ta    n
1.1       kristaps  205: .El
1.7       kristaps  206: .Pp
                    207: Although not historically part of the
                    208: .Nm
                    209: system, the following macros are also supported:
                    210: .Pp
                    211: .Bl -column "MacroX" "Arguments" -compact -offset indent
                    212: .It Em Macro Ta Em Arguments
                    213: .It \&.br    Ta    0
1.8       kristaps  214: .It \&.i     Ta    n
1.7       kristaps  215: .El
1.8       kristaps  216: .Pp
                    217: These follow the same calling conventions as the above
                    218: .Nm
                    219: macros.
1.1       kristaps  220: .\" SECTION
                    221: .Sh SEE ALSO
1.6       kristaps  222: .Xr mandoc 1 ,
                    223: .Xr mandoc_char 7
1.1       kristaps  224: .\" SECTION
                    225: .Sh AUTHORS
                    226: The
                    227: .Nm
                    228: utility was written by
1.12      kristaps  229: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.1       kristaps  230: .\" SECTION
                    231: .Sh CAVEATS
                    232: Do not use this language.  Use
                    233: .Xr mdoc 7 ,
                    234: instead.

CVSweb