Annotation of mandoc/roff.7, Revision 1.12
1.12 ! schwarze 1: .\" $Id: roff.7,v 1.11 2010/06/27 16:36:22 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.12 ! schwarze 18: .Dd $Mdocdate: June 27 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
95: Define a string.
96: This macro is intended to have two arguments,
97: the name of the string to define and its content.
98: Currently, it is ignored including its arguments,
99: and the number of arguments is not checked.
1.3 kristaps 100: .Ss \&de1
101: The syntax of this macro is the same as that of
102: .Sx \&ig ,
103: except that a leading argument must be specified.
104: It is ignored, as are its children.
1.5 kristaps 105: .Ss \&el
106: The
107: .Qq else
108: half of an if/else conditional.
109: Pops a result off the stack of conditional evaluations pushed by
110: .Sx \&ie
111: and uses it as its conditional.
112: If no stack entries are present (e.g., due to no prior
113: .Sx \&ie
114: calls)
115: then false is assumed.
116: The syntax of this macro is similar to
117: .Sx \&if
118: except that the conditional is missing.
119: .Ss \&ie
120: The
121: .Qq if
122: half of an if/else conditional.
123: The result of the conditional is pushed into a stack used by subsequent
124: invocations of
125: .Sx \&el ,
126: which may be separated by any intervening input (or not exist at all).
127: Its syntax is equivalent to
128: .Sx \&if .
1.1 kristaps 129: .Ss \&if
1.7 schwarze 130: Begins a conditional.
131: Right now, the conditional evaluates to true
132: if and only if it starts with the letter
133: .Sy n ,
134: indicating processing in
135: .Xr nroff 1
136: style as opposed to
137: .Xr troff 1
138: style.
1.3 kristaps 139: If a conditional is false, its children are not processed, but are
140: syntactically interpreted to preserve the integrity of the input
141: document.
142: Thus,
143: .Pp
144: .D1 \&.if t \e .ig
145: .Pp
146: will discard the
147: .Sq \&.ig ,
148: which may lead to interesting results, but
149: .Pp
150: .D1 \&.if t \e .if t \e{\e
151: .Pp
152: will continue to syntactically interpret to the block close of the final
153: conditional.
154: Sub-conditionals, in this case, obviously inherit the truth value of
155: the parent.
156: This macro has the following syntax:
1.1 kristaps 157: .Pp
158: .Bd -literal -offset indent -compact
159: \&.if COND \e{\e
160: BODY...
161: \&.\e}
162: .Ed
163: .Bd -literal -offset indent -compact
164: \&.if COND \e{ BODY
1.2 kristaps 165: BODY... \e}
166: .Ed
167: .Bd -literal -offset indent -compact
168: \&.if COND \e{ BODY
1.1 kristaps 169: BODY...
170: \&.\e}
171: .Ed
172: .Bd -literal -offset indent -compact
173: \&.if COND \e
174: BODY
175: .Ed
176: .Pp
1.9 kristaps 177: COND is a conditional statement.
178: roff allows for complicated conditionals; mandoc is much simpler.
179: At this time, mandoc supports only
180: .Sq n ,
181: evaluating to true;
182: and
183: .Sq t ,
184: .Sq e ,
185: and
186: .Sq o ,
187: evaluating to false.
188: All other invocations are read up to the next end of line or space and
189: evaluate as false.
1.1 kristaps 190: .Pp
191: If the BODY section is begun by an escaped brace
192: .Sq \e{ ,
193: scope continues until a closing-brace macro
194: .Sq \.\e} .
195: If the BODY is not enclosed in braces, scope continues until the next
196: macro or word.
197: If the COND is followed by a BODY on the same line, whether after a
198: brace or not, then macros
199: .Em must
200: begin with a control character.
201: It is generally more intuitive, in this case, to write
202: .Bd -literal -offset indent
203: \&.if COND \e{\e
204: \&.foo
205: bar
206: \&.\e}
207: .Ed
208: .Pp
209: than having the macro follow as
210: .Pp
211: .D1 \&.if COND \e{ .foo
212: .Pp
213: The scope of a conditional is always parsed, but only executed if the
214: conditional evaluates to true.
215: .Pp
216: Note that text subsequent a
1.2 kristaps 217: .Sq \&.\e}
218: macro is discarded.
219: Furthermore, if an explicit closing sequence
1.1 kristaps 220: .Sq \e}
1.2 kristaps 221: is specified in a free-form line, the entire line is accepted within the
1.8 kristaps 222: scope of the prior macro, not only the text preceding the close, with the
223: .Sq \e}
224: collapsing into a zero-width space.
1.1 kristaps 225: .Ss \&ig
1.2 kristaps 226: Ignore input.
227: Accepts the following syntax:
228: .Pp
229: .Bd -literal -offset indent -compact
230: \&.ig
231: BODY...
232: \&..
233: .Ed
234: .Bd -literal -offset indent -compact
235: \&.ig END
236: BODY...
237: \&.END
238: .Ed
239: .Pp
240: In the first case, input is ignored until a
241: .Sq \&..
1.1 kristaps 242: macro is encountered on its own line.
1.2 kristaps 243: In the second case, input is ignored until a
244: .Sq \&.END
245: is encountered.
246: Text subsequent the
247: .Sq \&.END
248: or
249: .Sq \&..
1.1 kristaps 250: is discarded.
1.2 kristaps 251: .Pp
252: Do not use the escape
253: .Sq \e
254: anywhere in the definition of END.
255: It causes very strange behaviour.
256: Furthermore, if you redefine a
257: .Nm
258: macro, such as
259: .Pp
260: .D1 \&.ig if
261: .Pp
262: the subsequent invocation of
263: .Sx \&if
264: will first signify the end of comment, then be invoked as a macro.
265: This behaviour really shouldn't be counted upon.
1.6 schwarze 266: .Ss \&rm
267: Remove a request, macro or string.
268: This macro is intended to have one argument,
269: the name of the request, macro or string to be undefined.
270: Currently, it is ignored including its arguments,
271: and the number of arguments is not checked.
1.10 kristaps 272: .Ss \&nr
273: Define a register.
274: A register is an arbitrary string value that defines some sort of state,
275: which influences parsing and/or formatting.
276: Its syntax is as follows:
277: .Pp
278: .D1 Pf \. Sx \&nr Cm name value
279: .Pp
280: The
281: .Cm value
282: may, at the moment, only be an integer.
283: The
284: .Cm name
285: is defined up to the next whitespace.
286: The following register
287: .Cm name
288: requests are recognised:
289: .Bl -tag -width Ds
290: .It Cm nS
291: If set to a positive integer value, certain
292: .Xr mdoc 7
1.11 kristaps 293: macros will behave as if they were defined in the
1.10 kristaps 294: .Em SYNOPSIS
1.11 kristaps 295: section.
1.10 kristaps 296: Otherwise, this behaviour is unset (even if called within the
297: .Em SYNOPSIS
298: section itself).
1.11 kristaps 299: Note that invoking a new
300: .Xr mdoc 7
301: section will unset this value.
1.10 kristaps 302: .El
1.6 schwarze 303: .Ss \&tr
304: Output character translation.
1.7 schwarze 305: This macro is intended to have one argument,
1.6 schwarze 306: consisting of an even number of characters.
307: Currently, it is ignored including its arguments,
308: and the number of arguments is not checked.
1.2 kristaps 309: .Sh COMPATIBILITY
310: This section documents compatibility between mandoc and other other
311: troff implementations, at this time limited to GNU troff
312: .Pq Qq groff .
313: The term
314: .Qq historic groff
315: refers to groff versions before the
316: .Pa doc.tmac
317: file re-write
318: .Pq somewhere between 1.15 and 1.19 .
319: .Pp
320: .Bl -dash -compact
1.10 kristaps 321: .It
322: The
323: .Cm nS
324: request to
325: .Sx \&nr
326: is only compatible with OpenBSD's groff.
1.2 kristaps 327: .It
328: Historic groff did not accept white-space buffering the custom END tag
329: for the
330: .Sx \&ig
331: macro.
1.4 kristaps 332: .It
333: The
334: .Sx \&if
335: and family would print funny white-spaces with historic groff when
336: depending on next-line syntax.
1.2 kristaps 337: .El
1.1 kristaps 338: .Sh AUTHORS
339: The
340: .Nm
341: reference was written by
342: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to roff.7 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc