=================================================================== RCS file: /cvs/mandoc/tbl.3,v retrieving revision 1.1 retrieving revision 1.5 diff -u -p -r1.1 -r1.5 --- mandoc/tbl.3 2013/06/01 05:44:39 1.1 +++ mandoc/tbl.3 2018/12/13 02:06:07 1.5 @@ -1,6 +1,6 @@ -.\" $Id: tbl.3,v 1.1 2013/06/01 05:44:39 schwarze Exp $ +.\" $Id: tbl.3,v 1.5 2018/12/13 02:06:07 schwarze Exp $ .\" -.\" Copyright (c) 2013 Ingo Schwarze +.\" Copyright (c) 2013, 2015, 2018 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above @@ -14,7 +14,7 @@ .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" -.Dd $Mdocdate: June 1 2013 $ +.Dd $Mdocdate: December 13 2018 $ .Dt TBL 3 .Os .Sh NAME @@ -26,16 +26,16 @@ .Nm tbl_free .Nd roff table parser library for mandoc .Sh SYNOPSIS -.In mandoc.h -.In libmandoc.h -.In libroff.h +.In sys/types.h +.In tbl.h +.In tbl_parse.h .Ft struct tbl_node * .Fo tbl_alloc .Fa "int pos" .Fa "int line" .Fa "struct mparse *parse" .Fc -.Ft enum rofferr +.Ft void .Fo tbl_read .Fa "struct tbl_node *tbl" .Fa "int ln" @@ -67,24 +67,49 @@ utility and not designed for stand-alone use. The present manual is intended as a reference for developers working on .Xr mandoc 1 . .Ss Data structures -Unless otherwise noted, all of the following data structures are defined in -.In mandoc.h +Unless otherwise noted, all of the following data structures are declared in +.In tbl.h and are deleted in .Fn tbl_free . .Bl -tag -width Ds .It Vt struct tbl_node This structure describes a complete table. -It is defined in -.In libroff.h , +It is declared in +.In tbl_int.h , created in .Fn tbl_alloc , and stored in the members -.Va first_tbl , -.Va last_tbl , +.Fa first_tbl , +.Fa last_tbl , and -.Va tbl +.Fa tbl of .Vt struct roff Bq Pa roff.c . +.Pp +The +.Fa first_span , +.Fa current_span , +.Fa last_span , +and +.Fa next +members may be +.Dv NULL . +The +.Fa first_row +and +.Fa last_row +members may be +.Dv NULL , +but if there is a span, the function +.Fn tbl_layout +guarantees that these pointers are not +.Dv NULL . +The function +.Fn tbl_alloc +guarantees that the +.Fa parse +member is not +.Dv NULL . .It Vt struct tbl_opts This structure describes the options of one table. It is used as a substructure of @@ -92,26 +117,27 @@ It is used as a substructure of and thus created and deleted together with it. It is filled in .Fn tbl_options . -.It Vt struct tbl_head -This structure describes one layout column in a table, -in particular the vertical line to its left. -It is allocated and filled in -.Fn cell_alloc Bq Pa tbl_layout.c -and referenced from the -.Va first_head -and -.Va last_head -members of -.Vt struct tbl_node . .It Vt struct tbl_row This structure describes one layout line in a table by maintaining a list of all the cells in that line. It is allocated and filled in .Fn row Bq Pa tbl_layout.c and referenced from the -.Va layout +.Fa layout member of .Vt struct tbl_node . +.Pp +The +.Fa next +member may be +.Dv NULL . +The function +.Fn tbl_layout +guarantees that the +.Fa first +and +.Fa last +members are not NULL. .It Vt struct tbl_cell This structure describes one layout cell in a table, in particular its alignment, membership in spans, and @@ -119,11 +145,16 @@ usage for lines. It is allocated and filled in .Fn cell_alloc Bq Pa tbl_layout.c and referenced from the -.Va first +.Fa first and -.Va last +.Fa last members of .Vt struct tbl_row . +.Pp +The +.Fa next +member may be +.Dv NULL . .It Vt struct tbl_span This structure describes one data line in a table by maintaining a list of all data cells in that line @@ -133,14 +164,14 @@ It is allocated and filled in which is called from .Fn tbl_data and referenced from the -.Va first_span , -.Va current_span , +.Fa first_span , +.Fa current_span , and -.Va last_span +.Fa last_span members of .Vt struct tbl_node , and from the -.Va span +.Fa span members of .Vt struct man_node and @@ -149,23 +180,53 @@ from .In man.h and .In mdoc.h . +.Pp +The +.Fa first , +.Fa last , +.Fa prev , +and +.Fa next +members may be +.Dv NULL . +The function +.Fn newspan Bq Pa tbl_data.c +guarantees that the +.Fa opts +and +.Fa layout +members are not +.Dv NULL . .It Vt struct tbl_dat This structure describes one data cell in a table by specifying whether it contains a line or data, whether it spans additional layout cells, and by storing the data. It is allocated and filled in -.Fn data +.Fn tbl_data and referenced from the -.Va first +.Fa first and -.Va last +.Fa last members of .Vt struct tbl_span . +.Pp +The +.Fa string +and +.Fa next +members may be +.Dv NULL . +The function +.Fn getdata +guarantees that the +.Fa layout +member is not +.Dv NULL . .El .Ss Interface functions The following functions are implemented in .Pa tbl.c , -and all callers in +and all callers are in .Pa roff.c . .Bl -tag -width Ds .It Fn tbl_alloc @@ -185,7 +246,7 @@ Called from .Fn roff_parseln . .It Fn tbl_restart Resets the -.Va part +.Fa part member of .Vt struct tbl_node to @@ -210,7 +271,7 @@ and .It Fn tbl_free Frees the specified .Vt struct tbl_node -and all the tbl_row, tbl_cell, tbl_span, tbl_dat and tbl_head structures +and all the tbl_row, tbl_cell, tbl_span, and tbl_dat structures referenced from it. Called from .Fn roff_free @@ -218,6 +279,8 @@ and .Fn roff_reset . .El .Ss Private functions +The following functions are declared in +.In tbl_int.h . .Bl -tag -width Ds .It Ft int Fn tbl_options "struct tbl_node *tbl" "int ln" "const char *p" Parses the options line into @@ -228,10 +291,8 @@ called from .Fn tbl_read . .It Ft int Fn tbl_layout "struct tbl_node *tbl" "int ln" "const char *p" Allocates and fills one -.Vt struct tbl_head -for each layout column, one .Vt struct tbl_row -for each layout line, and one +for each layout line and one .Vt struct tbl_cell for each layout cell. Implemented in @@ -242,8 +303,8 @@ called from Allocates one .Vt struct tbl_span for each data line and calls -.Fn data -on that line. +.Fn getdata +for each data cell. Implemented in .Pa tbl_data.c , called from @@ -255,7 +316,7 @@ When finding switches back to .Dv TBL_PART_DATA mode and calls -.Fn data +.Fn getdata if there are more data cells on the line. Otherwise, appends the data to the current data cell. Implemented in @@ -264,7 +325,7 @@ called from .Fn tbl_read . .It Xo .Ft int -.Fo data +.Fo getdata .Fa "struct tbl_node *tbl" .Fa "struct tbl_span *dp" .Fa "int ln"