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@xxxxxxxx> 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 _______________________________________________ Intel-gfx mailing list Intel-gfx@xxxxxxxxxxxxxxxxxxxxx http://lists.freedesktop.org/mailman/listinfo/intel-gfx
