threads / discuss / 23660

RFD: tables in documentation

Subject: RFD: tables in documentation

## tl;dr

11 messages between May 1, 2010 and May 25, 2010.

replies: 10people: 4as markdown or json

Michael J Gruber· May 1, 2010, 18:37 UTC · lore

Currently, all tables are formatted using indentation by spaces. This breaks whenever AsciiDoc's parsing changes.

Instead, I suggest to use AsciiDoc's table syntax which also produces proper tables in the HTML and man output. I formatted the first part of the first table in git-read-tree(1) like that so that you can compare easily.

I put it up at http://repo.or.cz/w/git/mjg.git/commit/table-example for your viewing pleasure. I'd say it looks great even in links (but not in lynx). It also shows a problem of xmlto with multiple rowspans (the xml is correct, .1 apparently not), which could be circumvented easily by repeating those cells.

HTML: http://repo.or.cz/w/git/mjg.git/blob_plain/table-example:/Documentation/git-read-tree.html

MAN: http://repo.or.cz/w/git/mjg.git/blob_plain/table-example:/Documentation/git-read-tree.1

MAN converted to txt by man: http://repo.or.cz/w/git/mjg.git/blob_plain/table-example:/Documentation/git-read-tree.1.txt

MAN converted to HTML by man2html: http://repo.or.cz/w/git/mjg.git/blob_plain/table-example:/Documentation/git-read-tree.1.html

Cheers, Michael

Jeff King· May 2, 2010, 05:06 UTC · re: Michael J Gruber · lore

Re: RFD: tables in documentation

On Sat, May 01, 2010 at 08:37:39PM +0200, Michael J Gruber wrote:
Show 7 quoted lines
> Currently, all tables are formatted using indentation by spaces. This
> breaks whenever AsciiDoc's parsing changes.
> 
> Instead, I suggest to use AsciiDoc's table syntax which also produces
> proper tables in the HTML and man output. I formatted the first part of
> the first table in git-read-tree(1) like that so that you can compare
> easily.

Conceptually I am in favor of semantic markup where possible. I find the resulting manpage a little harder to read, though. Is it possible for us to style it a bit more (e.g., such a simple table looks better, IMHO, without ascii-art borders).

Show 5 quoted lines
> I put it up at http://repo.or.cz/w/git/mjg.git/commit/table-example for
> your viewing pleasure. I'd say it looks great even in links (but not in
> lynx). It also shows a problem of xmlto with multiple rowspans (the xml
> is correct, .1 apparently not), which could be circumvented easily by
> repeating those cells.

Did you put the source up anywhere? I didn't see it, but it would be interesting to see how painful it is to write.

-Peff
Michael J Gruber· May 2, 2010, 13:31 UTC · re: Jeff King · lore

Re: RFD: tables in documentation

Jeff King venit, vidit, dixit 02.05.2010 07:06:
Show 14 quoted lines
> On Sat, May 01, 2010 at 08:37:39PM +0200, Michael J Gruber wrote:
> 
>> Currently, all tables are formatted using indentation by spaces. This
>> breaks whenever AsciiDoc's parsing changes.
>>
>> Instead, I suggest to use AsciiDoc's table syntax which also produces
>> proper tables in the HTML and man output. I formatted the first part of
>> the first table in git-read-tree(1) like that so that you can compare
>> easily.
> 
> Conceptually I am in favor of semantic markup where possible. I find the
> resulting manpage a little harder to read, though. Is it possible for us
> to style it a bit more (e.g., such a simple table looks better, IMHO,
> without ascii-art borders).

I really don't know (about styling docbook's tables). We can easily switch off the outer borders in AsciiDoc.

The docbook part of the toolchain makes me sick whenever I have to look at it. I really wish AsciiDoc could output roff straight away. I find it incredibly hard to find the relevant information for this part of the toolchain since it involves xmlto as well as the style sheets. Also, at least my version of xmlto/style sheets/whatever does not cope well with adjacent (or even non-adjacent multiple) rowspans, see below. Only the vger.k.o. outage kept me from posting without noticing this before...

Show 9 quoted lines
> 
>> I put it up at http://repo.or.cz/w/git/mjg.git/commit/table-example for
>> your viewing pleasure. I'd say it looks great even in links (but not in
>> lynx). It also shows a problem of xmlto with multiple rowspans (the xml
>> is correct, .1 apparently not), which could be circumvented easily by
>> repeating those cells.
> 
> Did you put the source up anywhere? I didn't see it, but it would be
> interesting to see how painful it is to write.
http://repo.or.cz/w/git/mjg.git/shortlog/refs/heads/doc-use-tables
Tough guess, I know ;)
Michael
Will Palmer· May 2, 2010, 14:43 UTC · re: Michael J Gruber · lore

Re: RFD: tables in documentation

