Re: [ANNOUNCE] GIT 1.5.3-rc4

From: David Kastrup <dak@gnu.org>
Date: Aug 4, 2007, 07:30 UTC
Message-ID: <85wswbiwoz.fsf@lola.goethe.zz>
In-Reply-To: <7vfy2zj4nj.fsf@assigned-by-dhcp.cox.net>

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

Show 9 quoted lines

> 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.

[...]

Show 11 quoted lines

> 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