Annotation of mandoc/roff.7, Revision 1.46
1.46 ! schwarze 1: .\" $Id: roff.7,v 1.45 2013/12/15 21:23:52 schwarze Exp $
1.1 kristaps 2: .\"
1.46 ! schwarze 3: .\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
! 4: .\" Copyright (c) 2010, 2011, 2013 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.46 ! schwarze 18: .Dd $Mdocdate: December 15 2013 $
1.1 kristaps 19: .Dt ROFF 7
20: .Os
21: .Sh NAME
22: .Nm roff
1.17 schwarze 23: .Nd roff language reference for mandoc
1.1 kristaps 24: .Sh DESCRIPTION
25: The
26: .Nm roff
1.17 schwarze 27: language is a general purpose text formatting language.
1.33 schwarze 28: Since traditional implementations of the
1.17 schwarze 29: .Xr mdoc 7
30: and
31: .Xr man 7
1.33 schwarze 32: manual formatting languages are based on it,
33: many real-world manuals use small numbers of
1.17 schwarze 34: .Nm
1.46 ! schwarze 35: requests and escape sequences intermixed with their
1.33 schwarze 36: .Xr mdoc 7
37: or
38: .Xr man 7
39: code.
40: To properly format such manuals, the
1.1 kristaps 41: .Xr mandoc 1
1.33 schwarze 42: utility supports a tiny subset of
43: .Nm
1.46 ! schwarze 44: requests and escapes.
! 45: Only these requests and escapes supported by
1.33 schwarze 46: .Xr mandoc 1
47: are documented in the present manual,
48: together with the basic language syntax shared by
49: .Nm ,
50: .Xr mdoc 7 ,
51: and
52: .Xr man 7 .
53: For complete
54: .Nm
55: manuals, consult the
56: .Sx SEE ALSO
57: section.
1.1 kristaps 58: .Pp
1.33 schwarze 59: Input lines beginning with the control character
1.17 schwarze 60: .Sq \&.
1.33 schwarze 61: are parsed for requests and macros.
62: Such lines are called
63: .Dq request lines
1.1 kristaps 64: or
1.33 schwarze 65: .Dq macro lines ,
66: respectively.
67: Requests change the processing state and manipulate the formatting;
68: some macros also define the document structure and produce formatted
69: output.
70: The single quote
71: .Pq Qq \(aq
72: is accepted as an alternative control character,
73: treated by
74: .Xr mandoc 1
75: just like
76: .Ql \&.
77: .Pp
78: Lines not beginning with control characters are called
79: .Dq text lines .
80: They provide free-form text to be printed; the formatting of the text
81: depends on the respective processing context.
1.1 kristaps 82: .Sh LANGUAGE SYNTAX
83: .Nm
84: documents may contain only graphable 7-bit ASCII characters, the space
1.17 schwarze 85: character, and, in certain circumstances, the tab character.
1.38 kristaps 86: The backslash character
1.33 schwarze 87: .Sq \e
1.46 ! schwarze 88: indicates the start of an escape sequence, used for example for
1.33 schwarze 89: .Sx Comments ,
90: .Sx Special Characters ,
91: .Sx Predefined Strings ,
92: and
93: user-defined strings defined using the
94: .Sx ds
95: request.
1.46 ! schwarze 96: For a listing of escape sequences, consult the
! 97: .Sx ESCAPE SEQUENCE REFERENCE
! 98: below.
1.33 schwarze 99: .Ss Comments
100: Text following an escaped double-quote
101: .Sq \e\(dq ,
102: whether in a request, macro, or text line, is ignored to the end of the line.
103: A request line beginning with a control character and comment escape
104: .Sq \&.\e\(dq
105: is also ignored.
106: Furthermore, request lines with only a control character and optional
107: trailing whitespace are stripped from input.
108: .Pp
109: Examples:
110: .Bd -literal -offset indent -compact
111: \&.\e\(dq This is a comment line.
112: \&.\e\(dq The next line is ignored:
113: \&.
114: \&.Sh EXAMPLES \e\(dq This is a comment, too.
115: \&example text \e\(dq And so is this.
116: .Ed
117: .Ss Special Characters
118: Special characters are used to encode special glyphs and are rendered
119: differently across output media.
120: They may occur in request, macro, and text lines.
121: Sequences begin with the escape character
122: .Sq \e
123: followed by either an open-parenthesis
124: .Sq \&(
125: for two-character sequences; an open-bracket
126: .Sq \&[
127: for n-character sequences (terminated at a close-bracket
128: .Sq \&] ) ;
129: or a single one character sequence.
130: .Pp
131: Examples:
132: .Bl -tag -width Ds -offset indent -compact
133: .It Li \e(em
134: Two-letter em dash escape.
135: .It Li \ee
136: One-letter backslash escape.
137: .El
138: .Pp
139: See
1.17 schwarze 140: .Xr mandoc_char 7
1.33 schwarze 141: for a complete list.
142: .Ss Text Decoration
143: Terms may be text-decorated using the
144: .Sq \ef
145: escape followed by an indicator: B (bold), I (italic), R (regular), or P
146: (revert to previous mode).
147: A numerical representation 3, 2, or 1 (bold, italic, and regular,
148: respectively) may be used instead.
1.34 kristaps 149: The indicator or numerical representative may be preceded by C
150: (constant-width), which is ignored.
1.33 schwarze 151: .Pp
1.42 schwarze 152: The two-character indicator
153: .Sq BI
154: requests a font that is both bold and italic.
155: It may not be portable to old roff implementations.
156: .Pp
1.33 schwarze 157: Examples:
158: .Bl -tag -width Ds -offset indent -compact
159: .It Li \efBbold\efR
1.42 schwarze 160: Write in \fBbold\fP, then switch to regular font mode.
1.33 schwarze 161: .It Li \efIitalic\efP
1.42 schwarze 162: Write in \fIitalic\fP, then return to previous font mode.
163: .It Li \ef(BIbold italic\efP
164: Write in \f(BIbold italic\fP, then return to previous font mode.
1.33 schwarze 165: .El
166: .Pp
167: Text decoration is
168: .Em not
169: recommended for
170: .Xr mdoc 7 ,
171: which encourages semantic annotation.
172: .Ss Predefined Strings
173: Predefined strings, like
174: .Sx Special Characters ,
175: mark special output glyphs.
176: Predefined strings are escaped with the slash-asterisk,
177: .Sq \e* :
178: single-character
179: .Sq \e*X ,
180: two-character
181: .Sq \e*(XX ,
182: and N-character
183: .Sq \e*[N] .
184: .Pp
185: Examples:
186: .Bl -tag -width Ds -offset indent -compact
187: .It Li \e*(Am
188: Two-letter ampersand predefined string.
189: .It Li \e*q
190: One-letter double-quote predefined string.
191: .El
192: .Pp
193: Predefined strings are not recommended for use,
194: as they differ across implementations.
195: Those supported by
196: .Xr mandoc 1
197: are listed in
198: .Xr mandoc_char 7 .
199: Manuals using these predefined strings are almost certainly not portable.
200: .Ss Whitespace
201: Whitespace consists of the space character.
202: In text lines, whitespace is preserved within a line.
203: In request and macro lines, whitespace delimits arguments and is discarded.
204: .Pp
205: Unescaped trailing spaces are stripped from text line input unless in a
206: literal context.
207: In general, trailing whitespace on any input line is discouraged for
208: reasons of portability.
209: In the rare case that a blank character is needed at the end of an
210: input line, it may be forced by
211: .Sq \e\ \e& .
212: .Pp
213: Literal space characters can be produced in the output
214: using escape sequences.
215: In macro lines, they can also be included in arguments using quotation; see
216: .Sx MACRO SYNTAX
217: for details.
218: .Pp
219: Blank text lines, which may include whitespace, are only permitted
220: within literal contexts.
221: If the first character of a text line is a space, that line is printed
222: with a leading newline.
223: .Ss Scaling Widths
224: Many requests and macros support scaled widths for their arguments.
225: The syntax for a scaled width is
226: .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
227: where a decimal must be preceded or followed by at least one digit.
228: Negative numbers, while accepted, are truncated to zero.
229: .Pp
230: The following scaling units are accepted:
231: .Pp
232: .Bl -tag -width Ds -offset indent -compact
233: .It c
234: centimetre
235: .It i
236: inch
237: .It P
238: pica (~1/6 inch)
239: .It p
240: point (~1/72 inch)
241: .It f
242: synonym for
243: .Sq u
244: .It v
245: default vertical span
246: .It m
247: width of rendered
248: .Sq m
249: .Pq em
250: character
251: .It n
252: width of rendered
253: .Sq n
254: .Pq en
255: character
256: .It u
257: default horizontal span
258: .It M
259: mini-em (~1/100 em)
260: .El
261: .Pp
262: Using anything other than
263: .Sq m ,
264: .Sq n ,
265: .Sq u ,
266: or
267: .Sq v
268: is necessarily non-portable across output media.
269: See
270: .Sx COMPATIBILITY .
271: .Pp
272: If a scaling unit is not provided, the numerical value is interpreted
273: under the default rules of
274: .Sq v
275: for vertical spaces and
276: .Sq u
277: for horizontal ones.
278: .Pp
279: Examples:
280: .Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact
281: .It Li \&.Bl -tag -width 2i
282: two-inch tagged list indentation in
283: .Xr mdoc 7
284: .It Li \&.HP 2i
285: two-inch tagged list indentation in
286: .Xr man 7
287: .It Li \&.sp 2v
288: two vertical spaces
289: .El
290: .Ss Sentence Spacing
291: Each sentence should terminate at the end of an input line.
292: By doing this, a formatter will be able to apply the proper amount of
293: spacing after the end of sentence (unescaped) period, exclamation mark,
294: or question mark followed by zero or more non-sentence closing
295: delimiters
296: .Po
297: .Sq \&) ,
298: .Sq \&] ,
299: .Sq \&' ,
300: .Sq \&"
301: .Pc .
302: .Pp
303: The proper spacing is also intelligently preserved if a sentence ends at
304: the boundary of a macro line.
305: .Pp
306: Examples:
307: .Bd -literal -offset indent -compact
308: Do not end sentences mid-line like this. Instead,
309: end a sentence like this.
310: A macro would end like this:
311: \&.Xr mandoc 1 \&.
312: .Ed
1.17 schwarze 313: .Sh REQUEST SYNTAX
314: A request or macro line consists of:
315: .Pp
316: .Bl -enum -compact
317: .It
318: the control character
319: .Sq \&.
1.1 kristaps 320: or
1.17 schwarze 321: .Sq \(aq
322: at the beginning of the line,
323: .It
324: optionally an arbitrary amount of whitespace,
325: .It
326: the name of the request or the macro, which is one word of arbitrary
327: length, terminated by whitespace,
328: .It
329: and zero or more arguments delimited by whitespace.
330: .El
331: .Pp
332: Thus, the following request lines are all equivalent:
1.1 kristaps 333: .Bd -literal -offset indent
1.17 schwarze 334: \&.ig end
335: \&.ig end
336: \&. ig end
1.1 kristaps 337: .Ed
1.24 schwarze 338: .Sh MACRO SYNTAX
1.33 schwarze 339: Macros are provided by the
340: .Xr mdoc 7
341: and
342: .Xr man 7
343: languages and can be defined by the
1.24 schwarze 344: .Sx \&de
345: request.
346: When called, they follow the same syntax as requests, except that
347: macro arguments may optionally be quoted by enclosing them
348: in double quote characters
349: .Pq Sq \(dq .
1.33 schwarze 350: Quoted text, even if it contains whitespace or would cause
351: a macro invocation when unquoted, is always considered literal text.
352: Inside quoted text, pairs of double quote characters
353: .Pq Sq Qq
354: resolve to single double quote characters.
355: .Pp
1.32 kristaps 356: To be recognised as the beginning of a quoted argument, the opening
1.24 schwarze 357: quote character must be preceded by a space character.
358: A quoted argument extends to the next double quote character that is not
359: part of a pair, or to the end of the input line, whichever comes earlier.
360: Leaving out the terminating double quote character at the end of the line
361: is discouraged.
362: For clarity, if more arguments follow on the same input line,
363: it is recommended to follow the terminating double quote character
364: by a space character; in case the next character after the terminating
365: double quote character is anything else, it is regarded as the beginning
366: of the next, unquoted argument.
367: .Pp
368: Both in quoted and unquoted arguments, pairs of backslashes
369: .Pq Sq \e\e
370: resolve to single backslashes.
371: In unquoted arguments, space characters can alternatively be included
372: by preceding them with a backslash
373: .Pq Sq \e\~ ,
374: but quoting is usually better for clarity.
1.33 schwarze 375: .Pp
376: Examples:
377: .Bl -tag -width Ds -offset indent -compact
378: .It Li .Fn strlen \(dqconst char *s\(dq
379: Group arguments
380: .Qq const char *s
381: into one function argument.
382: If unspecified,
383: .Qq const ,
384: .Qq char ,
385: and
386: .Qq *s
387: would be considered separate arguments.
388: .It Li .Op \(dqFl a\(dq
389: Consider
390: .Qq \&Fl a
391: as literal text instead of a flag macro.
392: .El
1.15 kristaps 393: .Sh REQUEST REFERENCE
1.17 schwarze 394: The
1.15 kristaps 395: .Xr mandoc 1
396: .Nm
1.32 kristaps 397: parser recognises the following requests.
1.17 schwarze 398: Note that the
1.15 kristaps 399: .Nm
1.17 schwarze 400: language defines many more requests not implemented in
1.15 kristaps 401: .Xr mandoc 1 .
402: .Ss \&ad
403: Set line adjustment mode.
404: This line-scoped request is intended to have one argument to select
1.32 kristaps 405: normal, left, right, or centre adjustment for subsequent text.
1.15 kristaps 406: Currently, it is ignored including its arguments,
407: and the number of arguments is not checked.
1.3 kristaps 408: .Ss \&am
1.15 kristaps 409: Append to a macro definition.
410: The syntax of this request is the same as that of
411: .Sx \&de .
412: It is currently ignored by
413: .Xr mandoc 1 ,
414: as are its children.
1.3 kristaps 415: .Ss \&ami
1.15 kristaps 416: Append to a macro definition, specifying the macro name indirectly.
417: The syntax of this request is the same as that of
418: .Sx \&dei .
419: It is currently ignored by
420: .Xr mandoc 1 ,
421: as are its children.
1.3 kristaps 422: .Ss \&am1
1.15 kristaps 423: Append to a macro definition, switching roff compatibility mode off
424: during macro execution.
425: The syntax of this request is the same as that of
426: .Sx \&de1 .
427: It is currently ignored by
428: .Xr mandoc 1 ,
429: as are its children.
1.39 kristaps 430: .Ss \&cc
431: Changes the control character.
432: Its syntax is as follows:
433: .Bd -literal -offset indent
434: .Pf . Cm \&cc Op Ar c
435: .Ed
436: .Pp
437: If
438: .Ar c
439: is not specified, the control character is reset to
440: .Sq \&. .
441: Trailing characters are ignored.
1.3 kristaps 442: .Ss \&de
1.17 schwarze 443: Define a
1.15 kristaps 444: .Nm
445: macro.
446: Its syntax can be either
447: .Bd -literal -offset indent
448: .Pf . Cm \&de Ar name
449: .Ar macro definition
450: \&..
451: .Ed
452: .Pp
453: or
454: .Bd -literal -offset indent
455: .Pf . Cm \&de Ar name Ar end
456: .Ar macro definition
457: .Pf . Ar end
458: .Ed
459: .Pp
460: Both forms define or redefine the macro
461: .Ar name
462: to represent the
463: .Ar macro definition ,
464: which may consist of one or more input lines, including the newline
465: characters terminating each line, optionally containing calls to
466: .Nm
467: requests,
468: .Nm
469: macros or high-level macros like
470: .Xr man 7
471: or
472: .Xr mdoc 7
473: macros, whichever applies to the document in question.
474: .Pp
475: Specifying a custom
476: .Ar end
477: macro works in the same way as for
478: .Sx \&ig ;
479: namely, the call to
480: .Sq Pf . Ar end
481: first ends the
482: .Ar macro definition ,
483: and after that, it is also evaluated as a
484: .Nm
485: request or
486: .Nm
487: macro, but not as a high-level macro.
488: .Pp
1.17 schwarze 489: The macro can be invoked later using the syntax
1.15 kristaps 490: .Pp
491: .D1 Pf . Ar name Op Ar argument Op Ar argument ...
492: .Pp
1.24 schwarze 493: Regarding argument parsing, see
494: .Sx MACRO SYNTAX
495: above.
1.15 kristaps 496: .Pp
1.17 schwarze 497: The line invoking the macro will be replaced
1.15 kristaps 498: in the input stream by the
499: .Ar macro definition ,
500: replacing all occurrences of
501: .No \e\e$ Ns Ar N ,
1.17 schwarze 502: where
1.15 kristaps 503: .Ar N
504: is a digit, by the
505: .Ar N Ns th Ar argument .
506: For example,
507: .Bd -literal -offset indent
508: \&.de ZN
509: \efI\e^\e\e$1\e^\efP\e\e$2
510: \&..
511: \&.ZN XtFree .
512: .Ed
513: .Pp
514: produces
515: .Pp
516: .D1 \efI\e^XtFree\e^\efP.
517: .Pp
518: in the input stream, and thus in the output: \fI\^XtFree\^\fP.
519: .Pp
1.17 schwarze 520: Since macros and user-defined strings share a common string table,
1.15 kristaps 521: defining a macro
522: .Ar name
523: clobbers the user-defined string
524: .Ar name ,
525: and the
526: .Ar macro definition
527: can also be printed using the
528: .Sq \e*
529: string interpolation syntax described below
530: .Sx ds ,
531: but this is rarely useful because every macro definition contains at least
532: one explicit newline character.
1.16 schwarze 533: .Pp
534: In order to prevent endless recursion, both groff and
535: .Xr mandoc 1
536: limit the stack depth for expanding macros and strings
537: to a large, but finite number.
538: Do not rely on the exact value of this limit.
1.3 kristaps 539: .Ss \&dei
1.17 schwarze 540: Define a
1.15 kristaps 541: .Nm
542: macro, specifying the macro name indirectly.
1.17 schwarze 543: The syntax of this request is the same as that of
1.15 kristaps 544: .Sx \&de .
545: It is currently ignored by
546: .Xr mandoc 1 ,
547: as are its children.
548: .Ss \&de1
1.17 schwarze 549: Define a
1.15 kristaps 550: .Nm
551: macro that will be executed with
552: .Nm
553: compatibility mode switched off during macro execution.
554: This is a GNU extension not available in traditional
555: .Nm
556: implementations and not even in older versions of groff.
557: Since
558: .Xr mandoc 1
559: does not implement
560: .Nm
1.17 schwarze 561: compatibility mode at all, it handles this request as an alias for
1.15 kristaps 562: .Sx \&de .
1.6 schwarze 563: .Ss \&ds
1.15 kristaps 564: Define a user-defined string.
1.13 kristaps 565: Its syntax is as follows:
566: .Pp
1.15 kristaps 567: .D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
1.13 kristaps 568: .Pp
569: The
1.15 kristaps 570: .Ar name
1.13 kristaps 571: and
1.15 kristaps 572: .Ar string
573: arguments are space-separated.
574: If the
575: .Ar string
576: begins with a double-quote character, that character will not be part
577: of the string.
578: All remaining characters on the input line form the
579: .Ar string ,
580: including whitespace and double-quote characters, even trailing ones.
581: .Pp
1.13 kristaps 582: The
1.15 kristaps 583: .Ar string
584: can be interpolated into subsequent text by using
585: .No \e* Ns Bq Ar name
586: for a
587: .Ar name
588: of arbitrary length, or \e*(NN or \e*N if the length of
589: .Ar name
590: is two or one characters, respectively.
1.17 schwarze 591: Interpolation can be prevented by escaping the leading backslash;
592: that is, an asterisk preceded by an even number of backslashes
593: does not trigger string interpolation.
1.15 kristaps 594: .Pp
595: Since user-defined strings and macros share a common string table,
596: defining a string
597: .Ar name
1.17 schwarze 598: clobbers the macro
1.15 kristaps 599: .Ar name ,
600: and the
601: .Ar name
602: used for defining a string can also be invoked as a macro,
603: in which case the following input line will be appended to the
604: .Ar string ,
605: forming a new input line passed to the
606: .Nm
607: parser.
608: For example,
609: .Bd -literal -offset indent
610: \&.ds badidea .S
611: \&.badidea
612: H SYNOPSIS
613: .Ed
614: .Pp
615: invokes the
616: .Cm SH
617: macro when used in a
618: .Xr man 7
619: document.
620: Such abuse is of course strongly discouraged.
1.5 kristaps 621: .Ss \&el
622: The
623: .Qq else
624: half of an if/else conditional.
625: Pops a result off the stack of conditional evaluations pushed by
626: .Sx \&ie
627: and uses it as its conditional.
628: If no stack entries are present (e.g., due to no prior
629: .Sx \&ie
630: calls)
631: then false is assumed.
1.17 schwarze 632: The syntax of this request is similar to
1.5 kristaps 633: .Sx \&if
634: except that the conditional is missing.
1.27 kristaps 635: .Ss \&EN
636: End an equation block.
637: See
638: .Sx \&EQ .
639: .Ss \&EQ
640: Begin an equation block.
641: See
642: .Xr eqn 7
643: for a description of the equation language.
1.43 schwarze 644: .Ss \&fam
645: Change the font family.
646: This line-scoped request is intended to have one argument specifying
647: the font family to be selected.
648: It is a groff extension, and currently, it is ignored including its
649: arguments, and the number of arguments is not checked.
1.44 schwarze 650: .Ss \&hw
651: Specify hyphenation points in words.
652: This line-scoped request is currently ignored.
1.15 kristaps 653: .Ss \&hy
654: Set automatic hyphenation mode.
655: This line-scoped request is currently ignored.
1.5 kristaps 656: .Ss \&ie
657: The
658: .Qq if
659: half of an if/else conditional.
660: The result of the conditional is pushed into a stack used by subsequent
661: invocations of
662: .Sx \&el ,
663: which may be separated by any intervening input (or not exist at all).
664: Its syntax is equivalent to
665: .Sx \&if .
1.1 kristaps 666: .Ss \&if
1.7 schwarze 667: Begins a conditional.
668: Right now, the conditional evaluates to true
669: if and only if it starts with the letter
670: .Sy n ,
1.17 schwarze 671: indicating processing in nroff style as opposed to troff style.
1.3 kristaps 672: If a conditional is false, its children are not processed, but are
673: syntactically interpreted to preserve the integrity of the input
674: document.
675: Thus,
676: .Pp
1.17 schwarze 677: .D1 \&.if t .ig
1.3 kristaps 678: .Pp
679: will discard the
680: .Sq \&.ig ,
681: which may lead to interesting results, but
682: .Pp
1.17 schwarze 683: .D1 \&.if t .if t \e{\e
1.3 kristaps 684: .Pp
685: will continue to syntactically interpret to the block close of the final
686: conditional.
687: Sub-conditionals, in this case, obviously inherit the truth value of
688: the parent.
1.17 schwarze 689: This request has the following syntax:
690: .Bd -literal -offset indent
1.1 kristaps 691: \&.if COND \e{\e
692: BODY...
693: \&.\e}
694: .Ed
1.17 schwarze 695: .Bd -literal -offset indent
1.1 kristaps 696: \&.if COND \e{ BODY
1.2 kristaps 697: BODY... \e}
698: .Ed
1.17 schwarze 699: .Bd -literal -offset indent
1.2 kristaps 700: \&.if COND \e{ BODY
1.1 kristaps 701: BODY...
702: \&.\e}
703: .Ed
1.17 schwarze 704: .Bd -literal -offset indent
1.1 kristaps 705: \&.if COND \e
706: BODY
707: .Ed
708: .Pp
1.9 kristaps 709: COND is a conditional statement.
710: roff allows for complicated conditionals; mandoc is much simpler.
711: At this time, mandoc supports only
712: .Sq n ,
713: evaluating to true;
714: and
715: .Sq t ,
716: .Sq e ,
717: and
718: .Sq o ,
719: evaluating to false.
720: All other invocations are read up to the next end of line or space and
721: evaluate as false.
1.1 kristaps 722: .Pp
723: If the BODY section is begun by an escaped brace
724: .Sq \e{ ,
1.17 schwarze 725: scope continues until a closing-brace escape sequence
1.1 kristaps 726: .Sq \.\e} .
1.17 schwarze 727: If the BODY is not enclosed in braces, scope continues until
728: the end of the line.
1.1 kristaps 729: If the COND is followed by a BODY on the same line, whether after a
1.17 schwarze 730: brace or not, then requests and macros
1.1 kristaps 731: .Em must
732: begin with a control character.
733: It is generally more intuitive, in this case, to write
734: .Bd -literal -offset indent
735: \&.if COND \e{\e
736: \&.foo
737: bar
738: \&.\e}
739: .Ed
740: .Pp
1.17 schwarze 741: than having the request or macro follow as
1.1 kristaps 742: .Pp
743: .D1 \&.if COND \e{ .foo
744: .Pp
745: The scope of a conditional is always parsed, but only executed if the
746: conditional evaluates to true.
747: .Pp
1.29 kristaps 748: Note that the
1.1 kristaps 749: .Sq \e}
1.29 kristaps 750: is converted into a zero-width escape sequence if not passed as a
751: standalone macro
752: .Sq \&.\e} .
753: For example,
754: .Pp
755: .D1 \&.Fl a \e} b
756: .Pp
757: will result in
1.8 kristaps 758: .Sq \e}
1.29 kristaps 759: being considered an argument of the
760: .Sq \&Fl
761: macro.
1.1 kristaps 762: .Ss \&ig
1.2 kristaps 763: Ignore input.
1.15 kristaps 764: Its syntax can be either
765: .Bd -literal -offset indent
766: .Pf . Cm \&ig
767: .Ar ignored text
1.2 kristaps 768: \&..
769: .Ed
1.15 kristaps 770: .Pp
771: or
772: .Bd -literal -offset indent
773: .Pf . Cm \&ig Ar end
774: .Ar ignored text
775: .Pf . Ar end
1.2 kristaps 776: .Ed
777: .Pp
778: In the first case, input is ignored until a
779: .Sq \&..
1.17 schwarze 780: request is encountered on its own line.
1.15 kristaps 781: In the second case, input is ignored until the specified
782: .Sq Pf . Ar end
783: macro is encountered.
784: Do not use the escape character
1.2 kristaps 785: .Sq \e
1.15 kristaps 786: anywhere in the definition of
787: .Ar end ;
788: it would cause very strange behaviour.
789: .Pp
790: When the
791: .Ar end
792: macro is a roff request or a roff macro, like in
1.2 kristaps 793: .Pp
794: .D1 \&.ig if
795: .Pp
796: the subsequent invocation of
797: .Sx \&if
1.15 kristaps 798: will first terminate the
799: .Ar ignored text ,
800: then be invoked as usual.
801: Otherwise, it only terminates the
802: .Ar ignored text ,
803: and arguments following it or the
804: .Sq \&..
1.17 schwarze 805: request are discarded.
1.15 kristaps 806: .Ss \&ne
807: Declare the need for the specified minimum vertical space
808: before the next trap or the bottom of the page.
809: This line-scoped request is currently ignored.
810: .Ss \&nh
811: Turn off automatic hyphenation mode.
812: This line-scoped request is currently ignored.
1.6 schwarze 813: .Ss \&rm
814: Remove a request, macro or string.
1.15 kristaps 815: This request is intended to have one argument,
1.6 schwarze 816: the name of the request, macro or string to be undefined.
817: Currently, it is ignored including its arguments,
818: and the number of arguments is not checked.
1.10 kristaps 819: .Ss \&nr
1.45 schwarze 820: Define or change a register.
1.10 kristaps 821: A register is an arbitrary string value that defines some sort of state,
822: which influences parsing and/or formatting.
823: Its syntax is as follows:
824: .Pp
1.45 schwarze 825: .D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar value
1.10 kristaps 826: .Pp
827: The
1.15 kristaps 828: .Ar value
1.10 kristaps 829: may, at the moment, only be an integer.
1.46 ! schwarze 830: If it is prefixed by a sign, the register will be
1.45 schwarze 831: incremented or decremented instead of assigned to.
832: .Pp
833: The following register
1.15 kristaps 834: .Ar name
1.45 schwarze 835: is handled specially:
1.10 kristaps 836: .Bl -tag -width Ds
837: .It Cm nS
838: If set to a positive integer value, certain
839: .Xr mdoc 7
1.17 schwarze 840: macros will behave in the same way as in the
1.10 kristaps 841: .Em SYNOPSIS
1.11 kristaps 842: section.
1.17 schwarze 843: If set to 0, these macros will behave in the same way as outside the
844: .Em SYNOPSIS
845: section, even when called within the
1.10 kristaps 846: .Em SYNOPSIS
1.17 schwarze 847: section itself.
848: Note that starting a new
1.11 kristaps 849: .Xr mdoc 7
1.17 schwarze 850: section with the
851: .Cm \&Sh
852: macro will reset this register.
1.10 kristaps 853: .El
1.26 schwarze 854: .Ss \&ns
855: Turn on no-space mode.
856: This line-scoped request is intended to take no arguments.
857: Currently, it is ignored including its arguments,
858: and the number of arguments is not checked.
859: .Ss \&ps
860: Change point size.
861: This line-scoped request is intended to take one numerical argument.
862: Currently, it is ignored including its arguments,
863: and the number of arguments is not checked.
1.15 kristaps 864: .Ss \&so
865: Include a source file.
866: Its syntax is as follows:
867: .Pp
868: .D1 Pf \. Cm \&so Ar file
869: .Pp
870: The
871: .Ar file
872: will be read and its contents processed as input in place of the
873: .Sq \&.so
874: request line.
1.28 kristaps 875: To avoid inadvertent inclusion of unrelated files,
1.15 kristaps 876: .Xr mandoc 1
877: only accepts relative paths not containing the strings
878: .Qq ../
879: and
880: .Qq /.. .
1.37 schwarze 881: .Pp
882: This request requires
883: .Xr man 1
884: to change to the right directory before calling
885: .Xr mandoc 1 ,
886: per convention to the root of the manual tree.
887: Typical usage looks like:
888: .Pp
889: .Dl \&.so man3/Xcursor.3
890: .Pp
891: As the whole concept is rather fragile, the use of
892: .Sx \&so
893: is discouraged.
894: Use
895: .Xr ln 1
896: instead.
1.26 schwarze 897: .Ss \&ta
898: Set tab stops.
899: This line-scoped request can take an arbitrary number of arguments.
900: Currently, it is ignored including its arguments.
1.6 schwarze 901: .Ss \&tr
902: Output character translation.
1.30 kristaps 903: Its syntax is as follows:
904: .Pp
905: .D1 Pf \. Cm \&tr Ar [ab]+
906: .Pp
907: Pairs of
908: .Ar ab
909: characters are replaced
910: .Ar ( a
911: for
912: .Ar b ) .
913: Replacement (or origin) characters may also be character escapes; thus,
914: .Pp
915: .Dl tr \e(xx\e(yy
916: .Pp
917: replaces all invocations of \e(xx with \e(yy.
1.20 kristaps 918: .Ss \&T&
919: Re-start a table layout, retaining the options of the prior table
920: invocation.
921: See
922: .Sx \&TS .
923: .Ss \&TE
924: End a table context.
925: See
926: .Sx \&TS .
927: .Ss \&TS
928: Begin a table, which formats input in aligned rows and columns.
1.23 kristaps 929: See
930: .Xr tbl 7
931: for a description of the tbl language.
1.46 ! schwarze 932: .Sh ESCAPE SEQUENCE REFERENCE
! 933: The
! 934: .Xr mandoc 1
! 935: .Nm
! 936: parser recognises the following escape sequences.
! 937: Note that the
! 938: .Nm
! 939: language defines more escape sequences not implemented in
! 940: .Xr mandoc 1 .
! 941: In
! 942: .Xr mdoc 7
! 943: and
! 944: .Xr man 7
! 945: documents, using escape sequences is discouraged except for those
! 946: described in the
! 947: .Sx LANGUAGE SYNTAX
! 948: section above.
! 949: .Pp
! 950: A backslash followed by any character not listed here
! 951: simply prints that character itself.
! 952: .Ss \e<newline>
! 953: A backslash at the end of an input line can be used to continue the
! 954: logical input line on the next physical input line, joining the text
! 955: on both lines together as if it were on a single input line.
! 956: .Ss \e<space>
! 957: The escape sequence backslash-space
! 958: .Pq Sq \e\ \&
! 959: is an unpaddable space-sized non-breaking space character; see
! 960: .Sx Whitespace .
! 961: .Ss \e\(dq
! 962: The rest of the input line is treated as
! 963: .Sx Comments .
! 964: .Ss \e%
! 965: Hyphenation allowed at this point of the word; ignored by
! 966: .Xr mandoc 1 .
! 967: .Ss \e&
! 968: Non-printing zero-width character; see
! 969: .Sx Whitespace .
! 970: .Ss \e\(aq
! 971: Acute accent special character; use
! 972: .Sq \e(aa
! 973: instead.
! 974: .Ss \e( Ns Ar cc
! 975: .Sx Special Characters
! 976: with two-letter names, see
! 977: .Xr mandoc_char 7 .
! 978: .Ss \e*[ Ns Ar name ]
! 979: Interpolate the string with the
! 980: .Ar name ;
! 981: see
! 982: .Sx Predefined Strings
! 983: and
! 984: .Sx ds .
! 985: For short names, there are variants
! 986: .No \e* Ns Ar c
! 987: and
! 988: .No \e*( Ns Ar cc .
! 989: .Ss \e-
! 990: Special character
! 991: .Dq mathematical minus sign .
! 992: .Ss \e[ Ns Ar name ]
! 993: .Sx Special Characters
! 994: with names of arbitrary length, see
! 995: .Xr mandoc_char 7 .
! 996: .Ss \e^
! 997: One-twelfth em half-narrow space character, effectively zero-width in
! 998: .Xr mandoc 1 .
! 999: .Ss \e`
! 1000: Grave accent special character; use
! 1001: .Sq \e(ga
! 1002: instead.
! 1003: .Ss \e{
! 1004: Begin conditional input; see
! 1005: .Sx if .
! 1006: .Ss \e\(ba
! 1007: One-sixth em narrow space character, effectively zero-width in
! 1008: .Xr mandoc 1 .
! 1009: .Ss \e}
! 1010: End conditional input; see
! 1011: .Sx if .
! 1012: .Ss \e~
! 1013: Paddable non-breaking space character.
! 1014: .Ss \e0
! 1015: Digit width space character.
! 1016: .Ss \eA\(aq Ns Ar string Ns \(aq
! 1017: Anchor definition; ignored by
! 1018: .Xr mandoc 1 .
! 1019: .Ss \eB\(aq Ns Ar string Ns \(aq
! 1020: Test whether
! 1021: .Ar string
! 1022: is a numerical expession; ignored by
! 1023: .Xr mandoc 1 .
! 1024: .Ss \eb\(aq Ns Ar string Ns \(aq
! 1025: Bracket building function; ignored by
! 1026: .Xr mandoc 1 .
! 1027: .Ss \eC\(aq Ns Ar name Ns \(aq
! 1028: .Sx Special Characters
! 1029: with names of arbitrary length.
! 1030: .Ss \ec
! 1031: Interrupt text processing to insert requests or macros; ignored by
! 1032: .Xr mandoc 1 .
! 1033: .Ss \eD\(aq Ns Ar string Ns \(aq
! 1034: Draw graphics function; ignored by
! 1035: .Xr mandoc 1 .
! 1036: .Ss \ed
! 1037: Move down by half a line; ignored by
! 1038: .Xr mandoc 1 .
! 1039: .Ss \ee
! 1040: Backslash special character.
! 1041: .Ss \eF[ Ns Ar name ]
! 1042: Switch font family (groff extension); ignored by
! 1043: .Xr mandoc 1 .
! 1044: For short names, there are variants
! 1045: .No \eF Ns Ar c
! 1046: and
! 1047: .No \eF( Ns Ar cc .
! 1048: .Ss \ef[ Ns Ar name ]
! 1049: Switch to the font
! 1050: .Ar name ,
! 1051: see
! 1052: .Sx Text Decoration .
! 1053: For short names, there are variants
! 1054: .No \ef Ns Ar c
! 1055: and
! 1056: .No \ef( Ns Ar cc .
! 1057: .Ss \eg[ Ns Ar name ]
! 1058: Interpolate the format of a number register; ignored by
! 1059: .Xr mandoc 1 .
! 1060: For short names, there are variants
! 1061: .No \eg Ns Ar c
! 1062: and
! 1063: .No \eg( Ns Ar cc .
! 1064: .Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
! 1065: Set the height of the current font; ignored by
! 1066: .Xr mandoc 1 .
! 1067: .Ss \eh\(aq Ns Ar number Ns \(aq
! 1068: Horizontal motion; ignored by
! 1069: .Xr mandoc 1 .
! 1070: .Ss \ek[ Ns Ar name ]
! 1071: Mark horizontal input place in register; ignored by
! 1072: .Xr mandoc 1 .
! 1073: For short names, there are variants
! 1074: .No \ek Ns Ar c
! 1075: and
! 1076: .No \ek( Ns Ar cc .
! 1077: .Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq
! 1078: Vertical line drawing function; ignored by
! 1079: .Xr mandoc 1 .
! 1080: .Ss \el\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq
! 1081: Horizontal line drawing function; ignored by
! 1082: .Xr mandoc 1 .
! 1083: .Ss \eM[ Ns Ar name ]
! 1084: Set fill (background) color (groff extension); ignored by
! 1085: .Xr mandoc 1 .
! 1086: For short names, there are variants
! 1087: .No \eM Ns Ar c
! 1088: and
! 1089: .No \eM( Ns Ar cc .
! 1090: .Ss \em[ Ns Ar name ]
! 1091: Set glyph drawing color (groff extension); ignored by
! 1092: .Xr mandoc 1 .
! 1093: For short names, there are variants
! 1094: .No \em Ns Ar c
! 1095: and
! 1096: .No \em( Ns Ar cc .
! 1097: .Ss \eN\(aq Ns Ar number Ns \(aq
! 1098: Character
! 1099: .Ar number
! 1100: on the current font.
! 1101: .Ss \en[ Ns Ar name ]
! 1102: Interpolate the number register
! 1103: .Ar name .
! 1104: For short names, there are variants
! 1105: .No \en Ns Ar c
! 1106: and
! 1107: .No \en( Ns Ar cc .
! 1108: .Ss \eo\(aq Ns Ar string Ns \(aq
! 1109: Overstrike
! 1110: .Ar string ;
! 1111: ignored by
! 1112: .Xr mandoc 1 .
! 1113: .Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq
! 1114: Set number register; ignored by
! 1115: .Xr mandoc 1 .
! 1116: .Ss \eS\(aq Ns Ar number Ns \(aq
! 1117: Slant output; ignored by
! 1118: .Xr mandoc 1 .
! 1119: .Ss \es\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
! 1120: Change point size; ignored by
! 1121: .Xr mandoc 1 .
! 1122: Alternative forms
! 1123: .No \es Ns Oo +|- Oc Ns Ar n ,
! 1124: .No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq ,
! 1125: .No \es Ns [ Oo +|- Oc Ns Ar number ] ,
! 1126: and
! 1127: .No \es Ns Oo +|- Oc Ns [ Ar number Ns ]
! 1128: are also parsed and ignored.
! 1129: .Ss \et
! 1130: Horizontal tab; ignored by
! 1131: .Xr mandoc 1 .
! 1132: .Ss \eu
! 1133: Move up by half a line; ignored by
! 1134: .Xr mandoc 1 .
! 1135: .Ss \eV[ Ns Ar name ]
! 1136: Interpolate an environment variable; ignored by
! 1137: .Xr mandoc 1 .
! 1138: For short names, there are variants
! 1139: .No \eV Ns Ar c
! 1140: and
! 1141: .No \eV( Ns Ar cc .
! 1142: .Ss \ev\(aq Ns Ar number Ns \(aq
! 1143: Vertical motion; ignored by
! 1144: .Xr mandoc 1 .
! 1145: .Ss \ew\(aq Ns Ar string Ns \(aq
! 1146: Interpolate the width of the
! 1147: .Ar string ;
! 1148: ignored by
! 1149: .Xr mandoc 1 .
! 1150: .Ss \eX\(aq Ns Ar string Ns \(aq
! 1151: Output
! 1152: .Ar string
! 1153: as device control function; ignored in nroff mode and by
! 1154: .Xr mandoc 1 .
! 1155: .Ss \ex\(aq Ns Ar number Ns \(aq
! 1156: Extra line space function; ignored by
! 1157: .Xr mandoc 1 .
! 1158: .Ss \eY[ Ns Ar name ]
! 1159: Output a string as a device control function; ignored in nroff mode and by
! 1160: .Xr mandoc 1 .
! 1161: For short names, there are variants
! 1162: .No \eY Ns Ar c
! 1163: and
! 1164: .No \eY( Ns Ar cc .
! 1165: .Ss \eZ\(aq Ns Ar string Ns \(aq
! 1166: Print
! 1167: .Ar string
! 1168: with zero width and height; ignored by
! 1169: .Xr mandoc 1 .
! 1170: .Ss \ez
! 1171: Output the next character without advancing the cursor position;
! 1172: approximated in
! 1173: .Xr mandoc 1
! 1174: by simply skipping the next character.
1.2 kristaps 1175: .Sh COMPATIBILITY
1.40 schwarze 1176: This section documents compatibility between mandoc and other
1.17 schwarze 1177: .Nm
1178: implementations, at this time limited to GNU troff
1.2 kristaps 1179: .Pq Qq groff .
1180: The term
1181: .Qq historic groff
1.17 schwarze 1182: refers to groff version 1.15.
1.2 kristaps 1183: .Pp
1184: .Bl -dash -compact
1.10 kristaps 1185: .It
1.27 kristaps 1186: In mandoc, the
1187: .Sx \&EQ ,
1188: .Sx \&TE ,
1189: .Sx \&TS ,
1190: and
1191: .Sx \&T& ,
1192: macros are considered regular macros.
1193: In all other
1194: .Nm
1195: implementations, these are special macros that must be specified without
1196: spacing between the control character (which must be a period) and the
1197: macro name.
1198: .It
1.10 kristaps 1199: The
1200: .Cm nS
1.17 schwarze 1201: register is only compatible with OpenBSD's groff-1.15.
1.2 kristaps 1202: .It
1.17 schwarze 1203: Historic groff did not accept white-space before a custom
1204: .Ar end
1205: macro for the
1.2 kristaps 1206: .Sx \&ig
1.17 schwarze 1207: request.
1.4 kristaps 1208: .It
1209: The
1210: .Sx \&if
1211: and family would print funny white-spaces with historic groff when
1.17 schwarze 1212: using the next-line syntax.
1.2 kristaps 1213: .El
1.17 schwarze 1214: .Sh SEE ALSO
1215: .Xr mandoc 1 ,
1.27 kristaps 1216: .Xr eqn 7 ,
1.17 schwarze 1217: .Xr man 7 ,
1218: .Xr mandoc_char 7 ,
1.23 kristaps 1219: .Xr mdoc 7 ,
1220: .Xr tbl 7
1.17 schwarze 1221: .Rs
1222: .%A Joseph F. Ossanna
1223: .%A Brian W. Kernighan
1224: .%I AT&T Bell Laboratories
1225: .%T Troff User's Manual
1226: .%R Computing Science Technical Report
1227: .%N 54
1228: .%C Murray Hill, New Jersey
1229: .%D 1976 and 1992
1230: .%U http://www.kohala.com/start/troff/cstr54.ps
1231: .Re
1232: .Rs
1233: .%A Joseph F. Ossanna
1234: .%A Brian W. Kernighan
1235: .%A Gunnar Ritter
1236: .%T Heirloom Documentation Tools Nroff/Troff User's Manual
1237: .%D September 17, 2007
1238: .%U http://heirloom.sourceforge.net/doctools/troff.pdf
1239: .Re
1240: .Sh HISTORY
1.35 kristaps 1241: The RUNOFF typesetting system, whose input forms the basis for
1.17 schwarze 1242: .Nm ,
1.35 kristaps 1243: was written in MAD and FAP for the CTSS operating system by Jerome E.
1244: Saltzer in 1964.
1245: Doug McIlroy rewrote it in BCPL in 1969, renaming it
1246: .Nm .
1247: Dennis M. Ritchie rewrote McIlroy's
1.36 schwarze 1248: .Nm
1249: in PDP-11 assembly for
1.35 kristaps 1250: .At v1 ,
1251: Joseph F. Ossanna improved roff and renamed it nroff
1252: for
1253: .At v2 ,
1254: then ported nroff to C as troff, which Brian W. Kernighan released with
1255: .At v7 .
1256: In 1989, James Clarke re-implemented troff in C++, naming it groff.
1.1 kristaps 1257: .Sh AUTHORS
1.15 kristaps 1258: .An -nosplit
1.31 kristaps 1259: This
1.1 kristaps 1260: .Nm
1261: reference was written by
1.41 schwarze 1262: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1.15 kristaps 1263: and
1.41 schwarze 1264: .An Ingo Schwarze Aq 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