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

Annotation of mandoc/roff.7, Revision 1.39

1.39    ! kristaps    1: .\"    $Id: roff.7,v 1.38 2012/06/12 19:50:50 kristaps Exp $
1.1       kristaps    2: .\"
1.33      schwarze    3: .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
                      4: .\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>
1.1       kristaps    5: .\"
                      6: .\" Permission to use, copy, modify, and distribute this software for any
                      7: .\" purpose with or without fee is hereby granted, provided that the above
                      8: .\" copyright notice and this permission notice appear in all copies.
                      9: .\"
                     10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
                     11: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
                     12: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
                     13: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
                     14: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
                     15: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
                     16: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
                     17: .\"
1.39    ! kristaps   18: .Dd $Mdocdate: June 12 2012 $
1.1       kristaps   19: .Dt ROFF 7
                     20: .Os
                     21: .Sh NAME
                     22: .Nm roff
1.17      schwarze   23: .Nd roff language reference for mandoc
1.1       kristaps   24: .Sh DESCRIPTION
                     25: The
                     26: .Nm roff
1.17      schwarze   27: language is a general purpose text formatting language.
1.33      schwarze   28: Since traditional implementations of the
1.17      schwarze   29: .Xr mdoc 7
                     30: and
                     31: .Xr man 7
1.33      schwarze   32: manual formatting languages are based on it,
                     33: many real-world manuals use small numbers of
1.17      schwarze   34: .Nm
1.33      schwarze   35: requests intermixed with their
                     36: .Xr mdoc 7
                     37: or
                     38: .Xr man 7
                     39: code.
                     40: To properly format such manuals, the
1.1       kristaps   41: .Xr mandoc 1
1.33      schwarze   42: utility supports a tiny subset of
                     43: .Nm
                     44: requests.
                     45: Only these requests supported by
                     46: .Xr mandoc 1
                     47: are documented in the present manual,
                     48: together with the basic language syntax shared by
                     49: .Nm ,
                     50: .Xr mdoc 7 ,
                     51: and
                     52: .Xr man 7 .
                     53: For complete
                     54: .Nm
                     55: manuals, consult the
                     56: .Sx SEE ALSO
                     57: section.
1.1       kristaps   58: .Pp
1.33      schwarze   59: Input lines beginning with the control character
1.17      schwarze   60: .Sq \&.
1.33      schwarze   61: are parsed for requests and macros.
                     62: Such lines are called
                     63: .Dq request lines
