Re: WIP: asciidoc replacement
- From
Wincent Colaiuta <win@wincent.com>
- Date
- Oct 3, 2007, 10:05 UTC
- Message-ID
- <1D18C52E-BB96-49EC-97A9-F802D56CAFF5@wincent.com>
- In-Reply-To
- <85abr0y5ua.fsf@lola.goethe.zz>
El 3/10/2007, a las 10:12, David Kastrup escribió:
> What with output in print, HTML, info?
Yes, that's still a problem...
> 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.
Yes, but editing DocBook (XML) is relatively painful compared to editing plain text. You either have to rely on a bloated XML- validating editor or instead ask your doc authors to manually write valid XML (and I totally agree with Terrence Parr that, "XML makes a lousy human interface "; see <http://www.ibm.com/developerworks/xml/library/x-sbxml.html> for his full take).
I know that Linus has argued for AsciiDoc because the source *is* the plain text documentation and is therefore easily readable, but for me the real benefit lies in the fact that *because* the source is plain text it is easily edited (ie. that the source is easily *writeable*), and things like documentation patches are very neat with AsciiDoc.
Cheers, Wincent