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

Annotation of mandoc/man.7, Revision 1.9

1.9     ! kristaps    1: .\" $Id: man.7,v 1.8 2009/04/05 16:34:22 kristaps Exp $
1.1       kristaps    2: .\"
                      3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
                      4: .\"
                      5: .\" Permission to use, copy, modify, and distribute this software for any
                      6: .\" purpose with or without fee is hereby granted, provided that the
                      7: .\" above copyright notice and this permission notice appear in all
                      8: .\" copies.
                      9: .\"
                     10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
                     11: .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
                     12: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
                     13: .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
                     14: .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
                     15: .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
                     16: .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
                     17: .\" PERFORMANCE OF THIS SOFTWARE.
                     18: .\"
                     19: .Dd $Mdocdate$
1.9     ! kristaps   20: .Dt MAN 7
1.1       kristaps   21: .Os
                     22: .\" SECTION
                     23: .Sh NAME
                     24: .Nm man
                     25: .Nd man language reference
                     26: .\" SECTION
                     27: .Sh DESCRIPTION
                     28: The
                     29: .Nm man
                     30: language was historically used to format
                     31: .Ux
1.8       kristaps   32: manuals.  This reference document describes the syntax and structure of
                     33: this language.
1.1       kristaps   34: .Pp
1.8       kristaps   35: .Em \&Do not
1.1       kristaps   36: use
                     37: .Nm
                     38: to write your manuals.  Use the
                     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
                     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
                     57: documents may contain only graphable 7-bit ASCII characters and the
                     58: space character
                     59: .Sq \  .
                     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
                     75: .Ss Special Characters
                     76: Special character sequences begin with the escape character
1.2       kristaps   77: .Sq \e
1.1       kristaps   78: followed by either an open-parenthesis
                     79: .Sq \&(
                     80: for two-character sequences; an open-bracket
                     81: .Sq \&[
                     82: for n-character sequences (terminated at a close-bracket
                     83: .Sq \&] ) ;
                     84: or a single one-character sequence.
                     85: .Pp
                     86: Characters may alternatively be escaped by a slash-asterisk,
1.2       kristaps   87: .Sq \e* ,
1.1       kristaps   88: with the same combinations as described above.  This form is deprecated.
                     89: .\" SECTION
                     90: .Sh STRUCTURE
1.2       kristaps   91: Macros are one to three three characters in length and begin with a
1.4       kristaps   92: control character ,
                     93: .Sq \&. ,
1.2       kristaps   94: at the beginning of the line.  An arbitrary amount of whitespace may
                     95: sit between the control character and the macro name.  Thus,
1.4       kristaps   96: .Sq \&.PP
1.2       kristaps   97: and
                     98: .Sq \&.\ \ \ \&PP
                     99: are equivalent.
                    100: .Pp
1.4       kristaps  101: All
                    102: .Nm
                    103: macros follow the same structural rules:
                    104: .Bd -literal -offset indent
                    105: \&.YO \(lBbody...\(rB
1.1       kristaps  106: .Ed
                    107: .Pp
                    108: The
                    109: .Dq body
                    110: consists of zero or more arguments to the macro.
1.4       kristaps  111: .Pp
                    112: .Nm
                    113: has a primitive notion of multi-line scope for the following macros:
                    114: .Sq \&.TM ,
                    115: .Sq \&.SM ,
                    116: .Sq \&.SB ,
                    117: .Sq \&.BI ,
                    118: .Sq \&.IB ,
                    119: .Sq \&.BR ,
                    120: .Sq \&.RB ,
                    121: .Sq \&.R ,
                    122: .Sq \&.B ,
                    123: .Sq \&.I ,
                    124: .Sq \&.IR
                    125: and
                    126: .Sq \&.RI .
                    127: When these macros are invoked without arguments, the subsequent line is
                    128: considered a continuation of the macro.  Thus:
                    129: .Bd -literal -offset indent
                    130: \&.RI
                    131: foo
                    132: .Ed
                    133: .Pp
1.5       kristaps  134: is equivalent to
1.8       kristaps  135: .Sq \&.RI foo .
1.5       kristaps  136: If two consecutive lines exhibit the latter behaviour,
                    137: an error is raised.  Thus, the following is not acceptable:
1.4       kristaps  138: .Bd -literal -offset indent
                    139: \&.RI
                    140: \&.I
                    141: Hello, world.
                    142: .Ed
                    143: .Pp
                    144: The
                    145: .Sq \&.TP
1.5       kristaps  146: macro is similar, but does not need an empty argument line to trigger
                    147: the behaviour.
1.1       kristaps  148: .\" PARAGRAPH
                    149: .Sh MACROS
                    150: This section contains a complete list of all
                    151: .Nm
1.5       kristaps  152: macros and corresponding number of arguments.
1.1       kristaps  153: .Pp
1.4       kristaps  154: .Bl -column "MacroX" "Arguments" -compact -offset indent
1.1       kristaps  155: .It Em Macro Ta Em Arguments
1.4       kristaps  156: .It \&.TH    Ta    >1, <6
                    157: .It \&.SH    Ta    >0
                    158: .It \&.SS    Ta    >0
1.1       kristaps  159: .It \&.TP    Ta    n
1.4       kristaps  160: .It \&.LP    Ta    0
                    161: .It \&.PP    Ta    0
                    162: .It \&.P     Ta    0
                    163: .It \&.IP    Ta    <3
                    164: .It \&.HP    Ta    <2
1.1       kristaps  165: .It \&.SM    Ta    n
                    166: .It \&.SB    Ta    n
                    167: .It \&.BI    Ta    n
                    168: .It \&.IB    Ta    n
                    169: .It \&.BR    Ta    n
                    170: .It \&.RB    Ta    n
                    171: .It \&.R     Ta    n
                    172: .It \&.B     Ta    n
                    173: .It \&.I     Ta    n
                    174: .It \&.IR    Ta    n
1.3       kristaps  175: .It \&.RI    Ta    n
1.1       kristaps  176: .El
1.7       kristaps  177: .Pp
                    178: Although not historically part of the
                    179: .Nm
                    180: system, the following macros are also supported:
                    181: .Pp
                    182: .Bl -column "MacroX" "Arguments" -compact -offset indent
                    183: .It Em Macro Ta Em Arguments
                    184: .It \&.br    Ta    0
1.8       kristaps  185: .It \&.i     Ta    n
1.7       kristaps  186: .El
1.8       kristaps  187: .Pp
                    188: These follow the same calling conventions as the above
                    189: .Nm
                    190: macros.
1.1       kristaps  191: .\" SECTION
                    192: .Sh SEE ALSO
1.6       kristaps  193: .Xr mandoc 1 ,
                    194: .Xr mandoc_char 7
1.1       kristaps  195: .\" SECTION
                    196: .Sh AUTHORS
                    197: The
                    198: .Nm
                    199: utility was written by
                    200: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
                    201: .\" SECTION
                    202: .Sh CAVEATS
                    203: Do not use this language.  Use
                    204: .Xr mdoc 7 ,
                    205: instead.

CVSweb