lkml.org 
[lkml]   [2007]   [Aug]   [11]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: Documentation files in html format?
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 majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/

\
 
 \ /
  Last update: 2007-08-11 21:19    [from the cache]
©2003-2011 Jasper Spaans