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]

Documentation/Makefile.sphinx

@@ -54,7 +54,7 @@ loop_cmd = $(echo-cmd) $(cmd_$(1))
 #    e.g. "media" for the linux-tv book-set at ./Documentation/media
 
 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)) \
 	$(SPHINXBUILD) \
 	-b $2 \
@@ -98,6 +98,7 @@ installmandocs:
 
 cleandocs:
 	$(Q)rm -rf $(BUILDDIR)
+	$(Q)$(MAKE) -C Documentation/media clean
 
 endif # HAVE_SPHINX
 

Documentation/conf.py

@@ -37,7 +37,7 @@ from load_config import loadConfig
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain']
 
 # 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")
 else:
     extensions.append("sphinx.ext.pngmath")
@@ -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
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).

Documentation/media/.gitignore

+*.pdf

Documentation/media/Makefile

@@ -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))
 
-.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}
+html: all
+epub: all
+xml: all
+latex: $(IMGPDF) all
+
+clean:
+	-rm -f $(IMGTGT) 2>/dev/null
 
 $(BUILDDIR):
 	$(Q)mkdir -p $@
@@ -58,4 +85,4 @@ $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exception
 	@$($(quiet)gen_rst)
 
 cleandocs:
-	-rm ${TARGETS}
+	-rm -f ${TARGETS}

Documentation/media/index.rst

 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:
 
 .. toctree::

Documentation/media/intro.rst

@@ -13,8 +13,8 @@ A typical media device hardware is shown at :ref:`typical_media_device`.
 
 .. _typical_media_device:
 
-.. figure::  media_api_files/typical_media_device.*
-    :alt:    typical_media_device.svg
+.. figure::  typical_media_device.*
+    :alt:    typical_media_device.pdf / typical_media_device.svg
     :align:  center
 
     Typical Media Device

Documentation/media/uapi/dvb/intro.rst

@@ -55,8 +55,8 @@ Overview
 
 .. _stb_components:
 
-.. figure::  intro_files/dvbstb.*
-    :alt:    dvbstb.pdf / dvbstb.png
+.. figure::  dvbstb.*
+    :alt:    dvbstb.pdf / dvbstb.svg
     :align:  center
 
     Components of a DVB card/STB

Documentation/media/uapi/v4l/constraints.svg