1.1       kristaps   64: or
1.33      schwarze   65: .Dq macro lines ,
                     66: respectively.
                     67: Requests change the processing state and manipulate the formatting;
                     68: some macros also define the document structure and produce formatted
                     69: output.
                     70: The single quote
                     71: .Pq Qq \(aq
                     72: is accepted as an alternative control character,
                     73: treated by
                     74: .Xr mandoc 1
                     75: just like
                     76: .Ql \&.
                     77: .Pp
                     78: Lines not beginning with control characters are called
                     79: .Dq text lines .
                     80: They provide free-form text to be printed; the formatting of the text
                     81: depends on the respective processing context.
1.1       kristaps   82: .Sh LANGUAGE SYNTAX
                     83: .Nm
                     84: documents may contain only graphable 7-bit ASCII characters, the space
1.17      schwarze   85: character, and, in certain circumstances, the tab character.
1.38      kristaps   86: The backslash character
1.33      schwarze   87: .Sq \e
                     88: indicates the start of an escape sequence for
                     89: .Sx Comments ,
                     90: .Sx Special Characters ,
                     91: .Sx Predefined Strings ,
                     92: and
                     93: user-defined strings defined using the
                     94: .Sx ds
                     95: request.
                     96: .Ss Comments
                     97: Text following an escaped double-quote
                     98: .Sq \e\(dq ,
                     99: whether in a request, macro, or text line, is ignored to the end of the line.
                    100: A request line beginning with a control character and comment escape
                    101: .Sq \&.\e\(dq
                    102: is also ignored.
                    103: Furthermore, request lines with only a control character and optional
                    104: trailing whitespace are stripped from input.
                    105: .Pp
                    106: Examples:
                    107: .Bd -literal -offset indent -compact
                    108: \&.\e\(dq This is a comment line.
                    109: \&.\e\(dq The next line is ignored:
                    110: \&.
                    111: \&.Sh EXAMPLES \e\(dq This is a comment, too.
                    112: \&example text \e\(dq And so is this.
                    113: .Ed
                    114: .Ss Special Characters
                    115: Special characters are used to encode special glyphs and are rendered
                    116: differently across output media.
                    117: They may occur in request, macro, and text lines.
                    118: Sequences begin with the escape character
                    119: .Sq \e
                    120: followed by either an open-parenthesis
                    121: .Sq \&(
                    122: for two-character sequences; an open-bracket
                    123: .Sq \&[
                    124: for n-character sequences (terminated at a close-bracket
                    125: .Sq \&] ) ;
                    126: or a single one character sequence.
                    127: .Pp
                    128: Examples:
                    129: .Bl -tag -width Ds -offset indent -compact
                    130: .It Li \e(em
                    131: Two-letter em dash escape.
                    132: .It Li \ee
                    133: One-letter backslash escape.
                    134: .El
                    135: .Pp
                    136: See
1.17      schwarze  137: .Xr mandoc_char 7
1.33      schwarze  138: for a complete list.
                    139: .Ss Text Decoration
                    140: Terms may be text-decorated using the
                    141: .Sq \ef
                    142: escape followed by an indicator: B (bold), I (italic), R (regular), or P
                    143: (revert to previous mode).
                    144: A numerical representation 3, 2, or 1 (bold, italic, and regular,
                    145: respectively) may be used instead.
1.34      kristaps  146: The indicator or numerical representative may be preceded by C
                    147: (constant-width), which is ignored.
1.33      schwarze  148: .Pp
                    149: Examples:
                    150: .Bl -tag -width Ds -offset indent -compact
                    151: .It Li \efBbold\efR
                    152: Write in bold, then switch to regular font mode.
                    153: .It Li \efIitalic\efP
                    154: Write in italic, then return to previous font mode.
                    155: .El
                    156: .Pp
                    157: Text decoration is
                    158: .Em not
                    159: recommended for
                    160: .Xr mdoc 7 ,
                    161: which encourages semantic annotation.
                    162: .Ss Predefined Strings
                    163: Predefined strings, like
                    164: .Sx Special Characters ,
                    165: mark special output glyphs.
                    166: Predefined strings are escaped with the slash-asterisk,
                    167: .Sq \e* :
                    168: single-character
                    169: .Sq \e*X ,
                    170: two-character
                    171: .Sq \e*(XX ,
                    172: and N-character
                    173: .Sq \e*[N] .
                    174: .Pp
                    175: Examples:
                    176: .Bl -tag -width Ds -offset indent -compact
                    177: .It Li \e*(Am
                    178: Two-letter ampersand predefined string.
                    179: .It Li \e*q
                    180: One-letter double-quote predefined string.
                    181: .El
                    182: .Pp
                    183: Predefined strings are not recommended for use,
                    184: as they differ across implementations.
                    185: Those supported by
                    186: .Xr mandoc 1
                    187: are listed in
                    188: .Xr mandoc_char 7 .
                    189: Manuals using these predefined strings are almost certainly not portable.
                    190: .Ss Whitespace
                    191: Whitespace consists of the space character.
                    192: In text lines, whitespace is preserved within a line.
                    193: In request and macro lines, whitespace delimits arguments and is discarded.
                    194: .Pp
                    195: Unescaped trailing spaces are stripped from text line input unless in a
                    196: literal context.
                    197: In general, trailing whitespace on any input line is discouraged for
                    198: reasons of portability.
                    199: In the rare case that a blank character is needed at the end of an
                    200: input line, it may be forced by
                    201: .Sq \e\ \e& .
                    202: .Pp
                    203: Literal space characters can be produced in the output
                    204: using escape sequences.
                    205: In macro lines, they can also be included in arguments using quotation; see
                    206: .Sx MACRO SYNTAX
                    207: for details.
                    208: .Pp
                    209: Blank text lines, which may include whitespace, are only permitted
                    210: within literal contexts.
                    211: If the first character of a text line is a space, that line is printed
                    212: with a leading newline.
                    213: .Ss Scaling Widths
                    214: Many requests and macros support scaled widths for their arguments.
                    215: The syntax for a scaled width is
                    216: .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
                    217: where a decimal must be preceded or followed by at least one digit.
                    218: Negative numbers, while accepted, are truncated to zero.
                    219: .Pp
                    220: The following scaling units are accepted:
                    221: .Pp
                    222: .Bl -tag -width Ds -offset indent -compact
                    223: .It c
                    224: centimetre
                    225: .It i
                    226: inch
                    227: .It P
                    228: pica (~1/6 inch)
                    229: .It p
                    230: point (~1/72 inch)
                    231: .It f
                    232: synonym for
                    233: .Sq u
                    234: .It v
                    235: default vertical span
                    236: .It m
                    237: width of rendered
                    238: .Sq m
                    239: .Pq em
                    240: character
                    241: .It n
                    242: width of rendered
                    243: .Sq n
                    244: .Pq en
                    245: character
                    246: .It u
                    247: default horizontal span
                    248: .It M
                    249: mini-em (~1/100 em)
                    250: .El
                    251: .Pp
                    252: Using anything other than
                    253: .Sq m ,
                    254: .Sq n ,
                    255: .Sq u ,
                    256: or
                    257: .Sq v
                    258: is necessarily non-portable across output media.
                    259: See
                    260: .Sx COMPATIBILITY .
                    261: .Pp
                    262: If a scaling unit is not provided, the numerical value is interpreted
                    263: under the default rules of
                    264: .Sq v
                    265: for vertical spaces and
                    266: .Sq u
                    267: for horizontal ones.
                    268: .Pp
                    269: Examples:
                    270: .Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact
                    271: .It Li \&.Bl -tag -width 2i
                    272: two-inch tagged list indentation in
                    273: .Xr mdoc 7
                    274: .It Li \&.HP 2i
                    275: two-inch tagged list indentation in
                    276: .Xr man 7
                    277: .It Li \&.sp 2v
                    278: two vertical spaces
                    279: .El
                    280: .Ss Sentence Spacing
                    281: Each sentence should terminate at the end of an input line.
                    282: By doing this, a formatter will be able to apply the proper amount of
                    283: spacing after the end of sentence (unescaped) period, exclamation mark,
                    284: or question mark followed by zero or more non-sentence closing
                    285: delimiters
                    286: .Po
                    287: .Sq \&) ,
                    288: .Sq \&] ,
                    289: .Sq \&' ,
                    290: .Sq \&"
                    291: .Pc .
                    292: .Pp
                    293: The proper spacing is also intelligently preserved if a sentence ends at
                    294: the boundary of a macro line.
                    295: .Pp
                    296: Examples:
                    297: .Bd -literal -offset indent -compact
                    298: Do not end sentences mid-line like this.  Instead,
                    299: end a sentence like this.
                    300: A macro would end like this:
                    301: \&.Xr mandoc 1 \&.
                    302: .Ed
1.17      schwarze  303: .Sh REQUEST SYNTAX
                    304: A request or macro line consists of:
                    305: .Pp
                    306: .Bl -enum -compact
                    307: .It
                    308: the control character
                    309: .Sq \&.
1.1       kristaps  310: or
1.17      schwarze  311: .Sq \(aq
                    312: at the beginning of the line,
                    313: .It
                    314: optionally an arbitrary amount of whitespace,
                    315: .It
                    316: the name of the request or the macro, which is one word of arbitrary
                    317: length, terminated by whitespace,
                    318: .It
                    319: and zero or more arguments delimited by whitespace.
                    320: .El
                    321: .Pp
                    322: Thus, the following request lines are all equivalent:
1.1       kristaps  323: .Bd -literal -offset indent
1.17      schwarze  324: \&.ig end
                    325: \&.ig    end
                    326: \&.   ig end
1.1       kristaps  327: .Ed
1.24      schwarze  328: .Sh MACRO SYNTAX
1.33      schwarze  329: Macros are provided by the
                    330: .Xr mdoc 7
                    331: and
                    332: .Xr man 7
                    333: languages and can be defined by the
1.24      schwarze  334: .Sx \&de
                    335: request.
                    336: When called, they follow the same syntax as requests, except that
                    337: macro arguments may optionally be quoted by enclosing them
                    338: in double quote characters
                    339: .Pq Sq \(dq .
1.33      schwarze  340: Quoted text, even if it contains whitespace or would cause
                    341: a macro invocation when unquoted, is always considered literal text.
                    342: Inside quoted text, pairs of double quote characters
                    343: .Pq Sq Qq
                    344: resolve to single double quote characters.
                    345: .Pp
1.32      kristaps  346: To be recognised as the beginning of a quoted argument, the opening
1.24      schwarze  347: quote character must be preceded by a space character.
                    348: A quoted argument extends to the next double quote character that is not
                    349: part of a pair, or to the end of the input line, whichever comes earlier.
                    350: Leaving out the terminating double quote character at the end of the line
                    351: is discouraged.
                    352: For clarity, if more arguments follow on the same input line,
                    353: it is recommended to follow the terminating double quote character
                    354: by a space character; in case the next character after the terminating
                    355: double quote character is anything else, it is regarded as the beginning
                    356: of the next, unquoted argument.
                    357: .Pp
                    358: Both in quoted and unquoted arguments, pairs of backslashes
                    359: .Pq Sq \e\e
                    360: resolve to single backslashes.
                    361: In unquoted arguments, space characters can alternatively be included
                    362: by preceding them with a backslash
                    363: .Pq Sq \e\~ ,
                    364: but quoting is usually better for clarity.
1.33      schwarze  365: .Pp
                    366: Examples:
                    367: .Bl -tag -width Ds -offset indent -compact
                    368: .It Li .Fn strlen \(dqconst char *s\(dq
                    369: Group arguments
                    370: .Qq const char *s
                    371: into one function argument.
                    372: If unspecified,
                    373: .Qq const ,
                    374: .Qq char ,
                    375: and
                    376: .Qq *s
                    377: would be considered separate arguments.
                    378: .It Li .Op \(dqFl a\(dq
                    379: Consider
                    380: .Qq \&Fl a
                    381: as literal text instead of a flag macro.
                    382: .El
1.15      kristaps  383: .Sh REQUEST REFERENCE
1.17      schwarze  384: The
1.15      kristaps  385: .Xr mandoc 1
                    386: .Nm
1.32      kristaps  387: parser recognises the following requests.
1.17      schwarze  388: Note that the
1.15      kristaps  389: .Nm
1.17      schwarze  390: language defines many more requests not implemented in
1.15      kristaps  391: .Xr mandoc 1 .
                    392: .Ss \&ad
                    393: Set line adjustment mode.
                    394: This line-scoped request is intended to have one argument to select
1.32      kristaps  395: normal, left, right, or centre adjustment for subsequent text.
1.15      kristaps  396: Currently, it is ignored including its arguments,
                    397: and the number of arguments is not checked.
1.3       kristaps  398: .Ss \&am
1.15      kristaps  399: Append to a macro definition.
                    400: The syntax of this request is the same as that of
                    401: .Sx \&de .
                    402: It is currently ignored by
                    403: .Xr mandoc 1 ,
                    404: as are its children.
1.3       kristaps  405: .Ss \&ami
1.15      kristaps  406: Append to a macro definition, specifying the macro name indirectly.
                    407: The syntax of this request is the same as that of
                    408: .Sx \&dei .
                    409: It is currently ignored by
                    410: .Xr mandoc 1 ,
                    411: as are its children.
1.3       kristaps  412: .Ss \&am1
1.15      kristaps  413: Append to a macro definition, switching roff compatibility mode off
                    414: during macro execution.
                    415: The syntax of this request is the same as that of
                    416: .Sx \&de1 .
                    417: It is currently ignored by
                    418: .Xr mandoc 1 ,
                    419: as are its children.
1.39    ! kristaps  420: .Ss \&cc
        !           421: Changes the control character.
        !           422: Its syntax is as follows:
        !           423: .Bd -literal -offset indent
        !           424: .Pf . Cm \&cc Op Ar c
        !           425: .Ed
        !           426: .Pp
        !           427: If
        !           428: .Ar c
        !           429: is not specified, the control character is reset to
        !           430: .Sq \&. .
        !           431: Trailing characters are ignored.
1.3       kristaps  432: .Ss \&de
1.17      schwarze  433: Define a
1.15      kristaps  434: .Nm
                    435: macro.
                    436: Its syntax can be either
                    437: .Bd -literal -offset indent
                    438: .Pf . Cm \&de Ar name
                    439: .Ar macro definition
                    440: \&..
                    441: .Ed
                    442: .Pp
                    443: or
                    444: .Bd -literal -offset indent
                    445: .Pf . Cm \&de Ar name Ar end
                    446: .Ar macro definition
                    447: .Pf . Ar end
                    448: .Ed
                    449: .Pp
                    450: Both forms define or redefine the macro
                    451: .Ar name
                    452: to represent the
                    453: .Ar macro definition ,
                    454: which may consist of one or more input lines, including the newline
                    455: characters terminating each line, optionally containing calls to
                    456: .Nm
                    457: requests,
                    458: .Nm
                    459: macros or high-level macros like
                    460: .Xr man 7
                    461: or
                    462: .Xr mdoc 7
                    463: macros, whichever applies to the document in question.
                    464: .Pp
                    465: Specifying a custom
                    466: .Ar end
                    467: macro works in the same way as for
                    468: .Sx \&ig ;
                    469: namely, the call to
                    470: .Sq Pf . Ar end
                    471: first ends the
                    472: .Ar macro definition ,
                    473: and after that, it is also evaluated as a
                    474: .Nm
                    475: request or
                    476: .Nm
                    477: macro, but not as a high-level macro.
                    478: .Pp
1.17      schwarze  479: The macro can be invoked later using the syntax
1.15      kristaps  480: .Pp
                    481: .D1 Pf . Ar name Op Ar argument Op Ar argument ...
                    482: .Pp
1.24      schwarze  483: Regarding argument parsing, see
                    484: .Sx MACRO SYNTAX
                    485: above.
1.15      kristaps  486: .Pp
1.17      schwarze  487: The line invoking the macro will be replaced
1.15      kristaps  488: in the input stream by the
                    489: .Ar macro definition ,
                    490: replacing all occurrences of
                    491: .No \e\e$ Ns Ar N ,
1.17      schwarze  492: where
1.15      kristaps  493: .Ar N
                    494: is a digit, by the
                    495: .Ar N Ns th Ar argument .
                    496: For example,
                    497: .Bd -literal -offset indent
                    498: \&.de ZN
                    499: \efI\e^\e\e$1\e^\efP\e\e$2
                    500: \&..
                    501: \&.ZN XtFree .
                    502: .Ed
                    503: .Pp
                    504: produces
                    505: .Pp
                    506: .D1 \efI\e^XtFree\e^\efP.
                    507: .Pp
                    508: in the input stream, and thus in the output: \fI\^XtFree\^\fP.
                    509: .Pp
1.17      schwarze  510: Since macros and user-defined strings share a common string table,
1.15      kristaps  511: defining a macro
                    512: .Ar name
                    513: clobbers the user-defined string
                    514: .Ar name ,
                    515: and the
                    516: .Ar macro definition
                    517: can also be printed using the
                    518: .Sq \e*
                    519: string interpolation syntax described below
                    520: .Sx ds ,
                    521: but this is rarely useful because every macro definition contains at least
                    522: one explicit newline character.
1.16      schwarze  523: .Pp
                    524: In order to prevent endless recursion, both groff and
                    525: .Xr mandoc 1
                    526: limit the stack depth for expanding macros and strings
                    527: to a large, but finite number.
                    528: Do not rely on the exact value of this limit.
1.3       kristaps  529: .Ss \&dei
1.17      schwarze  530: Define a
1.15      kristaps  531: .Nm
                    532: macro, specifying the macro name indirectly.
1.17      schwarze  533: The syntax of this request is the same as that of
1.15      kristaps  534: .Sx \&de .
                    535: It is currently ignored by
                    536: .Xr mandoc 1 ,
                    537: as are its children.
                    538: .Ss \&de1
1.17      schwarze  539: Define a
1.15      kristaps  540: .Nm
                    541: macro that will be executed with
                    542: .Nm
                    543: compatibility mode switched off during macro execution.
                    544: This is a GNU extension not available in traditional
                    545: .Nm
                    546: implementations and not even in older versions of groff.
                    547: Since
                    548: .Xr mandoc 1
                    549: does not implement
                    550: .Nm
1.17      schwarze  551: compatibility mode at all, it handles this request as an alias for
1.15      kristaps  552: .Sx \&de .
1.6       schwarze  553: .Ss \&ds
1.15      kristaps  554: Define a user-defined string.
1.13      kristaps  555: Its syntax is as follows:
                    556: .Pp
1.15      kristaps  557: .D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
1.13      kristaps  558: .Pp
                    559: The
1.15      kristaps  560: .Ar name
1.13      kristaps  561: and
1.15      kristaps  562: .Ar string
                    563: arguments are space-separated.
                    564: If the
                    565: .Ar string
                    566: begins with a double-quote character, that character will not be part
                    567: of the string.
                    568: All remaining characters on the input line form the
                    569: .Ar string ,
                    570: including whitespace and double-quote characters, even trailing ones.
                    571: .Pp
1.13      kristaps  572: The
1.15      kristaps  573: .Ar string
                    574: can be interpolated into subsequent text by using
                    575: .No \e* Ns Bq Ar name
                    576: for a
                    577: .Ar name
                    578: of arbitrary length, or \e*(NN or \e*N if the length of
                    579: .Ar name
                    580: is two or one characters, respectively.
1.17      schwarze  581: Interpolation can be prevented by escaping the leading backslash;
                    582: that is, an asterisk preceded by an even number of backslashes
                    583: does not trigger string interpolation.
1.15      kristaps  584: .Pp
                    585: Since user-defined strings and macros share a common string table,
                    586: defining a string
                    587: .Ar name
1.17      schwarze  588: clobbers the macro
1.15      kristaps  589: .Ar name ,
                    590: and the
                    591: .Ar name
                    592: used for defining a string can also be invoked as a macro,
                    593: in which case the following input line will be appended to the
                    594: .Ar string ,
                    595: forming a new input line passed to the
                    596: .Nm
                    597: parser.
                    598: For example,
                    599: .Bd -literal -offset indent
                    600: \&.ds badidea .S
                    601: \&.badidea
                    602: H SYNOPSIS
                    603: .Ed
                    604: .Pp
                    605: invokes the
                    606: .Cm SH
                    607: macro when used in a
                    608: .Xr man 7
                    609: document.
                    610: Such abuse is of course strongly discouraged.
1.5       kristaps  611: .Ss \&el
                    612: The
                    613: .Qq else
                    614: half of an if/else conditional.
                    615: Pops a result off the stack of conditional evaluations pushed by
                    616: .Sx \&ie
                    617: and uses it as its conditional.
                    618: If no stack entries are present (e.g., due to no prior
                    619: .Sx \&ie
                    620: calls)
                    621: then false is assumed.
1.17      schwarze  622: The syntax of this request is similar to
1.5       kristaps  623: .Sx \&if
                    624: except that the conditional is missing.
1.27      kristaps  625: .Ss \&EN
                    626: End an equation block.
                    627: See
                    628: .Sx \&EQ .
                    629: .Ss \&EQ
                    630: Begin an equation block.
                    631: See
                    632: .Xr eqn 7
                    633: for a description of the equation language.
1.15      kristaps  634: .Ss \&hy
                    635: Set automatic hyphenation mode.
                    636: This line-scoped request is currently ignored.
1.5       kristaps  637: .Ss \&ie
                    638: The
                    639: .Qq if
                    640: half of an if/else conditional.
                    641: The result of the conditional is pushed into a stack used by subsequent
                    642: invocations of
                    643: .Sx \&el ,
                    644: which may be separated by any intervening input (or not exist at all).
                    645: Its syntax is equivalent to
                    646: .Sx \&if .
1.1       kristaps  647: .Ss \&if
1.7       schwarze  648: Begins a conditional.
                    649: Right now, the conditional evaluates to true
                    650: if and only if it starts with the letter
                    651: .Sy n ,
1.17      schwarze  652: indicating processing in nroff style as opposed to troff style.
1.3       kristaps  653: If a conditional is false, its children are not processed, but are
                    654: syntactically interpreted to preserve the integrity of the input
                    655: document.
                    656: Thus,
                    657: .Pp
1.17      schwarze  658: .D1 \&.if t .ig
1.3       kristaps  659: .Pp
                    660: will discard the
                    661: .Sq \&.ig ,
                    662: which may lead to interesting results, but
                    663: .Pp
1.17      schwarze  664: .D1 \&.if t .if t \e{\e
1.3       kristaps  665: .Pp
                    666: will continue to syntactically interpret to the block close of the final
                    667: conditional.
                    668: Sub-conditionals, in this case, obviously inherit the truth value of
                    669: the parent.
1.17      schwarze  670: This request has the following syntax:
                    671: .Bd -literal -offset indent
1.1       kristaps  672: \&.if COND \e{\e
                    673: BODY...
                    674: \&.\e}
                    675: .Ed
1.17      schwarze  676: .Bd -literal -offset indent
1.1       kristaps  677: \&.if COND \e{ BODY
1.2       kristaps  678: BODY... \e}
                    679: .Ed
1.17      schwarze  680: .Bd -literal -offset indent
1.2       kristaps  681: \&.if COND \e{ BODY
1.1       kristaps  682: BODY...
                    683: \&.\e}
                    684: .Ed
1.17      schwarze  685: .Bd -literal -offset indent
1.1       kristaps  686: \&.if COND \e
                    687: BODY
                    688: .Ed
                    689: .Pp
1.9       kristaps  690: COND is a conditional statement.
                    691: roff allows for complicated conditionals; mandoc is much simpler.
                    692: At this time, mandoc supports only
                    693: .Sq n ,
                    694: evaluating to true;
                    695: and
                    696: .Sq t ,
                    697: .Sq e ,
                    698: and
                    699: .Sq o ,
                    700: evaluating to false.
                    701: All other invocations are read up to the next end of line or space and
                    702: evaluate as false.
1.1       kristaps  703: .Pp
                    704: If the BODY section is begun by an escaped brace
                    705: .Sq \e{ ,
1.17      schwarze  706: scope continues until a closing-brace escape sequence
1.1       kristaps  707: .Sq \.\e} .
1.17      schwarze  708: If the BODY is not enclosed in braces, scope continues until
                    709: the end of the line.
1.1       kristaps  710: If the COND is followed by a BODY on the same line, whether after a
1.17      schwarze  711: brace or not, then requests and macros
1.1       kristaps  712: .Em must
                    713: begin with a control character.
                    714: It is generally more intuitive, in this case, to write
                    715: .Bd -literal -offset indent
                    716: \&.if COND \e{\e
                    717: \&.foo
                    718: bar
                    719: \&.\e}
                    720: .Ed
                    721: .Pp
1.17      schwarze  722: than having the request or macro follow as
1.1       kristaps  723: .Pp
                    724: .D1 \&.if COND \e{ .foo
                    725: .Pp
                    726: The scope of a conditional is always parsed, but only executed if the
                    727: conditional evaluates to true.
                    728: .Pp
1.29      kristaps  729: Note that the
1.1       kristaps  730: .Sq \e}
1.29      kristaps  731: is converted into a zero-width escape sequence if not passed as a
                    732: standalone macro
                    733: .Sq \&.\e} .
                    734: For example,
                    735: .Pp
                    736: .D1 \&.Fl a \e} b
                    737: .Pp
                    738: will result in
1.8       kristaps  739: .Sq \e}
1.29      kristaps  740: being considered an argument of the
                    741: .Sq \&Fl
                    742: macro.
1.1       kristaps  743: .Ss \&ig
1.2       kristaps  744: Ignore input.
1.15      kristaps  745: Its syntax can be either
                    746: .Bd -literal -offset indent
                    747: .Pf . Cm \&ig
                    748: .Ar ignored text
1.2       kristaps  749: \&..
                    750: .Ed
1.15      kristaps  751: .Pp
                    752: or
                    753: .Bd -literal -offset indent
                    754: .Pf . Cm \&ig Ar end
                    755: .Ar ignored text
                    756: .Pf . Ar end
1.2       kristaps  757: .Ed
                    758: .Pp
                    759: In the first case, input is ignored until a
                    760: .Sq \&..
1.17      schwarze  761: request is encountered on its own line.
1.15      kristaps  762: In the second case, input is ignored until the specified
                    763: .Sq Pf . Ar end
                    764: macro is encountered.
                    765: Do not use the escape character
1.2       kristaps  766: .Sq \e
1.15      kristaps  767: anywhere in the definition of
                    768: .Ar end ;
                    769: it would cause very strange behaviour.
                    770: .Pp
                    771: When the
                    772: .Ar end
                    773: macro is a roff request or a roff macro, like in
1.2       kristaps  774: .Pp
                    775: .D1 \&.ig if
                    776: .Pp
                    777: the subsequent invocation of
                    778: .Sx \&if
1.15      kristaps  779: will first terminate the
                    780: .Ar ignored text ,
                    781: then be invoked as usual.
                    782: Otherwise, it only terminates the
                    783: .Ar ignored text ,
                    784: and arguments following it or the
                    785: .Sq \&..
1.17      schwarze  786: request are discarded.
1.15      kristaps  787: .Ss \&ne
                    788: Declare the need for the specified minimum vertical space
                    789: before the next trap or the bottom of the page.
                    790: This line-scoped request is currently ignored.
                    791: .Ss \&nh
                    792: Turn off automatic hyphenation mode.
                    793: This line-scoped request is currently ignored.
1.6       schwarze  794: .Ss \&rm
                    795: Remove a request, macro or string.
1.15      kristaps  796: This request is intended to have one argument,
1.6       schwarze  797: the name of the request, macro or string to be undefined.
                    798: Currently, it is ignored including its arguments,
                    799: and the number of arguments is not checked.
1.10      kristaps  800: .Ss \&nr
                    801: Define a register.
                    802: A register is an arbitrary string value that defines some sort of state,
                    803: which influences parsing and/or formatting.
                    804: Its syntax is as follows:
                    805: .Pp
1.15      kristaps  806: .D1 Pf \. Cm \&nr Ar name Ar value
1.10      kristaps  807: .Pp
                    808: The
1.15      kristaps  809: .Ar value
1.10      kristaps  810: may, at the moment, only be an integer.
1.15      kristaps  811: So far, only the following register
                    812: .Ar name
                    813: is recognised:
1.10      kristaps  814: .Bl -tag -width Ds
                    815: .It Cm nS
                    816: If set to a positive integer value, certain
                    817: .Xr mdoc 7
1.17      schwarze  818: macros will behave in the same way as in the
1.10      kristaps  819: .Em SYNOPSIS
1.11      kristaps  820: section.
1.17      schwarze  821: If set to 0, these macros will behave in the same way as outside the
                    822: .Em SYNOPSIS
                    823: section, even when called within the
1.10      kristaps  824: .Em SYNOPSIS
1.17      schwarze  825: section itself.
                    826: Note that starting a new
1.11      kristaps  827: .Xr mdoc 7
1.17      schwarze  828: section with the
                    829: .Cm \&Sh
                    830: macro will reset this register.
1.10      kristaps  831: .El
1.26      schwarze  832: .Ss \&ns
                    833: Turn on no-space mode.
                    834: This line-scoped request is intended to take no arguments.
                    835: Currently, it is ignored including its arguments,
                    836: and the number of arguments is not checked.
                    837: .Ss \&ps
                    838: Change point size.
                    839: This line-scoped request is intended to take one numerical argument.
                    840: Currently, it is ignored including its arguments,
                    841: and the number of arguments is not checked.
1.15      kristaps  842: .Ss \&so
                    843: Include a source file.
                    844: Its syntax is as follows:
                    845: .Pp
                    846: .D1 Pf \. Cm \&so Ar file
                    847: .Pp
                    848: The
                    849: .Ar file
                    850: will be read and its contents processed as input in place of the
                    851: .Sq \&.so
                    852: request line.
1.28      kristaps  853: To avoid inadvertent inclusion of unrelated files,
1.15      kristaps  854: .Xr mandoc 1
                    855: only accepts relative paths not containing the strings
                    856: .Qq ../
                    857: and
                    858: .Qq /.. .
1.37      schwarze  859: .Pp
                    860: This request requires
                    861: .Xr man 1
                    862: to change to the right directory before calling
                    863: .Xr mandoc 1 ,
                    864: per convention to the root of the manual tree.
                    865: Typical usage looks like:
                    866: .Pp
                    867: .Dl \&.so man3/Xcursor.3
                    868: .Pp
                    869: As the whole concept is rather fragile, the use of
                    870: .Sx \&so
                    871: is discouraged.
                    872: Use
                    873: .Xr ln 1
                    874: instead.
1.26      schwarze  875: .Ss \&ta
                    876: Set tab stops.
                    877: This line-scoped request can take an arbitrary number of arguments.
                    878: Currently, it is ignored including its arguments.
1.6       schwarze  879: .Ss \&tr
                    880: Output character translation.
1.30      kristaps  881: Its syntax is as follows:
                    882: .Pp
                    883: .D1 Pf \. Cm \&tr Ar [ab]+
                    884: .Pp
                    885: Pairs of
                    886: .Ar ab
                    887: characters are replaced
                    888: .Ar ( a
                    889: for
                    890: .Ar b ) .
                    891: Replacement (or origin) characters may also be character escapes; thus,
                    892: .Pp
                    893: .Dl tr \e(xx\e(yy
                    894: .Pp
                    895: replaces all invocations of \e(xx with \e(yy.
1.20      kristaps  896: .Ss \&T&
                    897: Re-start a table layout, retaining the options of the prior table
                    898: invocation.
                    899: See
                    900: .Sx \&TS .
                    901: .Ss \&TE
                    902: End a table context.
                    903: See
                    904: .Sx \&TS .
                    905: .Ss \&TS
                    906: Begin a table, which formats input in aligned rows and columns.
1.23      kristaps  907: See
                    908: .Xr tbl 7
                    909: for a description of the tbl language.
1.2       kristaps  910: .Sh COMPATIBILITY
                    911: This section documents compatibility between mandoc and other other
1.17      schwarze  912: .Nm
                    913: implementations, at this time limited to GNU troff
1.2       kristaps  914: .Pq Qq groff .
                    915: The term
                    916: .Qq historic groff
1.17      schwarze  917: refers to groff version 1.15.
1.2       kristaps  918: .Pp
                    919: .Bl -dash -compact
1.10      kristaps  920: .It
1.27      kristaps  921: In mandoc, the
                    922: .Sx \&EQ ,
                    923: .Sx \&TE ,
                    924: .Sx \&TS ,
                    925: and
                    926: .Sx \&T& ,
                    927: macros are considered regular macros.
                    928: In all other
                    929: .Nm
                    930: implementations, these are special macros that must be specified without
                    931: spacing between the control character (which must be a period) and the
                    932: macro name.
                    933: .It
1.10      kristaps  934: The
                    935: .Cm nS
1.17      schwarze  936: register is only compatible with OpenBSD's groff-1.15.
1.2       kristaps  937: .It
1.17      schwarze  938: Historic groff did not accept white-space before a custom
                    939: .Ar end
                    940: macro for the
1.2       kristaps  941: .Sx \&ig
1.17      schwarze  942: request.
1.4       kristaps  943: .It
                    944: The
                    945: .Sx \&if
                    946: and family would print funny white-spaces with historic groff when
1.17      schwarze  947: using the next-line syntax.
1.2       kristaps  948: .El
1.17      schwarze  949: .Sh SEE ALSO
                    950: .Xr mandoc 1 ,
1.27      kristaps  951: .Xr eqn 7 ,
1.17      schwarze  952: .Xr man 7 ,
                    953: .Xr mandoc_char 7 ,
1.23      kristaps  954: .Xr mdoc 7 ,
                    955: .Xr tbl 7
1.17      schwarze  956: .Rs
                    957: .%A Joseph F. Ossanna
                    958: .%A Brian W. Kernighan
                    959: .%I AT&T Bell Laboratories
                    960: .%T Troff User's Manual
                    961: .%R Computing Science Technical Report
                    962: .%N 54
                    963: .%C Murray Hill, New Jersey
                    964: .%D 1976 and 1992
                    965: .%U http://www.kohala.com/start/troff/cstr54.ps
                    966: .Re
                    967: .Rs
                    968: .%A Joseph F. Ossanna
                    969: .%A Brian W. Kernighan
                    970: .%A Gunnar Ritter
                    971: .%T Heirloom Documentation Tools Nroff/Troff User's Manual
                    972: .%D September 17, 2007
                    973: .%U http://heirloom.sourceforge.net/doctools/troff.pdf
                    974: .Re
                    975: .Sh HISTORY
1.35      kristaps  976: The RUNOFF typesetting system, whose input forms the basis for
1.17      schwarze  977: .Nm ,
1.35      kristaps  978: was written in MAD and FAP for the CTSS operating system by Jerome E.
                    979: Saltzer in 1964.
                    980: Doug McIlroy rewrote it in BCPL in 1969, renaming it
                    981: .Nm .
                    982: Dennis M. Ritchie rewrote McIlroy's
1.36      schwarze  983: .Nm
                    984: in PDP-11 assembly for
1.35      kristaps  985: .At v1 ,
                    986: Joseph F. Ossanna improved roff and renamed it nroff
                    987: for
                    988: .At v2 ,
                    989: then ported nroff to C as troff, which Brian W. Kernighan released with
                    990: .At v7 .
                    991: In 1989, James Clarke re-implemented troff in C++, naming it groff.
1.1       kristaps  992: .Sh AUTHORS
1.15      kristaps  993: .An -nosplit
1.31      kristaps  994: This
1.1       kristaps  995: .Nm
                    996: reference was written by
1.31      kristaps  997: .An Kristaps Dzonsons ,
                    998: .Mt kristaps@bsd.lv ;
1.15      kristaps  999: and
1.31      kristaps 1000: .An Ingo Schwarze ,
                   1001: .Mt schwarze@openbsd.org .

CVSweb