Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1353040

Re: Kernel docs: muddying the waters a bit

Show key headers only | View raw

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

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

Re: Kernel docs: muddying the waters a bit Jani Nikula <jani.nikula@intel.com> - 2016-03-08 10:50 +0100
  Re: Kernel docs: muddying the waters a bit Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-03-08 12:40 +0100
    Re: Kernel docs: muddying the waters a bit Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-03-08 14:40 +0100
      Re: Kernel docs: muddying the waters a bit Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-03-08 16:40 +0100
        Re: Kernel docs: muddying the waters a bit Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-03-09 22:30 +0100
          Re: Kernel docs: muddying the waters a bit Jani Nikula <jani.nikula@intel.com> - 2016-03-10 11:30 +0100
            Re: Kernel docs: muddying the waters a bit Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-03-10 16:30 +0100
              Re: Kernel docs: muddying the waters a bit Markus Heiser <markus.heiser@darmarit.de> - 2016-03-13 16:50 +0100
  Re: Kernel docs: muddying the waters a bit Mauro Carvalho Chehab <mchehab@osg.samsung.com> - 2016-03-08 14:40 +0100
  Re: Kernel docs: muddying the waters a bit Jani Nikula <jani.nikula@intel.com> - 2016-03-08 15:00 +0100
    Re: Kernel docs: muddying the waters a bit Jani Nikula <jani.nikula@intel.com> - 2016-03-09 10:00 +0100

csiph-web