[groff] 01/01: tbl.man: add simple examples

[Bernd Warken]

bwarken pushed a commit to branch master
in repository groff.

commit a2992cdd9995aef2da2d8f7a35eb0dfacd9ef7df
Author: Bernd Warken <address@hidden>
Date:   Mon Jul 21 15:04:55 2014 +0200

    tbl.man: add simple examples
---
 ChangeLog               |    4 +
 src/preproc/tbl/tbl.man |  169 ++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 164 insertions(+), 9 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 4e9e190..c902eff 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2014-07-21  Bernd Warken  <address@hidden>
+
+       * tbl.1 (src/preproc/tbl/tbl.man): Add simple examples.
+
 2014-07-12  Bernd Warken  <address@hidden>
 
        * groff.7 (man/groff.man): Add section about underlining.
diff --git a/src/preproc/tbl/tbl.man b/src/preproc/tbl/tbl.man
index e6a25cb..6db77e1 100644
--- a/src/preproc/tbl/tbl.man
+++ b/src/preproc/tbl/tbl.man
@@ -1,8 +1,17 @@
 '\" t
+.TH @address@hidden @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
+.SH NAME
address@hidden@tbl \- format tables for troff
+.
+.\" --------------------------------------------------------------------
 .ig
 Copyright (C) 1989-1995, 2001-2004, 2006-2014
   Free Software Foundation, Inc.
 
+Last update: 21 Jul 2014
+
+Bernd Warken <address@hidden> added simple examples.
+
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
 are preserved on all copies.
@@ -19,14 +28,7 @@ translations approved by the Free Software Foundation 
instead of in
 the original English.
 ..
 .
-.
-.TH @address@hidden @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
-.
-.
-.SH NAME
address@hidden@tbl \- format tables for troff
-.
-.
+.\" --------------------------------------------------------------------
 .SH SYNOPSIS
 .SY @address@hidden
 .OP \-Cv
@@ -34,6 +36,7 @@ the original English.
 .YS
 .
 .
+.\" --------------------------------------------------------------------
 .SH DESCRIPTION
 This manual page describes the GNU version of
 .BR tbl ,
@@ -76,7 +79,8 @@ Leader characters (\[rs]a) are handled as interpreted.
 Print the version number.
 .
 .
-.SH USAGE
+.\" --------------------------------------------------------------------
+.SH "LANGUAGE OVERVIEW"
 .B tbl
 expects to find table descriptions wrapped in the
 .B .TS
@@ -84,7 +88,154 @@ expects to find table descriptions wrapped in the
 .B .TE
 (table end) macros.
 .
+Within each such table sections, another table can be defined by
+using the request
+.B .T&
+before the final command
+.BR .TE .
+.
+Each table definition has the following structure:
+.
+.TP
+.I Global options
+This is optional.
+.
+This table part can use several of these options distributed in 1 or
+more lines.
+.
+The
+.I global option part
+must always be finished by a
+.B "semi-colon ;" .
+.
+.TP
+.I Table format specification
+This part must be given, it is not optional.
+.
+It determines the number of columns (cells) of the table.
+.
+Moreover each cell is classified by being central, left adjusted, or
+numerical, etc.
+.
+This specification can have several lines, but must be finished by a
+.B dot .
+at the end of the last line.
+.
+After each cell definition,
+.I column specifiers
+can be appended, but that's optional.
+.
+.
+.P
+Cells are separated by a tab character by default.
+.
+That can be changed by the
+.I global option
+.BI tbl( c ) \fR,
+where
+.I c
+is an arbitrary character.
+.
+.
+.\" --------------------------------------------------------------------
+.SH "SIMPLE EXAMPLES"
+The easiest table definition is.
+.RS
+.EX
+\&.TS
+c c c .
+This   is      centered
+Well,  this    also
+\&.TE
+.EE
+.RE
+.
+.
+By using
+.B c c
+.BR c ,
+each cell in the whole table will be centered.
+.
+The separating character is here the default
+.IR tab .
+.
+.
+.P
+The result is
+.RS
+.EX
+.TS
+c c c .
+This   is      centered
+Well,  this    also
+.TE
+.EE
+.RE
+.
+.
+.P
+This definition is identical to
+.RS
+.EX
+\&.TS
+tab(@);
+ccc.
address@hidden@centered
+Well,@address@hidden
+\&.TE
+.EE
+.RE
+.
+Here, the separating tab character is changed to the letter
+.BR @ .
+.
+.
+.P
+Moreover a title can be added and the centering directions can be
+changed to many other formats:
+.RS
+.EX
+\&.TS
+tab(@);
+c s s
+l c n .
+Title
address@hidden@123
address@hidden@75
+\&.TE
+.EE
+.RE
+.
+The result is
+.RS
+.EX
+.TS
+tab(@);
+c s s
+l c n .
+Title
address@hidden@123
address@hidden@75
+.TE
+.EE
+.RE
+.
+Here
+.B l
+means
+.IR left\-justified ,
+and
+.B n
+means
+.IR numerical ,
+which is here
+.IR right\-justified .
+.
+.
+.\" --------------------------------------------------------------------
+.SH USAGE
 .
+.\" --------------------------------------------------------------------
 .SS Global options
 The line immediately following the
 .B .TS