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