Em Mon, 31 Oct 2016 16:41:48 -0600 Mauro Carvalho Chehab <mche...@infradead.org> escreveu:
> Em Mon, 31 Oct 2016 16:40:02 -0600 > Mauro Carvalho Chehab <mche...@infradead.org> escreveu: > > > Em Mon, 31 Oct 2016 15:04:42 -0700 > > Jim Davis <jim.ep...@gmail.com> escreveu: > > > > > On Mon, Oct 31, 2016 at 1:58 PM, Mauro Carvalho Chehab > > > <mche...@infradead.org> wrote: > > > > Em Mon, 31 Oct 2016 14:17:59 -0600 > > > > Mauro Carvalho Chehab <mche...@infradead.org> escreveu: > > > > > > > >> Em Mon, 31 Oct 2016 13:15:24 -0600 > > > >> Jonathan Corbet <cor...@lwn.net> escreveu: > > > >> > > > >> > On Mon, 31 Oct 2016 11:51:20 -0700 > > > >> > Jim Davis <jim.ep...@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 <mche...@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 <mche...@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. > > > > > > > > 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 <mche...@osg.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 > > > > > > After applying the patch I'm seeing a similar error message > > > > > > [...] > > > Running Sphinx v1.3.1 > > > [...] > > > > Ah! you're running version 1.3.1... > > > > We should likely add some logic at conf.py to only enable this on > > Sphinx 1.4.x... > > Could you please apply just the hook that remove the index.rst > raw LaTeX command and see if it will build fine in interactive > mode? > > Cheers, > Mauro I'm not a python programmer, but, after playing with conf.py for a while, I guess that the following patch should do the right thing applying the LaTeX fix only for Sphinx 1.4.x. --- [PATCH v2] 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 <mche...@osg.samsung.com> diff --git a/Documentation/conf.py b/Documentation/conf.py index d9bad21dd427..375b61c25df2 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -332,6 +332,10 @@ latex_elements = { ''' } +# Fix reference escape troubles with Sphinx 1.4.x +if minor > 3: + latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }' + # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). 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