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

Annotation of mandoc/man.3, Revision 1.5

1.5     ! kristaps    1: .\"    $Id: man.3,v 1.4 2009/06/10 20:18:43 kristaps Exp $
1.1       kristaps    2: .\"
1.4       kristaps    3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
1.1       kristaps    4: .\"
                      5: .\" Permission to use, copy, modify, and distribute this software for any
1.3       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.
                      8: .\"
                      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.1       kristaps   16: .\"
                     17: .Dd $Mdocdate$
1.2       kristaps   18: .Dt MAN 3
1.1       kristaps   19: .Os
                     20: .\" SECTION
                     21: .Sh NAME
                     22: .Nm man_alloc ,
                     23: .Nm man_parseln ,
                     24: .Nm man_endparse ,
                     25: .Nm man_node ,
                     26: .Nm man_meta ,
                     27: .Nm man_free ,
                     28: .Nm man_reset
                     29: .Nd man macro compiler library
                     30: .\" SECTION
                     31: .Sh SYNOPSIS
                     32: .Fd #include <man.h>
                     33: .Vt extern const char * const * man_macronames;
                     34: .Ft "struct man *"
                     35: .Fn man_alloc "void *data" "int pflags" "const struct man_cb *cb"
                     36: .Ft void
                     37: .Fn man_reset "struct man *man"
                     38: .Ft void
                     39: .Fn man_free "struct man *man"
                     40: .Ft int
                     41: .Fn man_parseln "struct man *man" "int line" "char *buf"
                     42: .Ft "const struct man_node *"
                     43: .Fn man_node "struct man *man"
                     44: .Ft "const struct man_meta *"
                     45: .Fn man_meta "struct man *man"
                     46: .Ft int
                     47: .Fn man_endparse "struct man *man"
                     48: .\" SECTION
                     49: .Sh DESCRIPTION
                     50: The
                     51: .Nm man
                     52: library parses lines of
                     53: .Xr man 7
                     54: input (and
                     55: .Em only
                     56: man) into an abstract syntax tree (AST).
                     57: .\" PARAGRAPH
                     58: .Pp
                     59: In general, applications initiate a parsing sequence with
                     60: .Fn man_alloc ,
                     61: parse each line in a document with
                     62: .Fn man_parseln ,
                     63: close the parsing session with
                     64: .Fn man_endparse ,
                     65: operate over the syntax tree returned by
                     66: .Fn man_node
                     67: and
                     68: .Fn man_meta ,
                     69: then free all allocated memory with
                     70: .Fn man_free .
                     71: The
                     72: .Fn man_reset
                     73: function may be used in order to reset the parser for another input
                     74: sequence.  See the
                     75: .Sx EXAMPLES
                     76: section for a full example.
                     77: .\" PARAGRAPH
                     78: .Pp
                     79: This section further defines the
                     80: .Sx Types ,
                     81: .Sx Functions
                     82: and
                     83: .Sx Variables
                     84: available to programmers.  Following that, the
                     85: .Sx Abstract Syntax Tree
                     86: section documents the output tree.
                     87: .\" SUBSECTION
                     88: .Ss Types
                     89: Both functions (see
                     90: .Sx Functions )
                     91: and variables (see
                     92: .Sx Variables )
                     93: may use the following types:
                     94: .Bl -ohang -offset "XXXX"
                     95: .\" LIST-ITEM
                     96: .It Vt struct man
                     97: An opaque type defined in
                     98: .Pa man.c .
                     99: Its values are only used privately within the library.
                    100: .\" LIST-ITEM
                    101: .It Vt struct man_cb
                    102: A set of message callbacks defined in
                    103: .Pa man.h .
                    104: .\" LIST-ITEM
                    105: .It Vt struct man_node
                    106: A parsed node.  Defined in
                    107: .Pa man.h .
                    108: See
                    109: .Sx Abstract Syntax Tree
                    110: for details.
                    111: .El
                    112: .\" SUBSECTION
                    113: .Ss Functions
                    114: Function descriptions follow:
                    115: .Bl -ohang -offset "XXXX"
                    116: .\" LIST-ITEM
                    117: .It Fn man_alloc
                    118: Allocates a parsing structure.  The
                    119: .Fa data
                    120: pointer is passed to callbacks in
                    121: .Fa cb ,
                    122: which are documented further in the header file.
                    123: The
                    124: .Fa pflags
                    125: arguments are defined in
                    126: .Pa man.h .
                    127: Returns NULL on failure.  If non-NULL, the pointer must be freed with
                    128: .Fn man_free .
                    129: .\" LIST-ITEM
                    130: .It Fn man_reset
                    131: Reset the parser for another parse routine.  After its use,
                    132: .Fn man_parseln
                    133: behaves as if invoked for the first time.
                    134: .\" LIST-ITEM
                    135: .It Fn man_free
                    136: Free all resources of a parser.  The pointer is no longer valid after
                    137: invocation.
                    138: .\" LIST-ITEM
                    139: .It Fn man_parseln
                    140: Parse a nil-terminated line of input.  This line should not contain the
                    141: trailing newline.  Returns 0 on failure, 1 on success.  The input buffer
                    142: .Fa buf
                    143: is modified by this function.
                    144: .\" LIST-ITEM
                    145: .It Fn man_endparse
                    146: Signals that the parse is complete.  Note that if
                    147: .Fn man_endparse
                    148: is called subsequent to
                    149: .Fn man_node ,
                    150: the resulting tree is incomplete.  Returns 0 on failure, 1 on success.
                    151: .\" LIST-ITEM
                    152: .It Fn man_node
                    153: Returns the first node of the parse.  Note that if
                    154: .Fn man_parseln
                    155: or
                    156: .Fn man_endparse
                    157: return 0, the tree will be incomplete.
                    158: .It Fn man_meta
                    159: Returns the document's parsed meta-data.  If this information has not
                    160: yet been supplied or
                    161: .Fn man_parseln
                    162: or
                    163: .Fn man_endparse
                    164: return 0, the data will be incomplete.
                    165: .El
                    166: .\" SUBSECTION
                    167: .Ss Variables
                    168: The following variables are also defined:
                    169: .Bl -ohang -offset "XXXX"
                    170: .\" LIST-ITEM
                    171: .It Va man_macronames
                    172: An array of string-ified token names.
                    173: .El
                    174: .\" SUBSECTION
                    175: .Ss Abstract Syntax Tree
                    176: The
                    177: .Nm
                    178: functions produce an abstract syntax tree (AST) describing input in a
                    179: regular form.  It may be reviewed at any time with
                    180: .Fn man_nodes ;
                    181: however, if called before
                    182: .Fn man_endparse ,
                    183: or after
                    184: .Fn man_endparse
                    185: or
                    186: .Fn man_parseln
                    187: fail, it may be incomplete.
                    188: .\" PARAGRAPH
                    189: .Pp
                    190: This AST is governed by the ontological
                    191: rules dictated in
                    192: .Xr man 7
                    193: and derives its terminology accordingly.
                    194: .\" PARAGRAPH
                    195: .Pp
                    196: The AST is composed of
                    197: .Vt struct man_node
                    198: nodes with element, root and text types as declared
                    199: by the
                    200: .Va type
                    201: field.  Each node also provides its parse point (the
                    202: .Va line ,
                    203: .Va sec ,
                    204: and
                    205: .Va pos
                    206: fields), its position in the tree (the
                    207: .Va parent ,
                    208: .Va child ,
                    209: .Va next
                    210: and
                    211: .Va prev
                    212: fields) and some type-specific data.
                    213: .\" PARAGRAPH
                    214: .Pp
                    215: The tree itself is arranged according to the following normal form,
                    216: where capitalised non-terminals represent nodes.
                    217: .Pp
                    218: .Bl -tag -width "ELEMENTXX" -compact -offset "XXXX"
                    219: .\" LIST-ITEM
                    220: .It ROOT
                    221: \(<- mnode+
                    222: .It mnode
                    223: \(<- ELEMENT | TEXT
                    224: .It ELEMENT
                    225: \(<- ELEMENT | TEXT*
                    226: .It TEXT
                    227: \(<- [[:alpha:]]*
                    228: .El
                    229: .\" PARAGRAPH
                    230: .Pp
                    231: The only elements capable of nesting other elements are those with
                    232: next-lint scope as documented in
                    233: .Xr man 7 .
                    234: .\" SECTION
                    235: .Sh EXAMPLES
                    236: The following example reads lines from stdin and parses them, operating
                    237: on the finished parse tree with
                    238: .Fn parsed .
                    239: Note that, if the last line of the file isn't newline-terminated, this
                    240: will truncate the file's last character (see
                    241: .Xr fgetln 3 ) .
                    242: Further, this example does not error-check nor free memory upon failure.
                    243: .Bd -literal -offset "XXXX"
                    244: struct man *man;
                    245: struct man_node *node;
                    246: char *buf;
                    247: size_t len;
                    248: int line;
                    249:
                    250: line = 1;
                    251: man = man_alloc(NULL, 0, NULL);
                    252:
                    253: while ((buf = fgetln(fp, &len))) {
                    254:        buf[len - 1] = '\\0';
                    255:        if ( ! man_parseln(man, line, buf))
                    256:                errx(1, "man_parseln");
                    257:        line++;
                    258: }
                    259:
                    260: if ( ! man_endparse(man))
                    261:        errx(1, "man_endparse");
                    262: if (NULL == (node = man_node(man)))
                    263:        errx(1, "man_node");
                    264:
                    265: parsed(man, node);
                    266: man_free(man);
                    267: .Ed
                    268: .\" SECTION
                    269: .Sh SEE ALSO
                    270: .Xr mandoc 1 ,
                    271: .Xr man 7
                    272: .\" SECTION
                    273: .Sh AUTHORS
                    274: The
                    275: .Nm
                    276: utility was written by
1.5     ! kristaps  277: .An Kristaps Dzonsons Aq kristaps@kth.se .

CVSweb