| Message ID | 20170618234630.19964-1-corbet@lwn.net |
|---|---|
| Headers | show |
| Series | Make PDF builds work again | expand |
On Sun, 18 Jun 2017 17:46:25 -0600 Jonathan Corbet <corbet@lwn.net> wrote: > 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. Jim, I just realized I neglected Reported-by tags for you on these patches; I'll fix that before they go upstream. jon
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. > Perhaps nobody really cares about PDF output anymore? In the absence of a > concerted effort on somebody's part, I predict that PDF building will be > broken much of the time. I have to wonder if it's worth it... > > Jonathan Corbet (5): > Docs: Include the Latex "ifthen" package > Docs: Remove redundant geometry package inclusion > Docs: fix table problems in ras.rst > Docs: Use kernel-figure in vidioc-g-selection.rst > DRM: Fix an incorrectly formatted table > > Documentation/admin-guide/ras.rst | 10 ++-- > Documentation/conf.py | 3 +- > .../media/uapi/v4l/vidioc-g-selection.rst | 4 +- > include/drm/bridge/dw_hdmi.h | 70 +++++++++++----------- > 4 files changed, 43 insertions(+), 44 deletions(-) > Thanks, Mauro
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
On Sun, Jun 18, 2017 at 05:46:25PM -0600, Jonathan Corbet wrote: > 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. > > 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. Only now stumbled over the full thread, but the drm patch is already queued up for at least 4.13 (Dave was out and all that). I guess we could try to cherry-pick through stable. Personally I don't care at all for PDF builds, the only thing we do in our autobuilder is html, same for me locally when building docs. That tends to keep working :-) Also, 0-day only tests the htmlbuild. Maybe you want to ping Fu and ask him to add the pdfdocs to his build targets? -Daniel > > 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. > Perhaps nobody really cares about PDF output anymore? In the absence of a > concerted effort on somebody's part, I predict that PDF building will be > broken much of the time. I have to wonder if it's worth it... > > Jonathan Corbet (5): > Docs: Include the Latex "ifthen" package > Docs: Remove redundant geometry package inclusion > Docs: fix table problems in ras.rst > Docs: Use kernel-figure in vidioc-g-selection.rst > DRM: Fix an incorrectly formatted table > > Documentation/admin-guide/ras.rst | 10 ++-- > Documentation/conf.py | 3 +- > .../media/uapi/v4l/vidioc-g-selection.rst | 4 +- > include/drm/bridge/dw_hdmi.h | 70 +++++++++++----------- > 4 files changed, 43 insertions(+), 44 deletions(-) > > -- > 2.13.1 > -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch
On Mon, 3 Jul 2017 10:25:38 +0200 Daniel Vetter <daniel@ffwll.ch> wrote: > Only now stumbled over the full thread, but the drm patch is already > queued up for at least 4.13 (Dave was out and all that). I guess we could > try to cherry-pick through stable. I kind of gave up on the 4.12 goal, at least for now. The number of complaints has not been huge - I suspect you're far from the only one who is not too worried about building PDFs...:) jon
On 07/03/17 01:25, Daniel Vetter wrote: > On Sun, Jun 18, 2017 at 05:46:25PM -0600, Jonathan Corbet wrote: >> 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. >> >> 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. > > Only now stumbled over the full thread, but the drm patch is already > queued up for at least 4.13 (Dave was out and all that). I guess we could > try to cherry-pick through stable. > > Personally I don't care at all for PDF builds, the only thing we do in our > autobuilder is html, same for me locally when building docs. That tends to > keep working :-) > > Also, 0-day only tests the htmlbuild. Maybe you want to ping Fu and ask > him to add the pdfdocs to his build targets? > -Daniel > >> >> 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. >> Perhaps nobody really cares about PDF output anymore? In the absence of a >> concerted effort on somebody's part, I predict that PDF building will be >> broken much of the time. I have to wonder if it's worth it... I much prefer PDF output to html for my normal use. Not to get into a debate about whether html or PDF is better, both have valuable use cases. And it isn't PDF per se that I prefer - it could be any reasonable format that contains the entire content in a single file, is easily scannable ("scrolled through", viewed by the human eye), easily searched, and can be cut and pasted from. As far as lack of complaints, I have been ignoring building documentation until it feels to me like the issues from converting to the new system have been worked out. And once that point is reached, then I need to make time in my schedule to fix the in-source documentation so that building the documents for device tree provides useful information instead of incorrect information. If I was actively building documentation I would have complained. >> Jonathan Corbet (5): >> Docs: Include the Latex "ifthen" package >> Docs: Remove redundant geometry package inclusion >> Docs: fix table problems in ras.rst >> Docs: Use kernel-figure in vidioc-g-selection.rst >> DRM: Fix an incorrectly formatted table >> >> Documentation/admin-guide/ras.rst | 10 ++-- >> Documentation/conf.py | 3 +- >> .../media/uapi/v4l/vidioc-g-selection.rst | 4 +- >> include/drm/bridge/dw_hdmi.h | 70 +++++++++++----------- >> 4 files changed, 43 insertions(+), 44 deletions(-) >> >> -- >> 2.13.1 >> >
On Mon, Jul 3, 2017 at 5:44 AM, Jonathan Corbet <corbet@lwn.net> wrote: > On Mon, 3 Jul 2017 10:25:38 +0200 > Daniel Vetter <daniel@ffwll.ch> wrote: > >> Only now stumbled over the full thread, but the drm patch is already >> queued up for at least 4.13 (Dave was out and all that). I guess we could >> try to cherry-pick through stable. > > I kind of gave up on the 4.12 goal, at least for now. The number of > complaints has not been huge - I suspect you're far from the only one who > is not too worried about building PDFs...:) If fixing pdf (and ps) builds isn't worth the bother -- which I wouldn't debate -- then it's best to just drop those build targets. The only worrisome thing I see here is having build targets carried from release to release that don't work. -- Jim
> Am 05.07.2017 um 23:22 schrieb Jim Davis <jim.epost@gmail.com>: > > On Mon, Jul 3, 2017 at 5:44 AM, Jonathan Corbet <corbet@lwn.net> wrote: >> On Mon, 3 Jul 2017 10:25:38 +0200 >> Daniel Vetter <daniel@ffwll.ch> wrote: >> >>> Only now stumbled over the full thread, but the drm patch is already >>> queued up for at least 4.13 (Dave was out and all that). I guess we could >>> try to cherry-pick through stable. >> >> I kind of gave up on the 4.12 goal, at least for now. The number of >> complaints has not been huge - I suspect you're far from the only one who >> is not too worried about building PDFs...:) > > If fixing pdf (and ps) builds isn't worth the bother -- which I > wouldn't debate -- then it's best to just drop those build targets. > The only worrisome thing I see here is having build targets carried > from release to release that don't work. my 5cent: we have to communicate that PDF build is in a beta stage (for a long time). Sphinx-doc's PDF chain was not well maintained for a long time. With newer versions (started with 1.5 and continued in 1.6) it becomes better and better. This gives me some hope that there comes a day where building PDFs is robust enough to use in automatic builds. As long as we try to support various version of Sphinx shipped by various distros and at the same time make/need deep (LaTeX) adjustments, we will find those discussions on the ML. If you are doubtful about my assessment, compare Sphinx's TeX stuff from master https://github.com/sphinx-doc/sphinx/tree/master/sphinx/texinputs with e.g. 1.4.9 tag https://github.com/sphinx-doc/sphinx/tree/1.4.9/sphinx/texinputs -- Markus --
Em Wed, 5 Jul 2017 14:22:35 -0700 Jim Davis <jim.epost@gmail.com> escreveu: > On Mon, Jul 3, 2017 at 5:44 AM, Jonathan Corbet <corbet@lwn.net> wrote: > > On Mon, 3 Jul 2017 10:25:38 +0200 > > Daniel Vetter <daniel@ffwll.ch> wrote: > > > >> Only now stumbled over the full thread, but the drm patch is already > >> queued up for at least 4.13 (Dave was out and all that). I guess we could > >> try to cherry-pick through stable. > > > > I kind of gave up on the 4.12 goal, at least for now. The number of > > complaints has not been huge - I suspect you're far from the only one who > > is not too worried about building PDFs...:) > > If fixing pdf (and ps) builds isn't worth the bother -- which I > wouldn't debate -- then it's best to just drop those build targets. > The only worrisome thing I see here is having build targets carried > from release to release that don't work. My $5 cents on that. We do automatic pdf builds at linuxtv.org since when we moved the media books to Sphinx. In order to avoid regressions, we use a virtual environment for Sphinx, and we only update to a newer version after checking if the upgrade won't break build. Currently, it is running Sphinx version 1.4.9. I did a grep on the access for the media.pdf doc at the apache's log. We don't keep a long history there. We had 41 accesses to the pdf logs over the last ~3 days, with means that people are finding PDF output useful. - From my side, I like having everything into a single file specially when I'm needing to find things at the document. Well, ePub sort of provides that, but it is a way worse than PDF or html, specially when big tables are there. Btw, over the last ~3 days, we had only 1 access to the ePub version. So, not a very popular format. Thanks, Mauro