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

Annotation of mandoc/man.3, Revision 1.21

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

CVSweb