Skip to contentSkip to conversation

Start changing media docs to build with PDF

RFC PATCH New Mauro Carvalho Chehab 1 participant 6 messages Aug 15, 2016

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

cover Start changing media docs to build with PDF

This series are experimental patches that change some things at the media books in order to make pdflatex to produce a valid document.

The first patch use Sphinx math extension. Please notice that it only works if the rst2pdf extension is disabled, as otherwise Sphinx 1.4.x will complain about duplicated math modules. So, it can only be applied if we give up using rst2pdf or find the bug that prevents using it together with the math extension at the Sphinx conf.py.

The other two patches fix some additional issues that are needed for the Latex output to work.

The forth patch is actually a bug fix, and should be merged upstream anyway.

The last patch is actually a HACK!!! should *never* be merged upstream as-is.

It is there to show that somehow, Sphinx LaTeX tables output is broken. On several places where we add a note or an attention on a table row, the Latex output is broken. I suspect that the bug is actually when multiple lines are generated inside a table row, but I don't know enough about LaTeX to be sure...

Anyway, this is just a PoC. I don't care enough about PDF output to try fixing the issues at rst2pdf or at Sphinx LaTeX output (needed by pdflatex). Yet, I'd like to see patch 1 applied, as the math expressions look a way better using LaTeX math than before. Yet, if we do that, we'll end by needing the LaTeX big dependency chain.

Mauro Carvalho Chehab (5):
[media] pixfmt-007.rst: use Sphinx math:: expressions [media] pixfmt-nv12mt.rst: use PNG instead of GIF [media] docs-rst: get rid of extra less or equal symbols [media] vidioc-enumstd.rst: fix a broken reference HACK!!!!

 Documentation/conf.py                              |   9 +-
 .../media/uapi/cec/cec-ioc-adap-g-log-addrs.rst    |   2 +-
 Documentation/media/uapi/v4l/buffer.rst            |  15 +-
 Documentation/media/uapi/v4l/dev-overlay.rst       |   7 +-
 Documentation/media/uapi/v4l/pixfmt-007.rst        | 175 ++++++++++++++-------
 Documentation/media/uapi/v4l/pixfmt-nv12mt.rst     |   4 +-
 .../media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif  | Bin 2108 -> 0 bytes
 .../media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png  | Bin 0 -> 1920 bytes
 .../v4l/pixfmt-nv12mt_files/nv12mt_example.gif     | Bin 6858 -> 0 bytes
 .../v4l/pixfmt-nv12mt_files/nv12mt_example.png     | Bin 0 -> 5261 bytes
 Documentation/media/uapi/v4l/vidioc-enum-fmt.rst   |  17 +-
 .../media/uapi/v4l/vidioc-enum-freq-bands.rst      |  14 +-
 Documentation/media/uapi/v4l/vidioc-enumstd.rst    |   2 +-
 13 files changed, 152 insertions(+), 93 deletions(-)
 delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif
 create mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png
 delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.gif
 create mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.png
Signature · 1 line
2.7.4
#1 lore raw

RFC PATCH 1/5 pixfmt-007.rst: use Sphinx math:: expressions

Enrich math formulas by using the Sphinx math. That will allow using those formulas on pdf documents as well.

---
 Documentation/conf.py                       |   9 +-
 Documentation/media/uapi/v4l/pixfmt-007.rst | 175 ++++++++++++++++++----------
 2 files changed, 115 insertions(+), 69 deletions(-)
Documentation/conf.py +1 -8
index 96b7aa66c89c..163782912df9 100644
@@ -28,14 +28,7 @@ sys.path.insert(0, os.path.abspath('sphinx'))
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['kernel-doc', 'rstFlatTable', 'kernel_include']
-
-# Gracefully handle missing rst2pdf.
-try:
-    import rst2pdf
-    extensions += ['rst2pdf.pdfbuilder']
-except ImportError:
-    pass
+extensions = ['sphinx.ext.imgmath', 'kernel-doc', 'rstFlatTable', 'kernel_include']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
Documentation/media/uapi/v4l/pixfmt-007.rst +114 -61

331 lines not on this page · raw message

Signature · 1 line
2.7.4
#2 lore raw

RFC PATCH 2/5 pixfmt-nv12mt.rst: use PNG instead of GIF

