doc-dst: parse-headers: highlight deprecated comments

When something is deprecated, highlight it, as we want it
to be clearer to the reader.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: parse-headers: improve delimiters to detect symbols

As we had to escape the symbols for the ReST markup to not do
the wrong thing, the logic to discover start/end of strings
are not trivial. Improve the end delimiter detection, in order
to highlight more occurrences of the strings.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: auto-build the frontend.h.rst

This file is auto-generated with DocBook, from the uapi header.

Do the same with Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: add parse-headers.pl script

This script parses a header file and converts it into a
parsed-literal block, creating references for ioctls,
defines, typedefs, enums and structs.

It also allow an external file to modify the rules, in
order to fix the expressions.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv/index: Rename the book name

There's no need for all caps at its name. As the book title is
now showing at the top of each page, let's use Camel Case, to
make it less bold.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: v4l2: Rename the V4L2 API title

The V4L2 is the only part of the doc that has the word "Specification"
and mentions its version on the title.

Having the version there was important in the past, while we were
getting rid of V4L version 1. But, as v1 is long gone, all it lasts
is history (with is, btw, covered on the spec). So, no need to keep
the version on its title.

So, rename it, to be more generic and look like the remaining
of the document.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: Rename the title of the Digital TV section

The Digital TV section is ackward for two reasons:

  1) it is the only one with everything in upper case;
  2) its name is associated with the European digital TV standard.

Rename the part name, and add a notice that it refers to what's
known as "DVB API".

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: remote_controllers: fix conversion issues

Make it look like V4L, DVB and MC docbooks initial page.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: gen-errors: Improve table layout

Add a :widths: at the flat-table, to make it to look nicer.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: media-ioc-enum-entities: better format the table

Add a :widths: at the flat-table, to improve the visual.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: media-ioc-g-topology: Fix tables

The tables were not properly converted. It looked a little
ackward already at DocBook, but the conversion made it worse.

Fix them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: mediactl: fix some wrong cross references

Those cross references should point to media control syscalls,
and not to V4L ones.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: media-controller-model: fix a typo

Remove a 'm' at the end of the last phrase.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: media-controller.rst: add missing copy symbol

Just like V4L and DVB parts, add the copyright symbol.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: media-controller: missing credits

When I wrote the MC next gen patches, I also improved the media
controller documentation and added documentation for
MEDIA_IOC_G_TOPOLOGY, but I forgot to add the credits on that
time.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: media-controller: fix conversion issues

Make it look just like v4l and DVB parts.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: intro: remove obsolete headers

The video, audio and OSD APIs are obsolete. V4L2 should be
used instead. So, remove them from this intro item.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: dvb/intro: Better show the needed include blocks

The include blocks were not properly displayed. Fix it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: fix intro_files/dvbstb.png image

The png image was not base64 decoded correctly.
Fix it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: dvbapi: Fix conversion issues

The conversion of this file didn't happen too well. We want
the items numbered, and format it just like what we did with
part 1 of the document.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: dev-overlay: fix the last warning

Fixes this warning:

Documentation/linux_tv/media/v4l/dev-overlay.rst:247: WARNING: Title underline too short.

struct v4l2_clip [4]_
----------------

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: dmabuf: Fix the cross-reference

Fixes this warning:
    Documentation/linux_tv/media/v4l/dmabuf.rst:150: WARNING: undefined label: vidioc_dqbuf (if the link has no caption the label must precede a section header)

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: use :cpp:function:: on all syscalls

Now that we have one syscall per page, using :cpp:function::
cleans up almost all warnings, with is a great thing.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: don't use uppercases for syscall sections

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: customize RTD theme, captions & inline literal

The layout of (table) captions in the RTD theme is a bit ugly and the
bordered, red colored of inline literals is a bit to gaudy. The
requirements has been discussed in the ML [1].

captions:

  - captions should have 100% (not 85%) font size
  - hide the permalink symbol as long as link is not hovered

inline literal:

  - drop the borderbox and red color

[1] http://article.gmane.org/gmane.linux.drivers.video-input-infrastructure/101099

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>

