1 ROFF(5) Standards, Environments, and Macros ROFF(5)
2
3 NAME
4 roff - roff language reference for mandoc
5
6 DESCRIPTION
7 The roff language is a general purpose text formatting language. Since
8 traditional implementations of the mdoc(5) and man(5) manual formatting
9 languages are based on it, many real-world manuals use small numbers of
10 roff requests and escape sequences intermixed with their mdoc(5) or
11 man(5) code. To properly format such manuals, the mandoc(1) utility
12 supports a tiny subset of roff requests and escapes. Only these requests
13 and escapes supported by mandoc(1) are documented in the present manual,
14 together with the basic language syntax shared by roff, mdoc(5), and
15 man(5). For complete roff manuals, consult the SEE ALSO section.
16
17 Input lines beginning with the control character `.' are parsed for
18 requests and macros. Such lines are called "request lines" or "macro
19 lines", respectively. Requests change the processing state and
20 manipulate the formatting; some macros also define the document structure
21 and produce formatted output. The single quote ("'") is accepted as an
22 alternative control character, treated by mandoc(1) just like `.'
23
24 Lines not beginning with control characters are called "text lines".
25 They provide free-form text to be printed; the formatting of the text
26 depends on the respective processing context.
27
28 LANGUAGE SYNTAX
29 roff documents may contain only graphable 7-bit ASCII characters, the
30 space character, and, in certain circumstances, the tab character. The
31 backslash character `\' indicates the start of an escape sequence, used
32 for example for Comments, Special Characters, Predefined Strings, and
33 user-defined strings defined using the ds request. For a listing of
34 escape sequences, consult the ESCAPE SEQUENCE REFERENCE below.
35
36 Comments
37 Text following an escaped double-quote `\"', whether in a request, macro,
38 or text line, is ignored to the end of the line. A request line
39 beginning with a control character and comment escape `.\"' is also
40 ignored. Furthermore, request lines with only a control character and
41 optional trailing whitespace are stripped from input.
42
43 Examples:
44 .\" This is a comment line.
45 .\" The next line is ignored:
46 .
47 .Sh EXAMPLES \" This is a comment, too.
48 example text \" And so is this.
49
50 Special Characters
51 Special characters are used to encode special glyphs and are rendered
52 differently across output media. They may occur in request, macro, and
53 text lines. Sequences begin with the escape character `\' followed by
54 either an open-parenthesis `(' for two-character sequences; an open-
55 bracket `[' for n-character sequences (terminated at a close-bracket
56 `]'); or a single one character sequence.
57
58 Examples:
59 \(em Two-letter em dash escape.
60 \e One-letter backslash escape.
61
62 See mandoc_char(5) for a complete list.
63
64 Text Decoration
65 Terms may be text-decorated using the `\f' escape followed by an
66 indicator: B (bold), I (italic), R (regular), or P (revert to previous
67 mode). A numerical representation 3, 2, or 1 (bold, italic, and regular,
68 respectively) may be used instead. The indicator or numerical
69 representative may be preceded by C (constant-width), which is ignored.
70
71 The two-character indicator `BI' requests a font that is both bold and
72 italic. It may not be portable to old roff implementations.
73
74 Examples:
75 \fBbold\fR
76 Write in bold, then switch to regular font mode.
77 \fIitalic\fP
78 Write in italic, then return to previous font mode.
79 \f(BIbold italic\fP
80 Write in bold italic, then return to previous font mode.
81
82 Text decoration is not recommended for mdoc(5), which encourages semantic
83 annotation.
84
85 Predefined Strings
86 Predefined strings, like Special Characters, mark special output glyphs.
87 Predefined strings are escaped with the slash-asterisk, `\*': single-
88 character `\*X', two-character `\*(XX', and N-character `\*[N]'.
89
90 Examples:
91 \*(Am Two-letter ampersand predefined string.
92 \*q One-letter double-quote predefined string.
93
94 Predefined strings are not recommended for use, as they differ across
95 implementations. Those supported by mandoc(1) are listed in
96 mandoc_char(5). Manuals using these predefined strings are almost
97 certainly not portable.
98
99 Whitespace
100 Whitespace consists of the space character. In text lines, whitespace is
101 preserved within a line. In request and macro lines, whitespace delimits
102 arguments and is discarded.
103
104 Unescaped trailing spaces are stripped from text line input unless in a
105 literal context. In general, trailing whitespace on any input line is
106 discouraged for reasons of portability. In the rare case that a blank
107 character is needed at the end of an input line, it may be forced by
108 `\ \&'.
109
110 Literal space characters can be produced in the output using escape
111 sequences. In macro lines, they can also be included in arguments using
112 quotation; see MACRO SYNTAX for details.
113
114 Blank text lines, which may include whitespace, are only permitted within
115 literal contexts. If the first character of a text line is a space, that
116 line is printed with a leading newline.
117
118 Scaling Widths
119 Many requests and macros support scaled widths for their arguments. The
120 syntax for a scaled width is `[+-]?[0-9]*.[0-9]*[:unit:]', where a
121 decimal must be preceded or followed by at least one digit. Negative
122 numbers, while accepted, are truncated to zero.
123
124 The following scaling units are accepted:
125
126 c centimetre
127 i inch
128 P pica (~1/6 inch)
129 p point (~1/72 inch)
130 f scale `u' by 65536
131 v default vertical span
132 m width of rendered `m' (em) character
133 n width of rendered `n' (en) character
134 u default horizontal span for the terminal
135 M mini-em (~1/100 em)
136
137 Using anything other than `m', `n', or `v' is necessarily non-portable
138 across output media. See COMPATIBILITY.
139
140 If a scaling unit is not provided, the numerical value is interpreted
141 under the default rules of `v' for vertical spaces and `u' for horizontal
142 ones.
143
144 Examples:
145 .Bl -tag -width 2i two-inch tagged list indentation in mdoc(5)
146 .HP 2i two-inch tagged list indentation in man(5)
147 .sp 2v two vertical spaces
148
149 Sentence Spacing
150 Each sentence should terminate at the end of an input line. By doing
151 this, a formatter will be able to apply the proper amount of spacing
152 after the end of sentence (unescaped) period, exclamation mark, or
153 question mark followed by zero or more non-sentence closing delimiters
154 (`)', `]', `'', `"').
155
156 The proper spacing is also intelligently preserved if a sentence ends at
157 the boundary of a macro line.
158
159 Examples:
160 Do not end sentences mid-line like this. Instead,
161 end a sentence like this.
162 A macro would end like this:
163 .Xr mandoc 1 .
164
165 REQUEST SYNTAX
166 A request or macro line consists of:
167
168 1. the control character `.' or `'' at the beginning of the line,
169 2. optionally an arbitrary amount of whitespace,
170 3. the name of the request or the macro, which is one word of arbitrary
171 length, terminated by whitespace,
172 4. and zero or more arguments delimited by whitespace.
173
174 Thus, the following request lines are all equivalent:
175
176 .ig end
177 .ig end
178 . ig end
179
180 MACRO SYNTAX
181 Macros are provided by the mdoc(5) and man(5) languages and can be
182 defined by the de request. When called, they follow the same syntax as
183 requests, except that macro arguments may optionally be quoted by
184 enclosing them in double quote characters (`"'). Quoted text, even if it
185 contains whitespace or would cause a macro invocation when unquoted, is
186 always considered literal text. Inside quoted text, pairs of double
187 quote characters (`""') resolve to single double quote characters.
188
189 To be recognised as the beginning of a quoted argument, the opening quote
190 character must be preceded by a space character. A quoted argument
191 extends to the next double quote character that is not part of a pair, or
192 to the end of the input line, whichever comes earlier. Leaving out the
193 terminating double quote character at the end of the line is discouraged.
194 For clarity, if more arguments follow on the same input line, it is
195 recommended to follow the terminating double quote character by a space
196 character; in case the next character after the terminating double quote
197 character is anything else, it is regarded as the beginning of the next,
198 unquoted argument.
199
200 Both in quoted and unquoted arguments, pairs of backslashes (`\\')
201 resolve to single backslashes. In unquoted arguments, space characters
202 can alternatively be included by preceding them with a backslash (`\ '),
203 but quoting is usually better for clarity.
204
205 Examples:
206 .Fn strlen "const char *s"
207 Group arguments "const char *s" into one function argument.
208 If unspecified, "const", "char", and "*s" would be
209 considered separate arguments.
210 .Op "Fl a"
211 Consider "Fl a" as literal text instead of a flag macro.
212
213 REQUEST REFERENCE
214 The mandoc(1) roff parser recognises the following requests. For
215 requests marked as "ignored" or "unsupported", any arguments are ignored,
216 and the number of arguments is not checked.
217
218 ab [message]
219 Abort processing. Currently unsupported.
220
221 ad [b | c | l | n | r]
222 Set line adjustment mode for subsequent text. Currently ignored.
223
224 af registername format
225 Assign an output format to a number register. Currently ignored.
226
227 aln newname oldname
228 Create an alias for a number register. Currently unsupported.
229
230 als newname oldname
231 Create an alias for a request, string, macro, or diversion.
232
233 am macroname [endmacro]
234 Append to a macro definition. The syntax of this request is the
235 same as that of de.
236
237 am1 macroname [endmacro]
238 Append to a macro definition, switching roff compatibility mode
239 off during macro execution (groff extension). The syntax of this
240 request is the same as that of de1. Since mandoc(1) does not
241 implement roff compatibility mode at all, it handles this request
242 as an alias for am.
243
244 ami macrostring [endstring]
245 Append to a macro definition, specifying the macro name
246 indirectly (groff extension). The syntax of this request is the
247 same as that of dei.
248
249 ami1 macrostring [endstring]
250 Append to a macro definition, specifying the macro name
251 indirectly and switching roff compatibility mode off during macro
252 execution (groff extension). The syntax of this request is the
253 same as that of dei1. Since mandoc(1) does not implement roff
254 compatibility mode at all, it handles this request as an alias
255 for ami.
256
257 as stringname [string]
258 Append to a user-defined string. The syntax of this request is
259 the same as that of ds. If a user-defined string with the
260 specified name does not yet exist, it is set to the empty string
261 before appending.
262
263 as1 stringname [string]
264 Append to a user-defined string, switching roff compatibility
265 mode off during macro execution (groff extension). The syntax of
266 this request is the same as that of ds1. Since mandoc(1) does
267 not implement roff compatibility mode at all, it handles this
268 request as an alias for as.
269
270 asciify divname
271 Fully unformat a diversion. Currently unsupported.
272
273 backtrace
274 Print a backtrace of the input stack. This is a groff extension
275 and currently ignored.
276
277 bd font [curfont] [offset]
278 Artificially embolden by repeated printing with small shifts.
279 Currently ignored.
280
281 bleedat left top width height
282 Set the BleedBox page parameter for PDF generation. This is a
283 Heirloom extension and currently ignored.
284
285 blm macroname
286 Set a blank line trap. Currently unsupported.
287
288 box divname
289 Begin a diversion without including a partially filled line.
290 Currently unsupported.
291
292 boxa divname
293 Add to a diversion without including a partially filled line.
294 Currently unsupported.
295
296 bp [+|-]pagenumber
297 Begin a new page. Currently ignored.
298
299 BP source height width position offset flags label
300 Define a frame and place a picture in it. This is a Heirloom
301 extension and currently unsupported.
302
303 br Break the output line.
304
305 break Break out of a while loop. Currently unsupported.
306
307 breakchar char ...
308 Optional line break characters. This is a Heirloom extension and
309 currently ignored.
310
311 brnl N Break output line after the next N input lines. This is a
312 Heirloom extension and currently ignored.
313
314 brp Break and spread output line. Currently, this is implemented as
315 an alias for br.
316
317 brpnl N
318 Break and spread output line after the next N input lines. This
319 is a Heirloom extension and currently ignored.
320
321 c2 [char]
322 Change the no-break control character. Currently unsupported.
323
324 cc [char]
325 Change the control character. If char is not specified, the
326 control character is reset to `.'. Trailing characters are
327 ignored.
328
329 ce [N] Center the next N input lines without filling. N defaults to 1.
330 An argument of 0 or less ends centering. Currently, high level
331 macros abort centering.
332
333 cf filename
334 Output the contents of a file. Ignored because insecure.
335
336 cflags flags char ...
337 Set character flags. This is a groff extension and currently
338 ignored.
339
340 ch macroname [dist]
341 Change a trap location. Currently ignored.
342
343 char glyphname [string]
344 Define a new glyph. Currently unsupported.
345
346 chop stringname
347 Remove the last character from a macro, string, or diversion.
348 Currently unsupported.
349
350 class classname char ...
351 Define a character class. This is a groff extension and
352 currently ignored.
353
354 close streamname
355 Close an open file. Ignored because insecure.
356
357 CL color text
358 Print text in color. This is a Heirloom extension and currently
359 unsupported.
360
361 color [1 | 0]
362 Activate or deactivate colors. This is a groff extension and
363 currently ignored.
364
365 composite from to
366 Define a name component for composite glyph names. This is a
367 groff extension and currently unsupported.
368
369 continue
370 Immediately start the next iteration of a while loop. Currently
371 unsupported.
372
373 cp [1 | 0]
374 Switch roff compatibility mode on or off. Currently ignored.
375
376 cropat left top width height
377 Set the CropBox page parameter for PDF generation. This is a
378 Heirloom extension and currently ignored.
379
380 cs font [width [emsize]]
381 Constant character spacing mode. Currently ignored.
382
383 cu [N] Underline next N input lines including whitespace. Currently
384 ignored.
385
386 da divname
387 Append to a diversion. Currently unsupported.
388
389 dch macroname [dist]
390 Change a trap location in the current diversion. This is a
391 Heirloom extension and currently unsupported.
392
393 de macroname [endmacro]
394 Define a roff macro. Its syntax can be either
395
396 .de macroname
397 definition
398 ..
399
400 or
401
402 .de macroname endmacro
403 definition
404 .endmacro
405
406 Both forms define or redefine the macro macroname to represent
407 the definition, which may consist of one or more input lines,
408 including the newline characters terminating each line,
409 optionally containing calls to roff requests, roff macros or
410 high-level macros like man(5) or mdoc(5) macros, whichever
411 applies to the document in question.
412
413 Specifying a custom endmacro macro works in the same way as for
414 ig; namely, the call to `.endmacro' first ends the definition,
415 and after that, it is also evaluated as a roff request or roff
416 macro, but not as a high-level macro.
417
418 The macro can be invoked later using the syntax
419
420 .macroname [argument [argument ...]]
421
422 Regarding argument parsing, see MACRO SYNTAX above.
423
424 The line invoking the macro will be replaced in the input stream
425 by the definition, replacing all occurrences of \\$N, where N is
426 a digit, by the Nth argument. For example,
427
428 .de ZN
429 \fI\^\\$1\^\fP\\$2
430 ..
431 .ZN XtFree .
432
433 produces
434
435 \fI\^XtFree\^\fP.
436
437 in the input stream, and thus in the output: XtFree. Each
438 occurrence of \\$* is replaced with all the arguments, joined
439 together with single blank characters.
440
441 Since macros and user-defined strings share a common string
442 table, defining a macro macroname clobbers the user-defined
443 string macroname, and the definition can also be printed using
444 the `\*' string interpolation syntax described below ds, but this
445 is rarely useful because every macro definition contains at least
446 one explicit newline character.
447
448 In order to prevent endless recursion, both groff and mandoc(1)
449 limit the stack depth for expanding macros and strings to a
450 large, but finite number, and mandoc(1) also limits the length of
451 the expanded input line. Do not rely on the exact values of
452 these limits.
453
454 de1 macroname [endmacro]
455 Define a roff macro that will be executed with roff compatibility
456 mode switched off during macro execution. This is a groff
457 extension. Since mandoc(1) does not implement roff compatibility
458 mode at all, it handles this request as an alias for de.
459
460 defcolor newname scheme component ...
461 Define a color name. This is a groff extension and currently
462 ignored.
463
464 dei macrostring [endstring]
465 Define a roff macro, specifying the macro name indirectly (groff
466 extension). The syntax of this request is the same as that of
467 de. The effect is the same as:
468
469 .de \*[macrostring] [\*[endstring]]
470
471 dei1 macrostring [endstring]
472 Define a roff macro that will be executed with roff compatibility
473 mode switched off during macro execution, specifying the macro
474 name indirectly (groff extension). Since mandoc(1) does not
475 implement roff compatibility mode at all, it handles this request
476 as an alias for dei.
477
478 device string ...
479
480 devicem stringname
481 These two requests only make sense with the groff-specific
482 intermediate output format and are unsupported.
483
484 di divname
485 Begin a diversion. Currently unsupported.
486
487 do command [argument ...]
488 Execute roff request or macro line with compatibility mode
489 disabled. Currently unsupported.
490
491 ds stringname [["]string]
492 Define a user-defined string. The stringname and string
493 arguments are space-separated. If the string begins with a
494 double-quote character, that character will not be part of the
495 string. All remaining characters on the input line form the
496 string, including whitespace and double-quote characters, even
497 trailing ones.
498
499 The string can be interpolated into subsequent text by using
500 \*[stringname] for a stringname of arbitrary length, or \*(NN or
501 \*N if the length of stringname is two or one characters,
502 respectively. Interpolation can be prevented by escaping the
503 leading backslash; that is, an asterisk preceded by an even
504 number of backslashes does not trigger string interpolation.
505
506 Since user-defined strings and macros share a common string
507 table, defining a string stringname clobbers the macro
508 stringname, and the stringname used for defining a string can
509 also be invoked as a macro, in which case the following input
510 line will be appended to the string, forming a new input line
511 passed to the roff parser. For example,
512
513 .ds badidea .S
514 .badidea
515 H SYNOPSIS
516
517 invokes the SH macro when used in a man(5) document. Such abuse
518 is of course strongly discouraged.
519
520 ds1 stringname [["]string]
521 Define a user-defined string that will be expanded with roff
522 compatibility mode switched off during string expansion. This is
523 a groff extension. Since mandoc(1) does not implement roff
524 compatibility mode at all, it handles this request as an alias
525 for ds.
526
527 dwh dist macroname
528 Set a location trap in the current diversion. This is a Heirloom
529 extension and currently unsupported.
530
531 dt [dist macroname]
532 Set a trap within a diversion. Currently unsupported.
533
534 ec [char]
535 Enable the escape mechanism and change the escape character. The
536 char argument defaults to the backslash (`\').
537
538 ecr Restore the escape character. Currently unsupported.
539
540 ecs Save the escape character. Currently unsupported.
541
542 el body
543 The "else" half of an if/else conditional. Pops a result off the
544 stack of conditional evaluations pushed by ie and uses it as its
545 conditional. If no stack entries are present (e.g., due to no
546 prior ie calls) then false is assumed. The syntax of this
547 request is similar to if except that the conditional is missing.
548
549 em macroname
550 Set a trap at the end of input. Currently unsupported.
551
552 EN End an equation block. See EQ.
553
554 eo Disable the escape mechanism completely.
555
556 EP End a picture started by BP. This is a Heirloom extension and
557 currently unsupported.
558
559 EQ Begin an equation block. See eqn(5) for a description of the
560 equation language.
561
562 errprint message
563 Print a string like an error message. This is a Heirloom
564 extension and currently ignored.
565
566 ev [envname]
567 Switch to another environment. Currently unsupported.
568
569 evc [envname]
570 Copy an environment into the current environment. Currently
571 unsupported.
572
573 ex Abort processing and exit. Currently unsupported.
574
575 fallback curfont font ...
576 Select the fallback sequence for a font. This is a Heirloom
577 extension and currently ignored.
578
579 fam [familyname]
580 Change the font family. This is a groff extension and currently
581 ignored.
582
583 fc [delimchar [padchar]]
584 Define a delimiting and a padding character for fields.
585 Currently unsupported.
586
587 fchar glyphname [string]
588 Define a fallback glyph. Currently unsupported.
589
590 fcolor colorname
591 Set the fill color for \D objects. This is a groff extension and
592 currently ignored.
593
594 fdeferlig font string ...
595 Defer ligature building. This is a Heirloom extension and
596 currently ignored.
597
598 feature +|-name
599 Enable or disable an OpenType feature. This is a Heirloom
600 extension and currently ignored.
601
602 fi Switch to fill mode. See man(5). Ignored in mdoc(5).
603
604 fkern font minkern
605 Control the use of kerning tables for a font. This is a Heirloom
606 extension and currently ignored.
607
608 fl Flush output. Currently ignored.
609
610 flig font string char ...
611 Define ligatures. This is a Heirloom extension and currently
612 ignored.
613
614 fp position font [filename]
615 Assign font position. Currently ignored.
616
617 fps mapname ...
618 Mount a font with a special character map. This is a Heirloom
619 extension and currently ignored.
620
621 fschar font glyphname [string]
622 Define a font-specific fallback glyph. This is a groff extension
623 and currently unsupported.
624
625 fspacewidth font [afmunits]
626 Set a font-specific width for the space character. This is a
627 Heirloom extension and currently ignored.
628
629 fspecial curfont [font ...]
630 Conditionally define a special font. This is a groff extension
631 and currently ignored.
632
633 ft [font]
634 Change the font. The following font arguments are supported:
635
636 B, BI, 3, 4
637 switches to bold font
638
639 I, 2 switches to underlined font
640
641 R, CW, 1
642 switches to normal font
643
644 P or no argument
645 switches back to the previous font
646
647 This request takes effect only locally and may be overridden by
648 macros and escape sequences.
649
650 ftr newname [oldname]
651 Translate font name. This is a groff extension and currently
652 ignored.
653
654 fzoom font [permille]
655 Zoom font size. Currently ignored.
656
657 gcolor [colorname]
658 Set glyph color. This is a groff extension and currently
659 ignored.
660
661 hc [char]
662 Set the hyphenation character. Currently ignored.
663
664 hcode char code ...
665 Set hyphenation codes of characters. Currently ignored.
666
667 hidechar font char ...
668 Hide characters in a font. This is a Heirloom extension and
669 currently ignored.
670
671 hla language
672 Set hyphenation language. This is a groff extension and
673 currently ignored.
674
675 hlm [number]
676 Set maximum number of consecutive hyphenated lines. Currently
677 ignored.
678
679 hpf filename
680 Load hyphenation pattern file. This is a groff extension and
681 currently ignored.
682
683 hpfa filename
684 Load hyphenation pattern file, appending to the current patterns.
685 This is a groff extension and currently ignored.
686
687 hpfcode code code ...
688 Define mapping values for character codes in hyphenation
689 patterns. This is a groff extension and currently ignored.
690
691 hw word ...
692 Specify hyphenation points in words. Currently ignored.
693
694 hy [mode]
695 Set automatic hyphenation mode. Currently ignored.
696
697 hylang language
698 Set hyphenation language. This is a Heirloom extension and
699 currently ignored.
700
701 hylen nchar
702 Minimum word length for hyphenation. This is a Heirloom
703 extension and currently ignored.
704
705 hym [length]
706 Set hyphenation margin. This is a groff extension and currently
707 ignored.
708
709 hypp penalty ...
710 Define hyphenation penalties. This is a Heirloom extension and
711 currently ignored.
712
713 hys [length]
714 Set hyphenation space. This is a groff extension and currently
715 ignored.
716
717 ie condition body
718 The "if" half of an if/else conditional. The result of the
719 conditional is pushed into a stack used by subsequent invocations
720 of el, which may be separated by any intervening input (or not
721 exist at all). Its syntax is equivalent to if.
722
723 if condition body
724 Begin a conditional. This request can also be written as
725 follows:
726
727 .if condition \{body
728 body ...\}
729
730 .if condition \{\
731 body ...
732 .\}
733
734 The condition is a boolean expression. Currently, mandoc(1)
735 supports the following subset of roff conditionals:
736
737 o If `!' is prefixed to condition, it is logically inverted.
738
739 o If the first character of condition is `n' (nroff mode) or
740 `o' (odd page), it evaluates to true.
741
742 o If the first character of condition is `c' (character
743 available), `e' (even page), `t' (troff mode), or `v' (vroff
744 mode), it evaluates to false.
745
746 o If the first character of condition is `d', it evaluates to
747 true if the rest of condition is the name of an existing user
748 defined macro or string; otherwise, it evaluates to false.
749
750 o If the first character of condition is `r', it evaluates to
751 true if the rest of condition is the name of an existing
752 number register; otherwise, it evaluates to false.
753
754 o If the condition starts with a parenthesis or with an
755 optionally signed integer number, it is evaluated according
756 to the rules of Numerical expressions explained below. It
757 evaluates to true if the result is positive, or to false if
758 the result is zero or negative.
759
760 o Otherwise, the first character of condition is regarded as a
761 delimiter and it evaluates to true if the string extending
762 from its first to its second occurrence is equal to the
763 string extending from its second to its third occurrence.
764
765 o If condition cannot be parsed, it evaluates to false.
766
767 If a conditional is false, its children are not processed, but
768 are syntactically interpreted to preserve the integrity of the
769 input document. Thus,
770
771 .if t .ig
772
773 will discard the `.ig', which may lead to interesting results,
774 but
775
776 .if t .if t \{\
777
778 will continue to syntactically interpret to the block close of
779 the final conditional. Sub-conditionals, in this case, obviously
780 inherit the truth value of the parent.
781
782 If the body section is begun by an escaped brace `\{', scope
783 continues until the end of the input line containing the matching
784 closing-brace escape sequence `\}'. If the body is not enclosed
785 in braces, scope continues until the end of the line. If the
786 condition is followed by a body on the same line, whether after a
787 brace or not, then requests and macros must begin with a control
788 character. It is generally more intuitive, in this case, to
789 write
790
791 .if condition \{\
792 .request
793 .\}
794
795 than having the request or macro follow as
796
797 .if condition \{.request
798
799 The scope of a conditional is always parsed, but only executed if
800 the conditional evaluates to true.
801
802 Note that the `\}' is converted into a zero-width escape sequence
803 if not passed as a standalone macro `.\}'. For example,
804
805 .Fl a \} b
806
807 will result in `\}' being considered an argument of the `Fl'
808 macro.
809
810 ig [endmacro]
811 Ignore input. Its syntax can be either
812
813 .ig
814 ignored text
815 ..
816
817 or
818
819 .ig endmacro
820 ignored text
821 .endmacro
822
823 In the first case, input is ignored until a `..' request is
824 encountered on its own line. In the second case, input is
825 ignored until the specified `.endmacro' is encountered. Do not
826 use the escape character `\' anywhere in the definition of
827 endmacro; it would cause very strange behaviour.
828
829 When the endmacro is a roff request or a roff macro, like in
830
831 .ig if
832
833 the subsequent invocation of if will first terminate the ignored
834 text, then be invoked as usual. Otherwise, it only terminates
835 the ignored text, and arguments following it or the `..' request
836 are discarded.
837
838 in [[+|-]width]
839 Change indentation. See man(5). Ignored in mdoc(5).
840
841 index register stringname substring
842 Find a substring in a string. This is a Heirloom extension and
843 currently unsupported.
844
845 it expression macro
846 Set an input line trap. The named macro will be invoked after
847 processing the number of input text lines specified by the
848 numerical expression. While evaluating the expression, the unit
849 suffixes described below Scaling Widths are ignored.
850
851 it expression macro
852 Set an input line trap, not counting lines ending with \c.
853 Currently unsupported.
854
855 IX class keystring
856 To support the generation of a table of contents, pod2man(1)
857 emits this user-defined macro, usually without defining it. To
858 avoid reporting large numbers of spurious errors, mandoc(1)
859 ignores it.
860
861 kern [1 | 0]
862 Switch kerning on or off. Currently ignored.
863
864 kernafter font char ... afmunits ...
865 Increase kerning after some characters. This is a Heirloom
866 extension and currently ignored.
867
868 kernbefore font char ... afmunits ...
869 Increase kerning before some characters. This is a Heirloom
870 extension and currently ignored.
871
872 kernpair font char ... font char ... afmunits
873 Add a kerning pair to the kerning table. This is a Heirloom
874 extension and currently ignored.
875
876 lc [glyph]
877 Define a leader repetition character. Currently unsupported.
878
879 lc_ctype localename
880 Set the LC_CTYPE locale. This is a Heirloom extension and
881 currently unsupported.
882
883 lds macroname string
884 Define a local string. This is a Heirloom extension and
885 currently unsupported.
886
887 length register string
888 Count the number of input characters in a string. Currently
889 unsupported.
890
891 letadj lspmin lshmin letss lspmax lshmax
892 Dynamic letter spacing and reshaping. This is a Heirloom
893 extension and currently ignored.
894
895 lf lineno [filename]
896 Change the line number for error messages. Ignored because
897 insecure.
898
899 lg [1 | 0]
900 Switch the ligature mechanism on or off. Currently ignored.
901
902 lhang font char ... afmunits
903 Hang characters at left margin. This is a Heirloom extension and
904 currently ignored.
905
906 linetabs [1 | 0]
907 Enable or disable line-tabs mode. This is a groff extension and
908 currently unsupported.
909
910 ll [[+|-]width]
911 Change the output line length. If the width argument is omitted,
912 the line length is reset to its previous value. The default
913 setting for terminal output is 58n. If a sign is given, the line
914 length is added to or subtracted from; otherwise, it is set to
915 the provided value. Using this request in new manuals is
916 discouraged for several reasons, among others because it
917 overrides the mandoc(1) -O width command line option.
918
919 lnr register [+|-]value [increment]
920 Set local number register. This is a Heirloom extension and
921 currently unsupported.
922
923 lnrf register [+|-]value [increment]
924 Set local floating-point register. This is a Heirloom extension
925 and currently unsupported.
926
927 lpfx string
928 Set a line prefix. This is a Heirloom extension and currently
929 unsupported.
930
931 ls [factor]
932 Set line spacing. It takes one integer argument specifying the
933 vertical distance of subsequent output text lines measured in v
934 units. Currently ignored.
935
936 lsm macroname
937 Set a leading spaces trap. This is a groff extension and
938 currently unsupported.
939
940 lt [[+|-]width]
941 Set title line length. Currently ignored.
942
943 mc glyph [dist]
944 Print margin character in the right margin. The dist is
945 currently ignored; instead, 1n is used.
946
947 mediasize media
948 Set the device media size. This is a Heirloom extension and
949 currently ignored.
950
951 minss width
952 Set minimum word space. This is a Heirloom extension and
953 currently ignored.
954
955 mk [register]
956 Mark vertical position. Currently ignored.
957
958 mso filename
959 Load a macro file using the search path. Ignored because
960 insecure.
961
962 na Disable adjusting without changing the adjustment mode.
963 Currently ignored.
964
965 ne [height]
966 Declare the need for the specified minimum vertical space before
967 the next trap or the bottom of the page. Currently ignored.
968
969 nf Switch to no-fill mode. See man(5). Ignored by mdoc(5).
970
971 nh Turn off automatic hyphenation mode. Currently ignored.
972
973 nhychar char ...
974 Define hyphenation-inhibiting characters. This is a Heirloom
975 extension and currently ignored.
976
977 nm [start [inc [space [indent]]]]
978 Print line numbers. Currently unsupported.
979
980 nn [number]
981 Temporarily turn off line numbering. Currently unsupported.
982
983 nop body
984 Execute the rest of the input line as a request or macro line.
985 Currently unsupported.
986
987 nr register [+|-]expression [stepsize]
988 Define or change a register. A register is an arbitrary string
989 value that defines some sort of state, which influences parsing
990 and/or formatting. For the syntax of expression, see Numerical
991 expressions below. If it is prefixed by a sign, the register
992 will be incremented or decremented instead of assigned to.
993
994 The stepsize is used by the \n+ auto-increment feature. It
995 remains unchanged when omitted while changing an existing
996 register, and it defaults to 0 when defining a new register.
997
998 The following register is handled specially:
999
1000 nS If set to a positive integer value, certain mdoc(5)
1001 macros will behave in the same way as in the SYNOPSIS
1002 section. If set to 0, these macros will behave in the
1003 same way as outside the SYNOPSIS section, even when
1004 called within the SYNOPSIS section itself. Note that
1005 starting a new mdoc(5) section with the Sh macro will
1006 reset this register.
1007
1008 nrf register [+|-]expression [increment]
1009 Define or change a floating-point register. This is a Heirloom
1010 extension and currently unsupported.
1011
1012 nroff Force nroff mode. This is a groff extension and currently
1013 ignored.
1014
1015 ns Turn on no-space mode. Currently ignored.
1016
1017 nx [filename]
1018 Abort processing of the current input file and process another
1019 one. Ignored because insecure.
1020
1021 open stream file
1022 Open a file for writing. Ignored because insecure.
1023
1024 opena stream file
1025 Open a file for appending. Ignored because insecure.
1026
1027 os Output saved vertical space. Currently ignored.
1028
1029 output string
1030 Output directly to intermediate output. Not supported.
1031
1032 padj [1 | 0]
1033 Globally control paragraph-at-once adjustment. This is a
1034 Heirloom extension and currently ignored.
1035
1036 papersize media
1037 Set the paper size. This is a Heirloom extension and currently
1038 ignored.
1039
1040 pc [char]
1041 Change the page number character. Currently ignored.
1042
1043 pev Print environments. This is a groff extension and currently
1044 ignored.
1045
1046 pi command
1047 Pipe output to a shell command. Ignored because insecure.
1048
1049 PI Low-level request used by BP. This is a Heirloom extension and
1050 currently unsupported.
1051
1052 pl [[+|-]height]
1053 Change page length. Currently ignored.
1054
1055 pm Print names and sizes of macros, strings, and diversions to
1056 standard error output. Currently ignored.
1057
1058 pn [+|-]number
1059 Change the page number of the next page. Currently ignored.
1060
1061 pnr Print all number registers on standard error output. Currently
1062 ignored.
1063
1064 po [[+|-]offset]
1065 Set a horizontal page offset. If no argument is specified, the
1066 page offset is reverted to its previous value. If a sign is
1067 specified, the new page offset is calculated relative to the
1068 current one; otherwise, it is absolute. The argument follows the
1069 syntax of Scaling Widths and the default scaling unit is m.
1070
1071 ps [[+|-]size]
1072 Change point size. Currently ignored.
1073
1074 psbb filename
1075 Retrieve the bounding box of a PostScript file. Currently
1076 unsupported.
1077
1078 pshape indent length ...
1079 Set a special shape for the current paragraph. This is a
1080 Heirloom extension and currently unsupported.
1081
1082 pso command
1083 Include output of a shell command. Ignored because insecure.
1084
1085 ptr Print the names and positions of all traps on standard error
1086 output. This is a groff extension and currently ignored.
1087
1088 pvs [[+|-]height]
1089 Change post-vertical spacing. This is a groff extension and
1090 currently ignored.
1091
1092 rchar glyph ...
1093 Remove glyph definitions. Currently unsupported.
1094
1095 rd [prompt [argument ...]]
1096 Read from standard input. Currently ignored.
1097
1098 recursionlimit maxrec maxtail
1099 Set the maximum stack depth for recursive macros. This is a
1100 Heirloom extension and currently ignored.
1101
1102 return [twice]
1103 Exit a macro and return to the caller. Currently unsupported.
1104
1105 rfschar font glyph ...
1106 Remove font-specific fallback glyph definitions. Currently
1107 unsupported.
1108
1109 rhang font char ... afmunits
1110 Hang characters at right margin. This is a Heirloom extension
1111 and currently ignored.
1112
1113 rj [N] Justify the next N input lines to the right margin without
1114 filling. N defaults to 1. An argument of 0 or less ends right
1115 adjustment.
1116
1117 rm macroname
1118 Remove a request, macro or string.
1119
1120 rn oldname newname
1121 Rename a request, macro, diversion, or string. In mandoc(1),
1122 user-defined macros, mdoc(5) and man(5) macros, and user-defined
1123 strings can be renamed, but renaming of predefined strings and of
1124 roff requests is not supported, and diversions are not
1125 implemented at all.
1126
1127 rnn oldname newname
1128 Rename a number register. Currently unsupported.
1129
1130 rr register
1131 Remove a register.
1132
1133 rs End no-space mode. Currently ignored.
1134
1135 rt [dist]
1136 Return to marked vertical position. Currently ignored.
1137
1138 schar glyph [string]
1139 Define global fallback glyph. This is a groff extension and
1140 currently unsupported.
1141
1142 sentchar char ...
1143 Define sentence-ending characters. This is a Heirloom extension
1144 and currently ignored.
1145
1146 shc [glyph]
1147 Change the soft hyphen character. Currently ignored.
1148
1149 shift [number]
1150 Shift macro arguments. Currently unsupported.
1151
1152 sizes size ...
1153 Define permissible point sizes. This is a groff extension and
1154 currently ignored.
1155
1156 so filename
1157 Include a source file. The file is read and its contents
1158 processed as input in place of the so request line. To avoid
1159 inadvertent inclusion of unrelated files, mandoc(1) only accepts
1160 relative paths not containing the strings "../" and "/..".
1161
1162 This request requires man(1) to change to the right directory
1163 before calling mandoc(1), per convention to the root of the
1164 manual tree. Typical usage looks like:
1165
1166 .so man3/Xcursor.3
1167
1168 As the whole concept is rather fragile, the use of so is
1169 discouraged. Use ln(1) instead.
1170
1171 sp [height]
1172 Break the output line and emit vertical space. The argument
1173 follows the syntax of Scaling Widths and defaults to one blank
1174 line (1v).
1175
1176 spacewidth [1 | 0]
1177 Set the space width from the font metrics file. This is a
1178 Heirloom extension and currently ignored.
1179
1180 special [font ...]
1181 Define a special font. This is a groff extension and currently
1182 ignored.
1183
1184 spreadwarn [width]
1185 Warn about wide spacing between words. Currently ignored.
1186
1187 ss wordspace [sentencespace]
1188 Set space character size. Currently ignored.
1189
1190 sty position style
1191 Associate style with a font position. This is a groff extension
1192 and currently ignored.
1193
1194 substring stringname startpos [endpos]
1195 Replace a user-defined string with a substring. Currently
1196 unsupported.
1197
1198 sv [height]
1199 Save vertical space. Currently ignored.
1200
1201 sy command
1202 Execute shell command. Ignored because insecure.
1203
1204 T& Re-start a table layout, retaining the options of the prior table
1205 invocation. See TS.
1206
1207 ta [width ... [T width ...]]
1208 Set tab stops. Each width argument follows the syntax of Scaling
1209 Widths. If prefixed by a plus sign, it is relative to the
1210 previous tab stop. The arguments after the T marker are used
1211 repeatedly as often as needed; for each reuse, they are taken
1212 relative to the last previously established tab stop. When ta is
1213 called without arguments, all tab stops are cleared.
1214
1215 tc [glyph]
1216 Change tab repetition character. Currently unsupported.
1217
1218 TE End a table context. See TS.
1219
1220 ti [+|-]width
1221 Break the output line and indent the next output line by width.
1222 If a sign is specified, the temporary indentation is calculated
1223 relative to the current indentation; otherwise, it is absolute.
1224 The argument follows the syntax of Scaling Widths and the default
1225 scaling unit is m.
1226
1227 tkf font minps width1 maxps width2
1228 Enable track kerning for a font. Currently ignored.
1229
1230 tl 'left'center'right'
1231 Print a title line. Currently unsupported.
1232
1233 tm string
1234 Print to standard error output. Currently ignored.
1235
1236 tm1 string
1237 Print to standard error output, allowing leading blanks. This is
1238 a groff extension and currently ignored.
1239
1240 tmc string
1241 Print to standard error output without a trailing newline. This
1242 is a groff extension and currently ignored.
1243
1244 tr glyph glyph ...
1245 Output character translation. The first glyph in each pair is
1246 replaced by the second one. Character escapes can be used; for
1247 example,
1248
1249 tr \(xx\(yy
1250
1251 replaces all invocations of \(xx with \(yy.
1252
1253 track font minps width1 maxps width2
1254 Static letter space tracking. This is a Heirloom extension and
1255 currently ignored.
1256
1257 transchar char ...
1258 Define transparent characters for sentence-ending. This is a
1259 Heirloom extension and currently ignored.
1260
1261 trf filename
1262 Output the contents of a file, disallowing invalid characters.
1263 This is a groff extension and ignored because insecure.
1264
1265 trimat left top width height
1266 Set the TrimBox page parameter for PDF generation. This is a
1267 Heirloom extension and currently ignored.
1268
1269 trin glyph glyph ...
1270 Output character translation, ignored by asciify. Currently
1271 unsupported.
1272
1273 trnt glyph glyph ...
1274 Output character translation, ignored by \!. Currently
1275 unsupported.
1276
1277 troff Force troff mode. This is a groff extension and currently
1278 ignored.
1279
1280 TS Begin a table, which formats input in aligned rows and columns.
1281 See tbl(5) for a description of the tbl language.
1282
1283 uf font
1284 Globally set the underline font. Currently ignored.
1285
1286 ul [N] Underline next N input lines. Currently ignored.
1287
1288 unformat divname
1289 Unformat spaces and tabs in a diversion. Currently unsupported.
1290
1291 unwatch macroname
1292 Disable notification for string or macro. This is a Heirloom
1293 extension and currently ignored.
1294
1295 unwatchn register
1296 Disable notification for register. This is a Heirloom extension
1297 and currently ignored.
1298
1299 vpt [1 | 0]
1300 Enable or disable vertical position traps. This is a groff
1301 extension and currently ignored.
1302
1303 vs [[+|-]height]
1304 Change vertical spacing. Currently ignored.
1305
1306 warn flags
1307 Set warning level. Currently ignored.
1308
1309 warnscale si
1310 Set the scaling indicator used in warnings. This is a groff
1311 extension and currently ignored.
1312
1313 watch macroname
1314 Notify on change of string or macro. This is a Heirloom
1315 extension and currently ignored.
1316
1317 watchlength maxlength
1318 On change, report the contents of macros and strings up to the
1319 specified length. This is a Heirloom extension and currently
1320 ignored.
1321
1322 watchn register
1323 Notify on change of register. This is a Heirloom extension and
1324 currently ignored.
1325
1326 wh dist [macroname]
1327 Set a page location trap. Currently unsupported.
1328
1329 while condition body
1330 Repeated execution while a condition is true. Currently
1331 unsupported.
1332
1333 write ["]string
1334 Write to an open file. Ignored because insecure.
1335
1336 writec ["]string
1337 Write to an open file without appending a newline. Ignored
1338 because insecure.
1339
1340 writem macroname
1341 Write macro or string to an open file. Ignored because insecure.
1342
1343 xflag level
1344 Set the extension level. This is a Heirloom extension and
1345 currently ignored.
1346
1347 Numerical expressions
1348 The nr, if, and ie requests accept integer numerical expressions as
1349 arguments. These are always evaluated using the C int type; integer
1350 overflow works the same way as in the C language. Numbers consist of an
1351 arbitrary number of digits `0' to `9' prefixed by an optional sign `+' or
1352 `-'. Each number may be followed by one optional scaling unit described
1353 below Scaling Widths. The following equations hold:
1354
1355 1i = 6v = 6P = 10m = 10n = 52p = 1000M = 240u = 240
1356 254c = 100i = 24000u = 24000
1357 1f = 65536u = 65536
1358
1359 The following binary operators are implemented. Unless otherwise stated,
1360 they behave as in the C language:
1361
1362 + addition
1363 - subtraction
1364 * multiplication
1365 / division
1366 % remainder of division
1367 < less than
1368 > greater than
1369 == equal to
1370 = equal to, same effect as == (this differs from C)
1371 <= less than or equal to
1372 >= greater than or equal to
1373 <> not equal to (corresponds to C !=; this one is of limited
1374 portability, it is supported by Heirloom roff, but not by groff)
1375 & logical and (corresponds to C &&)
1376 : logical or (corresponds to C ||)
1377 <? minimum (not available in C)
1378 >? maximum (not available in C)
1379
1380 There is no concept of precedence; evaluation proceeds from left to
1381 right, except when subexpressions are enclosed in parentheses. Inside
1382 parentheses, whitespace is ignored.
1383
1384 ESCAPE SEQUENCE REFERENCE
1385 The mandoc(1) roff parser recognises the following escape sequences.
1386 Note that the roff language defines more escape sequences not implemented
1387 in mandoc(1). In mdoc(5) and man(5) documents, using escape sequences is
1388 discouraged except for those described in the LANGUAGE SYNTAX section
1389 above.
1390
1391 A backslash followed by any character not listed here simply prints that
1392 character itself.
1393
1394 \<newline>
1395 A backslash at the end of an input line can be used to continue the
1396 logical input line on the next physical input line, joining the text on
1397 both lines together as if it were on a single input line.
1398
1399 \<space>
1400 The escape sequence backslash-space (`\ ') is an unpaddable space-sized
1401 non-breaking space character; see Whitespace.
1402
1403 \"
1404 The rest of the input line is treated as Comments.
1405
1406 \%
1407 Hyphenation allowed at this point of the word; ignored by mandoc(1).
1408
1409 \&
1410 Non-printing zero-width character; see Whitespace.
1411
1412 \'
1413 Acute accent special character; use `\(aa' instead.
1414
1415 \(cc
1416 Special Characters with two-letter names, see mandoc_char(5).
1417
1418 \*[name]
1419 Interpolate the string with the name; see Predefined Strings and ds. For
1420 short names, there are variants \*c and \*(cc.
1421
1422 \,
1423 Left italic correction (groff extension); ignored by mandoc(1).
1424
1425 \-
1426 Special character "mathematical minus sign".
1427
1428 \/
1429 Right italic correction (groff extension); ignored by mandoc(1).
1430
1431 \[name]
1432 Special Characters with names of arbitrary length, see mandoc_char(5).
1433
1434 \^
1435 One-twelfth em half-narrow space character, effectively zero-width in
1436 mandoc(1).
1437
1438 \`
1439 Grave accent special character; use `\(ga' instead.
1440
1441 \{
1442 Begin conditional input; see if.
1443
1444 \|
1445 One-sixth em narrow space character, effectively zero-width in mandoc(1).
1446
1447 \}
1448 End conditional input; see if.
1449
1450 \~
1451 Paddable non-breaking space character.
1452
1453 \0
1454 Digit width space character.
1455
1456 \A'string'
1457 Anchor definition; ignored by mandoc(1).
1458
1459 \B'string'
1460 Interpolate `1' if string conforms to the syntax of Numerical expressions
1461 explained above and `0' otherwise.
1462
1463 \b'string'
1464 Bracket building function; ignored by mandoc(1).
1465
1466 \C'name'
1467 Special Characters with names of arbitrary length.
1468
1469 \c
1470 When encountered at the end of an input text line, the next input text
1471 line is considered to continue that line, even if there are request or
1472 macro lines in between. No whitespace is inserted.
1473
1474 \D'string'
1475 Draw graphics function; ignored by mandoc(1).
1476
1477 \d
1478 Move down by half a line; ignored by mandoc(1).
1479
1480 \e
1481 Backslash special character.
1482
1483 \F[name]
1484 Switch font family (groff extension); ignored by mandoc(1). For short
1485 names, there are variants \Fc and \F(cc.
1486
1487 \f[name]
1488 Switch to the font name, see Text Decoration. For short names, there are
1489 variants \fc and \f(cc.
1490
1491 \g[name]
1492 Interpolate the format of a number register; ignored by mandoc(1). For
1493 short names, there are variants \gc and \g(cc.
1494
1495 \H'[+|-]number'
1496 Set the height of the current font; ignored by mandoc(1).
1497
1498 \h'[|]width'
1499 Horizontal motion. If the vertical bar is given, the motion is relative
1500 to the current indentation. Otherwise, it is relative to the current
1501 position. The default scaling unit is m.
1502
1503 \k[name]
1504 Mark horizontal input place in register; ignored by mandoc(1). For short
1505 names, there are variants \kc and \k(cc.
1506
1507 \L'number[c]'
1508 Vertical line drawing function; ignored by mandoc(1).
1509
1510 \l'width[c]'
1511 Draw a horizontal line of width using the glyph c.
1512
1513 \M[name]
1514 Set fill (background) color (groff extension); ignored by mandoc(1). For
1515 short names, there are variants \Mc and \M(cc.
1516
1517 \m[name]
1518 Set glyph drawing color (groff extension); ignored by mandoc(1). For
1519 short names, there are variants \mc and \m(cc.
1520
1521 \N'number'
1522 Character number on the current font.
1523
1524 \n[+|-][name]
1525 Interpolate the number register name. For short names, there are
1526 variants \nc and \n(cc. If the optional sign is specified, the register
1527 is first incremented or decremented by the stepsize that was specified in
1528 the relevant nr request, and the changed value is interpolated.
1529
1530 \o'string'
1531 Overstrike, writing all the characters contained in the string to the
1532 same output position. In terminal and HTML output modes, only the last
1533 one of the characters is visible.
1534
1535 \p
1536 Break the output line at the end of the current word.
1537
1538 \R'name [+|-]number'
1539 Set number register; ignored by mandoc(1).
1540
1541 \S'number'
1542 Slant output; ignored by mandoc(1).
1543
1544 \s'[+|-]number'
1545 Change point size; ignored by mandoc(1). Alternative forms \s[+|-]n,
1546 \s[+|-]'number', \s[[+|-]number], and \s[+|-][number] are also parsed and
1547 ignored.
1548
1549 \t
1550 Horizontal tab; ignored by mandoc(1).
1551
1552 \u
1553 Move up by half a line; ignored by mandoc(1).
1554
1555 \V[name]
1556 Interpolate an environment variable; ignored by mandoc(1). For short
1557 names, there are variants \Vc and \V(cc.
1558
1559 \v'number'
1560 Vertical motion; ignored by mandoc(1).
1561
1562 \w'string'
1563 Interpolate the width of the string. The mandoc(1) implementation
1564 assumes that after expansion of user-defined strings, the string only
1565 contains normal characters, no escape sequences, and that each character
1566 has a width of 24 basic units.
1567
1568 \X'string'
1569 Output string as device control function; ignored in nroff mode and by
1570 mandoc(1).
1571
1572 \x'number'
1573 Extra line space function; ignored by mandoc(1).
1574
1575 \Y[name]
1576 Output a string as a device control function; ignored in nroff mode and
1577 by mandoc(1). For short names, there are variants \Yc and \Y(cc.
1578
1579 \Z'string'
1580 Print string with zero width and height; ignored by mandoc(1).
1581
1582 \z
1583 Output the next character without advancing the cursor position.
1584
1585 COMPATIBILITY
1586 The mandoc(1) implementation of the roff language is intentionally
1587 incomplete. Unimplemented features include:
1588
1589 - For security reasons, mandoc(1) never reads or writes external files
1590 except via so requests with safe relative paths.
1591 - There is no automatic hyphenation, no adjustment to the right margin,
1592 and no centering; the output is always set flush-left.
1593 - Support for setting tabulator positions and tabulator and leader
1594 characters is missing, and support for manually changing indentation
1595 is limited.
1596 - The `u' scaling unit is the default terminal unit. In traditional
1597 troff systems, this unit changes depending on the output media.
1598 - Width measurements are implemented in a crude way and often yield
1599 wrong results. Explicit movement requests and escapes are ignored.
1600 - There is no concept of output pages, no support for floats, graphics
1601 drawing, and picture inclusion; terminal output is always continuous.
1602 - Requests regarding color, font families, and glyph manipulation are
1603 ignored. Font support is very limited. Kerning is not implemented,
1604 and no ligatures are produced.
1605 - The "'" macro control character does not suppress output line breaks.
1606 - Diversions are not implemented, and support for traps is very
1607 incomplete.
1608 - While recursion is supported, while loops are not.
1609
1610 The special semantics of the nS number register is an idiosyncracy of
1611 OpenBSD manuals and not supported by other mdoc(5) implementations.
1612
1613 SEE ALSO
1614 mandoc(1), eqn(5), man(5), mandoc_char(5), mdoc(5), tbl(5)
1615
1616 Joseph F. Ossanna and Brian W. Kernighan, Troff User's Manual, AT&T Bell
1617 Laboratories, Computing Science Technical Report, 54,
1618 http://www.kohala.com/start/troff/cstr54.ps, Murray Hill, New Jersey,
1619 1976 and 1992.
1620
1621 Joseph F. Ossanna, Brian W. Kernighan, and Gunnar Ritter, Heirloom
1622 Documentation Tools Nroff/Troff User's Manual,
1623 http://heirloom.sourceforge.net/doctools/troff.pdf, September 17, 2007.
1624
1625 HISTORY
1626 The RUNOFF typesetting system, whose input forms the basis for roff, was
1627 written in MAD and FAP for the CTSS operating system by Jerome E.
1628 Saltzer in 1964. Doug McIlroy rewrote it in BCPL in 1969, renaming it
1629 roff. Dennis M. Ritchie rewrote McIlroy's roff in PDP-11 assembly for
1630 Version 1 AT&T UNIX, Joseph F. Ossanna improved roff and renamed it nroff
1631 for Version 2 AT&T UNIX, then ported nroff to C as troff, which Brian W.
1632 Kernighan released with Version 7 AT&T UNIX. In 1989, James Clarke re-
1633 implemented troff in C++, naming it groff.
1634
1635 AUTHORS
1636 This roff reference was written by Kristaps Dzonsons <kristaps@bsd.lv>
1637 and Ingo Schwarze <schwarze@openbsd.org>.
1638
1639 illumos April 10, 2018 illumos