[Intel-gfx] [RFC] Docs: drm: Move KMS properties table out to source files

[Graham Whaley]

On Mon, 2015-09-28 at 11:33 -0600, Jonathan Corbet wrote:
> On Mon, 28 Sep 2015 10:36:59 +0100
> Graham Whaley <graham.whaley at linux.intel.com> wrote:
> 
> > I've still not thought of a way of tweaking the kernel-doc and
> > pandoc
> > processing to work around this either, as they are done as
> > different
> > passes/phases that neither has knowledge about the others
> > requirements.
> > 
> > As it stands, I'm failing to find a method to break out the DRM
> > table
> > into markdown tables that I believe works, fundamentally due to
> > this
> > 'incompatibility' between the kernel-doc and pandoc_markdown
> > processing
> > phases around the highlight processing.
> 
> This sort of thing is why I'm increasingly nervous about this one-off
> mix
> of doc-generation tools we're putting together.  Sigh.

Hi Jon, all. Just to note, I've not forgotten about this. I was hoping
to bump into you at ELCE/LinuxCon Dublin to maybe chat over it Jon -
but I think you were not there. I see you did a talk on this topic at
the kernel summit though, and have read through your lwn.net article
and the string of replies.

> 
> One possibility might be to have kernel-doc understand some sort of
> table
> notation of its own and make it do the right thing.
> 
> Another might be to have kernel-doc format unconditionally to
> markdown
> (or ReST, or something) all the time, then have the secondary
> processor
> handle everything from there.  A bigger change, obviously.  Probably
> not
> something anybody wants to face, but we may reach a point where we
> need
> to consider having less than three independent formatting tools in
> the
> mix.  I *may* get a chance to mess with this idea in the next week or
> so,
> but no promises.
> 
The whole idea of moving this more towards some KISS philosophy rather
than further away is obviously appealing :-) I'm guessing you didn't
find any time yet?
I've been staring at the workflow of docproc and kernel-doc to try and
wrap my head better around exactly how it works at present.
Did you have thoughts on how moving kernel-doc to produce markdown all
the time would work in practice? Presumably we'd then have to put a
markdown->docbook processor between docproc and kernel-doc (be that
pandoc or something else). That may then solve the mixing of docbook
and markdown inside of kernel-doc that I saw with the highlighting
expansion.
I'll see if I can find some time to play with the idea - but please let
me know if that was not what you had in mind.

 Graham

> jon