tagging issues from weerd@ regarding hyphens

[mandoc.git] / tbl.3

diff --git a/tbl.3 b/tbl.3
index 05e423fe548ed100b7247909ab24491623a66695..d27b8dda32da7f5c6c7cc6f9268a2b5b2bdc6a24 100644 (file)
--- a/tbl.3
+++ b/tbl.3
@@ -1,6 +1,6 @@
-.\"    $Id: tbl.3,v 1.1 2013/06/01 05:44:39 schwarze Exp $
+.\"    $Id: tbl.3,v 1.6 2018/12/14 06:33:14 schwarze Exp $

 .\"
 .\"

-.\" Copyright (c) 2013 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2013, 2015, 2018 Ingo Schwarze <schwarze@openbsd.org>

 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\" purpose with or without fee is hereby granted, provided that the above
 .\"
 .\" 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.
 .\"
 .\" 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 14 2018 $

 .Dt TBL 3
 .Os
 .Sh NAME
 .Dt TBL 3
 .Os
 .Sh NAME


@@ -26,16 +26,15 @@
 .Nm tbl_free
 .Nd roff table parser library for mandoc
 .Sh SYNOPSIS
 .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"
 .Ft struct tbl_node *
 .Fo tbl_alloc
 .Fa "int pos"
 .Fa "int line"

-.Fa "struct mparse *parse"

 .Fc
 .Fc

-.Ft enum rofferr
+.Ft void

 .Fo tbl_read
 .Fa "struct tbl_node *tbl"
 .Fa "int ln"
 .Fo tbl_read
 .Fa "struct tbl_node *tbl"
 .Fa "int ln"


@@ -67,24 +66,43 @@ 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
 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.
 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
 created in
 .Fn tbl_alloc ,
 and stored in the members

-.Va first_tbl ,
-.Va last_tbl ,
+.Fa first_tbl ,
+.Fa last_tbl ,

 and
 and

-.Va tbl
+.Fa tbl

 of
 .Vt struct roff Bq Pa roff.c .
 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 .

 .It Vt struct tbl_opts
 This structure describes the options of one table.
 It is used as a substructure of
 .It Vt struct tbl_opts
 This structure describes the options of one table.
 It is used as a substructure of


@@ -92,26 +110,27 @@ It is used as a substructure of
 and thus created and deleted together with it.
 It is filled in
 .Fn tbl_options .
 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
 .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 .
 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
 .It Vt struct tbl_cell
 This structure describes one layout cell in a table,
 in particular its alignment, membership in spans, and


@@ -119,11 +138,16 @@ usage for lines.
 It is allocated and filled in
 .Fn cell_alloc Bq Pa tbl_layout.c
 and referenced from the
 It is allocated and filled in
 .Fn cell_alloc Bq Pa tbl_layout.c
 and referenced from the

-.Va first
+.Fa first

 and
 and

-.Va last
+.Fa last

 members of
 .Vt struct tbl_row .
 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
 .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 +157,14 @@ It is allocated and filled in
 which is called from
 .Fn tbl_data
 and referenced from the
 which is called from
 .Fn tbl_data
 and referenced from the

-.Va first_span ,
-.Va current_span ,
+.Fa first_span ,
+.Fa current_span ,

 and
 and

-.Va last_span
+.Fa last_span

 members of
 .Vt struct tbl_node ,
 and from the
 members of
 .Vt struct tbl_node ,
 and from the

-.Va span
+.Fa span

 members of
 .Vt struct man_node
 and
 members of
 .Vt struct man_node
 and


@@ -149,23 +173,53 @@ from
 .In man.h
 and
 .In mdoc.h .
 .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
 .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
 and referenced from the

-.Va first
+.Fa first

 and
 and

-.Va last
+.Fa last

 members of
 .Vt struct tbl_span .
 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 ,
 .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
 .Pa roff.c .
 .Bl -tag -width Ds
 .It Fn tbl_alloc


@@ -185,7 +239,7 @@ Called from
 .Fn roff_parseln .
 .It Fn tbl_restart
 Resets the
 .Fn roff_parseln .
 .It Fn tbl_restart
 Resets the

-.Va part
+.Fa part

 member of
 .Vt struct tbl_node
 to
 member of
 .Vt struct tbl_node
 to


@@ -210,7 +264,7 @@ and
 .It Fn tbl_free
 Frees the specified
 .Vt struct tbl_node
 .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
 referenced from it.
 Called from
 .Fn roff_free


@@ -218,6 +272,8 @@ and
 .Fn roff_reset .
 .El
 .Ss Private functions
 .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
 .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 +284,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
 .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
 .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
 .Vt struct tbl_cell
 for each layout cell.
 Implemented in


@@ -242,8 +296,8 @@ called from
 Allocates one
 .Vt struct tbl_span
 for each data line and calls
 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
 Implemented in
 .Pa tbl_data.c ,
 called from


@@ -255,7 +309,7 @@ When finding
 switches back to
 .Dv TBL_PART_DATA
 mode and calls
 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
 if there are more data cells on the line.
 Otherwise, appends the data to the current data cell.
 Implemented in


@@ -264,7 +318,7 @@ called from
 .Fn tbl_read .
 .It Xo
 .Ft int
 .Fn tbl_read .
 .It Xo
 .Ft int

-.Fo data
+.Fo getdata

 .Fa "struct tbl_node *tbl"
 .Fa "struct tbl_span *dp"
 .Fa "int ln"
 .Fa "struct tbl_node *tbl"
 .Fa "struct tbl_span *dp"
 .Fa "int ln"