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

Annotation of mandoc/roff.7, Revision 1.78

1.78    ! schwarze    1: .\"    $Id: roff.7,v 1.77 2017/05/05 02:31:35 schwarze Exp $
1.1       kristaps    2: .\"
1.46      schwarze    3: .\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
1.74      schwarze    4: .\" Copyright (c) 2010, 2011, 2013-2015 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.78    ! schwarze   18: .Dd $Mdocdate: May 5 2017 $
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.63      schwarze  398: For requests marked as "ignored" or "unsupported", any arguments are
                    399: ignored, and the number of arguments is not checked.
                    400: .Ss \&ab
                    401: Abort processing.
                    402: Currently unsupported.
1.15      kristaps  403: .Ss \&ad
                    404: Set line adjustment mode.
1.63      schwarze  405: It takes one argument to select normal, left, right,
                    406: or center adjustment for subsequent text.
                    407: Currently ignored.
                    408: .Ss \&af
                    409: Assign an output format to a number register.
                    410: Currently ignored.
                    411: .Ss \&aln
                    412: Create an alias for a number register.
                    413: Currently unsupported.
                    414: .Ss \&als
                    415: Create an alias for a request, string, macro, or diversion.
                    416: Currently unsupported.
1.3       kristaps  417: .Ss \&am
1.15      kristaps  418: Append to a macro definition.
                    419: The syntax of this request is the same as that of
                    420: .Sx \&de .
1.3       kristaps  421: .Ss \&am1
1.15      kristaps  422: Append to a macro definition, switching roff compatibility mode off
1.63      schwarze  423: during macro execution (groff extension).
1.15      kristaps  424: The syntax of this request is the same as that of
                    425: .Sx \&de1 .
1.55      schwarze  426: Since
                    427: .Xr mandoc 1
                    428: does not implement
                    429: .Nm
                    430: compatibility mode at all, it handles this request as an alias for
                    431: .Sx \&am .
1.63      schwarze  432: .Ss \&ami
                    433: Append to a macro definition, specifying the macro name indirectly
                    434: (groff extension).
                    435: The syntax of this request is the same as that of
                    436: .Sx \&dei .
                    437: .Ss \&ami1
                    438: Append to a macro definition, specifying the macro name indirectly
                    439: and switching roff compatibility mode off during macro execution
                    440: (groff extension).
                    441: The syntax of this request is the same as that of
                    442: .Sx \&dei1 .
                    443: Since
                    444: .Xr mandoc 1
                    445: does not implement
                    446: .Nm
                    447: compatibility mode at all, it handles this request as an alias for
                    448: .Sx \&ami .
1.47      schwarze  449: .Ss \&as
                    450: Append to a user-defined string.
                    451: The syntax of this request is the same as that of
                    452: .Sx \&ds .
                    453: If a user-defined string with the specified name does not yet exist,
                    454: it is set to the empty string before appending.
1.63      schwarze  455: .Ss \&as1
                    456: Append to a user-defined string, switching roff compatibility mode off
                    457: during macro execution (groff extension).
                    458: The syntax of this request is the same as that of
                    459: .Sx \&ds1 .
                    460: Since
                    461: .Xr mandoc 1
                    462: does not implement
                    463: .Nm
                    464: compatibility mode at all, it handles this request as an alias for
                    465: .Sx \&as .
                    466: .Ss \&asciify
                    467: Fully unformat a diversion.
                    468: Currently unsupported.
                    469: .Ss \&backtrace
                    470: Print a backtrace of the input stack.
                    471: This is a groff extension and currently ignored.
                    472: .Ss \&bd
                    473: Artificially embolden by repeated printing with small shifts.
                    474: Currently ignored.
                    475: .Ss \&bleedat
                    476: Set the BleedBox page parameter for PDF generation.
                    477: This is a Heirloom extension and currently ignored.
                    478: .Ss \&blm
                    479: Set a blank line trap.
                    480: Currently unsupported.
                    481: .Ss \&box
                    482: Begin a diversion without including a partially filled line.
                    483: Currently unsupported.
                    484: .Ss \&boxa
                    485: Add to a diversion without including a partially filled line.
                    486: Currently unsupported.
                    487: .Ss \&bp
                    488: Begin new page.
                    489: Currently ignored.
                    490: .Ss \&BP
                    491: Define a frame and place a picture in it.
                    492: This is a Heirloom extension and currently unsupported.
                    493: .Ss \&br
                    494: Break the output line.
                    495: .Ss \&break
                    496: Break out of a
                    497: .Sx \&while
                    498: loop.
                    499: Currently unsupported.
                    500: .Ss \&breakchar
                    501: Optional line break characters.
                    502: This is a Heirloom extension and currently ignored.
                    503: .Ss \&brnl
                    504: Break output line after next N input lines.
                    505: This is a Heirloom extension and currently ignored.
                    506: .Ss \&brp
                    507: Break and spread output line.
                    508: Currently, this is implemented as an alias for
                    509: .Sx \&br .
                    510: .Ss \&brpnl
                    511: Break and spread output line after next N input lines.
                    512: This is a Heirloom extension and currently ignored.
                    513: .Ss \&c2
                    514: Change the no-break control character.
                    515: Currently unsupported.
1.39      kristaps  516: .Ss \&cc
1.63      schwarze  517: Change the control character.
1.39      kristaps  518: Its syntax is as follows:
                    519: .Bd -literal -offset indent
                    520: .Pf . Cm \&cc Op Ar c
                    521: .Ed
                    522: .Pp
                    523: If
                    524: .Ar c
                    525: is not specified, the control character is reset to
                    526: .Sq \&. .
                    527: Trailing characters are ignored.
1.47      schwarze  528: .Ss \&ce
                    529: Center some lines.
1.63      schwarze  530: It takes one integer argument, specifying how many lines to center.
                    531: Currently ignored.
                    532: .Ss \&cf
                    533: Output the contents of a file.
                    534: Ignored because insecure.
                    535: .Ss \&cflags
                    536: Set character flags.
                    537: This is a groff extension and currently ignored.
                    538: .Ss \&ch
                    539: Change a trap location.
                    540: Currently ignored.
                    541: .Ss \&char
                    542: Define a new glyph.
                    543: Currently unsupported.
                    544: .Ss \&chop
                    545: Remove the last character from a macro, string, or diversion.
                    546: Currently unsupported.
                    547: .Ss \&class
                    548: Define a character class.
                    549: This is a groff extension and currently ignored.
                    550: .Ss \&close
                    551: Close an open file.
                    552: Ignored because insecure.
                    553: .Ss \&CL
                    554: Print text in color.
                    555: This is a Heirloom extension and currently unsupported.
                    556: .Ss \&color
                    557: Activate or deactivate colors.
                    558: This is a groff extension and currently ignored.
                    559: .Ss \&composite
                    560: Define a name component for composite glyph names.
                    561: This is a groff extension and currently unsupported.
                    562: .Ss \&continue
                    563: Immediately start the next iteration of a
                    564: .Sx \&while
                    565: loop.
                    566: Currently unsupported.
                    567: .Ss \&cp
                    568: Switch
                    569: .Nm
                    570: compatibility mode on or off.
                    571: Currently ignored.
                    572: .Ss \&cropat
                    573: Set the CropBox page parameter for PDF generation.
                    574: This is a Heirloom extension and currently ignored.
                    575: .Ss \&cs
                    576: Constant character spacing mode.
                    577: Currently ignored.
                    578: .Ss \&cu
                    579: Underline including whitespace.
                    580: Currently ignored.
                    581: .Ss \&da
                    582: Append to a diversion.
                    583: Currently unsupported.
                    584: .Ss \&dch
                    585: Change a trap location in the current diversion.
                    586: This is a Heirloom extension and currently unsupported.
1.3       kristaps  587: .Ss \&de
1.17      schwarze  588: Define a
1.15      kristaps  589: .Nm
                    590: macro.
                    591: Its syntax can be either
                    592: .Bd -literal -offset indent
                    593: .Pf . Cm \&de Ar name
                    594: .Ar macro definition
                    595: \&..
                    596: .Ed
                    597: .Pp
                    598: or
                    599: .Bd -literal -offset indent
                    600: .Pf . Cm \&de Ar name Ar end
                    601: .Ar macro definition
                    602: .Pf . Ar end
                    603: .Ed
                    604: .Pp
                    605: Both forms define or redefine the macro
                    606: .Ar name
                    607: to represent the
                    608: .Ar macro definition ,
                    609: which may consist of one or more input lines, including the newline
                    610: characters terminating each line, optionally containing calls to
                    611: .Nm
                    612: requests,
                    613: .Nm
                    614: macros or high-level macros like
                    615: .Xr man 7
                    616: or
                    617: .Xr mdoc 7
                    618: macros, whichever applies to the document in question.
                    619: .Pp
                    620: Specifying a custom
                    621: .Ar end
                    622: macro works in the same way as for
                    623: .Sx \&ig ;
                    624: namely, the call to
                    625: .Sq Pf . Ar end
                    626: first ends the
                    627: .Ar macro definition ,
                    628: and after that, it is also evaluated as a
                    629: .Nm
                    630: request or
                    631: .Nm
                    632: macro, but not as a high-level macro.
                    633: .Pp
