Annotation of mandoc/roff.7, Revision 1.14
1.14 ! kristaps 1: .\" $Id: roff.7,v 1.13 2010/07/07 15:04:54 kristaps Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
1.12 schwarze 4: .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
1.1 kristaps 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: .\"
1.14 ! kristaps 18: .Dd $Mdocdate: July 7 2010 $
1.1 kristaps 19: .Dt ROFF 7
20: .Os
21: .Sh NAME
22: .Nm roff
23: .Nd roff language reference
24: .Sh DESCRIPTION
25: The
26: .Nm roff
27: language is a general-purpose text-formatting language. The purpose of
28: this document is to consistently describe those language constructs
29: accepted by the
30: .Xr mandoc 1
31: utility. It is a work in progress.
32: .Pp
33: An
34: .Nm
35: document follows simple rules: lines beginning with the control
36: characters
37: .Sq \.
38: or
39: .Sq \(aq
40: are parsed for macros. Other lines are interpreted within the scope of
41: prior macros:
42: .Bd -literal -offset indent
43: \&.xx Macro lines change control state.
44: Other lines are interpreted within the current state.
45: .Ed
46: .Sh LANGUAGE SYNTAX
47: .Nm
48: documents may contain only graphable 7-bit ASCII characters, the space
49: character, and, in certain circumstances, the tab character. All
50: manuals must have
51: .Ux
52: line terminators.
53: .Sh MACRO SYNTAX
54: Macros are arbitrary in length and begin with a control character ,
55: .Sq \.
56: or
57: .Sq \(aq ,
58: at the beginning of the line.
59: An arbitrary amount of whitespace may sit between the control character
60: and the macro name.
61: Thus, the following are equivalent:
62: .Bd -literal -offset indent
63: \&.if
64: \&.\ \ \ \&if
65: .Ed
66: .Sh REFERENCE
67: This section is a canonical reference of all macros, arranged
68: alphabetically.
1.3 kristaps 69: .Ss \&am
70: The syntax of this macro is the same as that of
71: .Sx \&ig ,
72: except that a leading argument must be specified.
73: It is ignored, as are its children.
74: .Ss \&ami
75: The syntax of this macro is the same as that of
76: .Sx \&ig ,
77: except that a leading argument must be specified.
78: It is ignored, as are its children.
79: .Ss \&am1
80: The syntax of this macro is the same as that of
81: .Sx \&ig ,
82: except that a leading argument must be specified.
83: It is ignored, as are its children.
84: .Ss \&de
85: The syntax of this macro is the same as that of
86: .Sx \&ig ,
87: except that a leading argument must be specified.
88: It is ignored, as are its children.
89: .Ss \&dei
90: The syntax of this macro is the same as that of
91: .Sx \&ig ,
92: except that a leading argument must be specified.
93: It is ignored, as are its children.
1.6 schwarze 94: .Ss \&ds
1.13 kristaps 95: Define a reserved word.
96: Its syntax is as follows:
97: .Pp
98: .D1 Pf \. Sx \&ds No Cm key val
99: .Pp
100: The
101: .Cm key
102: and
103: .Cm val
104: strings are space-separated.
105: The
106: .Cm key
107: values may be invoked in subsequent text by using \e*(NN for two-letter
108: pairs, \e*N for one-letter, and \e*[NNN] for arbitrary-length values.
1.14 ! kristaps 109: .Pp
! 110: If
! 111: .Cm val
! 112: is begun with a double-quote mark, the mark is passed over.
! 113: .Cm val
! 114: consists of
! 115: .Em all
! 116: text following this point, including whitespace and trailing
! 117: double-quotes.
1.3 kristaps 118: .Ss \&de1
119: The syntax of this macro is the same as that of
120: .Sx \&ig ,
121: except that a leading argument must be specified.
122: It is ignored, as are its children.
1.5 kristaps 123: .Ss \&el
124: The
125: .Qq else
126: half of an if/else conditional.
127: Pops a result off the stack of conditional evaluations pushed by
128: .Sx \&ie
129: and uses it as its conditional.
130: If no stack entries are present (e.g., due to no prior
131: .Sx \&ie
132: calls)
133: then false is assumed.
134: The syntax of this macro is similar to
135: .Sx \&if
136: except that the conditional is missing.
137: .Ss \&ie
138: The
139: .Qq if
140: half of an if/else conditional.
141: The result of the conditional is pushed into a stack used by subsequent
142: invocations of
143: .Sx \&el ,
144: which may be separated by any intervening input (or not exist at all).
145: Its syntax is equivalent to
146: .Sx \&if .
1.1 kristaps 147: .Ss \&if
1.7 schwarze 148: Begins a conditional.
149: Right now, the conditional evaluates to true
150: if and only if it starts with the letter
151: .Sy n ,
152: indicating processing in
153: .Xr nroff 1
154: style as opposed to
155: .Xr troff 1
156: style.
1.3 kristaps 157: If a conditional is false, its children are not processed, but are
158: syntactically interpreted to preserve the integrity of the input
159: document.
160: Thus,
161: .Pp
162: .D1 \&.if t \e .ig
163: .Pp
164: will discard the
165: .Sq \&.ig ,
166: which may lead to interesting results, but
167: .Pp
168: .D1 \&.if t \e .if t \e{\e
169: .Pp
170: will continue to syntactically interpret to the block close of the final
171: conditional.
172: Sub-conditionals, in this case, obviously inherit the truth value of
173: the parent.
174: This macro has the following syntax:
1.1 kristaps 175: .Pp
176: .Bd -literal -offset indent -compact
177: \&.if COND \e{\e
178: BODY...
179: \&.\e}
180: .Ed
181: .Bd -literal -offset indent -compact
182: \&.if COND \e{ BODY
1.2 kristaps 183: BODY... \e}
184: .Ed
185: .Bd -literal -offset indent -compact
186: \&.if COND \e{ BODY
1.1 kristaps 187: BODY...
188: \&.\e}
189: .Ed
190: .Bd -literal -offset indent -compact
191: \&.if COND \e
192: BODY
193: .Ed
194: .Pp
1.9 kristaps 195: COND is a conditional statement.
196: roff allows for complicated conditionals; mandoc is much simpler.
197: At this time, mandoc supports only
198: .Sq n ,
199: evaluating to true;
200: and
201: .Sq t ,
202: .Sq e ,
203: and
204: .Sq o ,
205: evaluating to false.
206: All other invocations are read up to the next end of line or space and
207: evaluate as false.
1.1 kristaps 208: .Pp
209: If the BODY section is begun by an escaped brace
210: .Sq \e{ ,
211: scope continues until a closing-brace macro
212: .Sq \.\e} .
213: If the BODY is not enclosed in braces, scope continues until the next
214: macro or word.
215: If the COND is followed by a BODY on the same line, whether after a
216: brace or not, then macros
217: .Em must
218: begin with a control character.
219: It is generally more intuitive, in this case, to write
220: .Bd -literal -offset indent
221: \&.if COND \e{\e
222: \&.foo
223: bar
224: \&.\e}
225: .Ed
226: .Pp
227: than having the macro follow as
228: .Pp
229: .D1 \&.if COND \e{ .foo
230: .Pp
231: The scope of a conditional is always parsed, but only executed if the
232: conditional evaluates to true.
233: .Pp
234: Note that text subsequent a
1.2 kristaps 235: .Sq \&.\e}
236: macro is discarded.
237: Furthermore, if an explicit closing sequence
1.1 kristaps 238: .Sq \e}
1.2 kristaps 239: is specified in a free-form line, the entire line is accepted within the
1.8 kristaps 240: scope of the prior macro, not only the text preceding the close, with the
241: .Sq \e}
242: collapsing into a zero-width space.
1.1 kristaps 243: .Ss \&ig
1.2 kristaps 244: Ignore input.
245: Accepts the following syntax:
246: .Pp
247: .Bd -literal -offset indent -compact
248: \&.ig
249: BODY...
250: \&..
251: .Ed
252: .Bd -literal -offset indent -compact
253: \&.ig END
254: BODY...
255: \&.END
256: .Ed
257: .Pp
258: In the first case, input is ignored until a
259: .Sq \&..
1.1 kristaps 260: macro is encountered on its own line.
1.2 kristaps 261: In the second case, input is ignored until a
262: .Sq \&.END
263: is encountered.
264: Text subsequent the
265: .Sq \&.END
266: or
267: .Sq \&..
1.1 kristaps 268: is discarded.
1.2 kristaps 269: .Pp
270: Do not use the escape
271: .Sq \e
272: anywhere in the definition of END.
273: It causes very strange behaviour.
274: Furthermore, if you redefine a
275: .Nm
276: macro, such as
277: .Pp
278: .D1 \&.ig if
279: .Pp
280: the subsequent invocation of
281: .Sx \&if
282: will first signify the end of comment, then be invoked as a macro.
283: This behaviour really shouldn't be counted upon.
1.6 schwarze 284: .Ss \&rm
285: Remove a request, macro or string.
286: This macro is intended to have one argument,
287: the name of the request, macro or string to be undefined.
288: Currently, it is ignored including its arguments,
289: and the number of arguments is not checked.
1.10 kristaps 290: .Ss \&nr
291: Define a register.
292: A register is an arbitrary string value that defines some sort of state,
293: which influences parsing and/or formatting.
294: Its syntax is as follows:
295: .Pp
296: .D1 Pf \. Sx \&nr Cm name value
297: .Pp
298: The
299: .Cm value
300: may, at the moment, only be an integer.
301: The
302: .Cm name
303: is defined up to the next whitespace.
304: The following register
305: .Cm name
306: requests are recognised:
307: .Bl -tag -width Ds
308: .It Cm nS
309: If set to a positive integer value, certain
310: .Xr mdoc 7
1.11 kristaps 311: macros will behave as if they were defined in the
1.10 kristaps 312: .Em SYNOPSIS
1.11 kristaps 313: section.
1.10 kristaps 314: Otherwise, this behaviour is unset (even if called within the
315: .Em SYNOPSIS
316: section itself).
1.11 kristaps 317: Note that invoking a new
318: .Xr mdoc 7
319: section will unset this value.
1.10 kristaps 320: .El
1.6 schwarze 321: .Ss \&tr
322: Output character translation.
1.7 schwarze 323: This macro is intended to have one argument,
1.6 schwarze 324: consisting of an even number of characters.
325: Currently, it is ignored including its arguments,
326: and the number of arguments is not checked.
1.2 kristaps 327: .Sh COMPATIBILITY
328: This section documents compatibility between mandoc and other other
329: troff implementations, at this time limited to GNU troff
330: .Pq Qq groff .
331: The term
332: .Qq historic groff
333: refers to groff versions before the
334: .Pa doc.tmac
335: file re-write
336: .Pq somewhere between 1.15 and 1.19 .
337: .Pp
338: .Bl -dash -compact
1.10 kristaps 339: .It
340: The
341: .Cm nS
342: request to
343: .Sx \&nr
344: is only compatible with OpenBSD's groff.
1.2 kristaps 345: .It
346: Historic groff did not accept white-space buffering the custom END tag
347: for the
348: .Sx \&ig
349: macro.
1.4 kristaps 350: .It
351: The
352: .Sx \&if
353: and family would print funny white-spaces with historic groff when
354: depending on next-line syntax.
1.2 kristaps 355: .El
1.1 kristaps 356: .Sh AUTHORS
357: The
358: .Nm
359: reference was written by
360: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb