Re: [RFC PATCH 0/3] Documentation: switch to pdflatex and fix pdf build

[Mauro Carvalho Chehab]

Em Mon, 15 Aug 2016 12:40:21 +0300
Jani Nikula <jani.nikula@xxxxxxxxx> escreveu:

> On Sat, 13 Aug 2016, Jonathan Corbet <corbet@xxxxxxx> wrote:
> > On Wed, 10 Aug 2016 18:54:06 +0300
> > Jani Nikula <jani.nikula@xxxxxxxxx> wrote:
> >  
> >> With these you should be able to get started with pdf generation. It's a
> >> quick transition to pdflatex, the patches are not very pretty, but the
> >> pdf output is. Patch 3/3 works as an example where to add your stuff
> >> (latex_documents in conf.py) and how.  
> >
> > OK, now I have a bone to pick with you.
> >
> > I applied this, then decided to install the needed toolchain on the
> > Tumbleweed system I've been playing with; it wanted to install 1,727
> > packages to get pdflatex.  Pandoc just doesn't seem so bad anymore.  
> 
> Jon, I sent these to unblock Luis, and as a starting point for a
> discussion about rst2pdf vs. pdflatex. I didn't mean I'd want these
> merged as-is! I'm sorry if I didn't make myself clear.
> 
> I don't mind at all if you want to drop them.
> 
> As I played around, it worked for *me* better than rst2pdf. I had
> pdflatex already installed, so I didn't pay attention to the deps, and
> the numbers you quote come as a suprise.
> 
> > I've applied this so we have something to play with, but it doesn't feel
> > like a great solution.  This is the sort of installation hell that we
> > wanted to get away from.  It makes me wonder how hard it can really be to
> > fix rst2pdf; I wish I could say I'll find some time to figure that out.
> > Sigh.  
> 
> I'm afraid pdf generation is not very high on my list of priorities
> right now. Surely I'll get back to this eventually, but not any time
> soon. :(

I'm afraid that, no matter if we'll be using rst2pdf or pdflatex,
we'll need LaTex anyway.

One of the things that we want on media is to better represent the
math formulas there. Just enabling the math extension is enough for
it to require not only LaTex, but also this package (on Fedora):
	texlive-anyfontsize.noarch

So, unfortunately, I'm afraid that we'll end by having a much worse
dependency chain than what we used to have with DocBook.

An (incomplete) patch to let you test it is enclosed (it is actually after
patches 1 and 2 of this series).

Ah, it seems that rst2pdf is not compatible with math extension...

If we change the conf.py to:
	extensions = ['sphinx.ext.imgmath', 'kernel-doc', 'rstFlatTable', 'kernel_include']

	# Gracefully handle missing rst2pdf.
	try:
	    import rst2pdf
	    extensions += ['rst2pdf.pdfbuilder']
	except ImportError:
	    pass

The logic that tries to import rst2pdf produces the following error:

	Extension error:
	Config value 'math_number_all' already present

And, if we don't add the imgmath extension, the math expression
appears broken at the generated html page:

	The transfer function defined for SMPTE 170M is the same as the one defined in Rec. 709.
	L' = -1.099(-L)^{0.45} + 0.099 \text{ for } L \le-0.018 L' = 4.5L \text{ for } -0.018 < L < 0.018 L' = 1.099L^{0.45} - 0.099 \text{ for } L \ge 0.018

Btw, changing to math is a requirement for pdflatex to work on media,
as the font used by Sphinx/pdflatex doesn't have UTF-8 symbols used
on math. So, trying to build the documentation with pdfdocs (after
patches 1 and 2, before patch 3) would give fatal errors like:

	! Package inputenc Error: Unicode char \u8:â not set up for use with LaTeX.

	See the inputenc package documentation for explanation.
	Type  H <return>  for immediate help.
	 ...                                              
                                                  
	l.7759 ....099L $^{\text{0.45}}$ - 0.099 for L â
							 0.018

The problem is that the "grater or equal than" UTF-8 Math symbol
is not supported on the LaTex font.


Thanks,
Mauro


diff --git a/Documentation/conf.py b/Documentation/conf.py
index 96b7aa66c89c..0b60a55cea89 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -28,14 +28,14 @@ sys.path.insert(0, os.path.abspath('sphinx'))
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include']
+extensions = ['sphinx.ext.imgmath', 'kernel-doc', 'rstFlatTable', 'kernel_include']
 
 # Gracefully handle missing rst2pdf.
-try:
-    import rst2pdf
-    extensions += ['rst2pdf.pdfbuilder']
-except ImportError:
-    pass
+#try:
+#    import rst2pdf
+#    extensions += ['rst2pdf.pdfbuilder']
+#except ImportError:
+#    pass
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
diff --git a/Documentation/media/uapi/v4l/pixfmt-007.rst b/Documentation/media/uapi/v4l/pixfmt-007.rst
index 8c946b0c63a0..1253c3283b10 100644
--- a/Documentation/media/uapi/v4l/pixfmt-007.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-007.rst
@@ -72,11 +72,13 @@ SMPTE C set, so this colorspace is sometimes called SMPTE C as well.
 The transfer function defined for SMPTE 170M is the same as the one
 defined in Rec. 709.
 
-    L' = -1.099(-L) :sup:`0.45` + 0.099 for L â -0.018
+.. math::
 
-    L' = 4.5L for -0.018 < L < 0.018
+    L' = -1.099(-L)^{0.45} + 0.099 \text{ for } L \le-0.018
 
-    L' = 1.099L :sup:`0.45` - 0.099 for L â 0.018
+    L' = 4.5L \text{ for } -0.018 < L < 0.018
+
+    L' = 1.099L^{0.45} - 0.099 \text{ for } L \ge 0.018
 
 Inverse Transfer function: