Re: Documentation files in html format?

[Willy Tarreau <w@1wt.eu>]

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

Best regards,
Willy