From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S968519AbdADPk4 (ORCPT ); Wed, 4 Jan 2017 10:40:56 -0500 Received: from mga09.intel.com ([134.134.136.24]:21616 "EHLO mga09.intel.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1757498AbdADPkx (ORCPT ); Wed, 4 Jan 2017 10:40:53 -0500 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.33,459,1477983600"; d="scan'208";a="805060254" From: Jani Nikula To: Paolo Bonzini , linux-kernel@vger.kernel.org, linux-doc@vger.kernel.org Cc: corbet@lwn.net Subject: Re: [PATCH 0/5] kernel-doc tweaks and cleanup of rST vs. non-rST backends In-Reply-To: <9b78f94a-e27d-b463-2fe4-a307d8c008b8@redhat.com> Organization: Intel Finland Oy - BIC 0357606-4 - Westendinkatu 7, 02160 Espoo References: <20170102152227.9446-1-pbonzini@redhat.com> <87bmvoihyk.fsf@intel.com> <9b78f94a-e27d-b463-2fe4-a307d8c008b8@redhat.com> Date: Wed, 04 Jan 2017 17:40:47 +0200 Message-ID: <87h95ehlz4.fsf@intel.com> MIME-Version: 1.0 Content-Type: text/plain Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org On Wed, 04 Jan 2017, Paolo Bonzini wrote: > On 03/01/2017 10:57, Jani Nikula wrote: >> On Mon, 02 Jan 2017, Paolo Bonzini 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 > > 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