Documentation: convert USB to new format

This is a conversion of the USB documentation to the Sphinx format.
No content was altered or reformatted.

Signed-off-by: Oliver <oneukum@suse.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: circular-buffers: use READ_ONCE()

While the {READ,WRITE}_ONCE() macros should be used in preference to
ACCESS_ONCE(), the circular buffer documentation uses the latter
exclusively.

To point people in the right direction, and as a step towards the
eventual removal of ACCESS_ONCE(), update the documentation to use
READ_ONCE(), as ACCESS_ONCE() is only used in a reader context in the
circular buffer documentation.

Signed-off-by: Mark Rutland <mark.rutland@arm.com>
Acked-by: David Howells <dhowells@redhat.com>
Acked-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: atomic_ops: use {READ,WRITE}_ONCE()

While the {READ,WRITE}_ONCE() macros should be used in preference to
ACCESS_ONCE(), the atomic documentation uses the latter exclusively.

To point people in the right direction, and as a step towards the
eventual removal of ACCESS_ONCE(), update the documentation to use the
{READ,WRITE}_ONCE() macros as appropriate.

Signed-off-by: Mark Rutland <mark.rutland@arm.com>
Cc: Boqun Feng <boqun.feng@gmail.com>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Will Deacon <will.deacon@arm.com>
Acked-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Add more manuals to the PDF build

There were a few manuals that weren't being built in PDF format, but
there's no reason not to...

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

Merge branch 'mauro-pdf' into docs-next

Mauro says:

This series address a series of errors during PDF generation from
media documentation.

The first patch fixes the late redefinition of a LaTeX command at the
Sphinx LaTeX style that causes build to break when some cross-references
are used.

The next two patches fix PDF output issues with subdev-formats.rst.

The next 3 patches fix image includes and their output for PDF.

It is aligned with Linus request of not having binary-generated images
from their SVG source codes.

I still intend to move the remaing PNG images to vectorial ones (SVG),
as image scale works better, but this will require some additional work.
When done, I'll submit as a separate patch series.

It should also be noticed that the last patch violates the output dir,
when make is used with "O=some_dir", as Sphinx doesn't accept
image files outside the source directory. We'll likely need some Sphinx
extension in order to fix it, but at least with this series (plus Jani Nikola's
PDF fix series), the PDF output should work fine again.

[jc: added a commit fixing up a "make cleandocs" warning]

docs: Avoid warning on cleandocs

Recent Makefile changes added an rm command without the requisite "-f",
leading to warnings if the files do not exist.  Make it be quiet again.

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

docs-rst: auto-generate PDF image files

The PDF files that contain media images were actually generated
offline from their SVG or PNG source files.

Sphinx can handle PNG sources automatially. So, let's just
drop their PDF counterparts.

For SVG, however, Sphinx doesn't produce the right tags to
use the TexLive SVG support. Also, the SVG support is done via
shell execution, with is not nice.

So, while we don't have any support for SVG inside Sphinx
core or as an extension, move the logic to build them to Makefile,
producing the PDF images on runtime.

NOTE: due to the way Sphinx works, the PDF images should be
generated inside the Kernel source tree, as otherwise Sphinx
won't find it, not obeying what's specified by "O=" makefile
parameter.

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

docs-rst: convert gif files to png

Right now, media is using two different formats for bitmap
images: GIF and PNG. Let's use just one, to make it simpler when
building with Sphinx.

As PNG is usually better than GIF, let's use it.

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

convert some images from png to svg

SVG images are nicer, as they can easily be scaled. Also, they're
written in text, with makes easier to work.

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

subdev-formats.rst: add missing columns to tabularcolumns

There are several missing columns on the size specification,
causing LaTeX to complain on interactive mode.

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

subdev-formats.rst: don't use adjustbox on a longtable

adjustbox doesn't work on longtables. Also, this
causes an error on LaTeX in interactive mode.

So, use, instead, a tiny font.

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

docs-rst: fix LaTeX \DURole renewcommand with Sphinx 1.3+

PDF build on Kernel 4.9-rc? returns an error with Sphinx 1.3.x
and Sphinx 1.4.x, when trying to solve some cross-references.

The solution is to redefine the \DURole macro.

However, this is redefined too late. Move such redefinition to
LaTeX preamble and bind it to just the Sphinx versions where the
error is known to be present.

Tested by building the documentation on interactive mode:
make PDFLATEX=xelatex -C Documentation/output/./latex

Fixes: e61a39baf74d ("[media] index.rst: Fix LaTeX error in interactive mode on Sphinx 1.4.x")
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