1.17      schwarze  634: The macro can be invoked later using the syntax
1.15      kristaps  635: .Pp
                    636: .D1 Pf . Ar name Op Ar argument Op Ar argument ...
                    637: .Pp
1.24      schwarze  638: Regarding argument parsing, see
                    639: .Sx MACRO SYNTAX
                    640: above.
1.15      kristaps  641: .Pp
1.17      schwarze  642: The line invoking the macro will be replaced
1.15      kristaps  643: in the input stream by the
                    644: .Ar macro definition ,
                    645: replacing all occurrences of
                    646: .No \e\e$ Ns Ar N ,
1.17      schwarze  647: where
1.15      kristaps  648: .Ar N
                    649: is a digit, by the
                    650: .Ar N Ns th Ar argument .
                    651: For example,
                    652: .Bd -literal -offset indent
                    653: \&.de ZN
                    654: \efI\e^\e\e$1\e^\efP\e\e$2
                    655: \&..
                    656: \&.ZN XtFree .
                    657: .Ed
                    658: .Pp
                    659: produces
                    660: .Pp
                    661: .D1 \efI\e^XtFree\e^\efP.
                    662: .Pp
                    663: in the input stream, and thus in the output: \fI\^XtFree\^\fP.
1.73      schwarze  664: Each occurrence of \e\e$* is replaced with all the arguments,
                    665: joined together with single blank characters.
1.15      kristaps  666: .Pp
1.17      schwarze  667: Since macros and user-defined strings share a common string table,
1.15      kristaps  668: defining a macro
                    669: .Ar name
                    670: clobbers the user-defined string
                    671: .Ar name ,
                    672: and the
                    673: .Ar macro definition
                    674: can also be printed using the
                    675: .Sq \e*
                    676: string interpolation syntax described below
                    677: .Sx ds ,
                    678: but this is rarely useful because every macro definition contains at least
                    679: one explicit newline character.
1.16      schwarze  680: .Pp
                    681: In order to prevent endless recursion, both groff and
                    682: .Xr mandoc 1
                    683: limit the stack depth for expanding macros and strings
1.61      schwarze  684: to a large, but finite number, and
                    685: .Xr mandoc 1
                    686: also limits the length of the expanded input line.
                    687: Do not rely on the exact values of these limits.
1.63      schwarze  688: .Ss \&de1
                    689: Define a
                    690: .Nm
                    691: macro that will be executed with
                    692: .Nm
                    693: compatibility mode switched off during macro execution.
                    694: This is a groff extension.
                    695: Since
                    696: .Xr mandoc 1
                    697: does not implement
                    698: .Nm
                    699: compatibility mode at all, it handles this request as an alias for
                    700: .Sx \&de .
                    701: .Ss \&defcolor
                    702: Define a color name.
                    703: This is a groff extension and currently ignored.
1.3       kristaps  704: .Ss \&dei
1.17      schwarze  705: Define a
1.15      kristaps  706: .Nm
1.63      schwarze  707: macro, specifying the macro name indirectly (groff extension).
1.17      schwarze  708: The syntax of this request is the same as that of
1.15      kristaps  709: .Sx \&de .
1.55      schwarze  710: The request
                    711: .Pp
                    712: .D1 Pf . Cm \&dei Ar name Op Ar end
                    713: .Pp
                    714: has the same effect as:
                    715: .Pp
                    716: .D1 Pf . Cm \&de No \e* Ns Bo Ar name Bc Op \e* Ns Bq Ar end
1.63      schwarze  717: .Ss \&dei1
1.17      schwarze  718: Define a
1.15      kristaps  719: .Nm
                    720: macro that will be executed with
                    721: .Nm
1.63      schwarze  722: compatibility mode switched off during macro execution,
                    723: specifying the macro name indirectly (groff extension).
1.15      kristaps  724: Since
                    725: .Xr mandoc 1
                    726: does not implement
                    727: .Nm
1.17      schwarze  728: compatibility mode at all, it handles this request as an alias for
1.63      schwarze  729: .Sx \&dei .
                    730: .Ss \&device
                    731: This request only makes sense with the groff-specific intermediate
                    732: output format and is unsupported.
                    733: .Ss \&devicem
                    734: This request only makes sense with the groff-specific intermediate
                    735: output format and is unsupported.
                    736: .Ss \&di
                    737: Begin a diversion.
                    738: Currently unsupported.
                    739: .Ss \&do
                    740: Execute
                    741: .Nm
                    742: request or macro line with compatibility mode disabled.
                    743: Currently unsupported.
1.6       schwarze  744: .Ss \&ds
1.15      kristaps  745: Define a user-defined string.
1.13      kristaps  746: Its syntax is as follows:
                    747: .Pp
1.15      kristaps  748: .D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
1.13      kristaps  749: .Pp
                    750: The
1.15      kristaps  751: .Ar name
1.13      kristaps  752: and
1.15      kristaps  753: .Ar string
                    754: arguments are space-separated.
                    755: If the
                    756: .Ar string
                    757: begins with a double-quote character, that character will not be part
                    758: of the string.
                    759: All remaining characters on the input line form the
                    760: .Ar string ,
                    761: including whitespace and double-quote characters, even trailing ones.
                    762: .Pp
