From: Martin Langhoff <martin.langhoff@gmail.com>
Date: Thu, 04 Oct 2007 06:55:46 GMT
Subject: Re: WIP: asciidoc replacement
Message-ID: <46a038f90710032355t77c38d30p781743a6f248fab5@mail.gmail.com>
In-Reply-To: <7vd4vwfou9.fsf@gitster.siamese.dyndns.org>

Junio,

great summary!

On 10/3/07, Junio C Hamano <gitster@pobox.com> wrote:
> One thing Linus had to say about the issue from early on, and I
> still agree with, is the last paragraph in:
>
>     http://article.gmane.org/gmane.comp.version-control.git/2298

I'm in complete agreement here...

...
> I've seen markdown used elsewhere, and I regularly read pod.
...
> How good are HTML and manpage output support from these (or
> other candidates) formats these days?  Output to help page
> format Windows folks use (I am assuming Mac people are happy as
> long as man is available) would be a definite plus.

And something that leads to PDF (perhaps via latex).

The problem I see here -- and that I've bumped into several times in
other projects -- is that readable & easy to edit text formats for the
source are key, and those can do most of what we need for
man/info/html outputs. But documentation formats that produce high
quality print output usually need  arcane formats _and_ a
high-maintenance toolchain.

With AsciiDoc we've managed to avoid the arcane format, but we are
still laden with a horrid toolchain. In that light, I actually like
what Johannes is doing, even though it's a timesink.

Do the other text based alternatives these days have a workable high
quality PDF/latex output format without pulling in brittle
dependencies like XSLT?

cheers


martin