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