[media] index.rst: Fix LaTeX error in interactive mode on Sphinx 1.4.x

The Sphinx 1.4.x definition for \DUrole is:

\providecommand*{\DUrole}[2]{%
  \ifcsname DUrole#1\endcsname%
    \csname DUrole#1\endcsname{#2}%
  \else% backwards compatibility: try \docutilsrole#1{#2}
    \ifcsname docutilsrole#1\endcsname%
      \csname docutilsrole#1\endcsname{#2}%
    \else%
      #2%
    \fi%
  \fi%
}

This is broken when it is used inside a \begin{alltt} block.
So, replace it by just "#2", as this won't cause troubles, and
it is one of the fallback methods for it.

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

[media] docs-rst: Convert MC 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.

While here, improve the documentation to make them to look more
like the rest of the document.

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

[media] docs-rst: Convert LIRC 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.

While here, improve the documentation to make them to look more
like the rest of the document.

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

[media] docs-rst: Convert CEC 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.

While here, improve the documentation to make them to look more
like the rest of the document.

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

[media] docs-rst: Convert DVB 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.

While here, improve the documentation, marking the deprecated
ioctls, and making the non-deprecated ones more like the rest
of the media book.

Also, add a notice for ioctls that still require documentation.

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

[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>

[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>

[media] pixfmt-007.rst: use Sphinx math:: expressions

Enrich math formulas by using the Sphinx math. That will allow
using those formulas on pdf documents as well.

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

Merge remote-tracking branch 'docs-next/docs-next' into devel/docs-next

* docs-next/docs-next: (51 commits)
  docs-rst: add package adjustbox
  docs-rst: Fix an warning when in interactive mode
  docs-rst: Use better colors for note/warning/attention boxes
  docs-rst: conf.py: adjust the size of .. note:: tag
  docs-rst: add support for LaTeX output
  doc-rst: migrate ioctl CEC_DQEVENT to c-domain
  doc-rst: Revert "kernel-doc: fix handling of address_space tags"
  doc-rst: moved *duplicate* warnings to nitpicky mode
  doc-rst:c-domain: ref-name of a function declaration
  doc-rst: add boilerplate to customize c-domain
  docs: Sphinxify gdb-kernel-debugging.txt and move to dev-tools
  docs: sphinxify kmemcheck.txt and move to dev-tools
  docs: sphinxify kmemleak.txt and move it to dev-tools
  docs: sphinxify ubsan.txt and move it to dev-tools
  docs: sphinxify kasan.txt and move to dev-tools
  docs: sphinixfy gcov.txt and move to dev-tools
  docs: sphinxify kcov.txt and move to dev-tools
  docs: sphinxify sparse.txt and move to dev-tools
  docs: sphinxify coccinelle.txt and add it to dev-tools
  docs: create a new dev-tools directory
  ...

Merge branch 'doc/4.9' into docs-next

docs-rst: add package adjustbox

We need adjustbox to allow adjusting the size of tables that
are bigger than the line width. There are quite a few of them
at the media books.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: Fix an warning when in interactive mode

When XeLaTeX is in interactive mode, it complains that
py@noticelength already exists. Rename it and declare it
only once to avoid such messages.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: Use better colors for note/warning/attention boxes

Instead of painting the box with gray, let's use a colored
box. IMHO, that makes easier to warn users about some issue
pointed by the Sphinx. It also matches to what we do already
with the HTML output.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: conf.py: adjust the size of .. note:: tag

While the current implementation works well when using as a
paragraph, it doesn't work properly if inside a table. As we
have quite a few such cases, fix the logic to take the column
size into account.

PS.: I took the logic there from the latest version of Sphinx.sty

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: add support for LaTeX output

Sphinx supports LaTeX output. Sometimes, it is interesting to
call it directly, instead of also generating a PDF. As it comes
for free, add a target for it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc-rst: migrate ioctl CEC_DQEVENT to c-domain

This is only one example, demonstrating the benefits of the patch
series.  The CEC_DQEVENT ioctl is migrated to the sphinx c-domain and
referred by ":name: CEC_DQEVENT".

With this change the indirection using ":ref:`CEC_DQEVENT` is no longer
needed, we can refer the ioctl directly with ":c:func:`CEC_DQEVENT`". As
addition in the index, there is a entry "CEC_DQEVENT (C function)".

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc-rst: Revert "kernel-doc: fix handling of address_space tags"

This reverts commit a88b1672d4ddf9895eb53e6980926d5e960dea8e.

From the origin comit log::

  The RST cpp:function handler is very pedantic: it doesn't allow any
  macros like __user on it

Since the kernel-doc parser does NOT make use of the cpp:domain, there
is no need to change the kernel-doc parser eleminating the address_space
tags.

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc-rst: moved *duplicate* warnings to nitpicky mode

Moved the *duplicate C object description* warnings for function
declarations in the nitpicky mode. In nitpick mode, you can suppress
those warnings (e.g. ioctl) with::

  nitpicky = True
  nitpick_ignore = [
      ("c:func", "ioctl"),
  ]

See Sphinx documentation for the config values for ``nitpick`` and
``nitpick_ignore`` [1].

With this change all the ".. cpp:function:: int ioctl(..)" descriptions
(found in the media book) can be migrated to ".. c:function:: int
ioctl(..)", without getting any warnings. E.g.::

  .. cpp:function:: int ioctl( int fd, int request, struct cec_event *argp )

  .. c:function:: int ioctl( int fd, int request, struct cec_event *argp )

The main effect, is that we get those *CPP-types* back into Sphinx's C-
namespace and we need no longer to distinguish between c/cpp references,
when we refer a function like the ioctl.

[1] http://www.sphinx-doc.org/en/stable/config.html?highlight=nitpick#confval-nitpicky

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc-rst:c-domain: ref-name of a function declaration

Add option 'name' to the "c:function:" directive.  With option 'name'
the ref-name of a function can be modified. E.g.::

    .. c:function:: int ioctl( int fd, int request )
       :name: VIDIOC_LOG_STATUS

The func-name (e.g. ioctl) remains in the output but the ref-name
changed from ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for
this function is also changed to ``VIDIOC_LOG_STATUS`` and the function
can now referenced by::

    :c:func:`VIDIOC_LOG_STATUS`

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc-rst: add boilerplate to customize c-domain

Add a sphinx-extension to customize the sphinx c-domain.  No functional
changes right yet, just the boilerplate code.

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
[ jc: coding-style tweak ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

[media] MAINTAINERS: atmel-isc: add entry for Atmel ISC

Add the MAINTAINERS' entry for Microchip / Atmel Image Sensor Controller.

Signed-off-by: Songjun Wu <songjun.wu@microchip.com>
Acked-by: Nicolas Ferre <nicolas.ferre@atmel.com>
Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

[media] atmel-isc: DT binding for Image Sensor Controller driver

DT binding documentation for ISC driver.

Acked-by: Rob Herring <robh@kernel.org>
Signed-off-by: Songjun Wu <songjun.wu@microchip.com>
Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

[media] atmel-isc: add the Image Sensor Controller code

Add driver for the Image Sensor Controller. It manages
incoming data from a parallel based CMOS/CCD sensor.
It has an internal image processor, also integrates a
triple channel direct memory access controller master
interface.

Signed-off-by: Songjun Wu <songjun.wu@microchip.com>
Signed-off-by: Hans Verkuil <hans.verkuil@cisco.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

[media] docs-rst: fix some .. note:: occurrences

On some places, either an space or the second ':' is missing.

Fix them.

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

[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>

[media] docs-rst: v4l2-drivers book: adjust column margins

A few tables are not properly output on LaTeX format.

Fix them.

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

[media] v4l2-dev.rst: adjust table to fit into page

One table here is not being properly displayed on LaTeX
format. Adjust it.

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

[media] cec-ioc-receive.rst: one table here should be longtable

The table is too big to fit into a single page on LaTeX format.

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

[media] subdev-formats.rst: adjust tables size for LaTeX output

There are two big tables here that are very hard to adjust its
size.

The first one would fit into one page, but the latex.py logic
at Sphinx auto-switches to longtable when there are more than 30
rows. There's no way to override without coding.

The second one is really big, and won't fit on a single page.
So, it has to use tiny font to fit.

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

[media] extended-controls.rst: avoid going past page with LaTeX

It is painful to put code/verbatim code in bold. It seems that
the only way is to arrange it like:
``foo``
    bar

At least on LaTeX output, when this happens, the "foo" string
is not hidentable/breakable. The entire string should fit into
a single line.

Add a workaround for this ReST limitation by splitting the
foo string into two strings, on separate lines. The output
is not the best, but it works.

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

[media] Fix a few additional tables at uAPI for LaTeX output

There are still a few tables with wrong columns at the uAPI
docs. Fix them.

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

[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>

[media] gen-errors.rst fix error table column limits

Fix the generic errors table to avoid column overflows on
LaTeX output.

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

[media] uapi/cec: adjust tables on LaTeX output

Fix tables to avoid text to overflow the cell limits.

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

[media] cec-core: Convert it to ReST format

There are some things there that aren't ok for ReST format.

Fix them.

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

[media] docs-rst: move cec kAPI documentation to the media book

The CEC kAPI documentation should also be part of the media book.

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

[media] media-types.rst: adjust tables to fit on LaTeX output

A few tables at the media uAPI documentation have columns
not well dimentioned. Adjust them.

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

[media] adjust remaining tables at DVB uAPI documentation

There are a few broken tables on LaTeX output at the DVB
uAPI documentation. Fix them.

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

[media] fe_property_parameters.rst: Adjust column sizes

Add position hints for some tables, in order for them to be
shown properly on LaTeX output.

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

[media] fix v4l2-selection-*.rst tables for LaTeX output

Adjust the tables there to fit inside the page margins.

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

[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>

[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>

[media] adjust some vidioc-*rst tables with wrong columns

Adjust simple cases where the columns on some vidioc files
are overriding their neighbours.

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

[media] vidioc-g-sliced-vbi-cap.rst: make tables fit on LaTeX output

The tables don't fit at the page on this file. As noticed
before, Sphinx (or LaTeX?) does a crap job on tables with
cell span, and some work has to be done to make it fit.

Move the see also reference to a footnote, break one paragraph
into two and adjust the table columns to make it visible.

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

[media] vidioc-enumstd.rst: adjust video standards table

This table is too big for LaTeX output, and lacks columns
specs for LaTeX format.

Also, it has a hidden column, as there are some cell spans
with the wrong values.

Fix it, so it can be displayed properly on LaTeX/PDF.

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

[media] vidioc-dv-timings-cap.rst: Adjust LaTeX columns

Some tables are not properly displayed on LaTeX. Fix them.

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

[media] vidioc-dqevent.rst: adjust two table columns for LaTeX output

There are two tables with mangled columns. Fix it.

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

[media] vidioc-decoder-cmd.rst: better adjust column widths

Better adjust the columns for LaTeX output

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

[media] diff-v4l.rst: Make capabilities table fit in LaTeX

This table has several troubles:
- a duplicated "struct" on its name;
- a reference to a V4L version 1 struct that will never
  point to something (as we got rid of V4L1 API a long
  time ago);
- misses hints for LaTeX output (column size and longtable
  style).

Fix them.

It should be noticed that the first column of this table is
not aligned with the rest. I suspect that this is a bug at
the flat-table extension.

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

[media] subdev-formats.rst: adjust most of the tables to fill in page

Fix mosto fo the tables there in order to make them fit at the
page size.

There are, however, two exceptions: RGB and YUV big tables,
where adding the raw latex adjustbox caused the tables to not
be properly formatted. I suspect that the problem is because
those are long tables, but not really sure.

The thing is that Sphinx lacks an "adjustbox" tag that would
avoid the raw latex hacks.

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

[media] dev-subdev.rst: make table fully visible on LaTeX

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

Fix it.

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

[media] dev-rds.rst: adjust table dimentions for LaTeX

One of the tables has wrong column dimentions. Fix it.

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

[media] dev-sliced-vbi.rst: Adjust tables on LaTeX output

Better format the tables in a way that will fit inside the
page.

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

[media] dev-sliced-vbi.rst: use a footnote for VBI images

Just like on dvb-raw-vbi.rst, the LaTeX output doesn't work
well with cell spans. Also, this is actually a note, so, move
it to a footnote.

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

[media] docs-rst: re-generate vbi_525.pdf and vbi_625.pdf

Originally, each image were one page big, causing them to be
displayed on separate pages at the PDF output. Re-generate
them from the gif files.

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

[media] dev-raw-vbi.rst: adjust table columns for LaTeX output

Add the needed tags to fix LaTeX output of the tables there.

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

[media] dev-raw-vbi.rst: add a footnote for the count limits

There's a bug with LaTeX output on flat-tables with Sphinx 1.4.5
that prevents references at a cell span to be broken. As the
text is indeed too long, it makes sense to place the reference
to the pictures showing the VBI limits as a footnote.

That makes the text easier to read and also solves the issue
with LaTeX output.

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

[media] dev-overlay.rst: don't ident a note

There's one note there that it is indented for no good reason.
Fix it.

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

[media] buffer.rst: Adjust table columns for LaTeX output

The table columns are not properly displayed. Also, some
tables are too big to fit into just one page. So, fix them,
in order to better display the tables.

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

[media] docs-rst: remove width hints from pixfmt byte order tables

Those hints are wrong, and doesn't really improve the look
of those tables. So, keep them only when they're useful.

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

[media] pixfmt-packed-yuv.rst: adjust tables to fit in LaTeX

Adjust the table to fit at the LaTeX and PDF outputs, just like
what was done with pixfmt-packed-rgb.rst.

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

[media] pixfmt-packed-rgb.rst: adjust tables to fit in LaTeX

Adjust the tables to fit at the LaTeX and PDF outputs.

I wrote a previous patch RFC to show the big table in landscape,
but it makes harder to read on displays.

So, instead, let's use the adjustbox to shrink the size of those
long tables, as the table size can still be visible on screen,
and it is a way better to read in horizontal position and
visible if printed.

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

[media] pixfmt-packed-rgb.rst: Fix cell spans

There is an extra column just before eack pack of bits, to
improve table reading, but the header file didn't take this
into account.

Fix it.

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

[media] docs-rst: add column hints for pixfmt-002 and pixfmt-006

Add column hints for LaTeX to format columns on the tables inside
pixfmt-002.rst and pixfmt-006.rst.

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

[media] extended-controls.rst: fix table sizes

Lots of tables at extended-controls.rst need explicit hints for
LaTeX to adjust their widths. Provide that.

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

[media] control.rst: Fix table width

Manually adjust the table width for it to look nice on PDF output.

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

[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>

[media] docs-rst: re-generate typical_media_device.pdf

There are some texts there on the wrong place. Re-generate it
from the svg file.

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

[media] vidioc-querycap.rst: Better format tables on PDF output

Both tables on this rst file were not shown right, as they miss
the proper tag (tabularcolumns) to specify the column widths
required for PDF and LaTeX output.

Also, the second table is too big to fit into one page. So,
it should use the longtable class to allow it to be split into
two pages.

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

[media] docs-rst: get rid of code-block inside tables

There are two tables with a C code-block inside it. Unfortunately,
that causes LaTeX output to break. Yet, there's nothing special
there, so let's remove the code-block from them.

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

[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>

[media] vidioc-enumstd.rst: remove bullets from sound carrier

The items at the sound carrier had a bullet. Those are not needed.

So, get rid of them.

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

[media] vidioc-enumstd.rst: fix a broken reference

Somehow, the conversion broke a reference here. Re-add it.

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

[media] pixfmt-nv12mt.rst: use PNG instead of GIF

pdflatex doesn't like gif images:
None:None: WARNING: no matching candidate for image URI u'media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.*'
None:None: WARNING: no matching candidate for image URI u'media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.*'

But it works fine with png. So, convert them. As a plus, PNG images
are smaller.

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

Merge branch 'doc/4.9' into docs-next

Merge branch 'dev-tools' into doc/4.9

Coalesce development-tool documents into a single directory and sphinxify
them.

docs: Sphinxify gdb-kernel-debugging.txt and move to dev-tools

Acked-by: Jan Kiszka <jan.kiszka@siemens.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinxify kmemcheck.txt and move to dev-tools

Cc: Vegard Nossum <vegardno@ifi.uio.no>
Cc: Pekka Enberg <penberg@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinxify kmemleak.txt and move it to dev-tools

Acked-by: Catalin Marinas <catalin.marinas@arm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinxify ubsan.txt and move it to dev-tools

Acked-by: Andrey Ryabinin <aryabinin@virtuozzo.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinxify kasan.txt and move to dev-tools

No textual changes beyond formatting.

Acked-by: Andrey Ryabinin <aryabinin@virtuozzo.com>
Acked-by: Alexander Potapenko <glider@google.com>
Cc: Dmitry Vyukov <dvyukov@google.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinixfy gcov.txt and move to dev-tools

No textual changes beyond formatting.

Cc: Peter Oberparleiter <oberpar@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinxify kcov.txt and move to dev-tools

Another document added to the dev-tools collection.

Cc: Dmitry Vyukov <dvyukov@google.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinxify sparse.txt and move to dev-tools

Fold the sparse document into the development tools set; no changes to the
text itself beyond formatting.

Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: sphinxify coccinelle.txt and add it to dev-tools

No textual changes have been made, but the formatting has obviously been
tweaked.

Cc: Michal Marek <mmarek@suse.com>
Cc: Gilles Muller <Gilles.Muller@lip6.fr>
Acked-by: Nicolas Palix <nicolas.palix@imag.fr>
Acked-by: Julia Lawall <julia.lawall@lip6.fr>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: create a new dev-tools directory

This directory will be a collecting point for documentation oriented around
development tools.  As a step toward ordering Documentation/ it's a small
one, but we have to start somewhere...

Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Merge branch 'doc/4.9' into docs-next

Merge branch 'xelatex' into doc/4.9

Mauro says:

This patch series fix Sphinx to allow it to build the media
documentation as a PDF file.

The first patch is actually a bug fix: one of the previous patch
broke compilation for PDF as a hole, as it added an extra
parenthesis to a function call.

The second patch just removes a left over code for rst2pdf.

The other patches change from "pdflatex" to "xelatex" and address
several issues that prevent building the media books.

I think this patch series belong to docs-next. Feel free to merge
them there, if you agree. There's one extra patch that touches
Documentation/conf.py, re-adding the media book to the PDF build,
but IMHO this one would be better to be merged via the media tree,
after the fixes inside the media documentation to fix the build.

docs-rst: enable the Sphinx math extension

This extension will be used by the media books.

The name of the math image extension changed on Sphinx 1.4.x,
according with:
http://www.sphinx-doc.org/en/stable/ext/math.html#module-sphinx.ext.imgmath

Let's autodetect, to keep building with versions < 1.4.

Suggested-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: Don't go to interactive mode on errors

When building for LaTeX, it stops and enters into interactive
mode on errors. Don't do that, as there are some non-fatal errors
on media books when using Sphinx 1.4.x that we don't know how fix
yet.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: parse-heraders.pl: escape LaTeX characters

Let's escape the LaTeX characters, to avoid troubles when
outputing them.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: better adjust margins and font size

As we have big tables, reduce the left/right margins and decrease
the point size to 8pt. Visually, it is still good enough, and
now less tables are too big to be displayed.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: Don't mangle with UTF-8 chars on LaTeX/PDF output

pdflatex doesn't accept using some UTF-8 chars, like
"equal or less than" or "equal or greater than" chars. However,
the media documents use them. So, we need to use XeLaTeX for
conversion, and a font that accepts such characters.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: improve output for .. notes:: on LaTeX

The output for those notes are bad in pdf, as they're not
in a box with a different color. Also, it causes the output
to not build if the note is inside a table.

Change its implementation to avoid the above troubles.

The logic there came from:
https://stackoverflow.com/questions/606746/how-to-customize-an-existing-latex-environment-without-interfering-with-other-en

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: allow generating some LaTeX pages in landscape

Portrait is too small for some tables used at the media docs.
So, allow documents to tell Sphinx to generate some pages
in landscape by using:

.. raw:: latex

    \begin{landscape}

<some stuff>

.. raw:: latex

    \end{landscape}

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: remove a rst2pdf left over code

The usage of rst2pdf was replaced by pdflatex on a previous
patch. Remove the left-over code at conf.py.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs-rst: fix a breakage when building PDF documents

changeset 606b9ac81a63 ("doc-rst: generic way to build only sphinx
sub-folders") accidentally broke PDF generation by adding an extra
")". Remove it.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

mm, kasan: Update kasan docs to indicate arm64 support

KASAN has been supported on arm64 since 39d114ddc682 ("arm64: add KASAN
support"). Update the docs to indicate this.

Signed-off-by: Laura Abbott <labbott@redhat.com>
Acked-by: Andrey Ryabinin <aryabinin@virtuozzo.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc-rst: add index to sub-folders

Add a index if only a sub-folder is build e.g.::

  make SPHINXDIRS=media cleandocs htmldocs

BTW: removed dead search link in the top-index file

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

kconfig-language: improve menuconfig usage description

Improper menuconfig usage leads to empty menu entries.
zconfdump() is able to reveal some real-life examples:
- menuconfig VFIO_NOIOMMU
- menuconfig RESET_CONTROLLER
- menuconfig SND_ARM

To avoid future occurrences of those, improve the menuconfig syntax
description.

Signed-off-by: Eugeniu Rosca <rosca.eugeniu@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>