[PATCH 3/7] kernel-doc-HOWTO: add kernel-doc specification

[Markus Heiser <markus.heiser@darmarIT.de>]

From: "Heiser, Markus" <markus.heiser@darmarIT.de>

The kernel-doc-HOWTO book is a rewrite of the kernel-doc-nano-HOWTO.txt,
taking reST extension into account.

The kernel-doc-HOWTO is a user guide for kernel developers that also
serves as a specification.

The format for this documentation is called the *kernel-doc* format. With kernel
version 4.x the restructuredText (reST_) markup was added to the *kernel-doc*
format. The kernel-doc parser supports the markup modes:

 * kernel-doc (vintage)
 * reST

This document gives hints on how to use these markups and how to refer
and extract documentation from source files.

A online kernel-doc-HOWTO is available at [1]

[1] http://return42.github.io/sphkerneldoc/books/kernel-doc-HOWTO

Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
---
 Documentation/books/kernel-doc-HOWTO.conf          | 200 +++++++++
 .../books/kernel-doc-HOWTO/all-in-a-tumble-src.rst |  12 +
 .../books/kernel-doc-HOWTO/all-in-a-tumble.h       | 271 +++++++++++
 .../books/kernel-doc-HOWTO/all-in-a-tumble.rst     |  11 +
 Documentation/books/kernel-doc-HOWTO/csv_table.txt |   6 +
 Documentation/books/kernel-doc-HOWTO/index.rst     |  46 ++
 .../kernel-doc-HOWTO/kernel-doc-components.rst     |  35 ++
 .../kernel-doc-HOWTO/kernel-doc-directive.rst      | 199 ++++++++
 .../books/kernel-doc-HOWTO/kernel-doc-examples.rst |  16 +
 .../books/kernel-doc-HOWTO/kernel-doc-intro.rst    |  85 ++++
 .../books/kernel-doc-HOWTO/kernel-doc-syntax.rst   | 171 +++++++
 .../kernel-doc-HOWTO/reST-kernel-doc-mode.rst      | 120 +++++
 Documentation/books/kernel-doc-HOWTO/refs.txt      |  15 +
 .../books/kernel-doc-HOWTO/table-markup.rst        | 499 +++++++++++++++++++++
 .../books/kernel-doc-HOWTO/test/parser_test.h      | 332 ++++++++++++++
 .../kernel-doc-HOWTO/vintage-kernel-doc-mode.rst   | 100 +++++
 16 files changed, 2118 insertions(+)
 create mode 100644 Documentation/books/kernel-doc-HOWTO.conf
 create mode 100644 Documentation/books/kernel-doc-HOWTO/all-in-a-tumble-src.rst
 create mode 100644 Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.h
 create mode 100644 Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.rst
 create mode 100644 Documentation/books/kernel-doc-HOWTO/csv_table.txt
 create mode 100644 Documentation/books/kernel-doc-HOWTO/index.rst
 create mode 100644 Documentation/books/kernel-doc-HOWTO/kernel-doc-components.rst
 create mode 100644 Documentation/books/kernel-doc-HOWTO/kernel-doc-directive.rst
 create mode 100644 Documentation/books/kernel-doc-HOWTO/kernel-doc-examples.rst
 create mode 100644 Documentation/books/kernel-doc-HOWTO/kernel-doc-intro.rst
 create mode 100644 Documentation/books/kernel-doc-HOWTO/kernel-doc-syntax.rst
 create mode 100644 Documentation/books/kernel-doc-HOWTO/reST-kernel-doc-mode.rst
 create mode 100644 Documentation/books/kernel-doc-HOWTO/refs.txt
 create mode 100644 Documentation/books/kernel-doc-HOWTO/table-markup.rst
 create mode 100644 Documentation/books/kernel-doc-HOWTO/test/parser_test.h
 create mode 100644 Documentation/books/kernel-doc-HOWTO/vintage-kernel-doc-mode.rst