In reply to Mauro Carvalho Chehab

pdflatex doesn't like gif images:
None:None: WARNING: no matching candidate for image URI u'media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.*' None:None: WARNING: no matching candidate for image URI u'media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.*'

But it works fine with png. So, convert them. As a plus, PNG images are smaller.

---
 Documentation/media/uapi/v4l/pixfmt-nv12mt.rst           |   4 ++--
 .../media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif        | Bin 2108 -> 0 bytes
 .../media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png        | Bin 0 -> 1920 bytes
 .../uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.gif      | Bin 6858 -> 0 bytes
 .../uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.png      | Bin 0 -> 5261 bytes
 5 files changed, 2 insertions(+), 2 deletions(-)
 delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif
 create mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png
 delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.gif
 create mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.png
Documentation/media/uapi/v4l/pixfmt-nv12mt.rst +2 -2
index 6198941bb814..1e6fdf0194f5 100644
@@ -36,7 +36,7 @@ Layout of macroblocks in memory is presented in the following figure.
 .. _nv12mt:
 
 .. figure::  pixfmt-nv12mt_files/nv12mt.*
-    :alt:    nv12mt.gif
+    :alt:    nv12mt.png
     :align:  center
 
     V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout
@@ -53,7 +53,7 @@ interleaved. Height of the buffer is aligned to 32.
 .. _nv12mt_ex:
 
 .. figure::  pixfmt-nv12mt_files/nv12mt_example.*
-    :alt:    nv12mt_example.gif
+    :alt:    nv12mt_example.png
     :align:  center
 
     Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks
Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.gif deleted binary +0 -0
deleted file mode 100644
index ef2d4cf8367b97293eb9139de0f33d0a2ac236be..0000000000000000000000000000000000000000
GIT binary patch
Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png new file binary +0 -0
new file mode 100644
index 0000000000000000000000000000000000000000..41401860fb737739658c354c0cb7ca12313a0265
GIT binary patch
Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.gif deleted binary +0 -0
deleted file mode 100644
index df81d68108eeb66569417b475984aa634385eebb..0000000000000000000000000000000000000000
GIT binary patch
Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.png new file binary +0 -0
new file mode 100644
index 0000000000000000000000000000000000000000..7775f5d7cc4661b7ec082e7ed5542eddb7dc65de
GIT binary patch
Signature · 1 line
2.7.4
#3 lore raw

RFC PATCH 3/5 docs-rst: get rid of extra less or equal symbols

In reply to Mauro Carvalho Chehab

The LaTeX output format doesn't support less or equal UTF-8 symbols. So, we need to get rid of them or to convert to math expressions.

---
 Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst | 2 +-
 Documentation/media/uapi/v4l/dev-overlay.rst              | 7 ++++++-
 2 files changed, 7 insertions(+), 2 deletions(-)
Documentation/media/uapi/cec/cec-ioc-adap-g-log-addrs.rst +1 -1
index 04ee90099676..a7315a8d219a 100644
@@ -114,7 +114,7 @@ logical address types are already defined will return with error ``EBUSY``.
 
        -  ``num_log_addrs``
 
-       -  Number of logical addresses to set up. Must be ≤
+       -  Number of logical addresses to set up. Must be less or equal to
 	  ``available_log_addrs`` as returned by
 	  :ref:`CEC_ADAP_G_CAPS`. All arrays in
 	  this structure are only filled up to index
Documentation/media/uapi/v4l/dev-overlay.rst +6 -1
index 92b4471b0c6e..13359134b468 100644
@@ -216,7 +216,12 @@ bits like:
 
     ((__u8 *) bitmap)[w.width * y + x / 8] & (1 << (x & 7))
 
