From: Michael J Gruber <git@drmicha•warpmail.net>
To: Jeff King <peff@peff•net>
Cc: Git Mailing List <git@vger•kernel.org>
Subject: Re: RFD: tables in documentation
Date: Tue, 25 May 2010 13:59:19 +0200 [thread overview]
Message-ID: <4BFBBB97.7010107@drmicha.warpmail.net> (raw)
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?
>
> 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
prev parent reply other threads:[~2010-05-25 11:59 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-05-01 18:37 RFD: tables in documentation Michael J Gruber
2010-05-02 5:06 ` Jeff King
2010-05-02 13:31 ` Michael J Gruber
2010-05-02 14:43 ` Will Palmer
2010-05-02 14:51 ` Will Palmer
2010-05-02 15:08 ` Michael J Gruber
2010-05-02 15:27 ` Michael J Gruber
2010-05-02 17:53 ` Jonathan Nieder
2010-05-02 19:23 ` Michael J Gruber
2010-05-25 9:46 ` Jeff King
2010-05-25 11:59 ` Michael J Gruber [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=4BFBBB97.7010107@drmicha.warpmail.net \
--to=git@drmicha$(echo .)warpmail.net \
--cc=git@vger$(echo .)kernel.org \
--cc=peff@peff$(echo .)net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox