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

Annotation of mandoc/man.7, Revision 1.4

1.4     ! kristaps    1: .\" $Id: man.7,v 1.3 2009/03/26 14:38:11 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$
                     20: .Dt man 7
                     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
                     32: manuals.  In this reference document, we describe the syntax and
                     33: structure of the
                     34: .Nm
                     35: language.
                     36: .Pp
1.4     ! kristaps   37: .Em \&Do not ever
1.1       kristaps   38: use
                     39: .Nm
                     40: to write your manuals.  Use the
                     41: .Xr mdoc 7
                     42: language, instead.
                     43: .\" PARAGRAPH
                     44: .Pp
                     45: An
                     46: .Nm
                     47: document follows simple rules:  lines beginning with the control
                     48: character
1.2       kristaps   49: .Sq \&.
1.1       kristaps   50: are parsed for macros.  Other lines are interpreted within the scope of
                     51: prior macros:
1.4     ! kristaps   52: .Bd -literal -offset indent
1.1       kristaps   53: \&.SH Macro lines change control state.
                     54: Other lines are interpreted within the current state.
                     55: .Ed
                     56: .\" PARAGRAPH
                     57: .Pp
                     58: Macros are character sequences whose structural rules are described
                     59: later in this document.
                     60: .\" SECTION
                     61: .Sh INPUT ENCODING
                     62: .Nm
                     63: documents may contain only graphable 7-bit ASCII characters and the
                     64: space character
                     65: .Sq \  .
                     66: All manuals must have
                     67: .Sq \en
                     68: line termination.
                     69: .Pp
                     70: Blank lines are acceptable; where found, the output will also assert a
                     71: vertical space.
1.4     ! kristaps   72: .Pp
        !            73: The
        !            74: .Sq \ec
        !            75: escape is common in historical
        !            76: .Nm
        !            77: documents; if encountered at the end of a word, it ensures that the
        !            78: subsequent word isn't off-set by whitespace.
1.1       kristaps   79: .\" SUB-SECTION
                     80: .Ss Special Characters
                     81: Special character sequences begin with the escape character
1.2       kristaps   82: .Sq \e
1.1       kristaps   83: followed by either an open-parenthesis
                     84: .Sq \&(
                     85: for two-character sequences; an open-bracket
                     86: .Sq \&[
                     87: for n-character sequences (terminated at a close-bracket
                     88: .Sq \&] ) ;
                     89: or a single one-character sequence.
                     90: .Pp
                     91: Characters may alternatively be escaped by a slash-asterisk,
1.2       kristaps   92: .Sq \e* ,
1.1       kristaps   93: with the same combinations as described above.  This form is deprecated.
                     94: .Pp
1.2       kristaps   95: The
                     96: .Xr mdoc 7
                     97: contains a table of all available escapes.
1.1       kristaps   98: .\" SECTION
                     99: .Sh STRUCTURE
1.2       kristaps  100: Macros are one to three three characters in length and begin with a
1.4     ! kristaps  101: control character ,
        !           102: .Sq \&. ,
1.2       kristaps  103: at the beginning of the line.  An arbitrary amount of whitespace may
                    104: sit between the control character and the macro name.  Thus,
1.4     ! kristaps  105: .Sq \&.PP
1.2       kristaps  106: and
                    107: .Sq \&.\ \ \ \&PP
                    108: are equivalent.
                    109: .Pp
1.4     ! kristaps  110: All
        !           111: .Nm
        !           112: macros follow the same structural rules:
        !           113: .Bd -literal -offset indent
        !           114: \&.YO \(lBbody...\(rB
1.1       kristaps  115: .Ed
                    116: .Pp
                    117: The
                    118: .Dq body
                    119: consists of zero or more arguments to the macro.
1.4     ! kristaps  120: .Pp
        !           121: .Nm
        !           122: has a primitive notion of multi-line scope for the following macros:
        !           123: .Sq \&.TM ,
        !           124: .Sq \&.SM ,
        !           125: .Sq \&.SB ,
        !           126: .Sq \&.BI ,
        !           127: .Sq \&.IB ,
        !           128: .Sq \&.BR ,
        !           129: .Sq \&.RB ,
        !           130: .Sq \&.R ,
        !           131: .Sq \&.B ,
        !           132: .Sq \&.I ,
        !           133: .Sq \&.IR
        !           134: and
        !           135: .Sq \&.RI .
        !           136: When these macros are invoked without arguments, the subsequent line is
        !           137: considered a continuation of the macro.  Thus:
        !           138: .Bd -literal -offset indent
        !           139: \&.RI foo
        !           140: .Ed
        !           141: .Pp
        !           142: and
        !           143: .Bd -literal -offset indent
        !           144: \&.RI
        !           145: foo
        !           146: .Ed
        !           147: .Pp
        !           148: are equivalent.  If two consecutive lines exhibit the latter behaviour,
        !           149: an error is raised.  Thus, the following is acceptable:
        !           150: .Bd -literal -offset indent
        !           151: \&.RI
        !           152: \&.I Hello, world.
        !           153: foo
        !           154: .Ed
        !           155: .Pp
        !           156: The following, however, is not:
        !           157: .Bd -literal -offset indent
        !           158: \&.RI
        !           159: \&.I
        !           160: Hello, world.
        !           161: .Ed
        !           162: .Pp
        !           163: The
        !           164: .Sq \&.TP
        !           165: macro has similar behaviour, but does not need an empty argument line in
        !           166: order to trigger scope.
1.1       kristaps  167: .\" PARAGRAPH
                    168: .Sh MACROS
                    169: This section contains a complete list of all
                    170: .Nm
                    171: macros, arranged alphabetically, with the number of arguments.
                    172: .Pp
1.4     ! kristaps  173: .Bl -column "MacroX" "Arguments" -compact -offset indent
1.1       kristaps  174: .It Em Macro Ta Em Arguments
1.4     ! kristaps  175: .It \&.TH    Ta    >1, <6
        !           176: .It \&.SH    Ta    >0
        !           177: .It \&.SS    Ta    >0
1.1       kristaps  178: .It \&.TP    Ta    n
1.4     ! kristaps  179: .It \&.LP    Ta    0
        !           180: .It \&.PP    Ta    0
        !           181: .It \&.P     Ta    0
        !           182: .It \&.IP    Ta    <3
        !           183: .It \&.HP    Ta    <2
1.1       kristaps  184: .It \&.SM    Ta    n
                    185: .It \&.SB    Ta    n
                    186: .It \&.BI    Ta    n
                    187: .It \&.IB    Ta    n
                    188: .It \&.BR    Ta    n
                    189: .It \&.RB    Ta    n
                    190: .It \&.R     Ta    n
                    191: .It \&.B     Ta    n
                    192: .It \&.I     Ta    n
                    193: .It \&.IR    Ta    n
1.3       kristaps  194: .It \&.RI    Ta    n
1.1       kristaps  195: .El
                    196: .\" SECTION
                    197: .Sh SEE ALSO
                    198: .Xr mandoc 1
                    199: .\" SECTION
                    200: .Sh AUTHORS
                    201: The
                    202: .Nm
                    203: utility was written by
                    204: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
                    205: .\" SECTION
                    206: .Sh CAVEATS
                    207: Do not use this language.  Use
                    208: .Xr mdoc 7 ,
                    209: instead.

CVSweb