Annotation of mandoc/roff.7, Revision 1.3
1.3 ! kristaps 1: .\" $Id: roff.7,v 1.2 2010/05/16 22:28:33 kristaps Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16: .\"
1.2 kristaps 17: .Dd $Mdocdate: May 16 2010 $
1.1 kristaps 18: .Dt ROFF 7
19: .Os
20: .Sh NAME
21: .Nm roff
22: .Nd roff language reference
23: .Sh DESCRIPTION
24: The
25: .Nm roff
26: language is a general-purpose text-formatting language. The purpose of
27: this document is to consistently describe those language constructs
28: accepted by the
29: .Xr mandoc 1
30: utility. It is a work in progress.
31: .Pp
32: An
33: .Nm
34: document follows simple rules: lines beginning with the control
35: characters
36: .Sq \.
37: or
38: .Sq \(aq
39: are parsed for macros. Other lines are interpreted within the scope of
40: prior macros:
41: .Bd -literal -offset indent
42: \&.xx Macro lines change control state.
43: Other lines are interpreted within the current state.
44: .Ed
45: .Sh LANGUAGE SYNTAX
46: .Nm
47: documents may contain only graphable 7-bit ASCII characters, the space
48: character, and, in certain circumstances, the tab character. All
49: manuals must have
50: .Ux
51: line terminators.
52: .Sh MACRO SYNTAX
53: Macros are arbitrary in length and begin with a control character ,
54: .Sq \.
55: or
56: .Sq \(aq ,
57: at the beginning of the line.
58: An arbitrary amount of whitespace may sit between the control character
59: and the macro name.
60: Thus, the following are equivalent:
61: .Bd -literal -offset indent
62: \&.if
63: \&.\ \ \ \&if
64: .Ed
65: .Sh REFERENCE
66: This section is a canonical reference of all macros, arranged
67: alphabetically.
1.3 ! kristaps 68: .Ss \&am
! 69: The syntax of this macro is the same as that of
! 70: .Sx \&ig ,
! 71: except that a leading argument must be specified.
! 72: It is ignored, as are its children.
! 73: .Ss \&ami
! 74: The syntax of this macro is the same as that of
! 75: .Sx \&ig ,
! 76: except that a leading argument must be specified.
! 77: It is ignored, as are its children.
! 78: .Ss \&am1
! 79: The syntax of this macro is the same as that of
! 80: .Sx \&ig ,
! 81: except that a leading argument must be specified.
! 82: It is ignored, as are its children.
! 83: .Ss \&de
! 84: The syntax of this macro is the same as that of
! 85: .Sx \&ig ,
! 86: except that a leading argument must be specified.
! 87: It is ignored, as are its children.
! 88: .Ss \&dei
! 89: The syntax of this macro is the same as that of
! 90: .Sx \&ig ,
! 91: except that a leading argument must be specified.
! 92: It is ignored, as are its children.
! 93: .Ss \&de1
! 94: The syntax of this macro is the same as that of
! 95: .Sx \&ig ,
! 96: except that a leading argument must be specified.
! 97: It is ignored, as are its children.
1.1 kristaps 98: .Ss \&if
1.3 ! kristaps 99: Begins a conditional that always evaluates to false.
! 100: If a conditional is false, its children are not processed, but are
! 101: syntactically interpreted to preserve the integrity of the input
! 102: document.
! 103: Thus,
! 104: .Pp
! 105: .D1 \&.if t \e .ig
! 106: .Pp
! 107: will discard the
! 108: .Sq \&.ig ,
! 109: which may lead to interesting results, but
! 110: .Pp
! 111: .D1 \&.if t \e .if t \e{\e
! 112: .Pp
! 113: will continue to syntactically interpret to the block close of the final
! 114: conditional.
! 115: Sub-conditionals, in this case, obviously inherit the truth value of
! 116: the parent.
! 117: This macro has the following syntax:
1.1 kristaps 118: .Pp
119: .Bd -literal -offset indent -compact
120: \&.if COND \e{\e
121: BODY...
122: \&.\e}
123: .Ed
124: .Bd -literal -offset indent -compact
125: \&.if COND \e{ BODY
1.2 kristaps 126: BODY... \e}
127: .Ed
128: .Bd -literal -offset indent -compact
129: \&.if COND \e{ BODY
1.1 kristaps 130: BODY...
131: \&.\e}
132: .Ed
133: .Bd -literal -offset indent -compact
134: \&.if COND \e
135: BODY
136: .Ed
137: .Pp
1.3 ! kristaps 138: COND is a conditional (for the time being, this always evaluates to
! 139: false).
1.1 kristaps 140: .Pp
141: If the BODY section is begun by an escaped brace
142: .Sq \e{ ,
143: scope continues until a closing-brace macro
144: .Sq \.\e} .
145: If the BODY is not enclosed in braces, scope continues until the next
146: macro or word.
147: If the COND is followed by a BODY on the same line, whether after a
148: brace or not, then macros
149: .Em must
150: begin with a control character.
151: It is generally more intuitive, in this case, to write
152: .Bd -literal -offset indent
153: \&.if COND \e{\e
154: \&.foo
155: bar
156: \&.\e}
157: .Ed
158: .Pp
159: than having the macro follow as
160: .Pp
161: .D1 \&.if COND \e{ .foo
162: .Pp
163: The scope of a conditional is always parsed, but only executed if the
164: conditional evaluates to true.
165: .Pp
166: Note that text subsequent a
1.2 kristaps 167: .Sq \&.\e}
168: macro is discarded.
169: Furthermore, if an explicit closing sequence
1.1 kristaps 170: .Sq \e}
1.2 kristaps 171: is specified in a free-form line, the entire line is accepted within the
172: scope of the prior macro, not only the text preceding the close.
1.1 kristaps 173: .Ss \&ig
1.2 kristaps 174: Ignore input.
175: Accepts the following syntax:
176: .Pp
177: .Bd -literal -offset indent -compact
178: \&.ig
179: BODY...
180: \&..
181: .Ed
182: .Bd -literal -offset indent -compact
183: \&.ig END
184: BODY...
185: \&.END
186: .Ed
187: .Pp
188: In the first case, input is ignored until a
189: .Sq \&..
1.1 kristaps 190: macro is encountered on its own line.
1.2 kristaps 191: In the second case, input is ignored until a
192: .Sq \&.END
193: is encountered.
194: Text subsequent the
195: .Sq \&.END
196: or
197: .Sq \&..
1.1 kristaps 198: is discarded.
1.2 kristaps 199: .Pp
200: Do not use the escape
201: .Sq \e
202: anywhere in the definition of END.
203: It causes very strange behaviour.
204: Furthermore, if you redefine a
205: .Nm
206: macro, such as
207: .Pp
208: .D1 \&.ig if
209: .Pp
210: the subsequent invocation of
211: .Sx \&if
212: will first signify the end of comment, then be invoked as a macro.
213: This behaviour really shouldn't be counted upon.
214: .Sh COMPATIBILITY
215: This section documents compatibility between mandoc and other other
216: troff implementations, at this time limited to GNU troff
217: .Pq Qq groff .
218: The term
219: .Qq historic groff
220: refers to groff versions before the
221: .Pa doc.tmac
222: file re-write
223: .Pq somewhere between 1.15 and 1.19 .
224: .Pp
225: .Bl -dash -compact
226: .It
227: Historic groff did not accept white-space buffering the custom END tag
228: for the
229: .Sx \&ig
230: macro.
231: .El
1.1 kristaps 232: .Sh AUTHORS
233: The
234: .Nm
235: reference was written by
236: .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