Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST

["Paul E. McKenney" <paulmck@linux.ibm.com>]

On Tue, Jul 30, 2019 at 04:37:20PM -0700, Paul E. McKenney wrote:
> On Tue, Jul 30, 2019 at 06:50:51PM -0300, Mauro Carvalho Chehab wrote:
> > Em Tue, 30 Jul 2019 14:22:50 -0700
> > "Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:
> > 
> > > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > > > There are 4 RCU articles that are written on html format.
> > > > 
> > > > The way they are, they can't be part of the Linux Kernel
> > > > documentation body nor share the styles and pdf output.
> > > > 
> > > > So, convert them to ReST format.
> > > > 
> > > > This way, make htmldocs and make pdfdocs will produce a
> > > > documentation output that will be like the original ones, but
> > > > will be part of the Linux Kernel documentation body.
> > > > 
> > > > Part of the conversion was done with the help of pandoc, but
> > > > the result had some broken things that had to be manually
> > > > fixed.
> > > > 
> > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>  
> > > 
> > > I am having some trouble applying these, at least in part due to UTF-8
> > > sequences, for example double left quotation mark.  These end up being
> > > "=E2=80=9C", with a few space characters turned into "=20".
> > > 
> > > Any advice on how to apply these?
> > 
> > Didn't notice it ended with UTF-8 chars. It is probably because it came
> > from the html conversion.
> 
> Or maybe there are some email issues somewhere along the way.
> 
> > I guess it shouldn't hurt keeping those, but if you prefer I can find 
> > some time later to replace them.
> > 
> > > Should I just pull commits from somewhere?
> > 
> > Yeah, if you prefer, you can pull from this branch:
> > 
> > 	https://git.linuxtv.org/mchehab/experimental.git/log/?h=rcu-v1
> > 
> > It has just two patches: the RCU and tools/memory-model ones.
> > 
> > It is based on v5.3-rc2.
> 
> And that does apply, thank you!

And "make htmldocs" does produce real HTML!  At first glance anyway,
quite impressive.

However, "make pdfdocs" gives me this complaint:

	! Dimension too large.
	\color@b@x ... #3}\kern \fboxsep }\dimen@ \ht \z@ 
							  \advance \dimen@ \fboxsep ...
	l.5092 \end{sphinxVerbatim}

This appears to come from Documentation/output/latex/RCU.tex.
There is nevertheless an RCU.pdf in this directory.  It is not
bad, but has a figure full of XML on PDF page 21.  And a few later
on as well.

On the HTML side, the quick quizzes have immediately visible answers,
which defeats the purpose.  The original HTML used a white font,
so that you selected the answer with your mouse to make it visible.
Can something similar be done with Sphinx?  Another approach is to
gather the answers into a separate file and link to them.

I believe that Joel already noted that internal links are not working.
The external links that I tried work just fine, though.  As do the
links from the table of contents.

							Thanx, Paul