-where ``0`` ≤ x < ``w.width`` and ``0`` ≤ y <``w.height``. [#f2]_
+where [#f2]_:
+
+.. math::
+
+    0 \le x < w.width \text{, and }
+    0 \le y < w.height
 
 When a clipping bit mask is not supported the driver ignores this field,
 its contents after calling :ref:`VIDIOC_S_FMT <VIDIOC_G_FMT>` are
Signature · 1 line
2.7.4
#4 lore raw

RFC PATCH 4/5 vidioc-enumstd.rst: fix a broken reference

In reply to Mauro Carvalho Chehab

Somehow, the conversion broke a reference here. Re-add it.

---
 Documentation/media/uapi/v4l/vidioc-enumstd.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/media/uapi/v4l/vidioc-enumstd.rst +1 -1
index 6699b26cdeb4..a936fe32ce9c 100644
@@ -269,7 +269,7 @@ support digital TV. See also the Linux DVB API at
 
 .. _video-standards:
 
-.. flat-table:: Video Standards (based on [])
+.. flat-table:: Video Standards (based on :ref:`itu470`)
     :header-rows:  1
     :stub-columns: 0
 
Signature · 1 line
2.7.4
#5 lore raw

RFC PATCH 5/5 HACK!!!!

In reply to Mauro Carvalho Chehab

Please, never apply this!

This hack comments out some stuff, in order to fix a few table outputs when using Sphinx LaTeX output and pdflatex. Please notice that this *won't* fix all bugs. A lot more similar hacks is needed, as it seems that Sphinx LaTeX is broken for non-trivial tables.

---
 Documentation/media/uapi/v4l/buffer.rst                 | 15 ++++++++++-----
 Documentation/media/uapi/v4l/vidioc-enum-fmt.rst        | 17 +++++++++--------
 Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst | 14 ++++++++------
 3 files changed, 27 insertions(+), 19 deletions(-)
Documentation/media/uapi/v4l/buffer.rst +10 -5
index 5deb4a46f992..0b0af04ec955 100644
@@ -166,11 +166,16 @@ struct v4l2_buffer
 	  output device because the application did not pass new data in
 	  time.
 
-	  .. note:: This may count the frames received e.g. over USB, without
-	     taking into account the frames dropped by the remote hardware due
-	     to limited compression throughput or bus bandwidth. These devices
-	     identify by not enumerating any video standards, see
-	     :ref:`standard`.
+	  FOO
+
+..	  .. note::
+..
+..	     This may count the frames received e.g. over USB, without
+..	     taking into account the frames dropped by the remote hardware due
+..	     to limited compression throughput or bus bandwidth. These devices
+..	     identify by not enumerating any video standards, see
+..	     :ref:`standard`.
+
 
     -  .. row 10
 
Documentation/media/uapi/v4l/vidioc-enum-fmt.rst +9 -8
index 90996f69d6ae..f4b79975aefd 100644
@@ -51,7 +51,6 @@ one until ``EINVAL`` is returned.
     :stub-columns: 0
     :widths:       1 1 2
 
-
     -  .. row 1
 
        -  __u32
@@ -106,15 +105,17 @@ one until ``EINVAL`` is returned.
 
 
 	  .. _v4l2-fourcc:
-	  .. code-block:: c
-
-	      #define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))
-
+..	  .. code-block:: c
+..
+..	      #define v4l2_fourcc(a,b,c,d) (((__u32)(a)<<0)|((__u32)(b)<<8)|((__u32)(c)<<16)|((__u32)(d)<<24))
+..
 	  Several image formats are already defined by this specification in
 	  :ref:`pixfmt`.
-
-	  .. attention:: These codes are not the same as those used
-	     in the Windows world.
+..
+..	  .. attention::
+..
+..	     These codes are not the same as those used
+..	     in the Windows world.
 
     -  .. row 7
 
Documentation/media/uapi/v4l/vidioc-enum-freq-bands.rst +8 -6
index 00ab5e19cc1d..8564b9c2983e 100644
@@ -129,12 +129,14 @@ of the corresponding tuner/modulator is set.
        -  :cspan:`2` The supported modulation systems of this frequency
 	  band. See :ref:`band-modulation`.
 
-	  .. note:: Currently only one modulation system per frequency band
-	     is supported. More work will need to be done if multiple
-	     modulation systems are possible. Contact the linux-media
-	     mailing list
-	     (`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
-	     if you need such functionality.
+..	  .. note::
+..
+..	     Currently only one modulation system per frequency band
+..	     is supported. More work will need to be done if multiple
+..	     modulation systems are possible. Contact the linux-media
+..	     mailing list
+..	     (`https://linuxtv.org/lists.php <https://linuxtv.org/lists.php>`__)
+..	     if you need such functionality.
 
     -  .. row 8
 
Signature · 1 line
2.7.4