Re: RFD: tables in documentation

From: Michael J Gruber <git@drmicha.warpmail.net>
Date: May 25, 2010, 11:59 UTC
Message-ID: <4BFBBB97.7010107@drmicha.warpmail.net>
In-Reply-To: <20100525094621.GA984@coredump.intra.peff.net>

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