Re: RFD: tables in documentation

From: Michael J Gruber <git@drmicha.warpmail.net>
Date: May 2, 2010, 13:31 UTC
Message-ID: <4BDD7E96.2050603@drmicha.warpmail.net>
In-Reply-To: <20100502050622.GF14776@coredump.intra.peff.net>

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