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

Annotation of mandoc/roff.7, Revision 1.112

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

CVSweb