Annotation of mandoc/mdoc.3, Revision 1.5
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 ,
1.4 kristaps 10: .Nm mdoc_node ,
11: .Nm mdoc_meta ,
1.1 kristaps 12: .Nm mdoc_free
1.2 kristaps 13: .Nd mdoc macro compiler library
1.1 kristaps 14: .\"
15: .Sh SYNOPSIS
1.4 kristaps 16: .Fd #include <mdoc.h>
17: .Vt extern const char * const * mdoc_macronames;
18: .Vt extern const char * const * mdoc_argnames;
1.1 kristaps 19: .Ft "struct mdoc *"
20: .Fn mdoc_alloc "void *data" "const struct mdoc_cb *cb"
21: .Ft void
1.2 kristaps 22: .Fn mdoc_free "struct mdoc *mdoc"
1.1 kristaps 23: .Ft int
1.2 kristaps 24: .Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
1.1 kristaps 25: .Ft "const struct mdoc_node *"
1.4 kristaps 26: .Fn mdoc_node "struct mdoc *mdoc"
27: .Ft "const struct mdoc_meta *"
28: .Fn mdoc_meta "struct mdoc *mdoc"
1.1 kristaps 29: .Ft int
1.2 kristaps 30: .Fn mdoc_endparse "struct mdoc *mdoc"
1.1 kristaps 31: .\"
32: .Sh DESCRIPTION
33: The
34: .Nm mdoc
35: library parses lines of mdoc-macro text into an abstract syntax tree.
36: In general, applications initiate a parsing sequence with
37: .Fn mdoc_alloc ,
38: parse each line in a document with
39: .Fn mdoc_parseln ,
40: close the parsing session with
41: .Fn mdoc_endparse ,
42: operate over the syntax tree returned by
1.4 kristaps 43: .Fn mdoc_node
44: and
45: .Fn mdoc_meta ,
1.1 kristaps 46: then free all allocated memory with
47: .Fn mdoc_free .
48: See the
49: .Sx EXAMPLES
50: section for a full example.
1.2 kristaps 51: .Pp
1.4 kristaps 52: .\" Function descriptions.
1.2 kristaps 53: Function descriptions follow:
54: .Bl -ohang -offset indent
55: .It Fn mdoc_alloc
56: Allocates a parsing structure. The
57: .Fa data
58: pointer is passed to callbacks in
59: .Fa cb ,
60: which are documented further in the header file. Returns NULL on
61: failure. If non-NULL, the pointer must be freed with
62: .Fn mdoc_free .
63: .It Fn mdoc_free
64: Free all resources of a parser. The pointer is no longer valid after
65: invocation.
66: .It Fn mdoc_parseln
67: Parse a nil-terminated line of input. This line should not contain the
68: trailing newline. Returns 0 on failure, 1 on success. The input buffer
69: .Fa buf
70: is modified by this function.
71: .It Fn mdoc_endparse
72: Signals that the parse is complete. Note that if
73: .Fn mdoc_endparse
74: is called subsequent to
1.4 kristaps 75: .Fn mdoc_node ,
1.2 kristaps 76: the resulting tree is incomplete. Returns 0 on failure, 1 on success.
1.4 kristaps 77: .It Fn mdoc_node
78: Returns the first node of the parse. Note that if
1.2 kristaps 79: .Fn mdoc_parseln
80: or
81: .Fn mdoc_endparse
82: return 0, the tree will be incomplete.
1.4 kristaps 83: .It Fn mdoc_meta
84: Returns the document's parsed meta-data. If this information has not
85: yet been supplied or
86: .Fn mdoc_parseln
87: or
88: .Fn mdoc_endparse
89: return 0, the data will be incomplete.
90: .El
91: .Pp
92: .\" Variable descriptions.
93: The following variables are also defined:
94: .Bl -ohang -offset indent
95: .It Va mdoc_macronames
96: An array of string-ified token names.
97: .It Va mdoc_argnames
98: An array of string-ified token argument names.
1.2 kristaps 99: .El
100: .Pp
101: .Nm
102: is
103: .Ud
104: .\"
105: .Sh EXAMPLES
106: The following example reads lines from stdin and parses them, operating
107: on the finished parse tree with
108: .Fn parsed .
109: Note that, if the last line of the file isn't newline-terminated, this
110: will truncate the file's last character (see
111: .Xr fgetln 3 ) .
112: Further, this example does not error-check nor free memory upon failure.
113: .Bd -literal
114: struct mdoc *mdoc;
115: struct mdoc_node *node;
116: char *buf;
117: size_t len;
118: int line;
119:
120: line = 1;
121: mdoc = mdoc_alloc(NULL, NULL);
122:
123: while ((buf = fgetln(fp, &len))) {
124: buf[len - 1] = '\\0';
125: if ( ! mdoc_parseln(mdoc, line, buf))
126: errx(1, "mdoc_parseln");
127: line++;
128: }
129:
130: if ( ! mdoc_endparse(mdoc))
131: errx(1, "mdoc_endparse");
1.4 kristaps 132: if (NULL == (node = mdoc_node(mdoc)))
133: errx(1, "mdoc_node");
1.2 kristaps 134:
135: parsed(mdoc, node);
136: mdoc_free(mdoc);
137: .Ed
138: .\"
139: .Sh SEE ALSO
140: .Xr mdoc 7 ,
141: .Xr mdoc.samples 7 ,
142: .Xr groff 1 ,
143: .Xr mdocml 1
144: .\"
145: .\"
146: .Sh AUTHORS
147: The
148: .Nm
149: utility was written by
150: .An Kristaps Dzonsons Aq kristaps@kth.se .
151: .\"
152: .\"
153: .Sh BUGS
1.4 kristaps 154: Bugs, un-implemented macros and incompabilities are documented in this
155: section. The baseline for determining whether macro parsing is
156: .Qq incompatible
157: is the default
1.3 kristaps 158: .Xr groff 1
159: system bundled with
160: .Ox .
161: .Pp
1.4 kristaps 162: Un-implemented: the
1.2 kristaps 163: .Sq \&Xc
164: and
165: .Sq \&Xo
166: macros aren't handled when used to span lines for the
167: .Sq \&It
168: macro. Such usage is specifically discouraged in
169: .Xr mdoc.samples 7 .
170: .Pp
1.4 kristaps 171: Bugs: when
1.2 kristaps 172: .Sq \&It \-column
173: is invoked, whitespace is not stripped around
174: .Sq \&Ta
175: or tab-character separators.
1.3 kristaps 176: .Pp
1.4 kristaps 177: Incompatible: the
1.3 kristaps 178: .Sq \&At
1.4 kristaps 179: macro only accepts a single parameter. Furthermore, several macros
180: .Pf ( Sq \&Pp ,
181: .Sq \&It ,
182: and possibly others) accept multiple arguments with a warning.
1.5 ! kristaps 183: .Pp
! 184: Incompatible: only those macros specified by
! 185: .Xr mdoc.samples 7
! 186: and
! 187: .Xr mdoc 7
! 188: for
! 189: .Ox
! 190: are supported; support for
! 191: .Nx
! 192: and other BSD systems is in progress.
CVSweb