MAINTAINERS: The Chinese documentation moved

Update the F: line accordingly.

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

Documentation: Add HOWTO Korean translation into rst based build system

This commit adds Korean translation of HOWTO document into rst based
documentation build system.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation: Move translations into a sub-directory

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs/driver-api: Apply changed source file names

Few files under dma-buf/ changed their names but the changes didn't
applied to a document that referencing them.  It is causing few
documentation build warnings.  This commit fixes the problems by
applying changed file names on the document.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

USB: fix typo in documentation

A typo sneaked in the latest change on the USB documentation. Fixing it
and also a trailing whitespace since it is also in the "USB Host-Side API
Model" chapter.

Signed-off-by: Luis de Bethencourt <luisbg@osg.samsung.com>

coding-style: fix mismatch of jump label name

Commit 865a1caa4b6b ("CodingStyle: Clarify and complete chapter 7")
renamed the label "out_buffer" to "out_free_buffer", but missed to
change this line.

Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>
Reviewed-by: Jean Delvare <jdelvare@suse.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

doc-rst: make cleandocs misses a fair number of files

Removes intermediate 'Documentation/DocBook/.*.xml.cmd' files

Changes since v1:
- Reduce the patch to DocBook cleandocs

References: http://lkml.kernel.org/r/CA+r1Zhjr5SCVAroREBv84t9bxDVu5jVJ_Fu=BbVDGNNABdQOuQ@mail.gmail.com
Reported-by: Jim Davis <jim.epost@gmail.com>
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Merge branch 'tpm' into docs-next

tpm: move documentation under Documentation/security

In order too make Documentation root directory cleaner move the tpm
directory under Documentation/security.

Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

tpm: transition tpm_vtpm_proxy documentation to the Sphinx

Transitioned the tpm_vtpm_proxy documentation to the Sphinx
infrastructure and removed parts from the documentation that are easier
to pull from the sources. Restructured vtpm_proxy.h and tpm_vtpm_proxy.c
to be compatible with this approach and wrote associated documentation
comments.

Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Doc: update kselftest.txt with details on how to run tests after install

Update kselftest.txt with details on how to run tests after install.

Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Fix a PDF build error in bug-bisect.rst

It seems we can't have literal blocks in footnotes, which almost actually
makes some sense.  So just use basic ``monospace`` instead.

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

Merge branch 'sphinx-fixes-for-docs-next' of git://people.freedesktop.org/~jani/drm into test

A set of PDF and other docs related fixes from Jani.

ko_KR/HOWTO: Mark subsection in suggested format

`Specific guidelines for the kernel documentation` section of
`kernel-documentation.rst` suggests to use ``~`` for subsection but
subsections in HOWTO is not marked in the format.  This commit marks
them in the format.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Add whitespace between URL and text

Because few sentences has no whitespace between URL and text, few
document viewers fail to properly parse the URL from it.  This commit
adds whitespace between them to fix the problem.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Clean up bare :: lines

This commit applies commit 1b49ecf2f3be ("docs: Clean up bare :: lines")
to Korean translation.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Adjust external link references

