Re: Kernel docs: muddying the waters a bit

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

On Tue, 08 Mar 2016, Dan Allen <dan@opendevise.io> wrote:
> 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.

I need to look into this again. Is there a specific option or directive
to produce split output for includes? When I tried this, the result was
just one big output file. (And indeed we'd need both. Some includes we
want embedded, some includes should produce separate outputs.)

>> That actually makes choosing asciidoc harder, because
>> requiring another language environment complicates, not simplifies, the
>> toolchain. I'd really like to lower the bar for building the
>> documentation, for everyone, so much so that it becomes part of the
>> normal checks for patch inclusion.
>
> Pardon my bluntness here, but I don't buy that argument. This is Linux.
> Installing software couldn't be simpler, and we're talking about an
> extremely well supported language (Ruby).

Granted, that part works for me. I'm not so sensitive to the
dependencies; others may disagree.

> I think it's a huge exaggeration to say that Asciidoctor is any harder to
> install than AsciiDoc Python. It's also a heck of a lot smaller in size
> since AsciiDoc Python pulls in hundreds of MB of LaTeX packages.

For me, the comparison is really between Sphinx and Asciidoctor, not so
much doc vs. doctor. The native output format and extension support in
Sphinx is appealing; I am not yet convinced we could manage with
Asciidoctor but without DocBook. The extension offering seems better in
Sphinx.

> Whatever you decide, I wish you all the best with your documentation
> efforts!

Thanks!

BR,
Jani.

-- 
Jani Nikula, Intel Open Source Technology Center