1.13      kristaps  763: The
1.15      kristaps  764: .Ar string
                    765: can be interpolated into subsequent text by using
                    766: .No \e* Ns Bq Ar name
                    767: for a
                    768: .Ar name
                    769: of arbitrary length, or \e*(NN or \e*N if the length of
                    770: .Ar name
                    771: is two or one characters, respectively.
1.17      schwarze  772: Interpolation can be prevented by escaping the leading backslash;
                    773: that is, an asterisk preceded by an even number of backslashes
                    774: does not trigger string interpolation.
1.15      kristaps  775: .Pp
                    776: Since user-defined strings and macros share a common string table,
                    777: defining a string
                    778: .Ar name
1.17      schwarze  779: clobbers the macro
1.15      kristaps  780: .Ar name ,
                    781: and the
                    782: .Ar name
                    783: used for defining a string can also be invoked as a macro,
                    784: in which case the following input line will be appended to the
                    785: .Ar string ,
                    786: forming a new input line passed to the
                    787: .Nm
                    788: parser.
                    789: For example,
                    790: .Bd -literal -offset indent
                    791: \&.ds badidea .S
                    792: \&.badidea
                    793: H SYNOPSIS
                    794: .Ed
                    795: .Pp
                    796: invokes the
                    797: .Cm SH
                    798: macro when used in a
                    799: .Xr man 7
                    800: document.
                    801: Such abuse is of course strongly discouraged.
1.63      schwarze  802: .Ss \&ds1
                    803: Define a user-defined string that will be expanded with
                    804: .Nm
                    805: compatibility mode switched off during string expansion.
                    806: This is a groff extension.
                    807: Since
                    808: .Xr mandoc 1
                    809: does not implement
                    810: .Nm
                    811: compatibility mode at all, it handles this request as an alias for
                    812: .Sx \&ds .
                    813: .Ss \&dwh
                    814: Set a location trap in the current diversion.
                    815: This is a Heirloom extension and currently unsupported.
                    816: .Ss \&dt
                    817: Set a trap within a diversion.
                    818: Currently unsupported.
                    819: .Ss \&ec
                    820: Change the escape character.
                    821: Currently unsupported.
                    822: .Ss \&ecs
                    823: Restore the escape character.
                    824: Currently unsupported.
                    825: .Ss \&ecr
                    826: Save the escape character.
                    827: Currently unsupported.
1.5       kristaps  828: .Ss \&el
                    829: The
                    830: .Qq else
                    831: half of an if/else conditional.
                    832: Pops a result off the stack of conditional evaluations pushed by
                    833: .Sx \&ie
                    834: and uses it as its conditional.
                    835: If no stack entries are present (e.g., due to no prior
                    836: .Sx \&ie
                    837: calls)
                    838: then false is assumed.
1.17      schwarze  839: The syntax of this request is similar to
1.5       kristaps  840: .Sx \&if
                    841: except that the conditional is missing.
1.63      schwarze  842: .Ss \&em
                    843: Set a trap at the end of input.
                    844: Currently unsupported.
1.27      kristaps  845: .Ss \&EN
                    846: End an equation block.
                    847: See
                    848: .Sx \&EQ .
1.63      schwarze  849: .Ss \&eo
                    850: Disable the escape mechanism completely.
                    851: Currently unsupported.
                    852: .Ss \&EP
                    853: End a picture started by
                    854: .Sx \&BP .
                    855: This is a Heirloom extension and currently unsupported.
1.27      kristaps  856: .Ss \&EQ
                    857: Begin an equation block.
                    858: See
                    859: .Xr eqn 7
                    860: for a description of the equation language.
1.63      schwarze  861: .Ss \&errprint
                    862: Print a string like an error message.
                    863: This is a Heirloom extension and currently ignored.
                    864: .Ss \&ev
                    865: Switch to another environment.
                    866: Currently unsupported.
                    867: .Ss \&evc
                    868: Copy an environment into the current environment.
                    869: Currently unsupported.
                    870: .Ss \&ex
                    871: Abort processing and exit.
                    872: Currently unsupported.
                    873: .Ss \&fallback
                    874: Select the fallback sequence for a font.
                    875: This is a Heirloom extension and currently ignored.
1.43      schwarze  876: .Ss \&fam
                    877: Change the font family.
1.63      schwarze  878: Takes one argument specifying the font family to be selected.
                    879: It is a groff extension and currently ignored.
                    880: .Ss \&fc
                    881: Define a delimiting and a padding character for fields.
                    882: Currently unsupported.
                    883: .Ss \&fchar
                    884: Define a fallback glyph.
                    885: Currently unsupported.
                    886: .Ss \&fcolor
                    887: Set the fill color for \eD objects.
                    888: This is a groff extension and currently ignored.
                    889: .Ss \&fdeferlig
                    890: Defer ligature building.
                    891: This is a Heirloom extension and currently ignored.
                    892: .Ss \&feature
                    893: Enable or disable an OpenType feature.
                    894: This is a Heirloom extension and currently ignored.
                    895: .Ss \&fi
                    896: Switch to fill mode.
                    897: See
                    898: .Xr man 7 .
                    899: Ignored in
                    900: .Xr mdoc 7 .
                    901: .Ss \&fkern
                    902: Control the use of kerning tables for a font.
                    903: This is a Heirloom extension and currently ignored.
                    904: .Ss \&fl
                    905: Flush output.
                    906: Currently ignored.
                    907: .Ss \&flig
                    908: Define ligatures.
                    909: This is a Heirloom extension and currently ignored.
                    910: .Ss \&fp
                    911: Assign font position.
                    912: Currently ignored.
                    913: .Ss \&fps
                    914: Mount a font with a special character map.
                    915: This is a Heirloom extension and currently ignored.
                    916: .Ss \&fschar
                    917: Define a font-specific fallback glyph.
                    918: This is a groff extension and currently unsupported.
                    919: .Ss \&fspacewidth
                    920: Set a font-specific width for the space character.
                    921: This is a Heirloom extension and currently ignored.
                    922: .Ss \&fspecial
                    923: Conditionally define a special font.
                    924: This is a groff extension and currently ignored.
1.49      schwarze  925: .Ss \&ft
                    926: Change the font.
                    927: Its syntax is as follows:
                    928: .Pp
                    929: .D1 Pf . Cm \&ft Op Ar font
                    930: .Pp
                    931: The following
                    932: .Ar font
                    933: arguments are supported:
                    934: .Bl -tag -width 4n -offset indent
                    935: .It Cm B , BI , 3 , 4
                    936: switches to
                    937: .Sy bold
                    938: font
                    939: .It Cm I , 2
                    940: switches to
                    941: .Em underlined
                    942: font
                    943: .It Cm R , CW , 1
                    944: switches to normal font
                    945: .It Cm P No "or no argument"
                    946: switches back to the previous font
                    947: .El
                    948: .Pp
1.77      schwarze  949: This request takes effect only locally and may be overridden
                    950: by macros and escape sequences.
1.63      schwarze  951: .Ss \&ftr
                    952: Translate font name.
                    953: This is a groff extension and currently ignored.
                    954: .Ss \&fzoom
                    955: Zoom font size.
                    956: Currently ignored.
                    957: .Ss \&gcolor
                    958: Set glyph color.
                    959: This is a groff extension and currently ignored.
                    960: .Ss \&hc
                    961: Set the hyphenation character.
                    962: Currently ignored.
                    963: .Ss \&hcode
                    964: Set hyphenation codes of characters.
                    965: Currently ignored.
                    966: .Ss \&hidechar
                    967: Hide characters in a font.
                    968: This is a Heirloom extension and currently ignored.
                    969: .Ss \&hla
                    970: Set hyphenation language.
                    971: This is a groff extension and currently ignored.
                    972: .Ss \&hlm
                    973: Set maximum number of consecutive hyphenated lines.
                    974: Currently ignored.
                    975: .Ss \&hpf
                    976: Load hyphenation pattern file.
                    977: This is a groff extension and currently ignored.
                    978: .Ss \&hpfa
                    979: Load hyphenation pattern file, appending to the current patterns.
                    980: This is a groff extension and currently ignored.
                    981: .Ss \&hpfcode
                    982: Define mapping values for character codes in hyphenation patterns.
                    983: This is a groff extension and currently ignored.
1.44      schwarze  984: .Ss \&hw
                    985: Specify hyphenation points in words.
1.63      schwarze  986: Currently ignored.
1.15      kristaps  987: .Ss \&hy
                    988: Set automatic hyphenation mode.
1.63      schwarze  989: Currently ignored.
                    990: .Ss \&hylang
                    991: Set hyphenation language.
                    992: This is a Heirloom extension and currently ignored.
                    993: .Ss \&hylen
                    994: Minimum word length for hyphenation.
                    995: This is a Heirloom extension and currently ignored.
                    996: .Ss \&hym
                    997: Set hyphenation margin.
                    998: This is a groff extension and currently ignored.
                    999: .Ss \&hypp
                   1000: Define hyphenation penalties.
                   1001: This is a Heirloom extension and currently ignored.
1.64      schwarze 1002: .Ss \&hys
1.63      schwarze 1003: Set hyphenation space.
                   1004: This is a groff extension and currently ignored.
1.5       kristaps 1005: .Ss \&ie
                   1006: The
                   1007: .Qq if
                   1008: half of an if/else conditional.
                   1009: The result of the conditional is pushed into a stack used by subsequent
                   1010: invocations of
                   1011: .Sx \&el ,
                   1012: which may be separated by any intervening input (or not exist at all).
                   1013: Its syntax is equivalent to
                   1014: .Sx \&if .
1.1       kristaps 1015: .Ss \&if
1.7       schwarze 1016: Begins a conditional.
1.48      schwarze 1017: This request has the following syntax:
                   1018: .Bd -literal -offset indent
                   1019: \&.if COND BODY
                   1020: .Ed
                   1021: .Bd -literal -offset indent
                   1022: \&.if COND \e{BODY
                   1023: BODY...\e}
                   1024: .Ed
                   1025: .Bd -literal -offset indent
                   1026: \&.if COND \e{\e
                   1027: BODY...
                   1028: \&.\e}
                   1029: .Ed
                   1030: .Pp
                   1031: COND is a conditional statement.
                   1032: Currently,
                   1033: .Xr mandoc 1
                   1034: supports the following subset of roff conditionals:
                   1035: .Bl -bullet
                   1036: .It
                   1037: If
                   1038: .Sq \&!
                   1039: is prefixed to COND, the condition is logically inverted.
                   1040: .It
                   1041: If the first character of COND is
                   1042: .Sq n
                   1043: .Pq nroff mode
                   1044: or
                   1045: .Sq o
                   1046: .Pq odd page ,
                   1047: COND evaluates to true.
                   1048: .It
                   1049: If the first character of COND is
                   1050: .Sq c
                   1051: .Pq character available ,
                   1052: .Sq d
                   1053: .Pq string defined ,
                   1054: .Sq e
                   1055: .Pq even page ,
                   1056: .Sq t
                   1057: .Pq troff mode ,
1.59      schwarze 1058: or
                   1059: .Sq v
                   1060: .Pq vroff mode ,
1.48      schwarze 1061: COND evaluates to false.
1.72      schwarze 1062: .It
                   1063: If the first character of COND is
                   1064: .Sq r ,
1.75      schwarze 1065: it evaluates to true if the rest of COND is the name of an existing
1.72      schwarze 1066: number register; otherwise, it evaluates to false.
1.48      schwarze 1067: .It
1.53      schwarze 1068: If COND starts with a parenthesis or with an optionally signed
                   1069: integer number, it is evaluated according to the rules of
                   1070: .Sx Numerical expressions
                   1071: explained below.
1.57      schwarze 1072: It evaluates to true if the result is positive,
1.53      schwarze 1073: or to false if the result is zero or negative.
1.48      schwarze 1074: .It
                   1075: Otherwise, the first character of COND is regarded as a delimiter
                   1076: and COND evaluates to true if the string extending from its first
                   1077: to its second occurrence is equal to the string extending from its
                   1078: second to its third occurrence.
                   1079: .It
                   1080: If COND cannot be parsed, it evaluates to false.
                   1081: .El
                   1082: .Pp
1.3       kristaps 1083: If a conditional is false, its children are not processed, but are
                   1084: syntactically interpreted to preserve the integrity of the input
                   1085: document.
                   1086: Thus,
                   1087: .Pp
1.17      schwarze 1088: .D1 \&.if t .ig
1.3       kristaps 1089: .Pp
                   1090: will discard the
                   1091: .Sq \&.ig ,
                   1092: which may lead to interesting results, but
                   1093: .Pp
1.17      schwarze 1094: .D1 \&.if t .if t \e{\e
1.3       kristaps 1095: .Pp
                   1096: will continue to syntactically interpret to the block close of the final
                   1097: conditional.
                   1098: Sub-conditionals, in this case, obviously inherit the truth value of
                   1099: the parent.
1.1       kristaps 1100: .Pp
                   1101: If the BODY section is begun by an escaped brace
                   1102: .Sq \e{ ,
1.48      schwarze 1103: scope continues until the end of the input line containing the
                   1104: matching closing-brace escape sequence
                   1105: .Sq \e} .
1.17      schwarze 1106: If the BODY is not enclosed in braces, scope continues until
                   1107: the end of the line.
1.1       kristaps 1108: If the COND is followed by a BODY on the same line, whether after a
1.17      schwarze 1109: brace or not, then requests and macros
1.1       kristaps 1110: .Em must
                   1111: begin with a control character.
                   1112: It is generally more intuitive, in this case, to write
                   1113: .Bd -literal -offset indent
                   1114: \&.if COND \e{\e
                   1115: \&.foo
                   1116: bar
                   1117: \&.\e}
                   1118: .Ed
                   1119: .Pp
1.17      schwarze 1120: than having the request or macro follow as
1.1       kristaps 1121: .Pp
                   1122: .D1 \&.if COND \e{ .foo
                   1123: .Pp
                   1124: The scope of a conditional is always parsed, but only executed if the
                   1125: conditional evaluates to true.
                   1126: .Pp
1.29      kristaps 1127: Note that the
1.1       kristaps 1128: .Sq \e}
1.29      kristaps 1129: is converted into a zero-width escape sequence if not passed as a
                   1130: standalone macro
                   1131: .Sq \&.\e} .
                   1132: For example,
                   1133: .Pp
                   1134: .D1 \&.Fl a \e} b
                   1135: .Pp
                   1136: will result in
