Annotation of mandoc/mdoc.3, Revision 1.4
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.
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mdoc.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc