There are several broken references there, due to the conversion to
C domain. Fix them using this shell script and manually adjust what's
broken:

	# funcs is a file with the broken functions/references
	for i in $(cat funcs|sort|uniq|perl -ne 'print "$1\n" if (m/(\S+)$/)'); do
		i=${i//-/_}
		echo $i
		j=${i//_/-}
		for k in $(git grep -l "_$j:" Documentation/); do
			sed s,\_$j\:,"c\:type\:\: $i", <$k >a && mv a $k
		done
		for k in $(git grep -l "$j" Documentation/media/*.exceptions); do
			sed s,$j,":c\:type\:\`$i\`", <$k >a && mv a $k
		done
		for k in $(git grep -l "$j" Documentation/); do
			sed "s,:ref:\`$i <$j>\`,:c:type:\`$i\`," <$k >a && mv a $k
			sed "s,:ref:\`$j\`,:c:type:\`$i\`," <$k >a && mv a $k
			sed -E "s,:ref:\`(.*)<$j>\`,:c:type:\`\1<$i>\`," <$k >a && mv a $k
		done
		for k in $(git grep -l "<$j>" include/media); do
			sed -E "s,:ref:\`(.*)<$j>\`,enum \&$i," <$k >a && mv a $k
		done
	done
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Instead of using c:type:`struct foo <foo>`, use:
	struct c:type:`foo`

This patch was generated via this shell script:

	for i in `find Documentation/media -type f`; do perl -ne 'if (m/\:c\:type\:\`struct\s+(\S+)\s*\<(\S+)\>\`/) { $s=$1; $r=$2; if ($s eq $r) { s/\:c\:type\:\`struct\s+(\S+)\s*\<(\S+)\>\`/struct :c:type:`$2`/; s/struct\s+struct/struct/;  s/(struct\s+\:c\:type\:\`\S+\`)\s+structure/$1/;  }} print $_' <$i >a && mv a $i; done
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.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>

Name all ioctl references and make them match the ioctls that
are documented. That will improve the cross-reference index,
as it will have all ioctls and syscalls there.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

Now that we have an override for the c domain that will do
the right thing for the Kernel, stop abusing on the cpp
domain.
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>

LaTeX doesn't handle too well auto-width on tables, and ReST
markup requires an special tag to give it the needed hints.

As we're using A4 paper, we have 17cm of useful spaces. As
most media tables have widths, let's use it to generate the
needed via the following perl script:

my ($line_size, $table_header, $has_cols) = (17.5, 0, 0);
my $out;
my $header = "";
my @widths = ();
sub round { $_[0] > 0 ? int($_[0] + .5) : -int(-$_[0] + .5) }
while (<>) {
	if (!$table_header) {
		$has_cols = 1 if (m/..\s+tabularcolumns::/);
		if (m/..\s+flat-table::/) {
			$table_header = 1;
			$header = $_;
			next;
		}
		$out .= $_;
		next;
	}
	$header .= $_;
	@widths = split(/ /, $1) if (m/:widths:\s+(.*)/);
	if (m/^\n$/) {
		if (!$has_cols && @widths) {
			my ($tot, $t, $i) = (0, 0, 0);
			foreach my $v(@widths) { $tot += $v; };
			$out .= ".. tabularcolumns:: |";
			for ($i = 0; $i < scalar @widths - 1; $i++) {
				my $v = $widths[$i];
				my $w = round(10 * ($v * $line_size) / $tot) / 10;
				$out .= sprintf "p{%.1fcm}|", $w;
				$t += $w;
			}
			my $w = $line_size - $t;
			$out .= sprintf "p{%.1fcm}|\n\n", $w;
		}
		$out .= $header;
		$table_header = 0;
		$has_cols = 0;
		$header = "";
		@widths = ();
	}
}
print $out;
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

This patch touches on places where it shouldn't: image
files and code examples. Also, it doesn't fix all array
occurrences.

So, let's revert it.

This reverts commit ffbab694.

Those characters are used for citations. Better to escape, to
avoid them to be misinterpreted.
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>

On the syscall conversions, we used uppercase for the sections,
but this is too bold. So, convert them to Camel Case, as it
looks visually better.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The syscall pages are written to be used also as man-pages.

However, they don't match the format used by kernel-doc
generated pages from DocBook. Rewrite them to match it.

One side effect is that now all such pages at the book
will have the same format, reducing the format differences
between DVB and the other parts of the book.
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>

Using auto-generated links is dangerous, as there are multiple
definitions for syscalls (at least one on each book part).

So, reference them by their explicit reference.

I used this small script to help writing this patch:

for i in $(git grep -l "c:func:"); do perl -ne 's/\:c\:func:\`(open|close|read|poll|write|select|mmap|munmap|ioctl)\(\)`/:ref:`$1() <func-$1>`/; print $_' < $i >a && mv a $i; done
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>

On several places, instead of using references, the code was
using some other tag. Not sure if this was due to the conversion,
or if something were already wrong on the DocBook. In any case,
let's fix them.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

The c language parser checks if there are duplicated object
definitions. That causes lots of warnings like:
	WARNING: duplicate C object description of ioctl

Let's remove those by telling Sphinx that the language for
those objects are c++. The look of the descriptions will
be close, and the warnings will be gone.

Please notice that we had to keep a few of them as C, as
the c++ parser seems to be broken when it finds an enum.

Yet, this reduced from 219 warnings to 143, with is
a good thing.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

As VIDIOC_G_foo is the reference used for VIDIOC_S_foo and
VIDIOC_TRY_foo, we need to explicitly name the reference, as
otherwise, it will mention the three ioctls altogether, with
is not what we want.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>

There were lots of consts at the media docbook that should
be, instead, references. Convert the ones that can easily
be done by an automatic script.
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>