Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1550903 > unrolled thread

Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends

Back to article view | Back to linux.kernel

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST  backends Paolo Bonzini <pbonzini@redhat.com> - 2017-01-04 16:20 +0100
    Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends Jani Nikula <jani.nikula@linux.intel.com> - 2017-01-04 16:50 +0100

#1550903 — Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends

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! :)

>> 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!

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.

Paolo

[toc] | [next] | [standalone]

#1550938 — Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends

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

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web