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