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.

13 files changed, 137 insertions, 168 deletions

diff --git a/Documentation/admin-guide/bad-memory.rst b/Documentation/admin-guide/bad-memory.rst
deleted file mode 100644
index a5c0e25e496f..000000000000
--- a/Documentation/admin-guide/bad-memory.rst
+++ /dev/null
@@ -1,50 +0,0 @@
-How to deal with bad memory e.g. reported by memtest86+ ?
-=========================================================
-
-March 2008
-Jan-Simon Moeller, dl9pf@gmx.de
-
-
-
-There are three possibilities I know of:
-
-1) Reinsert/swap the memory modules
-
-2) Buy new modules (best!) or try to exchange the memory
-   if you have spare-parts
-
-3) Use BadRAM or memmap
-
-This Howto is about number 3) .
-
-
-BadRAM
-######
-
-BadRAM is the actively developed and available as kernel-patch
-here:  http://rick.vanrein.org/linux/badram/
-
-For more details see the BadRAM documentation.
-
-memmap
-######
-
-memmap is already in the kernel and usable as kernel-parameter at
-boot-time.  Its syntax is slightly strange and you may need to
-calculate the values by yourself!
-
-Syntax to exclude a memory area (see admin-guide/kernel-parameters.rst for details)::
-
-	memmap=<size>$<address>
-
-Example: memtest86+ reported here errors at address 0x18691458, 0x18698424 and
-some others. All had 0x1869xxxx in common, so I chose a pattern of
-0x18690000,0xffff0000.
-
-With the numbers of the example above::
-
-	memmap=64K$0x18690000
-
-or::
-
-	memmap=0x10000$0x18690000
diff --git a/Documentation/admin-guide/basic-profiling.rst b/Documentation/admin-guide/basic-profiling.rst
deleted file mode 100644
index 72babc71b771..000000000000
--- a/Documentation/admin-guide/basic-profiling.rst
+++ /dev/null
@@ -1,68 +0,0 @@
-Basic kernel profiling
-======================
-
-
-These instructions are deliberately very basic. If you want something clever,
-go read the real docs ;-)
-
-Please don't add more stuff, but feel free to
-correct my mistakes ;-)    (mbligh@aracnet.com)
-
-Thanks to John Levon, Dave Hansen, et al. for help writing this.
-
-``<test>`` is the thing you're trying to measure.
-Make sure you have the correct ``System.map`` / ``vmlinux`` referenced!
-
-It is probably easiest to use ``make install`` for linux and hack
-``/sbin/installkernel`` to copy ``vmlinux`` to ``/boot``, in addition to
-``vmlinuz``, ``config``, ``System.map``, which are usually installed by default.
-
-Readprofile
------------
-
-A recent ``readprofile`` command is needed for 2.6, such as found in util-linux
-2.12a, which can be downloaded from:
-
-	http://www.kernel.org/pub/linux/utils/util-linux/
-
-Most distributions will ship it already.
-
-Add ``profile=2`` to the kernel command line.
-
-Some ``readprofile`` commands::
-
-	clear		readprofile -r
-			<test>
-	dump output	readprofile -m /boot/System.map > captured_profile
-
-Oprofile
---------
-
-Get the source (see Changes for required version) from
-http://oprofile.sourceforge.net/ and add ``idle=poll`` to the kernel command
-line.
-
-Configure with ``CONFIG_PROFILING=y`` and ``CONFIG_OPROFILE=y`` & reboot on new kernel::
-
-	./configure --with-kernel-support
-	make install
-
-For superior results, be sure to enable the local APIC. If opreport sees
-a 0Hz CPU, APIC was not on. Be aware that idle=poll may mean a performance
-penalty.
-
-One time setup::
-
-			opcontrol --setup --vmlinux=/boot/vmlinux
-
-Some ``opcontrol`` commands::
-
-	clear		opcontrol --reset
-	start		opcontrol --start
-		<test>
-	stop		opcontrol --stop
-	dump output	opreport >  output_file
-
-To only report on the kernel, run ``opreport -l /boot/vmlinux > output_file``
-
-A reset is needed to clear old statistics, which survive a reboot.
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index fb779e67097b..368845e9900a 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -1,22 +1,52 @@
-Linux Kernel User's Documentation
-=================================
+The Linux kernel user's and administrator's guide
+=================================================
 
-Contents:
+The following is a collection of user-oriented documents that have been
+added to the kernel over time.  There is, as yet, little overall order or
+organization here — this material was not written to be a single, coherent
+document!  With luck things will improve quickly over time.
+
+This initial section contains overall information, including the README
+file describing the kernel as a whole, documentation on kernel parameters,
+etc. 
 
 .. toctree::
