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