OSDN Git Service
Mauro Carvalho Chehab [Mon, 14 Nov 2016 16:32:32 +0000 (14:32 -0200)]
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>
Mauro Carvalho Chehab [Mon, 14 Nov 2016 16:32:31 +0000 (14:32 -0200)]
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>
Mauro Carvalho Chehab [Mon, 14 Nov 2016 16:32:30 +0000 (14:32 -0200)]
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>
Mauro Carvalho Chehab [Mon, 14 Nov 2016 16:32:29 +0000 (14:32 -0200)]
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>
Mauro Carvalho Chehab [Mon, 14 Nov 2016 16:32:28 +0000 (14:32 -0200)]
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>
Mauro Carvalho Chehab [Mon, 14 Nov 2016 16:32:27 +0000 (14:32 -0200)]
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>
Jonathan Corbet [Sun, 13 Nov 2016 19:24:59 +0000 (12:24 -0700)]
MAINTAINERS: The Chinese documentation moved
Update the F: line accordingly.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
SeongJae Park [Tue, 8 Nov 2016 12:26:09 +0000 (21:26 +0900)]
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>
SeongJae Park [Tue, 8 Nov 2016 12:26:08 +0000 (21:26 +0900)]
Documentation: Move translations into a sub-directory
Signed-off-by: SeongJae Park <sj38.park@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
SeongJae Park [Tue, 8 Nov 2016 12:26:07 +0000 (21:26 +0900)]
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>
Luis de Bethencourt [Tue, 1 Nov 2016 15:23:37 +0000 (15:23 +0000)]
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>
Masahiro Yamada [Wed, 2 Nov 2016 16:57:34 +0000 (01:57 +0900)]
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>
Markus Heiser [Tue, 1 Nov 2016 14:36:02 +0000 (15:36 +0100)]
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>
Jonathan Corbet [Tue, 8 Nov 2016 01:58:01 +0000 (18:58 -0700)]
Merge branch 'tpm' into docs-next
Jarkko Sakkinen [Thu, 3 Nov 2016 23:57:52 +0000 (17:57 -0600)]
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>
Jarkko Sakkinen [Thu, 3 Nov 2016 23:57:51 +0000 (17:57 -0600)]
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>
Shuah Khan [Mon, 7 Nov 2016 20:24:14 +0000 (13:24 -0700)]
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>
Jonathan Corbet [Tue, 8 Nov 2016 01:03:13 +0000 (18:03 -0700)]
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>
Jonathan Corbet [Tue, 8 Nov 2016 00:08:33 +0000 (17:08 -0700)]
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.
SeongJae Park [Mon, 31 Oct 2016 20:27:21 +0000 (05:27 +0900)]
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>
SeongJae Park [Mon, 31 Oct 2016 20:27:20 +0000 (05:27 +0900)]
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>
SeongJae Park [Mon, 31 Oct 2016 20:27:19 +0000 (05:27 +0900)]
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>
SeongJae Park [Mon, 31 Oct 2016 20:27:18 +0000 (05:27 +0900)]
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>
SeongJae Park [Mon, 31 Oct 2016 20:27:17 +0000 (05:27 +0900)]
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>
SeongJae Park [Mon, 31 Oct 2016 20:27:16 +0000 (05:27 +0900)]
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>
SeongJae Park [Mon, 31 Oct 2016 20:27:15 +0000 (05:27 +0900)]
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>
SeongJae Park [Mon, 31 Oct 2016 20:27:14 +0000 (05:27 +0900)]
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>
SeongJae Park [Mon, 31 Oct 2016 20:27:13 +0000 (05:27 +0900)]
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>
SeongJae Park [Mon, 31 Oct 2016 20:27:12 +0000 (05:27 +0900)]
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>
SeongJae Park [Mon, 31 Oct 2016 20:27:11 +0000 (05:27 +0900)]
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>
SeongJae Park [Mon, 31 Oct 2016 20:27:10 +0000 (05:27 +0900)]
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>
Mauro Carvalho Chehab [Mon, 7 Nov 2016 19:03:19 +0000 (17:03 -0200)]
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>
Mauro Carvalho Chehab [Mon, 7 Nov 2016 19:03:18 +0000 (17:03 -0200)]
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>
Mauro Carvalho Chehab [Mon, 7 Nov 2016 19:03:17 +0000 (17:03 -0200)]
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>
Mauro Carvalho Chehab [Mon, 7 Nov 2016 19:03:16 +0000 (17:03 -0200)]
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>
Jani Nikula [Thu, 3 Nov 2016 10:11:50 +0000 (12:11 +0200)]
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>
Jani Nikula [Thu, 3 Nov 2016 10:10:10 +0000 (12:10 +0200)]
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>
Jani Nikula [Thu, 3 Nov 2016 09:44:23 +0000 (11:44 +0200)]
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>
Jani Nikula [Thu, 3 Nov 2016 09:44:04 +0000 (11:44 +0200)]
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>
Jani Nikula [Thu, 3 Nov 2016 09:43:29 +0000 (11:43 +0200)]
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>
Jani Nikula [Thu, 3 Nov 2016 08:26:54 +0000 (10:26 +0200)]
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>
Jani Nikula [Wed, 2 Nov 2016 11:05:59 +0000 (13:05 +0200)]
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>
Markus Heiser [Wed, 2 Nov 2016 14:37:11 +0000 (16:37 +0200)]
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>
Jani Nikula [Wed, 2 Nov 2016 11:20:15 +0000 (13:20 +0200)]
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>
Jani Nikula [Wed, 2 Nov 2016 08:56:31 +0000 (10:56 +0200)]
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>
Jani Nikula [Wed, 2 Nov 2016 09:13:19 +0000 (11:13 +0200)]
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>
Jani Nikula [Wed, 2 Nov 2016 08:38:43 +0000 (10:38 +0200)]
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>
Silvio Fricke [Fri, 28 Oct 2016 08:14:11 +0000 (10:14 +0200)]
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>
Silvio Fricke [Fri, 28 Oct 2016 08:14:10 +0000 (10:14 +0200)]
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>
Silvio Fricke [Fri, 28 Oct 2016 08:14:09 +0000 (10:14 +0200)]
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>
Silvio Fricke [Fri, 28 Oct 2016 08:14:08 +0000 (10:14 +0200)]
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>
Jonathan Corbet [Thu, 27 Oct 2016 23:05:10 +0000 (17:05 -0600)]
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.
Oliver Neukum [Thu, 20 Oct 2016 13:15:00 +0000 (15:15 +0200)]
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>
Jonathan Corbet [Wed, 26 Oct 2016 22:48:36 +0000 (16:48 -0600)]
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>
Jonathan Corbet [Wed, 26 Oct 2016 22:45:29 +0000 (16:45 -0600)]
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>
Jonathan Corbet [Wed, 26 Oct 2016 22:41:05 +0000 (16:41 -0600)]
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>
Jonathan Corbet [Wed, 26 Oct 2016 22:37:53 +0000 (16:37 -0600)]
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>
Jonathan Corbet [Wed, 26 Oct 2016 22:34:09 +0000 (16:34 -0600)]
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>
Jonathan Corbet [Wed, 26 Oct 2016 22:22:01 +0000 (16:22 -0600)]
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>
Jonathan Corbet [Wed, 26 Oct 2016 22:20:27 +0000 (16:20 -0600)]
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>
Jonathan Corbet [Wed, 26 Oct 2016 22:14:52 +0000 (16:14 -0600)]
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>
Jonathan Corbet [Wed, 26 Oct 2016 21:55:20 +0000 (15:55 -0600)]
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>
Jonathan Corbet [Wed, 26 Oct 2016 21:43:00 +0000 (15:43 -0600)]
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>
Markus Heiser [Wed, 26 Oct 2016 06:23:17 +0000 (08:23 +0200)]
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>
Markus Heiser [Wed, 26 Oct 2016 06:23:16 +0000 (08:23 +0200)]
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>
Markus Heiser [Wed, 26 Oct 2016 06:23:15 +0000 (08:23 +0200)]
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>
Markus Heiser [Wed, 26 Oct 2016 06:23:14 +0000 (08:23 +0200)]
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>
Jonathan Corbet [Wed, 26 Oct 2016 00:05:23 +0000 (18:05 -0600)]
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/
Igor Vuk [Tue, 25 Oct 2016 19:00:31 +0000 (21:00 +0200)]
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>
SeongJae Park [Fri, 21 Oct 2016 14:10:02 +0000 (23:10 +0900)]
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>
Mauro Carvalho Chehab [Tue, 18 Oct 2016 14:31:12 +0000 (12:31 -0200)]
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>
Mauro Carvalho Chehab [Tue, 18 Oct 2016 12:46:38 +0000 (10:46 -0200)]
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>
Mauro Carvalho Chehab [Tue, 18 Oct 2016 11:22:55 +0000 (09:22 -0200)]
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>
Mauro Carvalho Chehab [Tue, 18 Oct 2016 12:12:27 +0000 (10:12 -0200)]
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>
Mauro Carvalho Chehab [Wed, 21 Sep 2016 12:51:11 +0000 (09:51 -0300)]
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>
Mauro Carvalho Chehab [Wed, 21 Sep 2016 11:40:21 +0000 (08:40 -0300)]
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>
Mauro Carvalho Chehab [Tue, 18 Oct 2016 11:05:32 +0000 (09:05 -0200)]
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>
Mauro Carvalho Chehab [Wed, 21 Sep 2016 12:09:49 +0000 (09:09 -0300)]
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>
Mauro Carvalho Chehab [Wed, 21 Sep 2016 12:27:00 +0000 (09:27 -0300)]
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>
Mauro Carvalho Chehab [Tue, 18 Oct 2016 13:57:16 +0000 (11:57 -0200)]
Documentation/CodeOfConflict: convert to ReST
Fix ReST notation for a bullet item
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Fri, 23 Sep 2016 20:22:55 +0000 (17:22 -0300)]
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>
Mauro Carvalho Chehab [Fri, 23 Sep 2016 19:33:27 +0000 (16:33 -0300)]
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>
Mauro Carvalho Chehab [Fri, 23 Sep 2016 19:26:03 +0000 (16:26 -0300)]
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>
Mauro Carvalho Chehab [Fri, 23 Sep 2016 19:14:29 +0000 (16:14 -0300)]
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>
Mauro Carvalho Chehab [Fri, 23 Sep 2016 19:07:08 +0000 (16:07 -0300)]
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>
Mauro Carvalho Chehab [Fri, 23 Sep 2016 18:44:01 +0000 (15:44 -0300)]
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>
Mauro Carvalho Chehab [Fri, 23 Sep 2016 18:24:07 +0000 (15:24 -0300)]
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>
Mauro Carvalho Chehab [Fri, 23 Sep 2016 18:07:00 +0000 (15:07 -0300)]
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>
Mauro Carvalho Chehab [Fri, 23 Sep 2016 17:40:40 +0000 (14:40 -0300)]
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>
Mauro Carvalho Chehab [Fri, 23 Sep 2016 17:02:36 +0000 (14:02 -0300)]
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>
Mauro Carvalho Chehab [Fri, 23 Sep 2016 16:52:05 +0000 (13:52 -0300)]
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>
Mauro Carvalho Chehab [Fri, 23 Sep 2016 16:44:24 +0000 (13:44 -0300)]
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>
Mauro Carvalho Chehab [Fri, 23 Sep 2016 16:22:41 +0000 (13:22 -0300)]
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>
Mauro Carvalho Chehab [Wed, 21 Sep 2016 20:18:36 +0000 (17:18 -0300)]
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>
Mauro Carvalho Chehab [Wed, 21 Sep 2016 19:59:42 +0000 (16:59 -0300)]
Documentation/init.txt: convert to ReST markup
- use a quote blocks where needed;
- use ``foo`` for monotonic;
- adjust whitespaces and blank lines;
- fix the second list (that starts with 0, instead of A)
- add it to the user's book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Wed, 21 Sep 2016 19:52:26 +0000 (16:52 -0300)]
Documentation/initrd.txt: convert to ReST markup
- use a quote blocks where needed;
- fix the chapter/section/subsection markups;
- use ``foo`` for monotonic;
- use .. note:: for /sbin/init file permissions;
- adjust whitespaces and blank lines;
- add it to the user's book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Wed, 21 Sep 2016 19:32:00 +0000 (16:32 -0300)]
Documentation/dynamic-debug-howto.txt: convert it to ReST markup
- use a quote blocks where needed;
- fix the chapter/section/subsection markups;
- use ``foo`` for monotonic;
- use .. note:: for the line-range note;
- cleanup whitespaces;
- add it to the user's book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Wed, 21 Sep 2016 18:47:58 +0000 (15:47 -0300)]
Documentation/devices.rst: convert it to ReST markup
- use a quote block for the big device major/minor list;
- use tables for the other device tables;
- fix the chapter/section/subsection markups;
- use ``foo`` for monotonic;
- use .. attention:: for the attention note to developers;
- use cross-references where needed;
- cleanup whitespaces;
- add it to the user's book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Wed, 21 Sep 2016 18:16:45 +0000 (15:16 -0300)]
Documentation/BUG-HUNTING: convert to ReST markup
- Add a document title and remove its own index;
- use monotonic fonts for paths;
- use quote blocks where needed;
- adjust/use spaces to properly format paragraphs;
- add it to the user book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Mauro Carvalho Chehab [Wed, 21 Sep 2016 17:44:59 +0000 (14:44 -0300)]
Documentation/braille-console: convert it to ReST markup
- Fix identation for the document title;
- use monotonic fonts for paths;
- use quote blocks where needed;
- adjust spaces to properly format paragraphs;
- use :menuselection: and :kbd: for the menu item and keys;
- point too the right item at the menu;
- add it to the user book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>