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>

diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 4e5abbb4bbd58d6323b9e4aaa475c43f371a4168..2ce2bf02824bb85d5e751a67c61963d455cc647c 100644 (file)
--- 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,8 +55,6 @@ Contents:
    sysrq
    unicode
    vga-softcursor
-   sysfs-rules
-   devices
    binfmt-misc
    mono
    java

diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst
index d2f2725f032ea8f44d0988edfe75a087cbb6d176..37105aedb2e4f2c0f8b48a36f54983ba097d1d9e 100644 (file)
--- 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 04bdd52cba1d1ab3cee8f6e31ff214a9c41f4a24..abad33526acad1f51133c3c5c0ffdb5537e89180 100644 (file)
--- 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 9eac6744b3a19d19c65b9530744d65a1a44642ce..a663a745cff4bffd827ba8a06f9e9302c481b4c8 100644 (file)
--- 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::