Em Fri, 12 May 2017 18:35:29 +0200 Markus Heiser <markus.hei...@darmarit.de> escreveu:
> Am 12.05.2017 um 15:59 schrieb Mauro Carvalho Chehab > <mche...@s-opensource.com>: > > > 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 <mche...@s-opensource.com> > > --- > > 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
