Markdown Discuss - Jun 2011 - thoughts on a table specification (short! 10 simple rules!)

my take on a table specification.   it's short.

this is for my own system, so if some of it
doesn't seem to apply to you, that's why...

***

first, the overview:   keep it simple, stupid.

if your table is too big or too complex to grok
on an iphone, then it's too big or too complex.

so break it up, into a series of smaller tables.

and when you do so, do it in a way such that
an intelligent viewer-program in the future
can "stitch" the smaller pieces back together
when the view-port is big enough to allow it.
(since that's what intelligent viewer-tools do.)

you can draft the small tables on index cards.
that'll give you a good sense of the right size,
and whether each piece has enough integrity
to stand on its own and be meaningful to us.

also make sure that you can then arrange the
smaller pieces back together into the full table.
(make sure that any competent human would
be able to determine how to do a reassembly.)

having said all that, let's go on to the "10 rules"
for a light-markup solution to the table problem.

***

10 "k.i.s.s." rules for light-markup tables

1.   all of the lines in a table must be contiguous.
there must be no blank lines interrupting things.
each table line must have a space in column 1.

2.   a table is assumed to be a "basic" table --
where each line constitutes a row in the table.
for tables where this is not the case, you must
use a line of dashes for _all_ separation-lines.
the viewer-program will draw (faint, gray) lines
if the reader wants, regardless of what you do.
any lines that you do include will be respected.

3.   every cell in a row must be separated from
neighboring cells by at least 3 spaces, or 1 tab.
(people who tell you not to use tabs are idiots.)
if a cell is to be left empty, use a single period.
a lone period within a cell will not be displayed;
(the cell will get utilized as a merge candidate).

4.   the top line(s) of a table might be headers,
which must not contain internal spaces or tabs.
(leading and/or trailing spaces or tabs are ok.)
further thought might allow mid-table headers,
pending any future rule regarding cell-merging.
either way, a mid-table line without separators
will be interpreted to be a table-spanning line.

5.   the bottom line(s) might be footers, which
also are not permitted internal spaces or tabs.
this rule could be combined with #4 if there is
future need to make room for some new rule.

6.   the leftmost column will be assumed to be
the row-headers.   if this is not the case, then
make the whole first column "empty" by using
a single period in each cell in that first column.
the first column in each row must be a space,
since that's what indicates that this is a "block".
so a column of dots in column 2 would be seen
as an indication that there are no row-headers.

7.   all columns will be aligned automatically,
according to the type of data in each column.
99% of the time, it's fine; embrace constraint.
an override fluster-clucks user-comprehension.

8.   i forget what 8 was for.   (never tire of that.)

9.   aside from the rule about the separators
-- at least 3 spaces, or 1 tab -- there are no
other rules regarding the "look" of the table.
use any font your heart desires. and line up
the columns if you like, but it's unnecessary.
the computer will make your table look nice.
gotta believe.   plus, there's always rule #10.

10.   redundancy can often be a very good thing.
in this vein, make a fancy version of your table,
turn it into a graphic, and include that image-file
in your e-book, right next to the "raw text data",
so -- heaven forbid -- if the text just doesn't look
the way it should, the reader has another option.

ok, i've gotta stop editing this, because i just
keep adding more elaboration, and that only
serves to rob this nice little list of its simplicity.

less is more.

-bowerbird
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://six.pairlist.net/pipermail/markdown-discuss/attachments/20110606/88ce820b/attachment.html>

Hi Bowerbird (et al),

A few remarks...

- Using tabs to format tables will make your table look awful for
people with different tab sizes. That's why people use spaces instead
of tabs: they're always the same width. (And no, I don't think I'm
an
idiot)
- If your table is so complex it needs stuff like cell merging, I
don't think it should go in Markdown.
- Making row and column headers required would annoy me greatly.
- The single to mark empty cells feels too magical for me.
- Having to include images to make sure everyone can read your
Markdown document feels... wrong.

All in all, I wouldn't really like this going in mainline Markdown.

Cheers,
Wander