On Sun, 2010-05-02 at 15:31 +0200, Michael J Gruber wrote:
Show 10 quoted lines
> Jeff King venit, vidit, dixit 02.05.2010 07:06:
> > On Sat, May 01, 2010 at 08:37:39PM +0200, Michael J Gruber wrote:
> > Did you put the source up anywhere? I didn't see it, but it would be
> > interesting to see how painful it is to write.
> 
> http://repo.or.cz/w/git/mjg.git/shortlog/refs/heads/doc-use-tables
> 
> Tough guess, I know ;)
> 
> Michael

that looks suspiciously like a format that's intended to be readable in both plaintext and eventually-generated form. This is me speaking in pure ignorance, but would something like:

-- 
-- Will
Will Palmer· May 2, 2010, 14:51 UTC · re: Will Palmer · lore

Re: RFD: tables in documentation

sorry about that, apparently "shift+enter" means "send" to this thing...
On Sun, 2010-05-02 at 15:43 +0100, Will Palmer wrote:
Show 12 quoted lines
> On Sun, 2010-05-02 at 15:31 +0200, Michael J Gruber wrote:
> > Jeff King venit, vidit, dixit 02.05.2010 07:06:
> > > On Sat, May 01, 2010 at 08:37:39PM +0200, Michael J Gruber wrote:
> > > Did you put the source up anywhere? I didn't see it, but it would be
> > > interesting to see how painful it is to write.
> > 
> > http://repo.or.cz/w/git/mjg.git/shortlog/refs/heads/doc-use-tables
> > 
> > Tough guess, I know ;)
> > 
> > Michael
>

that looks suspiciously like a format that's intended to be readable in both plaintext and eventually-generated form. This is me speaking in pure ignorance, but would something like (though I assume not exactly):

[cols="1,3*5,8"]
   |=====================
   |		   |I		 |H		|M		|Result
   |     0	   |nothing	 |nothing	|nothing	|(does not happen)
   |     1	   |nothing	 |nothing	|exists		|use M
   |     2	   |nothing	 |exists	|nothing	|remove path from index
.2+|	 3	.2+|nothing   .2+|exists	|exists, H == M |use M if "initial checkout", keep index otherwise
						 exists, H != M |fail
   |=====================
work as intended?
-- 
-- Will
Michael J Gruber· May 2, 2010, 15:08 UTC · re: Will Palmer · lore

Re: RFD: tables in documentation

Will Palmer venit, vidit, dixit 02.05.2010 16:51:
Show 32 quoted lines
> sorry about that, apparently "shift+enter" means "send" to this thing...
> 
> On Sun, 2010-05-02 at 15:43 +0100, Will Palmer wrote:
>> On Sun, 2010-05-02 at 15:31 +0200, Michael J Gruber wrote:
>>> Jeff King venit, vidit, dixit 02.05.2010 07:06:
>>>> On Sat, May 01, 2010 at 08:37:39PM +0200, Michael J Gruber wrote:
>>>> Did you put the source up anywhere? I didn't see it, but it would be
>>>> interesting to see how painful it is to write.
>>>
>>> http://repo.or.cz/w/git/mjg.git/shortlog/refs/heads/doc-use-tables
>>>
>>> Tough guess, I know ;)
>>>
>>> Michael
>>
> 
> that looks suspiciously like a format that's intended to be readable in
> both plaintext and eventually-generated form. This is me speaking in
> pure ignorance, but would something like (though I assume not exactly):
> 
> [cols="1,3*5,8"]
>    |=====================
>    |		   |I		 |H		|M		|Result
>    |     0	   |nothing	 |nothing	|nothing	|(does not happen)
>    |     1	   |nothing	 |nothing	|exists		|use M
>    |     2	   |nothing	 |exists	|nothing	|remove path from index
> .2+|	 3	.2+|nothing   .2+|exists	|exists, H == M |use M if "initial checkout", keep index otherwise
> 						 exists, H != M |fail
>    |=====================
> 
> work as intended?
>

