[BACK]Return to mdoc.3 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/mdoc.3, Revision 1.18

1.18    ! kristaps    1: .\" $Id: mdoc.3,v 1.17 2009/03/14 05:21:58 kristaps Exp $
1.6       kristaps    2: .\"
                      3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
                      4: .\"
                      5: .\" Permission to use, copy, modify, and distribute this software for any
                      6: .\" purpose with or without fee is hereby granted, provided that the
                      7: .\" above copyright notice and this permission notice appear in all
                      8: .\" copies.
                      9: .\"
                     10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
                     11: .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
                     12: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
                     13: .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
                     14: .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
                     15: .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
                     16: .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
                     17: .\" PERFORMANCE OF THIS SOFTWARE.
1.1       kristaps   18: .\"
                     19: .Dd $Mdocdate$
                     20: .Dt mdoc 3
                     21: .Os
1.6       kristaps   22: .\" SECTION
1.1       kristaps   23: .Sh NAME
                     24: .Nm mdoc_alloc ,
                     25: .Nm mdoc_parseln ,
                     26: .Nm mdoc_endparse ,
1.4       kristaps   27: .Nm mdoc_node ,
                     28: .Nm mdoc_meta ,
1.1       kristaps   29: .Nm mdoc_free
1.2       kristaps   30: .Nd mdoc macro compiler library
1.6       kristaps   31: .\" SECTION
1.1       kristaps   32: .Sh SYNOPSIS
1.4       kristaps   33: .Fd #include <mdoc.h>
                     34: .Vt extern const char * const * mdoc_macronames;
                     35: .Vt extern const char * const * mdoc_argnames;
1.1       kristaps   36: .Ft "struct mdoc *"
                     37: .Fn mdoc_alloc "void *data" "const struct mdoc_cb *cb"
                     38: .Ft void
1.2       kristaps   39: .Fn mdoc_free "struct mdoc *mdoc"
1.1       kristaps   40: .Ft int
1.2       kristaps   41: .Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
1.1       kristaps   42: .Ft "const struct mdoc_node *"
1.4       kristaps   43: .Fn mdoc_node "struct mdoc *mdoc"
                     44: .Ft "const struct mdoc_meta *"
                     45: .Fn mdoc_meta "struct mdoc *mdoc"
1.1       kristaps   46: .Ft int
1.2       kristaps   47: .Fn mdoc_endparse "struct mdoc *mdoc"
1.6       kristaps   48: .\" SECTION
1.1       kristaps   49: .Sh DESCRIPTION
                     50: The
                     51: .Nm mdoc
1.17      kristaps   52: library parses lines of
                     53: .Xr mdoc 7
                     54: input (and
                     55: .Em only
                     56: mdoc) into an abstract syntax tree that generalises the semantic
                     57: annotation of its input.  Common front-ends for
1.6       kristaps   58: .Nm
1.17      kristaps   59: are
                     60: .Xr mdocterm 1 ,
                     61: .Xr mdoclint 1
1.6       kristaps   62: and
1.17      kristaps   63: .Xr mdoctree 1 .
1.6       kristaps   64: .\" PARAGRAPH
                     65: .Pp
1.1       kristaps   66: In general, applications initiate a parsing sequence with
                     67: .Fn mdoc_alloc ,
                     68: parse each line in a document with
                     69: .Fn mdoc_parseln ,
                     70: close the parsing session with
                     71: .Fn mdoc_endparse ,
                     72: operate over the syntax tree returned by
1.4       kristaps   73: .Fn mdoc_node
                     74: and
                     75: .Fn mdoc_meta ,
1.1       kristaps   76: then free all allocated memory with
                     77: .Fn mdoc_free .
                     78: See the
                     79: .Sx EXAMPLES
                     80: section for a full example.
1.6       kristaps   81: .\" PARAGRAPH
1.2       kristaps   82: .Pp
1.6       kristaps   83: This section further defines the
                     84: .Sx Types ,
                     85: .Sx Functions
                     86: and
                     87: .Sx Variables
1.17      kristaps   88: available to programmers.  Following that, the
                     89: .Sx Abstract Syntax Tree
                     90: section documents the output tree.
1.6       kristaps   91: .\" SUBSECTION
                     92: .Ss Types
                     93: Both functions (see
                     94: .Sx Functions )
                     95: and variables (see
                     96: .Sx Variables )
                     97: may use the following types:
