Annotation of mandoc/roff.7, Revision 1.16
1.16 ! schwarze 1: .\" $Id: roff.7,v 1.15 2010/12/06 16:37:32 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.16 ! schwarze 18: .Dd $Mdocdate: December 6 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
1.15 kristaps 40: are parsed for requests and macros.
41: Other lines are interpreted within the scope of
1.1 kristaps 42: prior macros:
43: .Bd -literal -offset indent
44: \&.xx Macro lines change control state.
45: Other lines are interpreted within the current state.
46: .Ed
47: .Sh LANGUAGE SYNTAX
48: .Nm
49: documents may contain only graphable 7-bit ASCII characters, the space
50: character, and, in certain circumstances, the tab character. All
51: manuals must have
52: .Ux
53: line terminators.
54: .Sh MACRO SYNTAX
1.15 kristaps 55: Requests and macros are arbitrary in length and begin with a control
56: character,
1.1 kristaps 57: .Sq \.
58: or
59: .Sq \(aq ,
60: at the beginning of the line.
61: An arbitrary amount of whitespace may sit between the control character
1.15 kristaps 62: and the request or macro name.
1.1 kristaps 63: Thus, the following are equivalent:
64: .Bd -literal -offset indent
65: \&.if
66: \&.\ \ \ \&if
67: .Ed
1.15 kristaps 68: .Sh REQUEST REFERENCE
69: This section is a canonical reference of all requests recognized by the
70: .Xr mandoc 1
71: .Nm
72: parser.
73: The
74: .Nm
75: language defines many more requests and macros not implemented in
76: .Xr mandoc 1 .
77: .Ss \&ad
78: Set line adjustment mode.
79: This line-scoped request is intended to have one argument to select
80: normal, left, right, or center adjustment for subsequent text.
81: Currently, it is ignored including its arguments,
82: and the number of arguments is not checked.
1.3 kristaps 83: .Ss \&am
1.15 kristaps 84: Append to a macro definition.
85: The syntax of this request is the same as that of
86: .Sx \&de .
87: It is currently ignored by
88: .Xr mandoc 1 ,
89: as are its children.
1.3 kristaps 90: .Ss \&ami
1.15 kristaps 91: Append to a macro definition, specifying the macro name indirectly.
92: The syntax of this request is the same as that of
93: .Sx \&dei .
94: It is currently ignored by
95: .Xr mandoc 1 ,
96: as are its children.
1.3 kristaps 97: .Ss \&am1
1.15 kristaps 98: Append to a macro definition, switching roff compatibility mode off
99: during macro execution.
100: The syntax of this request is the same as that of
101: .Sx \&de1 .
102: It is currently ignored by
103: .Xr mandoc 1 ,
104: as are its children.
1.3 kristaps 105: .Ss \&de
1.15 kristaps 106: Define a user-defined
107: .Nm
108: macro.
109: Its syntax can be either
110: .Bd -literal -offset indent
111: .Pf . Cm \&de Ar name
112: .Ar macro definition
113: \&..
114: .Ed
115: .Pp
116: or
117: .Bd -literal -offset indent
118: .Pf . Cm \&de Ar name Ar end
119: .Ar macro definition
120: .Pf . Ar end
121: .Ed
122: .Pp
123: Both forms define or redefine the macro
124: .Ar name
125: to represent the
126: .Ar macro definition ,
127: which may consist of one or more input lines, including the newline
128: characters terminating each line, optionally containing calls to
129: .Nm
130: requests,
131: .Nm
132: macros or high-level macros like
133: .Xr man 7
134: or
135: .Xr mdoc 7
136: macros, whichever applies to the document in question.
137: .Pp
138: Specifying a custom
139: .Ar end
140: macro works in the same way as for
141: .Sx \&ig ;
142: namely, the call to
143: .Sq Pf . Ar end
144: first ends the
145: .Ar macro definition ,
146: and after that, it is also evaluated as a
147: .Nm
148: request or
149: .Nm
150: macro, but not as a high-level macro.
151: .Pp
152: A user-defined macro can be invoked later using the syntax
153: .Pp
154: .D1 Pf . Ar name Op Ar argument Op Ar argument ...
155: .Pp
156: Arguments are separated by blank characters and can be quoted
157: using double-quotes
158: .Pq Sq \(dq
159: to allow inclusion of blank characters into arguments.
160: To include the double-quote character into a quoted argument,
161: escape it from ending the argument by doubling it.
162: .Pp
163: The line invoking the user-defined macro will be replaced
164: in the input stream by the
165: .Ar macro definition ,
166: replacing all occurrences of
167: .No \e\e$ Ns Ar N ,
168: where
169: .Ar N
170: is a digit, by the
171: .Ar N Ns th Ar argument .
172: For example,
173: .Bd -literal -offset indent
174: \&.de ZN
175: \efI\e^\e\e$1\e^\efP\e\e$2
176: \&..
177: \&.ZN XtFree .
178: .Ed
179: .Pp
180: produces
181: .Pp
182: .D1 \efI\e^XtFree\e^\efP.
183: .Pp
184: in the input stream, and thus in the output: \fI\^XtFree\^\fP.
185: .Pp
186: Since user-defined macros and strings share a common string table,
187: defining a macro
188: .Ar name
189: clobbers the user-defined string
190: .Ar name ,
191: and the
192: .Ar macro definition
193: can also be printed using the
194: .Sq \e*
195: string interpolation syntax described below
196: .Sx ds ,
197: but this is rarely useful because every macro definition contains at least
198: one explicit newline character.
1.16 ! schwarze 199: .Pp
! 200: In order to prevent endless recursion, both groff and
! 201: .Xr mandoc 1
! 202: limit the stack depth for expanding macros and strings
! 203: to a large, but finite number.
! 204: Do not rely on the exact value of this limit.
1.3 kristaps 205: .Ss \&dei
1.15 kristaps 206: Define a user-defined
207: .Nm
208: macro, specifying the macro name indirectly.
1.3 kristaps 209: The syntax of this macro is the same as that of
1.15 kristaps 210: .Sx \&de .
211: It is currently ignored by
212: .Xr mandoc 1 ,
213: as are its children.
214: .Ss \&de1
215: Define a user-defined
216: .Nm
217: macro that will be executed with
218: .Nm
219: compatibility mode switched off during macro execution.
220: This is a GNU extension not available in traditional
221: .Nm
222: implementations and not even in older versions of groff.
223: Since
224: .Xr mandoc 1
225: does not implement
226: .Nm
227: compatibility mode at all, it handles this macro as an alias for
228: .Sx \&de .
1.6 schwarze 229: .Ss \&ds
1.15 kristaps 230: Define a user-defined string.
1.13 kristaps 231: Its syntax is as follows:
232: .Pp
1.15 kristaps 233: .D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
1.13 kristaps 234: .Pp
235: The
1.15 kristaps 236: .Ar name
1.13 kristaps 237: and
1.15 kristaps 238: .Ar string
239: arguments are space-separated.
240: If the
241: .Ar string
242: begins with a double-quote character, that character will not be part
243: of the string.
244: All remaining characters on the input line form the
245: .Ar string ,
246: including whitespace and double-quote characters, even trailing ones.
247: .Pp
1.13 kristaps 248: The
1.15 kristaps 249: .Ar string
250: can be interpolated into subsequent text by using
251: .No \e* Ns Bq Ar name
252: for a
253: .Ar name
254: of arbitrary length, or \e*(NN or \e*N if the length of
255: .Ar name
256: is two or one characters, respectively.
257: .Pp
258: Since user-defined strings and macros share a common string table,
259: defining a string
260: .Ar name
261: clobbers the user-defined macro
262: .Ar name ,
263: and the
264: .Ar name
265: used for defining a string can also be invoked as a macro,
266: in which case the following input line will be appended to the
267: .Ar string ,
268: forming a new input line passed to the
269: .Nm
270: parser.
271: For example,
272: .Bd -literal -offset indent
273: \&.ds badidea .S
274: \&.badidea
275: H SYNOPSIS
276: .Ed
277: .Pp
278: invokes the
279: .Cm SH
280: macro when used in a
281: .Xr man 7
282: document.
283: Such abuse is of course strongly discouraged.
1.5 kristaps 284: .Ss \&el
285: The
286: .Qq else
287: half of an if/else conditional.
288: Pops a result off the stack of conditional evaluations pushed by
289: .Sx \&ie
290: and uses it as its conditional.
291: If no stack entries are present (e.g., due to no prior
292: .Sx \&ie
293: calls)
294: then false is assumed.
295: The syntax of this macro is similar to
296: .Sx \&if
297: except that the conditional is missing.
1.15 kristaps 298: .Ss \&hy
299: Set automatic hyphenation mode.
300: This line-scoped request is currently ignored.
1.5 kristaps 301: .Ss \&ie
302: The
303: .Qq if
304: half of an if/else conditional.
305: The result of the conditional is pushed into a stack used by subsequent
306: invocations of
307: .Sx \&el ,
308: which may be separated by any intervening input (or not exist at all).
309: Its syntax is equivalent to
310: .Sx \&if .
1.1 kristaps 311: .Ss \&if
1.7 schwarze 312: Begins a conditional.
313: Right now, the conditional evaluates to true
314: if and only if it starts with the letter
315: .Sy n ,
316: indicating processing in
317: .Xr nroff 1
318: style as opposed to
319: .Xr troff 1
320: style.
1.3 kristaps 321: If a conditional is false, its children are not processed, but are
322: syntactically interpreted to preserve the integrity of the input
323: document.
324: Thus,
325: .Pp
326: .D1 \&.if t \e .ig
327: .Pp
328: will discard the
329: .Sq \&.ig ,
330: which may lead to interesting results, but
331: .Pp
332: .D1 \&.if t \e .if t \e{\e
333: .Pp
334: will continue to syntactically interpret to the block close of the final
335: conditional.
336: Sub-conditionals, in this case, obviously inherit the truth value of
337: the parent.
338: This macro has the following syntax:
1.1 kristaps 339: .Pp
340: .Bd -literal -offset indent -compact
341: \&.if COND \e{\e
342: BODY...
343: \&.\e}
344: .Ed
345: .Bd -literal -offset indent -compact
346: \&.if COND \e{ BODY
1.2 kristaps 347: BODY... \e}
348: .Ed
349: .Bd -literal -offset indent -compact
350: \&.if COND \e{ BODY
1.1 kristaps 351: BODY...
352: \&.\e}
353: .Ed
354: .Bd -literal -offset indent -compact
355: \&.if COND \e
356: BODY
357: .Ed
358: .Pp
1.9 kristaps 359: COND is a conditional statement.
360: roff allows for complicated conditionals; mandoc is much simpler.
361: At this time, mandoc supports only
362: .Sq n ,
363: evaluating to true;
364: and
365: .Sq t ,
366: .Sq e ,
367: and
368: .Sq o ,
369: evaluating to false.
370: All other invocations are read up to the next end of line or space and
371: evaluate as false.
1.1 kristaps 372: .Pp
373: If the BODY section is begun by an escaped brace
374: .Sq \e{ ,
375: scope continues until a closing-brace macro
376: .Sq \.\e} .
377: If the BODY is not enclosed in braces, scope continues until the next
378: macro or word.
379: If the COND is followed by a BODY on the same line, whether after a
380: brace or not, then macros
381: .Em must
382: begin with a control character.
383: It is generally more intuitive, in this case, to write
384: .Bd -literal -offset indent
385: \&.if COND \e{\e
386: \&.foo
387: bar
388: \&.\e}
389: .Ed
390: .Pp
391: than having the macro follow as
392: .Pp
393: .D1 \&.if COND \e{ .foo
394: .Pp
395: The scope of a conditional is always parsed, but only executed if the
396: conditional evaluates to true.
397: .Pp
398: Note that text subsequent a
1.2 kristaps 399: .Sq \&.\e}
400: macro is discarded.
401: Furthermore, if an explicit closing sequence
1.1 kristaps 402: .Sq \e}
1.2 kristaps 403: is specified in a free-form line, the entire line is accepted within the
1.8 kristaps 404: scope of the prior macro, not only the text preceding the close, with the
405: .Sq \e}
406: collapsing into a zero-width space.
1.1 kristaps 407: .Ss \&ig
1.2 kristaps 408: Ignore input.
1.15 kristaps 409: Its syntax can be either
410: .Bd -literal -offset indent
411: .Pf . Cm \&ig
412: .Ar ignored text
1.2 kristaps 413: \&..
414: .Ed
1.15 kristaps 415: .Pp
416: or
417: .Bd -literal -offset indent
418: .Pf . Cm \&ig Ar end
419: .Ar ignored text
420: .Pf . Ar end
1.2 kristaps 421: .Ed
422: .Pp
423: In the first case, input is ignored until a
424: .Sq \&..
1.1 kristaps 425: macro is encountered on its own line.
1.15 kristaps 426: In the second case, input is ignored until the specified
427: .Sq Pf . Ar end
428: macro is encountered.
429: Do not use the escape character
1.2 kristaps 430: .Sq \e
1.15 kristaps 431: anywhere in the definition of
432: .Ar end ;
433: it would cause very strange behaviour.
434: .Pp
435: When the
436: .Ar end
437: macro is a roff request or a roff macro, like in
1.2 kristaps 438: .Pp
439: .D1 \&.ig if
440: .Pp
441: the subsequent invocation of
442: .Sx \&if
1.15 kristaps 443: will first terminate the
444: .Ar ignored text ,
445: then be invoked as usual.
446: Otherwise, it only terminates the
447: .Ar ignored text ,
448: and arguments following it or the
449: .Sq \&..
450: macro are discarded.
451: .Ss \&ne
452: Declare the need for the specified minimum vertical space
453: before the next trap or the bottom of the page.
454: This line-scoped request is currently ignored.
455: .Ss \&nh
456: Turn off automatic hyphenation mode.
457: This line-scoped request is currently ignored.
1.6 schwarze 458: .Ss \&rm
459: Remove a request, macro or string.
1.15 kristaps 460: This request is intended to have one argument,
1.6 schwarze 461: the name of the request, macro or string to be undefined.
462: Currently, it is ignored including its arguments,
463: and the number of arguments is not checked.
1.10 kristaps 464: .Ss \&nr
465: Define a register.
466: A register is an arbitrary string value that defines some sort of state,
467: which influences parsing and/or formatting.
468: Its syntax is as follows:
469: .Pp
1.15 kristaps 470: .D1 Pf \. Cm \&nr Ar name Ar value
1.10 kristaps 471: .Pp
472: The
1.15 kristaps 473: .Ar value
1.10 kristaps 474: may, at the moment, only be an integer.
475: The
1.15 kristaps 476: .Ar name
1.10 kristaps 477: is defined up to the next whitespace.
1.15 kristaps 478: So far, only the following register
479: .Ar name
480: is recognised:
1.10 kristaps 481: .Bl -tag -width Ds
482: .It Cm nS
483: If set to a positive integer value, certain
484: .Xr mdoc 7
1.11 kristaps 485: macros will behave as if they were defined in the
1.10 kristaps 486: .Em SYNOPSIS
1.11 kristaps 487: section.
1.10 kristaps 488: Otherwise, this behaviour is unset (even if called within the
489: .Em SYNOPSIS
490: section itself).
1.11 kristaps 491: Note that invoking a new
492: .Xr mdoc 7
493: section will unset this value.
1.10 kristaps 494: .El
1.15 kristaps 495: .Ss \&so
496: Include a source file.
497: Its syntax is as follows:
498: .Pp
499: .D1 Pf \. Cm \&so Ar file
500: .Pp
501: The
502: .Ar file
503: will be read and its contents processed as input in place of the
504: .Sq \&.so
505: request line.
506: To avoid inadvertant inclusion of unrelated files,
507: .Xr mandoc 1
508: only accepts relative paths not containing the strings
509: .Qq ../
510: and
511: .Qq /.. .
1.6 schwarze 512: .Ss \&tr
513: Output character translation.
1.7 schwarze 514: This macro is intended to have one argument,
1.6 schwarze 515: consisting of an even number of characters.
516: Currently, it is ignored including its arguments,
517: and the number of arguments is not checked.
1.2 kristaps 518: .Sh COMPATIBILITY
519: This section documents compatibility between mandoc and other other
520: troff implementations, at this time limited to GNU troff
521: .Pq Qq groff .
522: The term
523: .Qq historic groff
524: refers to groff versions before the
525: .Pa doc.tmac
526: file re-write
527: .Pq somewhere between 1.15 and 1.19 .
528: .Pp
529: .Bl -dash -compact
1.10 kristaps 530: .It
531: The
532: .Cm nS
533: request to
534: .Sx \&nr
535: is only compatible with OpenBSD's groff.
1.2 kristaps 536: .It
537: Historic groff did not accept white-space buffering the custom END tag
538: for the
539: .Sx \&ig
540: macro.
1.4 kristaps 541: .It
542: The
543: .Sx \&if
544: and family would print funny white-spaces with historic groff when
545: depending on next-line syntax.
1.2 kristaps 546: .El
1.1 kristaps 547: .Sh AUTHORS
1.15 kristaps 548: .An -nosplit
549: This partial
1.1 kristaps 550: .Nm
551: reference was written by
1.15 kristaps 552: .An Kristaps Dzonsons Aq kristaps@bsd.lv
553: and
554: .An Ingo Schwarze Aq schwarze@openbsd.org .
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