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.
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
Otherwise we get PDF build failures when LaTeX refused to acknowledge the
existence of \ifthenelse
Fixes: 41cff161fe99d1c6a773becc2250a1dc3ac035ff
Cc: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
---
Documentation/conf.py | 1 +
1 file changed, 1 insertion(+)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index bacf9d337c89..93827bc1620f 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -273,6 +273,7 @@ latex_elements = {
'preamble': '''
% Adjust margins
\\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry}
+ \\usepackage{ifthen}
% Allow generate some pages in landscape
\\usepackage{lscape}
--
2.13.1
Commit 85c21e5c3ee7 (docs-rst: better adjust margins and font size) added a
\usepackage{geometry} that conflicts with another inclusion deep within the
dependencies somewhere, causing the the PDF build to fail with a
"conflicting parameters" error. Just remove it for now until we can figure
out a better way.
Fixes: 85c21e5c3ee74fb75d690c57f7066bae7e2dca55
Cc: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
---
Documentation/conf.py | 2 --
1 file changed, 2 deletions(-)
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 93827bc1620f..3d4e89330044 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -271,8 +271,6 @@ latex_elements = {
# Additional stuff for the LaTeX preamble.
'preamble': '''
- % Adjust margins
- \\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry}
\\usepackage{ifthen}
% Allow generate some pages in landscape
--
2.13.1
The "supported input formats" table in dw_hdmi.h was incorrectly formatted,
using "+" signs where "|" needs to be. That, in turn, causes the PDF build
to fail.
Fixes: def23aa7e9821a3dfe3fb7b139dd0229a89fdeb0
Cc: Neil Armstrong <[email protected]>
Cc: Daniel Vetter <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
---
include/drm/bridge/dw_hdmi.h | 70 ++++++++++++++++++++++----------------------
1 file changed, 35 insertions(+), 35 deletions(-)
diff --git a/include/drm/bridge/dw_hdmi.h b/include/drm/bridge/dw_hdmi.h
index ed599bea3f6c..c00671fef53c 100644
--- a/include/drm/bridge/dw_hdmi.h
+++ b/include/drm/bridge/dw_hdmi.h
@@ -22,56 +22,56 @@ struct dw_hdmi;
* 48bit bus.
*
* +----------------------+----------------------------------+------------------------------+
- * + Format Name + Format Code + Encodings +
+ * | Format Name | Format Code | Encodings |
* +----------------------+----------------------------------+------------------------------+
- * + RGB 4:4:4 8bit + ``MEDIA_BUS_FMT_RGB888_1X24`` + ``V4L2_YCBCR_ENC_DEFAULT`` +
+ * | RGB 4:4:4 8bit | ``MEDIA_BUS_FMT_RGB888_1X24`` | ``V4L2_YCBCR_ENC_DEFAULT`` |
* +----------------------+----------------------------------+------------------------------+
- * + RGB 4:4:4 10bits + ``MEDIA_BUS_FMT_RGB101010_1X30`` + ``V4L2_YCBCR_ENC_DEFAULT`` +
+ * | RGB 4:4:4 10bits | ``MEDIA_BUS_FMT_RGB101010_1X30`` | ``V4L2_YCBCR_ENC_DEFAULT`` |
* +----------------------+----------------------------------+------------------------------+
- * + RGB 4:4:4 12bits + ``MEDIA_BUS_FMT_RGB121212_1X36`` + ``V4L2_YCBCR_ENC_DEFAULT`` +
+ * | RGB 4:4:4 12bits | ``MEDIA_BUS_FMT_RGB121212_1X36`` | ``V4L2_YCBCR_ENC_DEFAULT`` |
* +----------------------+----------------------------------+------------------------------+
- * + RGB 4:4:4 16bits + ``MEDIA_BUS_FMT_RGB161616_1X48`` + ``V4L2_YCBCR_ENC_DEFAULT`` +
+ * | RGB 4:4:4 16bits | ``MEDIA_BUS_FMT_RGB161616_1X48`` | ``V4L2_YCBCR_ENC_DEFAULT`` |
* +----------------------+----------------------------------+------------------------------+
- * + YCbCr 4:4:4 8bit + ``MEDIA_BUS_FMT_YUV8_1X24`` + ``V4L2_YCBCR_ENC_601`` +
- * + + + or ``V4L2_YCBCR_ENC_709`` +
- * + + + or ``V4L2_YCBCR_ENC_XV601`` +
- * + + + or ``V4L2_YCBCR_ENC_XV709`` +
+ * | YCbCr 4:4:4 8bit | ``MEDIA_BUS_FMT_YUV8_1X24`` | ``V4L2_YCBCR_ENC_601`` |
+ * | | | or ``V4L2_YCBCR_ENC_709`` |
+ * | | | or ``V4L2_YCBCR_ENC_XV601`` |
+ * | | | or ``V4L2_YCBCR_ENC_XV709`` |
* +----------------------+----------------------------------+------------------------------+
- * + YCbCr 4:4:4 10bits + ``MEDIA_BUS_FMT_YUV10_1X30`` + ``V4L2_YCBCR_ENC_601`` +
- * + + + or ``V4L2_YCBCR_ENC_709`` +
- * + + + or ``V4L2_YCBCR_ENC_XV601`` +
- * + + + or ``V4L2_YCBCR_ENC_XV709`` +
+ * | YCbCr 4:4:4 10bits | ``MEDIA_BUS_FMT_YUV10_1X30`` | ``V4L2_YCBCR_ENC_601`` |
+ * | | | or ``V4L2_YCBCR_ENC_709`` |
+ * | | | or ``V4L2_YCBCR_ENC_XV601`` |
+ * | | | or ``V4L2_YCBCR_ENC_XV709`` |
* +----------------------+----------------------------------+------------------------------+
- * + YCbCr 4:4:4 12bits + ``MEDIA_BUS_FMT_YUV12_1X36`` + ``V4L2_YCBCR_ENC_601`` +
- * + + + or ``V4L2_YCBCR_ENC_709`` +
- * + + + or ``V4L2_YCBCR_ENC_XV601`` +
- * + + + or ``V4L2_YCBCR_ENC_XV709`` +
+ * | YCbCr 4:4:4 12bits | ``MEDIA_BUS_FMT_YUV12_1X36`` | ``V4L2_YCBCR_ENC_601`` |
+ * | | | or ``V4L2_YCBCR_ENC_709`` |
+ * | | | or ``V4L2_YCBCR_ENC_XV601`` |
+ * | | | or ``V4L2_YCBCR_ENC_XV709`` |
* +----------------------+----------------------------------+------------------------------+
- * + YCbCr 4:4:4 16bits + ``MEDIA_BUS_FMT_YUV16_1X48`` + ``V4L2_YCBCR_ENC_601`` +
- * + + + or ``V4L2_YCBCR_ENC_709`` +
- * + + + or ``V4L2_YCBCR_ENC_XV601`` +
- * + + + or ``V4L2_YCBCR_ENC_XV709`` +
+ * | YCbCr 4:4:4 16bits | ``MEDIA_BUS_FMT_YUV16_1X48`` | ``V4L2_YCBCR_ENC_601`` |
+ * | | | or ``V4L2_YCBCR_ENC_709`` |
+ * | | | or ``V4L2_YCBCR_ENC_XV601`` |
+ * | | | or ``V4L2_YCBCR_ENC_XV709`` |
* +----------------------+----------------------------------+------------------------------+
- * + YCbCr 4:2:2 8bit + ``MEDIA_BUS_FMT_UYVY8_1X16`` + ``V4L2_YCBCR_ENC_601`` +
- * + + + or ``V4L2_YCBCR_ENC_709`` +
+ * | YCbCr 4:2:2 8bit | ``MEDIA_BUS_FMT_UYVY8_1X16`` | ``V4L2_YCBCR_ENC_601`` |
+ * | | | or ``V4L2_YCBCR_ENC_709`` |
* +----------------------+----------------------------------+------------------------------+
- * + YCbCr 4:2:2 10bits + ``MEDIA_BUS_FMT_UYVY10_1X20`` + ``V4L2_YCBCR_ENC_601`` +
- * + + + or ``V4L2_YCBCR_ENC_709`` +
+ * | YCbCr 4:2:2 10bits | ``MEDIA_BUS_FMT_UYVY10_1X20`` | ``V4L2_YCBCR_ENC_601`` |
+ * | | | or ``V4L2_YCBCR_ENC_709`` |
* +----------------------+----------------------------------+------------------------------+
- * + YCbCr 4:2:2 12bits + ``MEDIA_BUS_FMT_UYVY12_1X24`` + ``V4L2_YCBCR_ENC_601`` +
- * + + + or ``V4L2_YCBCR_ENC_709`` +
+ * | YCbCr 4:2:2 12bits | ``MEDIA_BUS_FMT_UYVY12_1X24`` | ``V4L2_YCBCR_ENC_601`` |
+ * | | | or ``V4L2_YCBCR_ENC_709`` |
* +----------------------+----------------------------------+------------------------------+
- * + YCbCr 4:2:0 8bit + ``MEDIA_BUS_FMT_UYYVYY8_0_5X24`` + ``V4L2_YCBCR_ENC_601`` +
- * + + + or ``V4L2_YCBCR_ENC_709`` +
+ * | YCbCr 4:2:0 8bit | ``MEDIA_BUS_FMT_UYYVYY8_0_5X24`` | ``V4L2_YCBCR_ENC_601`` |
+ * | | | or ``V4L2_YCBCR_ENC_709`` |
* +----------------------+----------------------------------+------------------------------+
- * + YCbCr 4:2:0 10bits + ``MEDIA_BUS_FMT_UYYVYY10_0_5X30``+ ``V4L2_YCBCR_ENC_601`` +
- * + + + or ``V4L2_YCBCR_ENC_709`` +
+ * | YCbCr 4:2:0 10bits | ``MEDIA_BUS_FMT_UYYVYY10_0_5X30``| ``V4L2_YCBCR_ENC_601`` |
+ * | | | or ``V4L2_YCBCR_ENC_709`` |
* +----------------------+----------------------------------+------------------------------+
- * + YCbCr 4:2:0 12bits + ``MEDIA_BUS_FMT_UYYVYY12_0_5X36``+ ``V4L2_YCBCR_ENC_601`` +
- * + + + or ``V4L2_YCBCR_ENC_709`` +
+ * | YCbCr 4:2:0 12bits | ``MEDIA_BUS_FMT_UYYVYY12_0_5X36``| ``V4L2_YCBCR_ENC_601`` |
+ * | | | or ``V4L2_YCBCR_ENC_709`` |
* +----------------------+----------------------------------+------------------------------+
- * + YCbCr 4:2:0 16bits + ``MEDIA_BUS_FMT_UYYVYY16_0_5X48``+ ``V4L2_YCBCR_ENC_601`` +
- * + + + or ``V4L2_YCBCR_ENC_709`` +
+ * | YCbCr 4:2:0 16bits | ``MEDIA_BUS_FMT_UYYVYY16_0_5X48``| ``V4L2_YCBCR_ENC_601`` |
+ * | | | or ``V4L2_YCBCR_ENC_709`` |
* +----------------------+----------------------------------+------------------------------+
*/
--
2.13.1
Two table problems caused the PDF build to fail:
- Evidently multirow cells are not appreciated in table headers,
so remove such from the "CS Rows" table.
- The logging message structure table was incorrectly formatted,
with two "+" instead of "|". The HTML build is forgiving of such
things, but PDF is not.
Cc: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
---
Documentation/admin-guide/ras.rst | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/Documentation/admin-guide/ras.rst b/Documentation/admin-guide/ras.rst
index 8c7bbf2c88d2..197896718f81 100644
--- a/Documentation/admin-guide/ras.rst
+++ b/Documentation/admin-guide/ras.rst
@@ -344,9 +344,9 @@ for more than 2 channels, like Fully Buffered DIMMs (FB-DIMMs) memory
controllers. The following example will assume 2 channels:
+------------+-----------------------+
- | Chip | Channels |
- | Select +-----------+-----------+
- | rows | ``ch0`` | ``ch1`` |
+ | CS Rows | Channels |
+ +------------+-----------+-----------+
+ | | ``ch0`` | ``ch1`` |
+============+===========+===========+
| ``csrow0`` | DIMM_A0 | DIMM_B0 |
+------------+ | |
@@ -698,7 +698,7 @@ information indicating that errors have been detected::
The structure of the message is:
+---------------------------------------+-------------+
- | Content + Example |
+ | Content | Example |
+=======================================+=============+
| The memory controller | MC0 |
+---------------------------------------+-------------+
@@ -713,7 +713,7 @@ The structure of the message is:
+---------------------------------------+-------------+
| The error syndrome | 0xb741 |
+---------------------------------------+-------------+
- | Memory row | row 0 +
+ | Memory row | row 0 |
+---------------------------------------+-------------+
| Memory channel | channel 1 |
+---------------------------------------+-------------+
--
2.13.1
...otherwise the PDF build fails when it can't find constraints.pdf.
CC: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
---
Documentation/media/uapi/v4l/vidioc-g-selection.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/media/uapi/v4l/vidioc-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-g-selection.rst
index deb1f6fb473b..b80d85cb8891 100644
--- a/Documentation/media/uapi/v4l/vidioc-g-selection.rst
+++ b/Documentation/media/uapi/v4l/vidioc-g-selection.rst
@@ -129,8 +129,8 @@ Selection targets and flags are documented in
.. _sel-const-adjust:
-.. figure:: constraints.*
- :alt: constraints.pdf / constraints.svg
+.. kernel-figure:: constraints.svg
+ :alt: constraints.svg
:align: center
Size adjustments with constraint flags.
--
2.13.1
On Sun, 18 Jun 2017 17:46:25 -0600
Jonathan Corbet <[email protected]> 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 <[email protected]> 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 <[email protected]>
>
> 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 17:46:27 -0600
Jonathan Corbet <[email protected]> escreveu:
> Commit 85c21e5c3ee7 (docs-rst: better adjust margins and font size) added a
> \usepackage{geometry} that conflicts with another inclusion deep within the
> dependencies somewhere, causing the the PDF build to fail with a
> "conflicting parameters" error. Just remove it for now until we can figure
> out a better way.
>
> Fixes: 85c21e5c3ee74fb75d690c57f7066bae7e2dca55
> Cc: Mauro Carvalho Chehab <[email protected]>
> Signed-off-by: Jonathan Corbet <[email protected]>
> ---
> Documentation/conf.py | 2 --
> 1 file changed, 2 deletions(-)
>
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 93827bc1620f..3d4e89330044 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -271,8 +271,6 @@ latex_elements = {
>
> # Additional stuff for the LaTeX preamble.
> 'preamble': '''
> - % Adjust margins
> - \\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry}
> \\usepackage{ifthen}
This patch has a bad side effect: with it, the tables with this tag:
.. tabularcolumns::
become too big, violating the right margin. If Sphinx 1.5.x or
1.6.x replaced geometry package with something else, then I
guess we'll need to add some hack at conf.py for it to adjust
it based on the Sphinx version.
Btw, in order to build latex output here with Sphinx 1.6.x,
I had to install this package:
texlive-fncychap.noarch
Perhaps the change is somehow related to it.
Btw, the current documentation at:
http://www.sphinx-doc.org/en/stable/latex.html
added a new option for version 1.5.3 and upper, to setup the
geometry, using 'sphinxsetup'. As described there:
'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
I'll play with it and see if I can use it on such versions.
Thanks,
Mauro
Em Mon, 19 Jun 2017 07:30:38 -0300
Mauro Carvalho Chehab <[email protected]> escreveu:
> Em Sun, 18 Jun 2017 17:46:27 -0600
> Jonathan Corbet <[email protected]> escreveu:
>
> > Commit 85c21e5c3ee7 (docs-rst: better adjust margins and font size) added a
> > \usepackage{geometry} that conflicts with another inclusion deep within the
> > dependencies somewhere, causing the the PDF build to fail with a
> > "conflicting parameters" error. Just remove it for now until we can figure
> > out a better way.
> >
> > Fixes: 85c21e5c3ee74fb75d690c57f7066bae7e2dca55
> > Cc: Mauro Carvalho Chehab <[email protected]>
> > Signed-off-by: Jonathan Corbet <[email protected]>
> > ---
> > Documentation/conf.py | 2 --
> > 1 file changed, 2 deletions(-)
> >
> > diff --git a/Documentation/conf.py b/Documentation/conf.py
> > index 93827bc1620f..3d4e89330044 100644
> > --- a/Documentation/conf.py
> > +++ b/Documentation/conf.py
> > @@ -271,8 +271,6 @@ latex_elements = {
> >
> > # Additional stuff for the LaTeX preamble.
> > 'preamble': '''
> > - % Adjust margins
> > - \\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry}
> > \\usepackage{ifthen}
>
> This patch has a bad side effect: with it, the tables with this tag:
> .. tabularcolumns::
>
> become too big, violating the right margin. If Sphinx 1.5.x or
> 1.6.x replaced geometry package with something else, then I
> guess we'll need to add some hack at conf.py for it to adjust
> it based on the Sphinx version.
>
> Btw, in order to build latex output here with Sphinx 1.6.x,
> I had to install this package:
>
> texlive-fncychap.noarch
>
> Perhaps the change is somehow related to it.
>
> Btw, the current documentation at:
> http://www.sphinx-doc.org/en/stable/latex.html
>
> added a new option for version 1.5.3 and upper, to setup the
> geometry, using 'sphinxsetup'. As described there:
>
> 'sphinxsetup': 'hmargin={2in,1.5in}, vmargin={1.5in,2in}, marginpar=1in',
>
> I'll play with it and see if I can use it on such versions.
I guess the right fix would be do to something similar to what's in
the patch below.
There's a catch, though: as sphinxsetup hmargin/vmargin was added
only on Sphinx version 1.5.3, the enclosed patch won't adjust the
margins for versions 1.5.0 to 1.5.2. While I didn't test, I bet it
will just ignore the keys, showing some warning.
[PATCH] Docs: Fix breakage with Sphinx 1.5 and upper
Commit 85c21e5c3ee7 (docs-rst: better adjust margins and font size) added a
\usepackage{geometry} that conflicts with another inclusion deep within the
dependencies with newer versions of Sphinx, causing the the PDF build to fail
with a "conflicting parameters" error.
Detect the Sphinx version, using sphinxsetup for Sphinx versions 1.5 and
upper.
Fixes: 85c21e5c3ee74fb75d690c57f7066bae7e2dca55
Sighed-off-by: Mauro Carvalho Chehab <[email protected]>
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 9eff2c8f7f67..900b9cfea430 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -271,8 +271,6 @@ latex_elements = {
# Additional stuff for the LaTeX preamble.
'preamble': '''
- % Adjust margins
- \\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry}
\\usepackage{ifthen}
% Allow generate some pages in landscape
@@ -343,6 +341,12 @@ latex_elements = {
if major == 1 and minor > 3:
latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }\n'
+if major == 1 and minor < 5:
+ latex_elements['preamble'] += '\\usepackage[margin=0.5in, top=1in, bottom=1in]{geometry}'
+else:
+ latex_elements['sphinxsetup'] = 'hmargin=0.5in, vmargin=0.5in'
+
+
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
Em Sun, 18 Jun 2017 22:18:29 -0300
Mauro Carvalho Chehab <[email protected]> escreveu:
> Hi Jon,
>
> Em Sun, 18 Jun 2017 17:46:25 -0600
> Jonathan Corbet <[email protected]> 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 <[email protected]>
>
> >
> > 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 Mon, 19 Jun 2017 07:49:06 -0300
Mauro Carvalho Chehab <[email protected]> wrote:
> There's a catch, though: as sphinxsetup hmargin/vmargin was added
> only on Sphinx version 1.5.3, the enclosed patch won't adjust the
> margins for versions 1.5.0 to 1.5.2. While I didn't test, I bet it
> will just ignore the keys, showing some warning.
And people routinely accuse *me* of being overly optimistic...
> ! Package keyval Error: hmargin undefined.
>
> See the keyval package documentation for explanation.
> Type H <return> for immediate help.
> ...
>
> l.19 \sphinxsetup{hmargin=0.5in, vmargin=0.5in}
>
> ?
So it kills the build on 1.5.2.
I've made a tweak to special-case early 1.5.x.
> Fixes: 85c21e5c3ee74fb75d690c57f7066bae7e2dca55
> Sighed-off-by: Mauro Carvalho Chehab <[email protected]>
Sighed-off-by indeed, I agree. It's a good thing there's a lot of beer in
the fridge...
jon
Em Fri, 23 Jun 2017 13:39:51 -0600
Jonathan Corbet <[email protected]> escreveu:
> On Mon, 19 Jun 2017 07:49:06 -0300
> Mauro Carvalho Chehab <[email protected]> wrote:
>
> > There's a catch, though: as sphinxsetup hmargin/vmargin was added
> > only on Sphinx version 1.5.3, the enclosed patch won't adjust the
> > margins for versions 1.5.0 to 1.5.2. While I didn't test, I bet it
> > will just ignore the keys, showing some warning.
>
> And people routinely accuse *me* of being overly optimistic...
:-)
> > ! Package keyval Error: hmargin undefined.
> >
> > See the keyval package documentation for explanation.
> > Type H <return> for immediate help.
> > ...
> >
> > l.19 \sphinxsetup{hmargin=0.5in, vmargin=0.5in}
> >
> > ?
>
> So it kills the build on 1.5.2.
Murphy's law applied to coding: Anything untested that can go wrong
will go wrong :-)
Sorry for that.
>
> I've made a tweak to special-case early 1.5.x.
>
> > Fixes: 85c21e5c3ee74fb75d690c57f7066bae7e2dca55
> > Sighed-off-by: Mauro Carvalho Chehab <[email protected]>
>
> Sighed-off-by indeed, I agree. It's a good thing there's a lot of beer in
> the fridge...
Heh. Yeah, your changes look OK to me.
Btw, I tried for some time to fix pdf build with Sphinx 1.6 without
much luck. The new table macros version 1.6 adds makes almost
impossible to use adjustbox before a table, because it calls
vskip on them. The solution seems to either redefine those macros
or to override tabulary for it to always call adjustbox.
Unfortunately, I'm not fluent on LaTeX macros, so it takes me a
lot of time to work on it.
I'll try to look on it later, after the merge window.
Regards,
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 <[email protected]> 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 <[email protected]> wrote:
> On Mon, 3 Jul 2017 10:25:38 +0200
> Daniel Vetter <[email protected]> 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 <[email protected]>:
>
> On Mon, Jul 3, 2017 at 5:44 AM, Jonathan Corbet <[email protected]> wrote:
>> On Mon, 3 Jul 2017 10:25:38 +0200
>> Daniel Vetter <[email protected]> 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 <[email protected]> escreveu:
> On Mon, Jul 3, 2017 at 5:44 AM, Jonathan Corbet <[email protected]> wrote:
> > On Mon, 3 Jul 2017 10:25:38 +0200
> > Daniel Vetter <[email protected]> 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