Re: WIP: asciidoc replacement

From: David Kastrup <dak@gnu.org>
Date: Oct 3, 2007, 08:12 UTC
Message-ID: <85abr0y5ua.fsf@lola.goethe.zz>
In-Reply-To: <39F3EE1B-7BD4-4927-AB90-2EB4BBAF05D0@wincent.com>

Wincent Colaiuta <win@wincent.com> writes:

Show 15 quoted lines

> El 3/10/2007, a las 6:48, Junio C Hamano escribió:
>
>>  - Does it make sense in the longer term for us to maintain
>>    in-house documentation tools?  Can we afford it?
>>
>> It appears that we heard about breakages for every minor docbook
>> updates, and it is really appealing if we do not have to rely on
>> xsl toolchain for manpage generation.
>
> Indeed, especially seeing as asciidoc and the xsl toolchain are the  
> trickiest build dependencies to install. If all that could be  
> replaced by a single simple script like this one then that would be  
> awesome, and probably more maintainable in the long run seeing as it  
> would eliminate those intermittent breakages caused by changes in  
> third-party tools.

What with output in print, HTML, info? The advantage of a toolchain in that it is flexible. I am the first to admit that getting the AsciiDoc/Docbook/Docbook2X toolchain to get it to do what one wants to is like baking cake in a lightless kitchen. But it is not like we go through that pain without any reason.

Personally, I think it might make sense to just step away from the AsciiDoc documentation to Docbook: plain text (without cutified formatting control like in AsciiDoc) can be generated _from_ Docbook.

And AsciiDoc keeps us from documenting the formatting: Docbook, which is a source format and looks it, can easily admit comments that won't get through to the formatted versions. Sure, the first version would likely be generated with AsciiDoc and thus basically uncommented.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum