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