Return to mdoc.3 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/mdoc.3, Revision 1.2

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
        !           130: The
        !           131: .Sq \&Xc
        !           132: and
        !           133: .Sq \&Xo
        !           134: macros aren't handled when used to span lines for the
        !           135: .Sq \&It
        !           136: macro.  Such usage is specifically discouraged in
        !           137: .Xr mdoc.samples 7 .
        !           138: .Pp
        !           139: When
        !           140: .Sq \&It \-column
        !           141: is invoked, whitespace is not stripped around
        !           142: .Sq \&Ta
        !           143: or tab-character separators.