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