Date: Mon, 19 Jun 2017 11:43:42 -0300
From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
To: Jonathan Corbet <corbet@lwn.net>,
        Markus Heiser <markus.heiser@darmarit.de>
Cc: linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        Jim Davis <jim.epost@gmail.com>,
        Daniel Vetter <daniel.vetter@ffwll.ch>
Subject: Re: [PATCH 0/5] Make PDF builds work again
Message-ID: <20170619114342.22acdef2@vento.lan>
In-Reply-To: <20170618221829.4573592b@vento.lan>
References: <20170618234630.19964-1-corbet@lwn.net>
        <20170618221829.4573592b@vento.lan>
Organization: Samsung
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 3361
Lines: 100

Em Sun, 18 Jun 2017 22:18:29 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> escreveu:

> Hi Jon,
> 
> Em Sun, 18 Jun 2017 17:46:25 -0600
> Jonathan Corbet <corbet@lwn.net> escreveu:
> 
> > I've just spent rather more time than I would like figuring out why the PDF
> > builds fail and what was needed to fix it.  The result is the following
> > patch series.  It's a combination of little mistakes and fragility in the
> > whole PDF build tool chain.  
> 
> Yeah, the PDF toolchain is very fragile. Yet, I'm pretty sure I was able
> to build PDF in the past without noticing the problems fixed by patches
> 1 and 2. Maybe the bugs has to do with some specific incompatibility with
> toolchain versions.
> 
> What Sphinx version are you using?
> 
> It is too late now, but tomorrow I'll test with a few Spinx versions
> and see if PDF builds equally well with them.
> 
> > 
> > Mauro, Daniel: Do you want the last two?  Or otherwise give me acks?  I'd
> > like to send the set Linusward forthwith so that 4.12 can come out with
> > a working PDF build.  
> 
> For the media and EDAC changes (patches 3 and 4), once I test it,
> feel free to add my ack and send via your tree:
> 
> Acked-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> 
> > 
> > In general, I'm dismayed by the fragility of the whole thing.  I'm also a
> > little concerned that nobody except Jim complained about the problem.  
> 
> Actually, despite any "errors", usually it produces the PDF files.
> I have a robot building just the media documentation, daily basis,
> from media development tree, at:
> 	https://linuxtv.org/downloads/v4l-dvb-apis-new/media.pdf
> 
> The robot is using Sphinx 1.4.8 version.

I tested building here with Sphinx 1.4.9, 1.5.6 and 1.6.2.

With those patches applied (using my version of the patch adjusting
the margins), the result is that it seems to be building fine with
versions 1.4.9 and 1.5.6.

However, with 1.6.2, I'm getting build errors:

Output written on driver-api.pdf (847 pages).
Transcript written on driver-api.log.
Documentation/Makefile:83: recipe for target 'pdfdocs' failed
make[1]: *** [pdfdocs] Error 2
Makefile:1470: recipe for target 'pdfdocs' failed
make: *** [pdfdocs] Error 2

Despite what's written there, I was unable to find a problem on
driver-api build so far. Yet, the media.pdf book is written with
just a few pages. It turns that the build breaks on the tables
that need scaling to fit at the paper's page.

The first one to break is this piece of .rst file, located at
media/uapi/v4l/extended-controls.rst:


	enum v4l2_vp8_golden_frame_sel -
	    Selects the golden frame for encoding. Possible values are:

	.. raw:: latex

	    \begin{adjustbox}{width=\columnwidth}

It seems that adjustbox doesn't work anymore. It fails with:


	! Missing \endgroup inserted.
	<inserted text> 
	                \endgroup 
	l.4104 \begin{savenotes}\sphinxattablestart

I suspect that we'll need to redefine sphinxattablestart for Sphinx
versions 1.6.x.

I'm starting to think that the only way we'll get some sanity on
documentation build is if we enforce that builds will happen with
only sanctioned Sphinx versions.

Markus,

Are there some way for us to have an extension that would provide
something that would modify the LaTeX output to 


Anyway, I'm seeking for some hack at conf.py that would fix it.

Thanks,
Mauro