Re: make pdfdocs fails with v4.9-rc3

[Mauro Carvalho Chehab <mchehab@infradead.org>]

Em Mon, 31 Oct 2016 13:15:24 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Mon, 31 Oct 2016 11:51:20 -0700
> Jim Davis <jim.epost@gmail.com> wrote:
> 
> > Running make pdfdocs on a Ubuntu 16.04 system fails with
> > 
> > Makefile:58: recipe for target 'media.pdf' failed
> > make[2]: *** [media.pdf] Error 1
> > Documentation/Makefile.sphinx:79: recipe for target 'pdfdocs' failed
> > make[1]: *** [pdfdocs] Error 2
> > Makefile:1442: recipe for target 'pdfdocs' failed
> > make: *** [pdfdocs] Error 2
> > 
> > It's not clear from the voluminous (>5MB) output from make pdfdocs
> > exactly which stage is failing, and there are some pdf files produced
> > in output/latex.  
> 
> Hmm, so it does.  It comes down to this:
> 
> ! LaTeX Error: \DUrole undefined.
> 
> See the LaTeX manual or LaTeX Companion for explanation.
> Type  H <return>  for immediate help.
>  ...                                              
>                                                   
> l.195 \renewcommand*{\DUrole}
>                              [2]{ #2 }
> 
> Where the offending command is in Documentation/media/index.rst.  Mauro,
> got an idea for what's going on there?

Sphinx is really a poor solution when it comes to PDF output. In this
specific case, this is meant to fix a problem with cross-references.

What happens is that Sphinx 1.4.6 (and later?) define reference names without
being properly escaped. So, for some references, it causes the PDF output
to crash. That happens at one of the DVB header files, if I remember well.

This commit restores the sphinx 1.2.x behavior:

    commit e61a39baf74dddb6cd236147bd19b55c10188d78
    Author: Mauro Carvalho Chehab <mchehab@s-opensource.com>
    Date:   Sun Aug 21 15:14:57 2016 -0300

    [media] index.rst: Fix LaTeX error in interactive mode on Sphinx 1.4.x
    
    The Sphinx 1.4.x definition for \DUrole is:
    
    \providecommand*{\DUrole}[2]{%
      \ifcsname DUrole#1\endcsname%
        \csname DUrole#1\endcsname{#2}%
      \else% backwards compatibility: try \docutilsrole#1{#2}
        \ifcsname docutilsrole#1\endcsname%
          \csname docutilsrole#1\endcsname{#2}%
        \else%
          #2%
        \fi%
      \fi%
    }
    
    This is broken when it is used inside a \begin{alltt} block.
    So, replace it by just "#2", as this won't cause troubles, and
    it is one of the fallback methods for it.
    
    Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

At the time I tested, it worked fine, but maybe it is redefining the
\DUrole too late.

Maybe we could move it to LaTeX preamble instead. Please check if this
untested patch fixes the issue.

diff --git a/Documentation/conf.py b/Documentation/conf.py
index d9bad21dd427..ae7450c0a6e0 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -329,6 +329,9 @@ latex_elements = {
 	% To allow adjusting table sizes
 	\\usepackage{adjustbox}
 
+	% Fix reference escape troubles with Sphinx 1.4.x
+	\renewcommand*{\DUrole}[2]{ #2 }
+
      '''
 }
 
diff --git a/Documentation/media/index.rst b/Documentation/media/index.rst
index e347a3e7bdef..7f8f0af620ce 100644
--- a/Documentation/media/index.rst
+++ b/Documentation/media/index.rst
@@ -1,11 +1,6 @@
 Linux Media Subsystem Documentation
 ===================================
 
-.. Sphinx 1.4.x has a definition for DUrole that doesn't work on alltt blocks
-.. raw:: latex
-
-	\renewcommand*{\DUrole}[2]{ #2 }
-
 Contents:
 
 .. toctree::



Cheers,
Mauro