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