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