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

Annotation of mandoc/roff.7, Revision 1.36

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

CVSweb