linux-kernel - Re: make pdfdocs fails with v4.9-rc3

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20161031145850.266feaeb@vela.lan>
Date:   Mon, 31 Oct 2016 14:58:50 -0600
From:   Mauro Carvalho Chehab <mchehab@...radead.org>
To:     Jonathan Corbet <corbet@....net>
Cc:     Jim Davis <jim.epost@...il.com>,
        linux-doc <linux-doc@...r.kernel.org>,
        linux-kernel <linux-kernel@...r.kernel.org>
Subject: Re: make pdfdocs fails with v4.9-rc3

Em Mon, 31 Oct 2016 14:17:59 -0600
Mauro Carvalho Chehab <mchehab@...radead.org> escreveu:

> Em Mon, 31 Oct 2016 13:15:24 -0600
> Jonathan Corbet <corbet@....net> escreveu:
> 
> > On Mon, 31 Oct 2016 11:51:20 -0700
> > Jim Davis <jim.epost@...il.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@...pensource.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@...pensource.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.

Yes, this seems to be the case. The patch below should fix it.

[PATCH] docs-rst: fix PDF build errors

PDF build on Kernel 4.9-rc? returns an error. This is
because we're re-defining a command too late. Move
such redefinition to LaTeX preamble.

Tested by building the documentation on interactive mode:
	make PDFLATEX=xelatex -C Documentation/output/./latex

Fixes: e61a39baf74d ("[media] index.rst: Fix LaTeX error in interactive mode on Sphinx 1.4.x")

Signed-off-by: Mauro Carvalho Chehab <mchehab@....samsung.com>

diff --git a/Documentation/conf.py b/Documentation/conf.py
index d9bad21dd427..d9ebfeb431a9 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