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

Annotation of mandoc/roff.7, Revision 1.61

1.61    ! schwarze    1: .\"    $Id: roff.7,v 1.60 2014/12/02 10:08:06 schwarze Exp $
1.1       kristaps    2: .\"
1.46      schwarze    3: .\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
1.47      schwarze    4: .\" Copyright (c) 2010, 2011, 2013, 2014 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.61    ! schwarze   18: .Dd $Mdocdate: December 2 2014 $
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.46      schwarze   35: requests and escape sequences intermixed with their
1.33      schwarze   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
1.46      schwarze   44: requests and escapes.
                     45: Only these requests and escapes supported by
1.33      schwarze   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
1.46      schwarze   88: indicates the start of an escape sequence, used for example for
1.33      schwarze   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.
1.46      schwarze   96: For a listing of escape sequences, consult the
                     97: .Sx ESCAPE SEQUENCE REFERENCE
                     98: below.
1.33      schwarze   99: .Ss Comments
                    100: Text following an escaped double-quote
                    101: .Sq \e\(dq ,
                    102: whether in a request, macro, or text line, is ignored to the end of the line.
                    103: A request line beginning with a control character and comment escape
                    104: .Sq \&.\e\(dq
                    105: is also ignored.
                    106: Furthermore, request lines with only a control character and optional
                    107: trailing whitespace are stripped from input.
                    108: .Pp
                    109: Examples:
                    110: .Bd -literal -offset indent -compact
                    111: \&.\e\(dq This is a comment line.
                    112: \&.\e\(dq The next line is ignored:
                    113: \&.
                    114: \&.Sh EXAMPLES \e\(dq This is a comment, too.
                    115: \&example text \e\(dq And so is this.
                    116: .Ed
                    117: .Ss Special Characters
                    118: Special characters are used to encode special glyphs and are rendered
                    119: differently across output media.
                    120: They may occur in request, macro, and text lines.
                    121: Sequences begin with the escape character
                    122: .Sq \e
                    123: followed by either an open-parenthesis
                    124: .Sq \&(
                    125: for two-character sequences; an open-bracket
                    126: .Sq \&[
                    127: for n-character sequences (terminated at a close-bracket
                    128: .Sq \&] ) ;
                    129: or a single one character sequence.
                    130: .Pp
                    131: Examples:
                    132: .Bl -tag -width Ds -offset indent -compact
                    133: .It Li \e(em
                    134: Two-letter em dash escape.
                    135: .It Li \ee
                    136: One-letter backslash escape.
                    137: .El
                    138: .Pp
                    139: See
1.17      schwarze  140: .Xr mandoc_char 7
1.33      schwarze  141: for a complete list.
                    142: .Ss Text Decoration
                    143: Terms may be text-decorated using the
                    144: .Sq \ef
                    145: escape followed by an indicator: B (bold), I (italic), R (regular), or P
                    146: (revert to previous mode).
                    147: A numerical representation 3, 2, or 1 (bold, italic, and regular,
                    148: respectively) may be used instead.
1.34      kristaps  149: The indicator or numerical representative may be preceded by C
                    150: (constant-width), which is ignored.
1.33      schwarze  151: .Pp
1.42      schwarze  152: The two-character indicator
                    153: .Sq BI
                    154: requests a font that is both bold and italic.
                    155: It may not be portable to old roff implementations.
                    156: .Pp
1.33      schwarze  157: Examples:
                    158: .Bl -tag -width Ds -offset indent -compact
                    159: .It Li \efBbold\efR
1.42      schwarze  160: Write in \fBbold\fP, then switch to regular font mode.
1.33      schwarze  161: .It Li \efIitalic\efP
1.42      schwarze  162: Write in \fIitalic\fP, then return to previous font mode.
                    163: .It Li \ef(BIbold italic\efP
                    164: Write in \f(BIbold italic\fP, then return to previous font mode.
1.33      schwarze  165: .El
                    166: .Pp
                    167: Text decoration is
                    168: .Em not
                    169: recommended for
                    170: .Xr mdoc 7 ,
                    171: which encourages semantic annotation.
                    172: .Ss Predefined Strings
                    173: Predefined strings, like
                    174: .Sx Special Characters ,
                    175: mark special output glyphs.
                    176: Predefined strings are escaped with the slash-asterisk,
                    177: .Sq \e* :
                    178: single-character
                    179: .Sq \e*X ,
                    180: two-character
                    181: .Sq \e*(XX ,
                    182: and N-character
                    183: .Sq \e*[N] .
                    184: .Pp
                    185: Examples:
                    186: .Bl -tag -width Ds -offset indent -compact
                    187: .It Li \e*(Am
                    188: Two-letter ampersand predefined string.
                    189: .It Li \e*q
                    190: One-letter double-quote predefined string.
                    191: .El
                    192: .Pp
                    193: Predefined strings are not recommended for use,
                    194: as they differ across implementations.
                    195: Those supported by
                    196: .Xr mandoc 1
                    197: are listed in
                    198: .Xr mandoc_char 7 .
                    199: Manuals using these predefined strings are almost certainly not portable.
                    200: .Ss Whitespace
                    201: Whitespace consists of the space character.
                    202: In text lines, whitespace is preserved within a line.
                    203: In request and macro lines, whitespace delimits arguments and is discarded.
                    204: .Pp
                    205: Unescaped trailing spaces are stripped from text line input unless in a
                    206: literal context.
                    207: In general, trailing whitespace on any input line is discouraged for
                    208: reasons of portability.
                    209: In the rare case that a blank character is needed at the end of an
                    210: input line, it may be forced by
                    211: .Sq \e\ \e& .
                    212: .Pp
                    213: Literal space characters can be produced in the output
                    214: using escape sequences.
                    215: In macro lines, they can also be included in arguments using quotation; see
                    216: .Sx MACRO SYNTAX
                    217: for details.
                    218: .Pp
                    219: Blank text lines, which may include whitespace, are only permitted
                    220: within literal contexts.
                    221: If the first character of a text line is a space, that line is printed
                    222: with a leading newline.
                    223: .Ss Scaling Widths
                    224: Many requests and macros support scaled widths for their arguments.
                    225: The syntax for a scaled width is
                    226: .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
                    227: where a decimal must be preceded or followed by at least one digit.
                    228: Negative numbers, while accepted, are truncated to zero.
                    229: .Pp
                    230: The following scaling units are accepted:
                    231: .Pp
                    232: .Bl -tag -width Ds -offset indent -compact
                    233: .It c
                    234: centimetre
                    235: .It i
                    236: inch
                    237: .It P
                    238: pica (~1/6 inch)
                    239: .It p
                    240: point (~1/72 inch)
                    241: .It f
1.56      kristaps  242: scale
1.33      schwarze  243: .Sq u
1.56      kristaps  244: by 65536
1.33      schwarze  245: .It v
                    246: default vertical span
                    247: .It m
                    248: width of rendered
                    249: .Sq m
                    250: .Pq em
                    251: character
                    252: .It n
                    253: width of rendered
                    254: .Sq n
                    255: .Pq en
                    256: character
                    257: .It u
1.56      kristaps  258: default horizontal span for the terminal
1.33      schwarze  259: .It M
                    260: mini-em (~1/100 em)
                    261: .El
                    262: .Pp
                    263: Using anything other than
                    264: .Sq m ,
                    265: .Sq n ,
                    266: or
                    267: .Sq v
                    268: is necessarily non-portable across output media.
                    269: See
                    270: .Sx COMPATIBILITY .
                    271: .Pp
                    272: If a scaling unit is not provided, the numerical value is interpreted
                    273: under the default rules of
                    274: .Sq v
                    275: for vertical spaces and
                    276: .Sq u
                    277: for horizontal ones.
                    278: .Pp
                    279: Examples:
                    280: .Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact
                    281: .It Li \&.Bl -tag -width 2i
                    282: two-inch tagged list indentation in
                    283: .Xr mdoc 7
                    284: .It Li \&.HP 2i
                    285: two-inch tagged list indentation in
                    286: .Xr man 7
                    287: .It Li \&.sp 2v
                    288: two vertical spaces
                    289: .El
                    290: .Ss Sentence Spacing
                    291: Each sentence should terminate at the end of an input line.
                    292: By doing this, a formatter will be able to apply the proper amount of
                    293: spacing after the end of sentence (unescaped) period, exclamation mark,
                    294: or question mark followed by zero or more non-sentence closing
                    295: delimiters
                    296: .Po
                    297: .Sq \&) ,
                    298: .Sq \&] ,
                    299: .Sq \&' ,
                    300: .Sq \&"
                    301: .Pc .
                    302: .Pp
                    303: The proper spacing is also intelligently preserved if a sentence ends at
                    304: the boundary of a macro line.
                    305: .Pp
                    306: Examples:
                    307: .Bd -literal -offset indent -compact
                    308: Do not end sentences mid-line like this.  Instead,
                    309: end a sentence like this.
                    310: A macro would end like this:
                    311: \&.Xr mandoc 1 \&.
                    312: .Ed
1.17      schwarze  313: .Sh REQUEST SYNTAX
                    314: A request or macro line consists of:
                    315: .Pp
                    316: .Bl -enum -compact
                    317: .It
                    318: the control character
                    319: .Sq \&.
1.1       kristaps  320: or
1.17      schwarze  321: .Sq \(aq
                    322: at the beginning of the line,
                    323: .It
                    324: optionally an arbitrary amount of whitespace,
                    325: .It
                    326: the name of the request or the macro, which is one word of arbitrary
                    327: length, terminated by whitespace,
                    328: .It
                    329: and zero or more arguments delimited by whitespace.
                    330: .El
                    331: .Pp
                    332: Thus, the following request lines are all equivalent:
1.1       kristaps  333: .Bd -literal -offset indent
1.17      schwarze  334: \&.ig end
                    335: \&.ig    end
                    336: \&.   ig end
1.1       kristaps  337: .Ed
1.24      schwarze  338: .Sh MACRO SYNTAX
1.33      schwarze  339: Macros are provided by the
                    340: .Xr mdoc 7
                    341: and
                    342: .Xr man 7
                    343: languages and can be defined by the
1.24      schwarze  344: .Sx \&de
                    345: request.
                    346: When called, they follow the same syntax as requests, except that
                    347: macro arguments may optionally be quoted by enclosing them
                    348: in double quote characters
                    349: .Pq Sq \(dq .
1.33      schwarze  350: Quoted text, even if it contains whitespace or would cause
                    351: a macro invocation when unquoted, is always considered literal text.
                    352: Inside quoted text, pairs of double quote characters
                    353: .Pq Sq Qq
                    354: resolve to single double quote characters.
                    355: .Pp
1.32      kristaps  356: To be recognised as the beginning of a quoted argument, the opening
1.24      schwarze  357: quote character must be preceded by a space character.
                    358: A quoted argument extends to the next double quote character that is not
                    359: part of a pair, or to the end of the input line, whichever comes earlier.
                    360: Leaving out the terminating double quote character at the end of the line
                    361: is discouraged.
                    362: For clarity, if more arguments follow on the same input line,
                    363: it is recommended to follow the terminating double quote character
                    364: by a space character; in case the next character after the terminating
                    365: double quote character is anything else, it is regarded as the beginning
                    366: of the next, unquoted argument.
                    367: .Pp
                    368: Both in quoted and unquoted arguments, pairs of backslashes
                    369: .Pq Sq \e\e
                    370: resolve to single backslashes.
                    371: In unquoted arguments, space characters can alternatively be included
                    372: by preceding them with a backslash
                    373: .Pq Sq \e\~ ,
                    374: but quoting is usually better for clarity.
1.33      schwarze  375: .Pp
                    376: Examples:
                    377: .Bl -tag -width Ds -offset indent -compact
                    378: .It Li .Fn strlen \(dqconst char *s\(dq
                    379: Group arguments
                    380: .Qq const char *s
                    381: into one function argument.
                    382: If unspecified,
                    383: .Qq const ,
                    384: .Qq char ,
                    385: and
                    386: .Qq *s
                    387: would be considered separate arguments.
                    388: .It Li .Op \(dqFl a\(dq
                    389: Consider
                    390: .Qq \&Fl a
                    391: as literal text instead of a flag macro.
                    392: .El
1.15      kristaps  393: .Sh REQUEST REFERENCE
1.17      schwarze  394: The
1.15      kristaps  395: .Xr mandoc 1
                    396: .Nm
1.32      kristaps  397: parser recognises the following requests.
1.17      schwarze  398: Note that the
1.15      kristaps  399: .Nm
1.17      schwarze  400: language defines many more requests not implemented in
1.15      kristaps  401: .Xr mandoc 1 .
                    402: .Ss \&ad
                    403: Set line adjustment mode.
                    404: This line-scoped request is intended to have one argument to select
1.32      kristaps  405: normal, left, right, or centre adjustment for subsequent text.
1.15      kristaps  406: Currently, it is ignored including its arguments,
                    407: and the number of arguments is not checked.
1.3       kristaps  408: .Ss \&am
1.15      kristaps  409: Append to a macro definition.
                    410: The syntax of this request is the same as that of
                    411: .Sx \&de .
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 .
1.3       kristaps  416: .Ss \&am1
1.15      kristaps  417: Append to a macro definition, switching roff compatibility mode off
                    418: during macro execution.
                    419: The syntax of this request is the same as that of
                    420: .Sx \&de1 .
1.55      schwarze  421: Since
                    422: .Xr mandoc 1
                    423: does not implement
                    424: .Nm
                    425: compatibility mode at all, it handles this request as an alias for
                    426: .Sx \&am .
1.47      schwarze  427: .Ss \&as
                    428: Append to a user-defined string.
                    429: The syntax of this request is the same as that of
                    430: .Sx \&ds .
                    431: If a user-defined string with the specified name does not yet exist,
                    432: it is set to the empty string before appending.
1.39      kristaps  433: .Ss \&cc
                    434: Changes the control character.
                    435: Its syntax is as follows:
                    436: .Bd -literal -offset indent
                    437: .Pf . Cm \&cc Op Ar c
                    438: .Ed
                    439: .Pp
                    440: If
                    441: .Ar c
                    442: is not specified, the control character is reset to
                    443: .Sq \&. .
                    444: Trailing characters are ignored.
1.47      schwarze  445: .Ss \&ce
                    446: Center some lines.
                    447: This line-scoped request is intended to take one integer argument,
                    448: specifying how many lines to center.
                    449: Currently, it is ignored including its arguments, and the number
                    450: of arguments is not checked.
1.3       kristaps  451: .Ss \&de
1.17      schwarze  452: Define a
1.15      kristaps  453: .Nm
                    454: macro.
                    455: Its syntax can be either
                    456: .Bd -literal -offset indent
                    457: .Pf . Cm \&de Ar name
                    458: .Ar macro definition
                    459: \&..
                    460: .Ed
                    461: .Pp
                    462: or
                    463: .Bd -literal -offset indent
                    464: .Pf . Cm \&de Ar name Ar end
                    465: .Ar macro definition
                    466: .Pf . Ar end
                    467: .Ed
                    468: .Pp
                    469: Both forms define or redefine the macro
                    470: .Ar name
                    471: to represent the
                    472: .Ar macro definition ,
                    473: which may consist of one or more input lines, including the newline
                    474: characters terminating each line, optionally containing calls to
                    475: .Nm
                    476: requests,
                    477: .Nm
                    478: macros or high-level macros like
                    479: .Xr man 7
                    480: or
                    481: .Xr mdoc 7
                    482: macros, whichever applies to the document in question.
                    483: .Pp
                    484: Specifying a custom
                    485: .Ar end
                    486: macro works in the same way as for
                    487: .Sx \&ig ;
                    488: namely, the call to
                    489: .Sq Pf . Ar end
                    490: first ends the
                    491: .Ar macro definition ,
                    492: and after that, it is also evaluated as a
                    493: .Nm
                    494: request or
                    495: .Nm
                    496: macro, but not as a high-level macro.
                    497: .Pp
1.17      schwarze  498: The macro can be invoked later using the syntax
1.15      kristaps  499: .Pp
                    500: .D1 Pf . Ar name Op Ar argument Op Ar argument ...
                    501: .Pp
1.24      schwarze  502: Regarding argument parsing, see
                    503: .Sx MACRO SYNTAX
                    504: above.
1.15      kristaps  505: .Pp
1.17      schwarze  506: The line invoking the macro will be replaced
1.15      kristaps  507: in the input stream by the
                    508: .Ar macro definition ,
                    509: replacing all occurrences of
                    510: .No \e\e$ Ns Ar N ,
1.17      schwarze  511: where
1.15      kristaps  512: .Ar N
                    513: is a digit, by the
                    514: .Ar N Ns th Ar argument .
                    515: For example,
                    516: .Bd -literal -offset indent
                    517: \&.de ZN
                    518: \efI\e^\e\e$1\e^\efP\e\e$2
                    519: \&..
                    520: \&.ZN XtFree .
                    521: .Ed
                    522: .Pp
                    523: produces
                    524: .Pp
                    525: .D1 \efI\e^XtFree\e^\efP.
                    526: .Pp
                    527: in the input stream, and thus in the output: \fI\^XtFree\^\fP.
                    528: .Pp
1.17      schwarze  529: Since macros and user-defined strings share a common string table,
1.15      kristaps  530: defining a macro
                    531: .Ar name
                    532: clobbers the user-defined string
                    533: .Ar name ,
                    534: and the
                    535: .Ar macro definition
                    536: can also be printed using the
                    537: .Sq \e*
                    538: string interpolation syntax described below
                    539: .Sx ds ,
                    540: but this is rarely useful because every macro definition contains at least
                    541: one explicit newline character.
1.16      schwarze  542: .Pp
                    543: In order to prevent endless recursion, both groff and
                    544: .Xr mandoc 1
                    545: limit the stack depth for expanding macros and strings
1.61    ! schwarze  546: to a large, but finite number, and
        !           547: .Xr mandoc 1
        !           548: also limits the length of the expanded input line.
        !           549: Do not rely on the exact values of these limits.
1.3       kristaps  550: .Ss \&dei
1.17      schwarze  551: Define a
1.15      kristaps  552: .Nm
                    553: macro, specifying the macro name indirectly.
1.17      schwarze  554: The syntax of this request is the same as that of
1.15      kristaps  555: .Sx \&de .
1.55      schwarze  556: The request
                    557: .Pp
                    558: .D1 Pf . Cm \&dei Ar name Op Ar end
                    559: .Pp
                    560: has the same effect as:
                    561: .Pp
                    562: .D1 Pf . Cm \&de No \e* Ns Bo Ar name Bc Op \e* Ns Bq Ar end
1.15      kristaps  563: .Ss \&de1
1.17      schwarze  564: Define a
1.15      kristaps  565: .Nm
                    566: macro that will be executed with
                    567: .Nm
                    568: compatibility mode switched off during macro execution.
                    569: This is a GNU extension not available in traditional
                    570: .Nm
                    571: implementations and not even in older versions of groff.
                    572: Since
                    573: .Xr mandoc 1
                    574: does not implement
                    575: .Nm
1.17      schwarze  576: compatibility mode at all, it handles this request as an alias for
1.15      kristaps  577: .Sx \&de .
1.6       schwarze  578: .Ss \&ds
1.15      kristaps  579: Define a user-defined string.
1.13      kristaps  580: Its syntax is as follows:
                    581: .Pp
1.15      kristaps  582: .D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
1.13      kristaps  583: .Pp
                    584: The
1.15      kristaps  585: .Ar name
1.13      kristaps  586: and
1.15      kristaps  587: .Ar string
                    588: arguments are space-separated.
                    589: If the
                    590: .Ar string
                    591: begins with a double-quote character, that character will not be part
                    592: of the string.
                    593: All remaining characters on the input line form the
                    594: .Ar string ,
                    595: including whitespace and double-quote characters, even trailing ones.
                    596: .Pp
1.13      kristaps  597: The
1.15      kristaps  598: .Ar string
                    599: can be interpolated into subsequent text by using
                    600: .No \e* Ns Bq Ar name
                    601: for a
                    602: .Ar name
                    603: of arbitrary length, or \e*(NN or \e*N if the length of
                    604: .Ar name
                    605: is two or one characters, respectively.
1.17      schwarze  606: Interpolation can be prevented by escaping the leading backslash;
                    607: that is, an asterisk preceded by an even number of backslashes
                    608: does not trigger string interpolation.
1.15      kristaps  609: .Pp
                    610: Since user-defined strings and macros share a common string table,
                    611: defining a string
                    612: .Ar name
1.17      schwarze  613: clobbers the macro
1.15      kristaps  614: .Ar name ,
                    615: and the
                    616: .Ar name
                    617: used for defining a string can also be invoked as a macro,
                    618: in which case the following input line will be appended to the
                    619: .Ar string ,
                    620: forming a new input line passed to the
                    621: .Nm
                    622: parser.
                    623: For example,
                    624: .Bd -literal -offset indent
                    625: \&.ds badidea .S
                    626: \&.badidea
                    627: H SYNOPSIS
                    628: .Ed
                    629: .Pp
                    630: invokes the
                    631: .Cm SH
                    632: macro when used in a
                    633: .Xr man 7
                    634: document.
                    635: Such abuse is of course strongly discouraged.
1.5       kristaps  636: .Ss \&el
                    637: The
                    638: .Qq else
                    639: half of an if/else conditional.
                    640: Pops a result off the stack of conditional evaluations pushed by
                    641: .Sx \&ie
                    642: and uses it as its conditional.
                    643: If no stack entries are present (e.g., due to no prior
                    644: .Sx \&ie
                    645: calls)
                    646: then false is assumed.
1.17      schwarze  647: The syntax of this request is similar to
1.5       kristaps  648: .Sx \&if
                    649: except that the conditional is missing.
1.27      kristaps  650: .Ss \&EN
                    651: End an equation block.
                    652: See
                    653: .Sx \&EQ .
                    654: .Ss \&EQ
                    655: Begin an equation block.
                    656: See
                    657: .Xr eqn 7
                    658: for a description of the equation language.
1.43      schwarze  659: .Ss \&fam
                    660: Change the font family.
                    661: This line-scoped request is intended to have one argument specifying
                    662: the font family to be selected.
                    663: It is a groff extension, and currently, it is ignored including its
                    664: arguments, and the number of arguments is not checked.
1.49      schwarze  665: .Ss \&ft
                    666: Change the font.
                    667: Its syntax is as follows:
                    668: .Pp
                    669: .D1 Pf . Cm \&ft Op Ar font
                    670: .Pp
                    671: The following
                    672: .Ar font
                    673: arguments are supported:
                    674: .Bl -tag -width 4n -offset indent
                    675: .It Cm B , BI , 3 , 4
                    676: switches to
                    677: .Sy bold
                    678: font
                    679: .It Cm I , 2
                    680: switches to
                    681: .Em underlined
                    682: font
                    683: .It Cm R , CW , 1
                    684: switches to normal font
                    685: .It Cm P No "or no argument"
                    686: switches back to the previous font
                    687: .El
                    688: .Pp
                    689: This request takes effect only locally, may be overridden by macros
                    690: and escape sequences, and is only supported in
                    691: .Xr man 7
                    692: for now.
1.44      schwarze  693: .Ss \&hw
                    694: Specify hyphenation points in words.
                    695: This line-scoped request is currently ignored.
1.15      kristaps  696: .Ss \&hy
                    697: Set automatic hyphenation mode.
                    698: This line-scoped request is currently ignored.
1.5       kristaps  699: .Ss \&ie
                    700: The
                    701: .Qq if
                    702: half of an if/else conditional.
                    703: The result of the conditional is pushed into a stack used by subsequent
                    704: invocations of
                    705: .Sx \&el ,
                    706: which may be separated by any intervening input (or not exist at all).
                    707: Its syntax is equivalent to
                    708: .Sx \&if .
1.1       kristaps  709: .Ss \&if
1.7       schwarze  710: Begins a conditional.
1.48      schwarze  711: This request has the following syntax:
                    712: .Bd -literal -offset indent
                    713: \&.if COND BODY
                    714: .Ed
                    715: .Bd -literal -offset indent
                    716: \&.if COND \e{BODY
                    717: BODY...\e}
                    718: .Ed
                    719: .Bd -literal -offset indent
                    720: \&.if COND \e{\e
                    721: BODY...
                    722: \&.\e}
                    723: .Ed
                    724: .Pp
                    725: COND is a conditional statement.
                    726: Currently,
                    727: .Xr mandoc 1
                    728: supports the following subset of roff conditionals:
                    729: .Bl -bullet
                    730: .It
                    731: If
                    732: .Sq \&!
                    733: is prefixed to COND, the condition is logically inverted.
                    734: .It
                    735: If the first character of COND is
                    736: .Sq n
                    737: .Pq nroff mode
                    738: or
                    739: .Sq o
                    740: .Pq odd page ,
                    741: COND evaluates to true.
                    742: .It
                    743: If the first character of COND is
                    744: .Sq c
                    745: .Pq character available ,
                    746: .Sq d
                    747: .Pq string defined ,
                    748: .Sq e
                    749: .Pq even page ,
                    750: .Sq r
                    751: .Pq register accessed ,
                    752: .Sq t
                    753: .Pq troff mode ,
1.59      schwarze  754: or
                    755: .Sq v
                    756: .Pq vroff mode ,
1.48      schwarze  757: COND evaluates to false.
                    758: .It
1.53      schwarze  759: If COND starts with a parenthesis or with an optionally signed
                    760: integer number, it is evaluated according to the rules of
                    761: .Sx Numerical expressions
                    762: explained below.
1.57      schwarze  763: It evaluates to true if the result is positive,
1.53      schwarze  764: or to false if the result is zero or negative.
1.48      schwarze  765: .It
                    766: Otherwise, the first character of COND is regarded as a delimiter
                    767: and COND evaluates to true if the string extending from its first
                    768: to its second occurrence is equal to the string extending from its
                    769: second to its third occurrence.
                    770: .It
                    771: If COND cannot be parsed, it evaluates to false.
                    772: .El
                    773: .Pp
1.3       kristaps  774: If a conditional is false, its children are not processed, but are
                    775: syntactically interpreted to preserve the integrity of the input
                    776: document.
                    777: Thus,
                    778: .Pp
1.17      schwarze  779: .D1 \&.if t .ig
1.3       kristaps  780: .Pp
                    781: will discard the
                    782: .Sq \&.ig ,
                    783: which may lead to interesting results, but
                    784: .Pp
1.17      schwarze  785: .D1 \&.if t .if t \e{\e
1.3       kristaps  786: .Pp
                    787: will continue to syntactically interpret to the block close of the final
                    788: conditional.
                    789: Sub-conditionals, in this case, obviously inherit the truth value of
                    790: the parent.
1.1       kristaps  791: .Pp
                    792: If the BODY section is begun by an escaped brace
                    793: .Sq \e{ ,
1.48      schwarze  794: scope continues until the end of the input line containing the
                    795: matching closing-brace escape sequence
                    796: .Sq \e} .
1.17      schwarze  797: If the BODY is not enclosed in braces, scope continues until
                    798: the end of the line.
1.1       kristaps  799: If the COND is followed by a BODY on the same line, whether after a
1.17      schwarze  800: brace or not, then requests and macros
1.1       kristaps  801: .Em must
                    802: begin with a control character.
                    803: It is generally more intuitive, in this case, to write
                    804: .Bd -literal -offset indent
                    805: \&.if COND \e{\e
                    806: \&.foo
                    807: bar
                    808: \&.\e}
                    809: .Ed
                    810: .Pp
1.17      schwarze  811: than having the request or macro follow as
1.1       kristaps  812: .Pp
                    813: .D1 \&.if COND \e{ .foo
                    814: .Pp
                    815: The scope of a conditional is always parsed, but only executed if the
                    816: conditional evaluates to true.
                    817: .Pp
1.29      kristaps  818: Note that the
1.1       kristaps  819: .Sq \e}
1.29      kristaps  820: is converted into a zero-width escape sequence if not passed as a
                    821: standalone macro
                    822: .Sq \&.\e} .
                    823: For example,
                    824: .Pp
                    825: .D1 \&.Fl a \e} b
                    826: .Pp
                    827: will result in
1.8       kristaps  828: .Sq \e}
1.29      kristaps  829: being considered an argument of the
                    830: .Sq \&Fl
                    831: macro.
1.1       kristaps  832: .Ss \&ig
1.2       kristaps  833: Ignore input.
1.15      kristaps  834: Its syntax can be either
                    835: .Bd -literal -offset indent
                    836: .Pf . Cm \&ig
                    837: .Ar ignored text
1.2       kristaps  838: \&..
                    839: .Ed
1.15      kristaps  840: .Pp
                    841: or
                    842: .Bd -literal -offset indent
                    843: .Pf . Cm \&ig Ar end
                    844: .Ar ignored text
                    845: .Pf . Ar end
1.2       kristaps  846: .Ed
                    847: .Pp
                    848: In the first case, input is ignored until a
                    849: .Sq \&..
1.17      schwarze  850: request is encountered on its own line.
1.15      kristaps  851: In the second case, input is ignored until the specified
                    852: .Sq Pf . Ar end
                    853: macro is encountered.
                    854: Do not use the escape character
1.2       kristaps  855: .Sq \e
1.15      kristaps  856: anywhere in the definition of
                    857: .Ar end ;
                    858: it would cause very strange behaviour.
                    859: .Pp
                    860: When the
                    861: .Ar end
                    862: macro is a roff request or a roff macro, like in
1.2       kristaps  863: .Pp
                    864: .D1 \&.ig if
                    865: .Pp
                    866: the subsequent invocation of
                    867: .Sx \&if
1.15      kristaps  868: will first terminate the
                    869: .Ar ignored text ,
                    870: then be invoked as usual.
                    871: Otherwise, it only terminates the
                    872: .Ar ignored text ,
                    873: and arguments following it or the
                    874: .Sq \&..
1.17      schwarze  875: request are discarded.
1.50      schwarze  876: .Ss \&ll
                    877: Change the output line length.
                    878: Its syntax is as follows:
                    879: .Pp
1.51      schwarze  880: .D1 Pf . Cm \&ll Op Oo +|- Oc Ns Ar width
1.50      schwarze  881: .Pp
                    882: If the
                    883: .Ar width
                    884: argument is omitted, the line length is reset to its previous value.
                    885: The default setting for terminal output is 78n.
1.51      schwarze  886: If a sign is given, the line length is added to or subtracted from;
                    887: otherwise, it is set to the provided value.
1.50      schwarze  888: Using this request in new manuals is discouraged for several reasons,
                    889: among others because it overrides the
                    890: .Xr mandoc 1
                    891: .Fl O Cm width
                    892: command line option.
1.15      kristaps  893: .Ss \&ne
                    894: Declare the need for the specified minimum vertical space
                    895: before the next trap or the bottom of the page.
                    896: This line-scoped request is currently ignored.
                    897: .Ss \&nh
                    898: Turn off automatic hyphenation mode.
                    899: This line-scoped request is currently ignored.
1.10      kristaps  900: .Ss \&nr
1.45      schwarze  901: Define or change a register.
1.10      kristaps  902: A register is an arbitrary string value that defines some sort of state,
                    903: which influences parsing and/or formatting.
                    904: Its syntax is as follows:
                    905: .Pp
1.53      schwarze  906: .D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar expression
1.10      kristaps  907: .Pp
1.53      schwarze  908: For the syntax of
                    909: .Ar expression ,
                    910: see
                    911: .Sx Numerical expressions
                    912: below.
1.46      schwarze  913: If it is prefixed by a sign, the register will be
1.45      schwarze  914: incremented or decremented instead of assigned to.
                    915: .Pp
                    916: The following register
1.15      kristaps  917: .Ar name
1.45      schwarze  918: is handled specially:
1.10      kristaps  919: .Bl -tag -width Ds
                    920: .It Cm nS
                    921: If set to a positive integer value, certain
                    922: .Xr mdoc 7
1.17      schwarze  923: macros will behave in the same way as in the
1.10      kristaps  924: .Em SYNOPSIS
1.11      kristaps  925: section.
1.17      schwarze  926: If set to 0, these macros will behave in the same way as outside the
                    927: .Em SYNOPSIS
                    928: section, even when called within the
1.10      kristaps  929: .Em SYNOPSIS
1.17      schwarze  930: section itself.
                    931: Note that starting a new
1.11      kristaps  932: .Xr mdoc 7
1.17      schwarze  933: section with the
                    934: .Cm \&Sh
                    935: macro will reset this register.
1.10      kristaps  936: .El
1.26      schwarze  937: .Ss \&ns
                    938: Turn on no-space mode.
                    939: This line-scoped request is intended to take no arguments.
1.58      schwarze  940: Currently, it is ignored including its arguments,
                    941: and the number of arguments is not checked.
                    942: .Ss \&pl
                    943: Change page length.
                    944: This line-scoped request is intended to take one height argument.
1.26      schwarze  945: Currently, it is ignored including its arguments,
                    946: and the number of arguments is not checked.
                    947: .Ss \&ps
                    948: Change point size.
                    949: This line-scoped request is intended to take one numerical argument.
                    950: Currently, it is ignored including its arguments,
                    951: and the number of arguments is not checked.
1.52      schwarze  952: .Ss \&rm
                    953: Remove a request, macro or string.
                    954: Its syntax is as follows:
                    955: .Pp
                    956: .D1 Pf \. Cm \&rm Ar name
                    957: .Ss \&rr
                    958: Remove a register.
                    959: Its syntax is as follows:
                    960: .Pp
                    961: .D1 Pf \. Cm \&rr Ar name
1.15      kristaps  962: .Ss \&so
                    963: Include a source file.
                    964: Its syntax is as follows:
                    965: .Pp
                    966: .D1 Pf \. Cm \&so Ar file
                    967: .Pp
                    968: The
                    969: .Ar file
                    970: will be read and its contents processed as input in place of the
                    971: .Sq \&.so
                    972: request line.
1.28      kristaps  973: To avoid inadvertent inclusion of unrelated files,
1.15      kristaps  974: .Xr mandoc 1
                    975: only accepts relative paths not containing the strings
                    976: .Qq ../
                    977: and
                    978: .Qq /.. .
1.37      schwarze  979: .Pp
                    980: This request requires
                    981: .Xr man 1
                    982: to change to the right directory before calling
                    983: .Xr mandoc 1 ,
                    984: per convention to the root of the manual tree.
                    985: Typical usage looks like:
                    986: .Pp
                    987: .Dl \&.so man3/Xcursor.3
                    988: .Pp
                    989: As the whole concept is rather fragile, the use of
                    990: .Sx \&so
                    991: is discouraged.
                    992: Use
                    993: .Xr ln 1
                    994: instead.
1.26      schwarze  995: .Ss \&ta
                    996: Set tab stops.
                    997: This line-scoped request can take an arbitrary number of arguments.
                    998: Currently, it is ignored including its arguments.
1.6       schwarze  999: .Ss \&tr
                   1000: Output character translation.
1.30      kristaps 1001: Its syntax is as follows:
                   1002: .Pp
                   1003: .D1 Pf \. Cm \&tr Ar [ab]+
                   1004: .Pp
                   1005: Pairs of
                   1006: .Ar ab
                   1007: characters are replaced
                   1008: .Ar ( a
                   1009: for
                   1010: .Ar b ) .
                   1011: Replacement (or origin) characters may also be character escapes; thus,
                   1012: .Pp
                   1013: .Dl tr \e(xx\e(yy
                   1014: .Pp
                   1015: replaces all invocations of \e(xx with \e(yy.
1.20      kristaps 1016: .Ss \&T&
                   1017: Re-start a table layout, retaining the options of the prior table
                   1018: invocation.
                   1019: See
                   1020: .Sx \&TS .
                   1021: .Ss \&TE
                   1022: End a table context.
                   1023: See
                   1024: .Sx \&TS .
                   1025: .Ss \&TS
                   1026: Begin a table, which formats input in aligned rows and columns.
1.23      kristaps 1027: See
                   1028: .Xr tbl 7
                   1029: for a description of the tbl language.
1.53      schwarze 1030: .Ss Numerical expressions
                   1031: The
                   1032: .Sx \&nr ,
                   1033: .Sx \&if ,
                   1034: and
                   1035: .Sx \&ie
                   1036: requests accept integer numerical expressions as arguments.
                   1037: These are always evaluated using the C
                   1038: .Vt int
                   1039: type; integer overflow works the same way as in the C language.
                   1040: Numbers consist of an arbitrary number of digits
                   1041: .Sq 0
                   1042: to
                   1043: .Sq 9
                   1044: prefixed by an optional sign
                   1045: .Sq +
                   1046: or
                   1047: .Sq - .
                   1048: .Pp
                   1049: The following binary operators are implemented.
                   1050: Unless otherwise stated, they behave as in the C language:
                   1051: .Pp
                   1052: .Bl -tag -width 2n -compact
                   1053: .It Ic +
                   1054: addition
                   1055: .It Ic -
                   1056: subtraction
                   1057: .It Ic *
                   1058: multiplication
                   1059: .It Ic /
                   1060: division
                   1061: .It Ic %
                   1062: remainder of division
                   1063: .It Ic <
                   1064: less than
                   1065: .It Ic >
                   1066: greater than
                   1067: .It Ic ==
                   1068: equal to
                   1069: .It Ic =
                   1070: equal to, same effect as
                   1071: .Ic ==
                   1072: (this differs from C)
                   1073: .It Ic <=
                   1074: less than or equal to
                   1075: .It Ic >=
                   1076: greater than or equal to
                   1077: .It Ic <>
                   1078: not equal to (corresponds to C
                   1079: .Ic != ;
                   1080: this one is of limited portability, it is supported by Heirloom roff,
                   1081: but not by groff)
                   1082: .It Ic &
                   1083: logical and (corresponds to C
                   1084: .Ic && )
                   1085: .It Ic \&:
                   1086: logical or (corresponds to C
                   1087: .Ic \&|| )
                   1088: .It Ic <?
                   1089: minimum (not available in C)
                   1090: .It Ic >?
                   1091: maximum (not available in C)
                   1092: .El
                   1093: .Pp
                   1094: There is no concept of precendence; evaluation proceeds from left to right,
                   1095: except when subexpressions are enclosed in parantheses.
                   1096: Inside parentheses, whitespace is ignored.
1.46      schwarze 1097: .Sh ESCAPE SEQUENCE REFERENCE
                   1098: The
                   1099: .Xr mandoc 1
                   1100: .Nm
                   1101: parser recognises the following escape sequences.
                   1102: Note that the
                   1103: .Nm
                   1104: language defines more escape sequences not implemented in
                   1105: .Xr mandoc 1 .
                   1106: In
                   1107: .Xr mdoc 7
                   1108: and
                   1109: .Xr man 7
                   1110: documents, using escape sequences is discouraged except for those
                   1111: described in the
                   1112: .Sx LANGUAGE SYNTAX
                   1113: section above.
                   1114: .Pp
                   1115: A backslash followed by any character not listed here
                   1116: simply prints that character itself.
                   1117: .Ss \e<newline>
                   1118: A backslash at the end of an input line can be used to continue the
                   1119: logical input line on the next physical input line, joining the text
                   1120: on both lines together as if it were on a single input line.
                   1121: .Ss \e<space>
                   1122: The escape sequence backslash-space
                   1123: .Pq Sq \e\ \&
                   1124: is an unpaddable space-sized non-breaking space character; see
                   1125: .Sx Whitespace .
                   1126: .Ss \e\(dq
                   1127: The rest of the input line is treated as
                   1128: .Sx Comments .
                   1129: .Ss \e%
                   1130: Hyphenation allowed at this point of the word; ignored by
                   1131: .Xr mandoc 1 .
                   1132: .Ss \e&
                   1133: Non-printing zero-width character; see
                   1134: .Sx Whitespace .
                   1135: .Ss \e\(aq
                   1136: Acute accent special character; use
                   1137: .Sq \e(aa
                   1138: instead.
                   1139: .Ss \e( Ns Ar cc
                   1140: .Sx Special Characters
                   1141: with two-letter names, see
                   1142: .Xr mandoc_char 7 .
                   1143: .Ss \e*[ Ns Ar name ]
                   1144: Interpolate the string with the
                   1145: .Ar name ;
                   1146: see
                   1147: .Sx Predefined Strings
                   1148: and
                   1149: .Sx ds .
                   1150: For short names, there are variants
                   1151: .No \e* Ns Ar c
                   1152: and
                   1153: .No \e*( Ns Ar cc .
                   1154: .Ss \e-
                   1155: Special character
                   1156: .Dq mathematical minus sign .
                   1157: .Ss \e[ Ns Ar name ]
                   1158: .Sx Special Characters
                   1159: with names of arbitrary length, see
                   1160: .Xr mandoc_char 7 .
                   1161: .Ss \e^
                   1162: One-twelfth em half-narrow space character, effectively zero-width in
                   1163: .Xr mandoc 1 .
                   1164: .Ss \e`
                   1165: Grave accent special character; use
                   1166: .Sq \e(ga
                   1167: instead.
                   1168: .Ss \e{
                   1169: Begin conditional input; see
                   1170: .Sx if .
                   1171: .Ss \e\(ba
                   1172: One-sixth em narrow space character, effectively zero-width in
                   1173: .Xr mandoc 1 .
                   1174: .Ss \e}
                   1175: End conditional input; see
                   1176: .Sx if .
                   1177: .Ss \e~
                   1178: Paddable non-breaking space character.
                   1179: .Ss \e0
                   1180: Digit width space character.
                   1181: .Ss \eA\(aq Ns Ar string Ns \(aq
                   1182: Anchor definition; ignored by
                   1183: .Xr mandoc 1 .
                   1184: .Ss \eB\(aq Ns Ar string Ns \(aq
1.54      schwarze 1185: Interpolate
                   1186: .Sq 1
                   1187: if
1.46      schwarze 1188: .Ar string
1.54      schwarze 1189: conforms to the syntax of
                   1190: .Sx Numerical expressions
                   1191: explained above and
                   1192: .Sq 0
                   1193: otherwise.
1.46      schwarze 1194: .Ss \eb\(aq Ns Ar string Ns \(aq
                   1195: Bracket building function; ignored by
                   1196: .Xr mandoc 1 .
                   1197: .Ss \eC\(aq Ns Ar name Ns \(aq
                   1198: .Sx Special Characters
                   1199: with names of arbitrary length.
                   1200: .Ss \ec
1.60      schwarze 1201: When encountered at the end of an input text line,
                   1202: the next input text line is considered to continue that line,
                   1203: even if there are request or macro lines in between.
                   1204: No whitespace is inserted.
1.46      schwarze 1205: .Ss \eD\(aq Ns Ar string Ns \(aq
                   1206: Draw graphics function; ignored by
                   1207: .Xr mandoc 1 .
                   1208: .Ss \ed
                   1209: Move down by half a line; ignored by
                   1210: .Xr mandoc 1 .
                   1211: .Ss \ee
                   1212: Backslash special character.
                   1213: .Ss \eF[ Ns Ar name ]
                   1214: Switch font family (groff extension); ignored by
                   1215: .Xr mandoc 1 .
                   1216: For short names, there are variants
                   1217: .No \eF Ns Ar c
                   1218: and
                   1219: .No \eF( Ns Ar cc .
                   1220: .Ss \ef[ Ns Ar name ]
                   1221: Switch to the font
                   1222: .Ar name ,
                   1223: see
                   1224: .Sx Text Decoration .
                   1225: For short names, there are variants
                   1226: .No \ef Ns Ar c
                   1227: and
                   1228: .No \ef( Ns Ar cc .
                   1229: .Ss \eg[ Ns Ar name ]
                   1230: Interpolate the format of a number register; ignored by
                   1231: .Xr mandoc 1 .
                   1232: For short names, there are variants
                   1233: .No \eg Ns Ar c
                   1234: and
                   1235: .No \eg( Ns Ar cc .
                   1236: .Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
                   1237: Set the height of the current font; ignored by
                   1238: .Xr mandoc 1 .
                   1239: .Ss \eh\(aq Ns Ar number Ns \(aq
                   1240: Horizontal motion; ignored by
                   1241: .Xr mandoc 1 .
                   1242: .Ss \ek[ Ns Ar name ]
                   1243: Mark horizontal input place in register; ignored by
                   1244: .Xr mandoc 1 .
                   1245: For short names, there are variants
                   1246: .No \ek Ns Ar c
                   1247: and
                   1248: .No \ek( Ns Ar cc .
                   1249: .Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq
                   1250: Vertical line drawing function; ignored by
                   1251: .Xr mandoc 1 .
                   1252: .Ss \el\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq
                   1253: Horizontal line drawing function; ignored by
                   1254: .Xr mandoc 1 .
                   1255: .Ss \eM[ Ns Ar name ]
                   1256: Set fill (background) color (groff extension); ignored by
                   1257: .Xr mandoc 1 .
                   1258: For short names, there are variants
                   1259: .No \eM Ns Ar c
                   1260: and
                   1261: .No \eM( Ns Ar cc .
                   1262: .Ss \em[ Ns Ar name ]
                   1263: Set glyph drawing color (groff extension); ignored by
                   1264: .Xr mandoc 1 .
                   1265: For short names, there are variants
                   1266: .No \em Ns Ar c
                   1267: and
                   1268: .No \em( Ns Ar cc .
                   1269: .Ss \eN\(aq Ns Ar number Ns \(aq
                   1270: Character
                   1271: .Ar number
                   1272: on the current font.
                   1273: .Ss \en[ Ns Ar name ]
                   1274: Interpolate the number register
                   1275: .Ar name .
                   1276: For short names, there are variants
                   1277: .No \en Ns Ar c
                   1278: and
                   1279: .No \en( Ns Ar cc .
                   1280: .Ss \eo\(aq Ns Ar string Ns \(aq
                   1281: Overstrike
                   1282: .Ar string ;
                   1283: ignored by
                   1284: .Xr mandoc 1 .
                   1285: .Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq
                   1286: Set number register; ignored by
                   1287: .Xr mandoc 1 .
                   1288: .Ss \eS\(aq Ns Ar number Ns \(aq
                   1289: Slant output; ignored by
                   1290: .Xr mandoc 1 .
                   1291: .Ss \es\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
                   1292: Change point size; ignored by
                   1293: .Xr mandoc 1 .
                   1294: Alternative forms
                   1295: .No \es Ns Oo +|- Oc Ns Ar n ,
                   1296: .No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq ,
                   1297: .No \es Ns [ Oo +|- Oc Ns Ar number ] ,
                   1298: and
                   1299: .No \es Ns Oo +|- Oc Ns [ Ar number Ns ]
                   1300: are also parsed and ignored.
                   1301: .Ss \et
                   1302: Horizontal tab; ignored by
                   1303: .Xr mandoc 1 .
                   1304: .Ss \eu
                   1305: Move up by half a line; ignored by
                   1306: .Xr mandoc 1 .
                   1307: .Ss \eV[ Ns Ar name ]
                   1308: Interpolate an environment variable; ignored by
                   1309: .Xr mandoc 1 .
                   1310: For short names, there are variants
                   1311: .No \eV Ns Ar c
                   1312: and
                   1313: .No \eV( Ns Ar cc .
                   1314: .Ss \ev\(aq Ns Ar number Ns \(aq
                   1315: Vertical motion; ignored by
                   1316: .Xr mandoc 1 .
                   1317: .Ss \ew\(aq Ns Ar string Ns \(aq
                   1318: Interpolate the width of the
1.54      schwarze 1319: .Ar string .
                   1320: The
                   1321: .Xr mandoc 1
                   1322: implementation assumes that after expansion of user-defined strings, the
                   1323: .Ar string
                   1324: only contains normal characters, no escape sequences, and that each
                   1325: character has a width of 24 basic units.
1.46      schwarze 1326: .Ss \eX\(aq Ns Ar string Ns \(aq
                   1327: Output
                   1328: .Ar string
                   1329: as device control function; ignored in nroff mode and by
                   1330: .Xr mandoc 1 .
                   1331: .Ss \ex\(aq Ns Ar number Ns \(aq
                   1332: Extra line space function; ignored by
                   1333: .Xr mandoc 1 .
                   1334: .Ss \eY[ Ns Ar name ]
                   1335: Output a string as a device control function; ignored in nroff mode and by
                   1336: .Xr mandoc 1 .
                   1337: For short names, there are variants
                   1338: .No \eY Ns Ar c
                   1339: and
                   1340: .No \eY( Ns Ar cc .
                   1341: .Ss \eZ\(aq Ns Ar string Ns \(aq
                   1342: Print
                   1343: .Ar string
                   1344: with zero width and height; ignored by
                   1345: .Xr mandoc 1 .
                   1346: .Ss \ez
                   1347: Output the next character without advancing the cursor position;
                   1348: approximated in
                   1349: .Xr mandoc 1
                   1350: by simply skipping the next character.
1.2       kristaps 1351: .Sh COMPATIBILITY
1.40      schwarze 1352: This section documents compatibility between mandoc and other
1.17      schwarze 1353: .Nm
                   1354: implementations, at this time limited to GNU troff
1.2       kristaps 1355: .Pq Qq groff .
                   1356: The term
                   1357: .Qq historic groff
1.17      schwarze 1358: refers to groff version 1.15.
1.2       kristaps 1359: .Pp
                   1360: .Bl -dash -compact
1.56      kristaps 1361: .It
                   1362: The
                   1363: .Sq u
                   1364: scaling unit is the default terminal unit.
                   1365: In traditional troff systems, this unit would change depending on the
                   1366: output media.
1.10      kristaps 1367: .It
1.27      kristaps 1368: In mandoc, the
                   1369: .Sx \&EQ ,
                   1370: .Sx \&TE ,
                   1371: .Sx \&TS ,
                   1372: and
                   1373: .Sx \&T& ,
                   1374: macros are considered regular macros.
                   1375: In all other
                   1376: .Nm
                   1377: implementations, these are special macros that must be specified without
                   1378: spacing between the control character (which must be a period) and the
                   1379: macro name.
                   1380: .It
1.10      kristaps 1381: The
                   1382: .Cm nS
1.17      schwarze 1383: register is only compatible with OpenBSD's groff-1.15.
1.2       kristaps 1384: .It
1.17      schwarze 1385: Historic groff did not accept white-space before a custom
                   1386: .Ar end
                   1387: macro for the
1.2       kristaps 1388: .Sx \&ig
1.17      schwarze 1389: request.
1.4       kristaps 1390: .It
                   1391: The
                   1392: .Sx \&if
                   1393: and family would print funny white-spaces with historic groff when
1.17      schwarze 1394: using the next-line syntax.
1.2       kristaps 1395: .El
1.17      schwarze 1396: .Sh SEE ALSO
                   1397: .Xr mandoc 1 ,
1.27      kristaps 1398: .Xr eqn 7 ,
1.17      schwarze 1399: .Xr man 7 ,
                   1400: .Xr mandoc_char 7 ,
1.23      kristaps 1401: .Xr mdoc 7 ,
                   1402: .Xr tbl 7
1.17      schwarze 1403: .Rs
                   1404: .%A Joseph F. Ossanna
                   1405: .%A Brian W. Kernighan
                   1406: .%I AT&T Bell Laboratories
                   1407: .%T Troff User's Manual
                   1408: .%R Computing Science Technical Report
                   1409: .%N 54
                   1410: .%C Murray Hill, New Jersey
                   1411: .%D 1976 and 1992
                   1412: .%U http://www.kohala.com/start/troff/cstr54.ps
                   1413: .Re
                   1414: .Rs
                   1415: .%A Joseph F. Ossanna
                   1416: .%A Brian W. Kernighan
                   1417: .%A Gunnar Ritter
                   1418: .%T Heirloom Documentation Tools Nroff/Troff User's Manual
                   1419: .%D September 17, 2007
                   1420: .%U http://heirloom.sourceforge.net/doctools/troff.pdf
                   1421: .Re
                   1422: .Sh HISTORY
1.35      kristaps 1423: The RUNOFF typesetting system, whose input forms the basis for
1.17      schwarze 1424: .Nm ,
1.35      kristaps 1425: was written in MAD and FAP for the CTSS operating system by Jerome E.
                   1426: Saltzer in 1964.
                   1427: Doug McIlroy rewrote it in BCPL in 1969, renaming it
                   1428: .Nm .
                   1429: Dennis M. Ritchie rewrote McIlroy's
1.36      schwarze 1430: .Nm
                   1431: in PDP-11 assembly for
1.35      kristaps 1432: .At v1 ,
                   1433: Joseph F. Ossanna improved roff and renamed it nroff
                   1434: for
                   1435: .At v2 ,
                   1436: then ported nroff to C as troff, which Brian W. Kernighan released with
                   1437: .At v7 .
                   1438: In 1989, James Clarke re-implemented troff in C++, naming it groff.
1.1       kristaps 1439: .Sh AUTHORS
1.15      kristaps 1440: .An -nosplit
1.31      kristaps 1441: This
1.1       kristaps 1442: .Nm
                   1443: reference was written by
1.41      schwarze 1444: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1.15      kristaps 1445: and
1.41      schwarze 1446: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .

CVSweb