+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   version="1.2"
+   width="249.00998mm"
+   height="143.00999mm"
+   viewBox="0 0 24900.998 14300.999"
+   preserveAspectRatio="xMidYMid"
+   xml:space="preserve"
+   id="svg2"
+   inkscape:version="0.91 r13725"
+   sodipodi:docname="constraints.svg"
+   style="fill-rule:evenodd;stroke-width:28.22200012;stroke-linejoin:round"><metadata
+     id="metadata325"><rdf:RDF><cc:Work
+         rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" /><dc:title /></cc:Work></rdf:RDF></metadata><sodipodi:namedview
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1"
+     objecttolerance="10"
+     gridtolerance="10"
+     guidetolerance="10"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:window-width="1920"
+     inkscape:window-height="997"
+     id="namedview323"
+     showgrid="false"
+     inkscape:zoom="1.0818519"
+     inkscape:cx="270.29272"
+     inkscape:cy="249.83854"
+     inkscape:window-x="1920"
+     inkscape:window-y="30"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="svg2"
+     fit-margin-top="0"
+     fit-margin-left="0"
+     fit-margin-right="0"
+     fit-margin-bottom="0" /><defs
+     class="ClipPathGroup"
+     id="defs4"><marker
+       inkscape:isstock="true"
+       style="overflow:visible"
+       id="marker6261"
+       refX="0"
+       refY="0"
+       orient="auto"
+       inkscape:stockid="Arrow1Mend"><path
+         transform="matrix(-0.4,0,0,-0.4,-4,0)"
+         style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1pt;stroke-opacity:1"
+         d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z"
+         id="path6263"
+         inkscape:connector-curvature="0" /></marker><marker
+       inkscape:stockid="Arrow1Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker6125"
+       style="overflow:visible"
+       inkscape:isstock="true"
+       inkscape:collect="always"><path
+         id="path6127"
+         d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z"
+         style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1pt;stroke-opacity:1"
+         transform="matrix(-0.4,0,0,-0.4,-4,0)"
+         inkscape:connector-curvature="0" /></marker><marker
+       inkscape:isstock="true"
+       style="overflow:visible"
+       id="marker6001"
+       refX="0"
+       refY="0"
+       orient="auto"
+       inkscape:stockid="Arrow1Mend"
+       inkscape:collect="always"><path
+         transform="matrix(-0.4,0,0,-0.4,-4,0)"
+         style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1pt;stroke-opacity:1"
+         d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z"
+         id="path6003"
+         inkscape:connector-curvature="0" /></marker><marker
+       inkscape:stockid="Arrow1Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker5693"
+       style="overflow:visible"
+       inkscape:isstock="true"
+       inkscape:collect="always"><path
+         id="path5695"
+         d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z"
+         style="fill:#ff0000;fill-opacity:1;fill-rule:evenodd;stroke:#ff0000;stroke-width:1pt;stroke-opacity:1"
+         transform="matrix(-0.4,0,0,-0.4,-4,0)"
+         inkscape:connector-curvature="0" /></marker><marker
+       inkscape:isstock="true"
+       style="overflow:visible"
+       id="marker5575"
+       refX="0"
+       refY="0"
+       orient="auto"
+       inkscape:stockid="Arrow1Mend"
+       inkscape:collect="always"><path
+         transform="matrix(-0.4,0,0,-0.4,-4,0)"
+         style="fill:#000080;fill-opacity:1;fill-rule:evenodd;stroke:#000080;stroke-width:1pt;stroke-opacity:1"
+         d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z"
+         id="path5577"
+         inkscape:connector-curvature="0" /></marker><marker
+       inkscape:stockid="Arrow1Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker5469"
+       style="overflow:visible"
+       inkscape:isstock="true"
+       inkscape:collect="always"><path
+         id="path5471"
+         d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z"
+         style="fill:#000080;fill-opacity:1;fill-rule:evenodd;stroke:#000080;stroke-width:1pt;stroke-opacity:1"
+         transform="matrix(-0.4,0,0,-0.4,-4,0)"
+         inkscape:connector-curvature="0" /></marker><marker
+       inkscape:stockid="Arrow1Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="marker5259"
+       style="overflow:visible"
+       inkscape:isstock="true"><path
+         id="path5261"
+         d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z"
+         style="fill:#000080;fill-opacity:1;fill-rule:evenodd;stroke:#000080;stroke-width:1pt;stroke-opacity:1"
+         transform="matrix(-0.4,0,0,-0.4,-4,0)"
+         inkscape:connector-curvature="0" /></marker><marker
+       inkscape:stockid="Arrow2Mend"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow2Mend"
+       style="overflow:visible"
+       inkscape:isstock="true"><path
+         id="path4241"
+         style="fill:#000080;fill-opacity:1;fill-rule:evenodd;stroke:#000080;stroke-width:0.625;stroke-linejoin:round;stroke-opacity:1"
+         d="M 8.7185878,4.0337352 -2.2072895,0.01601326 8.7185884,-4.0017078 c -1.7454984,2.3720609 -1.7354408,5.6174519 -6e-7,8.035443 z"
+         transform="scale(-0.6,-0.6)"
+         inkscape:connector-curvature="0" /></marker></defs><defs
+     id="defs9" /><defs
+     id="defs100" /><defs
+     id="defs123" /><defs
+     class="TextShapeIndex"
+     id="defs134" /><defs
+     class="EmbeddedBulletChars"
+     id="defs138" /><defs
+     class="TextEmbeddedBitmaps"
+     id="defs167" /><g
+     class="com.sun.star.drawing.CustomShape"
+     id="g204"
+     transform="translate(-1350,-3250)"><g
+       id="id6"><rect
+         class="BoundingBox"
+         x="1350"
+         y="3250"
+         width="24901"
+         height="14301"
+         id="rect207"
+         style="fill:none;stroke:none" /><path
+         d="m 13800,17500 -12400,0 0,-14200 24800,0 0,14200 -12400,0 z"
+         id="path209"
+         inkscape:connector-curvature="0"
+         style="fill:#ffffff;stroke:none" /><path
+         d="m 13800,17500 -12400,0 0,-14200 24800,0 0,14200 -12400,0 z"
+         id="path211"
+         inkscape:connector-curvature="0"
+         style="fill:none;stroke:#ff0000;stroke-width:100;stroke-linejoin:round" /><text
+         class="TextShape"
+         id="text213"><tspan
+           class="TextParagraph"
+           font-size="846px"
+           font-weight="400"
+           id="tspan215"
+           style="font-weight:400;font-size:846px;font-family:'Liberation Sans', sans-serif"><tspan
+             class="TextPosition"
+             x="1652"
+             y="17093"
+             id="tspan217"><tspan
+               id="tspan219"
+               style="fill:#ff0000;stroke:none" /><tspan
+               id="tspan221"
+               style="fill:#ff0000;stroke:none">V4L2_SEL_FLAG_GE</tspan></tspan></tspan></text>
+</g></g><rect
+     class="BoundingBox"
+     x="3000"
+     y="2200"
+     width="18101"
+     height="10101"
+     id="rect226"
+     style="fill:none;stroke:none" /><path
+     d="m 12050,12250 -9000,0 0,-10000 18000,0 0,10000 -9000,0 z"
+     id="path228"
+     inkscape:connector-curvature="0"
+     style="fill:#ffffff;stroke:none" /><path
+     d="m 12050,12250 -9000,0 0,-10000 18000,0 0,10000 -9000,0 z"
+     id="path230"
+     inkscape:connector-curvature="0"
+     style="fill:none;stroke:#000000;stroke-width:100;stroke-linejoin:round" /><text
+     class="TextShape"
+     id="text232"
+     x="-1350"
+     y="-3250"><tspan
+       class="TextParagraph"
+       font-size="987px"
+       font-weight="400"
+       id="tspan234"
+       style="font-weight:400;font-size:987px;font-family:'Liberation Sans', sans-serif"><tspan
+         class="TextPosition"
+         x="3227"
+         y="11503"
+         id="tspan236"><tspan
+           id="tspan238"
+           style="fill:#000000;stroke:none" /><tspan
+           id="tspan240"
+           style="fill:#000000;stroke:none">ORIGINAL</tspan></tspan></tspan></text>
+<g
+     class="com.sun.star.drawing.CustomShape"
+     id="g242"
+     transform="translate(-1350,-3250)"><g
+       id="id8"><rect
+         class="BoundingBox"
+         x="7050"
+         y="7950"
+         width="7901"
+         height="5501"
+         id="rect245"
+         style="fill:none;stroke:none" /><path
+         d="m 11000,13400 -3900,0 0,-5400 7800,0 0,5400 -3900,0 z"
+         id="path247"
+         inkscape:connector-curvature="0"
+         style="fill:#ffffff;stroke:none" /><path
+         d="m 11000,13400 -3900,0 0,-5400 7800,0 0,5400 -3900,0 z"
+         id="path249"
+         inkscape:connector-curvature="0"
+         style="fill:none;stroke:#3465a4;stroke-width:100;stroke-linejoin:round" /><text
+         class="TextShape"
+         id="text251"><tspan
+           class="TextParagraph"
+           font-size="776px"
+           font-weight="400"
+           id="tspan253"
+           style="font-weight:400;font-size:776px;font-family:'Liberation Sans', sans-serif"><tspan
+             class="TextPosition"
+             x="7228"
+             y="10969"
+             id="tspan255"><tspan
+               id="tspan257"
+               style="fill:#000080;stroke:none">V4L2_SEL_FLAG_LE</tspan></tspan></tspan></text>
+</g></g><rect
+     class="BoundingBox"
+     x="13700"
+     y="7100"
+     width="7101"
+     height="101"
+     id="rect262"
+     style="fill:none;stroke:none" /><path
+     d="m 20750,7150 -7000,0"
+     id="path264"
+     inkscape:connector-curvature="0"
+     style="fill:none;stroke:#000080;stroke-width:99.99134064;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow2Mend)" /><rect
+     class="BoundingBox"
+     x="3400"
+     y="7100"
+     width="2101"
+     height="101"
+     id="rect269"
+     style="fill:none;stroke:none" /><path
+     d="m 3450,7150 2000,0"
+     id="path271"
+     inkscape:connector-curvature="0"
+     style="fill:none;stroke:#000080;stroke-width:100;stroke-linejoin:round;marker-end:url(#marker5575)" /><rect
+     class="BoundingBox"
+     x="9800"
+     y="2900"
+     width="101"
+     height="1501"
+     id="rect276"
+     style="fill:none;stroke:none" /><path
+     d="m 9850,2950 0,1400"
+     id="path278"
+     inkscape:connector-curvature="0"
+     style="fill:none;stroke:#000080;stroke-width:100;stroke-linejoin:round;marker-end:url(#marker5259)" /><rect
+     class="BoundingBox"
+     x="9600"
+     y="10600"
+     width="101"
+     height="1301"
+     id="rect283"
+     style="fill:none;stroke:none" /><path
+     d="m 9650,11850 0,-1200"
+     id="path285"
+     inkscape:connector-curvature="0"
+     style="fill:none;stroke:#000080;stroke-width:100;stroke-linejoin:round;marker-end:url(#marker5469)" /><rect
+     class="BoundingBox"
+     x="450"
+     y="6850"
+     width="2051"
+     height="601"
+     id="rect290"
+     style="fill:none;stroke:none" /><path
+     d="m 2450,7150 -2000.8696,0"
+     id="path292"
+     inkscape:connector-curvature="0"
+     style="fill:none;stroke:#ff0000;stroke-width:132.48202515;stroke-linejoin:round;marker-end:url(#marker6125)" /><rect
+     class="BoundingBox"
+     x="21600"
+     y="6750"
+     width="2651"
+     height="601"
+     id="rect299"
+     style="fill:none;stroke:none" /><path
+     d="m 21650,7050 2522.609,0"
+     id="path301"
+     inkscape:connector-curvature="0"
+     style="fill:none;stroke:#ff0000;stroke-width:120.40660858;stroke-linejoin:round;marker-end:url(#marker6001)" /><rect
+     class="BoundingBox"
+     x="9550"
+     y="550"
+     width="601"
+     height="1451"
+     id="rect308"
+     style="fill:none;stroke:none" /><path
+     d="m 9836.957,1950 0,-1453.0435"
+     id="path310"
+     inkscape:connector-curvature="0"
+     style="fill:none;stroke:#ff0000;stroke-width:164.03721619;stroke-linejoin:round;marker-end:url(#marker6261)" /><rect
+     class="BoundingBox"
+     x="9350"
+     y="12500"
+     width="601"
+     height="1451"
+     id="rect317"
+     style="fill:none;stroke:none" /><path
+     d="m 9650,12550 0,1505.217"
+     id="path319"
+     inkscape:connector-curvature="0"
+     style="fill:none;stroke:#ff0000;stroke-width:166.95626831;stroke-linejoin:round;marker-end:url(#marker5693)" /></svg>
\ No newline at end of file

