On Fri, 10 Aug 2007 22:17:04 +0200 Willy Tarreau wrote: > Hi Stephen, > > On Thu, Aug 09, 2007 at 11:31:22AM +0100, Stephen Hemminger wrote: > > Since the network device documentation needs a rewrite, I was thinking > > of using basic html format instead of just plain text. But since this would > > be starting an new precedent for kernel documentation, some it seemed > > like a worthwhile topic for discussion. > > 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. Look at the bonding doc I wrote and updated > in 2000, people have updated or duplicated some of the diagrams when > they have added features. Something they would definitely not have done > if it had required some strange tool. > > Also, the advantage of plain text is that it stays compatible with > everything though the years. Had I used some random tool in 2000 for > this, I'm not sure the tool would still exist right now. Look at RFCs.
[resend, sorry about duplicates] This is getting dangerously close to an XML discussion. ;) ISTM (from reading the IETF mailing list) that the recommended tools for generating plaintext RFCs are either a) xml2rfc (from http://tools.ietf.org/inventory/author-tools) or b) an MS Word plugin/macro/whatever. There is also an xml RFC to pdf/ps converter here: http://www.arkko.com/tools/xml2pdfrfc.html > Nothing fancy, just readable. Even the TCP FSM in rfc793 from 26 years > ago is readable, understandable, and updatable by anybody (though it's > a little mit messy). And it's somewhat an extreme case ;-) > > 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... --- ~Randy *** Remember to use Documentation/SubmitChecklist when testing your code *** - 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/