doc-rst: customize RTD theme, table & full width

The default table layout of the RTD theme does not fit for vast tables,
like the ones we have in the linux_tv project. This has been discussed
on the ML [1].

The RTD theme is a two column layout, with a navigation column on the
left and a content column on the right:

content column

 RTD theme's default is 800px as max width for the content, but we have
 tables with tons of columns, which need the full width of the
 view-port (BTW: *full width* is what DocBook's HTML is).

table

   - sequences of whitespace should collapse into a single whitespace.
   - make the overflow auto (scrollbar if needed)
   - align caption "left" ("center" is unsuitable on vast tables)

[1] http://article.gmane.org/gmane.linux.kernel/2216509

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>

doc-rst: remove Documentation/linux_tv/conf.py file

This file is actually not used to build the media uAPI docbook.
So, remove it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: boilerplate HTML theme customization

Implements the minimal boilerplate for Sphinx HTML theme customization.

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: dvb: put return value at the end

On some syscall descriptions, the tables are described after
the return value. Do that inside descriptions.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: dvb: use lowercase for filenames

There are some ioctls in upper case. This is not the standard.
Put them on lowercase, to match what's done with other ioctls.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: reformat all syscall pages

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: split DVB function call documentation

Just like V4L, split the DVB function calls into one file per
system call. This is a requirement for the man pages creator
on Sphinx to work, and makes the document easier to maintain.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: libv4l-introduction: improve format

Fix some cross-references and improve the layout of this
page.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: subdev-formats: Improve figure caption

Add a numbering for the figure.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: dev-subdev: fix some format issues

The conversion from DocBook made somethings look ugly.
Improve them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: dev-sliced-vbi: convert table captions into headers

Sphinx doesn't format nice table captions, nor auto-numberate
them. So, convert tables into chapters.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: dev-raw-vbi fix conversion issues

There are several things that didn't convert well. Fix them,
in order to improve the layout of the formatted document.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: Use references for read()/write()

Use cross-references for read()/write() on a few places
where they weren't used.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: dev-codec: Fix a reference for _STREAMON

The referenced ioctl there is only VIDIOC_STREAMON, so we
should override the name, to avoid it to also show _STREAMOFF.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: dev-osd: Fix some issues due to conversion

The conversion to ReST broke a minor things. Fix them.

While here, also make EBUSY constant, just like on other places.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: dev-overlay: Fix conversion issues

There were several conversion issues on this file, causing it
to be badly formatted. Fix them, in order to match the
design used on DocBook.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: buffer: numerate tables and figures

Sphinx actually doesn't numerate tables nor figures. So,
let's add a subtitle before each table. That makes them
"numerated".

While here, fix the git binary that got corrupted.
Let's hope this will work, as the reason why we had
to encode them were to prevent some issues on commiting
those gif files on git.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: buffer: numerate tables

Sphinx actually  doesn't numerate tables. So, let's add a
subtitle before each table. That makes them numerated.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: dmabuf: Add ioctl cross references

There are lots of ioctls mentioned there that aren't cross-referenced.

Convert the const to cross references. That makes it visually
better, and improves navigation along the document.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: dmabuf: re-add the missing captions

The conversion from DocBook removed them. Re-add.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: remove whitespaces

Let's remove bad whitespaces on the entire book.

That helps to avoid mixing whitespace removal with other
patches.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: userp: Add ioctl cross references

There are lots of ioctls mentioned there that aren't cross-referenced.

Convert the const to cross references. That makes it visually
better, and improves navigation along the document.

While here, remove bad whitespaces.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: userp: re-add the missing captions

The conversion from DocBook removed them. Re-add.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: mmap: Add ioctl cross references

There are lots of ioctls mentioned there that aren't cross-referenced.

Convert the const to cross references. That makes it visually
better, and improves navigation along the document.

While here, remove bad whitespaces.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: mmap: re-add the missing captions

The conversion from DocBook removed them. Re-add.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: pixfmt-nv16m: remove an empty column

The conversion added an empty column (probably, it was used on
DocBook just to increase spacing.

Remove it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: v4l/pixfmt: re-join a broken paragraph

Originally, at the DocBook, the "Byte Order" were a single
paragraph with the string that follows it. The conversion
broke it, and, sometimes, it added an extra dot.

Fix them altogheter at pixfmt-*.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: pixfmt-nv16m: remove an empty column

The conversion added an empty column (probably, it was used on
DocBook just to increase spacing.

It also added an extra line on one of the texts, breaking
the original paragraph into two ones.

Remove them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: Fix a warning at lirc_dev_intro

Documentation/linux_tv/media/rc/lirc_dev_intro:17: WARNING: Inline substitution_reference start-string without end-string.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: promote generic documents to the parent dir

The generic error codes and licensing sections are general to the
entire media book. They should not be inside the v4l dir. So,
promote them to the parent directory.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: move MC stuff to a separate dir

When we wrote the media controller's section, we re-used the
V4L, just because we were lazy to create a brand new DocBook.

Yet, it is a little ackward to have it mixed with V4L. So,
move it to its own directory, in order to have it better
organized.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: move RC stuff to a separate dir

When we wrote the remote controller's section, we re-used the
V4L, just because we were lazy to create a brand new DocBook.

Yet, it is a little ackward to have it mixed with V4L. So,
move it to its own directory, in order to have it better
organized.

No functional changes.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: avoid using c:func::

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: fix remaining lack of escapes

Add escape before asterisk to fix those warnings:

Documentation/linux_tv/media/dvb/FE_GET_EVENT:47: WARNING: Inline emphasis start-string without end-string.
Documentation/linux_tv/media/v4l/media-ioc-enum-links:78: WARNING: Inline emphasis start-string without end-string.
Documentation/linux_tv/media/v4l/media-ioc-enum-links:87: WARNING: Inline emphasis start-string without end-string.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: FE_DISHNETWORK_SEND_LEGACY_CMD: improve man-like format

Parsing this file were causing lots of warnings with sphinx,
due to the c function prototypes.

Fix that by prepending them with .. c:function::

While here, use the same way we document man-like pages,
at the V4L side of the book and add escapes to asterisks.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: FE_GET_EVENT: improve man-like format

Parsing this file were causing lots of warnings with sphinx,
due to the c function prototypes.

Fix that by prepending them with .. c:function::

While here, use the same way we document man-like pages,
at the V4L side of the book and add escapes to asterisks.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: FE_GET_FRONTEND: improve man-like format

Parsing this file were causing lots of warnings with sphinx,
due to the c function prototypes.

Fix that by prepending them with .. c:function::

While here, use the same way we document man-like pages,
at the V4L side of the book and add escapes to asterisks.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: FE_READ_BER: improve man-like format

Parsing this file were causing lots of warnings with sphinx,
due to the c function prototypes.

Fix that by prepending them with .. c:function::

While here, use the same way we document man-like pages,
at the V4L side of the book and add escapes to asterisks.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: FE_READ_SIGNAL_STRENGTH: improve man-like format

Parsing this file were causing lots of warnings with sphinx,
due to the c function prototypes.

Fix that by prepending them with .. c:function::

While here, use the same way we document man-like pages,
at the V4L side of the book and add escapes to asterisks.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: FE_READ_SNR: improve man-like format

Parsing this file were causing lots of warnings with sphinx,
due to the c function prototypes.

Fix that by prepending them with .. c:function::

While here, use the same way we document man-like pages,
at the V4L side of the book and add escapes to asterisks.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: FE_READ_UNCORRECTED_BLOCKS: improve man-like format

Parsing this file were causing lots of warnings with sphinx,
due to the c function prototypes.

Fix that by prepending them with .. c:function::

While here, use the same way we document man-like pages,
at the V4L side of the book and add escapes to asterisks.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: FE_SET_FRONTEND: improve man-like format

Parsing this file were causing lots of warnings with sphinx,
due to the c function prototypes.

Fix that by prepending them with .. c:function::

While here, use the same way we document man-like pages,
at the V4L side of the book and add escapes to asterisks.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: audio_function_calls: improve man-like format

Parsing this file were causing lots of warnings with sphinx,
due to the c function prototypes.

Fix that by prepending them with .. cpp:function::

While here, use the same way we document man-like pages,
at the V4L side of the book and add escapes to asterisks.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: ca_function_calls: improve man-like format

Parsing this file were causing lots of warnings with sphinx,
due to the c function prototypes.

Fix that by prepending them with .. cpp:function::

While here, use the same way we document man-like pages,
at the V4L side of the book and add escapes to asterisks.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: video_function_calls: improve man-like format

Parsing this file were causing lots of warnings with sphinx,
due to the c function prototypes.

Fix that by prepending them with .. cpp:function::

While here, use the same way we document man-like pages,
at the V4L side of the book and add escapes to asterisks.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: dmx_fcalls: improve man-like format

Parsing this file were causing lots of warnings with sphinx,
due to the c function prototypes.

Fix that by prepending them with .. cpp:function::

While here, use the same way we document man-like pages,
at the V4L side of the book and add escapes to asterisks.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: pixfmt-nv16: remove an empty column

The conversion added an empty column (probably, it was used on
DocBook just to increase spacing.

It also added an extra line on one of the texts, breaking
the original paragraph into two ones.

Remove them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: Fix some occurences of :sub:

The right way to use it seems to do suscript is to use
this pattern: "\ :sub:"

Make sure all places of the media document will fit, by
using this script:

$n=0;
while (<>) {
$n++;
$t = $_;
@matches = $t =~ m/(..\:sub\:)/g;
foreach my $m (@matches) {
$m =~ m/(.)(.)(\:sub\:)/;
$s1=$1;
$s2=$2;
$s3=$3;
next if (($s1 eq "\\") && ($s2 eq " "));
if ($s2 eq " ") {
$t =~ s/$s1$s2$s3/$s1\\$s2$s3/;
next;
}
$t =~ s/$s1$s2$s3/$s1$s2\\ $s3/;
}
print $t;
}

And running it with:

for i in $(git grep -l sub Documentation/linux_tv/); do ./sub.pl $i >a && mv a $i; done

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: pixfmt-nv12m: fix conversion issues

The conversion added an empty column (probably, it was used on
DocBook just to increase spacing.

It also added an extra line on one of the texts, breaking
the original paragraph into two ones.

Remove them.

Finally, a space is required before :sub:, as otherwise it
won't display it right. Add it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: pixfmt-nv12: remove empty columns

The conversion added empty columns (probably, it was used on
DocBook just to increase spacing.

Remove them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: pixfmt-yuv411p: remove an empty column

The conversion added an empty column (probably, it was used on
DocBook just to increase spacing.

It also added an extra line on one of the texts, breaking
the original paragraph into two ones.

Remove them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: pixfmt-yuv422p: remove an empty column

The conversion added an empty column (probably, it was used on
DocBook just to increase spacing.

Remove it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: pixfmt-yuv444m: remove empty columns

The conversion added empty columns (probably, it was used on
DocBook just to increase spacing.

Remove them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: pixfmt-yuv422m: remove an empty column

The conversion added an empty column (probably, it was used on
DocBook just to increase spacing.

Remove it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: pixfmt-41p: remove empty columns

The conversion added empty columns (probably, it was used on
DocBook just to increase spacing.

Remove them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: pixfmt-vyuy: remove an empty column

The conversion added an empty column (probably, it was used on
DocBook just to increase spacing.

Remove it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: pixfmt-yvyu: remove an empty column

The conversion added an empty column (probably, it was used on
DocBook just to increase spacing.

Remove it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: pixfmt-uyvy: remove an empty column

The conversion added an empty column (probably, it was used on
DocBook just to increase spacing.

Remove it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: pixfmt-y12i: correct format conversion

The format conversion broke one paragraph into two. Fix it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: remove trailing comments

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: pixfmt-004: Add an extra reference

One paragraph mentions the YUV422 formats, but doesn't provide
a cross-ref. Add it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: extended-controls: "count" is a constant

Constify the string "count" where it means a field.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: rw fix a warning

Fix this Sphinx warning:
Documentation/linux_tv/media/v4l/rw:31: WARNING: Literal block ends without a blank line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: open: fix some warnings

Fix those warnings:
Documentation/linux_tv/media/v4l/open:38: WARNING: Literal block ends without a blank line; unexpected unindent.
Documentation/linux_tv/media/v4l/open:45: WARNING: Literal block ends without a blank line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: vidioc-g-edid remove a duplicate declaration

The ioctl is declared twice. This causes the following warning:
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/vidioc-g-edid:7:

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: fe_property_parameters: improve descriptions

The asterisks cause parsing warnings with Sphinx:
Documentation/linux_tv/media/dvb/fe_property_parameters:954: WARNING: Inline substitution_reference start-string without end-string.
/devel/v4l/patchwork/Documentation/linux_tv/media/dvb/fe_property_parameters:993: WARNING: Inline emphasis start-string without end-string.

On the first warning, the ISDB-T layer enabled description is a
kind of ackward. Improve it.

For the second one, IMHO, it is clearer to use [A-C], as it
shows what are the real possibilities, than using asterisk.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: fix some warnings due to '*'

Unescaped * causes warnings on Sphinx.

Add an escape at hist-v4l2 occurrences.

At libv4l-introduction, the best is do declare the function
prototypes as C code.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: fdl-appendix: Fix formatting issues

The conversion didn't add blank lines where needed, but it
added were it weren't ;)

Fix it, to make it to parse correctly by Sphinx. This also
fixes a bunch or warnings:
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/fdl-appendix:44: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/fdl-appendix:52: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/fdl-appendix:58: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/fdl-appendix:71: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/fdl-appendix:78: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/fdl-appendix:84: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/fdl-appendix:107: WARNING: Explicit markup ends without a blank line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: pixfmt-007: Fix formula parsing

There are lots of warnings there:

/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/pixfmt-007:74: ERROR: Unexpected indentation.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/pixfmt-007:89: ERROR: Unexpected indentation.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/pixfmt-007:168: ERROR: Unexpected indentation.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/pixfmt-007:183: ERROR: Unexpected indentation.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/pixfmt-007:206: ERROR: Unexpected indentation.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/pixfmt-007:216: ERROR: Unexpected indentation.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/pixfmt-007:292: ERROR: Unexpected indentation.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/pixfmt-007:308: ERROR: Unexpected indentation.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/pixfmt-007:393: ERROR: Unexpected indentation.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/pixfmt-007:478: ERROR: Unexpected indentation.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/pixfmt-007:657: ERROR: Unexpected indentation.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/pixfmt-007:735: ERROR: Unexpected indentation.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/pixfmt-007:746: ERROR: Unexpected indentation.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/pixfmt-007:822: ERROR: Unexpected indentation.
/devel/v4l/patchwork/Documentation/linux_tv/media/v4l/pixfmt-007:833: ERROR: Unexpected indentation.

Also, sometimes the :sup: tag was ignored. Fix it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: Fix remaining undefined references

Fix Sphinx those warnings:
WARNING: undefined label: fdl-modified>`as given on the :ref:`title page <fdl-title-page (if the link has no caption the label must precede a section header)
WARNING: undefined label: v4l2-pix-fmt-yuv420 (if the link has no caption the label must precede a section $
WARNING: undefined label: pixfmt-srggb10 (if the link has no caption the label must precede a section heade$

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: use references for structures

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: Error codes should be const

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: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: selection-api-006: add missing captions

The example captions got stripped by the conversion to ReST.
Re-add.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: linux_tv: use Example x.y. instead of a single number

On the example captions, use always <chapter>.<number>., because:
1) it matches the DocBook;
2) it would mean less changes if we need to add a new example,
as only one chapter will be affected.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

doc-rst: selection-api-005: Fix ReST parsing

The ReST markup is limited: it doesn't accept a const just
after a reference. So, change the documentation to avoid such
constraint.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>