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

Annotation of mandoc/man.3, Revision 1.15

1.15    ! kristaps    1: .\"    $Id: man.3,v 1.14 2010/03/30 19:20:33 kristaps Exp $
1.1       kristaps    2: .\"
1.12      kristaps    3: .\" Copyright (c) 2009-2010 Kristaps Dzonsons <kristaps@bsd.lv>
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: .\"
1.15    ! kristaps   17: .Dd $Mdocdate: March 30 2010 $
1.2       kristaps   18: .Dt MAN 3
1.1       kristaps   19: .Os
1.13      kristaps   20: .
                     21: .
1.1       kristaps   22: .Sh NAME
1.13      kristaps   23: .Nm man ,
1.1       kristaps   24: .Nm man_alloc ,
                     25: .Nm man_parseln ,
                     26: .Nm man_endparse ,
                     27: .Nm man_node ,
                     28: .Nm man_meta ,
                     29: .Nm man_free ,
                     30: .Nm man_reset
                     31: .Nd man macro compiler library
1.13      kristaps   32: .
                     33: .
1.1       kristaps   34: .Sh SYNOPSIS
1.10      kristaps   35: .In man.h
1.1       kristaps   36: .Vt extern const char * const * man_macronames;
                     37: .Ft "struct man *"
                     38: .Fn man_alloc "void *data" "int pflags" "const struct man_cb *cb"
                     39: .Ft void
                     40: .Fn man_reset "struct man *man"
                     41: .Ft void
                     42: .Fn man_free "struct man *man"
                     43: .Ft int
                     44: .Fn man_parseln "struct man *man" "int line" "char *buf"
                     45: .Ft "const struct man_node *"
1.6       kristaps   46: .Fn man_node "const struct man *man"
1.1       kristaps   47: .Ft "const struct man_meta *"
1.6       kristaps   48: .Fn man_meta "const struct man *man"
1.1       kristaps   49: .Ft int
                     50: .Fn man_endparse "struct man *man"
1.13      kristaps   51: .
                     52: .
1.1       kristaps   53: .Sh DESCRIPTION
                     54: The
1.13      kristaps   55: .Nm
1.7       kristaps   56: library parses lines of
1.1       kristaps   57: .Xr man 7
                     58: input (and
                     59: .Em only
                     60: man) into an abstract syntax tree (AST).
1.13      kristaps   61: .
1.1       kristaps   62: .Pp
                     63: In general, applications initiate a parsing sequence with
                     64: .Fn man_alloc ,
1.7       kristaps   65: parse each line in a document with
1.1       kristaps   66: .Fn man_parseln ,
                     67: close the parsing session with
                     68: .Fn man_endparse ,
                     69: operate over the syntax tree returned by
1.7       kristaps   70: .Fn man_node
1.1       kristaps   71: and
                     72: .Fn man_meta ,
                     73: then free all allocated memory with
                     74: .Fn man_free .
                     75: The
                     76: .Fn man_reset
                     77: function may be used in order to reset the parser for another input
                     78: sequence.  See the
                     79: .Sx EXAMPLES
                     80: section for a full example.
1.13      kristaps   81: .
                     82: .Pp
                     83: Beyond the full set of macros defined in
                     84: .Xr man 7 ,
                     85: the
                     86: .Nm
                     87: library also accepts the following macros:
                     88: .
1.1       kristaps   89: .Pp
1.13      kristaps   90: .Bl -tag -width Ds -compact
                     91: .It am
                     92: .It ami
                     93: .It de
                     94: .It dei
                     95: .It ig
                     96: Instructional macros in the original roff language.  Blocks begun by
                     97: these macros end with
                     98: .Sq ..
                     99: and may begin anywhere, although they may not break the next-line
                    100: scoping rules specified in
                    101: .Xr man 7 .
                    102: These blocks are discarded.
                    103: .
                    104: .It PD
                    105: Has no effect.  Handled as a current-scope line macro.
                    106: .
                    107: .It Sp
                    108: A synonym for
                    109: .Sq sp 0.5v
                    110: .Pq part of the standard preamble for Perl documentation .
                    111: Handled as a line macro.
                    112: .
                    113: .It UC
                    114: Has no effect.  Handled as a current-scope line macro.
                    115: .
                    116: .It Vb
                    117: A synonym for
                    118: .Sq nf
                    119: .Pq part of the standard preamble for Perl documentation .
                    120: Handled as a current-scope line macro.
                    121: .
                    122: .It Ve
                    123: A synonym for
                    124: .Sq fi ,
                    125: closing
                    126: .Sq Vb
                    127: .Pq part of the standard preamble for Perl documentation .
                    128: Handled as a current-scope line macro.
                    129: .El
1.14      kristaps  130: .Pp
                    131: Furthermore, the following escapes are accepted to allow
                    132: .Xr pod2man 1
