Junio C Hamano <gitster@pobox.com> writes:

quoted text
> Steven Grimm <koreth@midwinter.com> writes:
>
>> Am I correct in observing that "*roff -man" and HTML are the only
>> two output formats we care about, or do people use other formats in
>> their private branches?
>
> I obviously do not speak for others, but the only format I care
> about personally is the *.txt one.  We picked asciidoc primarily
> because the source language was readable.

[...]

quoted text
> It might be more worthwhile to research what other "Text-ish
> lightweight mark-up" systems are availble, and if there is one
> that is more efficient and can go to at least html and man,
> one-time convert our documentation source to that format using
> your Perl magic.  The minimum requirements are:
>
>  * The source is readable without too much mark-up distraction;
>
>  * Can go to roff -man;
>
>  * Can go to html.

Naturally I am biased, but Texinfo might be an option.  The source is
editable without too much distraction, one can generate HTML, printed
output, cross-referenced info files (those are really convenient for
Emacs users), cross-referenced PDF output.  For man pages, one could
follow the path outlined in
<URL:http://gcc.gnu.org/onlinedocs/gccint/Man-Page-Generation.html>.
That is probably the weakest point.

Plain, user-readable ASCII text without any Texinfo markup can also be
generated.  One can even include images in info, PDF and HTML and have
those replaced by ASCII art in the plain text output.

There are some disadvantages: AFAIR, utf-8 characters will in general
not fly.  One needs to code accented characters more or less
explicitly.

Texinfo conversions are fast.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html