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

Annotation of mandoc/man.7, Revision 1.21

1.21    ! kristaps    1: .\"    $Id: man.7,v 1.20 2009/07/20 13:45:11 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
        !            74: .Sq \e" ,
        !            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" ,
        !            78: is also ignored.
1.13      kristaps   79: .\" SUB-SECTION
1.1       kristaps   80: .Ss Special Characters
1.21    ! kristaps   81: Special characters may occur in both macro and free-form lines.
        !            82: Sequences begin with the escape character
1.2       kristaps   83: .Sq \e
1.20      kristaps   84: followed by either an open-parenthesis
1.1       kristaps   85: .Sq \&(
                     86: for two-character sequences; an open-bracket
                     87: .Sq \&[
                     88: for n-character sequences (terminated at a close-bracket
                     89: .Sq \&] ) ;
1.21    ! kristaps   90: or a single one-character sequence.  See
        !            91: .Xr mandoc_char 7
        !            92: for a complete list.  Examples include
        !            93: .Sq \e(em
        !            94: .Pq em-dash
        !            95: and
        !            96: .Sq \ee
        !            97: .Pq back-slash .
        !            98: .\" SUB-SECTION----------------------
        !            99: .Ss Text Decoration
        !           100: Terms may be text-decorated using the
1.18      kristaps  101: .Sq \ef
1.21    ! kristaps  102: escape followed by an indicator: B (bold), I, (italic), or P and R
        !           103: (Roman, or reset).
        !           104: .\" SUB-SECTION----------------------
1.17      kristaps  105: .Ss Whitespace
                    106: Unless specifically escaped, consecutive blocks of whitespace are pruned
                    107: from input.  These are later re-added, if applicable, by a front-end
                    108: utility such as
                    109: .Xr mandoc 1 .
1.1       kristaps  110: .\" SECTION
1.16      kristaps  111: .Sh STRUCTURE
                    112: Each
                    113: .Nm
                    114: document must contain contains at least the
                    115: .Sq \&.TH
                    116: macro describing the document's section and title.  It may occur
                    117: anywhere in the document, although conventionally, it appears as the
                    118: first macro.
                    119: .Pp
1.20      kristaps  120: Beyond the
1.16      kristaps  121: .Sq \&.TH ,
                    122: at least one macro or text node must appear in the document.
                    123: .\" SECTION
1.15      kristaps  124: .Sh SYNTAX
1.2       kristaps  125: Macros are one to three three characters in length and begin with a
1.4       kristaps  126: control character ,
                    127: .Sq \&. ,
1.2       kristaps  128: at the beginning of the line.  An arbitrary amount of whitespace may
                    129: sit between the control character and the macro name.  Thus,
1.4       kristaps  130: .Sq \&.PP
1.2       kristaps  131: and
                    132: .Sq \&.\ \ \ \&PP
                    133: are equivalent.
                    134: .Pp
1.20      kristaps  135: All
1.4       kristaps  136: .Nm
                    137: macros follow the same structural rules:
                    138: .Bd -literal -offset indent
1.20      kristaps  139: \&.YO \(lBbody...\(rB
1.1       kristaps  140: .Ed
                    141: .Pp
                    142: The
                    143: .Dq body
                    144: consists of zero or more arguments to the macro.
1.4       kristaps  145: .Pp
                    146: .Nm
1.20      kristaps  147: has a primitive notion of multi-line scope for the following macros:
1.4       kristaps  148: .Sq \&.TM ,
                    149: .Sq \&.SM ,
                    150: .Sq \&.SB ,
                    151: .Sq \&.BI ,
                    152: .Sq \&.IB ,
                    153: .Sq \&.BR ,
                    154: .Sq \&.RB ,
                    155: .Sq \&.R ,
                    156: .Sq \&.B ,
                    157: .Sq \&.I ,
1.20      kristaps  158: .Sq \&.IR
1.4       kristaps  159: and
                    160: .Sq \&.RI .
                    161: When these macros are invoked without arguments, the subsequent line is
                    162: considered a continuation of the macro.  Thus:
1.20      kristaps  163: .Bd -literal -offset indent
                    164: \&.RI
1.4       kristaps  165: foo
                    166: .Ed
                    167: .Pp
1.20      kristaps  168: is equivalent to
1.8       kristaps  169: .Sq \&.RI foo .
1.5       kristaps  170: If two consecutive lines exhibit the latter behaviour,
                    171: an error is raised.  Thus, the following is not acceptable:
1.20      kristaps  172: .Bd -literal -offset indent
                    173: \&.RI
                    174: \&.I
1.4       kristaps  175: Hello, world.
                    176: .Ed
                    177: .Pp
                    178: The
                    179: .Sq \&.TP
1.5       kristaps  180: macro is similar, but does not need an empty argument line to trigger
                    181: the behaviour.
1.15      kristaps  182: .\" SECTION
1.1       kristaps  183: .Sh MACROS
1.20      kristaps  184: This section contains a complete list of all
1.1       kristaps  185: .Nm
1.5       kristaps  186: macros and corresponding number of arguments.
1.1       kristaps  187: .Pp
1.4       kristaps  188: .Bl -column "MacroX" "Arguments" -compact -offset indent
1.1       kristaps  189: .It Em Macro Ta Em Arguments
1.4       kristaps  190: .It \&.TH    Ta    >1, <6
                    191: .It \&.SH    Ta    >0
                    192: .It \&.SS    Ta    >0
1.1       kristaps  193: .It \&.TP    Ta    n
1.4       kristaps  194: .It \&.LP    Ta    0
                    195: .It \&.PP    Ta    0
                    196: .It \&.P     Ta    0
                    197: .It \&.IP    Ta    <3
                    198: .It \&.HP    Ta    <2
1.1       kristaps  199: .It \&.SM    Ta    n
                    200: .It \&.SB    Ta    n
                    201: .It \&.BI    Ta    n
                    202: .It \&.IB    Ta    n
                    203: .It \&.BR    Ta    n
                    204: .It \&.RB    Ta    n
                    205: .It \&.R     Ta    n
                    206: .It \&.B     Ta    n
                    207: .It \&.I     Ta    n
                    208: .It \&.IR    Ta    n
1.3       kristaps  209: .It \&.RI    Ta    n
1.1       kristaps  210: .El
1.7       kristaps  211: .Pp
                    212: Although not historically part of the
                    213: .Nm
                    214: system, the following macros are also supported:
                    215: .Pp
                    216: .Bl -column "MacroX" "Arguments" -compact -offset indent
                    217: .It Em Macro Ta Em Arguments
                    218: .It \&.br    Ta    0
1.8       kristaps  219: .It \&.i     Ta    n
1.7       kristaps  220: .El
1.8       kristaps  221: .Pp
                    222: These follow the same calling conventions as the above
                    223: .Nm
                    224: macros.
1.1       kristaps  225: .\" SECTION
1.18      kristaps  226: .Sh COMPATIBILITY
                    227: See
                    228: .Xr mdoc 7
                    229: for groff compatibility notes.
                    230: .\" SECTION
1.1       kristaps  231: .Sh SEE ALSO
1.6       kristaps  232: .Xr mandoc 1 ,
                    233: .Xr mandoc_char 7
1.1       kristaps  234: .\" SECTION
                    235: .Sh AUTHORS
                    236: The
                    237: .Nm
1.20      kristaps  238: utility was written by
1.12      kristaps  239: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.1       kristaps  240: .\" SECTION
                    241: .Sh CAVEATS
                    242: Do not use this language.  Use
                    243: .Xr mdoc 7 ,
                    244: instead.

CVSweb