Uhm, how is that different from my patch (except for spaces which I didn't bother with for this p-o-c)? [This is AsciiDoc - you know, do you? ;)]

Jeff doesn't like the ascii art in the roff output (.1, as can be seen in the .1.txt file). It looks very "strong", just like the content.

Further experimentation (editing the xml) indicates that with my toolchain, I can either shut off all borders (between cells as well as outer) or none. Why does working with the toolchain always frustrate me? It's often a hindrance for improvements.

So, we could shut off all borders by adding an output dependent table definition in asciidoc.conf, copying current asciidoc's own and modifying it for docbook-man output. Is it worth it? Maybe others like the strong ascii borders...

Michael
Michael J Gruber· May 2, 2010, 15:27 UTC · re: Michael J Gruber · lore

Re: RFD: tables in documentation

Michael J Gruber venit, vidit, dixit 02.05.2010 17:08:
Show 50 quoted lines
> Will Palmer venit, vidit, dixit 02.05.2010 16:51:
>> sorry about that, apparently "shift+enter" means "send" to this thing...
>>
>> On Sun, 2010-05-02 at 15:43 +0100, Will Palmer wrote:
>>> On Sun, 2010-05-02 at 15:31 +0200, Michael J Gruber wrote:
>>>> Jeff King venit, vidit, dixit 02.05.2010 07:06:
>>>>> On Sat, May 01, 2010 at 08:37:39PM +0200, Michael J Gruber wrote:
>>>>> Did you put the source up anywhere? I didn't see it, but it would be
>>>>> interesting to see how painful it is to write.
>>>>
>>>> http://repo.or.cz/w/git/mjg.git/shortlog/refs/heads/doc-use-tables
>>>>
>>>> Tough guess, I know ;)
>>>>
>>>> Michael
>>>
>>
>> that looks suspiciously like a format that's intended to be readable in
>> both plaintext and eventually-generated form. This is me speaking in
>> pure ignorance, but would something like (though I assume not exactly):
>>
>> [cols="1,3*5,8"]
>>    |=====================
>>    |		   |I		 |H		|M		|Result
>>    |     0	   |nothing	 |nothing	|nothing	|(does not happen)
>>    |     1	   |nothing	 |nothing	|exists		|use M
>>    |     2	   |nothing	 |exists	|nothing	|remove path from index
>> .2+|	 3	.2+|nothing   .2+|exists	|exists, H == M |use M if "initial checkout", keep index otherwise
>> 						 exists, H != M |fail
>>    |=====================
>>
>> work as intended?
>>
> 
> Uhm, how is that different from my patch (except for spaces which I
> didn't bother with for this p-o-c)? [This is AsciiDoc - you know, do
> you? ;)]
> 
> Jeff doesn't like the ascii art in the roff output (.1, as can be seen
> in the .1.txt file). It looks very "strong", just like the content.
> 
> Further experimentation (editing the xml) indicates that with my
> toolchain, I can either shut off all borders (between cells as well as
> outer) or none. Why does working with the toolchain always frustrate me?
> It's often a hindrance for improvements.
> 
> So, we could shut off all borders by adding an output dependent table
> definition in asciidoc.conf, copying current asciidoc's own and
> modifying it for docbook-man output. Is it worth it? Maybe others like
> the strong ascii borders...
For completeness, it results in this:
     I                H         M               Result
 0   nothing          nothing   nothing         (does not happen)
 1   nothing          nothing   exists          use M
 2   nothing          exists    nothing         remove path from index
 3   nothing          exists    exists, H ==M   use M if "initial
                                                checkout", keep index
     exists, H != M             fail            otherwise

[Same unealt rowspan issue, of course.] Michael

Jonathan Nieder· May 2, 2010, 17:53 UTC · re: Michael J Gruber · lore

Re: RFD: tables in documentation

Hi Michael,
Michael J Gruber wrote:
> Michael J Gruber venit, vidit, dixit 02.05.2010 17:08:
>> Further experimentation (editing the xml) indicates that with my
>> toolchain, I can either shut off all borders (between cells as well as
>> outer) or none.
[...]
Show 15 quoted lines
> For completeness, it results in this:
> 
>      I                H         M               Result
> 
>  0   nothing          nothing   nothing         (does not happen)
> 
>  1   nothing          nothing   exists          use M
> 
>  2   nothing          exists    nothing         remove path from index
> 
>  3   nothing          exists    exists, H ==M   use M if "initial
>                                                 checkout", keep index
>      exists, H != M             fail            otherwise
> 
> [Same unealt rowspan issue, of course.]

For what it’s worth, except for the broken last row, I like this and find it readable. It is too bad there is no way to make it more compact so more rows can fit on a screen or page.

The ideal, to delimit the header without appearing busy, would be to just have a thin horizontal rule separating the header from the remaining rows[1]. Vertical rules are almost never a good idea. Maybe frame="topbot",grid="none",options="header" would be a good approximation.

Jonathan

[1] Just my opinion. I probably learned the aesthetic from Simon Fear. http://www.tex.ac.uk/cgi-bin/texfaq2html?label=destable

Michael J Gruber· May 2, 2010, 19:23 UTC · re: Jonathan Nieder · lore

Re: RFD: tables in documentation

