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