Annotation of mandoc/tbl.3, Revision 1.1
1.1 ! schwarze 1: .\" $Id: tbl.3,v 1.17 2012/01/13 15:27:14 joerg Exp $
! 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: .\"
! 17: .Dd $Mdocdate: January 13 2012 $
! 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
! 82: .Va first_tbl ,
! 83: .Va last_tbl ,
! 84: and
! 85: .Va tbl
! 86: of
! 87: .Vt struct roff Bq Pa roff.c .
! 88: .It Vt struct tbl_opts
! 89: This structure describes the options of one table.
! 90: It is used as a substructure of
! 91: .Vt struct tbl_node
! 92: and thus created and deleted together with it.
! 93: It is filled in
! 94: .Fn tbl_options .
! 95: .It Vt struct tbl_head
! 96: This structure describes one layout column in a table,
! 97: in particular the vertical line to its left.
! 98: It is allocated and filled in
! 99: .Fn cell_alloc Bq Pa tbl_layout.c
! 100: and referenced from the
! 101: .Va first_head
! 102: and
! 103: .Va last_head
! 104: members of
! 105: .Vt struct tbl_node .
! 106: .It Vt struct tbl_row
! 107: This structure describes one layout line in a table
! 108: by maintaining a list of all the cells in that line.
! 109: It is allocated and filled in
! 110: .Fn row Bq Pa tbl_layout.c
! 111: and referenced from the
! 112: .Va layout
! 113: member of
! 114: .Vt struct tbl_node .
! 115: .It Vt struct tbl_cell
! 116: This structure describes one layout cell in a table,
! 117: in particular its alignment, membership in spans, and
! 118: usage for lines.
! 119: It is allocated and filled in
! 120: .Fn cell_alloc Bq Pa tbl_layout.c
! 121: and referenced from the
! 122: .Va first
! 123: and
! 124: .Va last
! 125: members of
! 126: .Vt struct tbl_row .
! 127: .It Vt struct tbl_span
! 128: This structure describes one data line in a table
! 129: by maintaining a list of all data cells in that line
! 130: or by specifying that it is a horizontal line.
! 131: It is allocated and filled in
! 132: .Fn newspan Bq Pa tbl_data.c
! 133: which is called from
! 134: .Fn tbl_data
! 135: and referenced from the
! 136: .Va first_span ,
! 137: .Va current_span ,
! 138: and
! 139: .Va last_span
! 140: members of
! 141: .Vt struct tbl_node ,
! 142: and from the
! 143: .Va span
! 144: members of
! 145: .Vt struct man_node
! 146: and
! 147: .Vt struct mdoc_node
! 148: from
! 149: .In man.h
! 150: and
! 151: .In mdoc.h .
! 152: .It Vt struct tbl_dat
! 153: This structure describes one data cell in a table by specifying
! 154: whether it contains a line or data, whether it spans additional
! 155: layout cells, and by storing the data.
! 156: It is allocated and filled in
! 157: .Fn data
! 158: and referenced from the
! 159: .Va first
! 160: and
! 161: .Va last
! 162: members of
! 163: .Vt struct tbl_span .
! 164: .El
! 165: .Ss Interface functions
! 166: The following functions are implemented in
! 167: .Pa tbl.c ,
! 168: and all callers in
! 169: .Pa roff.c .
! 170: .Bl -tag -width Ds
! 171: .It Fn tbl_alloc
! 172: Allocates, initializes, and returns a new
! 173: .Vt struct tbl_node .
! 174: Called from
! 175: .Fn roff_TS .
! 176: .It Fn tbl_read
! 177: Dispatches to
! 178: .Fn tbl_option ,
! 179: .Fn tbl_layout ,
! 180: .Fn tbl_cdata ,
! 181: and
! 182: .Fn tbl_data ,
! 183: see below.
! 184: Called from
! 185: .Fn roff_parseln .
! 186: .It Fn tbl_restart
! 187: Resets the
! 188: .Va part
! 189: member of
! 190: .Vt struct tbl_node
! 191: to
! 192: .Dv TBL_PART_LAYOUT .
! 193: Called from
! 194: .Fn roff_T_ .
! 195: .It Fn tbl_span
! 196: On the first call, return the first
! 197: .Vt struct tbl_span ;
! 198: for later calls, return the next one or
! 199: .Dv NULL .
! 200: Called from
! 201: .Fn roff_span .
! 202: .It Fn tbl_end
! 203: Flags the last span as
! 204: .Dv TBL_SPAN_LAST
! 205: and clears the pointer passed as an argment.
! 206: Called from
! 207: .Fn roff_TE
! 208: and
! 209: .Fn roff_endparse .
! 210: .It Fn tbl_free
! 211: Frees the specified
! 212: .Vt struct tbl_node
! 213: and all the tbl_row, tbl_cell, tbl_span, tbl_dat and tbl_head structures
! 214: referenced from it.
! 215: Called from
! 216: .Fn roff_free
! 217: and
! 218: .Fn roff_reset .
! 219: .El
! 220: .Ss Private functions
! 221: .Bl -tag -width Ds
! 222: .It Ft int Fn tbl_options "struct tbl_node *tbl" "int ln" "const char *p"
! 223: Parses the options line into
! 224: .Vt struct tbl_opts .
! 225: Implemented in
! 226: .Pa tbl_opts.c ,
! 227: called from
! 228: .Fn tbl_read .
! 229: .It Ft int Fn tbl_layout "struct tbl_node *tbl" "int ln" "const char *p"
! 230: Allocates and fills one
! 231: .Vt struct tbl_head
! 232: for each layout column, one
! 233: .Vt struct tbl_row
! 234: for each layout line, and one
! 235: .Vt struct tbl_cell
! 236: for each layout cell.
! 237: Implemented in
! 238: .Pa tbl_layout.c ,
! 239: called from
! 240: .Fn tbl_read .
! 241: .It Ft int Fn tbl_data "struct tbl_node *tbl" "int ln" "const char *p"
! 242: Allocates one
! 243: .Vt struct tbl_span
! 244: for each data line and calls
! 245: .Fn data
! 246: on that line.
! 247: Implemented in
! 248: .Pa tbl_data.c ,
! 249: called from
! 250: .Fn tbl_read .
! 251: .It Ft int Fn tbl_cdata "struct tbl_node *tbl" "int ln" "const char *p"
! 252: Continues parsing a data line:
! 253: When finding
! 254: .Sq T} ,
! 255: switches back to
! 256: .Dv TBL_PART_DATA
! 257: mode and calls
! 258: .Fn data
! 259: if there are more data cells on the line.
! 260: Otherwise, appends the data to the current data cell.
! 261: Implemented in
! 262: .Pa tbl_data.c ,
! 263: called from
! 264: .Fn tbl_read .
! 265: .It Xo
! 266: .Ft int
! 267: .Fo data
! 268: .Fa "struct tbl_node *tbl"
! 269: .Fa "struct tbl_span *dp"
! 270: .Fa "int ln"
! 271: .Fa "const char *p"
! 272: .Fa "int *pos"
! 273: .Fc
! 274: .Xc
! 275: Parses one data cell into one
! 276: .Vt struct tbl_dat .
! 277: Implemented in
! 278: .Pa tbl_data.c ,
! 279: called from
! 280: .Fn tbl_data
! 281: and
! 282: .Fn tbl_cdata .
! 283: .El
! 284: .Sh SEE ALSO
! 285: .Xr mandoc 1 ,
! 286: .Xr mandoc 3 ,
! 287: .Xr tbl 7
! 288: .Sh AUTHORS
! 289: .An -nosplit
! 290: The
! 291: .Nm tbl
! 292: library was written by
! 293: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
! 294: with contributions from
! 295: .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