This commit appplies commit f1eebe92c265 ("Documentation/HOWTO: adjust
external link references") to Korean translation.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Improve some markups to make it visually better

This commit applies commit 34fed7e7e0e5 ("Documentation/HOWTO: improve
some markups to make it visually better") to Korean translation.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Update information about generating documentation

This commit applies commit 43fb67a5258c ("Documentation/HOWTO: update
information about generating documentation") to Korean translation.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Add cross-references to other documents

This commit applies commit 609d99a3b72e ("Documentation/HOWTO: add
cross-references to other documents") to Korean translation.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Convert to ReST notation

This commit applies commit 022e04d6f555 ("Documentation/HOWTO: convert
to ReST notation") to Korean translation and fix a trivial ReST build
failure problem.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Update obsolete link to bugzilla faq

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Fix subtitles style

This commit fixes subtitles style.  It aligns them with their header,
adjust blank lines between them properly.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

ko_KR/HOWTO: Fix a typo: s/Linux Torvalds/Linus Torvalds

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/process/howto: Mark subsection in suggested format

`Specific guidelines for the kernel documentation` section of
`kernel-documentation.rst` suggests to use ``~`` for subsection but
subsections in HOWTO is not marked in the format.  This commit marks
them in the format.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

admin-guide: merge oops-tracing with bug-hunting

Now that oops-tracing.rst has only information about
stack dumps found on OOPS, and bug-hunting.rst has only
information about how to identify the source code line
associated with a stack dump, let's merge them and
improve the information inside it.

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

admin-guide: move tainted kernels info to a separate file

The tainted kernels info is not directly related to
the oops tracing. So, let's move it to a separate file.

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

doc-rst: admin-guide: move bug bisect to a separate file

Better organize the admin guide documentation by moving the
bug bisect to a separate file.

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

bug-hunting.rst: update info about bug hunting

The document shows a really old procedure for bug hunting that
nobody uses anymore. Remove such section, and update the
remaining documentation to reflect the procedures used
currently.

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

Documentation/admin-guide: split the device list to a separate file

Include the literal device list from a separate file. This helps the pdf
build.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>

Documentation/admin-guide: split the kernel parameter list to a separate file

Include the literal kernel parameter list from a separate file. This
helps the pdf build.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>

Documentation/gpu: use code-block with proper language

Now that we don't have automatic syntax highlighting, use the code-block
directive with the explicitly selected language, where appropriate.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>

Documentation/dev-tools: use code-block with proper language

Now that we don't have automatic syntax highlighting, use the code-block
directive with the explicitly selected language, where appropriate.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>

Documentation/admin-guide: use code-block with proper language

Now that we don't have automatic syntax highlighting, use the code-block
directive with the explicitly selected language, where appropriate.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>

Documentation/sphinx: set literal block highlight language to none

Set the default highlight language to "none", i.e. do not try to guess
the language and do automatic syntax highlighting on literal blocks.

Eyeballing around the generated documentation, we don't seem to actually
have a lot of literal blocks that would benefit from syntax
highlighting. The C code blocks we do have are typically very short, and
most of the literal blocks are things that shouldn't be highlighted (or,
do not have a pygments lexer). This seems to be true for literal blocks
both in the rst source files and in source code comments.

Not highlighting code is never wrong, but guessing the language wrong
almost invariably leads to silly or confusing highlighting.

At the time of writing, admin-guide/oops-tracing.rst and
admin-guide/ramoops.rst contain good examples of 1) a small C code
snippet not highlighted, 2) a hex dump highligted as who knows what, 3)
device tree block highlighted as C or maybe Python, 4) a terminal
interaction highlighted as code in some language, and finally, 5) some C
code snippets correctly identified as C. I think we're better off
disabling language guessing, and going by explicitly identified
languages for longer code blocks.

It is still possible to enable highlighting on an rst source file basis
using the highlight directive:

.. higlight:: language

and on a literal block basis using the code-block directive:

.. code-block:: language

See http://www.sphinx-doc.org/en/latest/markup/code.html for details.

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Cc: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>

Documentation/sphinx: include admin-guide in the latex/pdf build

Fix the warning:

WARNING: "latex_documents" config value references unknown document
user/index

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>

Documentation/sphinx: fix make SPHINXDIRS="dirs" pdfdocs for more than one dir

Add missing semicolon to fix pdf build with more than one SPHINXDIRS
directory specified. For example make SPHINXDIRS="gpu media" pdfdocs.

Fixes: cd21379b1698 ("doc-rst: generic way to build PDF of sub-folders")
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>

Documentation/sphinx: change pdflatex interaction mode to batchmode

