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

[Mauro Carvalho Chehab <mchehab+samsung@kernel.org>]

Em Tue, 30 Jul 2019 17:04:55 -0700
"Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:

> 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.

Yeah, its output is pretty decent.

> 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.

PDF output is indeed an issue. The way it works is that it first
generates a LaTeX and then it uses texlive to produce the PDF. 

There is a rst2pdf tool with handles it directly, but it is a way more
 problematic. I have an experimental patch with enables it. Maybe
some day it could be applied, but upstream for the tool needs a lot 
more work.

With regards to the LaTeX/PDF output, on media, we had to tweak the
documents in order for them to produce a good LaTeX/PDF output on tables.

Usually, before some tables, we add something like this:

.. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}|

in order to teach LaTeX the size of each column.

If the table is really big, the only way for it to fit is to reduce
the font size, using a raw LaTeX syntax. See, for example:

	Documentation/media/uapi/v4l/dev-subdev.rst

There, we use things like:

.. raw:: latex

    \scriptsize

.. tabularcolumns:: |p{2.0cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|


	+-----------------+ ...
	| Some long table | ...
	+-----------------+ ...
	...
	+-----------------+ ...


.. raw:: latex

    \normalsize

In order to use a small font for the table.

Neither "raw:: latex" nor "tabularcolumns" tag affect html.

There is another trick too. By default, Sphinx LaTeX output uses a
type of table that should fit into a single page ("tabular").

If the table has more than 30 columns, it switches to another type
("longtable"), with can be split into multiple pages.

As the quiz tables usually have only 4 columns, it will always try
the unbreakable tabular table. If it doesn't fit, PDF will break.

In order to avoid that, just add:

.. cssclass:: longtable

Before the offended table. This will make Sphinx to use LaTeX
longtable instead of tabular ones.

This won't affect html output.

> 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.

Yeah, I guess you used a css style that would make the answer visible
when the mouse is inside it on your original lwn.net set of articles. 

Sphinx has a directive to use css, so, the short answer is: yes, you
can. 

For html, you would need to add a css specific for the RCU quiz,
placing it under Documentation/sphinx directory. Then, use the
 ".. css" directive to handle that.

You should notice, however, that this will be ignored for 
LaTeX/pdf output.

I guess you can place this on another file, or perhaps place at the
end of the document, having a link for the quiz answers. 

Another alternative would be to make the answer as a footnote.

> 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.

Yeah. Funny enough, when I tested here, they worked fine. Maybe
this is due to the Sphinx version I used here at the time I wrote
it.

Anyway, Joel already submitted a patch addressing this one. 


Thanks,
Mauro