Messages in this thread | | | From | Jani Nikula <> | Subject | Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends | Date | Wed, 04 Jan 2017 17:40:47 +0200 |
| |
On Wed, 04 Jan 2017, Paolo Bonzini <pbonzini@redhat.com> wrote: > On 03/01/2017 10:57, Jani Nikula wrote: >> On Mon, 02 Jan 2017, Paolo Bonzini <pbonzini@redhat.com> wrote: >>> Hi, >>> >>> these patches are the result of my experiments with using kernel-doc >>> for QEMU's documentation. Patches 1 and 2 should be relatively >>> straightforward, as they are simple bugfixes. Patches 3 to 5, instead, >>> are making the docbook backend (and the others too) more consistent with >>> the input and output of the rST backend. >> >> I did not test the patches, and for sure I will not attempt reviewing >> perl, but at a high level the changes seem sensible. >> >> Acked-by: Jani Nikula <jani.nikula@intel.com> > > Thanks---Perl's not that bad, come on! :)
FWIW 99% of all the Perl I've ever written or read is in kernel-doc...!
>>> I am not sure what is the state of the kernel-doc non-rST backends; >>> but there are still several books using the docbook workflow, so I'm >>> trying my luck and sending the patches anyway. :) >> >> Obviously reStructuredText is the main output now and has to work, and >> DocBook is still used as you say, but hopefully you sneaked in >> regressions for the other formats so we can gauge if anyone cares! ;) > > Couldn't expect any other deprecation plan from a graphics guy!
Auch, don't hit me below the belt! :p
> FWIW I tested building the Sphinx and DocBook books and eyeballed the > output for both of them. I also tested manually the list backend on toy > testcases, and of course it is used by docproc when building DocBook > manuals. I didn't test the other backends.
BTW one thing I did a lot while making supposedly benign changes to kernel-doc was:
$ make cleandocs $ make htmldocs $ mv Documentation/output Documentation/output.before $ # apply the change $ make htmldocs $ diff -r Documentation/output.before Documentation/output
There's some noise from .doctrees that you can safely ignore, but otherwise it was a life saver.
BR, Jani.
> > Paolo
-- Jani Nikula, Intel Open Source Technology Center
| |