diff --git a/Documentation/books/kernel-doc-HOWTO.conf b/Documentation/books/kernel-doc-HOWTO.conf
new file mode 100644
index 0000000..4e8c32a
--- /dev/null
+++ b/Documentation/books/kernel-doc-HOWTO.conf
@@ -0,0 +1,200 @@
+# -*- coding: utf-8; mode: python -*-
+#
+# This is the project specific sphinx-build configuration, which is loaded from
+# the base configuration file (``../conf.py``). About config values consult:
+#
+# * http://www.sphinx-doc.org/en/stable/config.html
+#
+# While setting values here, please take care to not overwrite common needed
+# configurations. This means, do not *overwrite* composite values (e.g. the
+# list- or dictionary-value of "latex_elements" resp. "extensions") by
+# thoughtless assignments. Manipulate composite values always by *update*
+# (dict-values) or extend (list-values). Nevertheless, if you know what you are
+# doing, you are free to *overwrite* values to your needs.
+#
+# useful preseted names:
+#
+# * BASE_FOLDER: the folder where the top conf.py is located
+# * main_name:   the basename of this project-folder
+
+# ------------------------------------------------------------------------------
+# General configuration
+# ------------------------------------------------------------------------------
+
+project   = u'kernel-doc HOWTO'
+copyright = u'2016, Linux documentation authors'
+author    = u'Linux contributors'
+
+extlinks.update({ })
+
+intersphinx_mapping.update({ })
+
+extensions.extend([
+    # 'sphinx.ext.pngmath'
+    #, 'sphinx.ext.mathjax'
+])
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = u'1.0'
+# The full version, including alpha/beta/rc tags.
+# release = u'0'
+
+# ------------------------------------------------------------------------------
+# Options for HTML output
+# ------------------------------------------------------------------------------
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = pathjoin(BASE_FOLDER, "_tex", "logo.png")
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path.extend([])
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = main_name
+
+# ------------------------------------------------------------------------------
+# Options for XeLaTeX output
+# ------------------------------------------------------------------------------
+
+xelatex_documents = [
+    # A book with default DIN A4 and 12pt
+    dict(docname         = master_doc
+         , targetname    = "%s.tex" % main_name
+         , documentclass = "darmarITArticle")]
+
+# This value determines the topmost sectioning unit. It should be chosen from
+# ``part``, ``chapter`` or ``section``. The default is ``None``; the topmost
+# sectioning unit is switched by documentclass. ``section`` is used if
+# documentclass will be ``howto``, otherwise ``chapter`` will be used.
+
+latex_toplevel_sectioning = 'chapter'
+
+# ------------------------------------------------------------------------------
+# Options for manual page output
+# ------------------------------------------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+# man_pages = [
+#     (master_doc, 'kernel-doc', u'Kernel-Doc',
+#      [author], 1)
+# ]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+# ------------------------------------------------------------------------------
+# Options for Texinfo output
+# ------------------------------------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+# texinfo_documents = [
+#     (master_doc, 'Kernel-Doc', u'Kernel-Doc Documentation',
+#      author, 'Kernel-Doc', 'One line description of project.',
+#      'Miscellaneous'),
+# ]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+# ------------------------------------------------------------------------------
+# Options for Epub output
+# ------------------------------------------------------------------------------
+
+# Bibliographic Dublin Core info.
+# epub_title = project
+# epub_author = author
+# epub_publisher = author
+# epub_copyright = copyright
+
+# The basename for the epub file. It defaults to the project name.
+#epub_basename = project
+
+# The HTML theme for the epub output. Since the default themes are not
+# optimized for small screen space, using the same theme for HTML and epub
+# output is usually not wise. This defaults to 'epub', a theme designed to save
+# visual space.
+#epub_theme = 'epub'
+
+# The language of the text. It defaults to the language option
+# or 'en' if the language is not set.
+#epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# A tuple containing the cover image and cover page html template filenames.
+#epub_cover = ()
+
+# A sequence of (type, uri, title) tuples for the guide element of content.opf.
+#epub_guide = ()
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files.extend([])
+
+# HTML files that should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files.extend([])
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files.extend([])
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
+
+# Allow duplicate toc entries.
+#epub_tocdup = True
+
+# Choose between 'default' and 'includehidden'.
+#epub_tocscope = 'default'
+
+# Fix unsupported image types using the Pillow.
+#epub_fix_images = False
+
+# Scale large images.
+#epub_max_image_width = 0
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#epub_show_urls = 'inline'
+
+# If false, no index is generated.
+#epub_use_index = True
+
diff --git a/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble-src.rst b/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble-src.rst
new file mode 100644
index 0000000..9d360ae
--- /dev/null
+++ b/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble-src.rst
@@ -0,0 +1,12 @@
+.. -*- coding: utf-8; mode: rst -*-
+.. include:: refs.txt
+
+.. _all-in-a-tumble-src:
+
+================
+Examples Sources
+================
+
+.. literalinclude:: ./all-in-a-tumble.h
+   :linenos:
+   :language: c
diff --git a/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.h b/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.h
new file mode 100644
index 0000000..d72c8bd
--- /dev/null
+++ b/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.h
@@ -0,0 +1,271 @@
+/* parse-markup: reST */
+
+/* parse-SNIP: intro */
+/**
+ * DOC: kernel-doc intro
+ *
+ * This file / chapter includes all the refered examples of the kernel-doc-HOWTO
+ * and additional tests.
+ *
+ * The content itself is nonsens / don’t look to close ;-)
+ */
+/* parse-SNAP: */
+
+
+/* parse-SNIP: hello-world */
+#include<stdio.h>
+int main() {
+  printf("Hello World\n");
+  return 0;
+}
+/* parse-SNAP: */
+
+
+/* parse-SNIP: my_struct */
+/**
+ * struct my_struct - short description
+ * @a: first member
+ * @b: second member
+ *
+ * Longer description
+ */
+struct my_struct {
+    int a;
+    int b;
+/* private: */
+    int c;
+};
+/* parse-SNAP: */
+
+
+/* parse-SNIP: my_long_struct */
+/**
+ * struct my_struct - short description
+ * @a: first member
+ * @b: second member
+ *
+ * Longer description
+ */
+struct my_long_struct {
+  int a;
+  int b;
+  /**
+   * @c: This is longer description of C.
+   *
+   * You can use paragraphs to describe arguments
+   * using this method.
+   */
+  int c;
+};
+/* parse-SNAP: */
+
+
+/* parse-SNIP: theory-of-operation */
+/**
+ * DOC: Theory of Operation
+ *
+ * The whizbang foobar is a dilly of a gizmo.  It can do whatever you
+ * want it to do, at any time.  It reads your mind.  Here's how it works.
+ *
+ * foo bar splat
+ *
+ * The only drawback to this gizmo is that is can sometimes damage
+ * hardware, software, or its subject(s).
+ */
+/* parse-SNAP: */
+
+
+
+/* parse-SNIP: user_function */
+/**
+ * user_function - function that can only be called in user context
+ * @a: some argument
+ * Context: !in_interrupt()
+ *
+ * This function makes no sense, it is only kernel-doc demonstration.
+ *
+ * ::
+ *
+ * Example:
+ * x = user_function(22);
+ *
+ * Return:
+ * Returns first argument
+ */
+int user_function(int a)
+{
+  return a;
+}
+/* parse-SNAP: */
+
+
+
+
+/* parse-markup: kernel-doc */
+
+/**
+ * vintage - short description of this function
+ * @parameter_a: first argument
+ * @parameter_b: second argument
+ * Context: in_gizmo_mode().
+ *
+ * Long description. This function has two integer arguments. The first is
+ * @parameter_a and the second is @parameter_b.
+ *
+ * Example:
+ * user_function(22);
+ *
+ * Return:
+ * Sum of @parameter_a and @parameter_b.
+ *
+ * highlighting:
+ *
+ * - vintage()    : function
+ * - @parameter_a : name of a parameter
+ * - $ENVVAR      : environmental variable
+ * - &my_struct   : name of a structure (up to two words including ``struct``)
+ * - %CONST       : name of a constant.
+ *
+ * Parser Mode: *vintage* kernel-doc mode
+ *
+ * Within the *vintage kernel-doc mode* dogged ignores any whitespace or inline
+ * markup.
+ *
+ * - Inline markup like *emphasis* or **emphasis strong**
+ * - Literals and/or block indent:
+ *
+ *      a + b
+ *
+ * In kernel-doc *vintage* mode, there are no special block or inline markups
+ * available. Markups like the one above result in ambiguous reST markup which
+ * could produce error messages in the subsequently sphinx-build
+ * process. Unexpected outputs are mostly the result.
+ *
+ * This is a link https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/
+ * to the Linux kernel source tree
+ *
+ * colon markup: sectioning by colon markup in vintage mode is partial ugly. ;-)
+ *
+ */
+int vintage(int parameter_a, char parameter_b)
+{
+  return a + b;
+}
+
+
+/* parse-markup: reST */
+
+/**
+ * rst_mode - short description of this function
+ * @a: first argument
+ * @b: second argument
+ * Context: :c:func:`in_gizmo_mode`.
+ *
+ * Long description. This function has two integer arguments. The first is
+ * ``parameter_a`` and the second is ``parameter_b``.
+ *
+ * As long as the reST / sphinx-doc toolchain uses `intersphinx
+ * <http://www.sphinx-doc.org/en/stable/ext/intersphinx.html>`__ you can refer
+ * definitions *outside* like :c:type:`struct media_device <media_device>`.  If
+ * the description of ``media_device`` struct is found in any of the intersphinx
+ * locations, a hyperref to this target is genarated a build time.
+ *
+ * Example:
+ *
+ * .. code-block:: c
+ *
+ *     user_function(22);
+ *
+ * Return:
+ * Sum of ``parameter_a`` and the second is ``parameter_b``.
+ *
+ * highlighting:
+ *
+ * Because reST markup syntax conflicts with the highlighting markup from the
+ * *vintage* mode, these *vintage* highlighting markup is not available in
+ * reST-mode. reST brings it's own markup to refer and highlight function,
+ * structs or whatever definition :
+ *
+ * - :c:func:`rst_mode` : function
+ * - ``$ENVVAR``:  environmental variable
+ * - :c:type:`my_struct` : name of a structure
+ * - ``parameter_a`` : name of a parameter
+ * - ``CONST`` : name of a constant.
+ *
+ * Parser Mode:
+ *
+ * This is an example with activated reST additions, in this section you will
+ * find some common inline markups.
+ *
+ * Within the *reST mode* the kernel-doc parser pass through all markups to the
+ * reST toolchain, except the *vintage highlighting* but including any
+ * whitespace. With this, the full reST markup is available in the comments.
+ *
+ * This is a link to the `Linux kernel source tree
+ * <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/>`_.
+ *
+ * This description is only to show some reST inline markups like *emphasise*
+ * and **emphasis strong**. The follwing is a demo of a reST list markup:
+ *
+ * Definition list:
+ * :def1: lorem
+ * :def2: ipsum
+ *
+ * Ordered List:
+ * - item one
+ * - item two
+ * - item three with
+ *   a linebreak
+ *
+ * Literal blocks:
+ * The next example shows a literal block::
+ *
+ *     +------+          +------+
+ *     |\     |\        /|     /|
+ *     | +----+-+      +-+----+ |
+ *     | |    | |      | |    | |
+ *     +-+----+ |      | +----+-+
+ *      \|     \|      |/     |/
+ *       +------+      +------+
+ *
+ * Highlighted code blocks:
+ * The next example shows a code example, with highlighting C syntax in the
+ * output.
+ *
+ * .. code-block:: c
+ *
+ *     // Hello World program
+ *
+ *     #include<stdio.h>
+ *
+ *     int main()
+ *     {
+ *         printf("Hello World");
+ *     }
+ *
+ *
+ * reST sectioning:
+ *
+ * colon markup: sectioning by colon markup in reST mode is less ugly. ;-)
+ *
+ * A kernel-doc section like *this* section is translated into a reST
+ * *subsection*. This means, you can only use the follwing *sub-levels* within a
+ * kernel-doc section.
+ *
+ * a subsubsection
+ * ^^^^^^^^^^^^^^^
+ *
+ * lorem ipsum
+ *
+ * a paragraph
+ * """""""""""
+ *
+ * lorem ipsum
+ *
+ */
+
+int rst_mode(int a, char b)
+{
+  return a + b;
+}
+
diff --git a/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.rst b/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.rst
new file mode 100644
index 0000000..17b127b
--- /dev/null
+++ b/Documentation/books/kernel-doc-HOWTO/all-in-a-tumble.rst
@@ -0,0 +1,11 @@
+.. -*- coding: utf-8; mode: rst -*-
+.. include:: refs.txt
+
+.. _all-in-a-tumble:
+
+=================
+Rendered Examples
+=================
+
+.. kernel-doc::  ./all-in-a-tumble.h
+    :module: example
diff --git a/Documentation/books/kernel-doc-HOWTO/csv_table.txt b/Documentation/books/kernel-doc-HOWTO/csv_table.txt
new file mode 100644
index 0000000..8a14541
--- /dev/null
+++ b/Documentation/books/kernel-doc-HOWTO/csv_table.txt
@@ -0,0 +1,6 @@
+stub col row 1, column, "loremLorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy
+eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam
+voluptua."
+stub col row 1, "At vero eos et accusam et justo duo dolores et ea rebum. Stet clita
+kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.", column
+stub col row 1, column, column
diff --git a/Documentation/books/kernel-doc-HOWTO/index.rst b/Documentation/books/kernel-doc-HOWTO/index.rst
new file mode 100644
index 0000000..1893303
--- /dev/null
+++ b/Documentation/books/kernel-doc-HOWTO/index.rst
@@ -0,0 +1,46 @@
+.. -*- coding: utf-8; mode: rst -*-
+.. include:: refs.txt
+
+.. _kernel-doc-howto:
+
+================
+kernel-doc HOWTO
+================
+
+In order to provide embedded, 'C' friendly, easy to maintain, but consistent and
+extractable documentation of the functions and data structures in the Linux
+kernel, the Linux kernel has adopted a consistent style for documenting
+functions and their parameters, and structures and their members.
+
+The format for this documentation is called the *kernel-doc* format. With kernel
+version 4.x the restructuredText (reST_) markup was added to the *kernel-doc*
+format. The kernel-doc parser supports the markup modes:
+:ref:`vintage-kernel-doc-mode` / :ref:`reST-kernel-doc-mode`.  This document
+gives hints on how to use these markups and how to refer and extract
+documentation from source files.
+
+The kernel-doc parser extracts the kernel-doc descriptions from the source files
+and produced reST markup as base format. With reST as base format the
+documentation building process changed also. The building process is now based
+on sphinx-doc_ and the DocBook documents will be migrated to reST gradually.
+
+.. toctree::
+    :maxdepth: 1
+
+    kernel-doc-intro
+    kernel-doc-syntax
+    vintage-kernel-doc-mode
+    reST-kernel-doc-mode
+    kernel-doc-directive
+    table-markup
+    kernel-doc-components
+    kernel-doc-examples
+
+The examples in this HOWTO using the kernel-doc comments from the example file
+:ref:`all-in-a-tumble-src`. They are rendered in the
+chapter :ref:`all-in-a-tumble`.
+
+.. only:: html
+
+  * :ref:`genindex`
+
diff --git a/Documentation/books/kernel-doc-HOWTO/kernel-doc-components.rst b/Documentation/books/kernel-doc-HOWTO/kernel-doc-components.rst
new file mode 100644
index 0000000..f515f04
--- /dev/null
+++ b/Documentation/books/kernel-doc-HOWTO/kernel-doc-components.rst
@@ -0,0 +1,35 @@
+.. -*- coding: utf-8; mode: rst -*-
+.. include:: refs.txt
+
+.. _kernel-doc-components:
+
+===================================
+Components of the kernel-doc system
+===================================
+
+Many places in the source tree have extractable kernel-doc documentation.  The
+components of this system are:
+
+Documentation/Makefile.reST and Documentation/conf.py
+  Makefile and basic `sphinx config`_ file to build the various reST documents
+  and output formats. Provides the basic sphinx-doc_ build infrastructure
+  including the *sphinx-subprojects* feature. With this feature each book can be
+  build and distributed stand-alone. Cross reference between *subprojects* will
+  be ensured by `intersphinx`_.
+
+Documentation/sphinx-static and Documentation/sphinx-tex
+  Paths that contain sphinx-doc_ custom static files (such as style sheets).
+
+Documentation/books
+  In this folder, the books with reST markup are placed. To provide
+  *sphinx-subprojects*, each book has its one folder and a (optional)
+  ``Documentation/books/{book-name}.conf`` file which *overwrites* the basic
+  configuration from ``Documentation/conf.py`` (settings see `sphinx config`_)
+
+scripts/site-python/linuxdoc
+  This folder includes python extensions related to the linux documentation
+  processes.
+
+
+
+
diff --git a/Documentation/books/kernel-doc-HOWTO/kernel-doc-directive.rst b/Documentation/books/kernel-doc-HOWTO/kernel-doc-directive.rst
new file mode 100644
index 0000000..5ae5c76
--- /dev/null
+++ b/Documentation/books/kernel-doc-HOWTO/kernel-doc-directive.rst
@@ -0,0 +1,199 @@
+.. -*- coding: utf-8; mode: rst -*-
+.. include:: refs.txt
+
+.. _kernel-doc-directive:
+
+================================
+Use kernel-doc in reST documents
+================================
+
+There exists a `reST-directive
+<http://www.sphinx-doc.org/en/stable/rest.html#directives>`_ named
+``kernel-doc`` to integrate kernel-doc comments into a reST document (e.g. in a
+*book*). The directive comes with options to fine grain control which parts
+should be placed into the reST document. With no options given, the complete
+kernel-doc comments from a source file will be inserted. So, the first and very
+simple example is:
+
+.. code-block:: rst
+
+   My Media Book
+   =============
+
+   .. kernel-doc:: include/media/media-device.h
+
+With this small example the kernel-doc comments from the media-device.h will be
+inserted direct under the chapter "My Media Book". The "DOC:" sections, the function
+and the type descriptions will be inserted in the order they appear in the source file.
+Mostly you want to select more fine grained, read on to see how.
+
+kernel-doc config
+=================
+
+Within the sphinx-doc config file (``config.py``) you can set the following
+option.
+
+kernel_doc_raise_error: ``True``
+  If true, fatal errors (like missing function descriptions) raise an error. The
+  default is ``True``. Because this might break your build process, you can
+  change the value to ``False``.
+
+  In this example, the documentation of definition ``no_longer_exists`` is
+  required.
+
+  .. code-block:: rst
+
+      .. kernel-doc::  ./all-in-a-tumble.h
+          :functions:  no_longer_exist
+
+  Since this definition not exists (anymore), the following TODO entry is
+  inserted, when ``kernel_doc_raise_error`` is ``False``.
+
+  .. kernel-doc::  ./all-in-a-tumble.h
+      :functions:  no_longer_exist
+
+
+kernel-doc options
+==================
+
+Here is a short overview of the options:
+
+.. code-block:: rst
+
+    .. kernel-doc:: <filename>
+        :doc: <section title>
+        :export:
+        :internal:
+        :functions: <function [, functions [, ...]]>
+        :module: <prefix-id>
+        :snippets:  <snippet [, snippets [, ...]]>
+        :language:  <snippet-lang>
+        :linenos:
+        :debug:
+
+The argument ``<filename>`` is required, it points to a source file in the
+kernel source tree. The pathname is relativ to kernel's root folder.  The
+options have the following meaning, but be aware that not all combinations of
+these options make sense:
+
+``doc <section title>``
+    Inserts the contents of the ``DOC:`` section titled ``<section title>``.
+    Spaces are allowed in ``<section title>``; do not quote the ``<section
+    title>``.
+
+``export``
+    Inserts the documentation of function, struct or whatever definition that is
+    exported using EXPORT_SYMBOL (``EXPORT_SYMBOL()``, ``EXPORT_SYMBOL_GPL()`` &
+    ``EXPORT_SYMBOL_GPL_FUTURE()``). Assume that a the all exported symbols are
+    documented.
+
+``internal``
+    Inserts the documentation of function, struct or whatever definition that
+    is documented, but not **not** exported using EXPORT_SYMBOL.
+
+``functions <name [, names [, ...]]>``
+    Inserts the documentation of function(s), struct(s) or whatever
+    definition(s) named ``name``.
+
+``module <prefix-id>``
+    The option ``:module: <id-prefix>`` sets a module-name. The module-name is
+    used as a prefix for automatic generated IDs (reference anchors).
+
+``snippets <name [, names [, ...]]>``
+    Inserts the source-code passage(s) marked with the snippet ``name``. The
+    snippet is inserted with a `code-block:: <http://www.sphinx-doc.org/en/stable/markup/code.html>`_
+    directive.
+
+    The next options make only sense in conjunction with option ``snippets``:
+
+    ``:language: <highlighter>``
+        Set highlighting language of the snippet code-block.
+
+    ``:linenos:``
+        Set line numbers in the snippet code-block.
+
+``debug``
+    Inserts a code-block with the generated reST source. This might somtimes
+    helpful to see how the kernel-doc parser transforms the kernel-doc markup to
+    reST markup.
+
+ducumentation blocks
+====================
+
+The following example inserts the documentation block with the title "Theory of
+Operation".
+
+.. code-block:: rst
+
+     .. kernel-doc::  ./all-in-a-tumble.h
+        :doc:  Theory of Operation
+        :module: example
+
+With the module name "example" the title refers by:
+
+.. code-block:: rst
+
+    Rendered example: :ref:`example.theory-of-operation`
+
+Rendered example: :ref:`example.theory-of-operation`
+
+functions
+=========
+
+The following example inserts the documentation of struct 'user_function'.
+
+.. code-block:: rst
+
+     .. kernel-doc:: ./all-in-a-tumble.h
+        :functions:  user_function
+        :module:     example
+
+.. code-block:: rst
+
+    * Rendered example by ID with module prefix: :ref:`example.user_function`
+    * Function reference: :c:func:`user_function`
+
+* Rendered example by ID with module prefix: :ref:`example.user_function`
+* Function reference: :c:func:`user_function`
+
+
+structs, unions, enums and typedefs
+===================================
+
+The following example inserts the documentation of struct 'my_long_struct'.
+
+.. code-block:: rst
+
+     .. kernel-doc:: ./all-in-a-tumble.h
+        :functions:  my_long_struct
+        :module:     example
+
+.. code-block:: rst
+
+    * Rendered example by ID with module prefix: :ref:`example.my_long_struct`
+    * Type reference: :c:type:`my_long_struct` or the alternativ notation
+      with title :c:type:`struct my_long_struct <my_long_struct>`
+
+* Rendered example by ID with module prefix: :ref:`example.my_long_struct`
+* Type reference: :c:type:`my_long_struct` or the alternativ notation
+  with title :c:type:`struct my_long_struct <my_long_struct>`
+
+Snippets
+========
+
+The kernel-doc Parser supports a comment-markup for
+:ref:`kernel-doc-syntax-snippets`. By example; The directive of the shown
+code-snippet below is:
+
+.. code-block:: rst
+
+     .. kernel-doc::  ./all-in-a-tumble.h
+        :snippets:  hello-world
+        :language:  c
+        :linenos:
+
+.. kernel-doc::  ./all-in-a-tumble.h
+    :snippets:  hello-world
+    :language:  c
+    :linenos:
+
diff --git a/Documentation/books/kernel-doc-HOWTO/kernel-doc-examples.rst b/Documentation/books/kernel-doc-HOWTO/kernel-doc-examples.rst
new file mode 100644
index 0000000..4c3ba3b
--- /dev/null
+++ b/Documentation/books/kernel-doc-HOWTO/kernel-doc-examples.rst
@@ -0,0 +1,16 @@
+.. -*- coding: utf-8; mode: rst -*-
+.. include:: refs.txt
+
+.. _kernel-doc-examples:
+
+=====================
+Examples & test cases
+=====================
+
+.. toctree::
+    :maxdepth: 2
+
+    all-in-a-tumble-src
+    all-in-a-tumble
+
+
diff --git a/Documentation/books/kernel-doc-HOWTO/kernel-doc-intro.rst b/Documentation/books/kernel-doc-HOWTO/kernel-doc-intro.rst
new file mode 100644
index 0000000..8cad730
--- /dev/null
+++ b/Documentation/books/kernel-doc-HOWTO/kernel-doc-intro.rst
@@ -0,0 +1,85 @@
+.. -*- coding: utf-8; mode: rst -*-
+.. include:: refs.txt
+
+.. _kernel-doc-intro:
+
+================
+kernel-doc intro
+================
+
+In order to provide good documentation of kernel functions and data structures,
+please use the following conventions to format your kernel-doc comments in Linux
+kernel source.
+
+We also look to provide kernel-doc formatted documentation for functions
+externally visible to other kernel files (not marked "static").  We also
+recommend providing kernel-doc formatted documentation for private (file
+"static") routines, for consistency of kernel source code layout.  But this is
+lower priority and at the discretion of the MAINTAINER of that kernel source
+file.  Data structures visible in kernel include files should also be documented
+using kernel-doc formatted comments.
+
+The opening comment mark ``/**`` is reserved for kernel-doc comments.  Only
+comments so marked will be considered by the kernel-doc tools, and any comment
+so marked must be in kernel-doc format. The closing comment marker for
+kernel-doc comments can be either ``*/`` or ``**/``, but ``*/`` is preferred in
+the Linux kernel tree.
+
+.. hint::
+
+  1. Do not use ``/**`` to be begin a comment block unless the comment block
+     contains kernel-doc formatted comments.
+
+  2. We definitely need kernel-doc formatted documentation for functions that
+     are exported to loadable modules using EXPORT_SYMBOL.
+
+  3. Kernel-doc comments should be placed just before the function or data
+     structure being described.
+
+
+Example kernel-doc function comment:
+
+.. code-block:: c
+
+    /**
+     * foobar() - short function description of foobar
+     * @arg1:	Describe the first argument to foobar.
+     * @arg2:	Describe the second argument to foobar.
+     *		One can provide multiple line descriptions
+     *		for arguments.
+     *
+     * A longer description, with more discussion of the function foobar()
+     * that might be useful to those using or modifying it.  Begins with
+     * empty comment line, and may include additional embedded empty
+     * comment lines.
+     *
+     * The longer description can have multiple paragraphs.
+     *
+     * Return: Describe the return value of foobar.
+     */
+
+The short description following the subject can span multiple lines and ends
+with an ``@name`` description, an empty line or the end of the comment block.
+The kernel-doc function comments describe each parameter to the function, in
+order, with the ``@name`` lines.  The ``@name`` descriptions must begin on the
+very next line following this opening short function description line, with no
+intervening empty comment lines. If a function parameter is ``...`` (varargs),
+it should be listed in kernel-doc notation as::
+
+     * @...: description
+
+The return value, if any, should be described in a dedicated section named
+``Return``. Beside functions you can also write documentation for structs,
+unions, enums and typedefs. Example kernel-doc data structure comment.::
+
+    /**
+     * struct blah - the basic blah structure
+     * @mem1:	describe the first member of struct blah
+     * @mem2:	describe the second member of struct blah,
+     *		perhaps with more lines and words.
+     *
+     * Longer description of this structure.
+     */
+
+The kernel-doc data structure comments describe each structure member in the
+data structure, with the ``@name`` lines.
diff --git a/Documentation/books/kernel-doc-HOWTO/kernel-doc-syntax.rst b/Documentation/books/kernel-doc-HOWTO/kernel-doc-syntax.rst
new file mode 100644
index 0000000..3037941
--- /dev/null
+++ b/Documentation/books/kernel-doc-HOWTO/kernel-doc-syntax.rst
@@ -0,0 +1,171 @@
+.. -*- coding: utf-8; mode: rst -*-
+.. include:: refs.txt
+
+.. _kernel-doc-syntax:
+
+==================
+kernel-doc syntax
+==================
+
+In the following examples,
+
+* ``(...)?`` signifies optional structure and
+* ``(...)*`` signifies 0 or more structure elements
+
+The definition (or DOC) name is the section header. The section header names
+must be unique per source file.
+
+.. _kernel-doc-syntax-functions:
+
+functions
+=========
+
+The format of the block comment is like this::
+
+    /**
+     * function_name(:)? (- short description)?
+    (* @parameterx: (description of parameter x)?)*
+    (* a blank line)?
+     * (Description:)? (Description of function)?
+     * (section header: (section description)? )*
+     (*)?*/
+
+All *description* text can span multiple lines, although the
+``function_name`` & its short description are traditionally on a single line.
+Description text may also contain blank lines (i.e., lines that contain only a
+"*").
+
+.. ????
+.. Avoid putting a spurious blank line after the function name, or else the
+.. description will be repeated!
+.. ????
+
+So, the trivial example would be:
+
+.. code-block:: c
+
+    /**
+     * my_function
+     */
+
+If the Description: header tag is omitted, then there must be a blank line
+after the last parameter specification.:
+
+.. code-block:: c
+
+    /**
+     * my_function - does my stuff
+     * @my_arg: its mine damnit
+     *
+     * Does my stuff explained.
+     */
+
+or, could also use:
+
+.. code-block:: c
+
+    /**
+     * my_function - does my stuff
+     * @my_arg: its mine damnit
+     * Description: Does my stuff explained.
+     */
+
+You can also add additional sections. When documenting kernel functions you
+should document the ``Context:`` of the function, e.g. whether the functions can
+be called form interrupts. Unlike other sections you can end it with an empty
+line.
+
+A non-void function should have a ``Return:`` section describing the return
+value(s).  Example-sections should contain the string ``EXAMPLE`` so that
+they are marked appropriately in the output format.
+
+.. kernel-doc::  ./all-in-a-tumble.h
+    :snippets:  user_function
+    :language:  c
+    :linenos:
+
+Rendered example: :ref:`example.user_function`
+
+.. _kernel-doc-syntax-misc-types:
+
+structs, unions, enums and typedefs
+===================================
+
+Beside functions you can also write documentation for structs, unions, enums and
+typedefs. Instead of the function name you must write the name of the
+declaration; the ``struct``, ``union``, ``enum`` or ``typedef`` must always
+precede the name. Nesting of declarations is not supported.  Use the
+``@argument`` mechanism to document members or constants.
+
+Inside a struct description, you can use the 'private:' and 'public:' comment
+tags.  Structure fields that are inside a 'private:' area are not listed in the
+generated output documentation.  The 'private:' and 'public:' tags must begin
+immediately following a ``/*`` comment marker.  They may optionally include
+comments between the ``:`` and the ending ``*/`` marker.
+
+.. kernel-doc::  ./all-in-a-tumble.h
+    :snippets:  my_struct
+    :language:  c
+    :linenos:
+
+Rendered example: :ref:`example.my_struct`
+
+All descriptions can be multiline, except the short function description.
+For really longs structs, you can also describe arguments inside the body of
+the struct.
+
+.. kernel-doc::  ./all-in-a-tumble.h
+    :snippets:  my_long_struct
+    :language:  c
+    :linenos:
+
+Rendered example: :ref:`example.my_long_struct`
+
+This should be used only for struct and enum members.
+
+.. _kernel-doc-syntax-doc:
+
+ducumentation blocks
+====================
+
+To facilitate having source code and comments close together, you can include
+kernel-doc documentation blocks that are *free-form* comments instead of being
+kernel-doc for functions, structures, unions, enums, or typedefs.  This could be
+used for something like a theory of operation for a driver or library code, for
+example.
+
+This is done by using a ``DOC:`` section keyword with a section title. A small
+example:
+
+.. kernel-doc::  ./all-in-a-tumble.h
+    :snippets:  theory-of-operation
+    :language:  c
+    :linenos:
+
+Rendered example: :ref:`example.theory-of-operation`
+
+.. _kernel-doc-syntax-snippets:
+
+Snippets
+========
+
+The kernel-doc Parser supports a comment-markup for snippets out of the source
+code. To start a region to snip insert::
+
+  /* parse-SNIP: <snippet-name> */
+
+The snippet region stops with a new snippet region or at the next::
+
+  /* parse-SNAP: */
+
+A small example:
+
+.. code-block:: c
+
+    /* parse-SNIP: hello-world */
+    #include<stdio.h>
+    int main() {
+        printf("Hello World\n");
+    return 0;
+    }
+    /* parse-SNAP: */
diff --git a/Documentation/books/kernel-doc-HOWTO/reST-kernel-doc-mode.rst b/Documentation/books/kernel-doc-HOWTO/reST-kernel-doc-mode.rst
new file mode 100644
index 0000000..5cfe59f
--- /dev/null
+++ b/Documentation/books/kernel-doc-HOWTO/reST-kernel-doc-mode.rst
@@ -0,0 +1,120 @@
+.. -*- coding: utf-8; mode: rst -*-
+.. include:: refs.txt
+
+.. _reST-kernel-doc-mode:
+
+====================
+reST kernel-doc mode
+====================
+
+To get in use of the fully reST_ add the following comment (e.g.) at the top of
+your source code file (or at any line reST content starts).::
+
+    /* parse-markup: reST */
+
+In reST mode the kernel-doc parser pass through all text / markups unchanged to
+the reST toolchain including any whitespace.  To toggle back to
+:ref:`vintage-kernel-doc-mode` type the following line::
+
+    /* parse-markup: kernel-doc */
+
+Within reST mode, most of the *vintage* kernel-doc markup -- as described in
+:ref:`kernel-doc-syntax` -- stays unchanged, except the vintage-highlighting
+markup and the treatment of whitespaces in description blocks. The *vintage
+highlighting* markup is not supported in reST mode, because it conflicts with
+the reST markup syntax.
+
+The reST syntax brings it's own markup to refer and highlight function,
+structs or whatever definition e.g.:
+
+* functions ...
+
+  .. code-block:: rst
+
+     :c:func:`foo_func`
+
+* structs ...
+
+  .. code-block:: rst
+
+     :c:type:`stuct foo_struct`
+
+If you are familiar with the vintage style, first this might be a cons-change
+for you, but take in account, that you get a expressive ASCII markup on the
+pro-side.
+
+
+reST section structure
+======================
+
+Since a section title in reST mode needs a line break after the colon, the colon
+handling is less ugly (:ref:`vintage-mode-quirks`).  E.g.::
+
+    prints out: hello world
+
+is rendered as expected in one line. If non text follows the colon, a section
+is inserted. To avoid sectioning in any case, place a space in front of the column.::
+
+   lorem list :
+
+   * lorem
+   * ipsum
+
+On the opposite, super-short sections like::
+
+    Return: sum of a and b
+
+are no longer supported, you have to enter at least one line break::
+
+    Return:
+    sum of a and b
+
+Beside these *sectioning* of the kernel-doc syntax, reST has it's own chapter,
+section etc. markup (e.g. see `Sections
+<http://www.sphinx-doc.org/en/stable/rest.html#sections>`_). Normally, there are
+no heading levels assigned to certain characters as the structure is determined
+from the succession of headings. However, there is a common convention, which is
+used by the kernel-doc parser also:
+
+* ``#`` with overline, for parts
+* ``*`` with overline, for chapters
+* ``=`` for sections
+* ``-`` for subsections
+* ``^`` for subsubsections
+* ``"`` for paragraphs
+
+Within kernel-doc comments you should use this sectioning with care. A
+kernel-doc section like the "Return" section above is translated into a reST
+section with the following markup.
+
+.. code-block:: rst
+
+    Return
+    ------
+
+    sum of a and b
+
+As you see, a kernel-doc section is at reST *subsection* level. This means, you
+can only use the following *sub-levels* within a kernel-doc section.
+
+* ``^`` for subsubsections
+* ``"`` for paragraphs
+
+
+further references
+==================
+
+Here are some handy links about reST_  and the `Sphinx markup constructs`_:
+
+* reST_ primer, `reST (quickref)`_, `reST (spec)`_
+* `Sphinx markup constructs`_
+* `sphinx domains`_
+* `sphinx cross refences`_
+* `intersphinx`_, `sphinx.ext.intersphinx`_
+* `sphinx-doc`_, `sphinx-doc FAQ`_
+* `docutils`_, `docutils FAQ`_
+
+In absence of a more detailed C style guide for documentation, the `Python's
+Style Guide for documentating
+<https://docs.python.org/devguide/documenting.html#style-guide>`_ provides a
+good orientation.
diff --git a/Documentation/books/kernel-doc-HOWTO/refs.txt b/Documentation/books/kernel-doc-HOWTO/refs.txt
new file mode 100644
index 0000000..6d96765
--- /dev/null
+++ b/Documentation/books/kernel-doc-HOWTO/refs.txt
@@ -0,0 +1,15 @@
+.. _`reST (spec)`: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
+.. _`reST (quickref)`: http://docutils.sourceforge.net/docs/user/rst/quickref.html
+
+.. _`reST`: http://www.sphinx-doc.org/en/stable/rest.html
+.. _`Sphinx markup constructs`: http://www.sphinx-doc.org/en/stable/markup/index.html
+.. _`sphinx-doc`: http://www.sphinx-doc.org/
+.. _`sphinx-doc FAQ`: http://www.sphinx-doc.org/en/stable/faq.html
+.. _`sphinx domains`: http://www.sphinx-doc.org/en/stable/domains.html
+.. _`sphinx cross refences`: http://www.sphinx-doc.org/en/stable/markup/inline.html#cross-referencing-arbitrary-locations
+.. _`sphinx.ext.intersphinx`: http://www.sphinx-doc.org/en/stable/ext/intersphinx.html#module-sphinx.ext.intersphinx
+.. _`intersphinx`: http://www.sphinx-doc.org/en/stable/ext/intersphinx.html
+.. _`sphinx config`: http://www.sphinx-doc.org/en/stable/config.html
+
+.. _`docutils`: http://docutils.sourceforge.net/docs/index.html
+.. _`docutils FAQ`: http://docutils.sourceforge.net/FAQ.html
diff --git a/Documentation/books/kernel-doc-HOWTO/table-markup.rst b/Documentation/books/kernel-doc-HOWTO/table-markup.rst
new file mode 100644
index 0000000..38a6de0
--- /dev/null
+++ b/Documentation/books/kernel-doc-HOWTO/table-markup.rst
@@ -0,0 +1,499 @@
+.. -*- coding: utf-8; mode: rst -*-
+
+.. _`Emacs Table Mode`: https://www.emacswiki.org/emacs/TableMode
+.. _`Online Tables Generator`: http://www.tablesgenerator.com/text_tables
+.. _`OASIS XML Exchange Table Model`: https://www.oasis-open.org/specs/tm9901.html
+
+
+.. _xref_table_concerns:
+
+============
+About tables
+============
+
+First: the rest-flat-table_ directive is preferred in the Linux kernel tree.
+
+Internaly, the docutils uses a representation according to the `OASIS XML
+Exchange Table Model`_ (same as DocBook). The *OASIS Table Model* gives a huge
+bandwith of possibilities to form tables. This often seduce authors to force a
+specific layout. Misuse of tables in this manner is not recommended, because it
+breaks the separation of *presentation from content* which most often ends in
+problems in range of output formats. Tables (and preformated text like source
+code listings) should be used advisedly. In a HTML output, the horizontal and
+vertical expansion is handled by a scrollbar. On print medias (paper / pdf)
+there is no scrollbar, automaticaly (page-) breaking a table (or line-breaking a
+preformated text) in the layout process ends mostly in a unwanted results.
+
+.. hint::
+
+  Tables and preformated text in itself violate the separation of *presentation
+  from content*, but we will never be able to entirely renounce them. Use them
+  with care, if your content should be rendered well, in wide variation of
+  output formats.
+
+
+ASCII-art tables
+================
+
+ASCII-art tables might be comfortable for readers of the text-files, but they
+have huge disadvantages in the creation and modifying. First, they are hard to
+edit. Think about adding a row or a column to a ASCII-art table or adding a
+paraggraph in a cell, it is a nightmare on big tables. Second the diff of
+modifing ASCII-art tables is not meaningfull, e.g. widening a cell generates a
+diff in which also changes are included, which are only ascribable to the
+ASCII-art (see also :ref:`list-table-directives`).
+
+* `Emacs Table Mode`_
+* `Online Tables Generator`_
+
+
+Simple tables
+-------------
+
+simple tables allow *colspan* but not *rowspan*:
+
+..  code-block:: none
+
+  ====== ====== ======
+      Inputs    Output
+  ------------- ------
+  A      B      A or B
+  ====== ====== ======
+  False
+  --------------------
+  True
+  --------------------
+  True   False  True
+  ------ ------ ------
+  False  True
+  ====== =============
+
+Rendered as:
+
+====== ====== ======
+    Inputs    Output
+------------- ------
+A      B      A or B
+====== ====== ======
+False
+--------------------
+True
+--------------------
+True   False  True
+------ ------ ------
+False  True
+====== =============
+
+
+Grid tables
+-----------
+
+grid tables allow colspan *colspan* and *rowspan*:
+
+.. code-block:: rst
+
+   +------------+------------+-----------+
+   | Header 1   | Header 2   | Header 3  |
+   +============+============+===========+
+   | body row 1 | column 2   | column 3  |
+   +------------+------------+-----------+
+   | body row 2 | Cells may span columns.|
+   +------------+------------+-----------+
+   | body row 3 | Cells may  | - Cells   |
+   +------------+ span rows. | - contain |
+   | body row 4 |            | - blocks. |
+   +------------+------------+-----------+
+
+Rendered as:
+
++------------+------------+-----------+
+| Header 1   | Header 2   | Header 3  |
++============+============+===========+
+| body row 1 | column 2   | column 3  |
++------------+------------+-----------+
+| body row 2 | Cells may span columns.|
++------------+------------+-----------+
+| body row 3 | Cells may  | - Cells   |
++------------+ span rows. | - contain |
+| body row 4 |            | - blocks. |
++------------+------------+-----------+
+
+.. _list-table-directives:
+
+List table directives
+=====================
+
+The *list table* formats are double stage list, compared to the ASCII-art they
+migth not be as comfortable for readers of the text-files. Their advantage is,
+that they are easy to create/modify and that the diff of a modification is much
+more meaningfull, because it is limited to the modified content.
+
+.. _rest-list-table:
+
+list-table
+----------
+
+The ``list-tables`` has no ability to *colspan* nor *rowspan*:
+
+.. code-block:: rst
+
+   .. list-table:: table title
+      :header-rows: 1
+      :stub-columns: 1
+
+      * - ..
+        - head col 1
+        - head col 2
+
+      * - stub col row 1
+        - column
+        - column
+
+      * - stub col row 2
+        - column
+        - column
+
+      * - stub col row 3
+        - column
+        - column
+
+
+Rendered as:
+
+.. list-table:: table title
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - ..
+     - head col 1
+     - head col 2
+
+   * - stub col row 1
+     - column
+     - column
+
+   * - stub col row 2
+     - column
+     - column
+
+   * - stub col row 3
+     - column
+     - column
+
+.. _rest-flat-table:
+
+flat-table
+----------
+
+The ``flat-table`` (:py:class:`FlatTable`) is a double-stage list similar
+to the ``list-table`` with some additional features:
+
+* *column-span*: with the role ``cspan`` a cell can be extended through
+   additional columns
+
+* *row-span*: with the role ``rspan`` a cell can be extended through
+   additional rows
+
+* *auto span* rightmost cell of a table row over the missing cells on the right
+  side of that table-row.  With Option ``:fill-cells:`` this behavior can
+  changed from *auto span* to *auto fill*, which automaticly inserts (empty)
+  cells instead of spanning the last cell.
+
+options:
+
+:header-rows:   [int] count of header rows
+:stub-columns:  [int] count of stub columns
+:widths:        [[int] [int] ... ] widths of columns
+:fill-cells:    instead of autospann missing cells, insert missing cells
+
+roles:
+
+:cspan: [int] additionale columns (*morecols*)
+:rspan: [int] additionale rows (*morerows*)
+
+The example below shows how to use this markup.  The first level of the staged
+list is the *table-row*. In the *table-row* there is only one markup allowed,
+the list of the cells in this *table-row*. Exception are *comments* ( ``..`` )
+and *targets* (e.g. a ref to :ref:`row 2 of table's body <row body 2>`).
+
+.. code-block:: rst
+
+   .. flat-table:: table title
+      :header-rows: 2
+      :stub-columns: 1
+      :widths: 1 1 1 1 2
+
+      * - :rspan:`1` head / stub
+        - :cspan:`3` head 1.1-4
+
+      * - head 2.1
+        - head 2.2
+        - head 2.3
+        - head 2.4
+
+      * .. row body 1 / this is a comment
+
+        - row 1
+        - :rspan:`2` cell 1-3.1
+        - cell 1.2
+        - cell 1.3
+        - cell 1.4
+
+      * .. Comments and targets are allowed on *table-row* stage.
+        .. _`row body 2`:
+
+        - row 2
+        - cell 2.2
+        - :rspan:`1` :cspan:`1`
+          cell 2.3 with a span over
+
+          * col 3-4 &
+          * row 2-3
+
+      * - row 3
+        - cell 3.2
+
+      * - row 4
+        - cell 4.1
+        - cell 4.2
+        - cell 4.3
+        - cell 4.4
+
+      * - row 5
+        - cell 5.1 with automatic span to rigth end
+
+      * - row 6
+        - cell 6.1
+        - ..
+
+
+Rendered as:
+
+ .. flat-table:: table title
+    :header-rows: 2
+    :stub-columns: 1
+    :widths: 1 1 1 1 2
+
+    * - :rspan:`1` head / stub
+      - :cspan:`3` head 1.1-4
+
+    * - head 2.1
+      - head 2.2
+      - head 2.3
+      - head 2.4
+
+    * .. row body 1 / this is a comment
+
+      - row 1
+      - :rspan:`2` cell 1-3.1
+      - cell 1.2
+      - cell 1.3
+      - cell 1.4
+
+    * .. Comments and targets are allowed on *table-row* stage.
+      .. _`row body 2`:
+
+      - row 2
+      - cell 2.2
+      - :rspan:`1` :cspan:`1`
+        cell 2.3 with a span over
+
+        * col 3-4 &
+        * row 2-3
+
+    * - row 3
+      - cell 3.2
+
+    * - row 4
+      - cell 4.1
+      - cell 4.2
+      - cell 4.3
+      - cell 4.4
+
+    * - row 5
+      - cell 5.1 with automatic span to rigth end
+
+    * - row 6
+      - cell 6.1
+      - ..
+
+
+CSV table
+=========
+
+CSV table might be the choice if you want to include CSV-data from a outstanding
+(build) process into your documentation.
+
+.. code-block:: rst
+
+   .. csv-table:: table title
+      :header: , Header1, Header2
+      :widths: 15, 10, 30
+      :stub-columns: 1
+      :file: csv_table.txt
+
+Content of file ``csv_table.txt``:
+
+.. literalinclude:: csv_table.txt
+
+Rendered as:
+
+.. csv-table:: table title
+   :header: , Header1, Header2
+   :widths: 15, 10, 30
+   :stub-columns: 1
+   :file: csv_table.txt
+
+
+Nested Tables
+=============
+
+Nested tables are ugly, don't use them! This part here is only to show what you
+should never do. They are ugly because they cause huge problems in many output
+formats and there is always no need for nested tables.
+
+.. code-block:: rst
+
+   +-----------+----------------------------------------------------+
+   | W/NW cell | N/NE cell                                          |
+   |           +-------------+--------------------------+-----------+
+   |           | W/NW center | N/NE center              | E/SE cell |
+   |           |             +------------+-------------+           |
+   |           |             | +--------+ | E/SE center |           |
+   |           |             | | nested | |             |           |
+   |           |             | +--------+ |             |           |
+   |           |             | | table  | |             |           |
+   |           |             | +--------+ |             |           |
+   |           +-------------+------------+             |           |
+   |           | S/SE center              |             |           |
+   +-----------+--------------------------+-------------+           |
+   | S/SW cell                                          |           |
+   +----------------------------------------------------+-----------+
+
+Rendered as: Not supported by all sphinx-builders, don't use nested tables!!!
+
+
+raw HTML tables
+===============
+
+If HTML is the only format you want to render, you could use a raw-import of a
+HTML table markup. But be aware, this breaks the separation of *presentation from
+content*. HTML-Tables are only rendered within a HTML output.
+
+.. code-block:: html
+
+   <div class="wy-table-responsive">
+   <table class="docutils">
+     <thead>
+       <tr style="font-weight: bold;">
+	 <td>Owner Module/Drivers</td>
+	 <td>Group</td>
+	 <td>Property Name</td>
+	 <td>Type</td>
+	 <td>Property Values</td>
+	 <td>Object attached</td>
+	 <td>Description/Restrictions</td>
+       </tr>
+     </thead>
+     <tbody>
+       <tr>
+	 <td rowspan="4">DRM</td>
+	 <td>Generic</td>
+	 <td>"rotation"</td>
+	 <td>BITMASK</td>
+	 <td>{ 0, "rotate-0" }, { 1, "rotate-90" }, { 2, "rotate-180" }, { 3,
+	   "rotate-270" }, { 4, "reflect-x" }, { 5, "reflect-y" }</td>
+	 <td>CRTC, Plane</td>
+	 <td>rotate-(degrees) rotates the image by the specified amount in
+	  degrees in counter clockwise direction. reflect-x and reflect-y
+	  reflects the image along the specified axis prior to rotation</td>
+       </tr>
+
+       <tr>
+	 <td rowspan="3">Connector</td>
+	 <td>"EDID"</td>
+	 <td>BLOB | IMMUTABLE</td>
+	 <td>0</td>
+	 <td>Connector</td>
+	 <td>Contains id of edid blob ptr object.</td>
+       </tr>
+
+       <tr>
+	 <td>"DPMS"</td>
+	 <td>ENUM</td>
+	 <td>{ "On", "Standby", "Suspend", "Off" }</td>
+	 <td>Connector</td>
+	 <td>Contains DPMS operation mode value.</td>
+       </tr>
+
+       <tr>
+	 <td>"PATH"</td>
+	 <td>BLOB | IMMUTABLE</td>
+	 <td>0</td>
+	 <td>Connector</td>
+	 <td>Contains topology path to a connector.</td>
+       </tr>
+     </tbody>
+   </table>
+   </div>
+
+
+
+.. raw:: html
+
+   <div class="wy-table-responsive">
+   <table class="docutils">
+     <thead>
+       <tr style="font-weight: bold;">
+	 <td>Owner Module/Drivers</td>
+	 <td>Group</td>
+	 <td>Property Name</td>
+	 <td>Type</td>
+	 <td>Property Values</td>
+	 <td>Object attached</td>
+	 <td>Description/Restrictions</td>
+       </tr>
+     </thead>
+     <tbody>
+       <tr>
+	 <td rowspan="4">DRM</td>
+	 <td>Generic</td>
+	 <td>"rotation"</td>
+	 <td>BITMASK</td>
+	 <td>{ 0, "rotate-0" }, { 1, "rotate-90" }, { 2, "rotate-180" }, { 3,
+	   "rotate-270" }, { 4, "reflect-x" }, { 5, "reflect-y" }</td>
+	 <td>CRTC, Plane</td>
+	 <td>rotate-(degrees) rotates the image by the specified amount in
+	  degrees in counter clockwise direction. reflect-x and reflect-y
+	  reflects the image along the specified axis prior to rotation</td>
+       </tr>
+
+       <tr>
+	 <td rowspan="3">Connector</td>
+	 <td>"EDID"</td>
+	 <td>BLOB | IMMUTABLE</td>
+	 <td>0</td>
+	 <td>Connector</td>
+	 <td>Contains id of edid blob ptr object.</td>
+       </tr>
+
+       <tr>
+	 <td>"DPMS"</td>
+	 <td>ENUM</td>
+	 <td>{ "On", "Standby", "Suspend", "Off" }</td>
+	 <td>Connector</td>
+	 <td>Contains DPMS operation mode value.</td>
+       </tr>
+
+       <tr>
+	 <td>"PATH"</td>
+	 <td>BLOB | IMMUTABLE</td>
+	 <td>0</td>
+	 <td>Connector</td>
+	 <td>Contains topology path to a connector.</td>
+       </tr>
+     </tbody>
+   </table>
+   </div>
+
+.. include:: refs.txt
diff --git a/Documentation/books/kernel-doc-HOWTO/test/parser_test.h b/Documentation/books/kernel-doc-HOWTO/test/parser_test.h
new file mode 100644
index 0000000..455b74c
--- /dev/null
+++ b/Documentation/books/kernel-doc-HOWTO/test/parser_test.h
@@ -0,0 +1,332 @@
+/* parse-markup: kernel-doc */
+
+/**
+ * struct v4l2_subdev_core_ops - Define core ops callbacks for subdevs
+ *
+ * @log_status: callback for VIDIOC_LOG_STATUS ioctl handler code.
+ *
+ * @s_io_pin_config: configure one or more chip I/O pins for chips that
+ *      multiplex different internal signal pads out to IO pins.  This function
+ *      takes a pointer to an array of 'n' pin configuration entries, one for
+ *      each pin being configured.  This function could be called at times
+ *      other than just subdevice initialization.
+ *
+ * @init: initialize the sensor registers to some sort of reasonable default
+ *      values. Do not use for new drivers and should be removed in existing
+ *      drivers.
+ *
+ * @load_fw: load firmware.
+ *
+ * @reset: generic reset command. The argument selects which subsystems to
+ *      reset. Passing 0 will always reset the whole chip. Do not use for new
+ *      drivers without discussing this first on the linux-media mailinglist.
+ *      There should be no reason normally to reset a device.
+ *
+ * @s_gpio: set GPIO pins. Very simple right now, might need to be extended with
+ *      a direction argument if needed.
+ *
+ * @queryctrl: callback for VIDIOC_QUERYCTL ioctl handler code.
+ *
+ * @g_ctrl: callback for VIDIOC_G_CTRL ioctl handler code.
+ *
+ * @s_ctrl: callback for VIDIOC_S_CTRL ioctl handler code.
+ *
+ * @g_ext_ctrls: callback for VIDIOC_G_EXT_CTRLS ioctl handler code.
+ *
+ * @s_ext_ctrls: callback for VIDIOC_S_EXT_CTRLS ioctl handler code.
+ *
+ * @try_ext_ctrls: callback for VIDIOC_TRY_EXT_CTRLS ioctl handler code.
+ *
+ * @querymenu: callback for VIDIOC_QUERYMENU ioctl handler code.
+ *
+ * @ioctl: called at the end of ioctl() syscall handler at the V4L2 core.
+ *         used to provide support for private ioctls used on the driver.
+ *
+ * @compat_ioctl32: called when a 32 bits application uses a 64 bits Kernel,
+ *                  in order to fix data passed from/to userspace.
+ *
+ * @g_register: callback for VIDIOC_G_REGISTER ioctl handler code.
+ *
+ * @s_register: callback for VIDIOC_G_REGISTER ioctl handler code.
+ *
+ * @s_power: puts subdevice in power saving mode (on == 0) or normal operation
+ *      mode (on == 1).
+ *
+ * @interrupt_service_routine: Called by the bridge chip's interrupt service
+ *      handler, when an interrupt status has be raised due to this subdev,
+ *      so that this subdev can handle the details.  It may schedule work to be
+ *      performed later.  It must not sleep.  *Called from an IRQ context*.
+ *
+ * @subscribe_event: used by the drivers to request the control framework that
+ *                   for it to be warned when the value of a control changes.
+ *
+ * @unsubscribe_event: remove event subscription from the control framework.
+ *
+ * @registered_async: the subdevice has been registered async.
+ *
+ * This is a copy&paste of a more complexe struct, just for testing.
+ */
+struct v4l2_subdev_core_ops {
+        int (*log_status)(struct v4l2_subdev *sd);
+        int (*s_io_pin_config)(struct v4l2_subdev *sd, size_t n,
+                                      struct v4l2_subdev_io_pin_config *pincfg);
+        int (*init)(struct v4l2_subdev *sd, u32 val);
+        int (*load_fw)(struct v4l2_subdev *sd);
+        int (*reset)(struct v4l2_subdev *sd, u32 val);
+        int (*s_gpio)(struct v4l2_subdev *sd, u32 val);
+        int (*queryctrl)(struct v4l2_subdev *sd, struct v4l2_queryctrl *qc);
+        int (*g_ctrl)(struct v4l2_subdev *sd, struct v4l2_control *ctrl);
+        int (*s_ctrl)(struct v4l2_subdev *sd, struct v4l2_control *ctrl);
+        int (*g_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls);
+        int (*s_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls);
+        int (*try_ext_ctrls)(struct v4l2_subdev *sd, struct v4l2_ext_controls *ctrls);
+        int (*querymenu)(struct v4l2_subdev *sd, struct v4l2_querymenu *qm);
+        long (*ioctl)(struct v4l2_subdev *sd, unsigned int cmd, void *arg);
+#ifdef CONFIG_COMPAT
+        long (*compat_ioctl32)(struct v4l2_subdev *sd, unsigned int cmd,
+                               unsigned long arg);
+#endif
+#ifdef CONFIG_VIDEO_ADV_DEBUG
+        int (*g_register)(struct v4l2_subdev *sd, struct v4l2_dbg_register *reg);
+        int (*s_register)(struct v4l2_subdev *sd, const struct v4l2_dbg_register *reg);
+#endif
+        int (*s_power)(struct v4l2_subdev *sd, int on);
+        int (*interrupt_service_routine)(struct v4l2_subdev *sd,
+                                                u32 status, bool *handled);
+        int (*subscribe_event)(struct v4l2_subdev *sd, struct v4l2_fh *fh,
+                               struct v4l2_event_subscription *sub);
+        int (*unsubscribe_event)(struct v4l2_subdev *sd, struct v4l2_fh *fh,
+                                 struct v4l2_event_subscription *sub);
+        int (*registered_async)(struct v4l2_subdev *sd);
+};
+
+/**
+ * DOC: Media Controller
+ *
+ * The media controller userspace API is documented in DocBook format in
+ * Documentation/DocBook/media/v4l/media-controller.xml. This document focus
+ * on the kernel-side implementation of the media framework.
+ *
+ * * Abstract media device model:
+ *
+ * Discovering a device internal topology, and configuring it at runtime, is one
+ * of the goals of the media framework. To achieve this, hardware devices are
+ * modelled as an oriented graph of building blocks called entities connected
+ * through pads.
+ *
+ * An entity is a basic media hardware building block. It can correspond to
+ * a large variety of logical blocks such as physical hardware devices
+ * (CMOS sensor for instance), logical hardware devices (a building block
+ * in a System-on-Chip image processing pipeline), DMA channels or physical
+ * connectors.
+ *
+ * A pad is a connection endpoint through which an entity can interact with
+ * other entities. Data (not restricted to video) produced by an entity
+ * flows from the entity's output to one or more entity inputs. Pads should
+ * not be confused with physical pins at chip boundaries.
+ *
+ * A link is a point-to-point oriented connection between two pads, either
+ * on the same entity or on different entities. Data flows from a source
+ * pad to a sink pad.
+ *
+ *
+ * * Media device:
+ *
+ * A media device is represented by a struct &media_device instance, defined in
+ * include/media/media-device.h. Allocation of the structure is handled by the
+ * media device driver, usually by embedding the &media_device instance in a
+ * larger driver-specific structure.
+ *
+ * Drivers register media device instances by calling
+ *	__media_device_register() via the macro media_device_register()
+ * and unregistered by calling
+ *	media_device_unregister().
+ *
+ * * Entities, pads and links:
+ *
+ * - Entities
+ *
+ * Entities are represented by a struct &media_entity instance, defined in
+ * include/media/media-entity.h. The structure is usually embedded into a
+ * higher-level structure, such as a v4l2_subdev or video_device instance,
+ * although drivers can allocate entities directly.
+ *
+ * Drivers initialize entity pads by calling
+ *	media_entity_pads_init().
+ *
+ * Drivers register entities with a media device by calling
+ *	media_device_register_entity()
+ * and unregistred by calling
+ *	media_device_unregister_entity().
+ *
+ * - Interfaces
+ *
+ * Interfaces are represented by a struct &media_interface instance, defined in
+ * include/media/media-entity.h. Currently, only one type of interface is
+ * defined: a device node. Such interfaces are represented by a struct
+ * &media_intf_devnode.
+ *
+ * Drivers initialize and create device node interfaces by calling
+ *	media_devnode_create()
+ * and remove them by calling:
+ *	media_devnode_remove().
+ *
+ * - Pads
+ *
+ * Pads are represented by a struct &media_pad instance, defined in
+ * include/media/media-entity.h. Each entity stores its pads in a pads array
+ * managed by the entity driver. Drivers usually embed the array in a
+ * driver-specific structure.
+ *
+ * Pads are identified by their entity and their 0-based index in the pads
+ * array.
+ * Both information are stored in the &media_pad structure, making the
+ * &media_pad pointer the canonical way to store and pass link references.
+ *
+ * Pads have flags that describe the pad capabilities and state.
+ *
+ *	%MEDIA_PAD_FL_SINK indicates that the pad supports sinking data.
+ *	%MEDIA_PAD_FL_SOURCE indicates that the pad supports sourcing data.
+ *
+ * NOTE: One and only one of %MEDIA_PAD_FL_SINK and %MEDIA_PAD_FL_SOURCE must
+ * be set for each pad.
+ *
+ * - Links
+ *
+ * Links are represented by a struct &media_link instance, defined in
+ * include/media/media-entity.h. There are two types of links:
+ *
+ * 1. pad to pad links:
+ *
+ * Associate two entities via their PADs. Each entity has a list that points
+ * to all links originating at or targeting any of its pads.
+ * A given link is thus stored twice, once in the source entity and once in
+ * the target entity.
+ *
+ * Drivers create pad to pad links by calling:
+ *	media_create_pad_link() and remove with media_entity_remove_links().
+ *
+ * 2. interface to entity links:
+ *
+ * Associate one interface to a Link.
+ *
+ * Drivers create interface to entity links by calling:
+ *	media_create_intf_link() and remove with media_remove_intf_links().
+ *
+ * NOTE:
+ *
+ * Links can only be created after having both ends already created.
+ *
+ * Links have flags that describe the link capabilities and state. The
+ * valid values are described at media_create_pad_link() and
+ * media_create_intf_link().
+ *
+ * Graph traversal:
+ *
+ * The media framework provides APIs to iterate over entities in a graph.
+ *
+ * To iterate over all entities belonging to a media device, drivers can use
+ * the media_device_for_each_entity macro, defined in
+ * include/media/media-device.h.
+ *
+ * 	struct media_entity *entity;
+ *
+ * 	media_device_for_each_entity(entity, mdev) {
+ * 		// entity will point to each entity in turn
+ * 		...
+ * 	}
+ *
+ * Drivers might also need to iterate over all entities in a graph that can be
+ * reached only through enabled links starting at a given entity. The media
+ * framework provides a depth-first graph traversal API for that purpose.
+ *
+ * Note that graphs with cycles (whether directed or undirected) are *NOT*
+ * supported by the graph traversal API. To prevent infinite loops, the graph
+ * traversal code limits the maximum depth to MEDIA_ENTITY_ENUM_MAX_DEPTH,
+ * currently defined as 16.
+ *
+ * Drivers initiate a graph traversal by calling
+ *	media_entity_graph_walk_start()
+ *
+ * The graph structure, provided by the caller, is initialized to start graph
+ * traversal at the given entity.
+ *
+ * Drivers can then retrieve the next entity by calling
+ *	media_entity_graph_walk_next()
+ *
+ * When the graph traversal is complete the function will return NULL.
+ *
+ * Graph traversal can be interrupted at any moment. No cleanup function call
+ * is required and the graph structure can be freed normally.
+ *
+ * Helper functions can be used to find a link between two given pads, or a pad
+ * connected to another pad through an enabled link
+ *	media_entity_find_link() and media_entity_remote_pad()
+ *
+ * Use count and power handling:
+ *
+ * Due to the wide differences between drivers regarding power management
+ * needs, the media controller does not implement power management. However,
+ * the &media_entity structure includes a use_count field that media drivers
+ * can use to track the number of users of every entity for power management
+ * needs.
+ *
+ * The &media_entity.@use_count field is owned by media drivers and must not be
+ * touched by entity drivers. Access to the field must be protected by the
+ * &media_device.@graph_mutex lock.
+ *
+ * Links setup:
+ *
+ * Link properties can be modified at runtime by calling
+ *	media_entity_setup_link()
+ *
+ * Pipelines and media streams:
+ *
+ * When starting streaming, drivers must notify all entities in the pipeline to
+ * prevent link states from being modified during streaming by calling
+ *	media_entity_pipeline_start().
+ *
+ * The function will mark all entities connected to the given entity through
+ * enabled links, either directly or indirectly, as streaming.
+ *
+ * The &media_pipeline instance pointed to by the pipe argument will be stored
+ * in every entity in the pipeline. Drivers should embed the &media_pipeline
+ * structure in higher-level pipeline structures and can then access the
+ * pipeline through the &media_entity pipe field.
+ *
+ * Calls to media_entity_pipeline_start() can be nested. The pipeline pointer
+ * must be identical for all nested calls to the function.
+ *
+ * media_entity_pipeline_start() may return an error. In that case, it will
+ * clean up any of the changes it did by itself.
+ *
+ * When stopping the stream, drivers must notify the entities with
+ *	media_entity_pipeline_stop().
+ *
+ * If multiple calls to media_entity_pipeline_start() have been made the same
+ * number of media_entity_pipeline_stop() calls are required to stop streaming.
+ * The &media_entity pipe field is reset to NULL on the last nested stop call.
+ *
+ * Link configuration will fail with -%EBUSY by default if either end of the
+ * link is a streaming entity. Links that can be modified while streaming must
+ * be marked with the %MEDIA_LNK_FL_DYNAMIC flag.
+ *
+ * If other operations need to be disallowed on streaming entities (such as
+ * changing entities configuration parameters) drivers can explicitly check the
+ * media_entity stream_count field to find out if an entity is streaming. This
+ * operation must be done with the media_device graph_mutex held.
+ *
+ * Link validation:
+ *
+ * Link validation is performed by media_entity_pipeline_start() for any
+ * entity which has sink pads in the pipeline. The
+ * &media_entity.@link_validate() callback is used for that purpose. In
+ * @link_validate() callback, entity driver should check that the properties of
+ * the source pad of the connected entity and its own sink pad match. It is up
+ * to the type of the entity (and in the end, the properties of the hardware)
+ * what matching actually means.
+ *
+ * Subsystems should facilitate link validation by providing subsystem specific
+ * helper functions to provide easy access for commonly needed information, and
+ * in the end provide a way to use driver-specific callbacks.
+ */
diff --git a/Documentation/books/kernel-doc-HOWTO/vintage-kernel-doc-mode.rst b/Documentation/books/kernel-doc-HOWTO/vintage-kernel-doc-mode.rst
new file mode 100644
index 0000000..a49bc25
--- /dev/null
+++ b/Documentation/books/kernel-doc-HOWTO/vintage-kernel-doc-mode.rst
@@ -0,0 +1,100 @@
+.. -*- coding: utf-8; mode: rst -*-
+.. include:: refs.txt
+
+.. _vintage-kernel-doc-mode:
+
+=======================
+Vintage kernel-doc mode
+=======================
+
+All kernel-doc markup is processed as described in :ref:`kernel-doc-syntax`, all
+descriptive text is further processed, scanning for the following special
+patterns, which are highlighted appropriately.
+
+* ``funcname()``   - function
+* ``$ENVVAR``      - environmental variable
+* ``&struct name`` - name of a structure (up to two words including ``struct``)
+* ``@parameter``   - name of a parameter
+* ``%CONST``       - name of a constant.
+
+These highlighted patterns are not used when you are using the reST addition
+(:ref:`reST-kernel-doc-mode`).  This is, because reST brings it's own markup to
+refer and highlight function, structs or whatever definition.
+
+Within the *vintage* kernel-doc mode the kernel-doc parser highlights the pattern
+above, but he also dogged ignores any whitespace formatting/markup.
+
+.. hint::
+
+   Formatting with whitespaces is substantial for ASCII markups. By this, it's
+   recommended to use the :ref:`reST-kernel-doc-mode` on any new or changed
+   comment.
+
+
+.. _vintage-mode-quirks:
+
+vintage mode quirks
+===================
+
+In the following, you will find some quirks of the *vintage* kernel-doc mode.
+
+* Since a colon introduce a new section, you can't use colons. E.g. a comment
+  line like::
+
+      prints out: hello world
+
+  will result in a section with the title "prints out" and a paragraph with only
+  "hello world" in, this is mostly not what you expect. To avoid sectioning,
+  place a space in front of the column::
+
+      prints out : hello world
+
+* The multi-line descriptive text you provide does *not* recognize
+  line breaks, so if you try to format some text nicely, as in::
+
+      Return:
+         0 - cool
+         1 - invalid arg
+         2 - out of memory
+
+  this will all run together and produce::
+
+      Return: 0 - cool 1 - invalid arg 2 - out of memory
+
+* If the descriptive text you provide has lines that begin with some phrase
+  followed by a colon, each of those phrases will be taken as a new section
+  heading, which means you should similarly try to avoid text like::
+
+      Return:
+        0: cool
+        1: invalid arg
+        2: out of memory
+
+  every line of which would start a new section.  Again, probably not what you
+  were after.
+
+Determined by the historical development of the kernel-doc comments, the
+*vintage* kernel-doc comments contain characters like "*" or strings with
+e.g. leading/trailing underscore ("_"), which are inline markups in reST. Here a
+short example from a *vintage* comment::
+
+    <SNIP> -----
+    * In contrast to the other drm_get_*_name functions this one here returns a
+    * const pointer and hence is threadsafe.
+    <SNAP> -----
+
+Within reST markup (the new bas format), the wildcard in the string
+``drm_get_*_name`` has to be masked: ``drm_get_\\*_name``. Some more examples
+from reST markup:
+
+* Emphasis "*":  like ``*emphasis*`` or ``**emphasis strong**``
+* Leading "_" :  is a *anchor* in reST markup (``_foo``).
+* Trailing "_:  is a reference in reST markup (``foo_``).
+* interpreted text: "`"
+* inline literals: "``"
+* substitution references: "|"
+
+As long as you in the *vintage* kernel-doc mode, these special strings will be
+masked in the reST output and can't be used as *plain-text markup*.
+
+
-- 
v4.7-rc-2