[Linux-kernel-mentees] [PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst

[paulmck at linux.ibm.com (Paul E. McKenney)]

On Tue, Jun 25, 2019 at 03:01:55PM -0600, Jonathan Corbet wrote:
> On Tue, 25 Jun 2019 08:56:23 -0700
> "Paul E. McKenney" <paulmck at linux.ibm.com> wrote:
> 
> > > -  See the UP.txt file in this directory.
> > > +  See :ref:`up_rcu` for more information.  
> > 
> > This rendered as straight text after "make htmldocs" instead of producing
> > a link in the HTML output.  The HTML itself is:
> > 
> > 	<span class="xref std std-ref">up_rcu</span>
> > 
> > This doesn't look like something that would create a link, though I
> > freely admit that my HTML is rather outdated.
> 
> The problem is that the reference target isn't called "up_rcu" in the file
> itself:
> 
> > diff --git a/Documentation/RCU/UP.txt b/Documentation/RCU/UP.txt
> > index 53bde717017b..67715a47ae89 100644
> > --- a/Documentation/RCU/UP.txt
> > +++ b/Documentation/RCU/UP.txt
> > @@ -1,17 +1,19 @@
> > -RCU on Uniprocessor Systems
> > +.. _up_doc:
> 
> Certainly "up_rcu" seems like a better name.  I do believe, though, that
> you can also use the title directly:
> 
>   See `RCU on Uniprocessor Systems`_ for more information

That does look prettier, though we might want to do something more
directly mapped for people directly reading the .rst files.

> > >  - How can I see where RCU is currently used in the Linux kernel?
> > >  
> > > @@ -67,7 +67,7 @@ Frequently Asked Questions
> > >  
> > >  - Why the name "RCU"?
> > >  
> > > -  "RCU" stands for "read-copy update".  The file listRCU.txt has
> > > +  "RCU" stands for "read-copy update".  :ref:`list_rcu` has  
> > 
> > Same here for list_rcu.
> 
> And the problem is the same, it's list_rcu_doc in the actual source file.
> 
> Jiang, as with so many things in software, if you haven't tested it, it
> probably doesn't work.  Please actually run "make htmldocs" and look at
> the results to be sure that they are what you expect.  (Along those lines,
> it would also be good to add the new directory to Documentation/index.rst
> so that it gets built with the rest).

What Jon said on the "haven't test it, it probably doesn't work" thought.
Sometimes I fear that my own work could be all too accurately modeled as
random mutations with rcutorture providing needed natural selection.  :-/

							Thanx, Paul