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