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

[Graham Whaley]

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?

 Graham
> 
> Thanks, Daniel