Annotation of mandoc/roff.3, Revision 1.2
1.2 ! kristaps 1: .\" $Id: roff.3,v 1.1 2010/05/25 22:16:59 kristaps Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16: .\"
1.2 ! kristaps 17: .Dd $Mdocdate: May 25 2010 $
1.1 kristaps 18: .Dt ROFF 3
19: .Os
20: .Sh NAME
21: .Nm roff ,
22: .Nm roff_alloc ,
23: .Nm roff_endparse ,
24: .Nm roff_free ,
25: .Nm roff_parseln ,
26: .Nm roff_reset
27: .Nd roff macro compiler library
28: .Sh SYNOPSIS
29: .In mandoc.h
1.2 ! kristaps 30: .In regs.h
1.1 kristaps 31: .In roff.h
32: .Ft "struct roff *"
33: .Fn roff_alloc "mandocmsg msgs" "void *data"
34: .Ft int
35: .Fn roff_endparse "struct roff *roff"
36: .Ft void
37: .Fn roff_free "struct roff *roff"
38: .Ft "enum rofferr"
39: .Fo roff_parseln
40: .Fa "struct roff *roff"
41: .Fa "int line"
42: .Fa "char **bufp"
43: .Fa "size_t *bufsz"
44: .Fa "int pos"
45: .Fa "int *offs"
46: .Fc
47: .Ft void
48: .Fn roff_reset "struct roff *roff"
49: .Sh DESCRIPTION
50: The
51: .Nm
52: library processes lines of
53: .Xr roff 7
54: input.
55: .Pp
56: In general, applications initiate a parsing sequence with
57: .Fn roff_alloc ,
58: parse each line in a document with
59: .Fn roff_parseln ,
60: close the parsing session with
61: .Fn roff_endparse ,
62: and finally free all allocated memory with
63: .Fn roff_free .
64: The
65: .Fn roff_reset
66: function may be used in order to reset the parser for another input
67: sequence.
68: .Pp
69: The
70: .Fn roff_parseln
71: function should be invoked before passing a line into the
72: .Xr mdoc 3
73: or
74: .Xr man 3
75: libraries.
76: .Pp
77: See the
78: .Sx EXAMPLES
79: section for a full example.
80: .Sh REFERENCE
81: This section further defines the
82: .Sx Types
83: and
84: .Sx Functions
85: available to programmers.
86: .Ss Types
87: Functions (see
88: .Sx Functions )
89: may use the following types:
90: .Bl -ohang
91: .It Vt "enum rofferr"
92: Instructions for further processing to the caller of
93: .Fn roff_parseln .
94: .It Vt struct roff
95: An opaque type defined in
96: .Pa roff.c .
97: Its values are only used privately within the library.
98: .It Vt mandocmsg
99: A function callback type defined in
100: .Pa mandoc.h .
101: .El
102: .Ss Functions
103: Function descriptions follow:
104: .Bl -ohang
105: .It Fn roff_alloc
106: Allocates a parsing structure.
107: The
108: .Fa data
109: pointer is passed to
110: .Fa msgs .
111: The
112: .Fa pflags
113: arguments are defined in
114: .Pa roff.h .
115: Returns NULL on failure.
116: If non-NULL, the pointer must be freed with
117: .Fn roff_free .
118: .It Fn roff_reset
119: Reset the parser for another parse routine.
120: After its use,
121: .Fn roff_parseln
122: behaves as if invoked for the first time.
123: .It Fn roff_free
124: Free all resources of a parser.
125: The pointer is no longer valid after invocation.
126: .It Fn roff_parseln
127: Parse a nil-terminated line of input.
128: The character array
129: .Fa bufp
130: may be modified or reallocated within this function.
131: In the latter case,
132: .Fa bufsz
133: will be modified accordingly.
134: The
135: .Fa offs
136: pointer will be modified if the line start during subsequent processing
137: of the line is not at the zeroth index.
138: This line should not contain the trailing newline.
139: Returns 0 on failure, 1 on success.
140: .It Fn roff_endparse
141: Signals that the parse is complete.
142: Returns 0 on failure, 1 on success.
143: .El
144: .Sh EXAMPLES
145: See
146: .Pa main.c
147: in the source distribution for an example of usage.
148: .Sh SEE ALSO
149: .Xr mandoc 1 ,
150: .Xr man 3 ,
151: .Xr mdoc 3 ,
152: .Xr roff 7
153: .Sh AUTHORS
154: The
155: .Nm
156: library was written by
157: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb