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 18:06:24 -0700
"Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:

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

> > > 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. 
> 
> Would it be fair to say that html output is what is currently supported,
> and that PDF output is a future thing?

Sure.

Anyway, if you want to fix PDF later, I suspect that simply adding:

	.. cssclass:: longtable

Before each quiz table should be enough to fix, as the tables there seem
to be simple enough. 

After fixed, the PDF and LaTeX output are usually decent.

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

You should either do CSS or PDF, as otherwise you will end with dirty
hacks like:

.. only:: html

	<some quiz table with answers using css>

.. only: latex

	<some quiz table with answers using footnotes>

E. g. you'll need to place the quiz twice, making it harder to maintain
and messier.

Btw, the LaTeX may also parse a css tag, processing it via some custom
macro (with should be added at Documentation/conf.py.

> > > 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!  ;-)

Great!

Thanks,
Mauro