Annotation of mandoc/roff.7, Revision 1.15
1.15 ! kristaps 1: .\" $Id: roff.7,v 1.14 2010/07/27 13:16:00 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.15 ! kristaps 18: .Dd $Mdocdate: July 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
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.3 kristaps 199: .Ss \&dei
1.15 ! kristaps 200: Define a user-defined
! 201: .Nm
! 202: macro, specifying the macro name indirectly.
1.3 kristaps 203: The syntax of this macro is the same as that of
1.15 ! kristaps 204: .Sx \&de .
! 205: It is currently ignored by
! 206: .Xr mandoc 1 ,
! 207: as are its children.
! 208: .Ss \&de1
! 209: Define a user-defined
! 210: .Nm
! 211: macro that will be executed with
! 212: .Nm
! 213: compatibility mode switched off during macro execution.
! 214: This is a GNU extension not available in traditional
! 215: .Nm
! 216: implementations and not even in older versions of groff.
! 217: Since
! 218: .Xr mandoc 1
! 219: does not implement
! 220: .Nm
! 221: compatibility mode at all, it handles this macro as an alias for
! 222: .Sx \&de .
1.6 schwarze 223: .Ss \&ds
1.15 ! kristaps 224: Define a user-defined string.
1.13 kristaps 225: Its syntax is as follows:
226: .Pp
1.15 ! kristaps 227: .D1 Pf . Cm \&ds Ar name Oo \(dq Oc Ns Ar string
1.13 kristaps 228: .Pp
229: The
1.15 ! kristaps 230: .Ar name
1.13 kristaps 231: and
1.15 ! kristaps 232: .Ar string
! 233: arguments are space-separated.
! 234: If the
! 235: .Ar string
! 236: begins with a double-quote character, that character will not be part
! 237: of the string.
! 238: All remaining characters on the input line form the
! 239: .Ar string ,
! 240: including whitespace and double-quote characters, even trailing ones.
! 241: .Pp
1.13 kristaps 242: The
1.15 ! kristaps 243: .Ar string
! 244: can be interpolated into subsequent text by using
! 245: .No \e* Ns Bq Ar name
! 246: for a
! 247: .Ar name
! 248: of arbitrary length, or \e*(NN or \e*N if the length of
! 249: .Ar name
! 250: is two or one characters, respectively.
! 251: .Pp
! 252: Since user-defined strings and macros share a common string table,
! 253: defining a string
! 254: .Ar name
! 255: clobbers the user-defined macro
! 256: .Ar name ,
! 257: and the
! 258: .Ar name
! 259: used for defining a string can also be invoked as a macro,
! 260: in which case the following input line will be appended to the
! 261: .Ar string ,
! 262: forming a new input line passed to the
! 263: .Nm
! 264: parser.
! 265: For example,
! 266: .Bd -literal -offset indent
! 267: \&.ds badidea .S
! 268: \&.badidea
! 269: H SYNOPSIS
! 270: .Ed
! 271: .Pp
! 272: invokes the
! 273: .Cm SH
! 274: macro when used in a
! 275: .Xr man 7
! 276: document.
! 277: Such abuse is of course strongly discouraged.
1.5 kristaps 278: .Ss \&el
279: The
280: .Qq else
281: half of an if/else conditional.
282: Pops a result off the stack of conditional evaluations pushed by
283: .Sx \&ie
284: and uses it as its conditional.
285: If no stack entries are present (e.g., due to no prior
286: .Sx \&ie
287: calls)
288: then false is assumed.
289: The syntax of this macro is similar to
290: .Sx \&if
291: except that the conditional is missing.
1.15 ! kristaps 292: .Ss \&hy
! 293: Set automatic hyphenation mode.
! 294: This line-scoped request is currently ignored.
1.5 kristaps 295: .Ss \&ie
296: The
297: .Qq if
298: half of an if/else conditional.
299: The result of the conditional is pushed into a stack used by subsequent
300: invocations of
301: .Sx \&el ,
302: which may be separated by any intervening input (or not exist at all).
303: Its syntax is equivalent to
304: .Sx \&if .
1.1 kristaps 305: .Ss \&if
1.7 schwarze 306: Begins a conditional.
307: Right now, the conditional evaluates to true
308: if and only if it starts with the letter
309: .Sy n ,
310: indicating processing in
311: .Xr nroff 1
312: style as opposed to
313: .Xr troff 1
314: style.
1.3 kristaps 315: If a conditional is false, its children are not processed, but are
316: syntactically interpreted to preserve the integrity of the input
317: document.
318: Thus,
319: .Pp
320: .D1 \&.if t \e .ig
321: .Pp
322: will discard the
323: .Sq \&.ig ,
324: which may lead to interesting results, but
325: .Pp
326: .D1 \&.if t \e .if t \e{\e
327: .Pp
328: will continue to syntactically interpret to the block close of the final
329: conditional.
330: Sub-conditionals, in this case, obviously inherit the truth value of
331: the parent.
332: This macro has the following syntax:
1.1 kristaps 333: .Pp
334: .Bd -literal -offset indent -compact
335: \&.if COND \e{\e
336: BODY...
337: \&.\e}
338: .Ed
339: .Bd -literal -offset indent -compact
340: \&.if COND \e{ BODY
1.2 kristaps 341: BODY... \e}
342: .Ed
343: .Bd -literal -offset indent -compact
344: \&.if COND \e{ BODY
1.1 kristaps 345: BODY...
346: \&.\e}
347: .Ed
348: .Bd -literal -offset indent -compact
349: \&.if COND \e
350: BODY
351: .Ed
352: .Pp
1.9 kristaps 353: COND is a conditional statement.
354: roff allows for complicated conditionals; mandoc is much simpler.
355: At this time, mandoc supports only
356: .Sq n ,
357: evaluating to true;
358: and
359: .Sq t ,
360: .Sq e ,
361: and
362: .Sq o ,
363: evaluating to false.
364: All other invocations are read up to the next end of line or space and
365: evaluate as false.
1.1 kristaps 366: .Pp
367: If the BODY section is begun by an escaped brace
368: .Sq \e{ ,
369: scope continues until a closing-brace macro
370: .Sq \.\e} .
371: If the BODY is not enclosed in braces, scope continues until the next
372: macro or word.
373: If the COND is followed by a BODY on the same line, whether after a
374: brace or not, then macros
375: .Em must
376: begin with a control character.
377: It is generally more intuitive, in this case, to write
378: .Bd -literal -offset indent
379: \&.if COND \e{\e
380: \&.foo
381: bar
382: \&.\e}
383: .Ed
384: .Pp
385: than having the macro follow as
386: .Pp
387: .D1 \&.if COND \e{ .foo
388: .Pp
389: The scope of a conditional is always parsed, but only executed if the
390: conditional evaluates to true.
391: .Pp
392: Note that text subsequent a
1.2 kristaps 393: .Sq \&.\e}
394: macro is discarded.
395: Furthermore, if an explicit closing sequence
1.1 kristaps 396: .Sq \e}
1.2 kristaps 397: is specified in a free-form line, the entire line is accepted within the
1.8 kristaps 398: scope of the prior macro, not only the text preceding the close, with the
399: .Sq \e}
400: collapsing into a zero-width space.
1.1 kristaps 401: .Ss \&ig
1.2 kristaps 402: Ignore input.
1.15 ! kristaps 403: Its syntax can be either
! 404: .Bd -literal -offset indent
! 405: .Pf . Cm \&ig
! 406: .Ar ignored text
1.2 kristaps 407: \&..
408: .Ed
1.15 ! kristaps 409: .Pp
! 410: or
! 411: .Bd -literal -offset indent
! 412: .Pf . Cm \&ig Ar end
! 413: .Ar ignored text
! 414: .Pf . Ar end
1.2 kristaps 415: .Ed
416: .Pp
417: In the first case, input is ignored until a
418: .Sq \&..
1.1 kristaps 419: macro is encountered on its own line.
1.15 ! kristaps 420: In the second case, input is ignored until the specified
! 421: .Sq Pf . Ar end
! 422: macro is encountered.
! 423: Do not use the escape character
1.2 kristaps 424: .Sq \e
1.15 ! kristaps 425: anywhere in the definition of
! 426: .Ar end ;
! 427: it would cause very strange behaviour.
! 428: .Pp
! 429: When the
! 430: .Ar end
! 431: macro is a roff request or a roff macro, like in
1.2 kristaps 432: .Pp
433: .D1 \&.ig if
434: .Pp
435: the subsequent invocation of
436: .Sx \&if
1.15 ! kristaps 437: will first terminate the
! 438: .Ar ignored text ,
! 439: then be invoked as usual.
! 440: Otherwise, it only terminates the
! 441: .Ar ignored text ,
! 442: and arguments following it or the
! 443: .Sq \&..
! 444: macro are discarded.
! 445: .Ss \&ne
! 446: Declare the need for the specified minimum vertical space
! 447: before the next trap or the bottom of the page.
! 448: This line-scoped request is currently ignored.
! 449: .Ss \&nh
! 450: Turn off automatic hyphenation mode.
! 451: This line-scoped request is currently ignored.
1.6 schwarze 452: .Ss \&rm
453: Remove a request, macro or string.
1.15 ! kristaps 454: This request is intended to have one argument,
1.6 schwarze 455: the name of the request, macro or string to be undefined.
456: Currently, it is ignored including its arguments,
457: and the number of arguments is not checked.
1.10 kristaps 458: .Ss \&nr
459: Define a register.
460: A register is an arbitrary string value that defines some sort of state,
461: which influences parsing and/or formatting.
462: Its syntax is as follows:
463: .Pp
1.15 ! kristaps 464: .D1 Pf \. Cm \&nr Ar name Ar value
1.10 kristaps 465: .Pp
466: The
1.15 ! kristaps 467: .Ar value
1.10 kristaps 468: may, at the moment, only be an integer.
469: The
1.15 ! kristaps 470: .Ar name
1.10 kristaps 471: is defined up to the next whitespace.
1.15 ! kristaps 472: So far, only the following register
! 473: .Ar name
! 474: is recognised:
1.10 kristaps 475: .Bl -tag -width Ds
476: .It Cm nS
477: If set to a positive integer value, certain
478: .Xr mdoc 7
1.11 kristaps 479: macros will behave as if they were defined in the
1.10 kristaps 480: .Em SYNOPSIS
1.11 kristaps 481: section.
1.10 kristaps 482: Otherwise, this behaviour is unset (even if called within the
483: .Em SYNOPSIS
484: section itself).
1.11 kristaps 485: Note that invoking a new
486: .Xr mdoc 7
487: section will unset this value.
1.10 kristaps 488: .El
1.15 ! kristaps 489: .Ss \&so
! 490: Include a source file.
! 491: Its syntax is as follows:
! 492: .Pp
! 493: .D1 Pf \. Cm \&so Ar file
! 494: .Pp
! 495: The
! 496: .Ar file
! 497: will be read and its contents processed as input in place of the
! 498: .Sq \&.so
! 499: request line.
! 500: To avoid inadvertant inclusion of unrelated files,
! 501: .Xr mandoc 1
! 502: only accepts relative paths not containing the strings
! 503: .Qq ../
! 504: and
! 505: .Qq /.. .
1.6 schwarze 506: .Ss \&tr
507: Output character translation.
1.7 schwarze 508: This macro is intended to have one argument,
1.6 schwarze 509: consisting of an even number of characters.
510: Currently, it is ignored including its arguments,
511: and the number of arguments is not checked.
1.2 kristaps 512: .Sh COMPATIBILITY
513: This section documents compatibility between mandoc and other other
514: troff implementations, at this time limited to GNU troff
515: .Pq Qq groff .
516: The term
517: .Qq historic groff
518: refers to groff versions before the
519: .Pa doc.tmac
520: file re-write
521: .Pq somewhere between 1.15 and 1.19 .
522: .Pp
523: .Bl -dash -compact
1.10 kristaps 524: .It
525: The
526: .Cm nS
527: request to
528: .Sx \&nr
529: is only compatible with OpenBSD's groff.
1.2 kristaps 530: .It
531: Historic groff did not accept white-space buffering the custom END tag
532: for the
533: .Sx \&ig
534: macro.
1.4 kristaps 535: .It
536: The
537: .Sx \&if
538: and family would print funny white-spaces with historic groff when
539: depending on next-line syntax.
1.2 kristaps 540: .El
1.1 kristaps 541: .Sh AUTHORS
1.15 ! kristaps 542: .An -nosplit
! 543: This partial
1.1 kristaps 544: .Nm
545: reference was written by
1.15 ! kristaps 546: .An Kristaps Dzonsons Aq kristaps@bsd.lv
! 547: and
! 548: .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