1.9       kristaps   98: .Bl -ohang -offset "XXXX"
1.6       kristaps   99: .\" LIST-ITEM
                    100: .It Vt struct mdoc
                    101: An opaque type defined in
                    102: .Pa mdoc.c .
                    103: Its values are only used privately within the library.
                    104: .\" LIST-ITEM
                    105: .It Vt struct mdoc_cb
                    106: A set of message callbacks defined in
                    107: .Pa mdoc.h .
                    108: .\" LIST-ITEM
                    109: .It Vt struct mdoc_node
                    110: A parsed node.  Defined in
                    111: .Pa mdoc.h .
                    112: See
                    113: .Sx Abstract Syntax Tree
                    114: for details.
                    115: .El
                    116: .\" SUBSECTION
                    117: .Ss Functions
1.2       kristaps  118: Function descriptions follow:
1.9       kristaps  119: .Bl -ohang -offset "XXXX"
1.6       kristaps  120: .\" LIST-ITEM
1.2       kristaps  121: .It Fn mdoc_alloc
                    122: Allocates a parsing structure.  The
                    123: .Fa data
                    124: pointer is passed to callbacks in
                    125: .Fa cb ,
                    126: which are documented further in the header file.  Returns NULL on
                    127: failure.  If non-NULL, the pointer must be freed with
                    128: .Fn mdoc_free .
1.6       kristaps  129: .\" LIST-ITEM
1.2       kristaps  130: .It Fn mdoc_free
                    131: Free all resources of a parser.  The pointer is no longer valid after
                    132: invocation.
1.6       kristaps  133: .\" LIST-ITEM
1.2       kristaps  134: .It Fn mdoc_parseln
                    135: Parse a nil-terminated line of input.  This line should not contain the
                    136: trailing newline.  Returns 0 on failure, 1 on success.  The input buffer
                    137: .Fa buf
                    138: is modified by this function.
1.6       kristaps  139: .\" LIST-ITEM
1.2       kristaps  140: .It Fn mdoc_endparse
                    141: Signals that the parse is complete.  Note that if
                    142: .Fn mdoc_endparse
                    143: is called subsequent to
1.4       kristaps  144: .Fn mdoc_node ,
1.2       kristaps  145: the resulting tree is incomplete.  Returns 0 on failure, 1 on success.
1.6       kristaps  146: .\" LIST-ITEM
1.4       kristaps  147: .It Fn mdoc_node
                    148: Returns the first node of the parse.  Note that if
1.2       kristaps  149: .Fn mdoc_parseln
                    150: or
                    151: .Fn mdoc_endparse
                    152: return 0, the tree will be incomplete.
1.4       kristaps  153: .It Fn mdoc_meta
                    154: Returns the document's parsed meta-data.  If this information has not
                    155: yet been supplied or
                    156: .Fn mdoc_parseln
                    157: or
                    158: .Fn mdoc_endparse
                    159: return 0, the data will be incomplete.
                    160: .El
1.6       kristaps  161: .\" SUBSECTION
                    162: .Ss Variables
1.4       kristaps  163: The following variables are also defined:
1.9       kristaps  164: .Bl -ohang -offset "XXXX"
1.6       kristaps  165: .\" LIST-ITEM
1.4       kristaps  166: .It Va mdoc_macronames
                    167: An array of string-ified token names.
1.6       kristaps  168: .\" LIST-ITEM
1.4       kristaps  169: .It Va mdoc_argnames
                    170: An array of string-ified token argument names.
1.2       kristaps  171: .El
1.6       kristaps  172: .\" SUBSECTION
                    173: .Ss Abstract Syntax Tree
                    174: The
                    175: .Nm
1.17      kristaps  176: functions produce an abstract syntax tree (AST) describing input in a
                    177: regular form.  It may be reviewed at any time with
1.6       kristaps  178: .Fn mdoc_nodes ;
                    179: however, if called before
                    180: .Fn mdoc_endparse ,
                    181: or after
                    182: .Fn mdoc_endparse
                    183: or
                    184: .Fn mdoc_parseln
1.18    ! kristaps  185: fail, it may be incomplete.
        !           186: .\" PARAGRAPH
        !           187: .Pp
        !           188: This AST is governed by the ontological
1.17      kristaps  189: rules dictated in
                    190: .Xr mdoc 7
                    191: and derives its terminology accordingly.
                    192: .Qq In-line
                    193: elements described in
                    194: .Xr mdoc 7
                    195: are described simply as
                    196: .Qq elements .
