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

Annotation of mandoc/mdoc.3, Revision 1.33

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

CVSweb