On 08/11/2007 08:31 AM, Stefan Richter wrote:
Rene Herman wrote:
On 08/10/2007 10:12 PM, Sam Ravnborg wrote:
What primary requirements does in-tree Linux kernel documentation have
to fulfill in general?
Skipping the obvious ones such as correct, up-to-date etc.
o Readable as-is
o Grepable
o buildable as structured documents or almost like a single book
o Easy to replicate structure
o Maintainable in any decent text-editor (emacs, vim, whatever)
Low entry barrier for patches from unsuspecting occasional contributors?
Indeed, and AsciiDoc seems to fit nicely; it's easy to work from example.
Look at:
http://www.methods.co.nz/asciidoc/asciidoc.txt
which is the source for:
http://www.methods.co.nz/asciidoc/asciidoc.css-embedded.html
In fact, one of the more important things for lowering the entry barrier is
providing contributors with infrastructure so that a contributor is free to
concentrate more on the what than the how and as was already argued in this
thread, when you start laying down structure and rules for Documentation/,
you end up with something close to AsciiDoc anyway.
Easy to put online?
http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=tree;f=Documentation
http://lxr.linux.no/source/Documentation/
http://users.sosdg.org/~qiyong/lxr/source/Documentation/
http://www.linux-m32r.org/lxr/http/source/Documentation/
http://lxr.free-electrons.com/source/Documentation/
Easy to put online in a nice way. Compare:
http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/kbuild/makefiles.txt;h=e08ef8759a0780caaa237a5a88ad8d921208af98;hb=HEAD
and
http://www.ravnborg.org/kbuild/makefiles.html
as Sam posted. I certainly think the latter reads nicer (it's missing the
table of content for now, but that appears to be a tool option).
(I admit though that formats like asciidoc or docbook are beneficial for
larger documentation files which want chapters, table of contents, and
internal crossreferences.)
I personally wouldn't want to rudely outlaw plain text -- the discussion
happened due to someone suggesting redoing some documentation in HTML. Some
people suggested DocBook (hnnng!) and now asciidoc.
I think that DocBook is a bloody trainwreck (yes, "make pdfdocs" bombs out
for me at the moment as well -- has it ever been different) but that some
simple formatting quite often makes for an improvement over plain text.
HTML directly would do as far as I'm concerned, but AsciiDoc can also
generate that and additionally imposes more structure (in the sense of
uniformity) than direct HTML would. On the downside it still requires some
external software, on the upside it directly translates to many more formats
when viewed as a DocBook pre-processor.
Works for me...
Rene.
-
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/
[Index of Archives]
[Kernel Newbies]
[Netfilter]
[Bugtraq]
[Photo]
[Stuff]
[Gimp]
[Yosemite News]
[MIPS Linux]
[ARM Linux]
[Linux Security]
[Linux RAID]
[Video 4 Linux]
[Linux for the blind]
[Linux Resources]
