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