1 .\" $Id: roff.7,v 1.94 2017/07/05 12:25:17 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2010,2011,2013-2015,2017 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: July 5 2017 $
19 .Dt ROFF 5
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 5
30 and
31 .Xr man 5
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 5
37 or
38 .Xr man 5
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 5 ,
51 and
52 .Xr man 5 .
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
64 or
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.
108 .Pp
109 Examples:
110 .Bd -literal -offset indent -compact
111 \&.\e\(dq This is a comment line.
112 \&.\e\(dq The next line is ignored:
113 \&.
114 \&.Sh EXAMPLES \e\(dq This is a comment, too.
115 \&example text \e\(dq And so is this.
116 .Ed
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.
130 .Pp
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.
137 .El
138 .Pp
139 See
140 .Xr mandoc_char 5
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.
151 .Pp
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.
156 .Pp
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.
165 .El
166 .Pp
167 Text decoration is
168 .Em not
169 recommended for
170 .Xr mdoc 5 ,
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 .
184 .Pp
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.
191 .El
192 .Pp
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 5 .
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.
204 .Pp
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& .
212 .Pp
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.
218 .Pp
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.
229 .Pp
230 The following scaling units are accepted:
231 .Pp
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)
261 .El
262 .Pp
263 Using anything other than
264 .Sq m ,
265 .Sq n ,
266 or
267 .Sq v
268 is necessarily non-portable across output media.
269 See
270 .Sx COMPATIBILITY .
271 .Pp
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.
278 .Pp
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 5
284 .It Li \&.HP 2i
285 two-inch tagged list indentation in
286 .Xr man 5
287 .It Li \&.sp 2v
288 two vertical spaces
289 .El
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
296 .Po
297 .Sq \&) ,
298 .Sq \&] ,
299 .Sq \&' ,
300 .Sq \&"
301 .Pc .
302 .Pp
303 The proper spacing is also intelligently preserved if a sentence ends at
304 the boundary of a macro line.
305 .Pp
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 \&.
312 .Ed
313 .Sh REQUEST SYNTAX
314 A request or macro line consists of:
315 .Pp
316 .Bl -enum -compact
317 .It
318 the control character
319 .Sq \&.
320 or
321 .Sq \(aq
322 at the beginning of the line,
323 .It
324 optionally an arbitrary amount of whitespace,
325 .It
326 the name of the request or the macro, which is one word of arbitrary
327 length, terminated by whitespace,
328 .It
329 and zero or more arguments delimited by whitespace.
330 .El
331 .Pp
332 Thus, the following request lines are all equivalent:
333 .Bd -literal -offset indent
334 \&.ig end
335 \&.ig end
336 \&. ig end
337 .Ed
338 .Sh MACRO SYNTAX
339 Macros are provided by the
340 .Xr mdoc 5
341 and
342 .Xr man 5
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.
355 .Pp
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.
367 .Pp
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.
375 .Pp
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 ,
385 and
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.
392 .El
393 .Sh REQUEST REFERENCE
394 The
395 .Xr mandoc 1
396 .Nm
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
427 .Nm
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
444 .Nm
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
461 .Nm
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.
520 If
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
570 .Nm
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
592 .Nm
593 macro.
594 Its syntax can be either
595 .Bd -literal -offset indent
596 .Pf . Ic \&de Ar macroname
597 .Ar definition
598 \&..
599 .Ed
600 .Pp
601 or
602 .Bd -literal -offset indent
603 .Pf . Ic \&de Ar macroname Ar endmacro
604 .Ar definition
605 .Pf . Ar endmacro
606 .Ed
607 .Pp
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
614 .Nm
615 requests,
616 .Nm
617 macros or high-level macros like
618 .Xr man 5
619 or
620 .Xr mdoc 5
621 macros, whichever applies to the document in question.
622 .Pp
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
632 .Nm
633 request or
634 .Nm
635 macro, but not as a high-level macro.
636 .Pp
637 The macro can be invoked later using the syntax
638 .Pp
639 .D1 Pf . Ar macroname Op Ar argument Op Ar argument ...
640 .Pp
641 Regarding argument parsing, see
642 .Sx MACRO SYNTAX
643 above.
644 .Pp
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 .
660 .Ed
661 .Pp
662 produces
663 .Pp
664 .D1 \efI\e^XtFree\e^\efP.
665 .Pp
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.
669 .Pp
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.
683 .Pp
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
693 .Nm
694 macro that will be executed with
695 .Nm
696 compatibility mode switched off during macro execution.
697 This is a groff extension.
698 Since
699 .Xr mandoc 1
700 does not implement
701 .Nm
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
709 .Nm
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:
714 .Pp
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
718 .Nm
719 macro that will be executed with
720 .Nm
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
726 .Nm
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
738 .Nm
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.
743 The
744 .Ar stringname
745 and
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.
755 .Pp
756 The
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.
768 .Pp
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
780 .Nm
781 parser.
782 For example,
783 .Bd -literal -offset indent
784 \&.ds badidea .S
785 \&.badidea
786 H SYNOPSIS
787 .Ed
788 .Pp
789 invokes the
790 .Ic SH
791 macro when used in a
792 .Xr man 5
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
797 .Nm
798 compatibility mode switched off during string expansion.
799 This is a groff extension.
800 Since
801 .Xr mandoc 1
802 does not implement
803 .Nm
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.
814 The
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
825 The
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.
843 See
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.
853 See
854 .Xr eqn 5
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.
891 See
892 .Xr man 5 .
893 Ignored in
894 .Xr mdoc 5 .
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
937 .El
938 .Pp
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
996 The
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}
1011 .Ed
1012 .Bd -unfilled -offset indent
1013 .Pf . Ic \&if Ar condition No \e{\e
1014 .Ar body ...
1015 .Pf . No \e}
1016 .Ed
1017 .Pp
1018 The
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
1025 .It
1026 If
1027 .Sq \&!
1028 is prefixed to
1029 .Ar condition ,
1030 it is logically inverted.
1031 .It
1032 If the first character of
1033 .Ar condition
1034 is
1035 .Sq n
1036 .Pq nroff mode
1037 or
1038 .Sq o
1039 .Pq odd page ,
1040 it evaluates to true.
1041 .It
1042 If the first character of
1043 .Ar condition
1044 is
1045 .Sq c
1046 .Pq character available ,
1047 .Sq e
1048 .Pq even page ,
1049 .Sq t
1050 .Pq troff mode ,
1051 or
1052 .Sq v
1053 .Pq vroff mode ,
1054 it evaluates to false.
1055 .It
1056 If the first character of
1057 .Ar condition
1058 is
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.
1064 .It
1065 If the first character of
1066 .Ar condition
1067 is
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.
1073 .It
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.
1082 .It
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.
1088 .It
1089 If
1090 .Ar condition
1091 cannot be parsed, it evaluates to false.
1092 .El
1093 .Pp
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,
1098 .Pp
1099 .D1 \&.if t .ig
1100 .Pp
1101 will discard the
1102 .Sq \&.ig ,
1103 which may lead to interesting results, but
1104 .Pp
1105 .D1 \&.if t .if t \e{\e
1106 .Pp
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.
1111 .Pp
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}
1134 .Ed
1135 .Pp
1136 than having the request or macro follow as
1137 .Pp
1138 .D1 Pf . Ic \&if Ar condition Pf \e{. Ar request
1139 .Pp
1140 The scope of a conditional is always parsed, but only executed if the
1141 conditional evaluates to true.
1142 .Pp
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,
1149 .Pp
1150 .D1 \&.Fl a \e} b
1151 .Pp
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 \&..
1164 .Ed
1165 .Pp
1166 or
1167 .Bd -literal -offset indent
1168 .Pf . Cm \&ig Ar endmacro
1169 .Ar ignored text
1170 .Pf . Ar endmacro
1171 .Ed
1172 .Pp
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.
1184 .Pp
1185 When the
1186 .Ar endmacro
1187 is a roff request or a roff macro, like in
1188 .Pp
1189 .D1 \&.ig if
1190 .Pp
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.
1203 See
1204 .Xr man 5 .
1205 Ignored in
1206 .Xr mdoc 5 .
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 58n.
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 \< 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.
1308 The
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.
1332 See
1333 .Xr man 5 .
1334 Ignored by
1335 .Xr mdoc 5 .
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
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 ,
1357 see
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.
1362 .Pp
1363 The following
1364 .Ar register
1365 is handled specially:
1366 .Bl -tag -width Ds
1367 .It Cm nS
1368 If set to a positive integer value, certain
1369 .Xr mdoc 5
1370 macros will behave in the same way as in the
1371 .Em SYNOPSIS
1372 section.
1373 If set to 0, these macros will behave in the same way as outside the
1374 .Em SYNOPSIS
1375 section, even when called within the
1376 .Em SYNOPSIS
1377 section itself.
1378 Note that starting a new
1379 .Xr mdoc 5
1380 section with the
1381 .Ic \&Sh
1382 macro will reset this register.
1383 .El
1384 .It Xo
1385 .Ic \&nrf Ar register Oo Cm + Ns | Ns Cm - Oc Ns Ar expression
1386 .Op Ar increment
1387 .Xc
1388 Define or change a floating-point register.
1389 This is a Heirloom extension and currently unsupported.
1390 .It Ic \&nroff
1391 Force nroff mode.
1392 This is a groff extension and currently ignored.
1393 .It Ic \&ns
1394 Turn on no-space mode.
1395 Currently ignored.
1396 .It Ic \&nx Op Ar filename
1397 Abort processing of the current input file and process another one.
1398 Ignored because insecure.
1399 .It Ic \&open Ar stream file
1400 Open a file for writing.
1401 Ignored because insecure.
1402 .It Ic \&opena Ar stream file
1403 Open a file for appending.
1404 Ignored because insecure.
1405 .It Ic \&os
1406 Output saved vertical space.
1407 Currently ignored.
1408 .It Ic \&output Ar string
1409 Output directly to intermediate output.
1410 Not supported.
1411 .It Ic \&padj Op Cm 1 | 0
1412 Globally control paragraph-at-once adjustment.
1413 This is a Heirloom extension and currently ignored.
1414 .It Ic \&papersize Ar media
1415 Set the paper size.
1416 This is a Heirloom extension and currently ignored.
1417 .It Ic \&pc Op Ar char
1418 Change the page number character.
1419 Currently ignored.
1420 .It Ic \&pev
1421 Print environments.
1422 This is a groff extension and currently ignored.
1423 .It Ic \&pi Ar command
1424 Pipe output to a shell command.
1425 Ignored because insecure.
1426 .It Ic \&PI
1427 Low-level request used by
1428 .Ic \&BP .
1429 This is a Heirloom extension and currently unsupported.
1430 .It Ic \&pl Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height
1431 Change page length.
1432 Currently ignored.
1433 .It Ic \&pm
1434 Print names and sizes of macros, strings, and diversions
1435 to standard error output.
1436 Currently ignored.
1437 .It Ic \&pn Oo Cm + Ns | Ns Cm - Oc Ns Ar number
1438 Change the page number of the next page.
1439 Currently ignored.
1440 .It Ic \&pnr
1441 Print all number registers on standard error output.
1442 Currently ignored.
1443 .It Ic \&po Op Oo Cm + Ns | Ns Cm - Oc Ns Ar offset
1444 Set a horizontal page offset.
1445 If no argument is specified, the page offset is reverted to its
1446 previous value.
1447 If a sign is specified, the new page offset is calculated relative
1448 to the current one; otherwise, it is absolute.
1449 The argument follows the syntax of
1450 .Sx Scaling Widths
1451 and the default scaling unit is
1452 .Cm m .
1453 .It Ic \&ps Op Oo Cm + Ns | Ns Cm - Oc Ns size
1454 Change point size.
1455 Currently ignored.
1456 .It Ic \&psbb Ar filename
1457 Retrieve the bounding box of a PostScript file.
1458 Currently unsupported.
1459 .It Ic \&pshape Ar indent length ...
1460 Set a special shape for the current paragraph.
1461 This is a Heirloom extension and currently unsupported.
1462 .It Ic \&pso Ar command
1463 Include output of a shell command.
1464 Ignored because insecure.
1465 .It Ic \&ptr
1466 Print the names and positions of all traps on standard error output.
1467 This is a groff extension and currently ignored.
1468 .It Ic \&pvs Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height
1469 Change post-vertical spacing.
1470 This is a groff extension and currently ignored.
1471 .It Ic \&rchar Ar glyph ...
1472 Remove glyph definitions.
1473 Currently unsupported.
1474 .It Ic \&rd Op Ar prompt Op Ar agument ...
1475 Read from standard input.
1476 Currently ignored.
1477 .It Ic \&recursionlimit Ar maxrec maxtail
1478 Set the maximum stack depth for recursive macros.
1479 This is a Heirloom extension and currently ignored.
1480 .It Ic \&return Op Ar twice
1481 Exit a macro and return to the caller.
1482 Currently unsupported.
1483 .It Ic \&rfschar Ar font glyph ...
1484 Remove font-specific fallback glyph definitions.
1485 Currently unsupported.
1486 .It Ic \&rhang Ar font char ... afmunits
1487 Hang characters at right margin.
1488 This is a Heirloom extension and currently ignored.
1489 .It Ic \&rj Op Ar N
1490 Justify the next
1491 .Ar N
1492 input lines to the right margin without filling.
1493 .Ar N
1494 defaults to 1.
1495 An argument of 0 or less ends right adjustment.
1496 .It Ic \&rm Ar macroname
1497 Remove a request, macro or string.
1498 .It Ic \&rn Ar oldname newname
1499 Rename a request, macro, diversion, or string.
1500 In
1501 .Xr mandoc 1 ,
1502 user-defined macros,
1503 .Xr mdoc 5
1504 and
1505 .Xr man 5
1506 macros, and user-defined strings can be renamed, but renaming of
1507 predefined strings and of
1508 .Nm
1509 requests is not supported, and diversions are not implemented at all.
1510 .It Ic \&rnn Ar oldname newname
1511 Rename a number register.
1512 Currently unsupported.
1513 .It Ic \&rr Ar register
1514 Remove a register.
1515 .It Ic \&rs
1516 End no-space mode.
1517 Currently ignored.
1518 .It Ic \&rt Op Ar dist
1519 Return to marked vertical position.
1520 Currently ignored.
1521 .It Ic \&schar Ar glyph Op Ar string
1522 Define global fallback glyph.
1523 This is a groff extension and currently unsupported.
1524 .It Ic \&sentchar Ar char ...
1525 Define sentence-ending characters.
1526 This is a Heirloom extension and currently ignored.
1527 .It Ic \&shc Op Ar glyph
1528 Change the soft hyphen character.
1529 Currently ignored.
1530 .It Ic \&shift Op Ar number
1531 Shift macro arguments.
1532 Currently unsupported.
1533 .It Ic \&sizes Ar size ...
1534 Define permissible point sizes.
1535 This is a groff extension and currently ignored.
1536 .It Ic \&so Ar filename
1537 Include a source file.
1538 The file is read and its contents processed as input in place of the
1539 .Ic \&so
1540 request line.
1541 To avoid inadvertent inclusion of unrelated files,
1542 .Xr mandoc 1
1543 only accepts relative paths not containing the strings
1544 .Qq ../
1545 and
1546 .Qq /.. .
1547 .Pp
1548 This request requires
1549 .Xr man 1
1550 to change to the right directory before calling
1551 .Xr mandoc 1 ,
1552 per convention to the root of the manual tree.
1553 Typical usage looks like:
1554 .Pp
1555 .Dl \&.so man3/Xcursor.3
1556 .Pp
1557 As the whole concept is rather fragile, the use of
1558 .Ic \&so
1559 is discouraged.
1560 Use
1561 .Xr ln 1
1562 instead.
1563 .It Ic \&sp Op Ar height
1564 Break the output line and emit vertical space.
1565 The argument follows the syntax of
1566 .Sx Scaling Widths
1567 and defaults to one blank line
1568 .Pq Li 1v .
1569 .It Ic \&spacewidth Op Cm 1 | 0
1570 Set the space width from the font metrics file.
1571 This is a Heirloom extension and currently ignored.
1572 .It Ic \&special Op Ar font ...
1573 Define a special font.
1574 This is a groff extension and currently ignored.
1575 .It Ic \&spreadwarn Op Ar width
1576 Warn about wide spacing between words.
1577 Currently ignored.
1578 .It Ic \&ss Ar wordspace Op Ar sentencespace
1579 Set space character size.
1580 Currently ignored.
1581 .It Ic \&sty Ar position style
1582 Associate style with a font position.
1583 This is a groff extension and currently ignored.
1584 .It Ic \&substring Ar stringname startpos Op Ar endpos
1585 Replace a user-defined string with a substring.
1586 Currently unsupported.
1587 .It Ic \&sv Op Ar height
1588 Save vertical space.
1589 Currently ignored.
1590 .It Ic \&sy Ar command
1591 Execute shell command.
1592 Ignored because insecure.
1593 .It Ic \&T&
1594 Re-start a table layout, retaining the options of the prior table
1595 invocation.
1596 See
1597 .Sx \&TS .
1598 .It Ic \&ta Op Ar width ... Op Cm T Ar width ...
1599 Set tab stops.
1600 Each
1601 .Ar width
1602 argument follows the syntax of
1603 .Sx Scaling Widths .
1604 If prefixed by a plus sign, it is relative to the previous tab stop.
1605 The arguments after the
1606 .Cm T
1607 marker are used repeatedly as often as needed; for each reuse,
1608 they are taken relative to the last previously established tab stop.
1609 When
1610 .Ic \&ta
1611 is called without arguments, all tab stops are cleared.
1612 .It Ic \&tc Op Ar glyph
1613 Change tab repetition character.
1614 Currently unsupported.
1615 .It Ic \&TE
1616 End a table context.
1617 See
1618 .Sx \&TS .
1619 .It Ic \&ti Oo Cm + Ns | Ns Cm - Oc Ns Ar width
1620 Break the output line and indent the next output line by
1621 .Ar width .
1622 If a sign is specified, the temporary indentation is calculated
1623 relative to the current indentation; otherwise, it is absolute.
1624 The argument follows the syntax of
1625 .Sx Scaling Widths
1626 and the default scaling unit is
1627 .Cm m .
1628 .It Ic \&tkf Ar font minps width1 maxps width2
1629 Enable track kerning for a font.
1630 Currently ignored.
1631 .It Ic \&tl No \& Ap Ar left Ap Ar center Ap Ar right Ap
1632 Print a title line.
1633 Currently unsupported.
1634 .It Ic \&tm Ar string
1635 Print to standard error output.
1636 Currently ignored.
1637 .It Ic \&tm1 Ar string
1638 Print to standard error output, allowing leading blanks.
1639 This is a groff extension and currently ignored.
1640 .It Ic \&tmc Ar string
1641 Print to standard error output without a trailing newline.
1642 This is a groff extension and currently ignored.
1643 .It Ic \&tr Ar glyph glyph ...
1644 Output character translation.
1645 The first glyph in each pair is replaced by the second one.
1646 Character escapes can be used; for example,
1647 .Pp
1648 .Dl tr \e(xx\e(yy
1649 .Pp
1650 replaces all invocations of \e(xx with \e(yy.
1651 .It Ic \&track Ar font minps width1 maxps width2
1652 Static letter space tracking.
1653 This is a Heirloom extension and currently ignored.
1654 .It Ic \&transchar Ar char ...
1655 Define transparent characters for sentence-ending.
1656 This is a Heirloom extension and currently ignored.
1657 .It Ic \&trf Ar filename
1658 Output the contents of a file, disallowing invalid characters.
1659 This is a groff extension and ignored because insecure.
1660 .It Ic \&trimat Ar left top width height
1661 Set the TrimBox page parameter for PDF generation.
1662 This is a Heirloom extension and currently ignored.
1663 .It Ic \&trin Ar glyph glyph ...
1664 Output character translation, ignored by
1665 .Ic \&asciify .
1666 Currently unsupported.
1667 .It Ic \&trnt Ar glyph glyph ...
1668 Output character translation, ignored by \e!.
1669 Currently unsupported.
1670 .It Ic \&troff
1671 Force troff mode.
1672 This is a groff extension and currently ignored.
1673 .It Ic \&TS
1674 Begin a table, which formats input in aligned rows and columns.
1675 See
1676 .Xr tbl 5
1677 for a description of the tbl language.
1678 .It Ic \&uf Ar font
1679 Globally set the underline font.
1680 Currently ignored.
1681 .It Ic \&ul Op Ar N
1682 Underline next
1683 .Ar N
1684 input lines.
1685 Currently ignored.
1686 .It Ic \&unformat Ar divname
1687 Unformat spaces and tabs in a diversion.
1688 Currently unsupported.
1689 .It Ic \&unwatch Ar macroname
1690 Disable notification for string or macro.
1691 This is a Heirloom extension and currently ignored.
1692 .It Ic \&unwatchn Ar register
1693 Disable notification for register.
1694 This is a Heirloom extension and currently ignored.
1695 .It Ic \&vpt Op Cm 1 | 0
1696 Enable or disable vertical position traps.
1697 This is a groff extension and currently ignored.
1698 .It Ic \&vs Op Oo Cm + Ns | Ns Cm - Oc Ns Ar height
1699 Change vertical spacing.
1700 Currently ignored.
1701 .It Ic \&warn Ar flags
1702 Set warning level.
1703 Currently ignored.
1704 .It Ic \&warnscale Ar si
1705 Set the scaling indicator used in warnings.
1706 This is a groff extension and currently ignored.
1707 .It Ic \&watch Ar macroname
1708 Notify on change of string or macro.
1709 This is a Heirloom extension and currently ignored.
1710 .It Ic \&watchlength Ar maxlength
1711 On change, report the contents of macros and strings
1712 up to the specified length.
1713 This is a Heirloom extension and currently ignored.
1714 .It Ic \&watchn Ar register
1715 Notify on change of register.
1716 This is a Heirloom extension and currently ignored.
1717 .It Ic \&wh Ar dist Op Ar macroname
1718 Set a page location trap.
1719 Currently unsupported.
1720 .It Ic \&while Ar condition body
1721 Repeated execution while a condition is true.
1722 Currently unsupported.
1723 .It Ic \&write Oo \(dq Oc Ns Ar string
1724 Write to an open file.
1725 Ignored because insecure.
1726 .It Ic \&writec Oo \(dq Oc Ns Ar string
1727 Write to an open file without appending a newline.
1728 Ignored because insecure.
1729 .It Ic \&writem Ar macroname
1730 Write macro or string to an open file.
1731 Ignored because insecure.
1732 .It Ic \&xflag Ar level
1733 Set the extension level.
1734 This is a Heirloom extension and currently ignored.
1735 .El
1736 .Ss Numerical expressions
1737 The
1738 .Sx \&nr ,
1739 .Sx \&if ,
1740 and
1741 .Sx \&ie
1742 requests accept integer numerical expressions as arguments.
1743 These are always evaluated using the C
1744 .Vt int
1745 type; integer overflow works the same way as in the C language.
1746 Numbers consist of an arbitrary number of digits
1747 .Sq 0
1748 to
1749 .Sq 9
1750 prefixed by an optional sign
1751 .Sq +
1752 or
1753 .Sq - .
1754 Each number may be followed by one optional scaling unit described below
1755 .Sx Scaling Widths .
1756 The following equations hold:
1757 .Bd -literal -offset indent
1758 1i = 6v = 6P = 10m = 10n = 52p = 1000M = 240u = 240
1759 254c = 100i = 24000u = 24000
1760 1f = 65536u = 65536
1761 .Ed
1762 .Pp
1763 The following binary operators are implemented.
1764 Unless otherwise stated, they behave as in the C language:
1765 .Pp
1766 .Bl -tag -width 2n -compact
1767 .It Ic +
1768 addition
1769 .It Ic -
1770 subtraction
1771 .It Ic *
1772 multiplication
1773 .It Ic /
1774 division
1775 .It Ic %
1776 remainder of division
1777 .It Ic <
1778 less than
1779 .It Ic >
1780 greater than
1781 .It Ic ==
1782 equal to
1783 .It Ic =
1784 equal to, same effect as
1785 .Ic ==
1786 (this differs from C)
1787 .It Ic <=
1788 less than or equal to
1789 .It Ic >=
1790 greater than or equal to
1791 .It Ic <>
1792 not equal to (corresponds to C
1793 .Ic != ;
1794 this one is of limited portability, it is supported by Heirloom roff,
1795 but not by groff)
1796 .It Ic &
1797 logical and (corresponds to C
1798 .Ic && )
1799 .It Ic \&:
1800 logical or (corresponds to C
1801 .Ic || )
1802 .It Ic <?
1803 minimum (not available in C)
1804 .It Ic >?
1805 maximum (not available in C)
1806 .El
1807 .Pp
1808 There is no concept of precedence; evaluation proceeds from left to right,
1809 except when subexpressions are enclosed in parentheses.
1810 Inside parentheses, whitespace is ignored.
1811 .Sh ESCAPE SEQUENCE REFERENCE
1812 The
1813 .Xr mandoc 1
1814 .Nm
1815 parser recognises the following escape sequences.
1816 Note that the
1817 .Nm
1818 language defines more escape sequences not implemented in
1819 .Xr mandoc 1 .
1820 In
1821 .Xr mdoc 5
1822 and
1823 .Xr man 5
1824 documents, using escape sequences is discouraged except for those
1825 described in the
1826 .Sx LANGUAGE SYNTAX
1827 section above.
1828 .Pp
1829 A backslash followed by any character not listed here
1830 simply prints that character itself.
1831 .Ss \e<newline>
1832 A backslash at the end of an input line can be used to continue the
1833 logical input line on the next physical input line, joining the text
1834 on both lines together as if it were on a single input line.
1835 .Ss \e<space>
1836 The escape sequence backslash-space
1837 .Pq Sq \e\ \&
1838 is an unpaddable space-sized non-breaking space character; see
1839 .Sx Whitespace .
1840 .Ss \e\(dq
1841 The rest of the input line is treated as
1842 .Sx Comments .
1843 .Ss \e%
1844 Hyphenation allowed at this point of the word; ignored by
1845 .Xr mandoc 1 .
1846 .Ss \e&
1847 Non-printing zero-width character; see
1848 .Sx Whitespace .
1849 .Ss \e\(aq
1850 Acute accent special character; use
1851 .Sq \e(aa
1852 instead.
1853 .Ss \e( Ns Ar cc
1854 .Sx Special Characters
1855 with two-letter names, see
1856 .Xr mandoc_char 5 .
1857 .Ss \e* Ns Bq Ar name
1858 Interpolate the string with the
1859 .Ar name ;
1860 see
1861 .Sx Predefined Strings
1862 and
1863 .Sx ds .
1864 For short names, there are variants
1865 .No \e* Ns Ar c
1866 and
1867 .No \e*( Ns Ar cc .
1868 .Ss \e,
1869 Left italic correction (groff extension); ignored by
1870 .Xr mandoc 1 .
1871 .Ss \e-
1872 Special character
1873 .Dq mathematical minus sign .
1874 .Ss \e/
1875 Right italic correction (groff extension); ignored by
1876 .Xr mandoc 1 .
1877 .Ss \e Ns Bq Ar name
1878 .Sx Special Characters
1879 with names of arbitrary length, see
1880 .Xr mandoc_char 5 .
1881 .Ss \e^
1882 One-twelfth em half-narrow space character, effectively zero-width in
1883 .Xr mandoc 1 .
1884 .Ss \e`
1885 Grave accent special character; use
1886 .Sq \e(ga
1887 instead.
1888 .Ss \e{
1889 Begin conditional input; see
1890 .Sx if .
1891 .Ss \e\(ba
1892 One-sixth em narrow space character, effectively zero-width in
1893 .Xr mandoc 1 .
1894 .Ss \e}
1895 End conditional input; see
1896 .Sx if .
1897 .Ss \e~
1898 Paddable non-breaking space character.
1899 .Ss \e0
1900 Digit width space character.
1901 .Ss \eA\(aq Ns Ar string Ns \(aq
1902 Anchor definition; ignored by
1903 .Xr mandoc 1 .
1904 .Ss \eB\(aq Ns Ar string Ns \(aq
1905 Interpolate
1906 .Sq 1
1907 if
1908 .Ar string
1909 conforms to the syntax of
1910 .Sx Numerical expressions
1911 explained above and
1912 .Sq 0
1913 otherwise.
1914 .Ss \eb\(aq Ns Ar string Ns \(aq
1915 Bracket building function; ignored by
1916 .Xr mandoc 1 .
1917 .Ss \eC\(aq Ns Ar name Ns \(aq
1918 .Sx Special Characters
1919 with names of arbitrary length.
1920 .Ss \ec
1921 When encountered at the end of an input text line,
1922 the next input text line is considered to continue that line,
1923 even if there are request or macro lines in between.
1924 No whitespace is inserted.
1925 .Ss \eD\(aq Ns Ar string Ns \(aq
1926 Draw graphics function; ignored by
1927 .Xr mandoc 1 .
1928 .Ss \ed
1929 Move down by half a line; ignored by
1930 .Xr mandoc 1 .
1931 .Ss \ee
1932 Backslash special character.
1933 .Ss \eF Ns Bq Ar name
1934 Switch font family (groff extension); ignored by
1935 .Xr mandoc 1 .
1936 For short names, there are variants
1937 .No \eF Ns Ar c
1938 and
1939 .No \eF( Ns Ar cc .
1940 .Ss \ef Ns Bq Ar name
1941 Switch to the font
1942 .Ar name ,
1943 see
1944 .Sx Text Decoration .
1945 For short names, there are variants
1946 .No \ef Ns Ar c
1947 and
1948 .No \ef( Ns Ar cc .
1949 .Ss \eg Ns Bq Ar name
1950 Interpolate the format of a number register; ignored by
1951 .Xr mandoc 1 .
1952 For short names, there are variants
1953 .No \eg Ns Ar c
1954 and
1955 .No \eg( Ns Ar cc .
1956 .Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
1957 Set the height of the current font; ignored by
1958 .Xr mandoc 1 .
1959 .Ss \eh\(aq Ns Oo Cm \&| Oc Ns Ar width Ns \(aq
1960 Horizontal motion.
1961 If the vertical bar is given, the motion is relative to the current
1962 indentation.
1963 Otherwise, it is relative to the current position.
1964 The default scaling unit is
1965 .Cm m .
1966 .Ss \ek Ns Bq Ar name
1967 Mark horizontal input place in register; ignored by
1968 .Xr mandoc 1 .
1969 For short names, there are variants
1970 .No \ek Ns Ar c
1971 and
1972 .No \ek( Ns Ar cc .
1973 .Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq
1974 Vertical line drawing function; ignored by
1975 .Xr mandoc 1 .
1976 .Ss \el\(aq Ns Ar width Ns Oo Ar c Oc Ns \(aq
1977 Draw a horizontal line of
1978 .Ar width
1979 using the glyph
1980 .Ar c .
1981 .Ss \eM Ns Bq Ar name
1982 Set fill (background) color (groff extension); ignored by
1983 .Xr mandoc 1 .
1984 For short names, there are variants
1985 .No \eM Ns Ar c
1986 and
1987 .No \eM( Ns Ar cc .
1988 .Ss \em Ns Bq Ar name
1989 Set glyph drawing color (groff extension); ignored by
1990 .Xr mandoc 1 .
1991 For short names, there are variants
1992 .No \em Ns Ar c
1993 and
1994 .No \em( Ns Ar cc .
1995 .Ss \eN\(aq Ns Ar number Ns \(aq
1996 Character
1997 .Ar number
1998 on the current font.
1999 .Ss \en Ns Bq Ar name
2000 Interpolate the number register
2001 .Ar name .
2002 For short names, there are variants
2003 .No \en Ns Ar c
2004 and
2005 .No \en( Ns Ar cc .
2006 .Ss \eo\(aq Ns Ar string Ns \(aq
2007 Overstrike, writing all the characters contained in the
2008 .Ar string
2009 to the same output position.
2010 In terminal and HTML output modes,
2011 only the last one of the characters is visible.
2012 .Ss \ep
2013 Break the output line at the end of the current word.
2014 .Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq
2015 Set number register; ignored by
2016 .Xr mandoc 1 .
2017 .Ss \eS\(aq Ns Ar number Ns \(aq
2018 Slant output; ignored by
2019 .Xr mandoc 1 .
2020 .Ss \es\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
2021 Change point size; ignored by
2022 .Xr mandoc 1 .
2023 Alternative forms
2024 .No \es Ns Oo +|- Oc Ns Ar n ,
2025 .No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq ,
2026 .No \es Ns Bq Oo +|- Oc Ns Ar number ,
2027 and
2028 .No \es Ns Oo +|- Oc Ns Bq Ar number
2029 are also parsed and ignored.
2030 .Ss \et
2031 Horizontal tab; ignored by
2032 .Xr mandoc 1 .
2033 .Ss \eu
2034 Move up by half a line; ignored by
2035 .Xr mandoc 1 .
2036 .Ss \eV Ns Bq Ar name
2037 Interpolate an environment variable; ignored by
2038 .Xr mandoc 1 .
2039 For short names, there are variants
2040 .No \eV Ns Ar c
2041 and
2042 .No \eV( Ns Ar cc .
2043 .Ss \ev\(aq Ns Ar number Ns \(aq
2044 Vertical motion; ignored by
2045 .Xr mandoc 1 .
2046 .Ss \ew\(aq Ns Ar string Ns \(aq
2047 Interpolate the width of the
2048 .Ar string .
2049 The
2050 .Xr mandoc 1
2051 implementation assumes that after expansion of user-defined strings, the
2052 .Ar string
2053 only contains normal characters, no escape sequences, and that each
2054 character has a width of 24 basic units.
2055 .Ss \eX\(aq Ns Ar string Ns \(aq
2056 Output
2057 .Ar string
2058 as device control function; ignored in nroff mode and by
2059 .Xr mandoc 1 .
2060 .Ss \ex\(aq Ns Ar number Ns \(aq
2061 Extra line space function; ignored by
2062 .Xr mandoc 1 .
2063 .Ss \eY Ns Bq Ar name
2064 Output a string as a device control function; ignored in nroff mode and by
2065 .Xr mandoc 1 .
2066 For short names, there are variants
2067 .No \eY Ns Ar c
2068 and
2069 .No \eY( Ns Ar cc .
2070 .Ss \eZ\(aq Ns Ar string Ns \(aq
2071 Print
2072 .Ar string
2073 with zero width and height; ignored by
2074 .Xr mandoc 1 .
2075 .Ss \ez
2076 Output the next character without advancing the cursor position.
2077 .Sh COMPATIBILITY
2078 The
2079 .Xr mandoc 1
2080 implementation of the
2081 .Nm
2082 language is intentionally incomplete.
2083 Unimplemented features include:
2084 .Pp
2085 .Bl -dash -compact
2086 .It
2087 For security reasons,
2088 .Xr mandoc 1
2089 never reads or writes external files except via
2090 .Sx \&so
2091 requests with safe relative paths.
2092 .It
2093 There is no automatic hyphenation, no adjustment to the right margin,
2094 and no centering; the output is always set flush-left.
2095 .It
2096 Support for setting tabulator positions
2097 and tabulator and leader characters is missing,
2098 and support for manually changing indentation is limited.
2099 .It
2100 The
2101 .Sq u
2102 scaling unit is the default terminal unit.
2103 In traditional troff systems, this unit changes depending on the
2104 output media.
2105 .It
2106 Width measurements are implemented in a crude way
2107 and often yield wrong results.
2108 Explicit movement requests and escapes are ignored.
2109 .It
2110 There is no concept of output pages, no support for floats,
2111 graphics drawing, and picture inclusion;
2112 terminal output is always continuous.
2113 .It
2114 Requests regarding color, font families, and glyph manipulation
2115 are ignored.
2116 Font support is very limited.
2117 Kerning is not implemented, and no ligatures are produced.
2118 .It
2119 The
2120 .Qq \(aq
2121 macro control character does not suppress output line breaks.
2122 .It
2123 Diversions are not implemented,
2124 and support for traps is very incomplete.
2125 .It
2126 While recursion is supported,
2127 .Sx \&while
2128 loops are not.
2129 .El
2130 .Pp
2131 The special semantics of the
2132 .Cm nS
2133 number register is an idiosyncracy of
2134 .Ox
2135 manuals and not supported by other
2136 .Xr mdoc 5
2137 implementations.
2138 .Sh SEE ALSO
2139 .Xr mandoc 1 ,
2140 .Xr eqn 5 ,
2141 .Xr man 5 ,
2142 .Xr mandoc_char 5 ,
2143 .Xr mdoc 5 ,
2144 .Xr tbl 5
2145 .Rs
2146 .%A Joseph F. Ossanna
2147 .%A Brian W. Kernighan
2148 .%I AT&T Bell Laboratories
2149 .%T Troff User's Manual
2150 .%R Computing Science Technical Report
2151 .%N 54
2152 .%C Murray Hill, New Jersey
2153 .%D 1976 and 1992
2154 .%U http://www.kohala.com/start/troff/cstr54.ps
2155 .Re
2156 .Rs
2157 .%A Joseph F. Ossanna
2158 .%A Brian W. Kernighan
2159 .%A Gunnar Ritter
2160 .%T Heirloom Documentation Tools Nroff/Troff User's Manual
2161 .%D September 17, 2007
2162 .%U http://heirloom.sourceforge.net/doctools/troff.pdf
2163 .Re
2164 .Sh HISTORY
2165 The RUNOFF typesetting system, whose input forms the basis for
2166 .Nm ,
2167 was written in MAD and FAP for the CTSS operating system by Jerome E.
2168 Saltzer in 1964.
2169 Doug McIlroy rewrote it in BCPL in 1969, renaming it
2170 .Nm .
2171 Dennis M. Ritchie rewrote McIlroy's
2172 .Nm
2173 in PDP-11 assembly for
2174 .At v1 ,
2175 Joseph F. Ossanna improved roff and renamed it nroff
2176 for
2177 .At v2 ,
2178 then ported nroff to C as troff, which Brian W. Kernighan released with
2179 .At v7 .
2180 In 1989, James Clarke re-implemented troff in C++, naming it groff.
2181 .Sh AUTHORS
2182 .An -nosplit
2183 This
2184 .Nm
2185 reference was written by
2186 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
2187 and
2188 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .