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

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