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