Re: WIP: asciidoc replacement

From: Martin Langhoff <martin.langhoff@gmail.com>
Date: Oct 4, 2007, 06:55 UTC
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