Am 04.05.2016 um 15:43 schrieb Daniel Vetter <daniel@xxxxxxxx>: > On Wed, May 04, 2016 at 02:40:29PM +0200, Markus Heiser wrote: >>> On Wed, 04 May 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote: >>> I'd be *very* hesitant about adding the kind of things you do in >>> reformat_block_rst to kernel-doc. IMO the extraction from kernel-doc >>> comments must be as simple as possible with basically pass-through of >>> the comment blocks to sphinx. >> >> Right, but you forgot, that the current markup in the source code comments >> is based on the kernel-doc-nano-HOWTO and I guess no one will migrate all >> these source code comments to reST markup ;-) >> >> So there is a need to differentiate between *vintage* kernel-doc markup >> and reST markup. >> >> My suggestion is to add a tag to the comments, here a short example >> what this might look like. >> >> <vintage-comment-SNIP> -------------- >> /** >> * drm_minor_release - Release DRM minor >> * @minor: Pointer to DRM minor object >> * >> * Release a minor that was previously acquired via drm_minor_acquire(). >> */ >> <vintage-comment-SNAP> -------------- >> >> in short: the vintage style does not need any change and >> comments with reST markup has a tag ":reST:" in the first >> line(s) ... >> >> <reST-comment-SNIP> -------------- >> /** >> * :reST: >> * >> * .. c:function:: void drm_minor_release(struct drm_minor *minor) >> * >> * Release DRM minor >> * >> * :param struct drm_minor \*minor: Pointer to DRM minor object >> * >> */ >> <reST-comment-SNAP> -------------- >> >> Comments with the ":reST:" tag could be exported and pass-through >> to sphinx. >> >>> Specifically, do not attempt to detect and >>> parse elements like lists in kernel-doc. >> >> If your markup in the comments is plain reST, no need to parse, but there >> are markups in the (vintage) comments which made use of individual >> text-markups, e.g. the markup of lists or ASCII-art. >> >> This individual text-markups has not been converted/rendered in the docbook >> output, but I wanted to convert this individuals to reST, to render them in >> Sphinx. > > I think we need to unconfuse what's current standardize kerneldoc markup. > There's three bits: > - The header with the one-liner and parameters, i.e. OK, forget my <reST-comment-SNAP> example, I don't really want to promote this way ... I agree, it is better to stay with standardize kernel-doc markup and provide a "pass through" for the section-content (even if it is mixing markups). Am 04.05.2016 um 15:41 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>: > Kernel-doc the tool should continue to parse kernel-doc comments at the > high level like they currently are, according to the kernel-doc > howto. The requirement was unclear for me, thanks to Daniel and Jani for clarifying this. Am 04.05.2016 um 15:43 schrieb Daniel Vetter <daniel@xxxxxxxx>: > This is already used widely in kerneldoc included by gpu.tmpl, and > currently it's asciidoc. Those lists and asciiarts though are _not_ > standard kerneldoc at all. But imo any doc toolchain improvement should > integrate along those lines. > > For reference, this is what it's supposed to look like with the asciidoc > support enabled: > > https://dri.freedesktop.org/docs/drm/API-struct-drm-display-mode.html > > Fyi those hacked-up patches to make this happen are available in > > https://cgit.freedesktop.org/drm-intel/log/?h=topic/kerneldoc > Correct my, if I'am wrong. I'am a bit unfamiliar with DOCPROC in particular with your "MARKDOWNREADY := gpu.xml" process. As I understood, you convert markdown to docbook within the kernel-doc script using pandoc's executable? ... I don't face this topic. With my modification of kernel-doc I produced pure reST markup from standardize kernel-doc markup, no intermediate steps or tools required. Am 04.05.2016 um 15:41 schrieb Jani Nikula <jani.nikula@xxxxxxxxx>: > Overall I think we should promote fixing those in the kernel-doc > comments. Trying to guesswork in kernel-doc tool will leave the source > littered with bad examples that get proliferated all around. Instead of > gradually fixing things, we'll end up gradually messing things up even > more. I agree with you, lets drop the reformat_block_rst from my kernel-doc script: * https://github.com/return42/sphkerneldoc/blob/master/scripts/kernel-doc#L1736 and we should have a plain "pass through". Am 04.05.2016 um 17:09 schrieb Jonathan Corbet <corbet@xxxxxxx>: > I think all of this makes sense. It would be really nice to have the > directives in the native sphinx language like that. I *don't* think we > need to aim for that at the outset; the docproc approach works until we can > properly get rid of it. What would be *really* nice would be to get > support for the kernel-doc directive into the sphinx upstream. No need for kernel-doc directive in sphinx upstream, later it will be an extension which could be installed by a simple command like "pip install kernel-doc-extensions" or similar. I develop these required extension (and more) within my proof of concept on github ... this takes time ... if I finished all my tests and all is well, I will build the *kernel-doc-extensions* package and deploy it on https://pypi.python.org/pypi from where everyone could install this with "pip". At this time I see only one change/merge to the linux upstream, this is my modification of the kernel-doc script to get a proper reST output. But my recommendation is not to merge anything in a hurry. --Markus-- -- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
