Annotation of mandoc/roff.7, Revision 1.21
1.21 ! kristaps 1: .\" $Id: roff.7,v 1.20 2011/01/03 16:04:41 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.21 ! kristaps 18: .Dd $Mdocdate: January 3 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.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.20 kristaps 538: .Ss \&T&
539: Re-start a table layout, retaining the options of the prior table
540: invocation.
541: See
542: .Sx \&TS .
543: .Ss \&TE
544: End a table context.
545: See
546: .Sx \&TS .
547: .Ss \&TS
548: Begin a table, which formats input in aligned rows and columns.
549: A table consists of an optional single line of table options terminated
550: by a semicolon, followed by one or more lines of layout specification
551: terminated by a period, then table data.
552: A table block may also include
553: .Nm ,
554: .Xr mdoc 7 ,
555: or
556: .Xr man 7
557: macros.
558: Example:
559: .Bd -literal -offset indent
560: \&.TS
561: box tab(:); \e" Table-wide options.
562: c | c \e" Layout for first line.
563: | c | c. \e" Layout for all subsequent lines.
564: 1:2 \e" Data...
565: 3:4
566: \&.TE
567: .Ed
568: .Pp
569: Table data is
570: .Em pre-processed ,
571: that is, data rows are parsed then inserted into the underlying stream
572: of input data.
573: This allows data rows to be interspersed by arbitrary macros, such as
574: .Bd -literal -offset indent
575: \&.TS
576: tab(:);
577: c c c.
578: 1:2:3
579: \&.Ao
580: 3:2:1
581: \&.Ac
582: \&.TE
583: .Ed
584: .Pp
585: in the case of
586: .Xr mdoc 7
587: or
588: .Bd -literal -offset indent
589: \&.TS
590: tab(:);
591: c c c.
592: \&.ds ab 2
593: 1:\e*(ab:3
594: \&.I
595: 3:2:1
596: \&.TE
597: .Ed
598: .Pp
599: in the case of
600: .Xr man 7 .
601: .Pp
602: The first line of a table consists of its options, which consists of
603: space-separated keys and modifiers terminated by a semicolon.
604: If the first line does not have a terminating semicolon, it is assumed
605: that no options are specified and instead a layout is processed.
606: Some options accept arguments enclosed by paranthesis.
607: The following case-insensitive options are available:
608: .Bl -tag -width Ds
609: .It Cm center
610: This option is not supported by
611: .Xr mandoc 1 .
612: This may also be invoked with
613: .Cm centre .
614: .It Cm delim
615: Accepts a two-character argument.
616: This option is not supported by
617: .Xr mandoc 1 .
618: .It Cm expand
619: This option is not supported by
620: .Xr mandoc 1 .
621: .It Cm box
622: Draw a single-line box around the table.
623: This may also be invoked with
624: .Cm frame .
625: .It Cm doublebox
626: Draw a double-line box around the table.
627: This may also be invoked with
628: .Cm doubleframe .
629: .It Cm allbox
630: This option is not supported by
631: .Xr mandoc 1 .
632: .It Cm tab
633: Accepts a single-character argument.
634: This character is used a delimiter between data cells, which otherwise
635: defaults to the tab character.
636: .It Cm linesize
637: Accepts a natural number (all digits).
638: This option is not supported by
639: .Xr mandoc 1 .
640: .It Cm nokeep
641: This option is not supported by
642: .Xr mandoc 1 .
643: .It Cm decimalpoint
644: Accepts a single-character argument.
645: This character will be used as the decimal point with the
646: .Cm n
647: layout key.
648: This option is not supported by
649: .Xr mandoc 1 .
650: .It Cm nospaces
651: This option is not supported by
652: .Xr mandoc 1 .
653: .El
654: .Pp
655: The table layout follows table options, except in the case of
656: .Sx \&T& ,
657: where it immediately procedes invocation.
658: Layout specifies how data rows are displayed on output.
659: Each layout line corresponds to a line of data; the last layout line
660: applies to all remaining data lines.
661: Layout lines may also be separated by a comma.
662: Each layout cell consists of one of the following case-insensitive keys:
663: .Bl -tag -width Ds
664: .It Cm c
665: Centre a literal string within its column.
666: .It Cm r
667: Right-justify a literal string within its column.
668: .It Cm l
669: Left-justify a literal string within its column.
670: .It Cm n
671: Justify a number around its decimal point.
672: If the decimal point is not found on the number, it's assumed to trail
673: the number.
674: .It Cm s
675: This option is not supported by
676: .Xr mandoc 1 .
677: .It Cm a
678: This option is not supported by
679: .Xr mandoc 1 .
680: .It Cm ^
681: This option is not supported by
682: .Xr mandoc 1 .
683: .It Cm \-
1.21 ! kristaps 684: Replace the data cell (its contents will be lost) with a single
! 685: horizontal line.
1.20 kristaps 686: This may also be invoked with
687: .Cm _ .
688: .It Cm =
1.21 ! kristaps 689: Replace the data cell (its contents will be lost) with a double
! 690: horizontal line.
1.20 kristaps 691: .It Cm \(ba
692: Emit a vertical bar instead of data.
693: .It Cm \(ba\(ba
694: Emit a double-vertical bar instead of data.
695: .El
696: .Pp
1.21 ! kristaps 697: For example, following layout specifies a centre-justified column of
! 698: minimum width 10, followed by vertical bar, followed by a left-justified
! 699: column of minimum width 10, another vertical bar, then a column
! 700: justified about the decimal point in numbers:
! 701: .Pp
! 702: .Dl c10 | l10 | n
! 703: .Pp
1.20 kristaps 704: Keys may be followed by a set of modifiers.
705: A modifier is either a modifier key or a natural number for specifying
706: spacing.
707: The following case-insensitive modifier keys are available:
1.21 ! kristaps 708: .Cm z ,
! 709: .Cm u ,
! 710: .Cm e ,
! 711: .Cm t ,
! 712: .Cm d ,
! 713: .Cm f ,
! 714: .Cm b ,
! 715: .Cm i ,
! 716: .Cm b ,
! 717: and
! 718: .Cm i .
! 719: All of these are ignored by
! 720: .Xr mandoc 1 .
! 721: .Pp
! 722: The data section follows the last layout row.
! 723: By default, cells in a data section are delimited by a tab.
! 724: This behaviour may be changed with the
! 725: .Cm tab
! 726: option.
! 727: If
! 728: .Cm _
! 729: or
! 730: .Cm =
! 731: is specified, a single or double line, respectively, is drawn across the
! 732: data field.
! 733: If
! 734: .Cm \e-
! 735: or
! 736: .Cm \e=
! 737: is specified, a line is drawn within the data field (i.e., terminating
! 738: within the cell and not draw to the border).
1.2 kristaps 739: .Sh COMPATIBILITY
740: This section documents compatibility between mandoc and other other
1.17 schwarze 741: .Nm
742: implementations, at this time limited to GNU troff
1.2 kristaps 743: .Pq Qq groff .
744: The term
745: .Qq historic groff
1.17 schwarze 746: refers to groff version 1.15.
1.2 kristaps 747: .Pp
748: .Bl -dash -compact
1.10 kristaps 749: .It
750: The
751: .Cm nS
1.17 schwarze 752: register is only compatible with OpenBSD's groff-1.15.
1.2 kristaps 753: .It
1.17 schwarze 754: Historic groff did not accept white-space before a custom
755: .Ar end
756: macro for the
1.2 kristaps 757: .Sx \&ig
1.17 schwarze 758: request.
1.4 kristaps 759: .It
760: The
761: .Sx \&if
762: and family would print funny white-spaces with historic groff when
1.17 schwarze 763: using the next-line syntax.
1.2 kristaps 764: .El
1.17 schwarze 765: .Sh SEE ALSO
766: .Xr mandoc 1 ,
767: .Xr man 7 ,
768: .Xr mandoc_char 7 ,
769: .Xr mdoc 7
1.21 ! kristaps 770: .Rs
! 771: .%A M. E. Lesk
! 772: .%T Tbl\(emA Program to Format Tables
! 773: .%D June 11, 1976
! 774: .%U http://www.kohala.com/start/troff/v7/man/tbl/tbl.ps
! 775: .Re
1.17 schwarze 776: .Rs
777: .%A Joseph F. Ossanna
778: .%A Brian W. Kernighan
779: .%I AT&T Bell Laboratories
780: .%T Troff User's Manual
781: .%R Computing Science Technical Report
782: .%N 54
783: .%C Murray Hill, New Jersey
784: .%D 1976 and 1992
785: .%U http://www.kohala.com/start/troff/cstr54.ps
786: .Re
787: .Rs
788: .%A Joseph F. Ossanna
789: .%A Brian W. Kernighan
790: .%A Gunnar Ritter
791: .%T Heirloom Documentation Tools Nroff/Troff User's Manual
792: .%D September 17, 2007
793: .%U http://heirloom.sourceforge.net/doctools/troff.pdf
794: .Re
795: .Sh HISTORY
796: The RUNOFF typesetting system was written in PL/1 for the CTSS
797: operating system by Jerome ("Jerry") E. Saltzer in 1961.
798: It was first used as the main documentation tool by Multics since 1963.
799: Robert ("Bob") H. Morris ported it to the GE-635 and called it
800: .Nm ,
801: Doug McIlroy rewrote it in BCPL in 1969,
802: Joseph F. Ossanna rewrote it in PDP-11 assembly in 1973,
803: and Brian W. Kernighan rewrote it in C in 1975.
1.1 kristaps 804: .Sh AUTHORS
1.15 kristaps 805: .An -nosplit
806: This partial
1.1 kristaps 807: .Nm
808: reference was written by
1.15 kristaps 809: .An Kristaps Dzonsons Aq kristaps@bsd.lv
810: and
811: .An Ingo Schwarze Aq schwarze@openbsd.org .
CVSweb