[BACK]Return to tbl.3 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/tbl.3, Revision 1.6

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

CVSweb