Re: Documentation files in html format?

[Stefan Richter <stefanr@s5r6.in-berlin.de>]

Sam Ravnborg wrote:
> On Thu, Aug 09, 2007 at 05:26:13PM +0200, Andi Kleen wrote:
>> Also I would expect much more people will know how to write html versus
>> DocBook.
> 
> Documentation should be easy to access and readable in the source format.
> For this purpose asciidoc seems to do a good job.
> 
> It is btw. discussed at git ML if they should shift due to toolset being
> slow but that happens to be the docbook utilities. asciidoc seems to be fast enough.
> And it can produce both HTML and docbook so seems to cover all cases.

It's true that asciidoc sources are nice to read in a plaintext viewer,
while HTML is not.  However, regardless whether the documentation is
written in HTML or docbook or asciidoc, all contributors will be forced
to learn the respective format --- otherwise the documentation will
become syntactically incorrect very quickly.

So, let's recall the start of this thread.  Stephen Hemminger wrote:
| Since the network device documentation needs a rewrite, I was thinking
| of using [CENSORED] format instead of just plain text.

What primary requirements does the network device documentation have to
fulfill?

What primary requirements does in-tree Linux kernel documentation have
to fulfill in general?

(Note that git's documentation has as one of its first and foremost
requirements that man pages can be generated.  This requirement does not
exist for the bulk of Linux kernel documentation.)

I've got a hunch that the most suitable format for Linux kernel
documentation, after careful consideration of what we want from it and
how we author and maintain it, will turn out to be...


...plaintext.
-- 
Stefan Richter
-=====-=-=== =--- -=-=-
http://arcgraph.de/sr/