From 270beb5b2aae021cdd6406b15a35d494d8467cc8 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet <corbet@lwn.net>
Date: Fri, 13 Dec 2024 11:20:54 -0700
Subject: [PATCH] docs: admin-guide: bring some order to the "everything else"
 section

The bulk of the admin guide had become a big pile of stuff haphazardly
tossed together, mostly in the catch-all "everything else" section.  Split
that section into a few broad categories and sort the documents into them
as appropriate.

No documents have been added or removed, they are just reordered.  Note
that many of these documents are severely obsolete and should be considered
for removal.

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20241213182057.343527-4-corbet@lwn.net
---
 Documentation/admin-guide/index.rst | 179 +++++++++++++++++-----------
 1 file changed, 109 insertions(+), 70 deletions(-)

diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 6864b079b391..c8af32a8f800 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -18,18 +18,41 @@ etc.
    :maxdepth: 1
 
    README
-   kernel-parameters
    devices
-   sysctl/index
 
    features
 
-This section describes CPU vulnerabilities and their mitigations.
+A big part of the kernel's administrative interface is the /proc and sysfs
+virtual filesystems; these documents describe how to interact with tem
+
+.. toctree::
+   :maxdepth: 1
+
+   sysfs-rules
+   sysctl/index
+   cputopology
+   abi
+
+Security-related documentation:
 
 .. toctree::
    :maxdepth: 1
 
    hw-vuln/index
+   LSM/index
+   perf-security
+
+Booting the kernel
+------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   bootconfig
+   kernel-parameters
+   efi-stub
+   initrd
+
 
 Tracking down and identifying problems
 --------------------------------------
@@ -53,18 +76,94 @@ problems and bugs in particular.
    kdump/index
    perf/index
    pstore-blk
+   clearing-warn-once
+   kernel-per-CPU-kthreads
+   lockup-watchdogs
+   RAS/index
+   sysrq
 
-sysfs
------
 
-A big part of the kernel's administrative interface is the sysfs virtual
-filesystem; these documents describe how to interact with sysfs.
+Core-kernel subsystems
+----------------------
+
+These documents describe core-kernel administration interfaces that are
+likely to be of interest on almost any system.
 
 .. toctree::
    :maxdepth: 1
 
-   sysfs-rules
-   abi
+   cgroup-v2
+   cgroup-v1/index
+   cpu-load
+   mm/index
+   module-signing
+   namespaces/index
+   numastat
+   pm/index
+   syscall-user-dispatch
+
+Support for non-native binary formats.  Note that some of these
+documents are ... old ...
+
+.. toctree::
+   :maxdepth: 1
+
+   binfmt-misc
+   java
+   mono
+
+
+Block-layer and filesystem administration
+-----------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   bcache
+   binderfs
+   blockdev/index
+   cifs/index
+   device-mapper/index
+   ext4
+   filesystem-monitoring
+   nfs/index
+   iostats
+   jfs
+   md
+   ufs
+   xfs
+
+Device-specific guides
+----------------------
+
+How to configure your hardware within your Linux system.
+
+.. toctree::
+   :maxdepth: 1
+
+   acpi/index
+   aoe/index
+   auxdisplay/index
+   braille-console
+   btmrvl
+   dell_rbu
+   edid
+   gpio/index
+   hw_random
+   laptops/index
+   lcd-panel-cgram
+   media/index
+   nvme-multipath
+   parport
+   pnp
+   rapidio
+   rtc
+   serial-console
+   svga
+   thermal/index
+   thunderbolt
+   vga-softcursor
+   video-output
 
 Workload analysis
 -----------------
@@ -83,74 +182,14 @@ subsystems expectations will be found here.
 Everything else
 ---------------
 
-The rest of this manual consists of various unordered guides on how to
-configure specific aspects of kernel behavior to your liking.
+A few hard-to-categorize and generally obsolete documents.
 
 .. toctree::
    :maxdepth: 1
 
-   acpi/index
-   aoe/index
-   auxdisplay/index
-   bcache
-   binderfs
-   binfmt-misc
-   blockdev/index
-   bootconfig
-   braille-console
-   btmrvl
-   cgroup-v1/index
-   cgroup-v2
-   cifs/index
-   clearing-warn-once
-   cpu-load
-   cputopology
-   dell_rbu
-   device-mapper/index
-   edid
-   efi-stub
-   ext4
-   filesystem-monitoring
-   nfs/index
-   gpio/index
    highuid
-   hw_random
-   initrd
-   iostats
-   java
-   jfs
-   kernel-per-CPU-kthreads
-   laptops/index
-   lcd-panel-cgram
    ldm
-   lockup-watchdogs
-   LSM/index
-   md
-   media/index
-   mm/index
-   module-signing
-   mono
-   namespaces/index
-   numastat
-   parport
-   perf-security
-   pm/index
-   pnp
-   rapidio
-   RAS/index
-   rtc
-   serial-console
-   svga
-   syscall-user-dispatch
-   sysrq
-   thermal/index
-   thunderbolt
-   ufs
    unicode
-   vga-softcursor
-   video-output
-   xfs
-   nvme-multipath
 
 .. only::  subproject and html