Fix and extend groff_hdtbl.man

1 files changed, 203 insertions, 3 deletions

diff --git a/contrib/hdtbl/groff_hdtbl.man b/contrib/hdtbl/groff_hdtbl.man
index 2d553bcc..7e7c1677 100644
--- a/contrib/hdtbl/groff_hdtbl.man
+++ b/contrib/hdtbl/groff_hdtbl.man
@@ -1,5 +1,5 @@
 .ig
-Copyright (C) 2005, 2006, 2008, 2009, 2010
+Copyright (C) 2005, 2006, 2008, 2009, 2010, 2013
   Free Software Foundation, Inc.
 
 Written by Joachim Walsdorff <Joachim.Walsdorff@urz.uni-heidelberg.de>
@@ -202,28 +202,89 @@ will be easily converted to HTML; this is not implemented yet.
 .
 .SH USAGE
 .
-The simplest well-formed table consists of just single calls to the four
-base table macros in the right order.
+In this and the next section, we present examples to help
+understanding how to use
+.BR hdtbl .
+.
+If you want to it you must first call its
+.I tmac
+file.
+.
+That means that you must include the following line in your
+.I roff
+file before using
+.BR hdtbl :
+.
+.PP
+.nf
+.nh
+.RS
+.CR .mso hdtbl.tmac
+.fi
+.hy
+.RE
+.
+.PP
+Then you can include on or more tables in your document, each one must
+be started with the command
+.CR .TBL
+and ended by the command
+.CR ".ETB \fR."
+.
+We will show the output of each example in the
+.I tty
+format.
+.
+But the graphical output is much more beautiful, it cannot however be
+shown in the
+.B man
+output.
+.
+.PP
+The simplest well\-formed table consists of just single calls to the
+four base table macros in the right order.
 .
 Here we construct a table with only one cell.
 .
 .PP
 .RS
 .nf
+.nh
 .CR .TBL
 .CR .TR
 .CR .TD
 .CI contents of the table cell
 .CR .ETB
 .fi
+.hy
+.RE
+.
+.PP
+Its
+.I tty
+output is
+.
+.PP
+.nf
+.nh
+.RS
+|                                                                |
++contents-of-the-table-cell--------------------------------------+
 .RE
+.hy
+.fi
 .
+
 .PP
 Equivalent to the above is the following notation.
 .
 .PP
 .RS
+.nh
+.nf
 .CRI ".TBL .TR .TD " "contents of the table cell" " .ETB"
+.fi
+.hy
 .RE
 .
 .PP
@@ -244,12 +305,32 @@ be written as
 .PP
 .RS
 .nf
+.nh
 .CR ".TBL cols=2"
 .CR ".  TR .TD 1*1 .TD 1*2"
 .CR ".  TR .TD 2*1 .TD 2*2"
 .CR ".ETB"
 .fi
+.hy
+.RE
+.
+.PP
+Its
+.I tty
+output is
+.
+.PP
+.nf
+.nh
+.RS
+|                               |                                |
+|1*1                            | 1*2                            |
++-------------------------------+--------------------------------+
++2*1----------------------------+-2*2----------------------------+
+                                |
 .RE
+.hy
+.fi
 .
 .PP
 Here we see a difference to HTML tables: The number of columns must be
@@ -275,6 +356,7 @@ Note, however, that this table
 .PP
 .RS
 .nf
+.nh
 .CR ".TBL"
 .CR ".  TR"
 .CR ".    TD"
@@ -290,6 +372,7 @@ Note, however, that this table
 .CR ".      ETB"
 .CR ".ETB"
 .fi
+.hy
 .RE
 .
 .PP
@@ -298,6 +381,7 @@ and this table
 .PP
 .RS
 .nf
+.nh
 .CR ".TBL cols=2"
 .CR ".  TR"
 .CR ".    TD colspan=2"
@@ -309,20 +393,54 @@ and this table
 .CR ".      nop 2*2"
 .CR ".ETB"
 .fi
+.hy
 .RE
 .
 .PP
 are similar but not identical.
 .
 .PP
+The first table looks like
+.
+.PP
+.nf
+.nh
+.RS
+|                                                                |
+|1*1 1*2                                                         |
++----------------------------------------------------------------+
+|                                                                |
++-2*1----------------------------2*2-----------------------------+
+.RE
+.hy
+.fi
+.
+.PP
+and the second one like
+.
+.PP
+.nf
+.nh
+.RS
+|                                                                |
+|1*1 1*2                                                         |
++-------------------------------+--------------------------------+
++2*1----------------------------+-2*2----------------------------+
+.RE
+.hy
+.fi
+.
+.PP
 Here the latter table in a more compact form.
 .
 .PP
 .RS
 .nf
+.nh
 .CR ".TBL cols=2 .TR \[dq].TD colspan=2\[dq] 1*1 1*2"
 .CR ".            TR .TD 2*1 .TD 2*2 .ETB"
 .fi
+.hy
 .RE
 .
 .PP
@@ -625,11 +743,91 @@ and causes incorrect results.
 .
 .RS
 .IP
+.nh
 .nf
 .CR ".TR .TD 1*1 \[dq].TD 1*2 rowspan=2\[dq] .TD 1*3"
 .CR ".TR \[dq].TD 2*1 colspan=2\[dq]         .TD 2*3"
 .fi
+.hy
+.RE
+.
+.PP
+A working example for headers and cells with
+.B colspan
+is
+.
+.PP
+.RS
+.nf
+.nh
+.CR .TBL cols=3
+.CR .TR \[rq].TH colspan=2 header1+2\[rq] \[rq].TH header3\[rq]
+.CR .TR \[rq].CR .TD 1*1 .TD 1*2 .TD 1*3\[rq]
+.CR .TR
+.CR .TD 1*2
+.CR .TD colspan=2 2+3*2
+.CR .ETB
+.fi
+.hy
+.RE
+.
+.PP
+This looks like
+.
+.PP
+.RS
+.nf
+.nh
+|                                          |                     |
+|                header1+2                 |      header3        |
++--------------------+---------------------+---------------------+
+|1*1                 | 1*2                 |1*3                  |
++--------------------+---------------------+---------------------+
+|1*2                 | 2+3*2                                     |
++--------------------+-------------------------------------------+
+.RE
+.hy
+.fi
+.
+.PP
+A working example with
+.B rowspan
+is
+.
+.PP
+.RS
+.nf
+.nh
+.CR .TBL cols=3
+.CR .TR
+.CR .TD 1*1
+.CR .TD rowspan=2 1*2
+.CR .TD 1*3
+.CR .
+.CR .TR
+.CR .TD 2*1
+.CR .TD 2*3
+.CR .ETB
+.fi
+.hy
 .RE
+.
+.PP
+That looks like
+.
+.PP
+.RS
+.nf
+.nh
+|                    |                     |                     |
+|1*1                 | 1*2                 |1*3                  |
++--------------------+-                    +---------------------+
++2*1-----------------+---------------------+2*3------------------+
+                     |                     |
+.hy
+.fi
+.RE
+.
 .RE
 .RE
 .
@@ -956,10 +1154,12 @@ For example:
 .PP
 .RS
 .nf
+.nh
 .CR ".am pg@end-text"
 .CR ".  t*EM"
 .CR ".."
 .fi
+.hy
 .RE
 .
 .PP