Re: make pdfdocs fails with v4.9-rc3

[Jim Davis]

On Mon, Oct 31, 2016 at 3:41 PM, Mauro Carvalho Chehab
<mchehab@xxxxxxxxxxxxx> wrote:
> Em Mon, 31 Oct 2016 16:40:02 -0600
> Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxx> escreveu:
>
>> Em Mon, 31 Oct 2016 15:04:42 -0700
>> Jim Davis <jim.epost@xxxxxxxxx> escreveu:
>>
>> > On Mon, Oct 31, 2016 at 1:58 PM, Mauro Carvalho Chehab
>> > <mchehab@xxxxxxxxxxxxx> wrote:
>> > > Em Mon, 31 Oct 2016 14:17:59 -0600
>> > > Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxx> escreveu:
>> > >
>> > >> Em Mon, 31 Oct 2016 13:15:24 -0600
>> > >> Jonathan Corbet <corbet@xxxxxxx> escreveu:
>> > >>
>> > >> > On Mon, 31 Oct 2016 11:51:20 -0700
>> > >> > Jim Davis <jim.epost@xxxxxxxxx> 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@xxxxxxxxxxxxxxxx>
>> > >>     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@xxxxxxxxxxxxxxxx>
>> > >>
>> > >> 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@xxxxxxxxxxxxxxx>
>> > >
>> > > 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?

With

jim@krebstar:~/linux-rc/Documentation/media$ git diff
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 bloc
ks
-.. raw:: latex
-
-    \renewcommand*{\DUrole}[2]{ #2 }
-
 Contents:

 .. toctree::

I'm still getting

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

after running make pdfdocs.  Sorry, I don't quite understand what
running interactively means in this case, though from the log of make
pdfdocs's output there's

make PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C
Documentation/output/./latex

which looks similar to something you mentioned above.

I've no idea where's it's going astray, though there are a number of errors:

jim@krebstar:~$ grep '^!' /tmp/make-pdfdocs.txt | sort -u
! Argument of \LT@max@sel has an extra }.
! Extra alignment tab has been changed to \cr.
! Extra \endcsname.
! Extra \endgroup.
! Illegal unit of measure (pt inserted).
! Improper alphabetic constant.
! LaTeX Error: \begin{document} ended by \end{adjustbox}.
! LaTeX Error: \begin{document} ended by \end{longtable}.
! LaTeX Error: Something's wrong--perhaps a missing \item.
! LaTeX Error: There's no line here to end.
! Misplaced \noalign.
! Missing \endcsname inserted.
! Missing \endgroup inserted.
! Missing { inserted.
! Missing } inserted.
! Missing # inserted in alignment preamble.
! Missing number, treated as zero.
! Paragraph ended before \LT@entry was complete.
! Paragraph ended before \LT@max@sel was complete.
! Paragraph ended before \multicolumn was complete.
! Undefined control sequence.
! You can't use `\hrule' here except wi

-- 
Jim