Jonathan Nieder venit, vidit, dixit 02.05.2010 19:53:
Show 34 quoted lines
> Hi Michael,
> 
> Michael J Gruber wrote:
>> Michael J Gruber venit, vidit, dixit 02.05.2010 17:08:
> 
>>> Further experimentation (editing the xml) indicates that with my
>>> toolchain, I can either shut off all borders (between cells as well as
>>> outer) or none.
> [...]
>> For completeness, it results in this:
>>
>>      I                H         M               Result
>>
>>  0   nothing          nothing   nothing         (does not happen)
>>
>>  1   nothing          nothing   exists          use M
>>
>>  2   nothing          exists    nothing         remove path from index
>>
>>  3   nothing          exists    exists, H ==M   use M if "initial
>>                                                 checkout", keep index
>>      exists, H != M             fail            otherwise
>>
>> [Same unealt rowspan issue, of course.]
> 
> For what it’s worth, except for the broken last row, I like this and
> find it readable.  It is too bad there is no way to make it more
> compact so more rows can fit on a screen or page.
> 
> The ideal, to delimit the header without appearing busy, would be to
> just have a thin horizontal rule separating the header from the
> remaining rows[1].  Vertical rules are almost never a good idea.
> Maybe frame="topbot",grid="none",options="header" would be a good
> approximation.

That looks nice in HTML (and produces the correct xml), but unfortunately my docbook renders this as if I had frame="all",grid="all" :(

Show 5 quoted lines
> 
> Jonathan
> 
> [1] Just my opinion.  I probably learned the aesthetic from Simon Fear.
> http://www.tex.ac.uk/cgi-bin/texfaq2html?label=destable
Jeff King· May 25, 2010, 09:46 UTC · re: Michael J Gruber · lore

Re: RFD: tables in documentation

[This is an old message, but I'm going through some old threads on my todo, and I owed you a response.]

On Sun, May 02, 2010 at 03:31:02PM +0200, Michael J Gruber wrote:
Show 7 quoted lines
> > Conceptually I am in favor of semantic markup where possible. I find the
> > resulting manpage a little harder to read, though. Is it possible for us
> > to style it a bit more (e.g., such a simple table looks better, IMHO,
> > without ascii-art borders).
> 
> I really don't know (about styling docbook's tables). We can easily
> switch off the outer borders in AsciiDoc.

I do think the border-less table that you presented later in the thread looks good, modulo the row-span issue.

And:
> > Did you put the source up anywhere? I didn't see it, but it would be
> > interesting to see how painful it is to write.
> 
> http://repo.or.cz/w/git/mjg.git/shortlog/refs/heads/doc-use-tables
I think the source remains pretty readable.

So assuming you can solve the row-span problem, I think it is a positive change.

> The docbook part of the toolchain makes me sick whenever I have to look
> at it. I really wish AsciiDoc could output roff straight away. I find it
Yes, I have also wished for that many times.
-Peff
Michael J Gruber· May 25, 2010, 11:59 UTC · re: Jeff King · lore

Re: RFD: tables in documentation

Jeff King venit, vidit, dixit 25.05.2010 11:46:
> [This is an old message, but I'm going through some old threads on my
> todo, and I owed you a response.]

I've been revisiting this myself just the other day - did someone say connecting minds?

Show 32 quoted lines
> 
> On Sun, May 02, 2010 at 03:31:02PM +0200, Michael J Gruber wrote:
> 
>>> Conceptually I am in favor of semantic markup where possible. I find the
>>> resulting manpage a little harder to read, though. Is it possible for us
>>> to style it a bit more (e.g., such a simple table looks better, IMHO,
>>> without ascii-art borders).
>>
>> I really don't know (about styling docbook's tables). We can easily
>> switch off the outer borders in AsciiDoc.
> 
> I do think the border-less table that you presented later in the thread
> looks good, modulo the row-span issue.
> 
> And:
> 
>>> Did you put the source up anywhere? I didn't see it, but it would be
>>> interesting to see how painful it is to write.
>>
>> http://repo.or.cz/w/git/mjg.git/shortlog/refs/heads/doc-use-tables
> 
> I think the source remains pretty readable.
> 
> So assuming you can solve the row-span problem, I think it is a
> positive change.
> 
>> The docbook part of the toolchain makes me sick whenever I have to look
>> at it. I really wish AsciiDoc could output roff straight away. I find it
> 
> Yes, I have also wished for that many times.
> 
> -Peff

Unfortunately, docbook still sucks. (I was hoping it would improve with Fedora 13, although I knew it wouldn't.)

I checked, again, that AsciiDoc produces correct docbook. But docbook has a problem with adjacent rowspans, and also with frames and grids: As soon as you specify any line element (say, "frame=topbot" or "grid=columns") docbook uses full frames and full grids. And I think having at least topbot would be helpful.

I think we should just get rid off the nroff pages and view man pages in html through links or such... [I noticed that lynx doesn't cope with the table, though.]

Alternatively, I would set up a default configuration in asciidoc.conf which uses topbot for html and no lines whatsoever for docbook, and circumvent adjacent rowspans. When/if docbook improves that workaround can be changed in that single place.

Michael

← back to recent threads