Annotation of mandoc/mandoc.3, Revision 1.2
1.2 ! kristaps 1: .\" $Id: mandoc.3,v 1.1 2011/03/22 10:02:50 kristaps Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4: .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
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.2 ! kristaps 18: .Dd $Mdocdate: March 22 2011 $
1.1 kristaps 19: .Dt MANDOC 3
20: .Os
21: .Sh NAME
22: .Nm mandoc ,
23: .Nm man_meta ,
24: .Nm man_node ,
25: .Nm mdoc_meta ,
26: .Nm mdoc_node ,
27: .Nm mparse_alloc ,
28: .Nm mparse_free ,
29: .Nm mparse_readfd ,
30: .Nm mparse_reset ,
1.2 ! kristaps 31: .Nm mparse_result ,
! 32: .Nm mparse_strerror ,
! 33: .Nm mparse_strlevel
1.1 kristaps 34: .Nd mandoc macro compiler library
35: .Sh SYNOPSIS
36: .In man.h
37: .In mdoc.h
38: .In mandoc.h
39: .Ft "const struct man_meta *"
40: .Fo man_meta
41: .Fa "const struct man *man"
42: .Fc
43: .Ft "const struct man_node *"
44: .Fo man_node
45: .Fa "const struct man *man"
46: .Fc
47: .Ft "const struct mdoc_meta *"
48: .Fo mdoc_meta
49: .Fa "const struct mdoc *mdoc"
50: .Fc
51: .Ft "const struct mdoc_node *"
52: .Fo mdoc_node
53: .Fa "const struct mdoc *mdoc"
54: .Fc
55: .Ft void
56: .Fo mparse_alloc
57: .Fa "enum mparset type"
58: .Fa "enum mandoclevel wlevel"
59: .Fa "mandocmsg msg"
60: .Fa "void *msgarg"
61: .Fc
62: .Ft void
63: .Fo mparse_free
64: .Fa "struct mparse *parse"
65: .Fc
66: .Ft "enum mandoclevel"
67: .Fo mparse_readfd
68: .Fa "struct mparse *parse"
69: .Fa "int fd"
70: .Fa "const char *fname"
71: .Fc
72: .Ft void
73: .Fo mparse_reset
74: .Fa "struct mparse *parse"
75: .Fc
76: .Ft void
77: .Fo mparse_result
78: .Fa "struct mparse *parse"
79: .Fa "struct mdoc **mdoc"
80: .Fa "struct man **man"
1.2 ! kristaps 81: .Fc
! 82: .Ft "const char *"
! 83: .Fo mparse_strerror
! 84: .Fa "enum mandocerr"
! 85: .Fc
! 86: .Ft "const char *"
! 87: .Fo mparse_strlevel
! 88: .Fa "enum mandoclevel"
1.1 kristaps 89: .Fc
90: .Vt extern const char * const * man_macronames;
91: .Vt extern const char * const * mdoc_argnames;
92: .Vt extern const char * const * mdoc_macronames;
93: .Sh DESCRIPTION
94: The
95: .Nm mandoc
96: library parses a
97: .Ux
98: manual into an abstract syntax tree (AST).
99: .Ux
100: manuals are composed of
101: .Xr mdoc 7
102: or
103: .Xr man 7 ,
104: and may be mixed with
105: .Xr roff 7 ,
106: .Xr tbl 7 ,
107: and
108: .Xr eqn 7
109: invocations.
110: .Pp
111: The following describes a general parse sequence:
112: .Bl -enum
113: .It
114: initiate a parsing sequence with
115: .Fn mparse_alloc ;
116: .It
117: parse files or file descriptors with
118: .Fn mparse_readfd ;
119: .It
120: retrieve a parsed syntax tree, if the parse was successful, with
121: .Fn mparse_result ;
122: .It
123: iterate over parse nodes with
124: .Fn mdoc_node
125: or
126: .Fn man_node ;
127: .It
128: free all allocated memory with
129: .Fn mparse_free ,
130: or invoke
131: .Fn mparse_reset
132: and parse new files.
133: .El
134: .Sh IMPLEMENTATION NOTES
135: This section consists of structural documentation for
136: .Xr mdoc 7
137: and
138: .Xr man 7
139: syntax trees.
140: .Ss Man Abstract Syntax Tree
141: This AST is governed by the ontological rules dictated in
142: .Xr man 7
143: and derives its terminology accordingly.
144: .Pp
145: The AST is composed of
146: .Vt struct man_node
147: nodes with element, root and text types as declared by the
148: .Va type
149: field.
150: Each node also provides its parse point (the
151: .Va line ,
152: .Va sec ,
153: and
154: .Va pos
155: fields), its position in the tree (the
156: .Va parent ,
157: .Va child ,
158: .Va next
159: and
160: .Va prev
161: fields) and some type-specific data.
162: .Pp
163: The tree itself is arranged according to the following normal form,
164: where capitalised non-terminals represent nodes.
165: .Pp
166: .Bl -tag -width "ELEMENTXX" -compact
167: .It ROOT
168: \(<- mnode+
169: .It mnode
170: \(<- ELEMENT | TEXT | BLOCK
171: .It BLOCK
172: \(<- HEAD BODY
173: .It HEAD
174: \(<- mnode*
175: .It BODY
176: \(<- mnode*
177: .It ELEMENT
178: \(<- ELEMENT | TEXT*
179: .It TEXT
180: \(<- [[:alpha:]]*
181: .El
182: .Pp
183: The only elements capable of nesting other elements are those with
184: next-lint scope as documented in
185: .Xr man 7 .
186: .Ss Mdoc Abstract Syntax Tree
187: This AST is governed by the ontological
188: rules dictated in
189: .Xr mdoc 7
190: and derives its terminology accordingly.
191: .Qq In-line
192: elements described in
193: .Xr mdoc 7
194: are described simply as
195: .Qq elements .
196: .Pp
197: The AST is composed of
198: .Vt struct mdoc_node
199: nodes with block, head, body, element, root and text types as declared
200: by the
201: .Va type
202: field.
203: Each node also provides its parse point (the
204: .Va line ,
205: .Va sec ,
206: and
207: .Va pos
208: fields), its position in the tree (the
209: .Va parent ,
210: .Va child ,
211: .Va nchild ,
212: .Va next
213: and
214: .Va prev
215: fields) and some type-specific data, in particular, for nodes generated
216: from macros, the generating macro in the
217: .Va tok
218: field.
219: .Pp
220: The tree itself is arranged according to the following normal form,
221: where capitalised non-terminals represent nodes.
222: .Pp
223: .Bl -tag -width "ELEMENTXX" -compact
224: .It ROOT
225: \(<- mnode+
226: .It mnode
227: \(<- BLOCK | ELEMENT | TEXT
228: .It BLOCK
229: \(<- HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]]
230: .It ELEMENT
231: \(<- TEXT*
232: .It HEAD
233: \(<- mnode*
234: .It BODY
235: \(<- mnode* [ENDBODY mnode*]
236: .It TAIL
237: \(<- mnode*
238: .It TEXT
239: \(<- [[:printable:],0x1e]*
240: .El
241: .Pp
242: Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
243: the BLOCK production: these refer to punctuation marks.
244: Furthermore, although a TEXT node will generally have a non-zero-length
245: string, in the specific case of
246: .Sq \&.Bd \-literal ,
247: an empty line will produce a zero-length string.
248: Multiple body parts are only found in invocations of
249: .Sq \&Bl \-column ,
250: where a new body introduces a new phrase.
251: .Pp
252: The
253: .Xr mdoc 7
254: syntax tree accomodates for broken block structures as well.
255: The ENDBODY node is available to end the formatting associated
256: with a given block before the physical end of that block.
257: It has a non-null
258: .Va end
259: field, is of the BODY
260: .Va type ,
261: has the same
262: .Va tok
263: as the BLOCK it is ending, and has a
264: .Va pending
265: field pointing to that BLOCK's BODY node.
266: It is an indirect child of that BODY node
267: and has no children of its own.
268: .Pp
269: An ENDBODY node is generated when a block ends while one of its child
270: blocks is still open, like in the following example:
271: .Bd -literal -offset indent
272: \&.Ao ao
273: \&.Bo bo ac
274: \&.Ac bc
275: \&.Bc end
276: .Ed
277: .Pp
278: This example results in the following block structure:
279: .Bd -literal -offset indent
280: BLOCK Ao
281: HEAD Ao
282: BODY Ao
283: TEXT ao
284: BLOCK Bo, pending -> Ao
285: HEAD Bo
286: BODY Bo
287: TEXT bo
288: TEXT ac
289: ENDBODY Ao, pending -> Ao
290: TEXT bc
291: TEXT end
292: .Ed
293: .Pp
294: Here, the formatting of the
295: .Sq \&Ao
296: block extends from TEXT ao to TEXT ac,
297: while the formatting of the
298: .Sq \&Bo
299: block extends from TEXT bo to TEXT bc.
300: It renders as follows in
301: .Fl T Ns Cm ascii
302: mode:
303: .Pp
304: .Dl <ao [bo ac> bc] end
305: .Pp
306: Support for badly-nested blocks is only provided for backward
307: compatibility with some older
308: .Xr mdoc 7
309: implementations.
310: Using badly-nested blocks is
311: .Em strongly discouraged ;
312: for example, the
313: .Fl T Ns Cm html
314: and
315: .Fl T Ns Cm xhtml
316: front-ends to
317: .Xr mandoc 1
318: are unable to render them in any meaningful way.
319: Furthermore, behaviour when encountering badly-nested blocks is not
320: consistent across troff implementations, especially when using multiple
321: levels of badly-nested blocks.
322: .Sh SEE ALSO
323: .Xr mandoc 1 ,
324: .Xr eqn 7 ,
325: .Xr man 7 ,
326: .Xr mdoc 7 ,
327: .Xr roff 7 ,
328: .Xr tbl 7
329: .Sh AUTHORS
330: The
331: .Nm
332: library was written by
333: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mandoc.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc