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    [W:0.207 / U:0.508 seconds]
    ©2003-2016 Jasper Spaans. hosted at Digital OceanAdvertise on this site