| 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 ? | |||
Home
Blog
Docs
Downloads
Tickets
Timeline
Branches
Tags
Wiki