1 .\" $Id: mandoc.3,v 1.17 2012/01/13 15:27:14 joerg 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 **end"
54 .Fa "const char **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,
260 Obtain the meta-data of a successful parse.
261 This may only be used on a pointer returned by
264 Get the parser used for the current output.
266 Obtain the root node of a successful parse.
267 This may only be used on a pointer returned by
271 .Vt "struct mchars *"
272 object for translating special characters into glyphs.
275 for an overview of special characters.
276 The object must be freed with
279 Free an object created with
281 .It Fn mchars_num2char
282 Convert a character index (e.g., the \eN\(aq\(aq escape) into a
283 printable ASCII character.
284 Returns \e0 (the nil character) if the input sequence is malformed.
286 Convert a hexadecimal character index (e.g., the \e[uNNNN] escape) into
288 Returns \e0 (the nil character) if the input sequence is malformed.
289 .It Fn mchars_spec2cp
290 Convert a special character into a valid Unicode codepoint.
291 Returns \-1 on failure or a non-zero Unicode codepoint on success.
292 .It Fn mchars_spec2str
293 Convert a special character into an ASCII string.
298 Obtain the meta-data of a successful parse.
299 This may only be used on a pointer returned by
302 Obtain the root node of a successful parse.
303 This may only be used on a pointer returned by
307 The same parser may be used for multiple files so long as
309 is called between parses.
311 must be called to free the memory allocated by this function.
313 Free all memory allocated by
315 .It Fn mparse_getkeep
316 Acquire the keep buffer.
317 Must follow a call of
320 Instruct the parser to retain a copy of its parsed input.
321 This can be acquired with subsequent
325 Parse a file or file descriptor.
330 is opened for reading.
333 is assumed to be the name associated with
335 This may be called multiple times with different parameters; however,
337 should be invoked between parses.
339 Reset a parser so that
343 Obtain the result of a parse.
344 Only successful parses
348 returned less than MANDOCLEVEL_FATAL
350 should invoke this function, in which case one of the two pointers will
352 .It Fn mparse_strerror
353 Return a statically-allocated string representation of an error code.
354 .It Fn mparse_strlevel
355 Return a statically-allocated string representation of a level code.
359 .It Va man_macronames
360 The string representation of a man macro as indexed by
363 The string representation of a mdoc macro argument as indexed by
364 .Vt "enum mdocargt" .
365 .It Va mdoc_macronames
366 The string representation of a mdoc macro as indexed by
369 .Sh IMPLEMENTATION NOTES
370 This section consists of structural documentation for
374 syntax trees and strings.
375 .Ss Man and Mdoc Strings
376 Strings may be extracted from mdoc and man meta-data, or from text
377 nodes (MDOC_TEXT and MAN_TEXT, respectively).
378 These strings have special non-printing formatting cues embedded in the
379 text itself, as well as
381 escapes preserved from input.
382 Implementing systems will need to handle both situations to produce
384 In general, strings may be assumed to consist of 7-bit ASCII characters.
386 The following non-printing characters may be embedded in text strings:
389 A non-breaking space character.
394 Escape characters are also passed verbatim into text strings.
395 An escape character is a sequence of characters beginning with the
398 To construct human-readable text, these should be intercepted with
400 and converted with one of
401 .Fn mchars_num2char ,
402 .Fn mchars_spec2str ,
404 .Ss Man Abstract Syntax Tree
405 This AST is governed by the ontological rules dictated in
407 and derives its terminology accordingly.
409 The AST is composed of
411 nodes with element, root and text types as declared by the
414 Each node also provides its parse point (the
419 fields), its position in the tree (the
425 fields) and some type-specific data.
427 The tree itself is arranged according to the following normal form,
428 where capitalised non-terminals represent nodes.
430 .Bl -tag -width "ELEMENTXX" -compact
434 \(<- ELEMENT | TEXT | BLOCK
447 The only elements capable of nesting other elements are those with
448 next-lint scope as documented in
450 .Ss Mdoc Abstract Syntax Tree
451 This AST is governed by the ontological
454 and derives its terminology accordingly.
456 elements described in
458 are described simply as
461 The AST is composed of
463 nodes with block, head, body, element, root and text types as declared
467 Each node also provides its parse point (the
472 fields), its position in the tree (the
479 fields) and some type-specific data, in particular, for nodes generated
480 from macros, the generating macro in the
484 The tree itself is arranged according to the following normal form,
485 where capitalised non-terminals represent nodes.
487 .Bl -tag -width "ELEMENTXX" -compact
491 \(<- BLOCK | ELEMENT | TEXT
493 \(<- HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]]
499 \(<- mnode* [ENDBODY mnode*]
506 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
507 the BLOCK production: these refer to punctuation marks.
508 Furthermore, although a TEXT node will generally have a non-zero-length
509 string, in the specific case of
510 .Sq \&.Bd \-literal ,
511 an empty line will produce a zero-length string.
512 Multiple body parts are only found in invocations of
514 where a new body introduces a new phrase.
518 syntax tree accommodates for broken block structures as well.
519 The ENDBODY node is available to end the formatting associated
520 with a given block before the physical end of that block.
523 field, is of the BODY
527 as the BLOCK it is ending, and has a
529 field pointing to that BLOCK's BODY node.
530 It is an indirect child of that BODY node
531 and has no children of its own.
533 An ENDBODY node is generated when a block ends while one of its child
534 blocks is still open, like in the following example:
535 .Bd -literal -offset indent
542 This example results in the following block structure:
543 .Bd -literal -offset indent
548 BLOCK Bo, pending -> Ao
553 ENDBODY Ao, pending -> Ao
558 Here, the formatting of the
560 block extends from TEXT ao to TEXT ac,
561 while the formatting of the
563 block extends from TEXT bo to TEXT bc.
564 It renders as follows in
568 .Dl <ao [bo ac> bc] end
570 Support for badly-nested blocks is only provided for backward
571 compatibility with some older
574 Using badly-nested blocks is
575 .Em strongly discouraged ;
582 are unable to render them in any meaningful way.
583 Furthermore, behaviour when encountering badly-nested blocks is not
584 consistent across troff implementations, especially when using multiple
585 levels of badly-nested blocks.
597 library was written by
598 .An Kristaps Dzonsons ,
599 .Mt kristaps@bsd.lv .