[PATCH 5/5] drm: Enable markdown^Wasciidoc for gpu.tmpl

[Daniel Vetter]

On Mon, Jan 11, 2016 at 06:12:12PM -0700, Jonathan Corbet wrote:
> On Sat, 12 Dec 2015 12:13:45 +0100
> Daniel Vetter <daniel at ffwll.ch> wrote:
> 
> > I just figured there's no way this could get it, and I'd
> > much rather improve the docs themselves than trying to convince core
> > kernel folks that this might be useful.
> 
> So I'm not quite sure why you figured that; I never said it, certainly.

To clarify this wasn't really my impression of your stance, but of the
overall room opinion when we had the discussion at KS. And then my main
goal here is to write great docs for drm (we have about 3k lines more docs
in 4.5 already), so that's why I dropped the ball on upstreaming. It
seemed unlikely to succeed, at least without some really seriuos effort at
convincing everyone, all while the drm docs for atomic haven't been in
good shape yet. Since then we had a few contributors of new atomic drivers
note on irc already that "oh cool, this is documented now". Overall really
just boils down to what I see as the most important things for drm ;-)

> I've been messing with it a bit, seems to work.  I do still wish we could
> consider alternatives, especially those that might simplify the toolchain
> rather than complicating it.  But it's clear that I'm not succeeding in
> finding time to actually explore that idea; the contents of $EXCUSES are
> good, but the end result is the same.  And the patch fairy just isn't
> coming through for me on this one.
> 
> In my mind, there's clearly no good that can come from (further) delaying
> something that works in favor of an "it would be nice" that may never
> even exist.  So I'm currently thinking that I'll pull this into the docs
> tree once the merge window is done, with the plan to push it for 4.6.
> Then we can see if anybody screams.
> 
> That gives a couple of weeks for an updated patch set, should you have
> one.
> 
> The build-time increase is painful in the extreme - about a factor of
> three for a -j1 build, and that's with only one file using the feature.
> It feels wrong, somehow, for the docs build to take longer than building
> the kernel itself.  Can we do something about that?
> 
>  - How many of the comments actually use asciidoc features?  Might there
>    be some possibility of detecting those in kernel-doc and skipping the
>    callout to asciidoc when it's not needed?

I think that amounts to writing a partial parser (we use asciidoc for
tables, lists, links, formatting, code snippets by now already, someone
even thought of using the asciiart->png feature it has but it's not yet
wired up). I don't think it's feasible.

>  - Pandoc seems to do asciidoc.  I still don't like the idea of depending
>    on it for this to work, but having the *option* to use it is fine.  If
>    it's really that much faster (yes, Python startup is painful) then
>    maybe providing the option is worth it.

Hm, Dave asked me to convert to use python-based asciidoc insted of
haskell-based pandoc.

>  - All over the kernel we've seen that batching improves performance.  It
>    would take a bit of work, but I bet kernel-doc could put together all
>    the snippets from one file, pass them through a single asciidoc
>    invocation, then split the results back apart.  That would probably
>    eliminate the performance hit entirely.
> 
> None of that is a condition for pulling this stuff in, but can it be
> looked into?

Besides what Jani mention that asciidoctor should be a drop-in replacement
if installed it also seems possible to parallelize the call-out to
kernel-doc from docproc.c without too much effort. I hoped Jani would get
around to implement the asciidoctor support, and I'm hoping I can snipe
away some free sometimes the next few months to look at docproc.c more
seriously. This would kinda be a cool intern project, but atm we throw
them all at improving testing infrastructure ...

Anyway I'm of course still open to get this upstream, and I think a few
things should be polished (like the speed-up). But right now bandwidth on
my side isn't too plentiful. Maybe we should aim to have a few better
ideas (perhaps even for all of the docs stuff) for next KS and respin that
discussion?

Thanks, Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch