Tcl Library Source Code

View Ticket
Login
Ticket UUID: 1267112
Title: doctools - Add table support
Type: RFE Version: None
Submitter: techentin Created on: 2005-08-23 13:43:53
Subsystem: doctools Assigned To: andreas_kupries
Priority: 5 Medium Severity:
Status: Open Last Modified: 2007-04-05 23:42:31
Resolution: Closed By:
    Closed on:
Description:
When composing the units man page, I used [example] to
format the tables of units, because that appeared
similar to preformatted, and was the only way I saw to
make a table.

It would be better if doctools supported [table]
commands.  The html, latex, and nroff engines could be
extended to support table output.  Tmml and wiki
formats don't support tables, so those engines would
have to generate some equivalent, perhaps preformatted,
output.
User Comments: techentin added on 2005-09-01 00:10:56:
Logged In: YES 
user_id=43494

Thanks for the examples, David.  I see that from these, and
the others with which I am familiar, just about everything
requires some sort of delimiter between column entries.  And
I've also looked at how the formatting engines handle lists
and examples.  

It appears that for the "plain" formats I suggested, using
line delimters for rows and word delimiters for columns, it
would be necessary to have fmt_plain_text change modes of
operation in a table environment.  This is presently only
done for latex examples (as far as I looked).  So it would
take a global (i.e., _in_table) and a switch inside of
fmt_plain_text to make it work.

It would also be possible to only support a single-command
format for a  table, much like the short form of example. 
So your table would be created with something like:

[table -align left -title "Units Abbreviations" {
Quantity      "Unit Name"  Abbr.
Length        meter        m
Mass          kilogram     kg
Time          second       s
}

This has the advantage of having all the table data in once
piece, so you can compute column widths for text formats. 
Your choice as to using Tcl words or a special delimiter
character to deliniate column entries, but I think I still
prefer words, just because it seems tclish.

andreas_kupries added on 2005-08-31 22:58:50:
Logged In: YES 
user_id=75003

And this is very welcome. Thanks.

escargo added on 2005-08-31 21:34:03:
Logged In: YES 
user_id=69099

Almost Free Text (http://www.maplefish.com/todd/aft.html),
txt2html
(http://txt2html.sourceforge.net/txt2html.html#input_file_format),
and txt2tags (http://txt2tags.sourceforge.net/rules.html)
have methods of supporting table output based on character
markup coming in.

Just to show some examples of how other processors handle
the task.

andreas_kupries added on 2005-08-24 05:18:16:
Logged In: YES 
user_id=75003

Huh. I'll have to think about the various examples ... First
"-quoting in regular text is not something the frontend
recognizes. It is simply passed to the backend. This is
important because all structural stuff should be in the
frontend, and nothing in the backend. ... In your example I
would have to handle the text between the table begin/end
markers as a CSV, apparently. Except when the row/elem
commands are used ... Definitely not easy to parse ...

More thinking required.

techentin added on 2005-08-24 05:03:30:
Logged In: YES 
user_id=43494

Oh, drat.  I meant to quote "Unit Name" as a single word. 
And now that I look at it, I've got the begin/end backwards too.

If I was going to make up a syntax, then I'd try to parallel
manpage_begin/end and list_begin/end.  Both mark the start
and end of blocks, and other doctool commands are valid
within the block.  I like the simplicity of using Tcl's
natural line and word boundaries to denote row and element
breaks, but I can imagine optional row and element commands,
[row] and [elem], and a special command for the header row,
[header].

Although a few doctool commands have optional arguments,
none of them have Tk-style options.  But I think that would
be the best way to implement table appearance features. 
Options to [table_begin] would apply to the entire table. 
Options to [row] would apply to the whole row, and options
to [elem] would apply to just that element.  Just for fun,
include a [columns] command, which takes a list of option
lists, and applies them to each column in the table.  Common
options would be

-align {left center right}
-colsep {true false}     draw a line to the right of the cell
-rowsep {true false}     draw a line below the cell

Options just for [table_begin] would be

-title "table title text"
-frame {all bottom none bottom sides top topbot}

And I've grown fond of grid's relative placement syntax, so
I'd use that to denote entries spanning more than one column
or row.

So without careful declaration of all the syntax, I present
some examples of how you might use these commands.  For
starters, apply some global formatting to the table with
attributes supplied to [table_begin].

[table_begin -align left -frame none]
Quantity      "Unit Name"  Abbr.
Length        meter        m
Mass          kilogram     kg
Time          second       s
[table_end]

Generate the same table, but center the rightmost column, so
we need both [row] and [elem] commands.

[table_begin -align left]
[row Quantity      "Unit Name"  [elem -align center Abbr.]]
[row Length        meter        [elem -align center m]]
[row Mass          kilogram     [elem -align center kg]]
[row Time          second       [elem -align center s]]
[table_end]

But if we have a [columns] command, then we can apply
formatting to just the third column.

[table_begin -align left]
[columns {} {} {-align center}]
Quantity      "Unit Name"  Abbr.
Length        meter        m
Mass          kilogram     kg
Time          second       s
[table_end]

Same table, but use a special [header] command for the first
row, which might give it special highlighting.

[table_begin]
[header Quantity   "Unit Name"  Abbr.]
[row Length        meter        m]
[row Mass          kilogram     kg]
[row Time          second       s]
[table_end]

Create an entry in the second column which spans two rows,
using the [grid] command's relative placement code.  This
will render the "meter" entry in a box that is two rows
high.  In the case of nroff format, it will probably leave a
blank line.  This implies quoting single characters of ^, x,
and - somehow, to avoid the special meaning.

[table_begin]
Quantity      "Unit Name"  Abbr.
Length        meter        m
Mass            ^          kg
Time          second       s
[table_end]

andreas_kupries added on 2005-08-24 03:33:19:
Logged In: YES 
user_id=75003

Is the column separator in your exmaple multiple spaces, or
tabs, or one space, or a mixture ? ... Wait, one space
cannot be a separator in your example, see 'Unit Name',
which is in one column.

Maybe several table commands, from the most primitive to one
which supports lots of features ?

techentin added on 2005-08-24 00:41:33:
Logged In: YES 
user_id=43494

HTML, Latex, tbl (nroff) and docbook all support column
headers, boxes around the table, framing each entry,
multiple column spans, multiple row spans, highlighting
entries (bold, italic), and some other features.

I'd be happy starting out with defining a table in each
format engine's default form.  Then it should be straight
forward to add other features later.

All of the engines define tables with commands for each row
and cell entry.  We could have a syntax with commands for
each row and element, but this would be pretty verbose.  I
would vote for one command per row, or even one command per
table, something like shown at the bottom of
http://wiki.tcl.tk/3150 (Displaying tables).

[begin_table]
Quantity                Unit Name    Abbr.
Length                  meter        m
Mass                    kilogram     kg
Time                    second       s
[end_table]

andreas_kupries added on 2005-08-23 23:57:51:
Logged In: YES 
user_id=75003

My problem is that I currently have no good idea for the
commands needed to define tables. Not sure if the HTML style
is good enough, or if something more like TeX should be used
... How far do we wish to go with cells spanning multiple
rows and/or columns ?