Re: [RFC] A first shot at asciidoc-based formatted docs

[Jani Nikula <jani.nikula@intel.com>]

On Tue, 26 Jan 2016, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> On Tue, Jan 26, 2016 at 1:08 PM, Jani Nikula <jani.nikula@intel.com> wrote:
>> I first took roughly the same approach as you did. I was really
>> impressed with the speed and the beauty of the produced HTML. The
>> trouble is, neither asciidoc nor asciidoctor can produce chunked (split
>> to several pages) HTML directly. This is a showstopper for the gpu
>> document which turns into 1.3 MB of HTML, which looks pretty but is a
>> paint to navigate. To do chunked output, you have to output DocBook and
>> handle that like we do now. So while I would like to have asciidoc
>> generate HTML directly for speed and beauty, I ended up going the
>> asciidoc to DocBook path. The upside is all the output formats are
>> supported.
>
> This is a big bummer since with the parralized kernel-doc processing
> using Makefiles and using asciidoctor even building something big like
> the gpu docs is down to 2-3 seconds. From a clean tree, so not even
> counting incremental speed-ups. Unfortunately asciidoc doesn't have an
> built-in tooling (there's some experimental extensions) to split
> things up.

Basically asciidoc -> HTML is about as fast as asciidoc -> XML, and with
parallel kernel-doc it really is fast. Sadly the XML -> HTML part still
takes forever.

I just want to emphasize that we can get parallel kernel-doc with either
pipeline. It is also possible to enable both pipelines, i.e. have a fast
path HTML generation with few external dependencies and the Swiss army
knife slow path with XML.

I should also remind us that the original goal was to enable lightweight
markup for documentation. This seems very much achievable now. We don't
have to solve all the existing problems with the XML pipeline right
now. And asciidoc suits this well, as it can also feed to the existing
pipeline.


BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center