Randy Dunlap wrote: > On Sat, 11 Aug 2007 16:17:19 +0200 Willy Tarreau wrote: >> On Sat, Aug 11, 2007 at 10:19:25AM -0400, J. Bruce Fields wrote: >>> I was just suggesting that if we took your suggestion of standardizing >>> on plain text plus some conventions for formatting lists and headers and >>> such, one easy way to do that might just be to adopt the asciidoc format >>> (or some subset thereof). Is there any part of the asciidoc *syntax* >>> that you object to? >> Not particularly. It's just slightly less readable as plain text but >> OTOH produces nice documents when you have a working toolchain. But >> that's a language which needs to be learned, as every such language. >> Plain text on the contrary, requires no learning. The conventions are >> more like suggestions to newcomers. Everyone is free to proceed as he >> wants, judging by the result while writing the text.
> but if we use something richer than plain text, I think that we > shouldn't need to invent yet another markup language. > Just use HTML or asciidoc or MarkDown etc... *If* we switch to a markup language instead of plaintext (or instead of plaintext with style recommendations), then submitters should at least be able to do basic syntax checks without having a toolchain installed. E.g. provide a scripts/checkdocumentation.p[ly] similar in function to scripts/checkpatch.pl. (OK, that one requires a perl interpreter installed, but that's a fair requirement.) One note on asciidoc: I experienced the same as Willy when I wanted to build git with manpages on a distribution without prebuilt asciidoc. And when I finally managed to build a minimum asciidoc setup, I was bitten by a syntax change in the asciidoc language, requiring a small change to git's documentation source to be compatible with both asciidoc 7.x and asciidoc 8.x IIRC. -- Stefan Richter -=====-=-=== =--- -==-- http://arcgraph.de/sr/ - 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/
