Annotation of mandoc/roff.3, Revision 1.5
1.5 ! schwarze 1: .\" $Id: roff.3,v 1.4 2010/07/03 16:02:12 schwarze Exp $
1.1 kristaps 2: .\"
3: .\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
1.5 ! schwarze 4: .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
1.1 kristaps 5: .\"
6: .\" Permission to use, copy, modify, and distribute this software for any
7: .\" purpose with or without fee is hereby granted, provided that the above
8: .\" copyright notice and this permission notice appear in all copies.
9: .\"
10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17: .\"
1.5 ! schwarze 18: .Dd $Mdocdate: July 3 2010 $
1.1 kristaps 19: .Dt ROFF 3
20: .Os
21: .Sh NAME
22: .Nm roff ,
23: .Nm roff_alloc ,
24: .Nm roff_endparse ,
25: .Nm roff_free ,
26: .Nm roff_parseln ,
27: .Nm roff_reset
28: .Nd roff macro compiler library
29: .Sh SYNOPSIS
30: .In mandoc.h
1.2 kristaps 31: .In regs.h
1.1 kristaps 32: .In roff.h
33: .Ft "struct roff *"
1.3 kristaps 34: .Fo roff_alloc
35: .Fa "struct regset *regs"
36: .Fa "mandocmsg msgs"
37: .Fa "void *data"
38: .Fc
1.1 kristaps 39: .Ft int
40: .Fn roff_endparse "struct roff *roff"
41: .Ft void
42: .Fn roff_free "struct roff *roff"
43: .Ft "enum rofferr"
44: .Fo roff_parseln
45: .Fa "struct roff *roff"
46: .Fa "int line"
47: .Fa "char **bufp"
48: .Fa "size_t *bufsz"
49: .Fa "int pos"
50: .Fa "int *offs"
51: .Fc
52: .Ft void
53: .Fn roff_reset "struct roff *roff"
1.4 schwarze 54: .In regs.h
55: .Ft "char *"
56: .Fn roff_setstr "const char *name" "const char *string"
57: .Ft "char *"
58: .Fn roff_getstr "const char *name"
59: .Ft "char *"
60: .Fn roff_getstrn "const char *name" "size_t len"
61: .Ft void
62: .Fn roff_freestr void
1.1 kristaps 63: .Sh DESCRIPTION
64: The
65: .Nm
66: library processes lines of
67: .Xr roff 7
68: input.
69: .Pp
70: In general, applications initiate a parsing sequence with
71: .Fn roff_alloc ,
72: parse each line in a document with
73: .Fn roff_parseln ,
74: close the parsing session with
75: .Fn roff_endparse ,
76: and finally free all allocated memory with
77: .Fn roff_free .
78: The
79: .Fn roff_reset
80: function may be used in order to reset the parser for another input
81: sequence.
82: .Pp
83: The
84: .Fn roff_parseln
85: function should be invoked before passing a line into the
86: .Xr mdoc 3
87: or
88: .Xr man 3
89: libraries.
90: .Pp
91: See the
92: .Sx EXAMPLES
93: section for a full example.
94: .Sh REFERENCE
95: This section further defines the
96: .Sx Types
97: and
98: .Sx Functions
99: available to programmers.
100: .Ss Types
101: Functions (see
102: .Sx Functions )
103: may use the following types:
104: .Bl -ohang
105: .It Vt "enum rofferr"
106: Instructions for further processing to the caller of
107: .Fn roff_parseln .
108: .It Vt struct roff
109: An opaque type defined in
110: .Pa roff.c .
111: Its values are only used privately within the library.
112: .It Vt mandocmsg
113: A function callback type defined in
114: .Pa mandoc.h .
115: .El
116: .Ss Functions
117: Function descriptions follow:
118: .Bl -ohang
119: .It Fn roff_alloc
120: Allocates a parsing structure.
121: The
122: .Fa data
123: pointer is passed to
124: .Fa msgs .
125: The
126: .Fa pflags
127: arguments are defined in
128: .Pa roff.h .
129: Returns NULL on failure.
130: If non-NULL, the pointer must be freed with
131: .Fn roff_free .
132: .It Fn roff_reset
133: Reset the parser for another parse routine.
134: After its use,
135: .Fn roff_parseln
136: behaves as if invoked for the first time.
137: .It Fn roff_free
138: Free all resources of a parser.
139: The pointer is no longer valid after invocation.
140: .It Fn roff_parseln
141: Parse a nil-terminated line of input.
142: The character array
143: .Fa bufp
144: may be modified or reallocated within this function.
145: In the latter case,
146: .Fa bufsz
147: will be modified accordingly.
148: The
149: .Fa offs
150: pointer will be modified if the line start during subsequent processing
151: of the line is not at the zeroth index.
152: This line should not contain the trailing newline.
153: Returns 0 on failure, 1 on success.
154: .It Fn roff_endparse
155: Signals that the parse is complete.
156: Returns 0 on failure, 1 on success.
157: .El
1.4 schwarze 158: .Sh USER-DEFINED STRINGS
159: Strings defined by the
160: .Xr roff 7
161: .Sx \&ds
162: instruction are saved using the
163: .Fn roff_setstr
164: function and retrieved using the
165: .Fn roff_getstr
166: and
167: .Fn roff_getstrn
168: functions.
169: .Pp
170: These functions take the name of the string to be accessed
171: as their first argument.
172: While
173: .Fn roff_getstr
174: requires the name to be null-terminated,
175: .Fn roff_getstrn
176: accepts non-terminated strings, but requires the length of the name
177: to be specified.
178: .Pp
179: The second argument to
180: .Fn roff_setstr
181: is the new value of the string.
182: It will be copied to internal storage, so both pointers to constant
183: strings and pointers to volatile storage are acceptable.
184: .Pp
185: All of these functions return a pointer to the new value of the string
186: in internal storage, which should be considered read-only, so use
187: .Xr strdup 3
188: on it as appropriate.
189: The read functions return NULL when a string of the specified name
190: is not available or empty, and
191: .Fn roff_setstr
192: returns NULL when memory allocation fails.
193: In the latter case, the string will remain unset.
194: .Pp
195: The function
196: .Fn roff_freestr
197: clears all user-defined strings.
198: It always succeeds.
199: Both
200: .Fn roff_reset
201: and
202: .Fn roff_free
203: call it.
1.1 kristaps 204: .Sh EXAMPLES
205: See
206: .Pa main.c
207: in the source distribution for an example of usage.
208: .Sh SEE ALSO
209: .Xr mandoc 1 ,
210: .Xr man 3 ,
211: .Xr mdoc 3 ,
212: .Xr roff 7
213: .Sh AUTHORS
214: The
215: .Nm
216: library was written by
217: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
1.4 schwarze 218: .Sh BUGS
219: The implementation of user-defined strings needs improvement:
220: .Bl -dash
221: .It
222: String values are taken literally and are not interpreted.
223: .It
224: Parsing of quoted strings is incomplete.
225: .It
226: The stings are stored internally using a singly linked list,
227: which is fine for small numbers of strings,
228: but ineffient when handling many strings.
229: .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