2 .\" Permission to use, copy, modify, and distribute this software for any
3 .\" purpose with or without fee is hereby granted, provided that the above
4 .\" copyright notice and this permission notice appear in all copies.
6 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
7 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
8 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
9 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
10 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
11 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
12 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 .\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
16 .\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>
17 .\" Copyright 2012 Nexenta Systems, Inc. All rights reserved.
18 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
25 .Nd roff language reference for mandoc
29 language is a general purpose text formatting language.
30 Since traditional implementations of the
34 manual formatting languages are based on it,
35 many real-world manuals use small numbers of
37 requests intermixed with their
42 To properly format such manuals, the
44 utility supports a tiny subset of
47 Only these requests supported by
49 are documented in the present manual,
50 together with the basic language syntax shared by
61 Input lines beginning with the control character
63 are parsed for requests and macros.
69 Requests change the processing state and manipulate the formatting;
70 some macros also define the document structure and produce formatted
74 is accepted as an alternative control character,
80 Lines not beginning with control characters are called
82 They provide free-form text to be printed; the formatting of the text
83 depends on the respective processing context.
86 documents may contain only graphable 7-bit ASCII characters, the space
87 character, and, in certain circumstances, the tab character.
88 The back-space character
90 indicates the start of an escape sequence for
92 .Sx Special Characters ,
93 .Sx Predefined Strings ,
95 user-defined strings defined using the
99 Text following an escaped double-quote
101 whether in a request, macro, or text line, is ignored to the end of the line.
102 A request line beginning with a control character and comment escape
105 Furthermore, request lines with only a control character and optional
106 trailing whitespace are stripped from input.
109 .Bd -literal -offset indent -compact
110 \&.\e\(dq This is a comment line.
111 \&.\e\(dq The next line is ignored:
113 \&.Sh EXAMPLES \e\(dq This is a comment, too.
114 \&example text \e\(dq And so is this.
116 .Ss Special Characters
117 Special characters are used to encode special glyphs and are rendered
118 differently across output media.
119 They may occur in request, macro, and text lines.
120 Sequences begin with the escape character
122 followed by either an open-parenthesis
124 for two-character sequences; an open-bracket
126 for n-character sequences (terminated at a close-bracket
128 or a single one character sequence.
131 .Bl -tag -width Ds -offset indent -compact
133 Two-letter em dash escape.
135 One-letter backslash escape.
142 Terms may be text-decorated using the
144 escape followed by an indicator: B (bold), I (italic), R (regular), or P
145 (revert to previous mode).
146 A numerical representation 3, 2, or 1 (bold, italic, and regular,
147 respectively) may be used instead.
148 The indicator or numerical representative may be preceded by C
149 (constant-width), which is ignored.
152 .Bl -tag -width Ds -offset indent -compact
154 Write in bold, then switch to regular font mode.
155 .It Li \efIitalic\efP
156 Write in italic, then return to previous font mode.
163 which encourages semantic annotation.
164 .Ss Predefined Strings
165 Predefined strings, like
166 .Sx Special Characters ,
167 mark special output glyphs.
168 Predefined strings are escaped with the slash-asterisk,
178 .Bl -tag -width Ds -offset indent -compact
180 Two-letter ampersand predefined string.
182 One-letter double-quote predefined string.
185 Predefined strings are not recommended for use,
186 as they differ across implementations.
191 Manuals using these predefined strings are almost certainly not portable.
193 Whitespace consists of the space character.
194 In text lines, whitespace is preserved within a line.
195 In request and macro lines, whitespace delimits arguments and is discarded.
197 Unescaped trailing spaces are stripped from text line input unless in a
199 In general, trailing whitespace on any input line is discouraged for
200 reasons of portability.
201 In the rare case that a blank character is needed at the end of an
202 input line, it may be forced by
205 Literal space characters can be produced in the output
206 using escape sequences.
207 In macro lines, they can also be included in arguments using quotation; see
211 Blank text lines, which may include whitespace, are only permitted
212 within literal contexts.
213 If the first character of a text line is a space, that line is printed
214 with a leading newline.
216 Many requests and macros support scaled widths for their arguments.
217 The syntax for a scaled width is
218 .Sq Li [+-]?[0-9]*.[0-9]*[:unit:] ,
219 where a decimal must be preceded or followed by at least one digit.
220 Negative numbers, while accepted, are truncated to zero.
222 The following scaling units are accepted:
224 .Bl -tag -width Ds -offset indent -compact
237 default vertical span
249 default horizontal span
254 Using anything other than
260 is necessarily non-portable across output media.
264 If a scaling unit is not provided, the numerical value is interpreted
265 under the default rules of
267 for vertical spaces and
272 .Bl -tag -width ".Bl -tag -width 2i" -offset indent -compact
273 .It Li \&.Bl -tag -width 2i
274 two-inch tagged list indentation in
277 two-inch tagged list indentation in
283 Each sentence should terminate at the end of an input line.
284 By doing this, a formatter will be able to apply the proper amount of
285 spacing after the end of sentence (unescaped) period, exclamation mark,
286 or question mark followed by zero or more non-sentence closing
295 The proper spacing is also intelligently preserved if a sentence ends at
296 the boundary of a macro line.
299 .Bd -literal -offset indent -compact
300 Do not end sentences mid-line like this. Instead,
301 end a sentence like this.
302 A macro would end like this:
306 A request or macro line consists of:
310 the control character
314 at the beginning of the line,
316 optionally an arbitrary amount of whitespace,
318 the name of the request or the macro, which is one word of arbitrary
319 length, terminated by whitespace,
321 and zero or more arguments delimited by whitespace.
324 Thus, the following request lines are all equivalent:
325 .Bd -literal -offset indent
331 Macros are provided by the
335 languages and can be defined by the
338 When called, they follow the same syntax as requests, except that
339 macro arguments may optionally be quoted by enclosing them
340 in double quote characters
342 Quoted text, even if it contains whitespace or would cause
343 a macro invocation when unquoted, is always considered literal text.
344 Inside quoted text, pairs of double quote characters
346 resolve to single double quote characters.
348 To be recognised as the beginning of a quoted argument, the opening
349 quote character must be preceded by a space character.
350 A quoted argument extends to the next double quote character that is not
351 part of a pair, or to the end of the input line, whichever comes earlier.
352 Leaving out the terminating double quote character at the end of the line
354 For clarity, if more arguments follow on the same input line,
355 it is recommended to follow the terminating double quote character
356 by a space character; in case the next character after the terminating
357 double quote character is anything else, it is regarded as the beginning
358 of the next, unquoted argument.
360 Both in quoted and unquoted arguments, pairs of backslashes
362 resolve to single backslashes.
363 In unquoted arguments, space characters can alternatively be included
364 by preceding them with a backslash
366 but quoting is usually better for clarity.
369 .Bl -tag -width Ds -offset indent -compact
370 .It Li .Fn strlen \(dqconst char *s\(dq
373 into one function argument.
379 would be considered separate arguments.
380 .It Li .Op \(dqFl a\(dq
383 as literal text instead of a flag macro.
385 .Sh REQUEST REFERENCE
389 parser recognises the following requests.
392 language defines many more requests not implemented in
395 Set line adjustment mode.
396 This line-scoped request is intended to have one argument to select
397 normal, left, right, or centre adjustment for subsequent text.
398 Currently, it is ignored including its arguments,
399 and the number of arguments is not checked.
401 Append to a macro definition.
402 The syntax of this request is the same as that of
404 It is currently ignored by
408 Append to a macro definition, specifying the macro name indirectly.
409 The syntax of this request is the same as that of
411 It is currently ignored by
415 Append to a macro definition, switching roff compatibility mode off
416 during macro execution.
417 The syntax of this request is the same as that of
419 It is currently ignored by
426 Its syntax can be either
427 .Bd -literal -offset indent
428 .Pf . Cm \&de Ar name
434 .Bd -literal -offset indent
435 .Pf . Cm \&de Ar name Ar end
440 Both forms define or redefine the macro
443 .Ar macro definition ,
444 which may consist of one or more input lines, including the newline
445 characters terminating each line, optionally containing calls to
449 macros or high-level macros like
453 macros, whichever applies to the document in question.
457 macro works in the same way as for
462 .Ar macro definition ,
463 and after that, it is also evaluated as a
467 macro, but not as a high-level macro.
469 The macro can be invoked later using the syntax
471 .D1 Pf . Ar name Op Ar argument Op Ar argument ...
473 Regarding argument parsing, see
477 The line invoking the macro will be replaced
478 in the input stream by the
479 .Ar macro definition ,
480 replacing all occurrences of
485 .Ar N Ns th Ar argument .
487 .Bd -literal -offset indent
489 \efI\e^\e\e$1\e^\efP\e\e$2
496 .D1 \efI\e^XtFree\e^\efP.
498 in the input stream, and thus in the output: \fI\^XtFree\^\fP.
500 Since macros and user-defined strings share a common string table,
503 clobbers the user-defined string
507 can also be printed using the
509 string interpolation syntax described below
511 but this is rarely useful because every macro definition contains at least
512 one explicit newline character.
514 In order to prevent endless recursion, both groff and
516 limit the stack depth for expanding macros and strings
517 to a large, but finite number.
518 Do not rely on the exact value of this limit.
522 macro, specifying the macro name indirectly.
523 The syntax of this request is the same as that of
525 It is currently ignored by
531 macro that will be executed with
533 compatibility mode switched off during macro execution.
534 This is a GNU extension not available in traditional
536 implementations and not even in older versions of groff.
541 compatibility mode at all, it handles this request as an alias for
544 Define a user-defined string.
545 Its syntax is as follows:
547 .D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
553 arguments are space-separated.
556 begins with a double-quote character, that character will not be part
558 All remaining characters on the input line form the
560 including whitespace and double-quote characters, even trailing ones.
564 can be interpolated into subsequent text by using
565 .No \e* Ns Bq Ar name
568 of arbitrary length, or \e*(NN or \e*N if the length of
570 is two or one characters, respectively.
571 Interpolation can be prevented by escaping the leading backslash;
572 that is, an asterisk preceded by an even number of backslashes
573 does not trigger string interpolation.
575 Since user-defined strings and macros share a common string table,
582 used for defining a string can also be invoked as a macro,
583 in which case the following input line will be appended to the
585 forming a new input line passed to the
589 .Bd -literal -offset indent
600 Such abuse is of course strongly discouraged.
604 half of an if/else conditional.
605 Pops a result off the stack of conditional evaluations pushed by
607 and uses it as its conditional.
608 If no stack entries are present (e.g., due to no prior
611 then false is assumed.
612 The syntax of this request is similar to
614 except that the conditional is missing.
616 End an equation block.
620 Begin an equation block.
623 for a description of the equation language.
625 Set automatic hyphenation mode.
626 This line-scoped request is currently ignored.
630 half of an if/else conditional.
631 The result of the conditional is pushed into a stack used by subsequent
634 which may be separated by any intervening input (or not exist at all).
635 Its syntax is equivalent to
638 Begins a conditional.
639 Right now, the conditional evaluates to true
640 if and only if it starts with the letter
642 indicating processing in nroff style as opposed to troff style.
643 If a conditional is false, its children are not processed, but are
644 syntactically interpreted to preserve the integrity of the input
652 which may lead to interesting results, but
654 .D1 \&.if t .if t \e{\e
656 will continue to syntactically interpret to the block close of the final
658 Sub-conditionals, in this case, obviously inherit the truth value of
660 This request has the following syntax:
661 .Bd -literal -offset indent
666 .Bd -literal -offset indent
670 .Bd -literal -offset indent
675 .Bd -literal -offset indent
680 COND is a conditional statement.
681 roff allows for complicated conditionals; mandoc is much simpler.
682 At this time, mandoc supports only
691 All other invocations are read up to the next end of line or space and
694 If the BODY section is begun by an escaped brace
696 scope continues until a closing-brace escape sequence
698 If the BODY is not enclosed in braces, scope continues until
700 If the COND is followed by a BODY on the same line, whether after a
701 brace or not, then requests and macros
703 begin with a control character.
704 It is generally more intuitive, in this case, to write
705 .Bd -literal -offset indent
712 than having the request or macro follow as
714 .D1 \&.if COND \e{ .foo
716 The scope of a conditional is always parsed, but only executed if the
717 conditional evaluates to true.
721 is converted into a zero-width escape sequence if not passed as a
730 being considered an argument of the
735 Its syntax can be either
736 .Bd -literal -offset indent
743 .Bd -literal -offset indent
749 In the first case, input is ignored until a
751 request is encountered on its own line.
752 In the second case, input is ignored until the specified
754 macro is encountered.
755 Do not use the escape character
757 anywhere in the definition of
759 it would cause very strange behaviour.
763 macro is a roff request or a roff macro, like in
767 the subsequent invocation of
769 will first terminate the
771 then be invoked as usual.
772 Otherwise, it only terminates the
774 and arguments following it or the
776 request are discarded.
778 Declare the need for the specified minimum vertical space
779 before the next trap or the bottom of the page.
780 This line-scoped request is currently ignored.
782 Turn off automatic hyphenation mode.
783 This line-scoped request is currently ignored.
785 Remove a request, macro or string.
786 This request is intended to have one argument,
787 the name of the request, macro or string to be undefined.
788 Currently, it is ignored including its arguments,
789 and the number of arguments is not checked.
792 A register is an arbitrary string value that defines some sort of state,
793 which influences parsing and/or formatting.
794 Its syntax is as follows:
796 .D1 Pf \. Cm \&nr Ar name Ar value
800 may, at the moment, only be an integer.
801 So far, only the following register
806 If set to a positive integer value, certain
808 macros will behave in the same way as in the
811 If set to 0, these macros will behave in the same way as outside the
813 section, even when called within the
816 Note that starting a new
820 macro will reset this register.
823 Turn on no-space mode.
824 This line-scoped request is intended to take no arguments.
825 Currently, it is ignored including its arguments,
826 and the number of arguments is not checked.
829 This line-scoped request is intended to take one numerical argument.
830 Currently, it is ignored including its arguments,
831 and the number of arguments is not checked.
833 Include a source file.
834 Its syntax is as follows:
836 .D1 Pf \. Cm \&so Ar file
840 will be read and its contents processed as input in place of the
843 To avoid inadvertent inclusion of unrelated files,
845 only accepts relative paths not containing the strings
850 This request requires
852 to change to the right directory before calling
854 per convention to the root of the manual tree.
855 Typical usage looks like:
857 .Dl \&.so man3/Xcursor.3
859 As the whole concept is rather fragile, the use of
867 This line-scoped request can take an arbitrary number of arguments.
868 Currently, it is ignored including its arguments.
870 Output character translation.
871 Its syntax is as follows:
873 .D1 Pf \. Cm \&tr Ar [ab]+
877 characters are replaced
881 Replacement (or origin) characters may also be character escapes; thus,
885 replaces all invocations of \e(xx with \e(yy.
887 Re-start a table layout, retaining the options of the prior table
896 Begin a table, which formats input in aligned rows and columns.
899 for a description of the tbl language.
901 This section documents compatibility between mandoc and other other
903 implementations, at this time limited to GNU troff
907 refers to groff version 1.15.
917 macros are considered regular macros.
920 implementations, these are special macros that must be specified without
921 spacing between the control character (which must be a period) and the
926 register is only compatible with OpenBSD's groff-1.15.
928 Historic groff did not accept white-space before a custom
936 and family would print funny white-spaces with historic groff when
937 using the next-line syntax.
947 .%A Joseph F. Ossanna
948 .%A Brian W. Kernighan
949 .%I AT&T Bell Laboratories
950 .%T Troff User's Manual
951 .%R Computing Science Technical Report
953 .%C Murray Hill, New Jersey
955 .%U http://www.kohala.com/start/troff/cstr54.ps
958 .%A Joseph F. Ossanna
959 .%A Brian W. Kernighan
961 .%T Heirloom Documentation Tools Nroff/Troff User's Manual
962 .%D September 17, 2007
963 .%U http://heirloom.sourceforge.net/doctools/troff.pdf
966 The RUNOFF typesetting system, whose input forms the basis for
968 was written in MAD and FAP for the CTSS operating system by Jerome E.
970 Doug McIlroy rewrote it in BCPL in 1969, renaming it
972 Dennis M. Ritchie rewrote McIlroy's
974 in PDP-11 assembly for
976 Joseph F. Ossanna improved roff and renamed it nroff
979 then ported nroff to C as troff, which Brian W. Kernighan released with
981 In 1989, James Clarke re-implemented troff in C++, naming it groff.
986 reference was written by
987 .An Kristaps Dzonsons ,
988 .Mt kristaps@bsd.lv ;
991 .Mt schwarze@openbsd.org .