1.8       kristaps 1137: .Sq \e}
1.29      kristaps 1138: being considered an argument of the
                   1139: .Sq \&Fl
                   1140: macro.
1.1       kristaps 1141: .Ss \&ig
1.2       kristaps 1142: Ignore input.
1.15      kristaps 1143: Its syntax can be either
                   1144: .Bd -literal -offset indent
                   1145: .Pf . Cm \&ig
                   1146: .Ar ignored text
1.2       kristaps 1147: \&..
                   1148: .Ed
1.15      kristaps 1149: .Pp
                   1150: or
                   1151: .Bd -literal -offset indent
                   1152: .Pf . Cm \&ig Ar end
                   1153: .Ar ignored text
                   1154: .Pf . Ar end
1.2       kristaps 1155: .Ed
                   1156: .Pp
                   1157: In the first case, input is ignored until a
                   1158: .Sq \&..
1.17      schwarze 1159: request is encountered on its own line.
1.15      kristaps 1160: In the second case, input is ignored until the specified
                   1161: .Sq Pf . Ar end
                   1162: macro is encountered.
                   1163: Do not use the escape character
1.2       kristaps 1164: .Sq \e
1.15      kristaps 1165: anywhere in the definition of
                   1166: .Ar end ;
                   1167: it would cause very strange behaviour.
                   1168: .Pp
                   1169: When the
                   1170: .Ar end
                   1171: macro is a roff request or a roff macro, like in
1.2       kristaps 1172: .Pp
                   1173: .D1 \&.ig if
                   1174: .Pp
                   1175: the subsequent invocation of
                   1176: .Sx \&if
1.15      kristaps 1177: will first terminate the
                   1178: .Ar ignored text ,
                   1179: then be invoked as usual.
                   1180: Otherwise, it only terminates the
                   1181: .Ar ignored text ,
                   1182: and arguments following it or the
                   1183: .Sq \&..
1.17      schwarze 1184: request are discarded.
1.63      schwarze 1185: .Ss \&in
                   1186: Change indentation.
                   1187: See
                   1188: .Xr man 7 .
                   1189: Ignored in
                   1190: .Xr mdoc 7 .
                   1191: .Ss \&index
                   1192: Find a substring in a string.
                   1193: This is a Heirloom extension and currently unsupported.
                   1194: .Ss \&it
                   1195: Set an input line trap.
                   1196: Its syntax is as follows:
                   1197: .Pp
1.70      schwarze 1198: .D1 Pf . Cm it Ar expression macro
1.63      schwarze 1199: .Pp
                   1200: The named
                   1201: .Ar macro
1.70      schwarze 1202: will be invoked after processing the number of input text lines
                   1203: specified by the numerical
                   1204: .Ar expression .
                   1205: While evaluating the
                   1206: .Ar expression ,
                   1207: the unit suffixes described below
                   1208: .Sx Scaling Widths
                   1209: are ignored.
1.63      schwarze 1210: .Ss \&itc
                   1211: Set an input line trap, not counting lines ending with \ec.
                   1212: Currently unsupported.
                   1213: .Ss \&IX
                   1214: To support the generation of a table of contents,
                   1215: .Xr pod2man 1
                   1216: emits this user-defined macro, usually without defining it.
                   1217: To avoid reporting large numbers of spurious errors,
                   1218: .Xr mandoc 1
                   1219: ignores it.
                   1220: .Ss \&kern
                   1221: Switch kerning on or off.
                   1222: Currently ignored.
                   1223: .Ss \&kernafter
                   1224: Increase kerning after some characters.
                   1225: This is a Heirloom extension and currently ignored.
                   1226: .Ss \&kernbefore
                   1227: Increase kerning before some characters.
                   1228: This is a Heirloom extension and currently ignored.
                   1229: .Ss \&kernpair
                   1230: Add a kerning pair to the kerning table.
                   1231: This is a Heirloom extension and currently ignored.
                   1232: .Ss \&lc
                   1233: Define a leader repetition character.
                   1234: Currently unsupported.
                   1235: .Ss \&lc_ctype
                   1236: Set the
                   1237: .Dv LC_CTYPE
                   1238: locale.
                   1239: This is a Heirloom extension and currently unsupported.
                   1240: .Ss \&lds
                   1241: Define a local string.
                   1242: This is a Heirloom extension and currently unsupported.
                   1243: .Ss \&length
                   1244: Count the number of input characters in a user-defined string.
                   1245: Currently unsupported.
                   1246: .Ss \&letadj
                   1247: Dynamic letter spacing and reshaping.
                   1248: This is a Heirloom extension and currently ignored.
                   1249: .Ss \&lf
                   1250: Change the line number for error messages.
                   1251: Ignored because insecure.
                   1252: .Ss \&lg
                   1253: Switch the ligature mechanism on or off.
                   1254: Currently ignored.
                   1255: .Ss \&lhang
                   1256: Hang characters at left margin.
                   1257: This is a Heirloom extension and currently ignored.
                   1258: .Ss \&linetabs
                   1259: Enable or disable line-tabs mode.
                   1260: This is a groff extension and currently unsupported.
1.50      schwarze 1261: .Ss \&ll
                   1262: Change the output line length.
                   1263: Its syntax is as follows:
                   1264: .Pp
1.51      schwarze 1265: .D1 Pf . Cm \&ll Op Oo +|- Oc Ns Ar width
1.50      schwarze 1266: .Pp
                   1267: If the
                   1268: .Ar width
                   1269: argument is omitted, the line length is reset to its previous value.
                   1270: The default setting for terminal output is 78n.
1.51      schwarze 1271: If a sign is given, the line length is added to or subtracted from;
                   1272: otherwise, it is set to the provided value.
1.50      schwarze 1273: Using this request in new manuals is discouraged for several reasons,
                   1274: among others because it overrides the
                   1275: .Xr mandoc 1
                   1276: .Fl O Cm width
                   1277: command line option.
1.63      schwarze 1278: .Ss \&lnr
                   1279: Set local number register.
                   1280: This is a Heirloom extension and currently unsupported.
                   1281: .Ss \&lnrf
                   1282: Set local floating-point register.
                   1283: This is a Heirloom extension and currently unsupported.
                   1284: .Ss \&lpfx
                   1285: Set a line prefix.
                   1286: This is a Heirloom extension and currently unsupported.
                   1287: .Ss \&ls
                   1288: Set line spacing.
                   1289: It takes one integer argument specifying the vertical distance of
                   1290: subsequent output text lines measured in v units.
                   1291: Currently ignored.
                   1292: .Ss \&lsm
                   1293: Set a leading spaces trap.
                   1294: This is a groff extension and currently unsupported.
                   1295: .Ss \&lt
                   1296: Set title line length.
                   1297: Currently ignored.
                   1298: .Ss \&mc
                   1299: Print margin character in the right margin.
                   1300: Currently ignored.
                   1301: .Ss \&mediasize
                   1302: Set the device media size.
                   1303: This is a Heirloom extension and currently ignored.
                   1304: .Ss \&minss
                   1305: Set minimum word space.
                   1306: This is a Heirloom extension and currently ignored.
                   1307: .Ss \&mk
                   1308: Mark vertical position.
                   1309: Currently ignored.
                   1310: .Ss \&mso
                   1311: Load a macro file.
                   1312: Ignored because insecure.
                   1313: .Ss \&na
                   1314: Disable adjusting without changing the adjustment mode.
                   1315: Currently ignored.
