Commit Graph

24 Commits

Author SHA1 Message Date
Mauro Carvalho Chehab 82559ac027 media: add SPDX header to media uAPI files
All those files are under GFDL 1.1 or later, with no invariant sections.
Tag them as such.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2018-12-05 10:39:18 -05:00
Mauro Carvalho Chehab 18e6830a63 media: remove text encoding from rst files
This is not needed there. Also, the same UTF-8 encoding should
be used on all documents.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
2018-12-05 10:37:18 -05:00
Mauro Carvalho Chehab 4d6436962a media: vidioc-g-tuner.rst: Fix table number of cols
The Tuner Audio Matrix table is broken: the first row has 7
columns instead of 6, causing it to be parsed wrong and displayed
very badly on PDF output.

Fix it and adjust the table to look nice at PDF output

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-09-05 06:24:59 -04:00
Mauro Carvalho Chehab 1473c75e9a media: v4l uAPI: add descriptions for arguments to all ioctls
Several ioctls are missing descriptions for the third argument
of the ioctl() command. They should have a description, as
otherwise the output won't be ok, and will sound like something
is missing.

So, add them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-09-05 06:24:28 -04:00
Mauro Carvalho Chehab 70b074df4e media: fix pdf build with Spinx 1.6
Sphinx 1.6 generates some LaTeX code before each table,
starting its own environment before calling tabulary,
apparently to improve table layout.

The problem is that such environment is incompatible with
adjustbox. While, in thesis, it should be possible to override
it or to redefine tabulary, I was unable to produce such patch.

Also, that would likely break on some future Sphinx version.

So, instead, let's just change the font size on bigger tables,
in order for them to fit into the page size. That is not as
good as adjustbox, and require some manual work, but it should
be less sensitive to Sphinx changes.

While here, adjust a few other tables whose text is exceeding
the cell boundaries.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2017-08-26 20:13:22 -04:00
Masanari Iida 84512f3e1c [media] v4l: doc: Fix typo in vidioc-g-tuner.rst
This patch fix spelling typos found in vidioc-g-tuner.rst

Signed-off-by: Masanari Iida <standby24x7@gmail.com>
Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-11-16 13:22:02 -02:00
Laurent Pinchart c2b66cafdf [media] v4l: doc: Remove row numbers from tables
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: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2016-09-22 07:03:14 -03:00
Laurent Pinchart c19584882a [media] v4l: doc: Prepare for table reorganization
Fix a few indentation issues to enable automated table reorganization
by a regex-based script.

Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-22 06:50:03 -03:00
Mauro Carvalho Chehab 56683d7dea [media] docs-rst: fix cross-references for videodev2.h
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-09 09:57:23 -03:00
Mauro Carvalho Chehab fc78c7c7a1 [media] docs-rst: simplify c:type: cross references
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-09 09:54:54 -03:00
Mauro Carvalho Chehab e8be7e97e6 [media] docs-rst: convert uAPI structs to C domain
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-09-09 09:34:01 -03:00
Mauro Carvalho Chehab 41d804653e [media] docs-rst: Convert V4L2 uAPI to use C function references
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-08-22 21:23:27 -03:00
Mauro Carvalho Chehab 1b81f010bf [media] docs-next: stop abusing on the cpp domain
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-08-22 21:23:00 -03:00
Mauro Carvalho Chehab 8c978c0846 [media] docs-rst: fix some LaTeX errors when in interactive mode
There are several minor issues that are seen when building
PDF on interactive mode.

Fix them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-08-22 10:35:47 -03:00
Mauro Carvalho Chehab fa92b04d98 [media] docs-rst: fix warnings introduced by LaTeX patchset
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-08-22 10:31:51 -03:00
Mauro Carvalho Chehab 11d7512bfe [media] vidioc-g-tuner.rst: Fix tables to fit at LaTeX output
Several tables are missing column definitions and/or are too big
to fit into the page. Adjust them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-08-22 10:23:30 -03:00
Mauro Carvalho Chehab e19c1779fb [media] vidioc-g-tuner.rst: improve documentation for tuner type
The tuner type table misses descriptions for each type. While
most of stuff are obvious, the two SDR definitions aren't.

So, add descriptions to all of them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-08-22 10:23:03 -03:00
Mauro Carvalho Chehab 5bd4bb7817 [media] docs-rst: add tabularcolumns to all tables
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-08-22 10:07:12 -03:00
Mauro Carvalho Chehab b6b6e67824 [media] docs-rst: better use the .. note:: tag
Change multi-line note tags to be more symetric, e. g. not starting
the text together witht the tag.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-08-22 10:02:29 -03:00
Mauro Carvalho Chehab 8968da9b86 Revert "[media] docs-rst: escape [] characters"
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 ffbab694ed.
2016-07-13 08:43:30 -03:00
Mauro Carvalho Chehab ffbab694ed [media] docs-rst: escape [] characters
Those characters are used for citations. Better to escape, to
avoid them to be misinterpreted.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-12 15:20:11 -03:00
Mauro Carvalho Chehab 4855307b81 [media] doc-rst: use the right markup for footnotes
According with ReST spec, footnotes should be like:
[#name], and not [name]. So, change them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-12 15:15:23 -03:00
Mauro Carvalho Chehab 706f8a9975 [media] doc-rst: improve display of notes and warnings
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-10 12:06:28 -03:00
Mauro Carvalho Chehab 60c2820d0f doc_rst: rename the media Sphinx suff to Documentation/media
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: Mauro Carvalho Chehab <mchehab@s-opensource.com>
2016-07-08 11:59:40 -03:00