The pipeline image was produced from some dot file that has
long missed. Create a pipeline.dot with the graph and convert
it to SVG. As we're planning to add future support for graphviz
graphics, also store the .dot file on the tree, as this will
make easier when we add such Sphinx extension.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

The PDF files that contain media images were actually generated
offline from their SVG or PNG source files.

Sphinx can handle PNG sources automatially. So, let's just
drop their PDF counterparts.

For SVG, however, Sphinx doesn't produce the right tags to
use the TexLive SVG support. Also, the SVG support is done via
shell execution, with is not nice.

So, while we don't have any support for SVG inside Sphinx
core or as an extension, move the logic to build them to Makefile,
producing the PDF images on runtime.

NOTE: due to the way Sphinx works, the PDF images should be
generated inside the Kernel source tree, as otherwise Sphinx
won't find it, not obeying what's specified by "O=" makefile
parameter.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Shorten the tables by removing row numbers in comments, allowing for
later insertion of rows with minimal diffs.

All changes have been generated by the following script.

import io
import re
import sys

def process_table(fname, data):
	if fname.endswith('hist-v4l2.rst'):
		data = re.sub(u'\n{1,2}\t( ?)  -( ?) ?', u'\n\t\\1 -\\2', data, flags = re.MULTILINE)
		data = re.sub(u'\n(\t|       )-  \.\. row [0-9]+\n\t  ?-( ?) ?', u'\\1* -\\2', data, flags = re.MULTILINE)
	else:
		data = re.sub(u'\n{1,2}       -( ?) ?', u'\n      -\\1', data, flags = re.MULTILINE)
		data = re.sub(u'(\n?)(\n\n    -  \.\. row 1\n)', u'\n\\2', data, flags = re.MULTILINE)
		data = re.sub(u'\n    -  \.\. row [0-9]+\n      -( ?) ?', u'    * -\\1', data, flags = re.MULTILINE)
		data = re.sub(u'\n    -  \.\. row [0-9]+\n       \.\. (_[A-Z0-9_`-]*:)', u'\n    -  .. \\1', data, flags = re.MULTILINE)
		data = re.sub(u'\n    -  \.\. (_[A-Z0-9_`-]*:)\n      -', u'    * .. \\1\n\n      -', data, flags = re.MULTILINE)
		data = re.sub(u'^       - ', u'      -', data, flags = re.MULTILINE)
		data = re.sub(u'^(\t{1,2})  ', u'\\1', data, flags = re.MULTILINE)

	return data

def process_file(fname, data):
	buf = io.StringIO(data)
	output = ''
	in_table = False
	table_separator = 0

	for line in buf.readlines():
		if line.find('.. flat-table::') != -1:
			in_table = True
			table = ''
		elif in_table and not re.match('^[\t\n]|(    )', line):
			in_table = False
			output += process_table(fname, table)

		if in_table:
			table += line
		else:
			output += line

	if in_table:
		in_table = False
		output += process_table(fname, table)

	return output

fname = sys.argv[1]

data = file(fname, 'rb').read().decode('utf-8')
data = process_file(fname, data)
file(fname, 'wb').write(data.encode('utf-8'))
Signed-off-by: NLaurent Pinchart <laurent.pinchart@ideasonboard.com>

instead of declaring the uAPI structs using usual refs, e. g.:
	.. _foo-struct:

Use the C domain way:
	.. c:type:: foo_struct

This way, the kAPI documentation can use cross-references to
point to the uAPI symbols.

That solves about ~100 undefined warnings like:
	WARNING: c:type reference target not found: foo_struct
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

There are several minor issues that are seen when building
PDF on interactive mode.

Fix them.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Sphinx is really pedantic with respect to the order where
table tags and references are created. Putting things at
the wrong order causes troubles.

The order that seems to work is:

	.. raw:: latex

	.. tabularcolumns::

	.. _foo_name:

	.. cssclass: longtable

	.. flat-table::

Reorder the tags to the above order, to avoid troubles, and
fix remaining warnings introduced by media recent patches.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The table there is too big and doesn't have format hints for
LaTeX output.

Fix it.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

There are several notes and warning mesages in the middle of
the media docbook. Use the ReST tags for that, as it makes
them visually better and hightlights them.

While here, modify a few ones to make them clearer.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The name of the subsystem is "media", and not "linux_tv". Also,
as we plan to add other stuff there in the future, let's
rename also the media uAPI book to media_uapi, to make it
clearer.

No functional changes.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The conversion from DocBook made somethings look ugly.
Improve them.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Let's remove bad whitespaces on the entire book.

That helps to avoid mixing whitespace removal with other
patches.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The conversion script added some comments at the end.
They point to the original DocBook files, with will be
removed after the manual fixes. So, they'll be pointing
to nowere. So, remove those comments.

They'll be forever stored at the Kernel tree. So, if
someone wants the references, it is just a matter of
looking at the backlog.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

All error codes should be const. Most are, but there are
lots of places where we forgot to add <constant> at the DocBook.

Fix those via this small script:
	for i in $(git grep -lE "\s+E[A-Z]+\b" Documentation/linux_tv/); do perl -ne 's,([^\`])\b(E[A-Z]+)\b,\1``\2``,g; print $_' <$i >a && mv a $i; done

As there are false positives, we needed to merge only the changes
that make sense, skipping the c blocks and skipping things like
EDID, EN, ETS that were also converted by the above code.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

There are lots of internal references in the form:
	:ref:`foo <foo>`

Simplify them to be just: :ref:`foo`.

Patch generated via this small script:

for j in $(find . -name '*'); do echo $j; perl -ne 'if (m/\`(\S+)\s*\<(\S+)\>\`/) { if (!($1=~'http') && $1 eq $2) { s,\s*\<(\S+)\>,,; } } print $_' <$j >a && mv a $j; done
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Due to a limitation at the DocBook language, the references
were using lowercase and slashes, instead of the name of the
ioctls. On ReST, make them identical. This will hopefully
help to cleanup the code a little bit.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

This is the restructuredText (reST) migration of the ``media``
DocBook-XML set from the linux_tv project.
Signed-off-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>