From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752370AbdEMKDX (ORCPT ); Sat, 13 May 2017 06:03:23 -0400 Received: from ec2-52-27-115-49.us-west-2.compute.amazonaws.com ([52.27.115.49]:50964 "EHLO osg.samsung.com" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1751018AbdEMKDV (ORCPT ); Sat, 13 May 2017 06:03:21 -0400 Date: Sat, 13 May 2017 07:03:13 -0300 From: Mauro Carvalho Chehab To: Markus Heiser Cc: linux-kernel@vger.kernel.org, Linux Doc Mailing List , Mauro Carvalho Chehab , Jonathan Corbet , Jani Nikula , Takashi Iwai , "Herton R. Krzesinski" , Al Viro , Silvio Fricke Subject: Re: [PATCH 01/36] docs-rst: convert kernel-hacking to ReST Message-ID: <20170513070313.2460f36b@vento.lan> In-Reply-To: <650BB12A-04FF-473A-A3C9-E2499B165667@darmarit.de> References: <650BB12A-04FF-473A-A3C9-E2499B165667@darmarit.de> Organization: Samsung X-Mailer: Claws Mail 3.14.1 (GTK+ 2.24.31; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Em Fri, 12 May 2017 18:35:29 +0200 Markus Heiser escreveu: > Am 12.05.2017 um 15:59 schrieb Mauro Carvalho Chehab : > > > Use pandoc to convert documentation to ReST by calling > > Documentation/sphinx/tmplcvt script. > > > > - Manually adjusted to use ..note and ..warning > > - Minor fixes for it to be parsed without errors > > - Use **bold** for emphasis. > > > > Signed-off-by: Mauro Carvalho Chehab > > --- > > Documentation/DocBook/Makefile | 2 +- > > Documentation/DocBook/kernel-hacking.tmpl | 1312 ----------------------------- > > Documentation/conf.py | 2 + > > Documentation/index.rst | 1 + > > Documentation/kernel-hacking/conf.py | 10 + > > Documentation/kernel-hacking/index.rst | 794 +++++++++++++++++ > > 6 files changed, 808 insertions(+), 1313 deletions(-) > > delete mode 100644 Documentation/DocBook/kernel-hacking.tmpl > > create mode 100644 Documentation/kernel-hacking/conf.py > > create mode 100644 Documentation/kernel-hacking/index.rst > > > > > .... > > > +:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()` ``include/asm/byteorder.h`` > > +--------------------------------------------------------------------------------------------------------------------------- > > + > > Hi Mauro, just my bikeshedding: > > what do you think, do we really need to refer functions in titles? > As far as I know, there is no use-case where we can get any benefit > from. So I recommend to write titles more simple, e.g.: > > cpu_to_be32()/be32_to_cpu()/cpu_to_le32()/le32_to_cpu() include/asm/byteorder.h > > .. which is long enough ;) There are some functions there that are only mentioned at the title, like: local_bh_disable(). IMHO, it is a good idea to add a cross-reference to those, as it helps the reader to get further information if needed. So, except if this would cause Sphinx to crash, I prefer to keep the references. What I did, instead, on patch 02/36 is to move all header references to be outside the title: +:c:func:`cpu_to_be32()`/:c:func:`be32_to_cpu()`/:c:func:`cpu_to_le32()`/:c:func:`le32_to_cpu()` +----------------------------------------------------------------------------------------------- + +Defined in ``include/asm/byteorder.h`` With reduces the displayed title to something reasonable. Thanks, Mauro