Return to roff.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/roff.7, Revision 1.1

1.1     ! kristaps    1: .\"    $Id$
        !             2: .\"
        !             3: .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
        !             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 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.
        !            16: .\"
        !            17: .Dd $Mdocdate$
        !            18: .Dt ROFF 7
        !            19: .Os
        !            20: .Sh NAME
        !            21: .Nm roff
        !            22: .Nd roff language reference
        !            23: .Sh DESCRIPTION
        !            24: The
        !            25: .Nm roff
        !            26: language is a general-purpose text-formatting language.  The purpose of
        !            27: this document is to consistently describe those language constructs
        !            28: accepted by the
        !            29: .Xr mandoc 1
        !            30: utility.  It is a work in progress.
        !            31: .Pp
        !            32: An
        !            33: .Nm
        !            34: document follows simple rules:  lines beginning with the control
        !            35: characters
        !            36: .Sq \.
        !            37: or
        !            38: .Sq \(aq
        !            39: are parsed for macros.  Other lines are interpreted within the scope of
        !            40: prior macros:
        !            41: .Bd -literal -offset indent
        !            42: \&.xx Macro lines change control state.
        !            43: Other lines are interpreted within the current state.
        !            44: .Ed
        !            45: .Sh LANGUAGE SYNTAX
        !            46: .Nm
        !            47: documents may contain only graphable 7-bit ASCII characters, the space
        !            48: character, and, in certain circumstances, the tab character.  All
        !            49: manuals must have
        !            50: .Ux
        !            51: line terminators.
        !            52: .Sh MACRO SYNTAX
        !            53: Macros are arbitrary in length and begin with a control character ,
        !            54: .Sq \.
        !            55: or
        !            56: .Sq \(aq ,
        !            57: at the beginning of the line.
        !            58: An arbitrary amount of whitespace may sit between the control character
        !            59: and the macro name.
        !            60: Thus, the following are equivalent:
        !            61: .Bd -literal -offset indent
        !            62: \&.if
        !            63: \&.\ \ \ \&if
        !            64: .Ed
        !            65: .Sh REFERENCE
        !            66: This section is a canonical reference of all macros, arranged
        !            67: alphabetically.
        !            68: .Ss \&if
        !            69: Begins a conditional.
        !            70: Has the following syntax:
        !            71: .Pp
        !            72: .Bd -literal -offset indent -compact
        !            73: \&.if COND \e{\e
        !            74: BODY...
        !            75: \&.\e}
        !            76: .Ed
        !            77: .Bd -literal -offset indent -compact
        !            78: \&.if COND \e{ BODY
        !            79: BODY...
        !            80: \&.\e}
        !            81: .Ed
        !            82: .Bd -literal -offset indent -compact
        !            83: \&.if COND \e
        !            84: BODY
        !            85: .Ed
        !            86: .Pp
        !            87: COND is a conditional (TODO: document).
        !            88: .Pp
        !            89: If the BODY section is begun by an escaped brace
        !            90: .Sq \e{ ,
        !            91: scope continues until a closing-brace macro
        !            92: .Sq \.\e} .
        !            93: If the BODY is not enclosed in braces, scope continues until the next
        !            94: macro or word.
        !            95: If the COND is followed by a BODY on the same line, whether after a
        !            96: brace or not, then macros
        !            97: .Em must
        !            98: begin with a control character.
        !            99: It is generally more intuitive, in this case, to write
        !           100: .Bd -literal -offset indent
        !           101: \&.if COND \e{\e
        !           102: \&.foo
        !           103: bar
        !           104: \&.\e}
        !           105: .Ed
        !           106: .Pp
        !           107: than having the macro follow as
        !           108: .Pp
        !           109: .D1 \&.if COND \e{ .foo
        !           110: .Pp
        !           111: The scope of a conditional is always parsed, but only executed if the
        !           112: conditional evaluates to true.
        !           113: .Pp
        !           114: Note that text subsequent a
        !           115: .Sq \e}
        !           116: is discarded.
        !           117: .Ss \&ig
        !           118: Ignore input until a
        !           119: .Sq \.\.
        !           120: macro is encountered on its own line.
        !           121: Note that text subsequent the
        !           122: .Sq \.\.
        !           123: is discarded.
        !           124: .Sh AUTHORS
        !           125: The
        !           126: .Nm
        !           127: reference was written by
        !           128: .An Kristaps Dzonsons Aq kristaps@bsd.lv .