bc5507488d3e8a4af2fa80498bde76a1843fb1d3
[dragonfly.git] / contrib / mdocml / roff.7
1 .\"     $Id: roff.7,v 1.45 2013/12/15 21:23:52 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2010, 2011 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: October 22 2013 $
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 intermixed with their
36 .Xr mdoc 7
37 or
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.
45 Only these requests 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
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 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 .Ss Comments
97 Text following an escaped double-quote
98 .Sq \e\(dq ,
99 whether in a request, macro, or text line, is ignored to the end of the line.
100 A request line beginning with a control character and comment escape
101 .Sq \&.\e\(dq
102 is also ignored.
103 Furthermore, request lines with only a control character and optional
104 trailing whitespace are stripped from input.
105 .Pp
106 Examples:
107 .Bd -literal -offset indent -compact
108 \&.\e\(dq This is a comment line.
109 \&.\e\(dq The next line is ignored:
110 \&.
111 \&.Sh EXAMPLES \e\(dq This is a comment, too.
112 \&example text \e\(dq And so is this.
113 .Ed
114 .Ss Special Characters
115 Special characters are used to encode special glyphs and are rendered
116 differently across output media.
117 They may occur in request, macro, and text lines.
118 Sequences begin with the escape character
119 .Sq \e
120 followed by either an open-parenthesis
121 .Sq \&(
122 for two-character sequences; an open-bracket
123 .Sq \&[
124 for n-character sequences (terminated at a close-bracket
125 .Sq \&] ) ;
126 or a single one character sequence.
127 .Pp
128 Examples:
129 .Bl -tag -width Ds -offset indent -compact
130 .It Li \e(em
131 Two-letter em dash escape.
132 .It Li \ee
133 One-letter backslash escape.
134 .El
135 .Pp
136 See
137 .Xr mandoc_char 7
138 for a complete list.
139 .Ss Text Decoration
140 Terms may be text-decorated using the
141 .Sq \ef
142 escape followed by an indicator: B (bold), I (italic), R (regular), or P
143 (revert to previous mode).
144 A numerical representation 3, 2, or 1 (bold, italic, and regular,
145 respectively) may be used instead.
146 The indicator or numerical representative may be preceded by C
147 (constant-width), which is ignored.
148 .Pp
149 The two-character indicator
150 .Sq BI
151 requests a font that is both bold and italic.
152 It may not be portable to old roff implementations.
153 .Pp
154 Examples:
155 .Bl -tag -width Ds -offset indent -compact
156 .It Li \efBbold\efR
157 Write in \fBbold\fP, then switch to regular font mode.
158 .It Li \efIitalic\efP
159 Write in \fIitalic\fP, then return to previous font mode.
160 .It Li \ef(BIbold italic\efP
161 Write in \f(BIbold italic\fP, then return to previous font mode.
162 .El
163 .Pp
164 Text decoration is
165 .Em not
166 recommended for
167 .Xr mdoc 7 ,
168 which encourages semantic annotation.
169 .Ss Predefined Strings
170 Predefined strings, like
171 .Sx Special Characters ,
172 mark special output glyphs.
173 Predefined strings are escaped with the slash-asterisk,
174 .Sq \e* :
175 single-character
176 .Sq \e*X ,
177 two-character
178 .Sq \e*(XX ,
179 and N-character
180 .Sq \e*[N] .
181 .Pp
182 Examples:
183 .Bl -tag -width Ds -offset indent -compact
184 .It Li \e*(Am
185 Two-letter ampersand predefined string.
186 .It Li \e*q
187 One-letter double-quote predefined string.
188 .El
189 .Pp
190 Predefined strings are not recommended for use,
191 as they differ across implementations.
192 Those supported by
193 .Xr mandoc 1
194 are listed in
195 .Xr mandoc_char 7 .
196 Manuals using these predefined strings are almost certainly not portable.
197 .Ss Whitespace
198 Whitespace consists of the space character.
199 In text lines, whitespace is preserved within a line.
200 In request and macro lines, whitespace delimits arguments and is discarded.
201 .Pp
202 Unescaped trailing spaces are stripped from text line input unless in a
203 literal context.
204 In general, trailing whitespace on any input line is discouraged for
205 reasons of portability.
206 In the rare case that a blank character is needed at the end of an
207 input line, it may be forced by
208 .Sq \e\ \e& .
209 .Pp
210 Literal space characters can be produced in the output
211 using escape sequences.
212 In macro lines, they can also be included in arguments using quotation; see
213 .Sx MACRO SYNTAX
214 for details.
215 .Pp
216 Blank text lines, which may include whitespace, are only permitted
217 within literal contexts.
218 If the first character of a text line is a space, that line is printed
219 with a leading newline.
220 .Ss Scaling Widths
221 Many requests and macros support scaled widths for their arguments.
222 The syntax for a scaled width is
223 .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
224 where a decimal must be preceded or followed by at least one digit.
225 Negative numbers, while accepted, are truncated to zero.
226 .Pp
227 The following scaling units are accepted:
228 .Pp
229 .Bl -tag -width Ds -offset indent -compact
230 .It c
231 centimetre
232 .It i
233 inch
234 .It P
235 pica (~1/6 inch)
236 .It p
237 point (~1/72 inch)
238 .It f
239 synonym for
240 .Sq u
241 .It v
242 default vertical span
243 .It m
244 width of rendered
245 .Sq m
246 .Pq em
247 character
248 .It n
249 width of rendered
250 .Sq n
251 .Pq en
252 character
253 .It u
254 default horizontal span
255 .It M
256 mini-em (~1/100 em)
257 .El
258 .Pp
259 Using anything other than
260 .Sq m ,
261 .Sq n ,
262 .Sq u ,
263 or
264 .Sq v
265 is necessarily non-portable across output media.
266 See
267 .Sx COMPATIBILITY .
268 .Pp
269 If a scaling unit is not provided, the numerical value is interpreted
270 under the default rules of
271 .Sq v
272 for vertical spaces and
273 .Sq u
274 for horizontal ones.
275 .Pp
276 Examples:
277 .Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact
278 .It Li \&.Bl -tag -width 2i
279 two-inch tagged list indentation in
280 .Xr mdoc 7
281 .It Li \&.HP 2i
282 two-inch tagged list indentation in
283 .Xr man 7
284 .It Li \&.sp 2v
285 two vertical spaces
286 .El
287 .Ss Sentence Spacing
288 Each sentence should terminate at the end of an input line.
289 By doing this, a formatter will be able to apply the proper amount of
290 spacing after the end of sentence (unescaped) period, exclamation mark,
291 or question mark followed by zero or more non-sentence closing
292 delimiters
293 .Po
294 .Sq \&) ,
295 .Sq \&] ,
296 .Sq \&' ,
297 .Sq \&"
298 .Pc .
299 .Pp
300 The proper spacing is also intelligently preserved if a sentence ends at
301 the boundary of a macro line.
302 .Pp
303 Examples:
304 .Bd -literal -offset indent -compact
305 Do not end sentences mid-line like this.  Instead,
306 end a sentence like this.
307 A macro would end like this:
308 \&.Xr mandoc 1 \&.
309 .Ed
310 .Sh REQUEST SYNTAX
311 A request or macro line consists of:
312 .Pp
313 .Bl -enum -compact
314 .It
315 the control character
316 .Sq \&.
317 or
318 .Sq \(aq
319 at the beginning of the line,
320 .It
321 optionally an arbitrary amount of whitespace,
322 .It
323 the name of the request or the macro, which is one word of arbitrary
324 length, terminated by whitespace,
325 .It
326 and zero or more arguments delimited by whitespace.
327 .El
328 .Pp
329 Thus, the following request lines are all equivalent:
330 .Bd -literal -offset indent
331 \&.ig end
332 \&.ig    end
333 \&.   ig end
334 .Ed
335 .Sh MACRO SYNTAX
336 Macros are provided by the
337 .Xr mdoc 7
338 and
339 .Xr man 7
340 languages and can be defined by the
341 .Sx \&de
342 request.
343 When called, they follow the same syntax as requests, except that
344 macro arguments may optionally be quoted by enclosing them
345 in double quote characters
346 .Pq Sq \(dq .
347 Quoted text, even if it contains whitespace or would cause
348 a macro invocation when unquoted, is always considered literal text.
349 Inside quoted text, pairs of double quote characters
350 .Pq Sq Qq
351 resolve to single double quote characters.
352 .Pp
353 To be recognised as the beginning of a quoted argument, the opening
354 quote character must be preceded by a space character.
355 A quoted argument extends to the next double quote character that is not
356 part of a pair, or to the end of the input line, whichever comes earlier.
357 Leaving out the terminating double quote character at the end of the line
358 is discouraged.
359 For clarity, if more arguments follow on the same input line,
360 it is recommended to follow the terminating double quote character
361 by a space character; in case the next character after the terminating
362 double quote character is anything else, it is regarded as the beginning
363 of the next, unquoted argument.
364 .Pp
365 Both in quoted and unquoted arguments, pairs of backslashes
366 .Pq Sq \e\e
367 resolve to single backslashes.
368 In unquoted arguments, space characters can alternatively be included
369 by preceding them with a backslash
370 .Pq Sq \e\~ ,
371 but quoting is usually better for clarity.
372 .Pp
373 Examples:
374 .Bl -tag -width Ds -offset indent -compact
375 .It Li .Fn strlen \(dqconst char *s\(dq
376 Group arguments
377 .Qq const char *s
378 into one function argument.
379 If unspecified,
380 .Qq const ,
381 .Qq char ,
382 and
383 .Qq *s
384 would be considered separate arguments.
385 .It Li .Op \(dqFl a\(dq
386 Consider
387 .Qq \&Fl a
388 as literal text instead of a flag macro.
389 .El
390 .Sh REQUEST REFERENCE
391 The
392 .Xr mandoc 1
393 .Nm
394 parser recognises the following requests.
395 Note that the
396 .Nm
397 language defines many more requests not implemented in
398 .Xr mandoc 1 .
399 .Ss \&ad
400 Set line adjustment mode.
401 This line-scoped request is intended to have one argument to select
402 normal, left, right, or centre adjustment for subsequent text.
403 Currently, it is ignored including its arguments,
404 and the number of arguments is not checked.
405 .Ss \&am
406 Append to a macro definition.
407 The syntax of this request is the same as that of
408 .Sx \&de .
409 It is currently ignored by
410 .Xr mandoc 1 ,
411 as are its children.
412 .Ss \&ami
413 Append to a macro definition, specifying the macro name indirectly.
414 The syntax of this request is the same as that of
415 .Sx \&dei .
416 It is currently ignored by
417 .Xr mandoc 1 ,
418 as are its children.
419 .Ss \&am1
420 Append to a macro definition, switching roff compatibility mode off
421 during macro execution.
422 The syntax of this request is the same as that of
423 .Sx \&de1 .
424 It is currently ignored by
425 .Xr mandoc 1 ,
426 as are its children.
427 .Ss \&cc
428 Changes the control character.
429 Its syntax is as follows:
430 .Bd -literal -offset indent
431 .Pf . Cm \&cc Op Ar c
432 .Ed
433 .Pp
434 If
435 .Ar c
436 is not specified, the control character is reset to
437 .Sq \&. .
438 Trailing characters are ignored.
439 .Ss \&de
440 Define a
441 .Nm
442 macro.
443 Its syntax can be either
444 .Bd -literal -offset indent
445 .Pf . Cm \&de Ar name
446 .Ar macro definition
447 \&..
448 .Ed
449 .Pp
450 or
451 .Bd -literal -offset indent
452 .Pf . Cm \&de Ar name Ar end
453 .Ar macro definition
454 .Pf . Ar end
455 .Ed
456 .Pp
457 Both forms define or redefine the macro
458 .Ar name
459 to represent the
460 .Ar macro definition ,
461 which may consist of one or more input lines, including the newline
462 characters terminating each line, optionally containing calls to
463 .Nm
464 requests,
465 .Nm
466 macros or high-level macros like
467 .Xr man 7
468 or
469 .Xr mdoc 7
470 macros, whichever applies to the document in question.
471 .Pp
472 Specifying a custom
473 .Ar end
474 macro works in the same way as for
475 .Sx \&ig ;
476 namely, the call to
477 .Sq Pf . Ar end
478 first ends the
479 .Ar macro definition ,
480 and after that, it is also evaluated as a
481 .Nm
482 request or
483 .Nm
484 macro, but not as a high-level macro.
485 .Pp
486 The macro can be invoked later using the syntax
487 .Pp
488 .D1 Pf . Ar name Op Ar argument Op Ar argument ...
489 .Pp
490 Regarding argument parsing, see
491 .Sx MACRO SYNTAX
492 above.
493 .Pp
494 The line invoking the macro will be replaced
495 in the input stream by the
496 .Ar macro definition ,
497 replacing all occurrences of
498 .No \e\e$ Ns Ar N ,
499 where
500 .Ar N
501 is a digit, by the
502 .Ar N Ns th Ar argument .
503 For example,
504 .Bd -literal -offset indent
505 \&.de ZN
506 \efI\e^\e\e$1\e^\efP\e\e$2
507 \&..
508 \&.ZN XtFree .
509 .Ed
510 .Pp
511 produces
512 .Pp
513 .D1 \efI\e^XtFree\e^\efP.
514 .Pp
515 in the input stream, and thus in the output: \fI\^XtFree\^\fP.
516 .Pp
517 Since macros and user-defined strings share a common string table,
518 defining a macro
519 .Ar name
520 clobbers the user-defined string
521 .Ar name ,
522 and the
523 .Ar macro definition
524 can also be printed using the
525 .Sq \e*
526 string interpolation syntax described below
527 .Sx ds ,
528 but this is rarely useful because every macro definition contains at least
529 one explicit newline character.
530 .Pp
531 In order to prevent endless recursion, both groff and
532 .Xr mandoc 1
533 limit the stack depth for expanding macros and strings
534 to a large, but finite number.
535 Do not rely on the exact value of this limit.
536 .Ss \&dei
537 Define a
538 .Nm
539 macro, specifying the macro name indirectly.
540 The syntax of this request is the same as that of
541 .Sx \&de .
542 It is currently ignored by
543 .Xr mandoc 1 ,
544 as are its children.
545 .Ss \&de1
546 Define a
547 .Nm
548 macro that will be executed with
549 .Nm
550 compatibility mode switched off during macro execution.
551 This is a GNU extension not available in traditional
552 .Nm
553 implementations and not even in older versions of groff.
554 Since
555 .Xr mandoc 1
556 does not implement
557 .Nm
558 compatibility mode at all, it handles this request as an alias for
559 .Sx \&de .
560 .Ss \&ds
561 Define a user-defined string.
562 Its syntax is as follows:
563 .Pp
564 .D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
565 .Pp
566 The
567 .Ar name
568 and
569 .Ar string
570 arguments are space-separated.
571 If the
572 .Ar string
573 begins with a double-quote character, that character will not be part
574 of the string.
575 All remaining characters on the input line form the
576 .Ar string ,
577 including whitespace and double-quote characters, even trailing ones.
578 .Pp
579 The
580 .Ar string
581 can be interpolated into subsequent text by using
582 .No \e* Ns Bq Ar name
583 for a
584 .Ar name
585 of arbitrary length, or \e*(NN or \e*N if the length of
586 .Ar name
587 is two or one characters, respectively.
588 Interpolation can be prevented by escaping the leading backslash;
589 that is, an asterisk preceded by an even number of backslashes
590 does not trigger string interpolation.
591 .Pp
592 Since user-defined strings and macros share a common string table,
593 defining a string
594 .Ar name
595 clobbers the macro
596 .Ar name ,
597 and the
598 .Ar name
599 used for defining a string can also be invoked as a macro,
600 in which case the following input line will be appended to the
601 .Ar string ,
602 forming a new input line passed to the
603 .Nm
604 parser.
605 For example,
606 .Bd -literal -offset indent
607 \&.ds badidea .S
608 \&.badidea
609 H SYNOPSIS
610 .Ed
611 .Pp
612 invokes the
613 .Cm SH
614 macro when used in a
615 .Xr man 7
616 document.
617 Such abuse is of course strongly discouraged.
618 .Ss \&el
619 The
620 .Qq else
621 half of an if/else conditional.
622 Pops a result off the stack of conditional evaluations pushed by
623 .Sx \&ie
624 and uses it as its conditional.
625 If no stack entries are present (e.g., due to no prior
626 .Sx \&ie
627 calls)
628 then false is assumed.
629 The syntax of this request is similar to
630 .Sx \&if
631 except that the conditional is missing.
632 .Ss \&EN
633 End an equation block.
634 See
635 .Sx \&EQ .
636 .Ss \&EQ
637 Begin an equation block.
638 See
639 .Xr eqn 7
640 for a description of the equation language.
641 .Ss \&fam
642 Change the font family.
643 This line-scoped request is intended to have one argument specifying
644 the font family to be selected.
645 It is a groff extension, and currently, it is ignored including its
646 arguments, and the number of arguments is not checked.
647 .Ss \&hw
648 Specify hyphenation points in words.
649 This line-scoped request is currently ignored.
650 .Ss \&hy
651 Set automatic hyphenation mode.
652 This line-scoped request is currently ignored.
653 .Ss \&ie
654 The
655 .Qq if
656 half of an if/else conditional.
657 The result of the conditional is pushed into a stack used by subsequent
658 invocations of
659 .Sx \&el ,
660 which may be separated by any intervening input (or not exist at all).
661 Its syntax is equivalent to
662 .Sx \&if .
663 .Ss \&if
664 Begins a conditional.
665 Right now, the conditional evaluates to true
666 if and only if it starts with the letter
667 .Sy n ,
668 indicating processing in nroff style as opposed to troff style.
669 If a conditional is false, its children are not processed, but are
670 syntactically interpreted to preserve the integrity of the input
671 document.
672 Thus,
673 .Pp
674 .D1 \&.if t .ig
675 .Pp
676 will discard the
677 .Sq \&.ig ,
678 which may lead to interesting results, but
679 .Pp
680 .D1 \&.if t .if t \e{\e
681 .Pp
682 will continue to syntactically interpret to the block close of the final
683 conditional.
684 Sub-conditionals, in this case, obviously inherit the truth value of
685 the parent.
686 This request has the following syntax:
687 .Bd -literal -offset indent
688 \&.if COND \e{\e
689 BODY...
690 \&.\e}
691 .Ed
692 .Bd -literal -offset indent
693 \&.if COND \e{ BODY
694 BODY... \e}
695 .Ed
696 .Bd -literal -offset indent
697 \&.if COND \e{ BODY
698 BODY...
699 \&.\e}
700 .Ed
701 .Bd -literal -offset indent
702 \&.if COND \e
703 BODY
704 .Ed
705 .Pp
706 COND is a conditional statement.
707 roff allows for complicated conditionals; mandoc is much simpler.
708 At this time, mandoc supports only
709 .Sq n ,
710 evaluating to true;
711 and
712 .Sq t ,
713 .Sq e ,
714 and
715 .Sq o ,
716 evaluating to false.
717 All other invocations are read up to the next end of line or space and
718 evaluate as false.
719 .Pp
720 If the BODY section is begun by an escaped brace
721 .Sq \e{ ,
722 scope continues until a closing-brace escape sequence
723 .Sq \.\e} .
724 If the BODY is not enclosed in braces, scope continues until
725 the end of the line.
726 If the COND is followed by a BODY on the same line, whether after a
727 brace or not, then requests and macros
728 .Em must
729 begin with a control character.
730 It is generally more intuitive, in this case, to write
731 .Bd -literal -offset indent
732 \&.if COND \e{\e
733 \&.foo
734 bar
735 \&.\e}
736 .Ed
737 .Pp
738 than having the request or macro follow as
739 .Pp
740 .D1 \&.if COND \e{ .foo
741 .Pp
742 The scope of a conditional is always parsed, but only executed if the
743 conditional evaluates to true.
744 .Pp
745 Note that the
746 .Sq \e}
747 is converted into a zero-width escape sequence if not passed as a
748 standalone macro
749 .Sq \&.\e} .
750 For example,
751 .Pp
752 .D1 \&.Fl a \e} b
753 .Pp
754 will result in
755 .Sq \e}
756 being considered an argument of the
757 .Sq \&Fl
758 macro.
759 .Ss \&ig
760 Ignore input.
761 Its syntax can be either
762 .Bd -literal -offset indent
763 .Pf . Cm \&ig
764 .Ar ignored text
765 \&..
766 .Ed
767 .Pp
768 or
769 .Bd -literal -offset indent
770 .Pf . Cm \&ig Ar end
771 .Ar ignored text
772 .Pf . Ar end
773 .Ed
774 .Pp
775 In the first case, input is ignored until a
776 .Sq \&..
777 request is encountered on its own line.
778 In the second case, input is ignored until the specified
779 .Sq Pf . Ar end
780 macro is encountered.
781 Do not use the escape character
782 .Sq \e
783 anywhere in the definition of
784 .Ar end ;
785 it would cause very strange behaviour.
786 .Pp
787 When the
788 .Ar end
789 macro is a roff request or a roff macro, like in
790 .Pp
791 .D1 \&.ig if
792 .Pp
793 the subsequent invocation of
794 .Sx \&if
795 will first terminate the
796 .Ar ignored text ,
797 then be invoked as usual.
798 Otherwise, it only terminates the
799 .Ar ignored text ,
800 and arguments following it or the
801 .Sq \&..
802 request are discarded.
803 .Ss \&ne
804 Declare the need for the specified minimum vertical space
805 before the next trap or the bottom of the page.
806 This line-scoped request is currently ignored.
807 .Ss \&nh
808 Turn off automatic hyphenation mode.
809 This line-scoped request is currently ignored.
810 .Ss \&rm
811 Remove a request, macro or string.
812 This request is intended to have one argument,
813 the name of the request, macro or string to be undefined.
814 Currently, it is ignored including its arguments,
815 and the number of arguments is not checked.
816 .Ss \&nr
817 Define or change a register.
818 A register is an arbitrary string value that defines some sort of state,
819 which influences parsing and/or formatting.
820 Its syntax is as follows:
821 .Pp
822 .D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar value
823 .Pp
824 The
825 .Ar value
826 may, at the moment, only be an integer.
827 If it is prefixed by a sign, the register will be 
828 incremented or decremented instead of assigned to.
829 .Pp
830 The following register
831 .Ar name
832 is handled specially:
833 .Bl -tag -width Ds
834 .It Cm nS
835 If set to a positive integer value, certain
836 .Xr mdoc 7
837 macros will behave in the same way as in the
838 .Em SYNOPSIS
839 section.
840 If set to 0, these macros will behave in the same way as outside the
841 .Em SYNOPSIS
842 section, even when called within the
843 .Em SYNOPSIS
844 section itself.
845 Note that starting a new
846 .Xr mdoc 7
847 section with the
848 .Cm \&Sh
849 macro will reset this register.
850 .El
851 .Ss \&ns
852 Turn on no-space mode.
853 This line-scoped request is intended to take no arguments.
854 Currently, it is ignored including its arguments,
855 and the number of arguments is not checked.
856 .Ss \&ps
857 Change point size.
858 This line-scoped request is intended to take one numerical argument.
859 Currently, it is ignored including its arguments,
860 and the number of arguments is not checked.
861 .Ss \&so
862 Include a source file.
863 Its syntax is as follows:
864 .Pp
865 .D1 Pf \. Cm \&so Ar file
866 .Pp
867 The
868 .Ar file
869 will be read and its contents processed as input in place of the
870 .Sq \&.so
871 request line.
872 To avoid inadvertent inclusion of unrelated files,
873 .Xr mandoc 1
874 only accepts relative paths not containing the strings
875 .Qq ../
876 and
877 .Qq /.. .
878 .Pp
879 This request requires
880 .Xr man 1
881 to change to the right directory before calling
882 .Xr mandoc 1 ,
883 per convention to the root of the manual tree.
884 Typical usage looks like:
885 .Pp
886 .Dl \&.so man3/Xcursor.3
887 .Pp
888 As the whole concept is rather fragile, the use of
889 .Sx \&so
890 is discouraged.
891 Use
892 .Xr ln 1
893 instead.
894 .Ss \&ta
895 Set tab stops.
896 This line-scoped request can take an arbitrary number of arguments.
897 Currently, it is ignored including its arguments.
898 .Ss \&tr
899 Output character translation.
900 Its syntax is as follows:
901 .Pp
902 .D1 Pf \. Cm \&tr Ar [ab]+
903 .Pp
904 Pairs of
905 .Ar ab
906 characters are replaced
907 .Ar ( a
908 for
909 .Ar b ) .
910 Replacement (or origin) characters may also be character escapes; thus,
911 .Pp
912 .Dl tr \e(xx\e(yy
913 .Pp
914 replaces all invocations of \e(xx with \e(yy.
915 .Ss \&T&
916 Re-start a table layout, retaining the options of the prior table
917 invocation.
918 See
919 .Sx \&TS .
920 .Ss \&TE
921 End a table context.
922 See
923 .Sx \&TS .
924 .Ss \&TS
925 Begin a table, which formats input in aligned rows and columns.
926 See
927 .Xr tbl 7
928 for a description of the tbl language.
929 .Sh COMPATIBILITY
930 This section documents compatibility between mandoc and other
931 .Nm
932 implementations, at this time limited to GNU troff
933 .Pq Qq groff .
934 The term
935 .Qq historic groff
936 refers to groff version 1.15.
937 .Pp
938 .Bl -dash -compact
939 .It
940 In mandoc, the
941 .Sx \&EQ ,
942 .Sx \&TE ,
943 .Sx \&TS ,
944 and
945 .Sx \&T& ,
946 macros are considered regular macros.
947 In all other
948 .Nm
949 implementations, these are special macros that must be specified without
950 spacing between the control character (which must be a period) and the
951 macro name.
952 .It
953 The
954 .Cm nS
955 register is only compatible with OpenBSD's groff-1.15.
956 .It
957 Historic groff did not accept white-space before a custom
958 .Ar end
959 macro for the
960 .Sx \&ig
961 request.
962 .It
963 The
964 .Sx \&if
965 and family would print funny white-spaces with historic groff when
966 using the next-line syntax.
967 .El
968 .Sh SEE ALSO
969 .Xr mandoc 1 ,
970 .Xr eqn 7 ,
971 .Xr man 7 ,
972 .Xr mandoc_char 7 ,
973 .Xr mdoc 7 ,
974 .Xr tbl 7
975 .Rs
976 .%A Joseph F. Ossanna
977 .%A Brian W. Kernighan
978 .%I AT&T Bell Laboratories
979 .%T Troff User's Manual
980 .%R Computing Science Technical Report
981 .%N 54
982 .%C Murray Hill, New Jersey
983 .%D 1976 and 1992
984 .%U http://www.kohala.com/start/troff/cstr54.ps
985 .Re
986 .Rs
987 .%A Joseph F. Ossanna
988 .%A Brian W. Kernighan
989 .%A Gunnar Ritter
990 .%T Heirloom Documentation Tools Nroff/Troff User's Manual
991 .%D September 17, 2007
992 .%U http://heirloom.sourceforge.net/doctools/troff.pdf
993 .Re
994 .Sh HISTORY
995 The RUNOFF typesetting system, whose input forms the basis for
996 .Nm ,
997 was written in MAD and FAP for the CTSS operating system by Jerome E.
998 Saltzer in 1964.
999 Doug McIlroy rewrote it in BCPL in 1969, renaming it
1000 .Nm .
1001 Dennis M. Ritchie rewrote McIlroy's
1002 .Nm
1003 in PDP-11 assembly for
1004 .At v1 ,
1005 Joseph F. Ossanna improved roff and renamed it nroff
1006 for
1007 .At v2 ,
1008 then ported nroff to C as troff, which Brian W. Kernighan released with
1009 .At v7 .
1010 In 1989, James Clarke re-implemented troff in C++, naming it groff.
1011 .Sh AUTHORS
1012 .An -nosplit
1013 This
1014 .Nm
1015 reference was written by
1016 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1017 and
1018 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .