Re: [PATCH v2] doc:process: add links where missing

[Federico Vaga <federico.vaga@vaga.pv.it>]

On Wednesday, November 21, 2018 2:23:46 PM CET Matthew Wilcox wrote:
> On Wed, Nov 21, 2018 at 01:35:19AM +0100, Federico Vaga wrote:
> > Some documents are refering to others without links. With this
> > patch I add those missing links.
> 
> I am a neophyte to ReST, but ...
> 
> > +++ b/Documentation/dev-tools/coccinelle.rst
> > @@ -4,6 +4,8 @@
> > 
> >  .. highlight:: none
> > 
> > +.. _devtools_coccinelle:
> > +
> > 
> >  Coccinelle
> >  ==========
> > 
> > +++ b/Documentation/process/4.Coding.rst
> > @@ -315,7 +315,8 @@ variety of potential coding problems; it can also
> > propose fixes for those> 
> >  problems.  Quite a few "semantic patches" for the kernel have been
> >  packaged
> >  under the scripts/coccinelle directory; running "make coccicheck" will
> >  run
> >  through those semantic patches and report on any problems found.  See
> > 
> > -Documentation/dev-tools/coccinelle.rst for more information.
> > +:ref:`Documentation/dev-tools/coccinelle.rst <devtools_coccinelle>`
> > +for more information.
> 
> when I tried to do something like this yesterday, I discovered that
> doing:
> 
> +.. _memory_allocation:
> 
> didn't work, and I had to do:
> 
> +.. _memory-allocation:

I would say that in principle it should not make a difference. Both '-' and 
'_' characters are explicitly allowed:

http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#reference-names

> instead.  Also, when doing 'ref', do we want this style of ref, or do we
> 
> prefer the plain:
> :ref:`devtools-coccinelle`
> 
> which is what I did yesterday.  

The style depends on the situation. In this patch (mine) the objective is to 
show that there is a file that talk about the topic, it's there (the path is 
visible), and by the way if you click on it you are able to open it.

> Maybe that's why yours works with the underscores and mine didn't?

This, honestly, I do not know. Perhaps it depends on the Sphinx version in use 
or some other python package? As explained here:

https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html

Sphinx environment can be fragile.

-- 
Federico Vaga
http://www.federicovaga.it/