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