-   :maxdepth: 2
-   :numbered:
+   :maxdepth: 1
 
    README
+   kernel-parameters
+   devices
+
+Here is a set of documents aimed at users who are trying to track down
+problems and bugs in particular.
+
+.. toctree::
+   :maxdepth: 1
+   
    reporting-bugs
+   security-bugs
    bug-hunting
    oops-tracing
    ramoops
-   initrd
-   init
    dynamic-debug-howto
-   security-bugs
-   kernel-parameters
+   init
+
+This is the beginning of a section with information of interest to
+application developers.  Documents covering various aspects of the kernel
+ABI will be found here.
+
+.. toctree::
+   :maxdepth: 1
+   
+   sysfs-rules
+
+The rest of this manual consists of various unordered guides on how to
+configure specific aspects of kernel behavior to your liking.
+
+.. toctree::
+   :maxdepth: 1
+   
+   initrd
    serial-console
    braille-console
    parport
@@ -25,13 +55,9 @@ Contents:
    sysrq
    unicode
    vga-softcursor
-   sysfs-rules
-   devices
    binfmt-misc
    mono
    java
-   bad-memory
-   basic-profiling
 
 .. only::  subproject and html
 
@@ -39,4 +65,3 @@ Contents:
    =======
 
    * :ref:`genindex`
-
diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst
index d2f2725f032e..37105aedb2e4 100644
--- a/Documentation/admin-guide/kernel-parameters.rst
+++ b/Documentation/admin-guide/kernel-parameters.rst
@@ -1,5 +1,5 @@
-Kernel Parameters
-~~~~~~~~~~~~~~~~~
+The kernel's command-line parameters
+====================================
 
 The following is a consolidated list of the kernel parameters as
 implemented by the __setup(), core_param() and module_param() macros
diff --git a/Documentation/admin-guide/sysfs-rules.rst b/Documentation/admin-guide/sysfs-rules.rst
index 04bdd52cba1d..abad33526aca 100644
--- a/Documentation/admin-guide/sysfs-rules.rst
+++ b/Documentation/admin-guide/sysfs-rules.rst
@@ -1,5 +1,5 @@
-Rules on how to access information in the Linux kernel sysfs
-============================================================
+Rules on how to access information in sysfs
+===========================================
 
 The kernel-exported sysfs exports internal kernel implementation details
 and depends on internal kernel structures and layout. It is agreed upon
