[Linux-kernel-mentees] [PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst
Paul E. McKenney
paulmck at linux.ibm.com
Tue Jun 25 21:17:40 UTC 2019
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
More information about the Linux-kernel-mentees
mailing list