Documentation/media/uapi/v4l/crop.rst

@@ -53,8 +53,8 @@ Cropping Structures
 
 .. _crop-scale:
 
-.. figure::  crop_files/crop.*
-    :alt:    crop.pdf / crop.gif
+.. figure::  crop.png
+    :alt:    crop.png
     :align:  center
 
     Image Cropping, Insertion and Scaling

Documentation/media/uapi/v4l/dev-raw-vbi.rst

@@ -221,8 +221,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does
 
 .. _vbi-hsync:
 
-.. figure::  dev-raw-vbi_files/vbi_hsync.*
-    :alt:    vbi_hsync.pdf / vbi_hsync.gif
+.. figure::  vbi_hsync.png
+    :alt:    vbi_hsync.png
     :align:  center
 
     **Figure 4.1. Line synchronization**
@@ -230,8 +230,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT <VIDIOC_G_FMT>` does
 
 .. _vbi-525:
 
-.. figure::  dev-raw-vbi_files/vbi_525.*
-    :alt:    vbi_525.pdf / vbi_525.gif
+.. figure::  vbi_525.png
+    :alt:    vbi_525.png
     :align:  center
 
     **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
 
 .. _vbi-625:
 
-.. figure::  dev-raw-vbi_files/vbi_625.*
-    :alt:    vbi_625.pdf / vbi_625.gif
+.. figure::  vbi_625.png
+    :alt:    vbi_625.png
     :align:  center
 
     **Figure 4.3. ITU-R 625 line numbering**