1.15      kristaps 1316: .Ss \&ne
                   1317: Declare the need for the specified minimum vertical space
                   1318: before the next trap or the bottom of the page.
1.63      schwarze 1319: Currently ignored.
                   1320: .Ss \&nf
                   1321: Switch to no-fill mode.
                   1322: See
                   1323: .Xr man 7 .
                   1324: Ignored by
1.64      schwarze 1325: .Xr mdoc 7 .
1.15      kristaps 1326: .Ss \&nh
                   1327: Turn off automatic hyphenation mode.
1.63      schwarze 1328: Currently ignored.
                   1329: .Ss \&nhychar
                   1330: Define hyphenation-inhibiting characters.
                   1331: This is a Heirloom extension and currently ignored.
                   1332: .Ss \&nm
                   1333: Print line numbers.
                   1334: Currently unsupported.
                   1335: .Ss \&nn
                   1336: Temporarily turn off line numbering.
                   1337: Currently unsupported.
                   1338: .Ss \&nop
1.75      schwarze 1339: Execute the rest of the input line as a request or macro line.
1.63      schwarze 1340: Currently unsupported.
1.10      kristaps 1341: .Ss \&nr
1.45      schwarze 1342: Define or change a register.
1.10      kristaps 1343: A register is an arbitrary string value that defines some sort of state,
                   1344: which influences parsing and/or formatting.
                   1345: Its syntax is as follows:
                   1346: .Pp
1.53      schwarze 1347: .D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar expression
1.10      kristaps 1348: .Pp
1.53      schwarze 1349: For the syntax of
                   1350: .Ar expression ,
                   1351: see
                   1352: .Sx Numerical expressions
                   1353: below.
1.46      schwarze 1354: If it is prefixed by a sign, the register will be
1.45      schwarze 1355: incremented or decremented instead of assigned to.
                   1356: .Pp
                   1357: The following register
1.15      kristaps 1358: .Ar name
1.45      schwarze 1359: is handled specially:
1.10      kristaps 1360: .Bl -tag -width Ds
                   1361: .It Cm nS
                   1362: If set to a positive integer value, certain
                   1363: .Xr mdoc 7
1.17      schwarze 1364: macros will behave in the same way as in the
1.10      kristaps 1365: .Em SYNOPSIS
1.11      kristaps 1366: section.
1.17      schwarze 1367: If set to 0, these macros will behave in the same way as outside the
                   1368: .Em SYNOPSIS
                   1369: section, even when called within the
1.10      kristaps 1370: .Em SYNOPSIS
1.17      schwarze 1371: section itself.
                   1372: Note that starting a new
1.11      kristaps 1373: .Xr mdoc 7
1.17      schwarze 1374: section with the
                   1375: .Cm \&Sh
                   1376: macro will reset this register.
1.10      kristaps 1377: .El
1.63      schwarze 1378: .Ss \&nrf
                   1379: Define or change a floating-point register.
                   1380: This is a Heirloom extension and currently unsupported.
                   1381: .Ss \&nroff
                   1382: Force nroff mode.
                   1383: This is a groff extension and currently ignored.
1.26      schwarze 1384: .Ss \&ns
                   1385: Turn on no-space mode.
1.63      schwarze 1386: Currently ignored.
                   1387: .Ss \&nx
                   1388: Abort processing of the current input file and process another one.
                   1389: Ignored because insecure.
                   1390: .Ss \&open
                   1391: Open a file for writing.
                   1392: Ignored because insecure.
                   1393: .Ss \&opena
                   1394: Open a file for appending.
                   1395: Ignored because insecure.
                   1396: .Ss \&os
                   1397: Output saved vertical space.
                   1398: Currently ignored.
                   1399: .Ss \&output
                   1400: Output directly to intermediate output.
                   1401: Not supported.
                   1402: .Ss \&padj
                   1403: Globally control paragraph-at-once adjustment.
                   1404: This is a Heirloom extension and currently ignored.
                   1405: .Ss \&papersize
                   1406: Set the paper size.
                   1407: This is a Heirloom extension and currently ignored.
                   1408: .Ss \&pc
                   1409: Change the page number character.
                   1410: Currently ignored.
                   1411: .Ss \&pev
                   1412: Print environments.
                   1413: This is a groff extension and currently ignored.
                   1414: .Ss \&pi
                   1415: Pipe output to a shell command.
                   1416: Ignored because insecure.
                   1417: .Ss \&PI
                   1418: Low-level request used by
                   1419: .Sx \&BP .
                   1420: This is a Heirloom extension and currently unsupported.
1.58      schwarze 1421: .Ss \&pl
                   1422: Change page length.
1.63      schwarze 1423: Takes one height argument.
                   1424: Currently ignored.
                   1425: .Ss \&pm
                   1426: Print names and sizes of macros, strings, and diversions.
                   1427: Currently ignored.
                   1428: .Ss \&pn
                   1429: Change page number of the next page.
                   1430: Currently ignored.
                   1431: .Ss \&pnr
                   1432: Print all number registers.
                   1433: Currently ignored.
                   1434: .Ss \&po
                   1435: Set horizontal page offset.
                   1436: Currently ignored.
1.26      schwarze 1437: .Ss \&ps
                   1438: Change point size.
1.63      schwarze 1439: Takes one numerical argument.
                   1440: Currently ignored.
                   1441: .Ss \&psbb
                   1442: Retrieve the bounding box of a PostScript file.
                   1443: Currently unsupported.
                   1444: .Ss \&pshape
                   1445: Set a special shape for the current paragraph.
1.68      schwarze 1446: This is a Heirloom extension and currently unsupported.
1.63      schwarze 1447: .Ss \&pso
                   1448: Include output of a shell command.
                   1449: Ignored because insecure.
                   1450: .Ss \&ptr
                   1451: Print the names and positions of all traps.
                   1452: This is a groff extension and currently ignored.
                   1453: .Ss \&pvs
                   1454: Change post-vertical spacing.
                   1455: This is a groff extension and currently ignored.
                   1456: .Ss \&rchar
                   1457: Remove glyph definitions.
                   1458: Currently unsupported.
                   1459: .Ss \&rd
                   1460: Read from standard input.
                   1461: Currently ignored.
                   1462: .Ss \&recursionlimit
                   1463: Set the maximum stack depth for recursive macros.
                   1464: This is a Heirloom extension and currently ignored.
                   1465: .Ss \&return
                   1466: Exit a macro and return to the caller.
                   1467: Currently unsupported.
                   1468: .Ss \&rfschar
                   1469: Remove font-specific fallback glyph definitions.
                   1470: Currently unsupported.
                   1471: .Ss \&rhang
                   1472: Hang characters at right margin.
                   1473: This is a Heirloom extension and currently ignored.
                   1474: .Ss \&rj
                   1475: Justify unfilled text to the right margin.
                   1476: Currently ignored.
1.52      schwarze 1477: .Ss \&rm
                   1478: Remove a request, macro or string.
                   1479: Its syntax is as follows:
                   1480: .Pp
                   1481: .D1 Pf \. Cm \&rm Ar name
1.63      schwarze 1482: .Ss \&rn
                   1483: Rename a request, macro, diversion, or string.
                   1484: Currently unsupported.
                   1485: .Ss \&rnn
                   1486: Rename a number register.
                   1487: Currently unsupported.
1.52      schwarze 1488: .Ss \&rr
                   1489: Remove a register.
                   1490: Its syntax is as follows:
                   1491: .Pp
                   1492: .D1 Pf \. Cm \&rr Ar name
1.63      schwarze 1493: .Ss \&rs
                   1494: End no-space mode.
                   1495: Currently ignored.
                   1496: .Ss \&rt
                   1497: Return to marked vertical position.
                   1498: Currently ignored.
                   1499: .Ss \&schar
                   1500: Define global fallback glyph.
                   1501: This is a groff extension and currently unsupported.
                   1502: .Ss \&sentchar
                   1503: Define sentence-ending characters.
                   1504: This is a Heirloom extension and currently ignored.
                   1505: .Ss \&shc
                   1506: Change the soft hyphen character.
                   1507: Currently ignored.
                   1508: .Ss \&shift
                   1509: Shift macro arguments.
                   1510: Currently unsupported.
                   1511: .Ss \&sizes
                   1512: Define permissible point sizes.
                   1513: This is a groff extension and currently ignored.
1.15      kristaps 1514: .Ss \&so
                   1515: Include a source file.
                   1516: Its syntax is as follows:
                   1517: .Pp
                   1518: .D1 Pf \. Cm \&so Ar file
                   1519: .Pp
                   1520: The
                   1521: .Ar file
                   1522: will be read and its contents processed as input in place of the
                   1523: .Sq \&.so
                   1524: request line.
