RFD: tables in documentation

RFD: tables in documentation

[Michael J Gruber]

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

Re: RFD: tables in documentation

[Jeff King]

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 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

Re: RFD: tables in documentation

[Michael J Gruber]

Jeff King venit, vidit, dixit 02.05.2010 07:06:
> 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...

> 
>> 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

Re: RFD: tables in documentation

[Will Palmer]

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:



-- 
-- Will

Re: RFD: tables in documentation

[Will Palmer]

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?


-- 
-- Will

Re: RFD: tables in documentation

[Michael J Gruber]

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...

Michael

Re: RFD: tables in documentation

[Michael J Gruber]

Michael J Gruber venit, vidit, dixit 02.05.2010 17:08:
> 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

Re: RFD: tables in documentation

[Jonathan Nieder]

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.

Jonathan

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

Re: RFD: tables in documentation

[Michael J Gruber]

Jonathan Nieder venit, vidit, dixit 02.05.2010 19:53:
> 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" :(

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

Re: RFD: tables in documentation

[Jeff King]

[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:

> > 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

Re: RFD: tables in documentation

[Michael J Gruber]

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?

> 
> 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