Annotation of mandoc/tbl.3, Revision 1.2
1.2 ! schwarze 1: .\" $Id: tbl.3,v 1.1 2013/06/01 05:44:39 schwarze Exp $
1.1 schwarze 2: .\"
3: .\" Copyright (c) 2013 Ingo Schwarze <schwarze@openbsd.org>
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.2 ! schwarze 17: .Dd $Mdocdate: June 1 2013 $
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
29: .In mandoc.h
30: .In libmandoc.h
31: .In libroff.h
32: .Ft struct tbl_node *
33: .Fo tbl_alloc
34: .Fa "int pos"
35: .Fa "int line"
36: .Fa "struct mparse *parse"
37: .Fc
38: .Ft enum rofferr
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
70: Unless otherwise noted, all of the following data structures are defined in
71: .In mandoc.h
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.
77: It is defined in
78: .In libroff.h ,
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 ,
229: and all callers in
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
282: .Bl -tag -width Ds
283: .It Ft int Fn tbl_options "struct tbl_node *tbl" "int ln" "const char *p"
284: Parses the options line into
285: .Vt struct tbl_opts .
286: Implemented in
287: .Pa tbl_opts.c ,
288: called from
289: .Fn tbl_read .
290: .It Ft int Fn tbl_layout "struct tbl_node *tbl" "int ln" "const char *p"
291: Allocates and fills one
292: .Vt struct tbl_row
1.2 ! schwarze 293: for each layout line and one
1.1 schwarze 294: .Vt struct tbl_cell
295: for each layout cell.
296: Implemented in
297: .Pa tbl_layout.c ,
298: called from
299: .Fn tbl_read .
300: .It Ft int Fn tbl_data "struct tbl_node *tbl" "int ln" "const char *p"
301: Allocates one
302: .Vt struct tbl_span
303: for each data line and calls
1.2 ! schwarze 304: .Fn getdata
! 305: for each data cell.
1.1 schwarze 306: Implemented in
307: .Pa tbl_data.c ,
308: called from
309: .Fn tbl_read .
310: .It Ft int Fn tbl_cdata "struct tbl_node *tbl" "int ln" "const char *p"
311: Continues parsing a data line:
312: When finding
313: .Sq T} ,
314: switches back to
315: .Dv TBL_PART_DATA
316: mode and calls
1.2 ! schwarze 317: .Fn getdata
1.1 schwarze 318: if there are more data cells on the line.
319: Otherwise, appends the data to the current data cell.
320: Implemented in
321: .Pa tbl_data.c ,
322: called from
323: .Fn tbl_read .
324: .It Xo
325: .Ft int
1.2 ! schwarze 326: .Fo getdata
1.1 schwarze 327: .Fa "struct tbl_node *tbl"
328: .Fa "struct tbl_span *dp"
329: .Fa "int ln"
330: .Fa "const char *p"
331: .Fa "int *pos"
332: .Fc
333: .Xc
334: Parses one data cell into one
335: .Vt struct tbl_dat .
336: Implemented in
337: .Pa tbl_data.c ,
338: called from
339: .Fn tbl_data
340: and
341: .Fn tbl_cdata .
342: .El
343: .Sh SEE ALSO
344: .Xr mandoc 1 ,
345: .Xr mandoc 3 ,
346: .Xr tbl 7
347: .Sh AUTHORS
348: .An -nosplit
349: The
350: .Nm tbl
351: library was written by
352: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
353: with contributions from
354: .An Ingo Schwarze Aq Mt schwarze@openbsd.org .
CVSweb