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