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