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