Annotation of mandoc/roff.3, Revision 1.3
1.3 ! kristaps 1: .\" $Id: roff.3,v 1.2 2010/06/26 15:22:19 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.3 ! kristaps 17: .Dd $Mdocdate: June 26 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 *"
1.3 ! kristaps 33: .Fo roff_alloc
! 34: .Fa "struct regset *regs"
! 35: .Fa "mandocmsg msgs"
! 36: .Fa "void *data"
! 37: .Fc
1.1 kristaps 38: .Ft int
39: .Fn roff_endparse "struct roff *roff"
40: .Ft void
41: .Fn roff_free "struct roff *roff"
42: .Ft "enum rofferr"
43: .Fo roff_parseln
44: .Fa "struct roff *roff"
45: .Fa "int line"
46: .Fa "char **bufp"
47: .Fa "size_t *bufsz"
48: .Fa "int pos"
49: .Fa "int *offs"
50: .Fc
51: .Ft void
52: .Fn roff_reset "struct roff *roff"
53: .Sh DESCRIPTION
54: The
55: .Nm
56: library processes lines of
57: .Xr roff 7
58: input.
59: .Pp
60: In general, applications initiate a parsing sequence with
61: .Fn roff_alloc ,
62: parse each line in a document with
63: .Fn roff_parseln ,
64: close the parsing session with
65: .Fn roff_endparse ,
66: and finally free all allocated memory with
67: .Fn roff_free .
68: The
69: .Fn roff_reset
70: function may be used in order to reset the parser for another input
71: sequence.
72: .Pp
73: The
74: .Fn roff_parseln
75: function should be invoked before passing a line into the
76: .Xr mdoc 3
77: or
78: .Xr man 3
79: libraries.
80: .Pp
81: See the
82: .Sx EXAMPLES
83: section for a full example.
84: .Sh REFERENCE
85: This section further defines the
86: .Sx Types
87: and
88: .Sx Functions
89: available to programmers.
90: .Ss Types
91: Functions (see
92: .Sx Functions )
93: may use the following types:
94: .Bl -ohang
95: .It Vt "enum rofferr"
96: Instructions for further processing to the caller of
97: .Fn roff_parseln .
98: .It Vt struct roff
99: An opaque type defined in
100: .Pa roff.c .
101: Its values are only used privately within the library.
102: .It Vt mandocmsg
103: A function callback type defined in
104: .Pa mandoc.h .
105: .El
106: .Ss Functions
107: Function descriptions follow:
108: .Bl -ohang
109: .It Fn roff_alloc
110: Allocates a parsing structure.
111: The
112: .Fa data
113: pointer is passed to
114: .Fa msgs .
115: The
116: .Fa pflags
117: arguments are defined in
118: .Pa roff.h .
119: Returns NULL on failure.
120: If non-NULL, the pointer must be freed with
121: .Fn roff_free .
122: .It Fn roff_reset
123: Reset the parser for another parse routine.
124: After its use,
125: .Fn roff_parseln
126: behaves as if invoked for the first time.
127: .It Fn roff_free
128: Free all resources of a parser.
129: The pointer is no longer valid after invocation.
130: .It Fn roff_parseln
131: Parse a nil-terminated line of input.
132: The character array
133: .Fa bufp
134: may be modified or reallocated within this function.
135: In the latter case,
136: .Fa bufsz
137: will be modified accordingly.
138: The
139: .Fa offs
140: pointer will be modified if the line start during subsequent processing
141: of the line is not at the zeroth index.
142: This line should not contain the trailing newline.
143: Returns 0 on failure, 1 on success.
144: .It Fn roff_endparse
145: Signals that the parse is complete.
146: Returns 0 on failure, 1 on success.
147: .El
148: .Sh EXAMPLES
149: See
150: .Pa main.c
151: in the source distribution for an example of usage.
152: .Sh SEE ALSO
153: .Xr mandoc 1 ,
154: .Xr man 3 ,
155: .Xr mdoc 3 ,
156: .Xr roff 7
157: .Sh AUTHORS
158: The
159: .Nm
160: library was written by
161: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb