Start changing media docs to build with PDF
Subsystems (2)
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
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
@@ -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
RFC PATCH 2/5 pixfmt-nv12mt.rst: use PNG instead of GIF
In reply to Mauro Carvalho Chehabpdflatex 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
@@ -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
Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png new file binary +0 -0
Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.gif deleted binary +0 -0
Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.png new file binary +0 -0
Signature · 1 line
2.7.4
RFC PATCH 3/5 docs-rst: get rid of extra less or equal symbols
In reply to Mauro Carvalho ChehabThe 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
@@ -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
@@ -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
RFC PATCH 4/5 vidioc-enumstd.rst: fix a broken reference
In reply to Mauro Carvalho ChehabSomehow, 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
@@ -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
RFC PATCH 5/5 HACK!!!!
In reply to Mauro Carvalho ChehabPlease, 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
@@ -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
@@ -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
@@ -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