Re: RFD: tables in documentation

From: Jeff King <peff@peff.net>
Date: May 2, 2010, 05:06 UTC
Message-ID: <20100502050622.GF14776@coredump.intra.peff.net>
In-Reply-To: <4BDC74F3.2020206@drmicha.warpmail.net>

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