Wincent Colaiuta <win@xxxxxxxxxxx> writes: > 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. > 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@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
