Annotation of mandoc/mandoc.3, Revision 1.16
1.16 ! kristaps 1: .\" $Id: mandoc.3,v 1.15 2011/10/18 13:25:38 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.16 ! kristaps 18: .Dd $Mdocdate: October 18 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 ,
1.14 kristaps 25: .Nm man_mparse ,
1.1 kristaps 26: .Nm man_node ,
1.6 kristaps 27: .Nm mchars_alloc ,
28: .Nm mchars_free ,
29: .Nm mchars_num2char ,
1.7 kristaps 30: .Nm mchars_num2uc ,
1.6 kristaps 31: .Nm mchars_spec2cp ,
32: .Nm mchars_spec2str ,
1.1 kristaps 33: .Nm mdoc_meta ,
34: .Nm mdoc_node ,
35: .Nm mparse_alloc ,
36: .Nm mparse_free ,
1.14 kristaps 37: .Nm mparse_getkeep ,
38: .Nm mparse_keep ,
1.1 kristaps 39: .Nm mparse_readfd ,
40: .Nm mparse_reset ,
1.2 kristaps 41: .Nm mparse_result ,
42: .Nm mparse_strerror ,
43: .Nm mparse_strlevel
1.1 kristaps 44: .Nd mandoc macro compiler library
1.8 kristaps 45: .Sh LIBRARY
46: .Lb mandoc
1.1 kristaps 47: .Sh SYNOPSIS
48: .In man.h
49: .In mdoc.h
50: .In mandoc.h
1.3 kristaps 51: .Ft "enum mandoc_esc"
52: .Fo mandoc_escape
1.15 kristaps 53: .Fa "const char **end"
54: .Fa "const char **start"
55: .Fa "int *sz"
1.3 kristaps 56: .Fc
1.1 kristaps 57: .Ft "const struct man_meta *"
58: .Fo man_meta
59: .Fa "const struct man *man"
60: .Fc
1.14 kristaps 61: .Ft "const struct mparse *"
62: .Fo man_mparse
63: .Fa "const struct man *man"
64: .Fc
1.1 kristaps 65: .Ft "const struct man_node *"
66: .Fo man_node
67: .Fa "const struct man *man"
68: .Fc
1.6 kristaps 69: .Ft "struct mchars *"
70: .Fn mchars_alloc
71: .Ft void
72: .Fn mchars_free "struct mchars *p"
73: .Ft char
74: .Fn mchars_num2char "const char *cp" "size_t sz"
1.7 kristaps 75: .Ft int
76: .Fn mchars_num2uc "const char *cp" "size_t sz"
1.6 kristaps 77: .Ft "const char *"
78: .Fo mchars_spec2str
1.16 ! kristaps 79: .Fa "const struct mchars *p"
1.6 kristaps 80: .Fa "const char *cp"
81: .Fa "size_t sz"
82: .Fa "size_t *rsz"
83: .Fc
84: .Ft int
85: .Fo mchars_spec2cp
1.16 ! kristaps 86: .Fa "const struct mchars *p"
1.6 kristaps 87: .Fa "const char *cp"
88: .Fa "size_t sz"
89: .Ft "const char *"
90: .Fc
1.1 kristaps 91: .Ft "const struct mdoc_meta *"
92: .Fo mdoc_meta
93: .Fa "const struct mdoc *mdoc"
94: .Fc
95: .Ft "const struct mdoc_node *"
96: .Fo mdoc_node
97: .Fa "const struct mdoc *mdoc"
98: .Fc
99: .Ft void
100: .Fo mparse_alloc
101: .Fa "enum mparset type"
102: .Fa "enum mandoclevel wlevel"
103: .Fa "mandocmsg msg"
104: .Fa "void *msgarg"
105: .Fc
106: .Ft void
107: .Fo mparse_free
108: .Fa "struct mparse *parse"
109: .Fc
1.14 kristaps 110: .Ft void
111: .Fo mparse_getkeep
112: .Fa "const struct mparse *parse"
113: .Fc
114: .Ft void
115: .Fo mparse_keep
116: .Fa "struct mparse *parse"
117: .Fc
1.1 kristaps 118: .Ft "enum mandoclevel"
119: .Fo mparse_readfd
120: .Fa "struct mparse *parse"
121: .Fa "int fd"
122: .Fa "const char *fname"
123: .Fc
124: .Ft void
125: .Fo mparse_reset
126: .Fa "struct mparse *parse"
127: .Fc
128: .Ft void
129: .Fo mparse_result
130: .Fa "struct mparse *parse"
131: .Fa "struct mdoc **mdoc"
132: .Fa "struct man **man"
1.2 kristaps 133: .Fc
134: .Ft "const char *"
135: .Fo mparse_strerror
136: .Fa "enum mandocerr"
137: .Fc
138: .Ft "const char *"
139: .Fo mparse_strlevel
140: .Fa "enum mandoclevel"
1.1 kristaps 141: .Fc
142: .Vt extern const char * const * man_macronames;
143: .Vt extern const char * const * mdoc_argnames;
144: .Vt extern const char * const * mdoc_macronames;
1.4 kristaps 145: .Fd "#define ASCII_NBRSP"
146: .Fd "#define ASCII_HYPH"
1.1 kristaps 147: .Sh DESCRIPTION
148: The
149: .Nm mandoc
150: library parses a
151: .Ux
152: manual into an abstract syntax tree (AST).
153: .Ux
154: manuals are composed of
155: .Xr mdoc 7
156: or
157: .Xr man 7 ,
158: and may be mixed with
159: .Xr roff 7 ,
160: .Xr tbl 7 ,
161: and
162: .Xr eqn 7
163: invocations.
164: .Pp
165: The following describes a general parse sequence:
166: .Bl -enum
167: .It
168: initiate a parsing sequence with
169: .Fn mparse_alloc ;
170: .It
171: parse files or file descriptors with
172: .Fn mparse_readfd ;
173: .It
174: retrieve a parsed syntax tree, if the parse was successful, with
175: .Fn mparse_result ;
176: .It
177: iterate over parse nodes with
178: .Fn mdoc_node
179: or
180: .Fn man_node ;
181: .It
182: free all allocated memory with
183: .Fn mparse_free ,
184: or invoke
185: .Fn mparse_reset
186: and parse new files.
1.3 kristaps 187: .El
1.6 kristaps 188: .Pp
189: The
190: .Nm
191: library also contains routines for translating character strings into glyphs
192: .Pq see Fn mchars_alloc
193: and parsing escape sequences from strings
194: .Pq see Fn mandoc_escape .
1.3 kristaps 195: .Sh REFERENCE
196: This section documents the functions, types, and variables available
197: via
198: .In mandoc.h .
199: .Ss Types
200: .Bl -ohang
201: .It Vt "enum mandoc_esc"
1.11 kristaps 202: An escape sequence classification.
1.3 kristaps 203: .It Vt "enum mandocerr"
1.11 kristaps 204: A fatal error, error, or warning message during parsing.
1.3 kristaps 205: .It Vt "enum mandoclevel"
1.11 kristaps 206: A classification of an
207: .Vt "enum mandoclevel"
208: as regards system operation.
1.6 kristaps 209: .It Vt "struct mchars"
210: An opaque pointer to an object allowing for translation between
211: character strings and glyphs.
212: See
213: .Fn mchars_alloc .
1.3 kristaps 214: .It Vt "enum mparset"
1.11 kristaps 215: The type of parser when reading input.
216: This should usually be
1.12 kristaps 217: .Dv MPARSE_AUTO
1.11 kristaps 218: for auto-detection.
1.3 kristaps 219: .It Vt "struct mparse"
1.11 kristaps 220: An opaque pointer to a running parse sequence.
221: Created with
222: .Fn mparse_alloc
223: and freed with
224: .Fn mparse_free .
225: This may be used across parsed input if
226: .Fn mparse_reset
227: is called between parses.
1.3 kristaps 228: .It Vt "mandocmsg"
1.11 kristaps 229: A prototype for a function to handle fatal error, error, and warning
230: messages emitted by the parser.
1.3 kristaps 231: .El
232: .Ss Functions
233: .Bl -ohang
234: .It Fn mandoc_escape
1.4 kristaps 235: Scan an escape sequence, i.e., a character string beginning with
236: .Sq \e .
237: Pass a pointer to this string as
238: .Va end ;
239: it will be set to the supremum of the parsed escape sequence unless
1.12 kristaps 240: returning
241: .Dv ESCAPE_ERROR ,
242: in which case the string is bogus and should be
1.4 kristaps 243: thrown away.
1.12 kristaps 244: If not
245: .Dv ESCAPE_ERROR
246: or
247: .Dv ESCAPE_IGNORE ,
1.4 kristaps 248: .Va start
249: is set to the first relevant character of the substring (font, glyph,
250: whatever) of length
251: .Va sz .
252: Both
253: .Va start
254: and
255: .Va sz
1.12 kristaps 256: may be
257: .Dv NULL .
1.3 kristaps 258: .It Fn man_meta
1.4 kristaps 259: Obtain the meta-data of a successful parse.
260: This may only be used on a pointer returned by
261: .Fn mparse_result .
1.14 kristaps 262: .It Fn man_mparse
263: Get the parser used for the current output.
1.3 kristaps 264: .It Fn man_node
1.4 kristaps 265: Obtain the root node of a successful parse.
266: This may only be used on a pointer returned by
267: .Fn mparse_result .
1.6 kristaps 268: .It Fn mchars_alloc
269: Allocate an
270: .Vt "struct mchars *"
271: object for translating special characters into glyphs.
272: See
273: .Xr mandoc_char 7
274: for an overview of special characters.
275: The object must be freed with
276: .Fn mchars_free .
277: .It Fn mchars_free
278: Free an object created with
279: .Fn mchars_alloc .
280: .It Fn mchars_num2char
1.7 kristaps 281: Convert a character index (e.g., the \eN\(aq\(aq escape) into a
282: printable ASCII character.
283: Returns \e0 (the nil character) if the input sequence is malformed.
284: .It Fn mchars_num2uc
285: Convert a hexadecimal character index (e.g., the \e[uNNNN] escape) into
286: a Unicode codepoint.
1.6 kristaps 287: Returns \e0 (the nil character) if the input sequence is malformed.
288: .It Fn mchars_spec2cp
289: Convert a special character into a valid Unicode codepoint.
1.10 kristaps 290: Returns \-1 on failure or a non-zero Unicode codepoint on success.
1.6 kristaps 291: .It Fn mchars_spec2str
292: Convert a special character into an ASCII string.
1.12 kristaps 293: Returns
294: .Dv NULL
295: on failure.
1.3 kristaps 296: .It Fn mdoc_meta
1.4 kristaps 297: Obtain the meta-data of a successful parse.
298: This may only be used on a pointer returned by
299: .Fn mparse_result .
1.3 kristaps 300: .It Fn mdoc_node
1.4 kristaps 301: Obtain the root node of a successful parse.
302: This may only be used on a pointer returned by
303: .Fn mparse_result .
1.3 kristaps 304: .It Fn mparse_alloc
1.4 kristaps 305: Allocate a parser.
306: The same parser may be used for multiple files so long as
307: .Fn mparse_reset
308: is called between parses.
309: .Fn mparse_free
310: must be called to free the memory allocated by this function.
1.3 kristaps 311: .It Fn mparse_free
1.4 kristaps 312: Free all memory allocated by
313: .Fn mparse_alloc .
1.14 kristaps 314: .It Fn mparse_getkeep
315: Acquire the keep buffer.
316: Must follow a call of
317: .Fn mparse_keep .
318: .It Fn mparse_keep
319: Instruct the parser to retain a copy of its parsed input.
320: This can be acquired with subsequent
321: .Fn mparse_getkeep
322: calls.
1.3 kristaps 323: .It Fn mparse_readfd
1.4 kristaps 324: Parse a file or file descriptor.
325: If
326: .Va fd
327: is -1,
328: .Va fname
329: is opened for reading.
330: Otherwise,
331: .Va fname
332: is assumed to be the name associated with
333: .Va fd .
334: This may be called multiple times with different parameters; however,
335: .Fn mparse_reset
336: should be invoked between parses.
1.3 kristaps 337: .It Fn mparse_reset
1.4 kristaps 338: Reset a parser so that
339: .Fn mparse_readfd
340: may be used again.
1.3 kristaps 341: .It Fn mparse_result
1.4 kristaps 342: Obtain the result of a parse.
343: Only successful parses
344: .Po
345: i.e., those where
346: .Fn mparse_readfd
347: returned less than MANDOCLEVEL_FATAL
348: .Pc
349: should invoke this function, in which case one of the two pointers will
350: be filled in.
1.3 kristaps 351: .It Fn mparse_strerror
1.4 kristaps 352: Return a statically-allocated string representation of an error code.
1.3 kristaps 353: .It Fn mparse_strlevel
1.4 kristaps 354: Return a statically-allocated string representation of a level code.
1.3 kristaps 355: .El
356: .Ss Variables
357: .Bl -ohang
358: .It Va man_macronames
1.4 kristaps 359: The string representation of a man macro as indexed by
360: .Vt "enum mant" .
1.3 kristaps 361: .It Va mdoc_argnames
1.4 kristaps 362: The string representation of a mdoc macro argument as indexed by
363: .Vt "enum mdocargt" .
1.3 kristaps 364: .It Va mdoc_macronames
1.4 kristaps 365: The string representation of a mdoc macro as indexed by
366: .Vt "enum mdoct" .
1.1 kristaps 367: .El
368: .Sh IMPLEMENTATION NOTES
369: This section consists of structural documentation for
370: .Xr mdoc 7
371: and
372: .Xr man 7
1.11 kristaps 373: syntax trees and strings.
374: .Ss Man and Mdoc Strings
375: Strings may be extracted from mdoc and man meta-data, or from text
376: nodes (MDOC_TEXT and MAN_TEXT, respectively).
377: These strings have special non-printing formatting cues embedded in the
378: text itself, as well as
379: .Xr roff 7
380: escapes preserved from input.
381: Implementing systems will need to handle both situations to produce
382: human-readable text.
383: In general, strings may be assumed to consist of 7-bit ASCII characters.
384: .Pp
385: The following non-printing characters may be embedded in text strings:
386: .Bl -tag -width Ds
387: .It Dv ASCII_NBRSP
388: A non-breaking space character.
389: .It Dv ASCII_HYPH
390: A soft hyphen.
391: .El
392: .Pp
393: Escape characters are also passed verbatim into text strings.
394: An escape character is a sequence of characters beginning with the
395: backslash
396: .Pq Sq \e .
397: To construct human-readable text, these should be intercepted with
398: .Fn mandoc_escape
399: and converted with one of
400: .Fn mchars_num2char ,
401: .Fn mchars_spec2str ,
402: and so on.
1.1 kristaps 403: .Ss Man Abstract Syntax Tree
404: This AST is governed by the ontological rules dictated in
405: .Xr man 7
406: and derives its terminology accordingly.
407: .Pp
408: The AST is composed of
409: .Vt struct man_node
410: nodes with element, root and text types as declared by the
411: .Va type
412: field.
413: Each node also provides its parse point (the
414: .Va line ,
415: .Va sec ,
416: and
417: .Va pos
418: fields), its position in the tree (the
419: .Va parent ,
420: .Va child ,
421: .Va next
422: and
423: .Va prev
424: fields) and some type-specific data.
425: .Pp
426: The tree itself is arranged according to the following normal form,
427: where capitalised non-terminals represent nodes.
428: .Pp
429: .Bl -tag -width "ELEMENTXX" -compact
430: .It ROOT
431: \(<- mnode+
432: .It mnode
433: \(<- ELEMENT | TEXT | BLOCK
434: .It BLOCK
435: \(<- HEAD BODY
436: .It HEAD
437: \(<- mnode*
438: .It BODY
439: \(<- mnode*
440: .It ELEMENT
441: \(<- ELEMENT | TEXT*
442: .It TEXT
1.11 kristaps 443: \(<- [[:ascii:]]*
1.1 kristaps 444: .El
445: .Pp
446: The only elements capable of nesting other elements are those with
447: next-lint scope as documented in
448: .Xr man 7 .
449: .Ss Mdoc Abstract Syntax Tree
450: This AST is governed by the ontological
451: rules dictated in
452: .Xr mdoc 7
453: and derives its terminology accordingly.
454: .Qq In-line
455: elements described in
456: .Xr mdoc 7
457: are described simply as
458: .Qq elements .
459: .Pp
460: The AST is composed of
461: .Vt struct mdoc_node
462: nodes with block, head, body, element, root and text types as declared
463: by the
464: .Va type
465: field.
466: Each node also provides its parse point (the
467: .Va line ,
468: .Va sec ,
469: and
470: .Va pos
471: fields), its position in the tree (the
472: .Va parent ,
473: .Va child ,
474: .Va nchild ,
475: .Va next
476: and
477: .Va prev
478: fields) and some type-specific data, in particular, for nodes generated
479: from macros, the generating macro in the
480: .Va tok
481: field.
482: .Pp
483: The tree itself is arranged according to the following normal form,
484: where capitalised non-terminals represent nodes.
485: .Pp
486: .Bl -tag -width "ELEMENTXX" -compact
487: .It ROOT
488: \(<- mnode+
489: .It mnode
490: \(<- BLOCK | ELEMENT | TEXT
491: .It BLOCK
492: \(<- HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]]
493: .It ELEMENT
494: \(<- TEXT*
495: .It HEAD
496: \(<- mnode*
497: .It BODY
498: \(<- mnode* [ENDBODY mnode*]
499: .It TAIL
500: \(<- mnode*
501: .It TEXT
1.11 kristaps 502: \(<- [[:ascii:]]*
1.1 kristaps 503: .El
504: .Pp
505: Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
506: the BLOCK production: these refer to punctuation marks.
507: Furthermore, although a TEXT node will generally have a non-zero-length
508: string, in the specific case of
509: .Sq \&.Bd \-literal ,
510: an empty line will produce a zero-length string.
511: Multiple body parts are only found in invocations of
512: .Sq \&Bl \-column ,
513: where a new body introduces a new phrase.
514: .Pp
515: The
516: .Xr mdoc 7
1.5 kristaps 517: syntax tree accommodates for broken block structures as well.
1.1 kristaps 518: The ENDBODY node is available to end the formatting associated
519: with a given block before the physical end of that block.
520: It has a non-null
521: .Va end
522: field, is of the BODY
523: .Va type ,
524: has the same
525: .Va tok
526: as the BLOCK it is ending, and has a
527: .Va pending
528: field pointing to that BLOCK's BODY node.
529: It is an indirect child of that BODY node
530: and has no children of its own.
531: .Pp
532: An ENDBODY node is generated when a block ends while one of its child
533: blocks is still open, like in the following example:
534: .Bd -literal -offset indent
535: \&.Ao ao
536: \&.Bo bo ac
537: \&.Ac bc
538: \&.Bc end
539: .Ed
540: .Pp
541: This example results in the following block structure:
542: .Bd -literal -offset indent
543: BLOCK Ao
544: HEAD Ao
545: BODY Ao
546: TEXT ao
547: BLOCK Bo, pending -> Ao
548: HEAD Bo
549: BODY Bo
550: TEXT bo
551: TEXT ac
552: ENDBODY Ao, pending -> Ao
553: TEXT bc
554: TEXT end
555: .Ed
556: .Pp
557: Here, the formatting of the
558: .Sq \&Ao
559: block extends from TEXT ao to TEXT ac,
560: while the formatting of the
561: .Sq \&Bo
562: block extends from TEXT bo to TEXT bc.
563: It renders as follows in
564: .Fl T Ns Cm ascii
565: mode:
566: .Pp
567: .Dl <ao [bo ac> bc] end
568: .Pp
569: Support for badly-nested blocks is only provided for backward
570: compatibility with some older
571: .Xr mdoc 7
572: implementations.
573: Using badly-nested blocks is
574: .Em strongly discouraged ;
575: for example, the
576: .Fl T Ns Cm html
577: and
578: .Fl T Ns Cm xhtml
579: front-ends to
580: .Xr mandoc 1
581: are unable to render them in any meaningful way.
582: Furthermore, behaviour when encountering badly-nested blocks is not
583: consistent across troff implementations, especially when using multiple
584: levels of badly-nested blocks.
585: .Sh SEE ALSO
586: .Xr mandoc 1 ,
587: .Xr eqn 7 ,
588: .Xr man 7 ,
1.6 kristaps 589: .Xr mandoc_char 7 ,
1.1 kristaps 590: .Xr mdoc 7 ,
591: .Xr roff 7 ,
592: .Xr tbl 7
593: .Sh AUTHORS
594: The
595: .Nm
596: library was written by
1.13 kristaps 597: .An Kristaps Dzonsons ,
598: .Mt kristaps@bsd.lv .
CVSweb