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

Annotation of mandoc/roff.7, Revision 1.43

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

CVSweb