1.6       kristaps  197: .\" PARAGRAPH
                    198: .Pp
                    199: The AST is composed of
                    200: .Vt struct mdoc_node
                    201: nodes with block, head, body, element, root and text types as declared
                    202: by the
                    203: .Va type
                    204: field.  Each node also provides its parse point (the
                    205: .Va line ,
                    206: .Va sec ,
                    207: and
                    208: .Va pos
                    209: fields), its position in the tree (the
                    210: .Va parent ,
                    211: .Va child ,
                    212: .Va next
                    213: and
                    214: .Va prev
                    215: fields) and type-specific data (the
                    216: .Va data
                    217: field).
                    218: .\" PARAGRAPH
                    219: .Pp
                    220: The tree itself is arranged according to the following normal form,
                    221: where capitalised non-terminals represent nodes.
                    222: .Pp
1.9       kristaps  223: .Bl -tag -width "ELEMENTXX" -compact -offset "XXXX"
1.6       kristaps  224: .\" LIST-ITEM
                    225: .It ROOT
                    226: \(<- mnode+
                    227: .It mnode
                    228: \(<- BLOCK | ELEMENT | TEXT
                    229: .It BLOCK
                    230: \(<- (HEAD [TEXT])+ [BODY [TEXT]] [TAIL [TEXT]]
                    231: .It BLOCK
                    232: \(<- BODY [TEXT] [TAIL [TEXT]]
                    233: .It ELEMENT
                    234: \(<- TEXT*
                    235: .It HEAD
                    236: \(<- mnode+
                    237: .It BODY
                    238: \(<- mnode+
                    239: .It TAIL
                    240: \(<- mnode+
                    241: .It TEXT
                    242: \(<- [[:alpha:]]*
                    243: .El
                    244: .\" PARAGRAPH
1.2       kristaps  245: .Pp
1.6       kristaps  246: Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
                    247: the BLOCK production.  These refer to punctuation marks.  Furthermore,
1.8       kristaps  248: although a TEXT node will generally have a non-zero-length string, in
                    249: the specific case of
                    250: .Sq \&.Bd \-literal ,
1.6       kristaps  251: an empty line will produce a zero-length string.
                    252: .\" SECTION
1.2       kristaps  253: .Sh EXAMPLES
                    254: The following example reads lines from stdin and parses them, operating
                    255: on the finished parse tree with
                    256: .Fn parsed .
                    257: Note that, if the last line of the file isn't newline-terminated, this
                    258: will truncate the file's last character (see
                    259: .Xr fgetln 3 ) .
                    260: Further, this example does not error-check nor free memory upon failure.
1.9       kristaps  261: .Bd -literal -offset "XXXX"
1.2       kristaps  262: struct mdoc *mdoc;
                    263: struct mdoc_node *node;
                    264: char *buf;
                    265: size_t len;
                    266: int line;
                    267:
                    268: line = 1;
                    269: mdoc = mdoc_alloc(NULL, NULL);
                    270:
                    271: while ((buf = fgetln(fp, &len))) {
                    272:        buf[len - 1] = '\\0';
                    273:        if ( ! mdoc_parseln(mdoc, line, buf))
                    274:                errx(1, "mdoc_parseln");
                    275:        line++;
                    276: }
                    277:
                    278: if ( ! mdoc_endparse(mdoc))
                    279:        errx(1, "mdoc_endparse");
1.4       kristaps  280: if (NULL == (node = mdoc_node(mdoc)))
                    281:        errx(1, "mdoc_node");
1.2       kristaps  282:
                    283: parsed(mdoc, node);
                    284: mdoc_free(mdoc);
                    285: .Ed
1.6       kristaps  286: .\" SECTION
1.17      kristaps  287: .Sh SEE ALSO
                    288: .Xr mdocterm 1 ,
                    289: .Xr mdoclint 1 ,
                    290: .Xr mdoctree 1 ,
1.14      kristaps  291: .Xr mdoc 7
1.6       kristaps  292: .\" SECTION
1.2       kristaps  293: .Sh AUTHORS
                    294: The
                    295: .Nm
                    296: utility was written by
                    297: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.6       kristaps  298: .\" SECTION
1.14      kristaps  299: .Sh CAVEATS
1.17      kristaps  300: .Bl -dash -compact
1.14      kristaps  301: .\" LIST-ITEM
                    302: .It
                    303: The
1.2       kristaps  304: .Sq \&Xc
                    305: and
                    306: .Sq \&Xo
                    307: macros aren't handled when used to span lines for the
                    308: .Sq \&It
1.17      kristaps  309: macro.
1.16      kristaps  310: .\" LIST-ITEM
                    311: .It
                    312: The
                    313: .Sq \&Bsx
1.17      kristaps  314: macro doesn't yet understand version arguments.
1.14      kristaps  315: .El

CVSweb