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.
CVSweb