Another set of fixes for PDF output
Subsystems (2)
PATCH 7/7 media: index.rst: don't write "Contents:" on PDF output
In reply to Mauro Carvalho ChehabRight now, Sphinx unconditionally creates a blank page with just "Contents:" on it, on PDF output. While this makes sense for html, it doesn't o PDF, as LaTeX does what's required automatically.
Fix it.
--- Documentation/media/index.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-)
Documentation/media/index.rst +5 -1
@@ -1,7 +1,11 @@ Linux Media Subsystem Documentation =================================== -Contents: +.. only:: html + + .. class:: toc-title + + Table of Contents .. toctree:: :maxdepth: 2
Signature · 1 line
2.13.5
cover Another set of fixes for PDF output
There are other things that are needed for a proper PDF output, and a fix for yet another Sphinx 1.6 breakage.
After this patch series, PDF output now looks OK on Sphinx 1.4 to 1.6.
There's, however, one step back on Sphinx 1.6: I couldn't find any way to use a background color for notifications (note, attention, important, etc).
In thesis, on Sphinx 1.6, this is natively supported. However, in practice, support for it is broken: if a note is inserted inside a table, it sometimes put at the wrong cell and with the wrong size.
I was not able to fix it there. Yet, it fails gracefully, as it will just display those boxes on boring black on white. While, IMHO, it fails to the idea of giving a highlight to the text, it is readable.
That is a shame, as, except for this, Sphinx 1.6 seems to produce a better table output than previous versions, when cell span is used. Also, less hacks at the latex_preamble are now required on newer versions. Well, maybe some day we may be able to remove all hacks on newer versions of it...
Mauro Carvalho Chehab (7):
media: format.rst: use the right markup for important notes
media: v4l2 uapi book: get rid of driver programming's chapter
media: vivid.rst: add a blank line to correct ReST format
media: vidioc-g-fmt.rst: adjust table format
media: fix build breakage with Sphinx 1.6
media: pixfmt*.rst: replace a two dots by a comma
media: index.rst: don't write "Contents:" on PDF output
Documentation/media/index.rst | 6 +++++- Documentation/media/uapi/v4l/driver.rst | 9 --------- Documentation/media/uapi/v4l/format.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-m420.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-nv12.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-nv12m.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-nv16.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-nv16m.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-srggb10p.rst | 16 ++++++++++++++-- Documentation/media/uapi/v4l/pixfmt-uyvy.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-vyuy.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-y41p.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yuv410.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yuv411p.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yuv420.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yuv420m.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yuv422m.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yuv422p.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yuv444m.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yuyv.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yvyu.rst | 2 +- Documentation/media/uapi/v4l/v4l2.rst | 1 - Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 2 +- Documentation/media/v4l-drivers/vivid.rst | 1 + 24 files changed, 39 insertions(+), 32 deletions(-) delete mode 100644 Documentation/media/uapi/v4l/driver.rst
Signature · 1 line
2.13.5
PATCH 2/7 media: v4l2 uapi book: get rid of driver programming's chapter
It doesn't make any sense having a driver programming's chapter at the uAPI book, as this is related to kernel API. Also, we now have such kAPI book where V4L2 driver programming is covered.
So, get rid of this left-over.
--- Documentation/media/uapi/v4l/driver.rst | 9 --------- Documentation/media/uapi/v4l/v4l2.rst | 1 - 2 files changed, 10 deletions(-) delete mode 100644 Documentation/media/uapi/v4l/driver.rst
Documentation/media/uapi/v4l/driver.rst deleted +0 -9
@@ -1,9 +0,0 @@ -.. -*- coding: utf-8; mode: rst -*- - -.. _driver: - -*********************** -V4L2 Driver Programming -*********************** - -to do
Documentation/media/uapi/v4l/v4l2.rst +0 -1
@@ -25,7 +25,6 @@ This part describes the Video for Linux API version 2 (V4L2 API) specification. pixfmt io devices - driver libv4l compat user-func
Signature · 1 line
2.13.5
PATCH 4/7 media: vidioc-g-fmt.rst: adjust table format
In reply to Mauro Carvalho ChehabWhile doing a visual inspection with Sphinx 1.5, I noticed that one of the columns was smaller than the text written there.
As this is the only thing I noticed with Sphinx 1.5, I suspect that this was also a problem with Sphinx 1.4. Yet, I opted to touch it in a way that wouldn't cause backward issues.
--- Documentation/media/uapi/v4l/vidioc-g-fmt.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/media/uapi/v4l/vidioc-g-fmt.rst +1 -1
@@ -88,7 +88,7 @@ The format as returned by :ref:`VIDIOC_TRY_FMT <VIDIOC_G_FMT>` must be identical .. c:type:: v4l2_format -.. tabularcolumns:: |p{1.2cm}|p{4.3cm}|p{3.0cm}|p{9.0cm}| +.. tabularcolumns:: |p{1.2cm}|p{4.6cm}|p{3.0cm}|p{8.6cm}| .. flat-table:: struct v4l2_format :header-rows: 0
Signature · 1 line
2.13.5
PATCH 5/7 media: fix build breakage with Sphinx 1.6
In reply to Mauro Carvalho ChehabNot sure why, but, on this particular document, on Sphinx 1.4 and 1.5, the usage of \small here causes it to write the table at the same column where the text before it ended, with makes the table to go out of the page.
A possible solution would be to add a \newline on latex raw, with was the approach took.
Unfortunately, that causes a breakage on Sphinx 1.6.
So, we're adding a small dot here, in order to avoid polluting too much the document, while making it compatible with all versions.
--- Documentation/media/uapi/v4l/pixfmt-srggb10p.rst | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-)
Documentation/media/uapi/v4l/pixfmt-srggb10p.rst +14 -2
@@ -33,10 +33,22 @@ of a small V4L2_PIX_FMT_SBGGR10P image: **Byte Order.** Each cell is one byte. - .. raw:: latex - \newline\small + \small + +.. HACK: + + On Sphinx 1.4 and 1.5, the usage of \small just before the table + causes it to continue at the same column where the above text ended. + + A possible solution would be to add a \newline on latex raw. + Unfortunately, that causes a breakage on Sphinx 1.6. + + So, we're placing the \small before this note, with should be producing + the same result on all versions + +. .. tabularcolumns:: |p{2.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{10.0cm}|
Signature · 1 line
2.13.5
PATCH 1/7 media: format.rst: use the right markup for important notes
In reply to Mauro Carvalho ChehabThere's an important note there, but it is not using the ReST markup. So, it doesn't get any visual highlight on the output.
--- Documentation/media/uapi/v4l/format.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/media/uapi/v4l/format.rst +1 -1
@@ -78,7 +78,7 @@ output devices is available. [#f1]_ The :ref:`VIDIOC_ENUM_FMT` ioctl must be supported by all drivers exchanging image data with applications. - **Important** +.. important:: Drivers are not supposed to convert image formats in kernel space. They must enumerate only formats directly supported by the hardware.
Signature · 1 line
2.13.5
PATCH 3/7 media: vivid.rst: add a blank line to correct ReST format
In reply to Mauro Carvalho ChehabOn all vivid parameters, there's an space after the parameter, except for "DV Timings Signal Mode". That makes this single one to be written in bold, and, at PDF output, at the same line as its description.
Use the same convention as the other parameters, in order to adjust its output.
--- Documentation/media/v4l-drivers/vivid.rst | 1 + 1 file changed, 1 insertion(+)
Documentation/media/v4l-drivers/vivid.rst +1 -0
@@ -829,6 +829,7 @@ The following two controls are only valid for video and vbi capture. The following two controls are only valid for video capture. - DV Timings Signal Mode: + selects the behavior of VIDIOC_QUERY_DV_TIMINGS: what should it return?
Signature · 1 line
2.13.5
PATCH 6/7 media: pixfmt*.rst: replace a two dots by a comma
In reply to Mauro Carvalho ChehabOn several tables, the color sample location table preamble is written as:
Color Sample Location..
Instead of:
Color Sample Location:
I suspect that the repetition of such pattern was due to some copy-and-paste (or perhaps some error during DocBook conversion).
Anyway, fix it.
--- Documentation/media/uapi/v4l/pixfmt-m420.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-nv12.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-nv12m.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-nv16.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-nv16m.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-uyvy.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-vyuy.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-y41p.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yuv410.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yuv411p.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yuv420.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yuv420m.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yuv422m.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yuv422p.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yuv444m.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yuyv.rst | 2 +- Documentation/media/uapi/v4l/pixfmt-yvyu.rst | 2 +- 17 files changed, 17 insertions(+), 17 deletions(-)
Documentation/media/uapi/v4l/pixfmt-m420.rst +1 -1
@@ -66,7 +66,7 @@ Each cell is one byte. - Cr\ :sub:`11` -**Color Sample Location..** +**Color Sample Location:**
Documentation/media/uapi/v4l/pixfmt-nv12.rst +1 -1
@@ -71,7 +71,7 @@ Each cell is one byte. - Cr\ :sub:`11` -**Color Sample Location..** +**Color Sample Location:** .. flat-table:: :header-rows: 0
Documentation/media/uapi/v4l/pixfmt-nv12m.rst +1 -1
@@ -83,7 +83,7 @@ Each cell is one byte. - Cr\ :sub:`11` -**Color Sample Location..** +**Color Sample Location:**
Documentation/media/uapi/v4l/pixfmt-nv16.rst +1 -1
@@ -79,7 +79,7 @@ Each cell is one byte. - Cr\ :sub:`31` -**Color Sample Location..** +**Color Sample Location:**
Documentation/media/uapi/v4l/pixfmt-nv16m.rst +1 -1
@@ -83,7 +83,7 @@ Each cell is one byte. - Cr\ :sub:`32` -**Color Sample Location..** +**Color Sample Location:**
Documentation/media/uapi/v4l/pixfmt-uyvy.rst +1 -1
@@ -65,7 +65,7 @@ Each cell is one byte. - Y'\ :sub:`33` -**Color Sample Location..** +**Color Sample Location:**
Documentation/media/uapi/v4l/pixfmt-vyuy.rst +1 -1
@@ -65,7 +65,7 @@ Each cell is one byte. - Y'\ :sub:`33` -**Color Sample Location..** +**Color Sample Location:** .. flat-table:: :header-rows: 0
Documentation/media/uapi/v4l/pixfmt-y41p.rst +1 -1
@@ -88,7 +88,7 @@ Each cell is one byte. - Y'\ :sub:`37` -**Color Sample Location..** +**Color Sample Location:** .. flat-table:: :header-rows: 0
Documentation/media/uapi/v4l/pixfmt-yuv410.rst +1 -1
@@ -67,7 +67,7 @@ Each cell is one byte. - Cb\ :sub:`00` -**Color Sample Location..** +**Color Sample Location:**
Documentation/media/uapi/v4l/pixfmt-yuv411p.rst +1 -1
@@ -75,7 +75,7 @@ Each cell is one byte. - Cr\ :sub:`30` -**Color Sample Location..** +**Color Sample Location:**
Documentation/media/uapi/v4l/pixfmt-yuv420.rst +1 -1
@@ -76,7 +76,7 @@ Each cell is one byte. - Cb\ :sub:`11` -**Color Sample Location..** +**Color Sample Location:**
Documentation/media/uapi/v4l/pixfmt-yuv420m.rst +1 -1
@@ -85,7 +85,7 @@ Each cell is one byte. - Cr\ :sub:`11` -**Color Sample Location..** +**Color Sample Location:**
Documentation/media/uapi/v4l/pixfmt-yuv422m.rst +1 -1
@@ -96,7 +96,7 @@ Each cell is one byte. - Cr\ :sub:`31` -**Color Sample Location..** +**Color Sample Location:**
Documentation/media/uapi/v4l/pixfmt-yuv422p.rst +1 -1
@@ -84,7 +84,7 @@ Each cell is one byte. - Cr\ :sub:`31` -**Color Sample Location..** +**Color Sample Location:**
Documentation/media/uapi/v4l/pixfmt-yuv444m.rst +1 -1
@@ -106,7 +106,7 @@ Each cell is one byte. - Cr\ :sub:`33` -**Color Sample Location..** +**Color Sample Location:**
Documentation/media/uapi/v4l/pixfmt-yuyv.rst +1 -1
@@ -68,7 +68,7 @@ Each cell is one byte. - Cr\ :sub:`31` -**Color Sample Location..** +**Color Sample Location:**
Documentation/media/uapi/v4l/pixfmt-yvyu.rst +1 -1
@@ -65,7 +65,7 @@ Each cell is one byte. - Cb\ :sub:`31` -**Color Sample Location..** +**Color Sample Location:** .. flat-table:: :header-rows: 0
Signature · 1 line
2.13.5
PATCH 1/1 docs-rst: media: Don't use \small for V4L2_PIX_FMT_SRGGB10 documentation
In reply to Mauro Carvalho ChehabThere appears to be an issue in using \small in certain cases on Sphinx 1.4 and 1.5. Other format documents don't use \small either, remove it from here as well.
---
Hi Mauro,
What would you think of this as an alternative approach? No hacks needed. Just a recognition \small could have issues. For what it's worth, I couldn't reproduce the issue on Sphinx 1.4.9.
Regards,
Sakari
Documentation/media/uapi/v4l/pixfmt-srggb10p.rst | 11 ----------- 1 file changed, 11 deletions(-)
Documentation/media/uapi/v4l/pixfmt-srggb10p.rst +0 -11
@@ -33,13 +33,6 @@ of a small V4L2_PIX_FMT_SBGGR10P image: **Byte Order.** Each cell is one byte. - -.. raw:: latex - - \small - -.. tabularcolumns:: |p{2.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{10.0cm}| - .. flat-table:: :header-rows: 0 :stub-columns: 0
@@ -73,7 +66,3 @@ Each cell is one byte. - R\ :sub:`33high` - R\ :sub:`33low`\ (bits 7--6) G\ :sub:`32low`\ (bits 5--4) R\ :sub:`31low`\ (bits 3--2) G\ :sub:`30low`\ (bits 1--0) - -.. raw:: latex - - \normalsize
Signature · 1 line
2.11.0
Re: [PATCH 1/1] docs-rst: media: Don't use \small for V4L2_PIX_FMT_SRGGB10 documentation
Em Sun, 3 Sep 2017 23:12:33 +0300
Sakari Ailus <[email protected]> escreveu:
Quoted 11 lines
There appears to be an issue in using \small in certain cases on Sphinx 1.4 and 1.5. Other format documents don't use \small either, remove it from here as well.
Signed-off-by Sakari Ailus <[email protected]>---
Hi Mauro,What would you think of this as an alternative approach? No hacks needed. Just a recognition \small could have issues. For what it's worth, I couldn't reproduce the issue on Sphinx 1.4.9.
Btw, there are other places where \small runs smoothly. It is *just* on this table that it has issues.
Quoted 12 lines
Regards,
SakariDocumentation/media/uapi/v4l/pixfmt-srggb10p.rst | 11 ----------- 1 file changed, 11 deletions(-)Documentation/media/uapi/v4l/pixfmt-srggb10p.rst +0
-0
Documentation/media/uapi/v4l/pixfmt-srggb10p.rst of a small V4L2_PIX_FMT_SBGGR10P image: · line 39
Quoted 7 lines
Documentation/media/uapi/v4l/pixfmt-srggb10p.rst +0
-4@@ -33,13 +33,6 @@ of a small V4L2_PIX_FMT_SBGGR10P image: **Byte Order.** Each cell is one byte. - -.. raw:: latex - - \small
Interesting... yeah, that could be possible.
Documentation/media/uapi/v4l/pixfmt-srggb10p.rst of a small V4L2_PIX_FMT_SBGGR10P image: · line 41
Quoted 2 lines
Documentation/media/uapi/v4l/pixfmt-srggb10p.rst +0
-2- -.. tabularcolumns:: |p{2.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{10.0cm}|
Nah... Without tabularcolumns, LaTeX usually got sizes wrong and don't always place things at the right positions I'm actually considering adding it to all media tables, in order to be less dependent on LaTex automatic cells resizing - with doesn't seem to work too well.
So, better to keep it, even if it works without
\small. Btw, tried your patch here (without tabularcolumns) on Sphinx 1.6 (tomorrow, I'll do tests with other version). There, the last "(bits x-y)" ends by being wrapped to the next line.
Yet, I guess the enclosed diff (or something like that) would be good enough (applied after my own patch, just to quickly test it).
I'll play more with it tomorrow.
Thanks,
Mauro
Documentation/media/uapi/v4l/pixfmt-srggb10p.rst +5 -22
@@ -33,24 +33,7 @@ of a small V4L2_PIX_FMT_SBGGR10P image: **Byte Order.** Each cell is one byte. -.. raw:: latex - - \small - -.. HACK: - - On Sphinx 1.4 and 1.5, the usage of \small just before the table - causes it to continue at the same column where the above text ended. - - A possible solution would be to add a \newline on latex raw. - Unfortunately, that causes a breakage on Sphinx 1.6. - - So, we're placing the \small before this note, with should be producing - the same result on all versions - -. - -.. tabularcolumns:: |p{2.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{10.0cm}| +.. tabularcolumns:: |p{2.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{6.0cm}| .. flat-table:: :header-rows: 0
@@ -63,6 +46,7 @@ Each cell is one byte. - B\ :sub:`02high` - G\ :sub:`03high` - G\ :sub:`03low`\ (bits 7--6) B\ :sub:`02low`\ (bits 5--4) + G\ :sub:`01low`\ (bits 3--2) B\ :sub:`00low`\ (bits 1--0) * - start + 5: - G\ :sub:`10high`
@@ -70,6 +54,7 @@ Each cell is one byte. - G\ :sub:`12high` - R\ :sub:`13high` - R\ :sub:`13low`\ (bits 7--6) G\ :sub:`12low`\ (bits 5--4) + R\ :sub:`11low`\ (bits 3--2) G\ :sub:`10low`\ (bits 1--0) * - start + 10: - B\ :sub:`20high`
@@ -77,6 +62,7 @@ Each cell is one byte. - B\ :sub:`22high` - G\ :sub:`23high` - G\ :sub:`23low`\ (bits 7--6) B\ :sub:`22low`\ (bits 5--4) + G\ :sub:`21low`\ (bits 3--2) B\ :sub:`20low`\ (bits 1--0) * - start + 15: - G\ :sub:`30high`
@@ -84,8 +70,5 @@ Each cell is one byte. - G\ :sub:`32high` - R\ :sub:`33high` - R\ :sub:`33low`\ (bits 7--6) G\ :sub:`32low`\ (bits 5--4) - R\ :sub:`31low`\ (bits 3--2) G\ :sub:`30low`\ (bits 1--0) - -.. raw:: latex - \normalsize + R\ :sub:`31low`\ (bits 3--2) G\ :sub:`30low`\ (bits 1--0)
Re: [PATCH 1/1] docs-rst: media: Don't use \small for V4L2_PIX_FMT_SRGGB10 documentation
Em Sun, 3 Sep 2017 22:40:02 -0300
Mauro Carvalho Chehab <[email protected]> escreveu:
Quoted 54 lines
Em Sun, 3 Sep 2017 23:12:33 +0300
Sakari Ailus <[email protected]> escreveu:Quoted 11 lines
There appears to be an issue in using \small in certain cases on Sphinx 1.4 and 1.5. Other format documents don't use \small either, remove it from here as well.
Signed-off-by Sakari Ailus <[email protected]>---
Hi Mauro,What would you think of this as an alternative approach? No hacks needed. Just a recognition \small could have issues. For what it's worth, I couldn't reproduce the issue on Sphinx 1.4.9.
Btw, there are other places where \small runs smoothly. It is *just* on this table that it has issues.
Quoted 12 lines
Regards,
SakariDocumentation/media/uapi/v4l/pixfmt-srggb10p.rst | 11 ----------- 1 file changed, 11 deletions(-)Documentation/media/uapi/v4l/pixfmt-srggb10p.rst +0
-0Documentation/media/uapi/v4l/pixfmt-srggb10p.rst of a small V4L2_PIX_FMT_SBGGR10P image: · line 39
Quoted 7 lines
Documentation/media/uapi/v4l/pixfmt-srggb10p.rst +0
-4@@ -33,13 +33,6 @@ of a small V4L2_PIX_FMT_SBGGR10P image: **Byte Order.** Each cell is one byte. - -.. raw:: latex - - \smallInteresting... yeah, that could be possible.
Documentation/media/uapi/v4l/pixfmt-srggb10p.rst of a small V4L2_PIX_FMT_SBGGR10P image: · line 41
Quoted 2 lines
Documentation/media/uapi/v4l/pixfmt-srggb10p.rst +0
-2- -.. tabularcolumns:: |p{2.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{1.0cm}|p{10.0cm}|Nah... Without tabularcolumns, LaTeX usually got sizes wrong and don't always place things at the right positions I'm actually considering adding it to all media tables, in order to be less dependent on LaTex automatic cells resizing - with doesn't seem to work too well.
So, better to keep it, even if it works without
\small. Btw, tried your patch here (without tabularcolumns) on Sphinx 1.6 (tomorrow, I'll do tests with other version). There, the last "(bits x-y)" ends by being wrapped to the next line.
Quoted 4 lines
Yet, I guess the enclosed diff (or something like that) would be good enough (applied after my own patch, just to quickly test it).
I'll play more with it tomorrow.
OK, that works. Thanks!
I rebased your patch, keeping tabularcolumns and adding blank lines to reduce the column size.
That works really better.
I also added a second patch doing the same for srggb12p.
Thanks,
Mauro