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

Annotation of mandoc/roff.7, Revision 1.104

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

CVSweb