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