Wincent Colaiuta <win@wincent.com> writes:

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

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

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