Annotation of mandoc/roff.7, Revision 1.20
1.20 ! kristaps 1: .\" $Id: roff.7,v 1.19 2010/12/29 15:21:34 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.19 kristaps 18: .Dd $Mdocdate: December 29 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.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 \-
! 684: This may also be invoked with
! 685: .Cm _ .
! 686: .It Cm =
! 687: .It Cm \(ba
! 688: Emit a vertical bar instead of data.
! 689: .It Cm \(ba\(ba
! 690: Emit a double-vertical bar instead of data.
! 691: .El
! 692: .Pp
! 693: Keys may be followed by a set of modifiers.
! 694: A modifier is either a modifier key or a natural number for specifying
! 695: spacing.
! 696: The following case-insensitive modifier keys are available:
! 697: .Bl -tag -width Ds
! 698: .It Cm z
! 699: .It Cm u
! 700: .It Cm e
! 701: .It Cm t
! 702: .It Cm d
! 703: .It Cm f
! 704: Must be followed by a case-insensitive font style:
! 705: .Cm b
! 706: for bold or
! 707: .Cm i
! 708: for italic.
! 709: .It Cm b
! 710: .It Cm i
! 711: .El
1.2 kristaps 712: .Sh COMPATIBILITY
713: This section documents compatibility between mandoc and other other
1.17 schwarze 714: .Nm
715: implementations, at this time limited to GNU troff
1.2 kristaps 716: .Pq Qq groff .
717: The term
718: .Qq historic groff
1.17 schwarze 719: refers to groff version 1.15.
1.2 kristaps 720: .Pp
721: .Bl -dash -compact
1.10 kristaps 722: .It
723: The
724: .Cm nS
1.17 schwarze 725: register is only compatible with OpenBSD's groff-1.15.
1.2 kristaps 726: .It
1.17 schwarze 727: Historic groff did not accept white-space before a custom
728: .Ar end
729: macro for the
1.2 kristaps 730: .Sx \&ig
1.17 schwarze 731: request.
1.4 kristaps 732: .It
733: The
734: .Sx \&if
735: and family would print funny white-spaces with historic groff when
1.17 schwarze 736: using the next-line syntax.
1.2 kristaps 737: .El
1.17 schwarze 738: .Sh SEE ALSO
739: .Xr mandoc 1 ,
740: .Xr man 7 ,
741: .Xr mandoc_char 7 ,
742: .Xr mdoc 7
1.19 kristaps 743: .\" .Rs
744: .\" .%A M. E. Lesk
745: .\" .%T Tbl\(emA Program to Format Tables
746: .\" .%D June 11, 1976
747: .\" .%U http://www.kohala.com/start/troff/v7/man/tbl/tbl.ps
748: .\" .Re
1.17 schwarze 749: .Rs
750: .%A Joseph F. Ossanna
751: .%A Brian W. Kernighan
752: .%I AT&T Bell Laboratories
753: .%T Troff User's Manual
754: .%R Computing Science Technical Report
755: .%N 54
756: .%C Murray Hill, New Jersey
757: .%D 1976 and 1992
758: .%U http://www.kohala.com/start/troff/cstr54.ps
759: .Re
760: .Rs
761: .%A Joseph F. Ossanna
762: .%A Brian W. Kernighan
763: .%A Gunnar Ritter
764: .%T Heirloom Documentation Tools Nroff/Troff User's Manual
765: .%D September 17, 2007
766: .%U http://heirloom.sourceforge.net/doctools/troff.pdf
767: .Re
768: .Sh HISTORY
769: The RUNOFF typesetting system was written in PL/1 for the CTSS
770: operating system by Jerome ("Jerry") E. Saltzer in 1961.
771: It was first used as the main documentation tool by Multics since 1963.
772: Robert ("Bob") H. Morris ported it to the GE-635 and called it
773: .Nm ,
774: Doug McIlroy rewrote it in BCPL in 1969,
775: Joseph F. Ossanna rewrote it in PDP-11 assembly in 1973,
776: and Brian W. Kernighan rewrote it in C in 1975.
1.1 kristaps 777: .Sh AUTHORS
1.15 kristaps 778: .An -nosplit
779: This partial
1.1 kristaps 780: .Nm
781: reference was written by
1.15 kristaps 782: .An Kristaps Dzonsons Aq kristaps@bsd.lv
783: and
784: .An Ingo Schwarze Aq schwarze@openbsd.org .
CVSweb