1 .\" Id: mandoc.3,v 1.22 2013/10/06 17:01:52 schwarze Exp
3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
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.
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.
44 .Nd mandoc macro compiler library
53 .Fa "const char const **end"
54 .Fa "const char const **start"
57 .Ft "const struct man_meta *"
59 .Fa "const struct man *man"
61 .Ft "const struct mparse *"
63 .Fa "const struct man *man"
65 .Ft "const struct man_node *"
67 .Fa "const struct man *man"
70 .Fn mchars_alloc "void"
72 .Fn mchars_free "struct mchars *p"
74 .Fn mchars_num2char "const char *cp" "size_t sz"
76 .Fn mchars_num2uc "const char *cp" "size_t sz"
79 .Fa "const struct mchars *p"
86 .Fa "const struct mchars *p"
90 .Ft "const struct mdoc_meta *"
92 .Fa "const struct mdoc *mdoc"
94 .Ft "const struct mdoc_node *"
96 .Fa "const struct mdoc *mdoc"
100 .Fa "enum mparset type"
101 .Fa "enum mandoclevel wlevel"
107 .Fa "struct mparse *parse"
111 .Fa "const struct mparse *parse"
115 .Fa "struct mparse *parse"
117 .Ft "enum mandoclevel"
119 .Fa "struct mparse *parse"
121 .Fa "const char *fname"
125 .Fa "struct mparse *parse"
129 .Fa "struct mparse *parse"
130 .Fa "struct mdoc **mdoc"
131 .Fa "struct man **man"
139 .Fa "enum mandoclevel"
141 .Vt extern const char * const * man_macronames;
142 .Vt extern const char * const * mdoc_argnames;
143 .Vt extern const char * const * mdoc_macronames;
144 .Fd "#define ASCII_NBRSP"
145 .Fd "#define ASCII_HYPH"
151 manual into an abstract syntax tree (AST).
153 manuals are composed of
157 and may be mixed with
164 The following describes a general parse sequence:
167 initiate a parsing sequence with
170 parse files or file descriptors with
173 retrieve a parsed syntax tree, if the parse was successful, with
176 iterate over parse nodes with
181 free all allocated memory with
190 library also contains routines for translating character strings into glyphs
191 .Pq see Fn mchars_alloc
192 and parsing escape sequences from strings
193 .Pq see Fn mandoc_escape .
195 This section documents the functions, types, and variables available
200 .It Vt "enum mandoc_esc"
201 An escape sequence classification.
202 .It Vt "enum mandocerr"
203 A fatal error, error, or warning message during parsing.
204 .It Vt "enum mandoclevel"
205 A classification of an
206 .Vt "enum mandoclevel"
207 as regards system operation.
208 .It Vt "struct mchars"
209 An opaque pointer to an object allowing for translation between
210 character strings and glyphs.
213 .It Vt "enum mparset"
214 The type of parser when reading input.
215 This should usually be
218 .It Vt "struct mparse"
219 An opaque pointer to a running parse sequence.
224 This may be used across parsed input if
226 is called between parses.
228 A prototype for a function to handle fatal error, error, and warning
229 messages emitted by the parser.
234 Scan an escape sequence, i.e., a character string beginning with
236 Pass a pointer to the character after the
240 it will be set to the supremum of the parsed escape sequence unless
243 in which case the string is bogus and should be
250 is set to the first relevant character of the substring (font, glyph,
264 Obtain the meta-data of a successful parse.
265 This may only be used on a pointer returned by
272 Get the parser used for the current output.
278 Obtain the root node of a successful parse.
279 This may only be used on a pointer returned by
287 .Vt "struct mchars *"
288 object for translating special characters into glyphs.
291 for an overview of special characters.
292 The object must be freed with
299 Free an object created with
305 .It Fn mchars_num2char
306 Convert a character index (e.g., the \eN\(aq\(aq escape) into a
307 printable ASCII character.
308 Returns \e0 (the nil character) if the input sequence is malformed.
314 Convert a hexadecimal character index (e.g., the \e[uNNNN] escape) into
316 Returns \e0 (the nil character) if the input sequence is malformed.
321 .It Fn mchars_spec2cp
322 Convert a special character into a valid Unicode codepoint.
323 Returns \-1 on failure or a non-zero Unicode codepoint on success.
328 .It Fn mchars_spec2str
329 Convert a special character into an ASCII string.
338 Obtain the meta-data of a successful parse.
339 This may only be used on a pointer returned by
346 Obtain the root node of a successful parse.
347 This may only be used on a pointer returned by
355 The same parser may be used for multiple files so long as
357 is called between parses.
359 must be called to free the memory allocated by this function.
365 Free all memory allocated by
371 .It Fn mparse_getkeep
372 Acquire the keep buffer.
373 Must follow a call of
380 Instruct the parser to retain a copy of its parsed input.
381 This can be acquired with subsequent
389 Parse a file or file descriptor.
394 is opened for reading.
397 is assumed to be the name associated with
399 This may be called multiple times with different parameters; however,
401 should be invoked between parses.
407 Reset a parser so that
415 Obtain the result of a parse.
416 Only successful parses
420 returned less than MANDOCLEVEL_FATAL
422 should invoke this function, in which case one of the two pointers will
428 .It Fn mparse_strerror
429 Return a statically-allocated string representation of an error code.
434 .It Fn mparse_strlevel
435 Return a statically-allocated string representation of a level code.
443 .It Va man_macronames
444 The string representation of a man macro as indexed by
447 The string representation of a mdoc macro argument as indexed by
448 .Vt "enum mdocargt" .
449 .It Va mdoc_macronames
450 The string representation of a mdoc macro as indexed by
453 .Sh IMPLEMENTATION NOTES
454 This section consists of structural documentation for
458 syntax trees and strings.
459 .Ss Man and Mdoc Strings
460 Strings may be extracted from mdoc and man meta-data, or from text
461 nodes (MDOC_TEXT and MAN_TEXT, respectively).
462 These strings have special non-printing formatting cues embedded in the
463 text itself, as well as
465 escapes preserved from input.
466 Implementing systems will need to handle both situations to produce
468 In general, strings may be assumed to consist of 7-bit ASCII characters.
470 The following non-printing characters may be embedded in text strings:
473 A non-breaking space character.
478 Escape characters are also passed verbatim into text strings.
479 An escape character is a sequence of characters beginning with the
482 To construct human-readable text, these should be intercepted with
484 and converted with one of
485 .Fn mchars_num2char ,
486 .Fn mchars_spec2str ,
488 .Ss Man Abstract Syntax Tree
489 This AST is governed by the ontological rules dictated in
491 and derives its terminology accordingly.
493 The AST is composed of
495 nodes with element, root and text types as declared by the
498 Each node also provides its parse point (the
503 fields), its position in the tree (the
509 fields) and some type-specific data.
511 The tree itself is arranged according to the following normal form,
512 where capitalised non-terminals represent nodes.
514 .Bl -tag -width "ELEMENTXX" -compact
518 \(<- ELEMENT | TEXT | BLOCK
531 The only elements capable of nesting other elements are those with
532 next-lint scope as documented in
534 .Ss Mdoc Abstract Syntax Tree
535 This AST is governed by the ontological
538 and derives its terminology accordingly.
540 elements described in
542 are described simply as
545 The AST is composed of
547 nodes with block, head, body, element, root and text types as declared
551 Each node also provides its parse point (the
556 fields), its position in the tree (the
563 fields) and some type-specific data, in particular, for nodes generated
564 from macros, the generating macro in the
568 The tree itself is arranged according to the following normal form,
569 where capitalised non-terminals represent nodes.
571 .Bl -tag -width "ELEMENTXX" -compact
575 \(<- BLOCK | ELEMENT | TEXT
577 \(<- HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]]
583 \(<- mnode* [ENDBODY mnode*]
590 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
591 the BLOCK production: these refer to punctuation marks.
592 Furthermore, although a TEXT node will generally have a non-zero-length
593 string, in the specific case of
594 .Sq \&.Bd \-literal ,
595 an empty line will produce a zero-length string.
596 Multiple body parts are only found in invocations of
598 where a new body introduces a new phrase.
602 syntax tree accommodates for broken block structures as well.
603 The ENDBODY node is available to end the formatting associated
604 with a given block before the physical end of that block.
607 field, is of the BODY
611 as the BLOCK it is ending, and has a
613 field pointing to that BLOCK's BODY node.
614 It is an indirect child of that BODY node
615 and has no children of its own.
617 An ENDBODY node is generated when a block ends while one of its child
618 blocks is still open, like in the following example:
619 .Bd -literal -offset indent
626 This example results in the following block structure:
627 .Bd -literal -offset indent
632 BLOCK Bo, pending -> Ao
637 ENDBODY Ao, pending -> Ao
642 Here, the formatting of the
644 block extends from TEXT ao to TEXT ac,
645 while the formatting of the
647 block extends from TEXT bo to TEXT bc.
648 It renders as follows in
652 .Dl <ao [bo ac> bc] end
654 Support for badly-nested blocks is only provided for backward
655 compatibility with some older
658 Using badly-nested blocks is
659 .Em strongly discouraged ;
666 are unable to render them in any meaningful way.
667 Furthermore, behaviour when encountering badly-nested blocks is not
668 consistent across troff implementations, especially when using multiple
669 levels of badly-nested blocks.
681 library was written by
682 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .