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

[Daniel Vetter]

On Tue, Jan 12, 2016 at 11:06:17AM +0000, Graham Whaley wrote:
> On Tue, 2016-01-12 at 09:34 +0100, Daniel Vetter wrote:
> > 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?
> 
> I was just about to reply to the thread.... looking at the
> linux.conf.au schedule it would seem that you are both attending and
> presenting, and there appears to be some sort of Documentation mini
> -summit on the Monday as well (not sure if that is the place for a
> discussion though). I will be at LCA for the Wed-Fri. You may not have
> to wait until the next KS?

Sounds like a great idea to pick this up at lca and toss around for some.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch