Annotation of mandoc/tbl.3, Revision 1.6
1.6 ! schwarze 1: .\" $Id: tbl.3,v 1.5 2018/12/13 02:06:07 schwarze Exp $
1.1 schwarze 2: .\"
1.5 schwarze 3: .\" Copyright (c) 2013, 2015, 2018 Ingo Schwarze <schwarze@openbsd.org>
1.1 schwarze 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.6 ! schwarze 17: .Dd $Mdocdate: December 13 2018 $
1.1 schwarze 18: .Dt TBL 3
19: .Os
20: .Sh NAME
21: .Nm tbl_alloc ,
22: .Nm tbl_read ,
23: .Nm tbl_restart ,
24: .Nm tbl_span ,
25: .Nm tbl_end ,
26: .Nm tbl_free
27: .Nd roff table parser library for mandoc
28: .Sh SYNOPSIS
1.5 schwarze 29: .In sys/types.h
1.4 schwarze 30: .In tbl.h
1.5 schwarze 31: .In tbl_parse.h
1.1 schwarze 32: .Ft struct tbl_node *
33: .Fo tbl_alloc
34: .Fa "int pos"
35: .Fa "int line"
36: .Fc
1.3 schwarze 37: .Ft void
1.1 schwarze 38: .Fo tbl_read
39: .Fa "struct tbl_node *tbl"
40: .Fa "int ln"
41: .Fa "const char *p"
42: .Fa "int offs"
43: .Fc
44: .Ft void
45: .Fo tbl_restart
46: .Fa "int line"
47: .Fa "int pos"
48: .Fa "struct tbl_node *tbl"
49: .Fc
50: .Ft const struct tbl_span *
51: .Fo tbl_span
52: .Fa "struct tbl_node *tbl"
53: .Fc
54: .Ft void
55: .Fo tbl_end
56: .Fa "struct tbl_node **tblp"
57: .Fc
58: .Ft void
59: .Fo tbl_free
60: .Fa "struct tbl_node *tbl"
61: .Fc
62: .Sh DESCRIPTION
63: This library is tightly integrated into the
64: .Xr mandoc 1
65: utility and not designed for stand-alone use.
66: The present manual is intended as a reference for developers working on
67: .Xr mandoc 1 .
68: .Ss Data structures
1.5 schwarze 69: Unless otherwise noted, all of the following data structures are declared in
70: .In tbl.h
1.1 schwarze 71: and are deleted in
72: .Fn tbl_free .
73: .Bl -tag -width Ds
74: .It Vt struct tbl_node
75: This structure describes a complete table.
1.5 schwarze 76: It is declared in
77: .In tbl_int.h ,
1.1 schwarze 78: created in
79: .Fn tbl_alloc ,
80: and stored in the members
1.2 schwarze 81: .Fa first_tbl ,
82: .Fa last_tbl ,
1.1 schwarze 83: and
1.2 schwarze 84: .Fa tbl
1.1 schwarze 85: of
86: .Vt struct roff Bq Pa roff.c .
1.2 schwarze 87: .Pp
88: The
89: .Fa first_span ,
90: .Fa current_span ,
91: .Fa last_span ,
92: and
93: .Fa next
94: members may be
95: .Dv NULL .
96: The
97: .Fa first_row
98: and
99: .Fa last_row
100: members may be
101: .Dv NULL ,
102: but if there is a span, the function
103: .Fn tbl_layout
104: guarantees that these pointers are not
105: .Dv NULL .
1.1 schwarze 106: .It Vt struct tbl_opts
107: This structure describes the options of one table.
108: It is used as a substructure of
109: .Vt struct tbl_node
110: and thus created and deleted together with it.
111: It is filled in
112: .Fn tbl_options .
113: .It Vt struct tbl_row
114: This structure describes one layout line in a table
115: by maintaining a list of all the cells in that line.
116: It is allocated and filled in
117: .Fn row Bq Pa tbl_layout.c
118: and referenced from the
1.2 schwarze 119: .Fa layout
1.1 schwarze 120: member of
121: .Vt struct tbl_node .
1.2 schwarze 122: .Pp
123: The
124: .Fa next
125: member may be
126: .Dv NULL .
127: The function
128: .Fn tbl_layout
129: guarantees that the
130: .Fa first
131: and
132: .Fa last
133: members are not NULL.
1.1 schwarze 134: .It Vt struct tbl_cell
135: This structure describes one layout cell in a table,
136: in particular its alignment, membership in spans, and
137: usage for lines.
138: It is allocated and filled in
139: .Fn cell_alloc Bq Pa tbl_layout.c
140: and referenced from the
1.2 schwarze 141: .Fa first
1.1 schwarze 142: and
1.2 schwarze 143: .Fa last
1.1 schwarze 144: members of
145: .Vt struct tbl_row .
1.2 schwarze 146: .Pp
147: The
148: .Fa next
149: member may be
150: .Dv NULL .
1.1 schwarze 151: .It Vt struct tbl_span
152: This structure describes one data line in a table
153: by maintaining a list of all data cells in that line
154: or by specifying that it is a horizontal line.
155: It is allocated and filled in
156: .Fn newspan Bq Pa tbl_data.c
157: which is called from
158: .Fn tbl_data
159: and referenced from the
1.2 schwarze 160: .Fa first_span ,
161: .Fa current_span ,
1.1 schwarze 162: and
1.2 schwarze 163: .Fa last_span
1.1 schwarze 164: members of
165: .Vt struct tbl_node ,
166: and from the
1.2 schwarze 167: .Fa span
1.1 schwarze 168: members of
169: .Vt struct man_node
170: and
171: .Vt struct mdoc_node
172: from
173: .In man.h
174: and
175: .In mdoc.h .
1.2 schwarze 176: .Pp
177: The
178: .Fa first ,
179: .Fa last ,
180: .Fa prev ,
181: and
182: .Fa next
183: members may be
184: .Dv NULL .
185: The function
186: .Fn newspan Bq Pa tbl_data.c
187: guarantees that the
188: .Fa opts
189: and
190: .Fa layout
191: members are not
192: .Dv NULL .
1.1 schwarze 193: .It Vt struct tbl_dat
194: This structure describes one data cell in a table by specifying
195: whether it contains a line or data, whether it spans additional
196: layout cells, and by storing the data.
197: It is allocated and filled in
1.2 schwarze 198: .Fn tbl_data
1.1 schwarze 199: and referenced from the
1.2 schwarze 200: .Fa first
1.1 schwarze 201: and
1.2 schwarze 202: .Fa last
1.1 schwarze 203: members of
204: .Vt struct tbl_span .
1.2 schwarze 205: .Pp
206: The
207: .Fa string
208: and
209: .Fa next
210: members may be
211: .Dv NULL .
212: The function
213: .Fn getdata
214: guarantees that the
215: .Fa layout
216: member is not
217: .Dv NULL .
1.1 schwarze 218: .El
219: .Ss Interface functions
220: The following functions are implemented in
221: .Pa tbl.c ,
1.5 schwarze 222: and all callers are in
1.1 schwarze 223: .Pa roff.c .
224: .Bl -tag -width Ds
225: .It Fn tbl_alloc
226: Allocates, initializes, and returns a new
227: .Vt struct tbl_node .
228: Called from
229: .Fn roff_TS .
230: .It Fn tbl_read
231: Dispatches to
232: .Fn tbl_option ,
233: .Fn tbl_layout ,
234: .Fn tbl_cdata ,
235: and
236: .Fn tbl_data ,
237: see below.
238: Called from
239: .Fn roff_parseln .
240: .It Fn tbl_restart
241: Resets the
1.2 schwarze 242: .Fa part
1.1 schwarze 243: member of
244: .Vt struct tbl_node
245: to
246: .Dv TBL_PART_LAYOUT .
247: Called from
248: .Fn roff_T_ .
249: .It Fn tbl_span
250: On the first call, return the first
251: .Vt struct tbl_span ;
252: for later calls, return the next one or
253: .Dv NULL .
254: Called from
255: .Fn roff_span .
256: .It Fn tbl_end
257: Flags the last span as
258: .Dv TBL_SPAN_LAST
259: and clears the pointer passed as an argment.
260: Called from
261: .Fn roff_TE
262: and
263: .Fn roff_endparse .
264: .It Fn tbl_free
265: Frees the specified
266: .Vt struct tbl_node
1.2 schwarze 267: and all the tbl_row, tbl_cell, tbl_span, and tbl_dat structures
1.1 schwarze 268: referenced from it.
269: Called from
270: .Fn roff_free
271: and
272: .Fn roff_reset .
273: .El
274: .Ss Private functions
1.5 schwarze 275: The following functions are declared in
276: .In tbl_int.h .
1.1 schwarze 277: .Bl -tag -width Ds
278: .It Ft int Fn tbl_options "struct tbl_node *tbl" "int ln" "const char *p"
279: Parses the options line into
280: .Vt struct tbl_opts .
281: Implemented in
282: .Pa tbl_opts.c ,
283: called from
284: .Fn tbl_read .
285: .It Ft int Fn tbl_layout "struct tbl_node *tbl" "int ln" "const char *p"
286: Allocates and fills one
287: .Vt struct tbl_row
1.2 schwarze 288: for each layout line and one
1.1 schwarze 289: .Vt struct tbl_cell
290: for each layout cell.
291: Implemented in
292: .Pa tbl_layout.c ,
293: called from
294: .Fn tbl_read .
295: .It Ft int Fn tbl_data "struct tbl_node *tbl" "int ln" "const char *p"
296: Allocates one
297: .Vt struct tbl_span
298: for each data line and calls
1.2 schwarze 299: .Fn getdata
300: for each data cell.
1.1 schwarze 301: Implemented in
302: .Pa tbl_data.c ,
303: called from
304: .Fn tbl_read .
305: .It Ft int Fn tbl_cdata "struct tbl_node *tbl" "int ln" "const char *p"
306: Continues parsing a data line:
307: When finding
308: .Sq T} ,
309: switches back to
310: .Dv TBL_PART_DATA
311: mode and calls
1.2 schwarze 312: .Fn getdata
1.1 schwarze 313: if there are more data cells on the line.
314: Otherwise, appends the data to the current data cell.
315: Implemented in
316: .Pa tbl_data.c ,
317: called from
318: .Fn tbl_read .
319: .It Xo
320: .Ft int
1.2 schwarze 321: .Fo getdata
1.1 schwarze 322: .Fa "struct tbl_node *tbl"
323: .Fa "struct tbl_span *dp"
324: .Fa "int ln"
325: .Fa "const char *p"
326: .Fa "int *pos"
327: .Fc
328: .Xc
329: Parses one data cell into one
330: .Vt struct tbl_dat .
331: Implemented in
332: .Pa tbl_data.c ,
333: called from
334: .Fn tbl_data
335: and
336: .Fn tbl_cdata .
337: .El
338: .Sh SEE ALSO
339: .Xr mandoc 1 ,
340: .Xr mandoc 3 ,
341: .Xr tbl 7
342: .Sh AUTHORS
343: .An -nosplit
344: The
345: .Nm tbl
346: library was written by
347: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
348: with contributions from
349: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
CVSweb