Annotation of mandoc/roff.7, Revision 1.24
1.24 ! schwarze 1: .\" $Id: roff.7,v 1.23 2011/01/04 23:32:21 kristaps Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
1.12 schwarze 4: .\" Copyright (c) 2010 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.22 kristaps 18: .Dd $Mdocdate: January 4 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.
28: In particular, it serves as the basis for the
29: .Xr mdoc 7
30: and
31: .Xr man 7
32: manual formatting macro languages.
33: This manual describes the subset of the
34: .Nm
35: language accepted by the
1.1 kristaps 36: .Xr mandoc 1
1.17 schwarze 37: utility.
1.1 kristaps 38: .Pp
1.17 schwarze 39: Input lines beginning with the control characters
40: .Sq \&.
1.1 kristaps 41: or
42: .Sq \(aq
1.15 kristaps 43: are parsed for requests and macros.
1.17 schwarze 44: These define the document structure, change the processing state
45: and manipulate the formatting.
46: Some requests and macros also produce formatted output,
47: while others do not.
48: .Pp
49: All other input lines provide free-form text to be printed;
50: the formatting of free-form text depends on the respective
51: processing context.
1.1 kristaps 52: .Sh LANGUAGE SYNTAX
53: .Nm
54: documents may contain only graphable 7-bit ASCII characters, the space
1.17 schwarze 55: character, and, in certain circumstances, the tab character.
56: To produce other characters in the output, use the escape sequences
57: documented in the
58: .Xr mandoc_char 7
59: manual.
60: .Pp
61: All manuals must have
1.1 kristaps 62: .Ux
63: line terminators.
1.17 schwarze 64: .Sh REQUEST SYNTAX
65: A request or macro line consists of:
66: .Pp
67: .Bl -enum -compact
68: .It
69: the control character
70: .Sq \&.
1.1 kristaps 71: or
1.17 schwarze 72: .Sq \(aq
73: at the beginning of the line,
74: .It
75: optionally an arbitrary amount of whitespace,
76: .It
77: the name of the request or the macro, which is one word of arbitrary
78: length, terminated by whitespace,
79: .It
80: and zero or more arguments delimited by whitespace.
81: .El
82: .Pp
83: Thus, the following request lines are all equivalent:
1.1 kristaps 84: .Bd -literal -offset indent
1.17 schwarze 85: \&.ig end
86: \&.ig end
87: \&. ig end
1.1 kristaps 88: .Ed
1.24 ! schwarze 89: .Sh MACRO SYNTAX
! 90: Macros can be defined by the
! 91: .Sx \&de
! 92: request.
! 93: When called, they follow the same syntax as requests, except that
! 94: macro arguments may optionally be quoted by enclosing them
! 95: in double quote characters
! 96: .Pq Sq \(dq .
! 97: To be recognized as the beginning of a quoted argument, the opening
! 98: quote character must be preceded by a space character.
! 99: .Pp
! 100: A quoted argument may contain whitespace, and pairs of double quote
! 101: characters
! 102: .Pq Sq Qq
! 103: resolve to single double quote characters.
! 104: A quoted argument extends to the next double quote character that is not
! 105: part of a pair, or to the end of the input line, whichever comes earlier.
! 106: Leaving out the terminating double quote character at the end of the line
! 107: is discouraged.
! 108: For clarity, if more arguments follow on the same input line,
! 109: it is recommended to follow the terminating double quote character
! 110: by a space character; in case the next character after the terminating
! 111: double quote character is anything else, it is regarded as the beginning
! 112: of the next, unquoted argument.
! 113: .Pp
! 114: Both in quoted and unquoted arguments, pairs of backslashes
! 115: .Pq Sq \e\e
! 116: resolve to single backslashes.
! 117: In unquoted arguments, space characters can alternatively be included
! 118: by preceding them with a backslash
! 119: .Pq Sq \e\~ ,
! 120: but quoting is usually better for clarity.
1.15 kristaps 121: .Sh REQUEST REFERENCE
1.17 schwarze 122: The
1.15 kristaps 123: .Xr mandoc 1
124: .Nm
1.17 schwarze 125: parser recognizes the following requests.
126: Note that the
1.15 kristaps 127: .Nm
1.17 schwarze 128: language defines many more requests not implemented in
1.15 kristaps 129: .Xr mandoc 1 .
130: .Ss \&ad
131: Set line adjustment mode.
132: This line-scoped request is intended to have one argument to select
133: normal, left, right, or center adjustment for subsequent text.
134: Currently, it is ignored including its arguments,
135: and the number of arguments is not checked.
1.3 kristaps 136: .Ss \&am
1.15 kristaps 137: Append to a macro definition.
138: The syntax of this request is the same as that of
139: .Sx \&de .
140: It is currently ignored by
141: .Xr mandoc 1 ,
142: as are its children.
1.3 kristaps 143: .Ss \&ami
1.15 kristaps 144: Append to a macro definition, specifying the macro name indirectly.
145: The syntax of this request is the same as that of
146: .Sx \&dei .
147: It is currently ignored by
148: .Xr mandoc 1 ,
149: as are its children.
1.3 kristaps 150: .Ss \&am1
1.15 kristaps 151: Append to a macro definition, switching roff compatibility mode off
152: during macro execution.
153: The syntax of this request is the same as that of
154: .Sx \&de1 .
155: It is currently ignored by
156: .Xr mandoc 1 ,
157: as are its children.
1.3 kristaps 158: .Ss \&de
1.17 schwarze 159: Define a
1.15 kristaps 160: .Nm
161: macro.
162: Its syntax can be either
163: .Bd -literal -offset indent
164: .Pf . Cm \&de Ar name
165: .Ar macro definition
166: \&..
167: .Ed
168: .Pp
169: or
170: .Bd -literal -offset indent
171: .Pf . Cm \&de Ar name Ar end
172: .Ar macro definition
173: .Pf . Ar end
174: .Ed
175: .Pp
176: Both forms define or redefine the macro
177: .Ar name
178: to represent the
179: .Ar macro definition ,
180: which may consist of one or more input lines, including the newline
181: characters terminating each line, optionally containing calls to
182: .Nm
183: requests,
184: .Nm
185: macros or high-level macros like
186: .Xr man 7
187: or
188: .Xr mdoc 7
189: macros, whichever applies to the document in question.
190: .Pp
191: Specifying a custom
192: .Ar end
193: macro works in the same way as for
194: .Sx \&ig ;
195: namely, the call to
196: .Sq Pf . Ar end
197: first ends the
198: .Ar macro definition ,
199: and after that, it is also evaluated as a
200: .Nm
201: request or
202: .Nm
203: macro, but not as a high-level macro.
204: .Pp
1.17 schwarze 205: The macro can be invoked later using the syntax
1.15 kristaps 206: .Pp
207: .D1 Pf . Ar name Op Ar argument Op Ar argument ...
208: .Pp
1.24 ! schwarze 209: Regarding argument parsing, see
! 210: .Sx MACRO SYNTAX
! 211: above.
1.15 kristaps 212: .Pp
1.17 schwarze 213: The line invoking the macro will be replaced
1.15 kristaps 214: in the input stream by the
215: .Ar macro definition ,
216: replacing all occurrences of
217: .No \e\e$ Ns Ar N ,
1.17 schwarze 218: where
1.15 kristaps 219: .Ar N
220: is a digit, by the
221: .Ar N Ns th Ar argument .
222: For example,
223: .Bd -literal -offset indent
224: \&.de ZN
225: \efI\e^\e\e$1\e^\efP\e\e$2
226: \&..
227: \&.ZN XtFree .
228: .Ed
229: .Pp
230: produces
231: .Pp
232: .D1 \efI\e^XtFree\e^\efP.
233: .Pp
234: in the input stream, and thus in the output: \fI\^XtFree\^\fP.
235: .Pp
1.17 schwarze 236: Since macros and user-defined strings share a common string table,
1.15 kristaps 237: defining a macro
238: .Ar name
239: clobbers the user-defined string
240: .Ar name ,
241: and the
242: .Ar macro definition
243: can also be printed using the
244: .Sq \e*
245: string interpolation syntax described below
246: .Sx ds ,
247: but this is rarely useful because every macro definition contains at least
248: one explicit newline character.
1.16 schwarze 249: .Pp
250: In order to prevent endless recursion, both groff and
251: .Xr mandoc 1
252: limit the stack depth for expanding macros and strings
253: to a large, but finite number.
254: Do not rely on the exact value of this limit.
1.3 kristaps 255: .Ss \&dei
1.17 schwarze 256: Define a
1.15 kristaps 257: .Nm
258: macro, specifying the macro name indirectly.
1.17 schwarze 259: The syntax of this request is the same as that of
1.15 kristaps 260: .Sx \&de .
261: It is currently ignored by
262: .Xr mandoc 1 ,
263: as are its children.
264: .Ss \&de1
1.17 schwarze 265: Define a
1.15 kristaps 266: .Nm
267: macro that will be executed with
268: .Nm
269: compatibility mode switched off during macro execution.
270: This is a GNU extension not available in traditional
271: .Nm
272: implementations and not even in older versions of groff.
273: Since
274: .Xr mandoc 1
275: does not implement
276: .Nm
1.17 schwarze 277: compatibility mode at all, it handles this request as an alias for
1.15 kristaps 278: .Sx \&de .
1.6 schwarze 279: .Ss \&ds
1.15 kristaps 280: Define a user-defined string.
1.13 kristaps 281: Its syntax is as follows:
282: .Pp
1.15 kristaps 283: .D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
1.13 kristaps 284: .Pp
285: The
1.15 kristaps 286: .Ar name
1.13 kristaps 287: and
1.15 kristaps 288: .Ar string
289: arguments are space-separated.
290: If the
291: .Ar string
292: begins with a double-quote character, that character will not be part
293: of the string.
294: All remaining characters on the input line form the
295: .Ar string ,
296: including whitespace and double-quote characters, even trailing ones.
297: .Pp
1.13 kristaps 298: The
1.15 kristaps 299: .Ar string
300: can be interpolated into subsequent text by using
301: .No \e* Ns Bq Ar name
302: for a
303: .Ar name
304: of arbitrary length, or \e*(NN or \e*N if the length of
305: .Ar name
306: is two or one characters, respectively.
1.17 schwarze 307: Interpolation can be prevented by escaping the leading backslash;
308: that is, an asterisk preceded by an even number of backslashes
309: does not trigger string interpolation.
1.15 kristaps 310: .Pp
311: Since user-defined strings and macros share a common string table,
312: defining a string
313: .Ar name
1.17 schwarze 314: clobbers the macro
1.15 kristaps 315: .Ar name ,
316: and the
317: .Ar name
318: used for defining a string can also be invoked as a macro,
319: in which case the following input line will be appended to the
320: .Ar string ,
321: forming a new input line passed to the
322: .Nm
323: parser.
324: For example,
325: .Bd -literal -offset indent
326: \&.ds badidea .S
327: \&.badidea
328: H SYNOPSIS
329: .Ed
330: .Pp
331: invokes the
332: .Cm SH
333: macro when used in a
334: .Xr man 7
335: document.
336: Such abuse is of course strongly discouraged.
1.5 kristaps 337: .Ss \&el
338: The
339: .Qq else
340: half of an if/else conditional.
341: Pops a result off the stack of conditional evaluations pushed by
342: .Sx \&ie
343: and uses it as its conditional.
344: If no stack entries are present (e.g., due to no prior
345: .Sx \&ie
346: calls)
347: then false is assumed.
1.17 schwarze 348: The syntax of this request is similar to
1.5 kristaps 349: .Sx \&if
350: except that the conditional is missing.
1.15 kristaps 351: .Ss \&hy
352: Set automatic hyphenation mode.
353: This line-scoped request is currently ignored.
1.5 kristaps 354: .Ss \&ie
355: The
356: .Qq if
357: half of an if/else conditional.
358: The result of the conditional is pushed into a stack used by subsequent
359: invocations of
360: .Sx \&el ,
361: which may be separated by any intervening input (or not exist at all).
362: Its syntax is equivalent to
363: .Sx \&if .
1.1 kristaps 364: .Ss \&if
1.7 schwarze 365: Begins a conditional.
366: Right now, the conditional evaluates to true
367: if and only if it starts with the letter
368: .Sy n ,
1.17 schwarze 369: indicating processing in nroff style as opposed to troff style.
1.3 kristaps 370: If a conditional is false, its children are not processed, but are
371: syntactically interpreted to preserve the integrity of the input
372: document.
373: Thus,
374: .Pp
1.17 schwarze 375: .D1 \&.if t .ig
1.3 kristaps 376: .Pp
377: will discard the
378: .Sq \&.ig ,
379: which may lead to interesting results, but
380: .Pp
1.17 schwarze 381: .D1 \&.if t .if t \e{\e
1.3 kristaps 382: .Pp
383: will continue to syntactically interpret to the block close of the final
384: conditional.
385: Sub-conditionals, in this case, obviously inherit the truth value of
386: the parent.
1.17 schwarze 387: This request has the following syntax:
388: .Bd -literal -offset indent
1.1 kristaps 389: \&.if COND \e{\e
390: BODY...
391: \&.\e}
392: .Ed
1.17 schwarze 393: .Bd -literal -offset indent
1.1 kristaps 394: \&.if COND \e{ BODY
1.2 kristaps 395: BODY... \e}
396: .Ed
1.17 schwarze 397: .Bd -literal -offset indent
1.2 kristaps 398: \&.if COND \e{ BODY
1.1 kristaps 399: BODY...
400: \&.\e}
401: .Ed
1.17 schwarze 402: .Bd -literal -offset indent
1.1 kristaps 403: \&.if COND \e
404: BODY
405: .Ed
406: .Pp
1.9 kristaps 407: COND is a conditional statement.
408: roff allows for complicated conditionals; mandoc is much simpler.
409: At this time, mandoc supports only
410: .Sq n ,
411: evaluating to true;
412: and
413: .Sq t ,
414: .Sq e ,
415: and
416: .Sq o ,
417: evaluating to false.
418: All other invocations are read up to the next end of line or space and
419: evaluate as false.
1.1 kristaps 420: .Pp
421: If the BODY section is begun by an escaped brace
422: .Sq \e{ ,
1.17 schwarze 423: scope continues until a closing-brace escape sequence
1.1 kristaps 424: .Sq \.\e} .
1.17 schwarze 425: If the BODY is not enclosed in braces, scope continues until
426: the end of the line.
1.1 kristaps 427: If the COND is followed by a BODY on the same line, whether after a
1.17 schwarze 428: brace or not, then requests and macros
1.1 kristaps 429: .Em must
430: begin with a control character.
431: It is generally more intuitive, in this case, to write
432: .Bd -literal -offset indent
433: \&.if COND \e{\e
434: \&.foo
435: bar
436: \&.\e}
437: .Ed
438: .Pp
1.17 schwarze 439: than having the request or macro follow as
1.1 kristaps 440: .Pp
441: .D1 \&.if COND \e{ .foo
442: .Pp
443: The scope of a conditional is always parsed, but only executed if the
444: conditional evaluates to true.
445: .Pp
1.17 schwarze 446: Note that text following an
1.2 kristaps 447: .Sq \&.\e}
1.17 schwarze 448: escape sequence is discarded.
1.2 kristaps 449: Furthermore, if an explicit closing sequence
1.1 kristaps 450: .Sq \e}
1.2 kristaps 451: is specified in a free-form line, the entire line is accepted within the
1.17 schwarze 452: scope of the prior request, not only the text preceding the close, with the
1.8 kristaps 453: .Sq \e}
454: collapsing into a zero-width space.
1.1 kristaps 455: .Ss \&ig
1.2 kristaps 456: Ignore input.
1.15 kristaps 457: Its syntax can be either
458: .Bd -literal -offset indent
459: .Pf . Cm \&ig
460: .Ar ignored text
1.2 kristaps 461: \&..
462: .Ed
1.15 kristaps 463: .Pp
464: or
465: .Bd -literal -offset indent
466: .Pf . Cm \&ig Ar end
467: .Ar ignored text
468: .Pf . Ar end
1.2 kristaps 469: .Ed
470: .Pp
471: In the first case, input is ignored until a
472: .Sq \&..
1.17 schwarze 473: request is encountered on its own line.
1.15 kristaps 474: In the second case, input is ignored until the specified
475: .Sq Pf . Ar end
476: macro is encountered.
477: Do not use the escape character
1.2 kristaps 478: .Sq \e
1.15 kristaps 479: anywhere in the definition of
480: .Ar end ;
481: it would cause very strange behaviour.
482: .Pp
483: When the
484: .Ar end
485: macro is a roff request or a roff macro, like in
1.2 kristaps 486: .Pp
487: .D1 \&.ig if
488: .Pp
489: the subsequent invocation of
490: .Sx \&if
1.15 kristaps 491: will first terminate the
492: .Ar ignored text ,
493: then be invoked as usual.
494: Otherwise, it only terminates the
495: .Ar ignored text ,
496: and arguments following it or the
497: .Sq \&..
1.17 schwarze 498: request are discarded.
1.15 kristaps 499: .Ss \&ne
500: Declare the need for the specified minimum vertical space
501: before the next trap or the bottom of the page.
502: This line-scoped request is currently ignored.
503: .Ss \&nh
504: Turn off automatic hyphenation mode.
505: This line-scoped request is currently ignored.
1.6 schwarze 506: .Ss \&rm
507: Remove a request, macro or string.
1.15 kristaps 508: This request is intended to have one argument,
1.6 schwarze 509: the name of the request, macro or string to be undefined.
510: Currently, it is ignored including its arguments,
511: and the number of arguments is not checked.
1.10 kristaps 512: .Ss \&nr
513: Define a register.
514: A register is an arbitrary string value that defines some sort of state,
515: which influences parsing and/or formatting.
516: Its syntax is as follows:
517: .Pp
1.15 kristaps 518: .D1 Pf \. Cm \&nr Ar name Ar value
1.10 kristaps 519: .Pp
520: The
1.15 kristaps 521: .Ar value
1.10 kristaps 522: may, at the moment, only be an integer.
1.15 kristaps 523: So far, only the following register
524: .Ar name
525: is recognised:
1.10 kristaps 526: .Bl -tag -width Ds
527: .It Cm nS
528: If set to a positive integer value, certain
529: .Xr mdoc 7
1.17 schwarze 530: macros will behave in the same way as in the
1.10 kristaps 531: .Em SYNOPSIS
1.11 kristaps 532: section.
1.17 schwarze 533: If set to 0, these macros will behave in the same way as outside the
534: .Em SYNOPSIS
535: section, even when called within the
1.10 kristaps 536: .Em SYNOPSIS
1.17 schwarze 537: section itself.
538: Note that starting a new
1.11 kristaps 539: .Xr mdoc 7
1.17 schwarze 540: section with the
541: .Cm \&Sh
542: macro will reset this register.
1.10 kristaps 543: .El
1.15 kristaps 544: .Ss \&so
545: Include a source file.
546: Its syntax is as follows:
547: .Pp
548: .D1 Pf \. Cm \&so Ar file
549: .Pp
550: The
551: .Ar file
552: will be read and its contents processed as input in place of the
553: .Sq \&.so
554: request line.
555: To avoid inadvertant inclusion of unrelated files,
556: .Xr mandoc 1
557: only accepts relative paths not containing the strings
558: .Qq ../
559: and
560: .Qq /.. .
1.6 schwarze 561: .Ss \&tr
562: Output character translation.
1.17 schwarze 563: This request is intended to have one argument,
1.6 schwarze 564: consisting of an even number of characters.
565: Currently, it is ignored including its arguments,
566: and the number of arguments is not checked.
1.20 kristaps 567: .Ss \&T&
568: Re-start a table layout, retaining the options of the prior table
569: invocation.
570: See
571: .Sx \&TS .
572: .Ss \&TE
573: End a table context.
574: See
575: .Sx \&TS .
576: .Ss \&TS
577: Begin a table, which formats input in aligned rows and columns.
1.23 kristaps 578: See
579: .Xr tbl 7
580: for a description of the tbl language.
1.2 kristaps 581: .Sh COMPATIBILITY
582: This section documents compatibility between mandoc and other other
1.17 schwarze 583: .Nm
584: implementations, at this time limited to GNU troff
1.2 kristaps 585: .Pq Qq groff .
586: The term
587: .Qq historic groff
1.17 schwarze 588: refers to groff version 1.15.
1.2 kristaps 589: .Pp
590: .Bl -dash -compact
1.10 kristaps 591: .It
592: The
593: .Cm nS
1.17 schwarze 594: register is only compatible with OpenBSD's groff-1.15.
1.2 kristaps 595: .It
1.17 schwarze 596: Historic groff did not accept white-space before a custom
597: .Ar end
598: macro for the
1.2 kristaps 599: .Sx \&ig
1.17 schwarze 600: request.
1.4 kristaps 601: .It
602: The
603: .Sx \&if
604: and family would print funny white-spaces with historic groff when
1.17 schwarze 605: using the next-line syntax.
1.2 kristaps 606: .El
1.17 schwarze 607: .Sh SEE ALSO
608: .Xr mandoc 1 ,
609: .Xr man 7 ,
610: .Xr mandoc_char 7 ,
1.23 kristaps 611: .Xr mdoc 7 ,
612: .Xr tbl 7
1.17 schwarze 613: .Rs
614: .%A Joseph F. Ossanna
615: .%A Brian W. Kernighan
616: .%I AT&T Bell Laboratories
617: .%T Troff User's Manual
618: .%R Computing Science Technical Report
619: .%N 54
620: .%C Murray Hill, New Jersey
621: .%D 1976 and 1992
622: .%U http://www.kohala.com/start/troff/cstr54.ps
623: .Re
624: .Rs
625: .%A Joseph F. Ossanna
626: .%A Brian W. Kernighan
627: .%A Gunnar Ritter
628: .%T Heirloom Documentation Tools Nroff/Troff User's Manual
629: .%D September 17, 2007
630: .%U http://heirloom.sourceforge.net/doctools/troff.pdf
631: .Re
632: .Sh HISTORY
633: The RUNOFF typesetting system was written in PL/1 for the CTSS
634: operating system by Jerome ("Jerry") E. Saltzer in 1961.
635: It was first used as the main documentation tool by Multics since 1963.
636: Robert ("Bob") H. Morris ported it to the GE-635 and called it
637: .Nm ,
638: Doug McIlroy rewrote it in BCPL in 1969,
639: Joseph F. Ossanna rewrote it in PDP-11 assembly in 1973,
640: and Brian W. Kernighan rewrote it in C in 1975.
1.1 kristaps 641: .Sh AUTHORS
1.15 kristaps 642: .An -nosplit
643: This partial
1.1 kristaps 644: .Nm
645: reference was written by
1.15 kristaps 646: .An Kristaps Dzonsons Aq kristaps@bsd.lv
647: and
648: .An Ingo Schwarze Aq schwarze@openbsd.org .
CVSweb