1.15    ! kristaps  133: documents to be correctly formatted:
1.14      kristaps  134: \e*(-- (dash),
                    135: \e*(PI (pi),
                    136: \e*(L" (left double-quote),
                    137: \e*(R" (right double-quote),
                    138: \e*(C+ (C++),
                    139: \e*(C` (left single-quote),
                    140: \e*(C' (right single-quote),
                    141: \e*(Aq (apostrophe),
                    142: \e*^ (hat),
                    143: \e*, (comma),
                    144: \e*~ (tilde),
                    145: \e*/ (forward slash),
                    146: \e*: (umlaut),
                    147: \e*8 (beta),
                    148: \e*o (degree),
                    149: \e*(D- (Eth),
                    150: \e*(d- (eth),
                    151: \e*(Th (Thorn),
                    152: and
                    153: \e*(th (thorn).
1.13      kristaps  154: .
                    155: .
                    156: .Sh REFERENCE
1.7       kristaps  157: This section further defines the
1.1       kristaps  158: .Sx Types ,
1.7       kristaps  159: .Sx Functions
1.1       kristaps  160: and
                    161: .Sx Variables
                    162: available to programmers.  Following that, the
1.7       kristaps  163: .Sx Abstract Syntax Tree
1.1       kristaps  164: section documents the output tree.
1.13      kristaps  165: .
                    166: .
1.1       kristaps  167: .Ss Types
                    168: Both functions (see
                    169: .Sx Functions )
                    170: and variables (see
                    171: .Sx Variables )
                    172: may use the following types:
1.12      kristaps  173: .Bl -ohang
1.13      kristaps  174: .
1.1       kristaps  175: .It Vt struct man
                    176: An opaque type defined in
                    177: .Pa man.c .
                    178: Its values are only used privately within the library.
1.13      kristaps  179: .
1.1       kristaps  180: .It Vt struct man_cb
                    181: A set of message callbacks defined in
                    182: .Pa man.h .
1.13      kristaps  183: .
1.1       kristaps  184: .It Vt struct man_node
                    185: A parsed node.  Defined in
                    186: .Pa man.h .
1.7       kristaps  187: See
1.1       kristaps  188: .Sx Abstract Syntax Tree
                    189: for details.
                    190: .El
1.13      kristaps  191: .
                    192: .
1.1       kristaps  193: .Ss Functions
                    194: Function descriptions follow:
1.12      kristaps  195: .Bl -ohang
1.13      kristaps  196: .
1.1       kristaps  197: .It Fn man_alloc
                    198: Allocates a parsing structure.  The
                    199: .Fa data
                    200: pointer is passed to callbacks in
1.7       kristaps  201: .Fa cb ,
                    202: which are documented further in the header file.
1.1       kristaps  203: The
                    204: .Fa pflags
                    205: arguments are defined in
                    206: .Pa man.h .
                    207: Returns NULL on failure.  If non-NULL, the pointer must be freed with
                    208: .Fn man_free .
1.13      kristaps  209: .
1.1       kristaps  210: .It Fn man_reset
1.7       kristaps  211: Reset the parser for another parse routine.  After its use,
1.1       kristaps  212: .Fn man_parseln
                    213: behaves as if invoked for the first time.
1.13      kristaps  214: .
1.1       kristaps  215: .It Fn man_free
                    216: Free all resources of a parser.  The pointer is no longer valid after
                    217: invocation.
1.13      kristaps  218: .
1.1       kristaps  219: .It Fn man_parseln
                    220: Parse a nil-terminated line of input.  This line should not contain the
1.7       kristaps  221: trailing newline.  Returns 0 on failure, 1 on success.  The input buffer
1.1       kristaps  222: .Fa buf
                    223: is modified by this function.
1.13      kristaps  224: .
1.1       kristaps  225: .It Fn man_endparse
1.7       kristaps  226: Signals that the parse is complete.  Note that if
1.1       kristaps  227: .Fn man_endparse
                    228: is called subsequent to
                    229: .Fn man_node ,
                    230: the resulting tree is incomplete.  Returns 0 on failure, 1 on success.
1.13      kristaps  231: .
1.1       kristaps  232: .It Fn man_node
1.7       kristaps  233: Returns the first node of the parse.  Note that if
1.1       kristaps  234: .Fn man_parseln
                    235: or
                    236: .Fn man_endparse
                    237: return 0, the tree will be incomplete.
                    238: .It Fn man_meta
                    239: Returns the document's parsed meta-data.  If this information has not
1.7       kristaps  240: yet been supplied or
1.1       kristaps  241: .Fn man_parseln
                    242: or
                    243: .Fn man_endparse
                    244: return 0, the data will be incomplete.
                    245: .El
1.13      kristaps  246: .
                    247: .
1.1       kristaps  248: .Ss Variables
                    249: The following variables are also defined:
1.12      kristaps  250: .Bl -ohang
1.13      kristaps  251: .
1.1       kristaps  252: .It Va man_macronames
                    253: An array of string-ified token names.
                    254: .El
1.13      kristaps  255: .
                    256: .
1.1       kristaps  257: .Ss Abstract Syntax Tree
1.7       kristaps  258: The
1.1       kristaps  259: .Nm
                    260: functions produce an abstract syntax tree (AST) describing input in a
                    261: regular form.  It may be reviewed at any time with
                    262: .Fn man_nodes ;
                    263: however, if called before
                    264: .Fn man_endparse ,
                    265: or after
1.7       kristaps  266: .Fn man_endparse
1.1       kristaps  267: or
                    268: .Fn man_parseln
1.7       kristaps  269: fail, it may be incomplete.
1.13      kristaps  270: .
1.1       kristaps  271: .Pp
                    272: This AST is governed by the ontological
                    273: rules dictated in
                    274: .Xr man 7
1.7       kristaps  275: and derives its terminology accordingly.
1.13      kristaps  276: .
1.1       kristaps  277: .Pp
1.7       kristaps  278: The AST is composed of
1.1       kristaps  279: .Vt struct man_node
                    280: nodes with element, root and text types as declared
                    281: by the
                    282: .Va type
                    283: field.  Each node also provides its parse point (the
                    284: .Va line ,
                    285: .Va sec ,
                    286: and
                    287: .Va pos
                    288: fields), its position in the tree (the
                    289: .Va parent ,
                    290: .Va child ,
1.7       kristaps  291: .Va next
1.1       kristaps  292: and
1.7       kristaps  293: .Va prev
1.1       kristaps  294: fields) and some type-specific data.
1.13      kristaps  295: .
1.1       kristaps  296: .Pp
                    297: The tree itself is arranged according to the following normal form,
                    298: where capitalised non-terminals represent nodes.
                    299: .Pp
1.12      kristaps  300: .Bl -tag -width "ELEMENTXX" -compact
1.1       kristaps  301: .It ROOT
                    302: \(<- mnode+
                    303: .It mnode
1.8       kristaps  304: \(<- ELEMENT | TEXT | BLOCK
                    305: .It BLOCK
                    306: \(<- HEAD BODY
                    307: .It HEAD
                    308: \(<- mnode*
                    309: .It BODY
                    310: \(<- mnode*
1.1       kristaps  311: .It ELEMENT
                    312: \(<- ELEMENT | TEXT*
                    313: .It TEXT
                    314: \(<- [[:alpha:]]*
                    315: .El
1.13      kristaps  316: .
1.1       kristaps  317: .Pp
                    318: The only elements capable of nesting other elements are those with
                    319: next-lint scope as documented in
                    320: .Xr man 7 .
1.13      kristaps  321: .
                    322: .
1.1       kristaps  323: .Sh EXAMPLES
                    324: The following example reads lines from stdin and parses them, operating
1.7       kristaps  325: on the finished parse tree with
1.1       kristaps  326: .Fn parsed .
1.12      kristaps  327: This example does not error-check nor free memory upon failure.
                    328: .Bd -literal -offset indent
1.1       kristaps  329: struct man *man;
                    330: struct man_node *node;
                    331: char *buf;
                    332: size_t len;
                    333: int line;
                    334:
                    335: line = 1;
                    336: man = man_alloc(NULL, 0, NULL);
1.12      kristaps  337: buf = NULL;
                    338: alloc_len = 0;
1.1       kristaps  339:
1.12      kristaps  340: while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
                    341:     if (len && buflen[len - 1] = '\en')
                    342:         buf[len - 1] = '\e0';
                    343:     if ( ! man_parseln(man, line, buf))
                    344:         errx(1, "man_parseln");
                    345:     line++;
1.1       kristaps  346: }
                    347:
1.12      kristaps  348: free(buf);
                    349:
1.1       kristaps  350: if ( ! man_endparse(man))
1.12      kristaps  351:     errx(1, "man_endparse");
1.1       kristaps  352: if (NULL == (node = man_node(man)))
1.12      kristaps  353:     errx(1, "man_node");
1.1       kristaps  354:
                    355: parsed(man, node);
                    356: man_free(man);
                    357: .Ed
1.13      kristaps  358: .
                    359: .
1.1       kristaps  360: .Sh SEE ALSO
                    361: .Xr mandoc 1 ,
                    362: .Xr man 7
1.13      kristaps  363: .
                    364: .
1.1       kristaps  365: .Sh AUTHORS
                    366: The
                    367: .Nm
1.7       kristaps  368: utility was written by
1.12      kristaps  369: .An Kristaps Dzonsons Aq kristaps@bsd.lv .

CVSweb