1.28      kristaps 1525: To avoid inadvertent inclusion of unrelated files,
1.15      kristaps 1526: .Xr mandoc 1
                   1527: only accepts relative paths not containing the strings
                   1528: .Qq ../
                   1529: and
                   1530: .Qq /.. .
1.37      schwarze 1531: .Pp
                   1532: This request requires
                   1533: .Xr man 1
                   1534: to change to the right directory before calling
                   1535: .Xr mandoc 1 ,
                   1536: per convention to the root of the manual tree.
                   1537: Typical usage looks like:
                   1538: .Pp
                   1539: .Dl \&.so man3/Xcursor.3
                   1540: .Pp
                   1541: As the whole concept is rather fragile, the use of
                   1542: .Sx \&so
                   1543: is discouraged.
                   1544: Use
                   1545: .Xr ln 1
                   1546: instead.
1.78    ! schwarze 1547: .Ss \&sp
        !          1548: Break the output line and emit vertical space.
        !          1549: Its syntax is as follows:
        !          1550: .Pp
        !          1551: .D1 Pf \. Cm \&sp Op Ar height
        !          1552: .Pp
        !          1553: The argument follows the syntax of
        !          1554: .Sx Scaling Widths
        !          1555: and defaults to one blank line
        !          1556: .Pq Li 1v .
1.63      schwarze 1557: .Ss \&spacewidth
                   1558: Set the space width from the font metrics file.
                   1559: This is a Heirloom extension and currently ignored.
                   1560: .Ss \&special
                   1561: Define a special font.
                   1562: This is a groff extension and currently ignored.
                   1563: .Ss \&spreadwarn
                   1564: Warn about wide spacing between words.
                   1565: Currently ignored.
                   1566: .Ss \&ss
                   1567: Set space character size.
                   1568: Currently ignored.
1.64      schwarze 1569: .Ss \&sty
1.63      schwarze 1570: Associate style with a font position.
                   1571: This is a groff extension and currently ignored.
                   1572: .Ss \&substring
                   1573: Replace a user-defined string with a substring.
                   1574: Currently unsupported.
                   1575: .Ss \&sv
                   1576: Save vertical space.
                   1577: Currently ignored.
                   1578: .Ss \&sy
                   1579: Execute shell command.
                   1580: Ignored because insecure.
                   1581: .Ss \&T&
                   1582: Re-start a table layout, retaining the options of the prior table
                   1583: invocation.
                   1584: See
                   1585: .Sx \&TS .
1.26      schwarze 1586: .Ss \&ta
                   1587: Set tab stops.
1.63      schwarze 1588: Takes an arbitrary number of arguments.
1.68      schwarze 1589: Currently unsupported.
1.63      schwarze 1590: .Ss \&tc
1.75      schwarze 1591: Change tab repetition character.
1.63      schwarze 1592: Currently unsupported.
                   1593: .Ss \&TE
                   1594: End a table context.
                   1595: See
                   1596: .Sx \&TS .
                   1597: .Ss \&ti
                   1598: Temporary indent.
1.68      schwarze 1599: Currently unsupported.
1.63      schwarze 1600: .Ss \&tkf
                   1601: Enable track kerning for a font.
                   1602: Currently ignored.
                   1603: .Ss \&tl
                   1604: Print a title line.
                   1605: Currently unsupported.
                   1606: .Ss \&tm
                   1607: Print to standard error output.
                   1608: Currently ignored.
                   1609: .Ss \&tm1
                   1610: Print to standard error output, allowing leading blanks.
                   1611: This is a groff extension and currently ignored.
                   1612: .Ss \&tmc
                   1613: Print to standard error output without a trailing newline.
                   1614: This is a groff extension and currently ignored.
1.6       schwarze 1615: .Ss \&tr
                   1616: Output character translation.
