Return to mdoc.3 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/mdoc.3, Revision 1.3

1.1       kristaps    1: .\"
                      2: .Dd $Mdocdate$
                      3: .Dt mdoc 3
                      4: .Os
                      5: .\"
                      6: .Sh NAME
                      7: .Nm mdoc_alloc ,
                      8: .Nm mdoc_parseln ,
                      9: .Nm mdoc_endparse ,
                     10: .Nm mdoc_result ,
                     11: .Nm mdoc_free
1.2       kristaps   12: .Nd mdoc macro compiler library
1.1       kristaps   13: .\"
                     14: .Sh SYNOPSIS
                     15: .In mdoc.h
                     16: .Ft "struct mdoc *"
                     17: .Fn mdoc_alloc "void *data" "const struct mdoc_cb *cb"
                     18: .Ft void
1.2       kristaps   19: .Fn mdoc_free "struct mdoc *mdoc"
1.1       kristaps   20: .Ft int
1.2       kristaps   21: .Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
1.1       kristaps   22: .Ft "const struct mdoc_node *"
1.2       kristaps   23: .Fn mdoc_result "struct mdoc *mdoc"
1.1       kristaps   24: .Ft int
1.2       kristaps   25: .Fn mdoc_endparse "struct mdoc *mdoc"
1.1       kristaps   26: .\"
                     27: .Sh DESCRIPTION
                     28: The
                     29: .Nm mdoc
                     30: library parses lines of mdoc-macro text into an abstract syntax tree.
                     31: In general, applications initiate a parsing sequence with
                     32: .Fn mdoc_alloc ,
                     33: parse each line in a document with
                     34: .Fn mdoc_parseln ,
                     35: close the parsing session with
                     36: .Fn mdoc_endparse ,
                     37: operate over the syntax tree returned by
                     38: .Fn mdoc_result ,
                     39: then free all allocated memory with
                     40: .Fn mdoc_free .
                     41: See the
                     42: .Sx EXAMPLES
                     43: section for a full example.
1.2       kristaps   44: .Pp
                     45: Function descriptions follow:
                     46: .Bl -ohang -offset indent
                     47: .It Fn mdoc_alloc
                     48: Allocates a parsing structure.  The
                     49: .Fa data
                     50: pointer is passed to callbacks in
                     51: .Fa cb ,
                     52: which are documented further in the header file.  Returns NULL on
                     53: failure.  If non-NULL, the pointer must be freed with
                     54: .Fn mdoc_free .
                     55: .It Fn mdoc_free
                     56: Free all resources of a parser.  The pointer is no longer valid after
                     57: invocation.
                     58: .It Fn mdoc_parseln
                     59: Parse a nil-terminated line of input.  This line should not contain the
                     60: trailing newline.  Returns 0 on failure, 1 on success.  The input buffer
                     61: .Fa buf
                     62: is modified by this function.
                     63: .It Fn mdoc_endparse
                     64: Signals that the parse is complete.  Note that if
                     65: .Fn mdoc_endparse
                     66: is called subsequent to
                     67: .Fn mdoc_result ,
                     68: the resulting tree is incomplete.  Returns 0 on failure, 1 on success.
                     69: .It Fn mdoc_result
                     70: Returns the result of the parse or NULL on failure.  Note that if
                     71: .Fn mdoc_parseln
                     72: or
                     73: .Fn mdoc_endparse
                     74: return 0, the tree will be incomplete.
                     75: .El
                     76: .Pp
                     77: .Nm
                     78: is
                     79: .Ud
                     80: .\"
                     81: .Sh EXAMPLES
                     82: The following example reads lines from stdin and parses them, operating
                     83: on the finished parse tree with
                     84: .Fn parsed .
                     85: Note that, if the last line of the file isn't newline-terminated, this
                     86: will truncate the file's last character (see
                     87: .Xr fgetln 3 ) .
                     88: Further, this example does not error-check nor free memory upon failure.
                     89: .Bd -literal
                     90: struct mdoc *mdoc;
                     91: struct mdoc_node *node;
                     92: char *buf;
                     93: size_t len;
                     94: int line;
                     95:
                     96: line = 1;
                     97: mdoc = mdoc_alloc(NULL, NULL);
                     98:
                     99: while ((buf = fgetln(fp, &len))) {
                    100:        buf[len - 1] = '\\0';
                    101:        if ( ! mdoc_parseln(mdoc, line, buf))
                    102:                errx(1, "mdoc_parseln");
                    103:        line++;
                    104: }
                    105:
                    106: if ( ! mdoc_endparse(mdoc))
                    107:        errx(1, "mdoc_endparse");
                    108: if (NULL == (node = mdoc_result(mdoc)))
                    109:        errx(1, "mdoc_result");
                    110:
                    111: parsed(mdoc, node);
                    112: mdoc_free(mdoc);
                    113: .Ed
                    114: .\"
                    115: .Sh SEE ALSO
                    116: .Xr mdoc 7 ,
                    117: .Xr mdoc.samples 7 ,
                    118: .Xr groff 1 ,
                    119: .Xr mdocml 1
                    120: .\"
                    121: .\"
                    122: .Sh AUTHORS
                    123: The
                    124: .Nm
                    125: utility was written by
                    126: .An Kristaps Dzonsons Aq kristaps@kth.se .
                    127: .\"
                    128: .\"
                    129: .Sh BUGS
1.3     ! kristaps  130: Both bugs and incompabilities are documented in this section.  An
        !           131: incompatible macro or behaviour is relative to the default
        !           132: .Xr groff 1
        !           133: system bundled with
        !           134: .Ox .
        !           135: .Pp
1.2       kristaps  136: The
                    137: .Sq \&Xc
                    138: and
                    139: .Sq \&Xo
                    140: macros aren't handled when used to span lines for the
                    141: .Sq \&It
                    142: macro.  Such usage is specifically discouraged in
                    143: .Xr mdoc.samples 7 .
                    144: .Pp
                    145: When
                    146: .Sq \&It \-column
                    147: is invoked, whitespace is not stripped around
                    148: .Sq \&Ta
                    149: or tab-character separators.
1.3     ! kristaps  150: .Pp
        !           151: The
        !           152: .Sq \&At
        !           153: macro only accepts a single parameter.