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