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

`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: NSeongJae Park <sj38.park@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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: NSeongJae Park <sj38.park@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This commit applies commit 1b49ecf2 ("docs: Clean up bare :: lines")
to Korean translation.
Signed-off-by: NSeongJae Park <sj38.park@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This commit appplies commit f1eebe92 ("Documentation/HOWTO: adjust
external link references") to Korean translation.
Signed-off-by: NSeongJae Park <sj38.park@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This commit applies commit 34fed7e7 ("Documentation/HOWTO: improve
some markups to make it visually better") to Korean translation.
Signed-off-by: NSeongJae Park <sj38.park@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This commit applies commit 43fb67a5 ("Documentation/HOWTO: update
information about generating documentation") to Korean translation.
Signed-off-by: NSeongJae Park <sj38.park@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This commit applies commit 609d99a3 ("Documentation/HOWTO: add
cross-references to other documents") to Korean translation.
Signed-off-by: NSeongJae Park <sj38.park@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

This commit applies commit 022e04d6 ("Documentation/HOWTO: convert
to ReST notation") to Korean translation and fix a trivial ReST build
failure problem.
Signed-off-by: NSeongJae Park <sj38.park@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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

This commit fixes subtitles style.  It aligns them with their header,
adjust blank lines between them properly.
Signed-off-by: NSeongJae Park <sj38.park@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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

`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: NSeongJae Park <sj38.park@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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

The tainted kernels info is not directly related to
the oops tracing. So, let's move it to a separate file.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

Better organize the admin guide documentation by moving the
bug bisect to a separate file.
Signed-off-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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

Include the literal device list from a separate file. This helps the pdf
build.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

Include the literal kernel parameter list from a separate file. This
helps the pdf build.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

Now that we don't have automatic syntax highlighting, use the code-block
directive with the explicitly selected language, where appropriate.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

Now that we don't have automatic syntax highlighting, use the code-block
directive with the explicitly selected language, where appropriate.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

Now that we don't have automatic syntax highlighting, use the code-block
directive with the explicitly selected language, where appropriate.
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

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: NJani Nikula <jani.nikula@intel.com>

Fix the warning:

WARNING: "latex_documents" config value references unknown document
user/index
Reviewed-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

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

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

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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Tested-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

With the unnecessary ; removed, the terminal URL detection also works
better.
Reviewed-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Tested-by: NMarkus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

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: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJani Nikula <jani.nikula@intel.com>

... and move to Documentation/core-api folder.
Signed-off-by: NSilvio Fricke <silvio.fricke@gmail.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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

Only formating changes.
Signed-off-by: NSilvio Fricke <silvio.fricke@gmail.com>
Acked-by: NTejun Heo <tj@kernel.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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: NSilvio Fricke <silvio.fricke@gmail.com>
Reviewed-by: Jani Nikula <jani.nikula@intel.com
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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.

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: NOliver Neukum <oneukum@suse.com>
Acked-by: NGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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

This is crufty stuff and should maybe just be deleted, but I'm not quite
ready to do that yet.
Reviewed-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

I believe this makes the page as a whole more approachable.
Reviewed-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>

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

Put like documents together, with the essential ones at the top, and split
the TOC into sections.
Reviewed-by: NMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: NJonathan Corbet <corbet@lwn.net>