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 09:47:22PM -0300, Mauro Carvalho Chehab wrote:
> 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.

Would it be fair to say that html output is what is currently supported,
and that PDF output is a future thing?

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

Making it CSS for HTML and a footnote for PDF seems eminently
reasonable to me!

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

And it works for me, anyway!  ;-)

							Thanx, Paul