1.30      kristaps 1617: Its syntax is as follows:
                   1618: .Pp
                   1619: .D1 Pf \. Cm \&tr Ar [ab]+
                   1620: .Pp
                   1621: Pairs of
                   1622: .Ar ab
                   1623: characters are replaced
                   1624: .Ar ( a
                   1625: for
                   1626: .Ar b ) .
                   1627: Replacement (or origin) characters may also be character escapes; thus,
                   1628: .Pp
                   1629: .Dl tr \e(xx\e(yy
                   1630: .Pp
                   1631: replaces all invocations of \e(xx with \e(yy.
1.63      schwarze 1632: .Ss \&track
                   1633: Static letter space tracking.
                   1634: This is a Heirloom extension and currently ignored.
                   1635: .Ss \&transchar
                   1636: Define transparent characters for sentence-ending.
                   1637: This is a Heirloom extension and currently ignored.
                   1638: .Ss \&trf
                   1639: Output the contents of a file, disallowing invalid characters.
                   1640: This is a groff extension and ignored because insecure.
                   1641: .Ss \&trimat
                   1642: Set the TrimBox page parameter for PDF generation.
                   1643: This is a Heirloom extension and currently ignored.
                   1644: .Ss \&trin
                   1645: Output character translation, ignored by
                   1646: .Cm \&asciify .
                   1647: Currently unsupported.
                   1648: .Ss \&trnt
                   1649: Output character translation, ignored by \e!.
                   1650: Currently unsupported.
                   1651: .Ss \&troff
                   1652: Force troff mode.
                   1653: This is a groff extension and currently ignored.
1.20      kristaps 1654: .Ss \&TS
                   1655: Begin a table, which formats input in aligned rows and columns.
1.23      kristaps 1656: See
                   1657: .Xr tbl 7
                   1658: for a description of the tbl language.
1.63      schwarze 1659: .Ss \&uf
                   1660: Globally set the underline font.
                   1661: Currently ignored.
                   1662: .Ss \&ul
                   1663: Underline.
                   1664: Currently ignored.
                   1665: .Ss \&unformat
                   1666: Unformat spaces and tabs in a diversion.
                   1667: Currently unsupported.
                   1668: .Ss \&unwatch
                   1669: Disable notification for string or macro.
                   1670: This is a Heirloom extension and currently ignored.
                   1671: .Ss \&unwatchn
                   1672: Disable notification for register.
                   1673: This is a Heirloom extension and currently ignored.
                   1674: .Ss \&vpt
                   1675: Enable or disable vertical position traps.
                   1676: This is a groff extension and currently ignored.
                   1677: .Ss \&vs
                   1678: Change vertical spacing.
                   1679: Currently ignored.
                   1680: .Ss \&warn
                   1681: Set warning level.
                   1682: Currently ignored.
                   1683: .Ss \&warnscale
                   1684: Set the scaling indicator used in warnings.
                   1685: This is a groff extension and currently ignored.
                   1686: .Ss \&watch
                   1687: Notify on change of string or macro.
                   1688: This is a Heirloom extension and currently ignored.
                   1689: .Ss \&watchlength
                   1690: On change, report the contents of macros and strings
1.75      schwarze 1691: up to the specified length.
1.63      schwarze 1692: This is a Heirloom extension and currently ignored.
                   1693: .Ss \&watchn
                   1694: Notify on change of register.
                   1695: This is a Heirloom extension and currently ignored.
                   1696: .Ss \&wh
                   1697: Set a page location trap.
                   1698: Currently unsupported.
                   1699: .Ss \&while
                   1700: Repeated execution while a condition is true.
                   1701: Currently unsupported.
                   1702: .Ss \&write
                   1703: Write to an open file.
                   1704: Ignored because insecure.
                   1705: .Ss \&writec
                   1706: Write to an open file without appending a newline.
                   1707: Ignored because insecure.
                   1708: .Ss \&writem
                   1709: Write macro or string to an open file.
                   1710: Ignored because insecure.
                   1711: .Ss \&xflag
                   1712: Set the extension level.
                   1713: This is a Heirloom extension and currently ignored.
1.53      schwarze 1714: .Ss Numerical expressions
                   1715: The
                   1716: .Sx \&nr ,
                   1717: .Sx \&if ,
                   1718: and
                   1719: .Sx \&ie
                   1720: requests accept integer numerical expressions as arguments.
                   1721: These are always evaluated using the C
                   1722: .Vt int
                   1723: type; integer overflow works the same way as in the C language.
                   1724: Numbers consist of an arbitrary number of digits
                   1725: .Sq 0
                   1726: to
                   1727: .Sq 9
                   1728: prefixed by an optional sign
                   1729: .Sq +
                   1730: or
                   1731: .Sq - .
1.67      schwarze 1732: Each number may be followed by one optional scaling unit described below
                   1733: .Sx Scaling Widths .
                   1734: The following equations hold:
                   1735: .Bd -literal -offset indent
                   1736: 1i = 6v = 6P = 10m = 10n = 72p = 1000M = 240u = 240
1.68      schwarze 1737: 254c = 100i = 24000u = 24000
1.67      schwarze 1738: 1f = 65536u = 65536
                   1739: .Ed
1.53      schwarze 1740: .Pp
                   1741: The following binary operators are implemented.
                   1742: Unless otherwise stated, they behave as in the C language:
                   1743: .Pp
                   1744: .Bl -tag -width 2n -compact
                   1745: .It Ic +
                   1746: addition
                   1747: .It Ic -
                   1748: subtraction
                   1749: .It Ic *
                   1750: multiplication
                   1751: .It Ic /
                   1752: division
                   1753: .It Ic %
                   1754: remainder of division
                   1755: .It Ic <
                   1756: less than
                   1757: .It Ic >
                   1758: greater than
                   1759: .It Ic ==
                   1760: equal to
                   1761: .It Ic =
                   1762: equal to, same effect as
                   1763: .Ic ==
                   1764: (this differs from C)
                   1765: .It Ic <=
                   1766: less than or equal to
                   1767: .It Ic >=
                   1768: greater than or equal to
                   1769: .It Ic <>
                   1770: not equal to (corresponds to C
                   1771: .Ic != ;
                   1772: this one is of limited portability, it is supported by Heirloom roff,
                   1773: but not by groff)
                   1774: .It Ic &
                   1775: logical and (corresponds to C
                   1776: .Ic && )
                   1777: .It Ic \&:
                   1778: logical or (corresponds to C
                   1779: .Ic \&|| )
                   1780: .It Ic <?
                   1781: minimum (not available in C)
                   1782: .It Ic >?
                   1783: maximum (not available in C)
                   1784: .El
                   1785: .Pp
1.75      schwarze 1786: There is no concept of precedence; evaluation proceeds from left to right,
1.76      schwarze 1787: except when subexpressions are enclosed in parentheses.
1.53      schwarze 1788: Inside parentheses, whitespace is ignored.
1.46      schwarze 1789: .Sh ESCAPE SEQUENCE REFERENCE
                   1790: The
                   1791: .Xr mandoc 1
                   1792: .Nm
                   1793: parser recognises the following escape sequences.
                   1794: Note that the
                   1795: .Nm
                   1796: language defines more escape sequences not implemented in
                   1797: .Xr mandoc 1 .
                   1798: In
                   1799: .Xr mdoc 7
                   1800: and
                   1801: .Xr man 7
                   1802: documents, using escape sequences is discouraged except for those
                   1803: described in the
                   1804: .Sx LANGUAGE SYNTAX
                   1805: section above.
                   1806: .Pp
                   1807: A backslash followed by any character not listed here
                   1808: simply prints that character itself.
                   1809: .Ss \e<newline>
                   1810: A backslash at the end of an input line can be used to continue the
                   1811: logical input line on the next physical input line, joining the text
                   1812: on both lines together as if it were on a single input line.
                   1813: .Ss \e<space>
                   1814: The escape sequence backslash-space
                   1815: .Pq Sq \e\ \&
                   1816: is an unpaddable space-sized non-breaking space character; see
                   1817: .Sx Whitespace .
                   1818: .Ss \e\(dq
                   1819: The rest of the input line is treated as
                   1820: .Sx Comments .
                   1821: .Ss \e%
                   1822: Hyphenation allowed at this point of the word; ignored by
                   1823: .Xr mandoc 1 .
                   1824: .Ss \e&
                   1825: Non-printing zero-width character; see
                   1826: .Sx Whitespace .
                   1827: .Ss \e\(aq
                   1828: Acute accent special character; use
                   1829: .Sq \e(aa
                   1830: instead.
                   1831: .Ss \e( Ns Ar cc
                   1832: .Sx Special Characters
                   1833: with two-letter names, see
                   1834: .Xr mandoc_char 7 .
                   1835: .Ss \e*[ Ns Ar name ]
                   1836: Interpolate the string with the
                   1837: .Ar name ;
                   1838: see
                   1839: .Sx Predefined Strings
                   1840: and
                   1841: .Sx ds .
                   1842: For short names, there are variants
                   1843: .No \e* Ns Ar c
                   1844: and
                   1845: .No \e*( Ns Ar cc .
1.74      schwarze 1846: .Ss \e,
                   1847: Left italic correction (groff extension); ignored by
                   1848: .Xr mandoc 1 .
1.46      schwarze 1849: .Ss \e-
                   1850: Special character
                   1851: .Dq mathematical minus sign .
1.74      schwarze 1852: .Ss \e/
                   1853: Right italic correction (groff extension); ignored by
                   1854: .Xr mandoc 1 .
1.46      schwarze 1855: .Ss \e[ Ns Ar name ]
                   1856: .Sx Special Characters
                   1857: with names of arbitrary length, see
                   1858: .Xr mandoc_char 7 .
                   1859: .Ss \e^
                   1860: One-twelfth em half-narrow space character, effectively zero-width in
                   1861: .Xr mandoc 1 .
                   1862: .Ss \e`
                   1863: Grave accent special character; use
                   1864: .Sq \e(ga
                   1865: instead.
                   1866: .Ss \e{
                   1867: Begin conditional input; see
                   1868: .Sx if .
                   1869: .Ss \e\(ba
                   1870: One-sixth em narrow space character, effectively zero-width in
                   1871: .Xr mandoc 1 .
                   1872: .Ss \e}
                   1873: End conditional input; see
                   1874: .Sx if .
                   1875: .Ss \e~
                   1876: Paddable non-breaking space character.
                   1877: .Ss \e0
                   1878: Digit width space character.
                   1879: .Ss \eA\(aq Ns Ar string Ns \(aq
                   1880: Anchor definition; ignored by
                   1881: .Xr mandoc 1 .
                   1882: .Ss \eB\(aq Ns Ar string Ns \(aq
1.54      schwarze 1883: Interpolate
                   1884: .Sq 1
                   1885: if
1.46      schwarze 1886: .Ar string
1.54      schwarze 1887: conforms to the syntax of
                   1888: .Sx Numerical expressions
                   1889: explained above and
                   1890: .Sq 0
                   1891: otherwise.
1.46      schwarze 1892: .Ss \eb\(aq Ns Ar string Ns \(aq
                   1893: Bracket building function; ignored by
                   1894: .Xr mandoc 1 .
                   1895: .Ss \eC\(aq Ns Ar name Ns \(aq
                   1896: .Sx Special Characters
                   1897: with names of arbitrary length.
                   1898: .Ss \ec
1.60      schwarze 1899: When encountered at the end of an input text line,
                   1900: the next input text line is considered to continue that line,
                   1901: even if there are request or macro lines in between.
                   1902: No whitespace is inserted.
1.46      schwarze 1903: .Ss \eD\(aq Ns Ar string Ns \(aq
                   1904: Draw graphics function; ignored by
                   1905: .Xr mandoc 1 .
                   1906: .Ss \ed
                   1907: Move down by half a line; ignored by
                   1908: .Xr mandoc 1 .
                   1909: .Ss \ee
                   1910: Backslash special character.
                   1911: .Ss \eF[ Ns Ar name ]
                   1912: Switch font family (groff extension); ignored by
                   1913: .Xr mandoc 1 .
                   1914: For short names, there are variants
                   1915: .No \eF Ns Ar c
                   1916: and
                   1917: .No \eF( Ns Ar cc .
                   1918: .Ss \ef[ Ns Ar name ]
                   1919: Switch to the font
                   1920: .Ar name ,
                   1921: see
                   1922: .Sx Text Decoration .
                   1923: For short names, there are variants
                   1924: .No \ef Ns Ar c
                   1925: and
                   1926: .No \ef( Ns Ar cc .
                   1927: .Ss \eg[ Ns Ar name ]
                   1928: Interpolate the format of a number register; ignored by
                   1929: .Xr mandoc 1 .
                   1930: For short names, there are variants
                   1931: .No \eg Ns Ar c
                   1932: and
                   1933: .No \eg( Ns Ar cc .
                   1934: .Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
                   1935: Set the height of the current font; ignored by
                   1936: .Xr mandoc 1 .
                   1937: .Ss \eh\(aq Ns Ar number Ns \(aq
                   1938: Horizontal motion; ignored by
                   1939: .Xr mandoc 1 .
                   1940: .Ss \ek[ Ns Ar name ]
                   1941: Mark horizontal input place in register; ignored by
                   1942: .Xr mandoc 1 .
                   1943: For short names, there are variants
                   1944: .No \ek Ns Ar c
                   1945: and
                   1946: .No \ek( Ns Ar cc .
                   1947: .Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq
                   1948: Vertical line drawing function; ignored by
                   1949: .Xr mandoc 1 .
                   1950: .Ss \el\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq
                   1951: Horizontal line drawing function; ignored by
                   1952: .Xr mandoc 1 .
                   1953: .Ss \eM[ Ns Ar name ]
                   1954: Set fill (background) color (groff extension); ignored by
                   1955: .Xr mandoc 1 .
                   1956: For short names, there are variants
                   1957: .No \eM Ns Ar c
                   1958: and
                   1959: .No \eM( Ns Ar cc .
                   1960: .Ss \em[ Ns Ar name ]
                   1961: Set glyph drawing color (groff extension); ignored by
                   1962: .Xr mandoc 1 .
                   1963: For short names, there are variants
                   1964: .No \em Ns Ar c
                   1965: and
                   1966: .No \em( Ns Ar cc .
                   1967: .Ss \eN\(aq Ns Ar number Ns \(aq
                   1968: Character
                   1969: .Ar number
                   1970: on the current font.
                   1971: .Ss \en[ Ns Ar name ]
                   1972: Interpolate the number register
                   1973: .Ar name .
                   1974: For short names, there are variants
                   1975: .No \en Ns Ar c
                   1976: and
                   1977: .No \en( Ns Ar cc .
                   1978: .Ss \eo\(aq Ns Ar string Ns \(aq
1.66      schwarze 1979: Overstrike, writing all the characters contained in the
1.65      schwarze 1980: .Ar string
                   1981: to the same output position.
                   1982: In terminal and HTML output modes,
                   1983: only the last one of the characters is visible.
1.46      schwarze 1984: .Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq
                   1985: Set number register; ignored by
                   1986: .Xr mandoc 1 .
                   1987: .Ss \eS\(aq Ns Ar number Ns \(aq
                   1988: Slant output; ignored by
                   1989: .Xr mandoc 1 .
                   1990: .Ss \es\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
                   1991: Change point size; ignored by
                   1992: .Xr mandoc 1 .
                   1993: Alternative forms
                   1994: .No \es Ns Oo +|- Oc Ns Ar n ,
                   1995: .No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq ,
                   1996: .No \es Ns [ Oo +|- Oc Ns Ar number ] ,
                   1997: and
                   1998: .No \es Ns Oo +|- Oc Ns [ Ar number Ns ]
                   1999: are also parsed and ignored.
                   2000: .Ss \et
                   2001: Horizontal tab; ignored by
                   2002: .Xr mandoc 1 .
                   2003: .Ss \eu
                   2004: Move up by half a line; ignored by
                   2005: .Xr mandoc 1 .
                   2006: .Ss \eV[ Ns Ar name ]
                   2007: Interpolate an environment variable; ignored by
                   2008: .Xr mandoc 1 .
                   2009: For short names, there are variants
                   2010: .No \eV Ns Ar c
                   2011: and
                   2012: .No \eV( Ns Ar cc .
                   2013: .Ss \ev\(aq Ns Ar number Ns \(aq
                   2014: Vertical motion; ignored by
                   2015: .Xr mandoc 1 .
                   2016: .Ss \ew\(aq Ns Ar string Ns \(aq
                   2017: Interpolate the width of the
1.54      schwarze 2018: .Ar string .
                   2019: The
                   2020: .Xr mandoc 1
                   2021: implementation assumes that after expansion of user-defined strings, the
                   2022: .Ar string
                   2023: only contains normal characters, no escape sequences, and that each
                   2024: character has a width of 24 basic units.
1.46      schwarze 2025: .Ss \eX\(aq Ns Ar string Ns \(aq
                   2026: Output
                   2027: .Ar string
                   2028: as device control function; ignored in nroff mode and by
                   2029: .Xr mandoc 1 .
                   2030: .Ss \ex\(aq Ns Ar number Ns \(aq
                   2031: Extra line space function; ignored by
                   2032: .Xr mandoc 1 .
                   2033: .Ss \eY[ Ns Ar name ]
                   2034: Output a string as a device control function; ignored in nroff mode and by
                   2035: .Xr mandoc 1 .
                   2036: For short names, there are variants
                   2037: .No \eY Ns Ar c
                   2038: and
                   2039: .No \eY( Ns Ar cc .
                   2040: .Ss \eZ\(aq Ns Ar string Ns \(aq
                   2041: Print
                   2042: .Ar string
                   2043: with zero width and height; ignored by
                   2044: .Xr mandoc 1 .
                   2045: .Ss \ez
1.71      schwarze 2046: Output the next character without advancing the cursor position.
1.2       kristaps 2047: .Sh COMPATIBILITY
1.69      schwarze 2048: The
                   2049: .Xr mandoc 1
                   2050: implementation of the
1.17      schwarze 2051: .Nm
1.69      schwarze 2052: language is intentionally incomplete.
                   2053: Unimplemented features include:
1.2       kristaps 2054: .Pp
                   2055: .Bl -dash -compact
1.56      kristaps 2056: .It
1.69      schwarze 2057: For security reasons,
                   2058: .Xr mandoc 1
                   2059: never reads or writes external files except via
                   2060: .Sx \&so
                   2061: requests with safe relative paths.
                   2062: .It
                   2063: There is no automatic hyphenation, no adjustment to the right margin,
                   2064: and no centering; the output is always set flush-left.
                   2065: .It
                   2066: Support for setting tabulator positions
                   2067: and tabulator and leader characters is missing,
                   2068: and support for manually changing indentation is limited.
                   2069: .It
1.56      kristaps 2070: The
                   2071: .Sq u
                   2072: scaling unit is the default terminal unit.
1.69      schwarze 2073: In traditional troff systems, this unit changes depending on the
1.56      kristaps 2074: output media.
1.10      kristaps 2075: .It
1.69      schwarze 2076: Width measurements are implemented in a crude way
                   2077: and often yield wrong results.
                   2078: Explicit movement requests and escapes are ignored.
                   2079: .It
                   2080: There is no concept of output pages, no support for floats,
                   2081: graphics drawing, and picture inclusion;
                   2082: terminal output is always continuous.
                   2083: .It
                   2084: Requests regarding color, font families, and glyph manipulation
                   2085: are ignored.
                   2086: Font support is very limited.
                   2087: Kerning is not implemented, and no ligatures are produced.
1.27      kristaps 2088: .It
1.10      kristaps 2089: The
1.69      schwarze 2090: .Qq \(aq
                   2091: macro control character does not suppress output line breaks.
1.2       kristaps 2092: .It
1.69      schwarze 2093: Diversions are not implemented,
                   2094: and support for traps is very incomplete.
1.4       kristaps 2095: .It
1.69      schwarze 2096: While recursion is supported,
                   2097: .Sx \&while
                   2098: loops are not.
1.2       kristaps 2099: .El
1.69      schwarze 2100: .Pp
                   2101: The special semantics of the
                   2102: .Cm nS
                   2103: number register is an idiosyncracy of
                   2104: .Ox
                   2105: manuals and not supported by other
                   2106: .Xr mdoc 7
                   2107: implementations.
1.17      schwarze 2108: .Sh SEE ALSO
                   2109: .Xr mandoc 1 ,
1.27      kristaps 2110: .Xr eqn 7 ,
1.17      schwarze 2111: .Xr man 7 ,
                   2112: .Xr mandoc_char 7 ,
1.23      kristaps 2113: .Xr mdoc 7 ,
                   2114: .Xr tbl 7
1.17      schwarze 2115: .Rs
                   2116: .%A Joseph F. Ossanna
                   2117: .%A Brian W. Kernighan
                   2118: .%I AT&T Bell Laboratories
                   2119: .%T Troff User's Manual
                   2120: .%R Computing Science Technical Report
                   2121: .%N 54
                   2122: .%C Murray Hill, New Jersey
                   2123: .%D 1976 and 1992
                   2124: .%U http://www.kohala.com/start/troff/cstr54.ps
                   2125: .Re
                   2126: .Rs
                   2127: .%A Joseph F. Ossanna
                   2128: .%A Brian W. Kernighan
                   2129: .%A Gunnar Ritter
                   2130: .%T Heirloom Documentation Tools Nroff/Troff User's Manual
                   2131: .%D September 17, 2007
                   2132: .%U http://heirloom.sourceforge.net/doctools/troff.pdf
                   2133: .Re
                   2134: .Sh HISTORY
1.35      kristaps 2135: The RUNOFF typesetting system, whose input forms the basis for
1.17      schwarze 2136: .Nm ,
1.35      kristaps 2137: was written in MAD and FAP for the CTSS operating system by Jerome E.
                   2138: Saltzer in 1964.
                   2139: Doug McIlroy rewrote it in BCPL in 1969, renaming it
                   2140: .Nm .
                   2141: Dennis M. Ritchie rewrote McIlroy's
1.36      schwarze 2142: .Nm
                   2143: in PDP-11 assembly for
1.35      kristaps 2144: .At v1 ,
                   2145: Joseph F. Ossanna improved roff and renamed it nroff
                   2146: for
                   2147: .At v2 ,
                   2148: then ported nroff to C as troff, which Brian W. Kernighan released with
                   2149: .At v7 .
                   2150: In 1989, James Clarke re-implemented troff in C++, naming it groff.
1.1       kristaps 2151: .Sh AUTHORS
1.15      kristaps 2152: .An -nosplit
1.31      kristaps 2153: This
1.1       kristaps 2154: .Nm
                   2155: reference was written by
1.41      schwarze 2156: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1.15      kristaps 2157: and
1.41      schwarze 2158: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .

CVSweb