contrib/mdocml/tbl.3

   1 .\"     $Id: tbl.3,v 1.1 2013/06/01 05:44:39 schwarze 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: June 1 2013 $
  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 .