From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <linux-kernel-owner@vger.kernel.org>
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
        id S1422686AbcKAEvu (ORCPT <rfc822;w@1wt.eu>);
        Tue, 1 Nov 2016 00:51:50 -0400
Received: from bombadil.infradead.org ([198.137.202.9]:38741 "EHLO
        bombadil.infradead.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
        with ESMTP id S1161804AbcKAEvr (ORCPT
        <rfc822;linux-kernel@vger.kernel.org>);
        Tue, 1 Nov 2016 00:51:47 -0400
Date: Mon, 31 Oct 2016 22:51:42 -0600
From: Mauro Carvalho Chehab <mchehab@infradead.org>
To: Jim Davis <jim.epost@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>,
        linux-doc <linux-doc@vger.kernel.org>,
        linux-kernel <linux-kernel@vger.kernel.org>
Subject: Re: make pdfdocs fails with v4.9-rc3
Message-ID: <20161031225142.1f1900bc@vela.lan>
In-Reply-To: <20161031164148.50aba3be@vela.lan>
References: <CA+r1Zhgj7os_npcj4CbNY4fh4jBC2deVfQB41g-4E+z05H7YAQ@mail.gmail.com>
        <20161031131524.581accdc@lwn.net>
        <20161031141759.7eb1c9e5@vela.lan>
        <20161031145850.266feaeb@vela.lan>
        <CA+r1Zhiz5r-a9ODOdTbw1X6m+=RTueXU=QOAcQYdM2Vs3kT0Og@mail.gmail.com>
        <20161031164002.0104ddc0@vela.lan>
        <20161031164148.50aba3be@vela.lan>
X-Mailer: Claws Mail 3.14.0 (GTK+ 2.24.31; x86_64-redhat-linux-gnu)
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
X-SRS-Rewrite: SMTP reverse-path rewritten from <mchehab@infradead.org> by bombadil.infradead.org. See http://www.infradead.org/rpr.html
Sender: linux-kernel-owner@vger.kernel.org
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

Em Mon, 31 Oct 2016 16:41:48 -0600
Mauro Carvalho Chehab <mchehab@infradead.org> escreveu:

> Em Mon, 31 Oct 2016 16:40:02 -0600
> Mauro Carvalho Chehab <mchehab@infradead.org> escreveu:
> 
> > Em Mon, 31 Oct 2016 15:04:42 -0700
> > Jim Davis <jim.epost@gmail.com> escreveu:
> > 
> > > On Mon, Oct 31, 2016 at 1:58 PM, Mauro Carvalho Chehab
> > > <mchehab@infradead.org> wrote:
> > > > Em Mon, 31 Oct 2016 14:17:59 -0600
> > > > Mauro Carvalho Chehab <mchehab@infradead.org> escreveu:
> > > >  
> > > >> 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.  
> > > >
> > > > 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@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 <mchehab@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