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

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

Documentation/Makefile.sphinx

+2 −1
Original line number Diff line number Diff line
@@ -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

+5 −1
Original line number Diff line number Diff line
@@ -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

0 → 100644
+1 −0
Original line number Diff line number Diff line 
*.pdf

Documentation/media/Makefile

+29 −2
Original line number Diff line number Diff line
@@ -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

+0 −5
Original line number Diff line number Diff line 
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::

CRA Git | Maintained and supported by SUSTech CRA and CCSE