Radically reduce the noise on stdout. The full build logs will still be
available under Documentatio/output/latex/*.log.

Cc: Mauro Carvalho Chehab <mchehab@osg.samsung.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Tested-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>

Documentation/sphinx: remove superfluous trailing ; from quiet_cmd_sphinx

With the unnecessary ; removed, the terminal URL detection also works
better.

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>

Documentation/sphinx: make it possible to build latexdocs without pdflatex

Building latexdocs doesn't actually require $(PDFLATEX). Move the checks
for it to the pdfdocs target which does require it, and specifically
outside of the target in order to not depend on latexdocs when we can't
build pdfdocs anyway.

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Tested-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>

Documentation/sphinx: let the user specify PDFLATEX and LATEXOPTS

Refer to xelatex and latex options via variables. This allows the user
to override the pdflatex and latex options to use on the make command
line for experimenting. As a side effect, this makes the makefile a bit
tidier.

Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>

Documentation/workqueue.txt: convert to ReST markup

... and move to Documentation/core-api folder.

Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/00-index: update for new core-api folder

Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

workqueue: kerneldocify workqueue_attrs

Only formating changes.

Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com>
Acked-by: Tejun Heo <tj@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

kernel-doc: better parsing of named variable arguments

Without this patch we get warnings for named variable arguments.

    warning: No description found for parameter '...'
    warning: Excess function parameter 'args' description in 'alloc_ordered_workqueue'

Signed-off-by: Silvio Fricke <silvio.fricke@gmail.com>
Reviewed-by: Jani Nikula <jani.nikula@intel.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Merge branch 'doc-tweaks' into docs-next

The creation of the admin and process guides is a great thing, but, without
care, we risk replacing a messy docs directory with a few messy Sphinx
books.  In an attempt to head that off and show what I'm thinking, here's a
set of tweaks that, I think, make the existing Sphinx-formatted docs a bit
more accessible.

USB: update intro of documentation

It does no good to mention The 2.4 kernel series and neglect
USB 3.x and XHCI. Also with type C and micro/mini USB we better
not talk about the shape of connectors.

Signed-off-by: Oliver Neukum <oneukum@suse.com>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Add a warning to applying-patches.rst

This is ancient stuff and we don't do things this way anymore.  In the
absence of simply deleting the document, at least add a warning to it.

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

docs: add a warning to submitting-drivers.rst

This is crufty stuff and should maybe just be deleted, but I'm not quite
ready to do that yet.

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

docs: Collapse the process guide TOC

I believe this makes the page as a whole more approachable.

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

docs: Tweak submitting-patches.rst formatting

The main goal here was to get the subsections to show in the TOC as they do
for all the other documents.  Also call out the DCO in the section title
since it's important.

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

docs: Apply some basic organization to the process guide

Put like documents together, with the essential ones at the top, and split
the TOC into sections.

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

docs: Get rid of the "basic profiling" guide

The document has not been touched in over 11 years and doesn't reflect how
profiling is done in the perf era.

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

docs: Get rid of the badRAM guide

The last release of this tool was for 2.6.28; it's hard to see how it has
any relevance to current kernels.

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

docs: Clean up and organize the admin guide a bit

The admin guide is a good start, but it's time to turn it into something
better than an unordered blob of files.  This is a first step in that
direction.  The TOC has been split up and annotated, the guides have been
reordered, and minor tweaks have been applied to a few of them.

One consequence of splitting up the TOC is that we don't really want to use
:numbered: anymore, since the count resets every time and there doesn't
seem to be a way to change that.  Eventually we probably want to group the
documents into sub-books, at which point we can go back to a single TOC,
but it's probably early to do that.

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

docs: retitle the kernel-documentation.rst

Let's make the title of this document (which shows up in the top page)
better describe its contents.

Cc: Jani Nikula <jani.nikula@intel.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

docs: Tweak the top-level Sphinx page

This will be the initial landing point for readers, so give them a bit of
introductory material.  Also split the TOC into area-specific chunks to
make the whole thing a bit more approachable.

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

doc-rst: build PDF of 80211 and gpu sub-project

This allows to build PDF of only the sub-projects, which reduce the
roundtrip compared to build the PDF from the main documentation.

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

doc-rst: include index only in subproject AND html

The index should only be included if the build of the sub-folder is done
with the html-builder (HTML output).

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

doc-rst: make driver-api folder buildable stand-alone

Add minimal conf.py makes the driver-api folder buildable
stand-alone. To build only this folder run::

  make SPHINXDIRS=driver-api htmldocs
  make SPHINXDIRS=driver-api pdfdocs

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

doc-rst: make dev-tools folder buildable stand-alone

Add minimal conf.py and moved dev-tools/tools.rst to dev-tools/index.rst
makes the dev-tools folder buildable stand-alone. To build only this
folder run::

  make SPHINXDIRS=dev-tools htmldocs
  make SPHINXDIRS=dev-tools pdfdocs

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

Merge branch 'mauro-books' into docs-next

Merge Mauro's massive patch series creating the process and admin-guide
books.  I think there's a lot of stuff to clean up here, but there's no
point in holding things up for that.

Mauro sez:

This patch series continues the efforts of converting the Linux Kernel
documentation to Sphinx.

It contains text to ReST conversion of several files under Documentation,
and a few ones under the main dir (README, REPORTING-BUGS).

All patches on this series can be found on my development tree:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=lkml-books-v2

The Kernel docs html output after this series can be seen at:
https://mchehab.fedorapeople.org/kernel_docs/

Documentation: cpu-hotplug: Fix typos

Fix some minor spelling errors and capitalization issues.

Signed-off-by: Igor Vuk <parcijala@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

locking/Doc/ko_KR: Clarify limited control-dependency scope

This commit applies upstream change, commit ebff09a6ff16
("locking/Documentation: Clarify limited control-dependency scope"), to
Korean translation.

Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/00-INDEX: remove legacy media directories

The dvb/ and video4linux/ dirs were removed, as now, all media
documentation is under media/.

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

README: add a new README file, pointing to the Documentation/

As we moved the real README file to Documentation/admin-guide/README.rst,
let's add a replacement, pointing to it, and giving the main directions
about documentation.

In the future, perhaps it would be worth to move the contents
of Documentation/00-Index into this README.

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

doc: re-add CodingStyle and SubmittingPatches

Those files got moved to Documentation/process, but as they're very
well known files, add pointers to their new locations.

PS.: I opted to not merge this patch with the previous one
in order to make the diff of the previous one more consistent,
as it will show only renames.

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

docs: fix locations of several documents that got moved

The previous patch renamed several files that are cross-referenced
along the Kernel documentation. Adjust the links to point to
the right places.

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

docs-rst: create an user's manual book

Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters
on an user's manual book.

As we'll be numbering the user's manual, remove the manual
numbering from SecurityBugs.

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

docs-rst: add documents to development-process

Add several documents to the development-process ReST book.

As we don't want renames, use symlinks instead, keeping those
documents on their original place.

Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

docs: rename development-process/ to process/

As we'll type this a lot, after adding CodingStyle & friends,
let's rename the directory name to a shorter one.

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

README: convert it to ReST markup

Adjust the readme file for it to use the ReST markup:

- add chapter/section markups;
- use ``foo`` for commands;
- use :: for verbatim and script blocks;
- replace unsupported markup _foo_ by **foo**;
- add cross-references to other ReST files;
- use lower case on the section titles, to match other ReST files.

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

REPORTING-BUGS: convert to ReST markup

- add a title to the document;
- use :: before verbatim blocks;
- add blank lines where required;
- use protocol for URL references;
- use a verbatim block for the bugs template;
- add cross references to SecurityBugs.

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

Documentation/CodeOfConflict: convert to ReST

Fix ReST notation for a bullet item

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

Documentation/parport.txt: fix table to show on LaTeX

Sphinx doesn't like nested tables on the LaTex output.

So, change the table there to be displayed properly at
the PDF output.

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

Documentation/volatile-considered-harmful.txt: convert to ReST markup

- Fix document section markups;
- use quote blocks where needed;
- adjust spaces and blank lines;
- add it to the development-processs book.

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

Documentation/VGA-softcursor.txt: convert to ReST markup

- Fix document title;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.

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

Documentation/unicode.txt: convert it to ReST markup

Probably, unicode is something that we might remove from the
docs, as all modern systems support it. Yet, this chapter
is fun, as it mentions support for the Klington fictional
charset ;)

On the other hand, I bet all other OS user manuals
explicit mention unicode support.

So, convert it to ReST and include it at the user's book.

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

Documentation/sysrq.txt: convert to ReST markup

- Fix document title;
- use a table for the valid commands;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.

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

Documentation/sysfs-rules.txt: convert it to ReST markup

- Fix document title;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.

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

Documentation/ramoops.txt: convert it to ReST format

- Fix document title;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.

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

Documentation/parport.txt: convert to ReST markup

- Add a document title;
- use quote blocks where needed;
- convert parameters to a nested table;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- replace _foo_ by **foo**;
- add it to the user's book.

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

Documentation/oops-tracing.txt: convert to ReST markup

- Add a document title;
- use .. note:: markup;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- replace _foo_ by **foo**;
- while here, remove whitespaces at the end of paragraph;
- add it to the user's book.

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

Documentation/java.txt: convert to ReST markup

- Fix document title;
- use quote blocks where needed;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.

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

Documentation/mono.txt: convert to ReST markup

- Fix document title;
- use quote blocks where needed;
- use .. note:: for notes;
- use monotonic fonts for config options and file names;
- adjust whitespaces and blank lines;
- add it to the user's book.

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

Documentation/module-signing.txt: convert to ReST markup

- Fix identatio for the document title;
- remove its index;
- create a table for hash algorithm to be used;
- use quote blocks where needed;
- use monotonic fonts for parameters;
- adjust whitespaces and blank lines;
- Fix case on section titles;
- add it to the user's book.

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

Documentation/md.txt: Convert to ReST markup

- add a title for the document;
- convert some parameters to tables;
- use quote blocks where needed;
- use monotonic fonts for parameters;
- adjust whitespaces and blank lines;
- add it to the user's book.

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

Documentation/magic-number.txt: convert it to ReST markup

- add a title for the document;
- convert the table;
- use quote block for the changelog;
- use monotonic fonts for file names;
- adjust whitespaces and blank lines;
- add it to the user's book.

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