On Mon, Jun 6, 2011 at 18:52,  <Bowerbird at aol.com>
wrote:
> my take on a table specification.? it's short.
>
> this is for my own system, so if some of it
> doesn't seem to apply to you, that's why...
>
> ***
>
> first, the overview:? keep it simple, stupid.
>
> if your table is too big or too complex to grok
> on an iphone, then it's too big or too complex.
>
> so break it up, into a series of smaller tables.
>
> and when you do so, do it in a way such that
> an intelligent viewer-program in the future
> can "stitch" the smaller pieces back together
> when the view-port is big enough to allow it.
> (since that's what intelligent viewer-tools do.)
>
> you can draft the small tables on index cards.
> that'll give you a good sense of the right size,
> and whether each piece has enough integrity
> to stand on its own and be meaningful to us.
>
> also make sure that you can then arrange the
> smaller pieces back together into the full table.
> (make sure that any competent human would
> be able to determine how to do a reassembly.)
>
> having said all that, let's go on to the "10 rules"
> for a light-markup solution to the table problem.
>
> ***
>
> 10 "k.i.s.s." rules for light-markup tables
>
> 1.? all of the lines in a table must be contiguous.
> there must be no blank lines interrupting things.
> each table line must have a space in column 1.
>
> 2.? a table is assumed to be a "basic" table --
> where each line constitutes a row in the table.
> for tables where this is not the case, you must
> use a line of dashes for _all_ separation-lines.
> the viewer-program will draw (faint, gray) lines
> if the reader wants, regardless of what you do.
> any lines that you do include will be respected.
>
> 3.? every cell in a row must be separated from
> neighboring cells by at least 3 spaces, or 1 tab.
> (people who tell you not to use tabs are idiots.)
> if a cell is to be left empty, use a single period.
> a lone period within a cell will not be displayed;
> (the cell will get utilized as a merge candidate).
>
> 4.? the top line(s) of a table might be headers,
> which must not contain internal spaces or tabs.
> (leading and/or trailing spaces or tabs are ok.)
> further thought might allow mid-table headers,
> pending any future rule regarding cell-merging.
> either way, a mid-table line without separators
> will be interpreted to be a table-spanning line.
>
> 5.? the bottom line(s) might be footers, which
> also are not permitted internal spaces or tabs.
> this rule could be combined with #4 if there is
> future need to make room for some new rule.
>
> 6.? the leftmost column will be assumed to be
> the row-headers.? if this is not the case, then
> make the whole first column "empty" by using
> a single period in each cell in that first column.
> the first column in each row must be a space,
> since that's what indicates that this is a "block".
> so a column of dots in column 2 would be seen
> as an indication that there are no row-headers.
>
> 7.? all columns will be aligned automatically,
> according to the type of data in each column.
> 99% of the time, it's fine; embrace constraint.
> an override fluster-clucks user-comprehension.
>
> 8.? i forget what 8 was for.? (never tire of that.)
>
> 9.? aside from the rule about the separators
> -- at least 3 spaces, or 1 tab -- there are no
> other rules regarding the "look" of the table.
> use any font your heart desires. and line up
> the columns if you like, but it's unnecessary.
> the computer will make your table look nice.
> gotta believe.? plus, there's always rule #10.
>
> 10.? redundancy can often be a very good thing.
> in this vein, make a fancy version of your table,
> turn it into a graphic, and include that image-file
> in your e-book, right next to the "raw text data",
> so -- heaven forbid -- if the text just doesn't look
> the way it should, the reader has another option.
>
> ok, i've gotta stop editing this, because i just
> keep adding more elaboration, and that only
> serves to rob this nice little list of its simplicity.
>
> less is more.
>
> -bowerbird
>
> _______________________________________________
> Markdown-Discuss mailing list
> Markdown-Discuss at six.pairlist.net
> http://six.pairlist.net/mailman/listinfo/markdown-discuss
>
>

wander said:
>    A few remarks... 
thanks for your feedback!      :+)

>    Using tabs to format tables 
>    will make your table look awful 
>    for people with different tab sizes.
yes, i get that.

but as i said, this is for my own system,
where i've programmed the viewer-app,
and that program sets all the "tab stops".

i didn't bother to say _how_ it does that,
but a short version is that it copy-fits the
table to look nice in the current view-port.

indeed, one description of how my viewer
earns its praise as an "intelligent" app is 
it copy-fits the entire book to the window.

one example is its widow/orphan control.
another is headings are sized to copy-fit.

>    If your table is so complex 
>    it needs stuff like cell merging
i mentioned cell-merging as a possibility,
and only a possibility.   it'll take examples
from the real-world to see if cell-merging
(a) is possible, and (b) is necessary...

>    Making row and column headers required
>    would annoy me greatly. 
well, i wouldn't want to "annoy you" at all,
let alone "greatly", so i would probably just
tell you that to signal a table, it is required to
put a space in column 1 and a dot in column 2,
_but_ that you could _skip_ the dot in column 2
if you wanted to put a row-header there instead.

>    The single to mark empty cells 
>    feels too magical for me. 
the whole thing should feel "too magical" for you.

but i'm going to make it work.   you just watch me.

>    Having to include images to make sure everyone
>    can read your Markdown document feels... wrong. 
it's not a requirement.   it's just a good suggestion.

my users are making e-books.   the hard part is the
writing and the editing and the polishing and all that.
creating a few images, to make sure that the content
is properly appreciated, is a very small price to them
for the peace-of-mind that the redundancy brings...

>    All in all, I wouldn't really like this 
>    going in mainline Markdown. 
i wouldn't either.   because then "jaguar" wouldn't be
so special, especially in comparison with markdown.

but elegance has a brilliance that spreads itself widely.

-bowerbird
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://six.pairlist.net/pipermail/markdown-discuss/attachments/20110606/f350308d/attachment.html>