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

Groups > linux.kernel > #1353068

Re: Kernel docs: muddying the waters a bit

Show all headers | View raw

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

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