Right now, for a struct, kernel-doc produces the following output:

	.. c:type:: struct v4l2_prio_state

	   stores the priority states

	**Definition**

	::

	  struct v4l2_prio_state {
	    atomic_t prios[4];
	  };

	**Members**

	``atomic_t prios[4]``
	  array with elements to store the array priorities

Putting a member name in verbatim and adding a continuation line
causes the LaTeX output to generate something like:
	item[atomic_t prios\[4\]] array with elements to store the array priorities

Everything inside "item" is non-breakable, with may produce
lines bigger than the column width.

Also, for function members, like:

        int (* rx_read) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num);

It puts the name of the member at the end, like:

        int (*) (struct v4l2_subdev *sd, u8 *buf, size_t count,ssize_t *num) read

With is very confusing.

The best is to highlight what really matters: the member name.
is a secondary information.

So, change kernel-doc, for it to produce the output on a different way:

	**Members**

	``prios[4]``

	  array with elements to store the array priorities

Also, as the type is not part of LaTeX "item[]", LaTeX will split it into
multiple lines, if needed.

So, both LaTeX/PDF and HTML outputs will look good.

It should be noticed, however, that the way Sphinx LaTeX output handles
things like:

	Foo
	   bar

is different than the HTML output. On HTML, it will produce something
like:

	**Foo**
	   bar

While, on LaTeX, it puts both foo and bar at the same line, like:

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

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>

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>

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>

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>

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>

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>

This reverts commit a88b1672.

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>

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-nitpickySigned-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

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>

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>

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

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

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

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

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

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>

No textual changes beyond formatting.

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

Another document added to the dev-tools collection.

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

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>

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>

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>

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.

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>

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>

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>

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>

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>

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-enSigned-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

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>

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>

changeset 606b9ac8 ("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>

KASAN has been supported on arm64 since 39d114dd ("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>

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>

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>

Hi Jon,

This patch is an old one, we have corrected some minor issues on the newer one.
Please only review the newest version from my last mail with this subject
"[PATCH] ACPI: Update the maximum depth of C-state from 6 to 9".
And I also attached it to this mail.

Thanks,
Baole

On 7/11/2016 6:37 AM, Jonathan Corbet wrote:
> On Mon, 4 Jul 2016 09:55:10 +0800
> "baolex.ni" <baolex.ni@intel.com> wrote:
>
>> Currently, CPUIDLE_STATE_MAX has been defined as 10 in the cpuidle head file,
>> and max_cstate = CPUIDLE_STATE_MAX – 1, so 9 is the right maximum depth of C-state.
>> This change is reflected in one place of the kernel-param file,
>> but not in the other place where I suggest changing.
>>
>> Signed-off-by: Chuansheng Liu <chuansheng.liu@intel.com>
>> Signed-off-by: Baole Ni <baolex.ni@intel.com>
>
> So why are there two signoffs on a single-line patch?  Which one of you
> is the actual author?
>
> Thanks,
>
> jon
>

From cf5f8aa6885874f6490b11507d3c0c86fa0a11f4 Mon Sep 17 00:00:00 2001
From: Chuansheng Liu <chuansheng.liu@intel.com>
Date: Mon, 4 Jul 2016 08:52:51 +0800
Subject: [PATCH] Update the maximum depth of C-state from 6 to 9
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Currently, CPUIDLE_STATE_MAX has been defined as 10 in the cpuidle head file,
and max_cstate = CPUIDLE_STATE_MAX – 1, so 9 is the right maximum depth of C-state.
This change is reflected in one place of the kernel-param file,
but not in the other place where I suggest changing.
Signed-off-by: Chuansheng Liu <chuansheng.liu@intel.com>
Signed-off-by: Baole Ni <baolex.ni@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Now, the A83T and A64 SoC user manuals are available.
Update the documentation to add the links.

An updated version of A83T datasheet is also included now.
Signed-off-by: Icenowy Zheng <icenowy@aosc.xyz>
Acked-by: Chen-Yu Tsai <wens@csie.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

It is not a very good practice to define the IOCTL manually instead of
using the header file.

Fix it on the documentation example.
Signed-off-by: Ricardo Ribalda Delgado <ricardo.ribalda@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Some architectures (i.e.: sparc64 and arm64) make reasonable partial stack
duplication for jprobes problematic. Document this.
Signed-off-by: David A. Long <dave.long@linaro.org>
Acked-by: Catalin Marinas <catalin.marinas@arm.com>
Acked-by: Masami Hiramatsu <mhiramat@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Because Linus may still be reading source code on greenbar paper
instead of color terminals with code syntax highlighting and
appropriate font decorations.

Link: http://lkml.kernel.org/r/CA+55aFyQYJerovMsSoSKS7PessZBr4vNp-3QUUwhqk4A4_jcbg@mail.gmail.comSigned-off-by: Joe Perches <joe@perches.com>