Commit 3ed3e130 authored by Jonathan Corbet's avatar Jonathan Corbet

Merge branch 'mauro-pdf' into docs-next

Mauro says:

This series address a series of errors during PDF generation from
media documentation.

The first patch fixes the late redefinition of a LaTeX command at the
Sphinx LaTeX style that causes build to break when some cross-references
are used.

The next two patches fix PDF output issues with subdev-formats.rst.

The next 3 patches fix image includes and their output for PDF.

It is aligned with Linus request of not having binary-generated images
from their SVG source codes.

I still intend to move the remaing PNG images to vectorial ones (SVG),
as image scale works better, but this will require some additional work.
When done, I'll submit as a separate patch series.

It should also be noticed that the last patch violates the output dir,
when make is used with "O=some_dir", as Sphinx doesn't accept
image files outside the source directory. We'll likely need some Sphinx
extension in order to fix it, but at least with this series (plus Jani Nikola's
PDF fix series), the PDF output should work fine again.

[jc: added a commit fixing up a "make cleandocs" warning]
parents f5ff9b63 c54b6b37
...@@ -54,7 +54,7 @@ loop_cmd = $(echo-cmd) $(cmd_$(1)) ...@@ -54,7 +54,7 @@ loop_cmd = $(echo-cmd) $(cmd_$(1))
# e.g. "media" for the linux-tv book-set at ./Documentation/media # e.g. "media" for the linux-tv book-set at ./Documentation/media
quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media all;\ cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2;\
BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
$(SPHINXBUILD) \ $(SPHINXBUILD) \
-b $2 \ -b $2 \
...@@ -98,6 +98,7 @@ installmandocs: ...@@ -98,6 +98,7 @@ installmandocs:
cleandocs: cleandocs:
$(Q)rm -rf $(BUILDDIR) $(Q)rm -rf $(BUILDDIR)
$(Q)$(MAKE) -C Documentation/media clean
endif # HAVE_SPHINX endif # HAVE_SPHINX
......
...@@ -37,7 +37,7 @@ from load_config import loadConfig ...@@ -37,7 +37,7 @@ from load_config import loadConfig
extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain'] extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain']
# The name of the math extension changed on Sphinx 1.4 # The name of the math extension changed on Sphinx 1.4
if minor > 3: if major == 1 and minor > 3:
extensions.append("sphinx.ext.imgmath") extensions.append("sphinx.ext.imgmath")
else: else:
extensions.append("sphinx.ext.pngmath") extensions.append("sphinx.ext.pngmath")
...@@ -332,6 +332,10 @@ latex_elements = { ...@@ -332,6 +332,10 @@ latex_elements = {
''' '''
} }
# Fix reference escape troubles with Sphinx 1.4.x
if major == 1 and minor > 3:
latex_elements['preamble'] += '\\renewcommand*{\\DUrole}[2]{ #2 }\n'
# Grouping the document tree into LaTeX files. List of tuples # Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, # (source start file, target name, title,
# author, documentclass [howto, manual, or own class]). # author, documentclass [howto, manual, or own class]).
......
...@@ -10,8 +10,35 @@ FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \ ...@@ -10,8 +10,35 @@ FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \
TARGETS := $(addprefix $(BUILDDIR)/, $(FILES)) TARGETS := $(addprefix $(BUILDDIR)/, $(FILES))
.PHONY: all IMAGES = \
typical_media_device.svg \
uapi/dvb/dvbstb.svg \
uapi/v4l/constraints.svg \
uapi/v4l/subdev-image-processing-full.svg \
uapi/v4l/subdev-image-processing-scaling-multi-source.svg \
uapi/v4l/subdev-image-processing-crop.svg \
IMGTGT := $(patsubst %.png,%.pdf,$(patsubst %.svg,%.pdf,$(IMAGES)))
IMGPDF := $(patsubst %,$(SRC_DIR)/%,$(IMGTGT))
cmd = $(echo-cmd) $(cmd_$(1))
quiet_cmd_genpdf = GENPDF $2
cmd_genpdf = convert $2 $3
%.pdf: %.svg
@$(call cmd,genpdf,$<,$@)
.PHONY: all html epub xml latex
all: $(BUILDDIR) ${TARGETS} all: $(BUILDDIR) ${TARGETS}
html: all
epub: all
xml: all
latex: $(IMGPDF) all
clean:
-rm -f $(IMGTGT) 2>/dev/null
$(BUILDDIR): $(BUILDDIR):
$(Q)mkdir -p $@ $(Q)mkdir -p $@
...@@ -58,4 +85,4 @@ $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exception ...@@ -58,4 +85,4 @@ $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exception
@$($(quiet)gen_rst) @$($(quiet)gen_rst)
cleandocs: cleandocs:
-rm ${TARGETS} -rm -f ${TARGETS}
Linux Media Subsystem Documentation Linux Media Subsystem Documentation
=================================== ===================================
.. Sphinx 1.4.x has a definition for DUrole that doesn't work on alltt blocks
.. raw:: latex
\renewcommand*{\DUrole}[2]{ #2 }
Contents: Contents:
.. toctree:: .. toctree::
......
...@@ -13,8 +13,8 @@ A typical media device hardware is shown at :ref:`typical_media_device`. ...@@ -13,8 +13,8 @@ A typical media device hardware is shown at :ref:`typical_media_device`.
.. _typical_media_device: .. _typical_media_device:
.. figure:: media_api_files/typical_media_device.* .. figure:: typical_media_device.*
:alt: typical_media_device.svg :alt: typical_media_device.pdf / typical_media_device.svg
:align: center :align: center
Typical Media Device Typical Media Device
......
This diff is collapsed.
...@@ -55,8 +55,8 @@ Overview ...@@ -55,8 +55,8 @@ Overview
.. _stb_components: .. _stb_components:
.. figure:: intro_files/dvbstb.* .. figure:: dvbstb.*
:alt: dvbstb.pdf / dvbstb.png :alt: dvbstb.pdf / dvbstb.svg
:align: center :align: center
Components of a DVB card/STB Components of a DVB card/STB
......
This diff is collapsed.
...@@ -53,8 +53,8 @@ Cropping Structures ...@@ -53,8 +53,8 @@ Cropping Structures
.. _crop-scale: .. _crop-scale:
.. figure:: crop_files/crop.* .. figure:: crop.png
:alt: crop.pdf / crop.gif :alt: crop.png
:align: center :align: center
Image Cropping, Insertion and Scaling Image Cropping, Insertion and Scaling
......
...@@ -221,8 +221,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does ...@@ -221,8 +221,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does
.. _vbi-hsync: .. _vbi-hsync:
.. figure:: dev-raw-vbi_files/vbi_hsync.* .. figure:: vbi_hsync.png
:alt: vbi_hsync.pdf / vbi_hsync.gif :alt: vbi_hsync.png
:align: center :align: center
**Figure 4.1. Line synchronization** **Figure 4.1. Line synchronization**
...@@ -230,8 +230,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does ...@@ -230,8 +230,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does
.. _vbi-525: .. _vbi-525:
.. figure:: dev-raw-vbi_files/vbi_525.* .. figure:: vbi_525.png
:alt: vbi_525.pdf / vbi_525.gif :alt: vbi_525.png
:align: center :align: center
**Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)** **Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)**
...@@ -240,8 +240,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does ...@@ -240,8 +240,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does
.. _vbi-625: .. _vbi-625:
.. figure:: dev-raw-vbi_files/vbi_625.* .. figure:: vbi_625.png
:alt: vbi_625.pdf / vbi_625.gif :alt: vbi_625.png
:align: center :align: center
**Figure 4.3. ITU-R 625 line numbering** **Figure 4.3. ITU-R 625 line numbering**
......
...@@ -99,8 +99,8 @@ the video sensor and the host image processing hardware. ...@@ -99,8 +99,8 @@ the video sensor and the host image processing hardware.
.. _pipeline-scaling: .. _pipeline-scaling:
.. figure:: dev-subdev_files/pipeline.* .. figure:: pipeline.png
:alt: pipeline.pdf / pipeline.png :alt: pipeline.png
:align: center :align: center
Image Format Negotiation on Pipelines Image Format Negotiation on Pipelines
...@@ -404,8 +404,8 @@ selection will refer to the sink pad format dimensions instead. ...@@ -404,8 +404,8 @@ selection will refer to the sink pad format dimensions instead.
.. _subdev-image-processing-crop: .. _subdev-image-processing-crop:
.. figure:: dev-subdev_files/subdev-image-processing-crop.* .. figure:: subdev-image-processing-crop.*
:alt: subdev-image-processing-crop.svg :alt: subdev-image-processing-crop.pdf / subdev-image-processing-crop.svg
:align: center :align: center
**Figure 4.5. Image processing in subdevs: simple crop example** **Figure 4.5. Image processing in subdevs: simple crop example**
...@@ -421,8 +421,8 @@ pad. ...@@ -421,8 +421,8 @@ pad.
.. _subdev-image-processing-scaling-multi-source: .. _subdev-image-processing-scaling-multi-source:
.. figure:: dev-subdev_files/subdev-image-processing-scaling-multi-source.* .. figure:: subdev-image-processing-scaling-multi-source.*
:alt: subdev-image-processing-scaling-multi-source.svg :alt: subdev-image-processing-scaling-multi-source.pdf / subdev-image-processing-scaling-multi-source.svg
:align: center :align: center
**Figure 4.6. Image processing in subdevs: scaling with multiple sources** **Figure 4.6. Image processing in subdevs: scaling with multiple sources**
...@@ -437,8 +437,8 @@ an area at location specified by the source crop rectangle from it. ...@@ -437,8 +437,8 @@ an area at location specified by the source crop rectangle from it.
.. _subdev-image-processing-full: .. _subdev-image-processing-full:
.. figure:: dev-subdev_files/subdev-image-processing-full.* .. figure:: subdev-image-processing-full.*
:alt: subdev-image-processing-full.svg :alt: subdev-image-processing-full.pdf / subdev-image-processing-full.svg
:align: center :align: center
**Figure 4.7. Image processing in subdevs: scaling and composition with multiple sinks and sources** **Figure 4.7. Image processing in subdevs: scaling and composition with multiple sinks and sources**
......
...@@ -141,8 +141,8 @@ enum v4l2_field ...@@ -141,8 +141,8 @@ enum v4l2_field
Field Order, Top Field First Transmitted Field Order, Top Field First Transmitted
======================================== ========================================
.. figure:: field-order_files/fieldseq_tb.* .. figure:: fieldseq_tb.png
:alt: fieldseq_tb.pdf / fieldseq_tb.gif :alt: fieldseq_tb.png
:align: center :align: center
...@@ -151,7 +151,7 @@ Field Order, Top Field First Transmitted ...@@ -151,7 +151,7 @@ Field Order, Top Field First Transmitted
Field Order, Bottom Field First Transmitted Field Order, Bottom Field First Transmitted
=========================================== ===========================================
.. figure:: field-order_files/fieldseq_bt.* .. figure:: fieldseq_bt.png
:alt: fieldseq_bt.pdf / fieldseq_bt.gif :alt: fieldseq_bt.png
:align: center :align: center
...@@ -33,7 +33,7 @@ Layout of macroblocks in memory is presented in the following figure. ...@@ -33,7 +33,7 @@ Layout of macroblocks in memory is presented in the following figure.
.. _nv12mt: .. _nv12mt:
.. figure:: pixfmt-nv12mt_files/nv12mt.* .. figure:: nv12mt.png
:alt: nv12mt.png :alt: nv12mt.png
:align: center :align: center
...@@ -50,7 +50,7 @@ interleaved. Height of the buffer is aligned to 32. ...@@ -50,7 +50,7 @@ interleaved. Height of the buffer is aligned to 32.
.. _nv12mt_ex: .. _nv12mt_ex:
.. figure:: pixfmt-nv12mt_files/nv12mt_example.* .. figure:: nv12mt_example.png
:alt: nv12mt_example.png :alt: nv12mt_example.png
:align: center :align: center
......
...@@ -7,7 +7,7 @@ Selection targets ...@@ -7,7 +7,7 @@ Selection targets
.. _sel-targets-capture: .. _sel-targets-capture:
.. figure:: selection-api-003_files/selection.* .. figure:: selection.png
:alt: selection.png :alt: selection.png
:align: center :align: center
......
...@@ -1514,23 +1514,28 @@ be named ``MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE``. ...@@ -1514,23 +1514,28 @@ be named ``MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE``.
.. _bayer-patterns: .. _bayer-patterns:
.. figure:: subdev-formats_files/bayer.* .. figure:: bayer.png
:alt: bayer.png :alt: bayer.png
:align: center :align: center
**Figure 4.8 Bayer Patterns** **Figure 4.8 Bayer Patterns**
The following table lists existing packed Bayer formats. The data The following table lists existing packed Bayer formats. The data
organization is given as an example for the first pixel only. organization is given as an example for the first pixel only.
.. HACK: ideally, we would be using adjustbox here. However, Sphinx
.. is a very bad behaviored guy: if the table has more than 30 cols,
.. it switches to long table, and there's no way to override it.
.. raw:: latex .. raw:: latex
\newline\newline\begin{adjustbox}{width=\columnwidth} \begingroup
\tiny
\setlength{\tabcolsep}{2pt}
.. tabularcolumns:: |p{7.6cm}|p{1.6cm}|p{0.7cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}| .. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.3cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
.. _v4l2-mbus-pixelcode-bayer: .. _v4l2-mbus-pixelcode-bayer:
...@@ -2314,7 +2319,7 @@ organization is given as an example for the first pixel only. ...@@ -2314,7 +2319,7 @@ organization is given as an example for the first pixel only.
.. raw:: latex .. raw:: latex
\end{adjustbox}\newline\newline \endgroup
Packed YUV Formats Packed YUV Formats
......
...@@ -129,8 +129,8 @@ Selection targets and flags are documented in ...@@ -129,8 +129,8 @@ Selection targets and flags are documented in
.. _sel-const-adjust: .. _sel-const-adjust:
.. figure:: vidioc-g-selection_files/constraints.* .. figure:: constraints.*
:alt: constraints.png :alt: constraints.pdf / constraints.svg
:align: center :align: center
Size adjustments with constraint flags. Size adjustments with constraint flags.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment