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