On Friday, November 22, 2019 6:34:37 PM CET Jonathan Corbet wrote:
> On Fri, 22 Nov 2019 12:53:37 +0100
>
> Federico Vaga <federico.vaga@xxxxxxxxxx> wrote:
> > This patch:
> >
> > commit fcfacb9f8374 ("doc: move namespaces.rst from kbuild/ to core-api/")
> >
> > forgot to update the document kernel-hacking/hacking.rst.
> >
> > In addition to the fix the path now is a cross-reference to the document.
> >
> > Signed-off-by: Federico Vaga <federico.vaga@xxxxxxxxxx>
> > ---
> >
> > Documentation/core-api/symbol-namespaces.rst | 2 ++
> > Documentation/kernel-hacking/hacking.rst | 4 ++--
> > 2 files changed, 4 insertions(+), 2 deletions(-)
> >
> > diff --git a/Documentation/core-api/symbol-namespaces.rst
> > b/Documentation/core-api/symbol-namespaces.rst index
> > 982ed7b568ac..6791f8a5d726 100644
> > --- a/Documentation/core-api/symbol-namespaces.rst
> > +++ b/Documentation/core-api/symbol-namespaces.rst
> > @@ -1,3 +1,5 @@
> > +.. _core-api-namespace:
> > +
>
> So I've been wondering for a bit why we don't use section headers as
> targets more often rather than adding all these tags. Perhaps it's because
> we never enabled that extension? What do you think of this as an
> alternative fix? (Probably before committing this I would split into two,
> since enabling the extension merits its own patch).
I take this occasion to express my opinion, even if it is not a strong
opinion, I am fine with your solution.
A tag should be always unique (a duplicated tag is an error), so a reference
to it can't (shouldn't) be wrong. A section header could be repeated when it
is, let's say, too generic (e.g. "Introduction" is a legitimate section in any
document). Then we can have both:
- a document title is, in general, unique so it is not a problem to use it as
targets
- a document sub-section could collide with others so it is preferable an
unique tag.
>
> Thanks,
>
> jon
>
> From b5ca7304e1a7f67717acff2a7bf50f56d387afdd Mon Sep 17 00:00:00 2001
> From: Jonathan Corbet <corbet@xxxxxxx>
> Date: Fri, 22 Nov 2019 10:30:30 -0700
> Subject: [PATCH] docs: fix reference to core-api/namespaces.rst
>
> Fix a couple of dangling links to core-api/namespaces.rst by turning them
> into proper references. Enable the autosection extension (available since
> Sphinx 1.4) to make this work.
>
> Co-developed-by: Federico Vaga <federico.vaga@xxxxxxxxxx>
> Fixes: fcfacb9f8374 ("doc: move namespaces.rst from kbuild/ to core-api/")
> Signed-off-by: Jonathan Corbet <corbet@xxxxxxx>
> ---
> Documentation/conf.py | 2 +-
> Documentation/kernel-hacking/hacking.rst | 4 ++--
> 2 files changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 3c7bdf4cd31f..fa2bfcd6df1d 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -38,7 +38,7 @@ needs_sphinx = '1.3'
> # ones.
> extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain',
> 'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
> - 'maintainers_include']
> + 'maintainers_include', 'sphinx.ext.autosectionlabel' ]
>
> # The name of the math extension changed on Sphinx 1.4
> if (major == 1 and minor > 3) or (major > 1):
> diff --git a/Documentation/kernel-hacking/hacking.rst
> b/Documentation/kernel-hacking/hacking.rst index a3ddb213a5e1..d707a0a61cc9
> 100644
> --- a/Documentation/kernel-hacking/hacking.rst
> +++ b/Documentation/kernel-hacking/hacking.rst
> @@ -601,7 +601,7 @@ Defined in ``include/linux/export.h``
>
> This is the variant of `EXPORT_SYMBOL()` that allows specifying a symbol
> namespace. Symbol Namespaces are documented in
> -``Documentation/kbuild/namespaces.rst``.
> +:ref:`Documentation/core-api/symbol-namespaces.rst <Symbol Namespaces>`
>
> :c:func:`EXPORT_SYMBOL_NS_GPL()`
>
> --------------------------------
> @@ -610,7 +610,7 @@ Defined in ``include/linux/export.h``
>
> This is the variant of `EXPORT_SYMBOL_GPL()` that allows specifying a
> symbol namespace. Symbol Namespaces are documented in
> -``Documentation/kbuild/namespaces.rst``.
> +:ref:`Documentation/core-api/symbol-namespaces.rst <Symbol Namespaces>`
>
> Routines and Conventions
> ========================
