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