diff --git a/Documentation/admin-guide/vga-softcursor.rst b/Documentation/admin-guide/vga-softcursor.rst
index 9eac6744b3a1..a663a745cff4 100644
--- a/Documentation/admin-guide/vga-softcursor.rst
+++ b/Documentation/admin-guide/vga-softcursor.rst
@@ -50,8 +50,8 @@ third parameter
 
 .. [#f1] see ``#define TRIDENT_GLITCH`` in ``drivers/video/vgacon.c``.
 
-Examples:
-=========
+Examples
+--------
 
 To get normal blinking underline, use::
 
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 0f98823126f2..85a66270f96c 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -3,18 +3,55 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to The Linux Kernel's documentation!
-============================================
+Welcome to The Linux Kernel's documentation
+===========================================
 
-Contents:
+This is the top level of the kernel's documentation tree.  Kernel
+documentation, like the kernel itself, is very much a work in progress;
+that is especially true as we work to integrate our many scattered
+documents into a coherent whole.  Please note that improvements to the
+documentation are welcome; join the linux-doc list at vger.kernel.org if
+you want to help out.
+
+User-oriented documentation
+---------------------------
+
+The following manuals are written for *users* of the kernel — those who are
+trying to get it to work optimally on a given system.
 
 .. toctree::
    :maxdepth: 2
 
    admin-guide/index
-   kernel-documentation
+
+Introduction to kernel development
+----------------------------------
+
+These manuals contain overall information about how to develop the kernel.
+The kernel community is quite large, with thousands of developers
+contributing over the course of a year.  As with any large community,
+knowing how things are done will make the process of getting your changes
+merged much easier.
+
+.. toctree::
+   :maxdepth: 2
+
    process/index
    dev-tools/index
+   kernel-documentation
+
+Kernel API documentation
+------------------------
+
+These books get into the details of how specific kernel subsystems work
+from the point of view of a kernel developer.  Much of the information here
+is taken directly from the kernel source, with supplemental material added
+as needed (or at least as we managed to add it — probably *not* all that is
+needed). 
+
+.. toctree::
+   :maxdepth: 2
+
    driver-api/index
    media/index
    gpu/index
diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
index 10cc7ddb6235..c66ab937c2ca 100644
--- a/Documentation/kernel-documentation.rst
+++ b/Documentation/kernel-documentation.rst
@@ -1,6 +1,6 @@
-==========================
-Linux Kernel Documentation
-==========================
+=================================
+How to write kernel documentation
+=================================
 
 Introduction
 ============
diff --git a/Documentation/process/applying-patches.rst b/Documentation/process/applying-patches.rst
index abd7dc7ae240..87825cf96f33 100644
--- a/Documentation/process/applying-patches.rst
+++ b/Documentation/process/applying-patches.rst
@@ -9,6 +9,10 @@ Original by:
 Last update:
 	2016-09-14
 
+.. note::
+
+   This document is obsolete.  In most cases, rather than using ``patch``
+   manually, you'll almost certainly want to look at using Git instead.
 
 A frequently asked question on the Linux Kernel Mailing List is how to apply
 a patch to the kernel or, more specifically, what base kernel a patch for
diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst
index 22797a15dc24..56ce66114665 100644
--- a/Documentation/process/changes.rst
+++ b/Documentation/process/changes.rst
@@ -1,6 +1,6 @@
 .. _changes:
 
-Minimal requerements to compile the Kernel
+Minimal requirements to compile the Kernel
 ++++++++++++++++++++++++++++++++++++++++++
 
 Intro
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index cddf580671e7..10aa6920709a 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -4,34 +4,51 @@
 	\renewcommand\thesubsection*
 
 
-Linux Kernel Development Documentation
-======================================
+Working with the kernel development community
+=============================================
 
-Contents:
+So you want to be a Linux kernel developer?  Welcome!  While there is a lot
+to be learned about the kernel in a technical sense, it is also important
+to learn about how our community works.  Reading these documents will make
+it much easier for you to get your changes merged with a minimum of
+trouble.
+
+Below are the essential guides that every developer should read.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    howto
-   changes
-   coding-style
+   code-of-conflict
+   development-process
    submitting-patches
+   coding-style
+   email-clients
+
+Other guides to the community that are of interest to most developers are: 
+
+.. toctree::
+   :maxdepth: 1
+
+   changes
    submitting-drivers
    stable-api-nonsense
    management-style
    stable-kernel-rules
+   submit-checklist
    kernel-docs
+
+These are some overall technical guides that have been put here for now for
+lack of a better place.
+
+.. toctree::
+   :maxdepth: 1
+
    applying-patches
-   email-clients
-   submit-checklist
-   code-of-conflict
    adding-syscalls
    magic-number
    volatile-considered-harmful
 
-   development-process
-
-
 .. only::  subproject and html
 
    Indices
diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst
index 0939d018c289..afb82ee0cbea 100644
--- a/Documentation/process/submitting-drivers.rst
+++ b/Documentation/process/submitting-drivers.rst
@@ -8,6 +8,14 @@ various kernel trees. Note that if you are interested in video card drivers
 you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org
 (http://x.org/) instead.
 
+.. note::
+
+   This document is old and has seen little maintenance in recent years; it
+   should probably be updated or, perhaps better, just deleted.  Most of
+   what is here can be found in the other development documents anyway.
+
+   Oh, and we don't really recommend submitting changes to XFree86 :)
+
 Also read the Documentation/process/submitting-patches.rst document.
 
 
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index b4cf8f375184..3e10719fee35 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -1,7 +1,7 @@
 .. _submittingpatches:
 
-How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds
-=========================================================================================
+Submitting patches: the essential guide to getting your code into the kernel
+============================================================================
 
 For a person or company who wishes to submit a change to the Linux
 kernel, the process can sometimes be daunting if you're not familiar
@@ -24,10 +24,6 @@ of the mechanical work done for you, though you'll still need to prepare
 and document a sensible set of patches.  In general, use of ``git`` will make
 your life as a kernel developer easier.
 
-Creating and Sending your Change
-********************************
-
-
 0) Obtain a current source tree
 -------------------------------
 
@@ -417,8 +413,8 @@ e-mail discussions.
 
 
 
-11) Sign your work
-------------------
+11) Sign your work — the Developer's Certificate of Origin
+----------------------------------------------------------
 
 To improve tracking of who did what, especially with patches that can
 percolate to their final resting place in the kernel through several
@@ -803,8 +799,8 @@ command like this will do the trick::
   git request-pull master git://my.public.tree/linux.git my-signed-tag
 
 
-REFERENCES
-**********
+References
+----------
 
 Andrew Morton, "The perfect patch" (tpp).
   <http://www.ozlabs.org/~akpm/stuff/tpp.txt>