On Fri, Aug 10, 2007 at 04:40:25PM -0400, J. Bruce Fields wrote: > On Fri, Aug 10, 2007 at 10:17:04PM +0200, Willy Tarreau wrote: > > I've read pro-plain text arguments, so I'll not repeat them. I also see > > another advantage to plain text : it's very easy to draw ascii-art > > diagrams of anything. It only takes a few minutes, is always inline > > and readable with any tool. > > Asciidoc should preserve ascii-art diagrams OK; the git docs use them > all over. > > Not that I'd necessarily push asciidoc. But: > > > I'd prefer that you define some writing conventions for plain-text > > documents that anyone should try follow, starting with the 80-cols > > limit to make Davem happy. I think that many of us can help define > > such a "standard" indicating how to underline subtitles, how to > > enumerate a list, how to avoid using tabs, how to write boxes and > > arrows in their diagrams, etc... > > ... at the point where you actually start setting standards for subtitle > underlining and list enumeration, you'd want to take another look at > asciidoc; since it already defines conventions for that stuff (which > are probably close to what people would do anyway), it might make sense > just to start using asciidoc.
The problem I have with asciidoc is that it's a nightmare to get it to work. It's what GIT uses, and after spending a whole day trying to *build* that thing, I finally resigned and asked Junio if he could publish the pre-formatted manpages himself, which he agreed to. All I remember is that there was a very deep level of dependencies through XML craps^H^H^H^H^Hpackages and I don't remember what magic things, but one full day trying to build something to read a doc is too much, so I imagine that I would not even have tried that long if I had wanted to complete a doc and check that my changes looked right. Maybe the language is fine, but the tool needs to build first. Willy - To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
