Date:   Tue, 1 Nov 2016 16:49:43 -0600
From:   Mauro Carvalho Chehab <mchehab@...radead.org>
To:     Jim Davis <jim.epost@...il.com>
Cc:     Jonathan Corbet <corbet@....net>,
        linux-doc <linux-doc@...r.kernel.org>,
        linux-kernel <linux-kernel@...r.kernel.org>
Subject: Re: make pdfdocs fails with v4.9-rc3

Em Tue, 1 Nov 2016 15:11:55 -0700
Jim Davis <jim.epost@...il.com> escreveu:

> On Mon, Oct 31, 2016 at 3:41 PM, Mauro Carvalho Chehab
> <mchehab@...radead.org> wrote:
> > Em Mon, 31 Oct 2016 16:40:02 -0600
> > Mauro Carvalho Chehab <mchehab@...radead.org> escreveu:
> >  
> >> Em Mon, 31 Oct 2016 15:04:42 -0700
> >> Jim Davis <jim.epost@...il.com> escreveu:
> >>  
> >> > On Mon, Oct 31, 2016 at 1:58 PM, Mauro Carvalho Chehab
> >> > <mchehab@...radead.org> wrote:  
> >> > > 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  
> >> >
> >> > 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@...bstar:~/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

Well, xelatex has a few modes of operation:

-interaction=STRING     set interaction mode (STRING=batchmode/nonstopmode/
                          scrollmode/errorstopmode)

on batchmode, it doesn't complain about any errors, but doesn't produce any
error. On the default mode (errorstopmode), it will stop on the first error.


> 
> 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@...bstar:~$ grep '^!' /tmp/make-pdfdocs.txt | sort -u
> ! Argument of \LT@max@sel has an extra }.
> ! Extra alignment tab has been changed to \cr.

Ok, but this one is on another place ;)

If it is the same issue that happened on Sphinx 1.4.x, it is due to 
the lack of some column specification on a .. tabularcolumn markup.

I have already a series fixing all errors with PDF on 1.4.x.

Just submitted. Please check it it makes ok on Sphinx 1.3.x.

Cheers,
Mauro

Powered by blists - more mailing lists