Re: WIP: asciidoc replacement

From: David Kastrup <dak@gnu.org>
Date: Oct 3, 2007, 10:25 UTC
Message-ID: <85k5q4v6jb.fsf@lola.goethe.zz>
In-Reply-To: <1D18C52E-BB96-49EC-97A9-F802D56CAFF5@wincent.com>

Wincent Colaiuta <win@wincent.com> writes:

Show 12 quoted lines

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

The problem is that we are not editing plain text, but Docbook source masquerading as plain text.

Show 13 quoted lines

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

But it is not all _all_ easily writeable the moment you try to do something with _structural_ impact. In fact, it is pretty much impossible for anybody except wizards to do that. And when the wizards do it, they can't actually document what they have been doing since that would mean cluttering the purported "plain text documentation" with formatting comments.

Maybe it would help to rename *.txt to *.asciidoc and generate *.txt in future. That would at least make it possible to document stuff in the AsciiDoc source, and also would make it possible to add indexing info and other stuff without cluttering up the plain text use case.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum