sbin/mount_hammer: Use calloc(3) and cleanups
[dragonfly.git] / contrib / mdocml / roff.7
blobbc2f24e45b3fb115321e60bda8fd60c9fda7badf
1 .\"     $Id: roff.7,v 1.55 2014/07/07 11:35:06 schwarze Exp $
2 .\"
3 .\" Copyright (c) 2010, 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2010, 2011, 2013, 2014 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 7 2014 $
19 .Dt ROFF 7
20 .Os
21 .Sh NAME
22 .Nm roff
23 .Nd roff language reference for mandoc
24 .Sh DESCRIPTION
25 The
26 .Nm roff
27 language is a general purpose text formatting language.
28 Since traditional implementations of the
29 .Xr mdoc 7
30 and
31 .Xr man 7
32 manual formatting languages are based on it,
33 many real-world manuals use small numbers of
34 .Nm
35 requests and escape sequences intermixed with their
36 .Xr mdoc 7
38 .Xr man 7
39 code.
40 To properly format such manuals, the
41 .Xr mandoc 1
42 utility supports a tiny subset of
43 .Nm
44 requests and escapes.
45 Only these requests and escapes supported by
46 .Xr mandoc 1
47 are documented in the present manual,
48 together with the basic language syntax shared by
49 .Nm ,
50 .Xr mdoc 7 ,
51 and
52 .Xr man 7 .
53 For complete
54 .Nm
55 manuals, consult the
56 .Sx SEE ALSO
57 section.
58 .Pp
59 Input lines beginning with the control character
60 .Sq \&.
61 are parsed for requests and macros.
62 Such lines are called
63 .Dq request lines
65 .Dq macro lines ,
66 respectively.
67 Requests change the processing state and manipulate the formatting;
68 some macros also define the document structure and produce formatted
69 output.
70 The single quote
71 .Pq Qq \(aq
72 is accepted as an alternative control character,
73 treated by
74 .Xr mandoc 1
75 just like
76 .Ql \&.
77 .Pp
78 Lines not beginning with control characters are called
79 .Dq text lines .
80 They provide free-form text to be printed; the formatting of the text
81 depends on the respective processing context.
82 .Sh LANGUAGE SYNTAX
83 .Nm
84 documents may contain only graphable 7-bit ASCII characters, the space
85 character, and, in certain circumstances, the tab character.
86 The backslash character
87 .Sq \e
88 indicates the start of an escape sequence, used for example for
89 .Sx Comments ,
90 .Sx Special Characters ,
91 .Sx Predefined Strings ,
92 and
93 user-defined strings defined using the
94 .Sx ds
95 request.
96 For a listing of escape sequences, consult the
97 .Sx ESCAPE SEQUENCE REFERENCE
98 below.
99 .Ss Comments
100 Text following an escaped double-quote
101 .Sq \e\(dq ,
102 whether in a request, macro, or text line, is ignored to the end of the line.
103 A request line beginning with a control character and comment escape
104 .Sq \&.\e\(dq
105 is also ignored.
106 Furthermore, request lines with only a control character and optional
107 trailing whitespace are stripped from input.
109 Examples:
110 .Bd -literal -offset indent -compact
111 \&.\e\(dq This is a comment line.
112 \&.\e\(dq The next line is ignored:
114 \&.Sh EXAMPLES \e\(dq This is a comment, too.
115 \&example text \e\(dq And so is this.
117 .Ss Special Characters
118 Special characters are used to encode special glyphs and are rendered
119 differently across output media.
120 They may occur in request, macro, and text lines.
121 Sequences begin with the escape character
122 .Sq \e
123 followed by either an open-parenthesis
124 .Sq \&(
125 for two-character sequences; an open-bracket
126 .Sq \&[
127 for n-character sequences (terminated at a close-bracket
128 .Sq \&] ) ;
129 or a single one character sequence.
131 Examples:
132 .Bl -tag -width Ds -offset indent -compact
133 .It Li \e(em
134 Two-letter em dash escape.
135 .It Li \ee
136 One-letter backslash escape.
140 .Xr mandoc_char 7
141 for a complete list.
142 .Ss Text Decoration
143 Terms may be text-decorated using the
144 .Sq \ef
145 escape followed by an indicator: B (bold), I (italic), R (regular), or P
146 (revert to previous mode).
147 A numerical representation 3, 2, or 1 (bold, italic, and regular,
148 respectively) may be used instead.
149 The indicator or numerical representative may be preceded by C
150 (constant-width), which is ignored.
152 The two-character indicator
153 .Sq BI
154 requests a font that is both bold and italic.
155 It may not be portable to old roff implementations.
157 Examples:
158 .Bl -tag -width Ds -offset indent -compact
159 .It Li \efBbold\efR
160 Write in \fBbold\fP, then switch to regular font mode.
161 .It Li \efIitalic\efP
162 Write in \fIitalic\fP, then return to previous font mode.
163 .It Li \ef(BIbold italic\efP
164 Write in \f(BIbold italic\fP, then return to previous font mode.
167 Text decoration is
168 .Em not
169 recommended for
170 .Xr mdoc 7 ,
171 which encourages semantic annotation.
172 .Ss Predefined Strings
173 Predefined strings, like
174 .Sx Special Characters ,
175 mark special output glyphs.
176 Predefined strings are escaped with the slash-asterisk,
177 .Sq \e* :
178 single-character
179 .Sq \e*X ,
180 two-character
181 .Sq \e*(XX ,
182 and N-character
183 .Sq \e*[N] .
185 Examples:
186 .Bl -tag -width Ds -offset indent -compact
187 .It Li \e*(Am
188 Two-letter ampersand predefined string.
189 .It Li \e*q
190 One-letter double-quote predefined string.
193 Predefined strings are not recommended for use,
194 as they differ across implementations.
195 Those supported by
196 .Xr mandoc 1
197 are listed in
198 .Xr mandoc_char 7 .
199 Manuals using these predefined strings are almost certainly not portable.
200 .Ss Whitespace
201 Whitespace consists of the space character.
202 In text lines, whitespace is preserved within a line.
203 In request and macro lines, whitespace delimits arguments and is discarded.
205 Unescaped trailing spaces are stripped from text line input unless in a
206 literal context.
207 In general, trailing whitespace on any input line is discouraged for
208 reasons of portability.
209 In the rare case that a blank character is needed at the end of an
210 input line, it may be forced by
211 .Sq \e\ \e& .
213 Literal space characters can be produced in the output
214 using escape sequences.
215 In macro lines, they can also be included in arguments using quotation; see
216 .Sx MACRO SYNTAX
217 for details.
219 Blank text lines, which may include whitespace, are only permitted
220 within literal contexts.
221 If the first character of a text line is a space, that line is printed
222 with a leading newline.
223 .Ss Scaling Widths
224 Many requests and macros support scaled widths for their arguments.
225 The syntax for a scaled width is
226 .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
227 where a decimal must be preceded or followed by at least one digit.
228 Negative numbers, while accepted, are truncated to zero.
230 The following scaling units are accepted:
232 .Bl -tag -width Ds -offset indent -compact
233 .It c
234 centimetre
235 .It i
236 inch
237 .It P
238 pica (~1/6 inch)
239 .It p
240 point (~1/72 inch)
241 .It f
242 synonym for
243 .Sq u
244 .It v
245 default vertical span
246 .It m
247 width of rendered
248 .Sq m
249 .Pq em
250 character
251 .It n
252 width of rendered
253 .Sq n
254 .Pq en
255 character
256 .It u
257 default horizontal span
258 .It M
259 mini-em (~1/100 em)
262 Using anything other than
263 .Sq m ,
264 .Sq n ,
265 .Sq u ,
267 .Sq v
268 is necessarily non-portable across output media.
270 .Sx COMPATIBILITY .
272 If a scaling unit is not provided, the numerical value is interpreted
273 under the default rules of
274 .Sq v
275 for vertical spaces and
276 .Sq u
277 for horizontal ones.
279 Examples:
280 .Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact
281 .It Li \&.Bl -tag -width 2i
282 two-inch tagged list indentation in
283 .Xr mdoc 7
284 .It Li \&.HP 2i
285 two-inch tagged list indentation in
286 .Xr man 7
287 .It Li \&.sp 2v
288 two vertical spaces
290 .Ss Sentence Spacing
291 Each sentence should terminate at the end of an input line.
292 By doing this, a formatter will be able to apply the proper amount of
293 spacing after the end of sentence (unescaped) period, exclamation mark,
294 or question mark followed by zero or more non-sentence closing
295 delimiters
297 .Sq \&) ,
298 .Sq \&] ,
299 .Sq \&' ,
300 .Sq \&"
301 .Pc .
303 The proper spacing is also intelligently preserved if a sentence ends at
304 the boundary of a macro line.
306 Examples:
307 .Bd -literal -offset indent -compact
308 Do not end sentences mid-line like this.  Instead,
309 end a sentence like this.
310 A macro would end like this:
311 \&.Xr mandoc 1 \&.
313 .Sh REQUEST SYNTAX
314 A request or macro line consists of:
316 .Bl -enum -compact
318 the control character
319 .Sq \&.
321 .Sq \(aq
322 at the beginning of the line,
324 optionally an arbitrary amount of whitespace,
326 the name of the request or the macro, which is one word of arbitrary
327 length, terminated by whitespace,
329 and zero or more arguments delimited by whitespace.
332 Thus, the following request lines are all equivalent:
333 .Bd -literal -offset indent
334 \&.ig end
335 \&.ig    end
336 \&.   ig end
338 .Sh MACRO SYNTAX
339 Macros are provided by the
340 .Xr mdoc 7
342 .Xr man 7
343 languages and can be defined by the
344 .Sx \&de
345 request.
346 When called, they follow the same syntax as requests, except that
347 macro arguments may optionally be quoted by enclosing them
348 in double quote characters
349 .Pq Sq \(dq .
350 Quoted text, even if it contains whitespace or would cause
351 a macro invocation when unquoted, is always considered literal text.
352 Inside quoted text, pairs of double quote characters
353 .Pq Sq Qq
354 resolve to single double quote characters.
356 To be recognised as the beginning of a quoted argument, the opening
357 quote character must be preceded by a space character.
358 A quoted argument extends to the next double quote character that is not
359 part of a pair, or to the end of the input line, whichever comes earlier.
360 Leaving out the terminating double quote character at the end of the line
361 is discouraged.
362 For clarity, if more arguments follow on the same input line,
363 it is recommended to follow the terminating double quote character
364 by a space character; in case the next character after the terminating
365 double quote character is anything else, it is regarded as the beginning
366 of the next, unquoted argument.
368 Both in quoted and unquoted arguments, pairs of backslashes
369 .Pq Sq \e\e
370 resolve to single backslashes.
371 In unquoted arguments, space characters can alternatively be included
372 by preceding them with a backslash
373 .Pq Sq \e\~ ,
374 but quoting is usually better for clarity.
376 Examples:
377 .Bl -tag -width Ds -offset indent -compact
378 .It Li .Fn strlen \(dqconst char *s\(dq
379 Group arguments
380 .Qq const char *s
381 into one function argument.
382 If unspecified,
383 .Qq const ,
384 .Qq char ,
386 .Qq *s
387 would be considered separate arguments.
388 .It Li .Op \(dqFl a\(dq
389 Consider
390 .Qq \&Fl a
391 as literal text instead of a flag macro.
393 .Sh REQUEST REFERENCE
395 .Xr mandoc 1
397 parser recognises the following requests.
398 Note that the
400 language defines many more requests not implemented in
401 .Xr mandoc 1 .
402 .Ss \&ad
403 Set line adjustment mode.
404 This line-scoped request is intended to have one argument to select
405 normal, left, right, or centre adjustment for subsequent text.
406 Currently, it is ignored including its arguments,
407 and the number of arguments is not checked.
408 .Ss \&am
409 Append to a macro definition.
410 The syntax of this request is the same as that of
411 .Sx \&de .
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 .Ss \&am1
417 Append to a macro definition, switching roff compatibility mode off
418 during macro execution.
419 The syntax of this request is the same as that of
420 .Sx \&de1 .
421 Since
422 .Xr mandoc 1
423 does not implement
425 compatibility mode at all, it handles this request as an alias for
426 .Sx \&am .
427 .Ss \&as
428 Append to a user-defined string.
429 The syntax of this request is the same as that of
430 .Sx \&ds .
431 If a user-defined string with the specified name does not yet exist,
432 it is set to the empty string before appending.
433 .Ss \&cc
434 Changes the control character.
435 Its syntax is as follows:
436 .Bd -literal -offset indent
437 .Pf . Cm \&cc Op Ar c
441 .Ar c
442 is not specified, the control character is reset to
443 .Sq \&. .
444 Trailing characters are ignored.
445 .Ss \&ce
446 Center some lines.
447 This line-scoped request is intended to take one integer argument,
448 specifying how many lines to center.
449 Currently, it is ignored including its arguments, and the number
450 of arguments is not checked.
451 .Ss \&de
452 Define a
454 macro.
455 Its syntax can be either
456 .Bd -literal -offset indent
457 .Pf . Cm \&de Ar name
458 .Ar macro definition
459 \&..
463 .Bd -literal -offset indent
464 .Pf . Cm \&de Ar name Ar end
465 .Ar macro definition
466 .Pf . Ar end
469 Both forms define or redefine the macro
470 .Ar name
471 to represent the
472 .Ar macro definition ,
473 which may consist of one or more input lines, including the newline
474 characters terminating each line, optionally containing calls to
476 requests,
478 macros or high-level macros like
479 .Xr man 7
481 .Xr mdoc 7
482 macros, whichever applies to the document in question.
484 Specifying a custom
485 .Ar end
486 macro works in the same way as for
487 .Sx \&ig ;
488 namely, the call to
489 .Sq Pf . Ar end
490 first ends the
491 .Ar macro definition ,
492 and after that, it is also evaluated as a
494 request or
496 macro, but not as a high-level macro.
498 The macro can be invoked later using the syntax
500 .D1 Pf . Ar name Op Ar argument Op Ar argument ...
502 Regarding argument parsing, see
503 .Sx MACRO SYNTAX
504 above.
506 The line invoking the macro will be replaced
507 in the input stream by the
508 .Ar macro definition ,
509 replacing all occurrences of
510 .No \e\e$ Ns Ar N ,
511 where
512 .Ar N
513 is a digit, by the
514 .Ar N Ns th Ar argument .
515 For example,
516 .Bd -literal -offset indent
517 \&.de ZN
518 \efI\e^\e\e$1\e^\efP\e\e$2
519 \&..
520 \&.ZN XtFree .
523 produces
525 .D1 \efI\e^XtFree\e^\efP.
527 in the input stream, and thus in the output: \fI\^XtFree\^\fP.
529 Since macros and user-defined strings share a common string table,
530 defining a macro
531 .Ar name
532 clobbers the user-defined string
533 .Ar name ,
534 and the
535 .Ar macro definition
536 can also be printed using the
537 .Sq \e*
538 string interpolation syntax described below
539 .Sx ds ,
540 but this is rarely useful because every macro definition contains at least
541 one explicit newline character.
543 In order to prevent endless recursion, both groff and
544 .Xr mandoc 1
545 limit the stack depth for expanding macros and strings
546 to a large, but finite number.
547 Do not rely on the exact value of this limit.
548 .Ss \&dei
549 Define a
551 macro, specifying the macro name indirectly.
552 The syntax of this request is the same as that of
553 .Sx \&de .
554 The request
556 .D1 Pf . Cm \&dei Ar name Op Ar end
558 has the same effect as:
560 .D1 Pf . Cm \&de No \e* Ns Bo Ar name Bc Op \e* Ns Bq Ar end
561 .Ss \&de1
562 Define a
564 macro that will be executed with
566 compatibility mode switched off during macro execution.
567 This is a GNU extension not available in traditional
569 implementations and not even in older versions of groff.
570 Since
571 .Xr mandoc 1
572 does not implement
574 compatibility mode at all, it handles this request as an alias for
575 .Sx \&de .
576 .Ss \&ds
577 Define a user-defined string.
578 Its syntax is as follows:
580 .D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
583 .Ar name
585 .Ar string
586 arguments are space-separated.
587 If the
588 .Ar string
589 begins with a double-quote character, that character will not be part
590 of the string.
591 All remaining characters on the input line form the
592 .Ar string ,
593 including whitespace and double-quote characters, even trailing ones.
596 .Ar string
597 can be interpolated into subsequent text by using
598 .No \e* Ns Bq Ar name
599 for a
600 .Ar name
601 of arbitrary length, or \e*(NN or \e*N if the length of
602 .Ar name
603 is two or one characters, respectively.
604 Interpolation can be prevented by escaping the leading backslash;
605 that is, an asterisk preceded by an even number of backslashes
606 does not trigger string interpolation.
608 Since user-defined strings and macros share a common string table,
609 defining a string
610 .Ar name
611 clobbers the macro
612 .Ar name ,
613 and the
614 .Ar name
615 used for defining a string can also be invoked as a macro,
616 in which case the following input line will be appended to the
617 .Ar string ,
618 forming a new input line passed to the
620 parser.
621 For example,
622 .Bd -literal -offset indent
623 \&.ds badidea .S
624 \&.badidea
625 H SYNOPSIS
628 invokes the
629 .Cm SH
630 macro when used in a
631 .Xr man 7
632 document.
633 Such abuse is of course strongly discouraged.
634 .Ss \&el
636 .Qq else
637 half of an if/else conditional.
638 Pops a result off the stack of conditional evaluations pushed by
639 .Sx \&ie
640 and uses it as its conditional.
641 If no stack entries are present (e.g., due to no prior
642 .Sx \&ie
643 calls)
644 then false is assumed.
645 The syntax of this request is similar to
646 .Sx \&if
647 except that the conditional is missing.
648 .Ss \&EN
649 End an equation block.
651 .Sx \&EQ .
652 .Ss \&EQ
653 Begin an equation block.
655 .Xr eqn 7
656 for a description of the equation language.
657 .Ss \&fam
658 Change the font family.
659 This line-scoped request is intended to have one argument specifying
660 the font family to be selected.
661 It is a groff extension, and currently, it is ignored including its
662 arguments, and the number of arguments is not checked.
663 .Ss \&ft
664 Change the font.
665 Its syntax is as follows:
667 .D1 Pf . Cm \&ft Op Ar font
669 The following
670 .Ar font
671 arguments are supported:
672 .Bl -tag -width 4n -offset indent
673 .It Cm B , BI , 3 , 4
674 switches to
675 .Sy bold
676 font
677 .It Cm I , 2
678 switches to
679 .Em underlined
680 font
681 .It Cm R , CW , 1
682 switches to normal font
683 .It Cm P No "or no argument"
684 switches back to the previous font
687 This request takes effect only locally, may be overridden by macros
688 and escape sequences, and is only supported in
689 .Xr man 7
690 for now.
691 .Ss \&hw
692 Specify hyphenation points in words.
693 This line-scoped request is currently ignored.
694 .Ss \&hy
695 Set automatic hyphenation mode.
696 This line-scoped request is currently ignored.
697 .Ss \&ie
699 .Qq if
700 half of an if/else conditional.
701 The result of the conditional is pushed into a stack used by subsequent
702 invocations of
703 .Sx \&el ,
704 which may be separated by any intervening input (or not exist at all).
705 Its syntax is equivalent to
706 .Sx \&if .
707 .Ss \&if
708 Begins a conditional.
709 This request has the following syntax:
710 .Bd -literal -offset indent
711 \&.if COND BODY
713 .Bd -literal -offset indent
714 \&.if COND \e{BODY
715 BODY...\e}
717 .Bd -literal -offset indent
718 \&.if COND \e{\e
719 BODY...
720 \&.\e}
723 COND is a conditional statement.
724 Currently,
725 .Xr mandoc 1
726 supports the following subset of roff conditionals:
727 .Bl -bullet
730 .Sq \&!
731 is prefixed to COND, the condition is logically inverted.
733 If the first character of COND is
734 .Sq n
735 .Pq nroff mode
737 .Sq o
738 .Pq odd page ,
739 COND evaluates to true.
741 If the first character of COND is
742 .Sq c
743 .Pq character available ,
744 .Sq d
745 .Pq string defined ,
746 .Sq e
747 .Pq even page ,
748 .Sq r
749 .Pq register accessed ,
751 .Sq t
752 .Pq troff mode ,
753 COND evaluates to false.
755 If COND starts with a parenthesis or with an optionally signed
756 integer number, it is evaluated according to the rules of
757 .Sx Numerical expressions
758 explained below.
759 It evaluates to true if the the result is positive,
760 or to false if the result is zero or negative.
762 Otherwise, the first character of COND is regarded as a delimiter
763 and COND evaluates to true if the string extending from its first
764 to its second occurrence is equal to the string extending from its
765 second to its third occurrence.
767 If COND cannot be parsed, it evaluates to false.
770 If a conditional is false, its children are not processed, but are
771 syntactically interpreted to preserve the integrity of the input
772 document.
773 Thus,
775 .D1 \&.if t .ig
777 will discard the
778 .Sq \&.ig ,
779 which may lead to interesting results, but
781 .D1 \&.if t .if t \e{\e
783 will continue to syntactically interpret to the block close of the final
784 conditional.
785 Sub-conditionals, in this case, obviously inherit the truth value of
786 the parent.
788 If the BODY section is begun by an escaped brace
789 .Sq \e{ ,
790 scope continues until the end of the input line containing the
791 matching closing-brace escape sequence
792 .Sq \e} .
793 If the BODY is not enclosed in braces, scope continues until
794 the end of the line.
795 If the COND is followed by a BODY on the same line, whether after a
796 brace or not, then requests and macros
797 .Em must
798 begin with a control character.
799 It is generally more intuitive, in this case, to write
800 .Bd -literal -offset indent
801 \&.if COND \e{\e
802 \&.foo
804 \&.\e}
807 than having the request or macro follow as
809 .D1 \&.if COND \e{ .foo
811 The scope of a conditional is always parsed, but only executed if the
812 conditional evaluates to true.
814 Note that the
815 .Sq \e}
816 is converted into a zero-width escape sequence if not passed as a
817 standalone macro
818 .Sq \&.\e} .
819 For example,
821 .D1 \&.Fl a \e} b
823 will result in
824 .Sq \e}
825 being considered an argument of the
826 .Sq \&Fl
827 macro.
828 .Ss \&ig
829 Ignore input.
830 Its syntax can be either
831 .Bd -literal -offset indent
832 .Pf . Cm \&ig
833 .Ar ignored text
834 \&..
838 .Bd -literal -offset indent
839 .Pf . Cm \&ig Ar end
840 .Ar ignored text
841 .Pf . Ar end
844 In the first case, input is ignored until a
845 .Sq \&..
846 request is encountered on its own line.
847 In the second case, input is ignored until the specified
848 .Sq Pf . Ar end
849 macro is encountered.
850 Do not use the escape character
851 .Sq \e
852 anywhere in the definition of
853 .Ar end ;
854 it would cause very strange behaviour.
856 When the
857 .Ar end
858 macro is a roff request or a roff macro, like in
860 .D1 \&.ig if
862 the subsequent invocation of
863 .Sx \&if
864 will first terminate the
865 .Ar ignored text ,
866 then be invoked as usual.
867 Otherwise, it only terminates the
868 .Ar ignored text ,
869 and arguments following it or the
870 .Sq \&..
871 request are discarded.
872 .Ss \&ll
873 Change the output line length.
874 Its syntax is as follows:
876 .D1 Pf . Cm \&ll Op Oo +|- Oc Ns Ar width
878 If the
879 .Ar width
880 argument is omitted, the line length is reset to its previous value.
881 The default setting for terminal output is 78n.
882 If a sign is given, the line length is added to or subtracted from;
883 otherwise, it is set to the provided value.
884 Using this request in new manuals is discouraged for several reasons,
885 among others because it overrides the
886 .Xr mandoc 1
887 .Fl O Cm width
888 command line option.
889 .Ss \&ne
890 Declare the need for the specified minimum vertical space
891 before the next trap or the bottom of the page.
892 This line-scoped request is currently ignored.
893 .Ss \&nh
894 Turn off automatic hyphenation mode.
895 This line-scoped request is currently ignored.
896 .Ss \&nr
897 Define or change a register.
898 A register is an arbitrary string value that defines some sort of state,
899 which influences parsing and/or formatting.
900 Its syntax is as follows:
902 .D1 Pf \. Cm \&nr Ar name Oo +|- Oc Ns Ar expression
904 For the syntax of
905 .Ar expression ,
907 .Sx Numerical expressions
908 below.
909 If it is prefixed by a sign, the register will be
910 incremented or decremented instead of assigned to.
912 The following register
913 .Ar name
914 is handled specially:
915 .Bl -tag -width Ds
916 .It Cm nS
917 If set to a positive integer value, certain
918 .Xr mdoc 7
919 macros will behave in the same way as in the
920 .Em SYNOPSIS
921 section.
922 If set to 0, these macros will behave in the same way as outside the
923 .Em SYNOPSIS
924 section, even when called within the
925 .Em SYNOPSIS
926 section itself.
927 Note that starting a new
928 .Xr mdoc 7
929 section with the
930 .Cm \&Sh
931 macro will reset this register.
933 .Ss \&ns
934 Turn on no-space mode.
935 This line-scoped request is intended to take no arguments.
936 Currently, it is ignored including its arguments,
937 and the number of arguments is not checked.
938 .Ss \&ps
939 Change point size.
940 This line-scoped request is intended to take one numerical argument.
941 Currently, it is ignored including its arguments,
942 and the number of arguments is not checked.
943 .Ss \&rm
944 Remove a request, macro or string.
945 Its syntax is as follows:
947 .D1 Pf \. Cm \&rm Ar name
948 .Ss \&rr
949 Remove a register.
950 Its syntax is as follows:
952 .D1 Pf \. Cm \&rr Ar name
953 .Ss \&so
954 Include a source file.
955 Its syntax is as follows:
957 .D1 Pf \. Cm \&so Ar file
960 .Ar file
961 will be read and its contents processed as input in place of the
962 .Sq \&.so
963 request line.
964 To avoid inadvertent inclusion of unrelated files,
965 .Xr mandoc 1
966 only accepts relative paths not containing the strings
967 .Qq ../
969 .Qq /.. .
971 This request requires
972 .Xr man 1
973 to change to the right directory before calling
974 .Xr mandoc 1 ,
975 per convention to the root of the manual tree.
976 Typical usage looks like:
978 .Dl \&.so man3/Xcursor.3
980 As the whole concept is rather fragile, the use of
981 .Sx \&so
982 is discouraged.
984 .Xr ln 1
985 instead.
986 .Ss \&ta
987 Set tab stops.
988 This line-scoped request can take an arbitrary number of arguments.
989 Currently, it is ignored including its arguments.
990 .Ss \&tr
991 Output character translation.
992 Its syntax is as follows:
994 .D1 Pf \. Cm \&tr Ar [ab]+
996 Pairs of
997 .Ar ab
998 characters are replaced
999 .Ar ( a
1001 .Ar b ) .
1002 Replacement (or origin) characters may also be character escapes; thus,
1004 .Dl tr \e(xx\e(yy
1006 replaces all invocations of \e(xx with \e(yy.
1007 .Ss \&T&
1008 Re-start a table layout, retaining the options of the prior table
1009 invocation.
1011 .Sx \&TS .
1012 .Ss \&TE
1013 End a table context.
1015 .Sx \&TS .
1016 .Ss \&TS
1017 Begin a table, which formats input in aligned rows and columns.
1019 .Xr tbl 7
1020 for a description of the tbl language.
1021 .Ss Numerical expressions
1023 .Sx \&nr ,
1024 .Sx \&if ,
1026 .Sx \&ie
1027 requests accept integer numerical expressions as arguments.
1028 These are always evaluated using the C
1029 .Vt int
1030 type; integer overflow works the same way as in the C language.
1031 Numbers consist of an arbitrary number of digits
1032 .Sq 0
1034 .Sq 9
1035 prefixed by an optional sign
1036 .Sq +
1038 .Sq - .
1040 The following binary operators are implemented.
1041 Unless otherwise stated, they behave as in the C language:
1043 .Bl -tag -width 2n -compact
1044 .It Ic +
1045 addition
1046 .It Ic -
1047 subtraction
1048 .It Ic *
1049 multiplication
1050 .It Ic /
1051 division
1052 .It Ic %
1053 remainder of division
1054 .It Ic <
1055 less than
1056 .It Ic >
1057 greater than
1058 .It Ic ==
1059 equal to
1060 .It Ic =
1061 equal to, same effect as
1062 .Ic ==
1063 (this differs from C)
1064 .It Ic <=
1065 less than or equal to
1066 .It Ic >=
1067 greater than or equal to
1068 .It Ic <>
1069 not equal to (corresponds to C
1070 .Ic != ;
1071 this one is of limited portability, it is supported by Heirloom roff,
1072 but not by groff)
1073 .It Ic &
1074 logical and (corresponds to C
1075 .Ic && )
1076 .It Ic \&:
1077 logical or (corresponds to C
1078 .Ic \&|| )
1079 .It Ic <?
1080 minimum (not available in C)
1081 .It Ic >?
1082 maximum (not available in C)
1085 There is no concept of precendence; evaluation proceeds from left to right,
1086 except when subexpressions are enclosed in parantheses.
1087 Inside parentheses, whitespace is ignored.
1088 .Sh ESCAPE SEQUENCE REFERENCE
1090 .Xr mandoc 1
1092 parser recognises the following escape sequences.
1093 Note that the
1095 language defines more escape sequences not implemented in
1096 .Xr mandoc 1 .
1098 .Xr mdoc 7
1100 .Xr man 7
1101 documents, using escape sequences is discouraged except for those
1102 described in the
1103 .Sx LANGUAGE SYNTAX
1104 section above.
1106 A backslash followed by any character not listed here
1107 simply prints that character itself.
1108 .Ss \e<newline>
1109 A backslash at the end of an input line can be used to continue the
1110 logical input line on the next physical input line, joining the text
1111 on both lines together as if it were on a single input line.
1112 .Ss \e<space>
1113 The escape sequence backslash-space
1114 .Pq Sq \e\ \&
1115 is an unpaddable space-sized non-breaking space character; see
1116 .Sx Whitespace .
1117 .Ss \e\(dq
1118 The rest of the input line is treated as
1119 .Sx Comments .
1120 .Ss \e%
1121 Hyphenation allowed at this point of the word; ignored by
1122 .Xr mandoc 1 .
1123 .Ss \e&
1124 Non-printing zero-width character; see
1125 .Sx Whitespace .
1126 .Ss \e\(aq
1127 Acute accent special character; use
1128 .Sq \e(aa
1129 instead.
1130 .Ss \e( Ns Ar cc
1131 .Sx Special Characters
1132 with two-letter names, see
1133 .Xr mandoc_char 7 .
1134 .Ss \e*[ Ns Ar name ]
1135 Interpolate the string with the
1136 .Ar name ;
1138 .Sx Predefined Strings
1140 .Sx ds .
1141 For short names, there are variants
1142 .No \e* Ns Ar c
1144 .No \e*( Ns Ar cc .
1145 .Ss \e-
1146 Special character
1147 .Dq mathematical minus sign .
1148 .Ss \e[ Ns Ar name ]
1149 .Sx Special Characters
1150 with names of arbitrary length, see
1151 .Xr mandoc_char 7 .
1152 .Ss \e^
1153 One-twelfth em half-narrow space character, effectively zero-width in
1154 .Xr mandoc 1 .
1155 .Ss \e`
1156 Grave accent special character; use
1157 .Sq \e(ga
1158 instead.
1159 .Ss \e{
1160 Begin conditional input; see
1161 .Sx if .
1162 .Ss \e\(ba
1163 One-sixth em narrow space character, effectively zero-width in
1164 .Xr mandoc 1 .
1165 .Ss \e}
1166 End conditional input; see
1167 .Sx if .
1168 .Ss \e~
1169 Paddable non-breaking space character.
1170 .Ss \e0
1171 Digit width space character.
1172 .Ss \eA\(aq Ns Ar string Ns \(aq
1173 Anchor definition; ignored by
1174 .Xr mandoc 1 .
1175 .Ss \eB\(aq Ns Ar string Ns \(aq
1176 Interpolate
1177 .Sq 1
1179 .Ar string
1180 conforms to the syntax of
1181 .Sx Numerical expressions
1182 explained above and
1183 .Sq 0
1184 otherwise.
1185 .Ss \eb\(aq Ns Ar string Ns \(aq
1186 Bracket building function; ignored by
1187 .Xr mandoc 1 .
1188 .Ss \eC\(aq Ns Ar name Ns \(aq
1189 .Sx Special Characters
1190 with names of arbitrary length.
1191 .Ss \ec
1192 Interrupt text processing to insert requests or macros; ignored by
1193 .Xr mandoc 1 .
1194 .Ss \eD\(aq Ns Ar string Ns \(aq
1195 Draw graphics function; ignored by
1196 .Xr mandoc 1 .
1197 .Ss \ed
1198 Move down by half a line; ignored by
1199 .Xr mandoc 1 .
1200 .Ss \ee
1201 Backslash special character.
1202 .Ss \eF[ Ns Ar name ]
1203 Switch font family (groff extension); ignored by
1204 .Xr mandoc 1 .
1205 For short names, there are variants
1206 .No \eF Ns Ar c
1208 .No \eF( Ns Ar cc .
1209 .Ss \ef[ Ns Ar name ]
1210 Switch to the font
1211 .Ar name ,
1213 .Sx Text Decoration .
1214 For short names, there are variants
1215 .No \ef Ns Ar c
1217 .No \ef( Ns Ar cc .
1218 .Ss \eg[ Ns Ar name ]
1219 Interpolate the format of a number register; ignored by
1220 .Xr mandoc 1 .
1221 For short names, there are variants
1222 .No \eg Ns Ar c
1224 .No \eg( Ns Ar cc .
1225 .Ss \eH\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
1226 Set the height of the current font; ignored by
1227 .Xr mandoc 1 .
1228 .Ss \eh\(aq Ns Ar number Ns \(aq
1229 Horizontal motion; ignored by
1230 .Xr mandoc 1 .
1231 .Ss \ek[ Ns Ar name ]
1232 Mark horizontal input place in register; ignored by
1233 .Xr mandoc 1 .
1234 For short names, there are variants
1235 .No \ek Ns Ar c
1237 .No \ek( Ns Ar cc .
1238 .Ss \eL\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq
1239 Vertical line drawing function; ignored by
1240 .Xr mandoc 1 .
1241 .Ss \el\(aq Ns Ar number Ns Oo Ar c Oc Ns \(aq
1242 Horizontal line drawing function; ignored by
1243 .Xr mandoc 1 .
1244 .Ss \eM[ Ns Ar name ]
1245 Set fill (background) color (groff extension); ignored by
1246 .Xr mandoc 1 .
1247 For short names, there are variants
1248 .No \eM Ns Ar c
1250 .No \eM( Ns Ar cc .
1251 .Ss \em[ Ns Ar name ]
1252 Set glyph drawing color (groff extension); ignored by
1253 .Xr mandoc 1 .
1254 For short names, there are variants
1255 .No \em Ns Ar c
1257 .No \em( Ns Ar cc .
1258 .Ss \eN\(aq Ns Ar number Ns \(aq
1259 Character
1260 .Ar number
1261 on the current font.
1262 .Ss \en[ Ns Ar name ]
1263 Interpolate the number register
1264 .Ar name .
1265 For short names, there are variants
1266 .No \en Ns Ar c
1268 .No \en( Ns Ar cc .
1269 .Ss \eo\(aq Ns Ar string Ns \(aq
1270 Overstrike
1271 .Ar string ;
1272 ignored by
1273 .Xr mandoc 1 .
1274 .Ss \eR\(aq Ns Ar name Oo +|- Oc Ns Ar number Ns \(aq
1275 Set number register; ignored by
1276 .Xr mandoc 1 .
1277 .Ss \eS\(aq Ns Ar number Ns \(aq
1278 Slant output; ignored by
1279 .Xr mandoc 1 .
1280 .Ss \es\(aq Ns Oo +|- Oc Ns Ar number Ns \(aq
1281 Change point size; ignored by
1282 .Xr mandoc 1 .
1283 Alternative forms
1284 .No \es Ns Oo +|- Oc Ns Ar n ,
1285 .No \es Ns Oo +|- Oc Ns \(aq Ns Ar number Ns \(aq ,
1286 .No \es Ns [ Oo +|- Oc Ns Ar number ] ,
1288 .No \es Ns Oo +|- Oc Ns [ Ar number Ns ]
1289 are also parsed and ignored.
1290 .Ss \et
1291 Horizontal tab; ignored by
1292 .Xr mandoc 1 .
1293 .Ss \eu
1294 Move up by half a line; ignored by
1295 .Xr mandoc 1 .
1296 .Ss \eV[ Ns Ar name ]
1297 Interpolate an environment variable; ignored by
1298 .Xr mandoc 1 .
1299 For short names, there are variants
1300 .No \eV Ns Ar c
1302 .No \eV( Ns Ar cc .
1303 .Ss \ev\(aq Ns Ar number Ns \(aq
1304 Vertical motion; ignored by
1305 .Xr mandoc 1 .
1306 .Ss \ew\(aq Ns Ar string Ns \(aq
1307 Interpolate the width of the
1308 .Ar string .
1310 .Xr mandoc 1
1311 implementation assumes that after expansion of user-defined strings, the
1312 .Ar string
1313 only contains normal characters, no escape sequences, and that each
1314 character has a width of 24 basic units.
1315 .Ss \eX\(aq Ns Ar string Ns \(aq
1316 Output
1317 .Ar string
1318 as device control function; ignored in nroff mode and by
1319 .Xr mandoc 1 .
1320 .Ss \ex\(aq Ns Ar number Ns \(aq
1321 Extra line space function; ignored by
1322 .Xr mandoc 1 .
1323 .Ss \eY[ Ns Ar name ]
1324 Output a string as a device control function; ignored in nroff mode and by
1325 .Xr mandoc 1 .
1326 For short names, there are variants
1327 .No \eY Ns Ar c
1329 .No \eY( Ns Ar cc .
1330 .Ss \eZ\(aq Ns Ar string Ns \(aq
1331 Print
1332 .Ar string
1333 with zero width and height; ignored by
1334 .Xr mandoc 1 .
1335 .Ss \ez
1336 Output the next character without advancing the cursor position;
1337 approximated in
1338 .Xr mandoc 1
1339 by simply skipping the next character.
1340 .Sh COMPATIBILITY
1341 This section documents compatibility between mandoc and other
1343 implementations, at this time limited to GNU troff
1344 .Pq Qq groff .
1345 The term
1346 .Qq historic groff
1347 refers to groff version 1.15.
1349 .Bl -dash -compact
1351 In mandoc, the
1352 .Sx \&EQ ,
1353 .Sx \&TE ,
1354 .Sx \&TS ,
1356 .Sx \&T& ,
1357 macros are considered regular macros.
1358 In all other
1360 implementations, these are special macros that must be specified without
1361 spacing between the control character (which must be a period) and the
1362 macro name.
1365 .Cm nS
1366 register is only compatible with OpenBSD's groff-1.15.
1368 Historic groff did not accept white-space before a custom
1369 .Ar end
1370 macro for the
1371 .Sx \&ig
1372 request.
1375 .Sx \&if
1376 and family would print funny white-spaces with historic groff when
1377 using the next-line syntax.
1379 .Sh SEE ALSO
1380 .Xr mandoc 1 ,
1381 .Xr eqn 7 ,
1382 .Xr man 7 ,
1383 .Xr mandoc_char 7 ,
1384 .Xr mdoc 7 ,
1385 .Xr tbl 7
1387 .%A Joseph F. Ossanna
1388 .%A Brian W. Kernighan
1389 .%I AT&T Bell Laboratories
1390 .%T Troff User's Manual
1391 .%R Computing Science Technical Report
1392 .%N 54
1393 .%C Murray Hill, New Jersey
1394 .%D 1976 and 1992
1395 .%U http://www.kohala.com/start/troff/cstr54.ps
1398 .%A Joseph F. Ossanna
1399 .%A Brian W. Kernighan
1400 .%A Gunnar Ritter
1401 .%T Heirloom Documentation Tools Nroff/Troff User's Manual
1402 .%D September 17, 2007
1403 .%U http://heirloom.sourceforge.net/doctools/troff.pdf
1405 .Sh HISTORY
1406 The RUNOFF typesetting system, whose input forms the basis for
1407 .Nm ,
1408 was written in MAD and FAP for the CTSS operating system by Jerome E.
1409 Saltzer in 1964.
1410 Doug McIlroy rewrote it in BCPL in 1969, renaming it
1411 .Nm .
1412 Dennis M. Ritchie rewrote McIlroy's
1414 in PDP-11 assembly for
1415 .At v1 ,
1416 Joseph F. Ossanna improved roff and renamed it nroff
1418 .At v2 ,
1419 then ported nroff to C as troff, which Brian W. Kernighan released with
1420 .At v7 .
1421 In 1989, James Clarke re-implemented troff in C++, naming it groff.
1422 .Sh AUTHORS
1423 .An -nosplit
1424 This
1426 reference was written by
1427 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1429 .An Ingo Schwarze Aq Mt schwarze@openbsd.org .