lkml.org 
[lkml]   [2016]   [Mar]   [8]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    Date
    From
    SubjectRe: Kernel docs: muddying the waters a bit
    Em Tue, 08 Mar 2016 05:09:40 -0700
    Dan Allen <dan@opendevise.io> escreveu:

    > Jani wrote:
    >
    > > there was no support for chunked, or split
    > > to chapters, HTML, and the single page result was simply way too big.
    > >
    >
    > That's not entirely true. First, you can pre-split at the source level
    > using includes and generate output for each of the masters. That's what I
    > tend to do and it works really well since these are logical split points.

    The problem on pre-splitting the documents and process them in separate
    is that this will break cross-references. At the media uAPI Docbook,
    we use a lot of cross references.

    Btw, we use a lot of includes. Currently, it has 187 separate files.

    We even parse the header files looking for typedefs, structs, enums,
    #defines and functions, in order to produce a document that will
    cross-reference the documentation.

    > Second, there is a custom converter in the works to split post-generate
    > (which is really what we're talking about when we compare it to the DocBook
    > toolchain).
    >
    > https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/multipage-html5-converter.rb
    >
    > It's just a prototype, but proves it is possible by design.

    I didn't test it, but I saw some comments at the web that the part
    that would handle cross-references between files is not ready.

    > Personally, I don't like most chunked HTML approaches because they split
    > arbitrarily. We are trying to find the right balance so that the output is
    > actually sensible. There's still work to do, but there are options in the
    > meantime.

    Well, if it is capable of creating one chunk per include file, and do
    cross-references between chunks, this would work for media UAPI book.

    Yet, it would be good to have the multi-chunk extension packaged
    on major distros, as I don't like the idea of installing it without
    using my distro's package manager.

    --
    Thanks,
    Mauro

    \
     
     \ /
      Last update: 2016-03-08 15:01    [W:6.632 / U:0.036 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site