From mboxrd@z Thu Jan 1 00:00:00 1970 From: paulmck at linux.ibm.com (Paul E. McKenney) Date: Tue, 25 Jun 2019 14:17:40 -0700 Subject: [Linux-kernel-mentees] [PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst In-Reply-To: <20190625150155.5c9b8880@lwn.net> References: <20190623081413.7095-1-c0d1n61at3@gmail.com> <20190625062627.26378-6-c0d1n61at3@gmail.com> <20190625155623.GA26519@linux.ibm.com> <20190625150155.5c9b8880@lwn.net> Message-ID: <20190625211740.GQ26519@linux.ibm.com> List-Id: 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" 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: > > > > up_rcu > > > > 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 From mboxrd@z Thu Jan 1 00:00:00 1970 From: paulmck@linux.ibm.com (Paul E. McKenney) Date: Tue, 25 Jun 2019 14:17:40 -0700 Subject: [Linux-kernel-mentees] [PATCH v3 5/6] Documentation: RCU: Add links to rcu.rst In-Reply-To: <20190625150155.5c9b8880@lwn.net> References: <20190623081413.7095-1-c0d1n61at3@gmail.com> <20190625062627.26378-6-c0d1n61at3@gmail.com> <20190625155623.GA26519@linux.ibm.com> <20190625150155.5c9b8880@lwn.net> Message-ID: <20190625211740.GQ26519@linux.ibm.com> List-Id: Content-Type: text/plain; charset="UTF-8" Message-ID: <20190625211740.puquG6ORTXMrXT8po6t_vYu8JDFn4QbK-4VcjGRIF9k@z> 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" 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: > > > > up_rcu > > > > 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