Wincent Colaiuta <win@wincent.com> writes:

quoted text
> 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
-
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