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