Menu
▾
▴
#208 doctools - Add table support
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.
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 ?
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]
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 ?
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]
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.
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.
Logged In: YES
user_id=75003
And this is very welcome. Thanks.
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.