Import mdocml-1.11.3
[dragonfly.git] / contrib / mdocml / roff.7
CommitLineData
a4c7eb57 1.\" $Id: roff.7,v 1.29 2011/05/24 15:22:14 kristaps Exp $
80387638
SW
2.\"
3.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
4.\" Copyright (c) 2010 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.\"
a4c7eb57 18.Dd $Mdocdate: May 24 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.
28In particular, it serves as the basis for the
29.Xr mdoc 7
30and
31.Xr man 7
32manual formatting macro languages.
33This manual describes the subset of the
34.Nm
35language accepted by the
36.Xr mandoc 1
37utility.
38.Pp
39Input lines beginning with the control characters
40.Sq \&.
41or
42.Sq \(aq
43are parsed for requests and macros.
44These define the document structure, change the processing state
45and manipulate the formatting.
46Some requests and macros also produce formatted output,
47while others do not.
48.Pp
49All other input lines provide free-form text to be printed;
50the formatting of free-form text depends on the respective
51processing context.
52.Sh LANGUAGE SYNTAX
53.Nm
54documents may contain only graphable 7-bit ASCII characters, the space
55character, and, in certain circumstances, the tab character.
56To produce other characters in the output, use the escape sequences
57documented in the
58.Xr mandoc_char 7
59manual.
80387638
SW
60.Sh REQUEST SYNTAX
61A request or macro line consists of:
62.Pp
63.Bl -enum -compact
64.It
65the control character
66.Sq \&.
67or
68.Sq \(aq
69at the beginning of the line,
70.It
71optionally an arbitrary amount of whitespace,
72.It
73the name of the request or the macro, which is one word of arbitrary
74length, terminated by whitespace,
75.It
76and zero or more arguments delimited by whitespace.
77.El
78.Pp
79Thus, the following request lines are all equivalent:
80.Bd -literal -offset indent
81\&.ig end
82\&.ig end
83\&. ig end
84.Ed
60e1e752
SW
85.Sh MACRO SYNTAX
86Macros can be defined by the
87.Sx \&de
88request.
89When called, they follow the same syntax as requests, except that
90macro arguments may optionally be quoted by enclosing them
91in double quote characters
92.Pq Sq \(dq .
93To be recognized as the beginning of a quoted argument, the opening
94quote character must be preceded by a space character.
95.Pp
96A quoted argument may contain whitespace, and pairs of double quote
97characters
98.Pq Sq Qq
99resolve to single double quote characters.
100A quoted argument extends to the next double quote character that is not
101part of a pair, or to the end of the input line, whichever comes earlier.
102Leaving out the terminating double quote character at the end of the line
103is discouraged.
104For clarity, if more arguments follow on the same input line,
105it is recommended to follow the terminating double quote character
106by a space character; in case the next character after the terminating
107double quote character is anything else, it is regarded as the beginning
108of the next, unquoted argument.
109.Pp
110Both in quoted and unquoted arguments, pairs of backslashes
111.Pq Sq \e\e
112resolve to single backslashes.
113In unquoted arguments, space characters can alternatively be included
114by preceding them with a backslash
115.Pq Sq \e\~ ,
116but quoting is usually better for clarity.
80387638
SW
117.Sh REQUEST REFERENCE
118The
119.Xr mandoc 1
120.Nm
121parser recognizes the following requests.
122Note that the
123.Nm
124language defines many more requests not implemented in
125.Xr mandoc 1 .
126.Ss \&ad
127Set line adjustment mode.
128This line-scoped request is intended to have one argument to select
129normal, left, right, or center adjustment for subsequent text.
130Currently, it is ignored including its arguments,
131and the number of arguments is not checked.
132.Ss \&am
133Append to a macro definition.
134The syntax of this request is the same as that of
135.Sx \&de .
136It is currently ignored by
137.Xr mandoc 1 ,
138as are its children.
139.Ss \&ami
140Append to a macro definition, specifying the macro name indirectly.
141The syntax of this request is the same as that of
142.Sx \&dei .
143It is currently ignored by
144.Xr mandoc 1 ,
145as are its children.
146.Ss \&am1
147Append to a macro definition, switching roff compatibility mode off
148during macro execution.
149The syntax of this request is the same as that of
150.Sx \&de1 .
151It is currently ignored by
152.Xr mandoc 1 ,
153as are its children.
154.Ss \&de
155Define a
156.Nm
157macro.
158Its syntax can be either
159.Bd -literal -offset indent
160.Pf . Cm \&de Ar name
161.Ar macro definition
162\&..
163.Ed
164.Pp
165or
166.Bd -literal -offset indent
167.Pf . Cm \&de Ar name Ar end
168.Ar macro definition
169.Pf . Ar end
170.Ed
171.Pp
172Both forms define or redefine the macro
173.Ar name
174to represent the
175.Ar macro definition ,
176which may consist of one or more input lines, including the newline
177characters terminating each line, optionally containing calls to
178.Nm
179requests,
180.Nm
181macros or high-level macros like
182.Xr man 7
183or
184.Xr mdoc 7
185macros, whichever applies to the document in question.
186.Pp
187Specifying a custom
188.Ar end
189macro works in the same way as for
190.Sx \&ig ;
191namely, the call to
192.Sq Pf . Ar end
193first ends the
194.Ar macro definition ,
195and after that, it is also evaluated as a
196.Nm
197request or
198.Nm
199macro, but not as a high-level macro.
200.Pp
201The macro can be invoked later using the syntax
202.Pp
203.D1 Pf . Ar name Op Ar argument Op Ar argument ...
204.Pp
60e1e752
SW
205Regarding argument parsing, see
206.Sx MACRO SYNTAX
207above.
80387638
SW
208.Pp
209The line invoking the macro will be replaced
210in the input stream by the
211.Ar macro definition ,
212replacing all occurrences of
213.No \e\e$ Ns Ar N ,
214where
215.Ar N
216is a digit, by the
217.Ar N Ns th Ar argument .
218For example,
219.Bd -literal -offset indent
220\&.de ZN
221\efI\e^\e\e$1\e^\efP\e\e$2
222\&..
223\&.ZN XtFree .
224.Ed
225.Pp
226produces
227.Pp
228.D1 \efI\e^XtFree\e^\efP.
229.Pp
230in the input stream, and thus in the output: \fI\^XtFree\^\fP.
231.Pp
232Since macros and user-defined strings share a common string table,
233defining a macro
234.Ar name
235clobbers the user-defined string
236.Ar name ,
237and the
238.Ar macro definition
239can also be printed using the
240.Sq \e*
241string interpolation syntax described below
242.Sx ds ,
243but this is rarely useful because every macro definition contains at least
244one explicit newline character.
245.Pp
246In order to prevent endless recursion, both groff and
247.Xr mandoc 1
248limit the stack depth for expanding macros and strings
249to a large, but finite number.
250Do not rely on the exact value of this limit.
251.Ss \&dei
252Define a
253.Nm
254macro, specifying the macro name indirectly.
255The syntax of this request is the same as that of
256.Sx \&de .
257It is currently ignored by
258.Xr mandoc 1 ,
259as are its children.
260.Ss \&de1
261Define a
262.Nm
263macro that will be executed with
264.Nm
265compatibility mode switched off during macro execution.
266This is a GNU extension not available in traditional
267.Nm
268implementations and not even in older versions of groff.
269Since
270.Xr mandoc 1
271does not implement
272.Nm
273compatibility mode at all, it handles this request as an alias for
274.Sx \&de .
275.Ss \&ds
276Define a user-defined string.
277Its syntax is as follows:
278.Pp
279.D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
280.Pp
281The
282.Ar name
283and
284.Ar string
285arguments are space-separated.
286If the
287.Ar string
288begins with a double-quote character, that character will not be part
289of the string.
290All remaining characters on the input line form the
291.Ar string ,
292including whitespace and double-quote characters, even trailing ones.
293.Pp
294The
295.Ar string
296can be interpolated into subsequent text by using
297.No \e* Ns Bq Ar name
298for a
299.Ar name
300of arbitrary length, or \e*(NN or \e*N if the length of
301.Ar name
302is two or one characters, respectively.
303Interpolation can be prevented by escaping the leading backslash;
304that is, an asterisk preceded by an even number of backslashes
305does not trigger string interpolation.
306.Pp
307Since user-defined strings and macros share a common string table,
308defining a string
309.Ar name
310clobbers the macro
311.Ar name ,
312and the
313.Ar name
314used for defining a string can also be invoked as a macro,
315in which case the following input line will be appended to the
316.Ar string ,
317forming a new input line passed to the
318.Nm
319parser.
320For example,
321.Bd -literal -offset indent
322\&.ds badidea .S
323\&.badidea
324H SYNOPSIS
325.Ed
326.Pp
327invokes the
328.Cm SH
329macro when used in a
330.Xr man 7
331document.
332Such abuse is of course strongly discouraged.
333.Ss \&el
334The
335.Qq else
336half of an if/else conditional.
337Pops a result off the stack of conditional evaluations pushed by
338.Sx \&ie
339and uses it as its conditional.
340If no stack entries are present (e.g., due to no prior
341.Sx \&ie
342calls)
343then false is assumed.
344The syntax of this request is similar to
345.Sx \&if
346except that the conditional is missing.
60e1e752
SW
347.Ss \&EN
348End an equation block.
349See
350.Sx \&EQ .
351.Ss \&EQ
352Begin an equation block.
353See
354.Xr eqn 7
355for a description of the equation language.
80387638
SW
356.Ss \&hy
357Set automatic hyphenation mode.
358This line-scoped request is currently ignored.
359.Ss \&ie
360The
361.Qq if
362half of an if/else conditional.
363The result of the conditional is pushed into a stack used by subsequent
364invocations of
365.Sx \&el ,
366which may be separated by any intervening input (or not exist at all).
367Its syntax is equivalent to
368.Sx \&if .
369.Ss \&if
370Begins a conditional.
371Right now, the conditional evaluates to true
372if and only if it starts with the letter
373.Sy n ,
374indicating processing in nroff style as opposed to troff style.
375If a conditional is false, its children are not processed, but are
376syntactically interpreted to preserve the integrity of the input
377document.
378Thus,
379.Pp
380.D1 \&.if t .ig
381.Pp
382will discard the
383.Sq \&.ig ,
384which may lead to interesting results, but
385.Pp
386.D1 \&.if t .if t \e{\e
387.Pp
388will continue to syntactically interpret to the block close of the final
389conditional.
390Sub-conditionals, in this case, obviously inherit the truth value of
391the parent.
392This request has the following syntax:
393.Bd -literal -offset indent
394\&.if COND \e{\e
395BODY...
396\&.\e}
397.Ed
398.Bd -literal -offset indent
399\&.if COND \e{ BODY
400BODY... \e}
401.Ed
402.Bd -literal -offset indent
403\&.if COND \e{ BODY
404BODY...
405\&.\e}
406.Ed
407.Bd -literal -offset indent
408\&.if COND \e
409BODY
410.Ed
411.Pp
412COND is a conditional statement.
413roff allows for complicated conditionals; mandoc is much simpler.
414At this time, mandoc supports only
415.Sq n ,
416evaluating to true;
417and
418.Sq t ,
419.Sq e ,
420and
421.Sq o ,
422evaluating to false.
423All other invocations are read up to the next end of line or space and
424evaluate as false.
425.Pp
426If the BODY section is begun by an escaped brace
427.Sq \e{ ,
428scope continues until a closing-brace escape sequence
429.Sq \.\e} .
430If the BODY is not enclosed in braces, scope continues until
431the end of the line.
432If the COND is followed by a BODY on the same line, whether after a
433brace or not, then requests and macros
434.Em must
435begin with a control character.
436It is generally more intuitive, in this case, to write
437.Bd -literal -offset indent
438\&.if COND \e{\e
439\&.foo
440bar
441\&.\e}
442.Ed
443.Pp
444than having the request or macro follow as
445.Pp
446.D1 \&.if COND \e{ .foo
447.Pp
448The scope of a conditional is always parsed, but only executed if the
449conditional evaluates to true.
450.Pp
a4c7eb57 451Note that the
80387638 452.Sq \e}
a4c7eb57
SW
453is converted into a zero-width escape sequence if not passed as a
454standalone macro
455.Sq \&.\e} .
456For example,
457.Pp
458.D1 \&.Fl a \e} b
459.Pp
460will result in
80387638 461.Sq \e}
a4c7eb57
SW
462being considered an argument of the
463.Sq \&Fl
464macro.
80387638
SW
465.Ss \&ig
466Ignore input.
467Its syntax can be either
468.Bd -literal -offset indent
469.Pf . Cm \&ig
470.Ar ignored text
471\&..
472.Ed
473.Pp
474or
475.Bd -literal -offset indent
476.Pf . Cm \&ig Ar end
477.Ar ignored text
478.Pf . Ar end
479.Ed
480.Pp
481In the first case, input is ignored until a
482.Sq \&..
483request is encountered on its own line.
484In the second case, input is ignored until the specified
485.Sq Pf . Ar end
486macro is encountered.
487Do not use the escape character
488.Sq \e
489anywhere in the definition of
490.Ar end ;
491it would cause very strange behaviour.
492.Pp
493When the
494.Ar end
495macro is a roff request or a roff macro, like in
496.Pp
497.D1 \&.ig if
498.Pp
499the subsequent invocation of
500.Sx \&if
501will first terminate the
502.Ar ignored text ,
503then be invoked as usual.
504Otherwise, it only terminates the
505.Ar ignored text ,
506and arguments following it or the
507.Sq \&..
508request are discarded.
509.Ss \&ne
510Declare the need for the specified minimum vertical space
511before the next trap or the bottom of the page.
512This line-scoped request is currently ignored.
513.Ss \&nh
514Turn off automatic hyphenation mode.
515This line-scoped request is currently ignored.
516.Ss \&rm
517Remove a request, macro or string.
518This request is intended to have one argument,
519the name of the request, macro or string to be undefined.
520Currently, it is ignored including its arguments,
521and the number of arguments is not checked.
522.Ss \&nr
523Define a register.
524A register is an arbitrary string value that defines some sort of state,
525which influences parsing and/or formatting.
526Its syntax is as follows:
527.Pp
528.D1 Pf \. Cm \&nr Ar name Ar value
529.Pp
530The
531.Ar value
532may, at the moment, only be an integer.
533So far, only the following register
534.Ar name
535is recognised:
536.Bl -tag -width Ds
537.It Cm nS
538If set to a positive integer value, certain
539.Xr mdoc 7
540macros will behave in the same way as in the
541.Em SYNOPSIS
542section.
543If set to 0, these macros will behave in the same way as outside the
544.Em SYNOPSIS
545section, even when called within the
546.Em SYNOPSIS
547section itself.
548Note that starting a new
549.Xr mdoc 7
550section with the
551.Cm \&Sh
552macro will reset this register.
553.El
60e1e752
SW
554.Ss \&ns
555Turn on no-space mode.
556This line-scoped request is intended to take no arguments.
557Currently, it is ignored including its arguments,
558and the number of arguments is not checked.
559.Ss \&ps
560Change point size.
561This line-scoped request is intended to take one numerical argument.
562Currently, it is ignored including its arguments,
563and the number of arguments is not checked.
80387638
SW
564.Ss \&so
565Include a source file.
566Its syntax is as follows:
567.Pp
568.D1 Pf \. Cm \&so Ar file
569.Pp
570The
571.Ar file
572will be read and its contents processed as input in place of the
573.Sq \&.so
574request line.
a4c7eb57 575To avoid inadvertent inclusion of unrelated files,
80387638
SW
576.Xr mandoc 1
577only accepts relative paths not containing the strings
578.Qq ../
579and
580.Qq /.. .
60e1e752
SW
581.Ss \&ta
582Set tab stops.
583This line-scoped request can take an arbitrary number of arguments.
584Currently, it is ignored including its arguments.
80387638
SW
585.Ss \&tr
586Output character translation.
587This request is intended to have one argument,
588consisting of an even number of characters.
589Currently, it is ignored including its arguments,
590and the number of arguments is not checked.
591.Ss \&T&
592Re-start a table layout, retaining the options of the prior table
593invocation.
594See
595.Sx \&TS .
596.Ss \&TE
597End a table context.
598See
599.Sx \&TS .
600.Ss \&TS
601Begin a table, which formats input in aligned rows and columns.
602See
603.Xr tbl 7
604for a description of the tbl language.
605.Sh COMPATIBILITY
606This section documents compatibility between mandoc and other other
607.Nm
608implementations, at this time limited to GNU troff
609.Pq Qq groff .
610The term
611.Qq historic groff
612refers to groff version 1.15.
613.Pp
614.Bl -dash -compact
615.It
60e1e752
SW
616In mandoc, the
617.Sx \&EQ ,
618.Sx \&TE ,
619.Sx \&TS ,
620and
621.Sx \&T& ,
622macros are considered regular macros.
623In all other
624.Nm
625implementations, these are special macros that must be specified without
626spacing between the control character (which must be a period) and the
627macro name.
628.It
80387638
SW
629The
630.Cm nS
631register is only compatible with OpenBSD's groff-1.15.
632.It
633Historic groff did not accept white-space before a custom
634.Ar end
635macro for the
636.Sx \&ig
637request.
638.It
639The
640.Sx \&if
641and family would print funny white-spaces with historic groff when
642using the next-line syntax.
643.El
644.Sh SEE ALSO
645.Xr mandoc 1 ,
60e1e752 646.Xr eqn 7 ,
80387638
SW
647.Xr man 7 ,
648.Xr mandoc_char 7 ,
649.Xr mdoc 7 ,
650.Xr tbl 7
651.Rs
652.%A Joseph F. Ossanna
653.%A Brian W. Kernighan
654.%I AT&T Bell Laboratories
655.%T Troff User's Manual
656.%R Computing Science Technical Report
657.%N 54
658.%C Murray Hill, New Jersey
659.%D 1976 and 1992
660.%U http://www.kohala.com/start/troff/cstr54.ps
661.Re
662.Rs
663.%A Joseph F. Ossanna
664.%A Brian W. Kernighan
665.%A Gunnar Ritter
666.%T Heirloom Documentation Tools Nroff/Troff User's Manual
667.%D September 17, 2007
668.%U http://heirloom.sourceforge.net/doctools/troff.pdf
669.Re
670.Sh HISTORY
671The RUNOFF typesetting system was written in PL/1 for the CTSS
672operating system by Jerome ("Jerry") E. Saltzer in 1961.
673It was first used as the main documentation tool by Multics since 1963.
674Robert ("Bob") H. Morris ported it to the GE-635 and called it
675.Nm ,
676Doug McIlroy rewrote it in BCPL in 1969,
677Joseph F. Ossanna rewrote it in PDP-11 assembly in 1973,
678and Brian W. Kernighan rewrote it in C in 1975.
679.Sh AUTHORS
680.An -nosplit
681This partial
682.Nm
683reference was written by
684.An Kristaps Dzonsons Aq kristaps@bsd.lv
685and
686.An Ingo Schwarze Aq schwarze@openbsd.org .