Message-ID: <Z10A2FG2IqgkNsoj@archie.me>
Date: Sat, 14 Dec 2024 10:51:52 +0700
From: Bagas Sanjaya <bagasdotme@...il.com>
To: Jonathan Corbet <corbet@....net>, linux-doc@...r.kernel.org
Cc: linux-kernel@...r.kernel.org
Subject: Re: [PATCH 3/3] docs: admin-guide: bring some order to the
 "everything else" section

On Fri, Dec 13, 2024 at 11:20:54AM -0700, Jonathan Corbet wrote:
> 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
                                                                     "them"
> +
> +.. 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,104 +76,120 @@ problems and bugs in particular.
>     kdump/index
>     perf/index
>     pstore-blk
> +   clearing-warn-once
> +   kernel-per-CPU-kthreads
> +   lockup-watchdogs
> +   RAS/index
> +   sysrq
> +
>  
> -sysfs
> ------
> +Core-kernel subsystems
> +----------------------
>  
> -A big part of the kernel's administrative interface is the sysfs virtual
> -filesystem; these documents describe how to interact with sysfs.
> +These documents describe core-kernel administration interfaces that are
> +likely to be of interest on almost any system.
>  
>  .. toctree::
>     :maxdepth: 1
>  
> -   sysfs-rules
> -   abi
> -
> -Workload analysis
> ------------------
> +   cgroup-v2
> +   cgroup-v1/index
> +   cpu-load
> +   mm/index
> +   module-signing
> +   namespaces/index
> +   numastat
> +   pm/index
> +   syscall-user-dispatch
>  
> -This is the beginning of a section with information of interest to
> -application developers and system integrators doing analysis of the
> -Linux kernel for safety critical applications. Documents supporting
> -analysis of kernel interactions with applications, and key kernel
> -subsystems expectations will be found here.
> +Support for non-native binary formats.  Note that some of these
> +documents are ... old ...
>  
>  .. toctree::
>     :maxdepth: 1
>  
> -   workload-tracing
> +   binfmt-misc
> +   java
> +   mono
>  
> -Everything else
> ----------------
>  
> -The rest of this manual consists of various unordered guides on how to
> -configure specific aspects of kernel behavior to your liking.
> +Block-layer and filesystem administration
> +-----------------------------------------
>  
>  .. 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
> +   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
> -   ldm
> -   lockup-watchdogs
> -   LSM/index
> -   md
>     media/index
> -   mm/index
> -   module-signing
> -   mono
> -   namespaces/index
> -   numastat
> +   nvme-multipath
>     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
> +
> +Workload analysis
> +-----------------
> +
> +This is the beginning of a section with information of interest to
> +application developers and system integrators doing analysis of the
> +Linux kernel for safety critical applications. Documents supporting
> +analysis of kernel interactions with applications, and key kernel
> +subsystems expectations will be found here.
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   workload-tracing
> +
> +Everything else
> +---------------
> +
> +A few hard-to-categorize and generally obsolete documents.
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   highuid
> +   ldm
> +   unicode
>  
>  .. only::  subproject and html
>  

The rest looks good.

Reviewed-by: Bagas Sanjaya <bagasdotme@...il.com>

-- 
An old man doll... just what I always wanted! - Clara

Download attachment "signature.asc" of type "application/pgp-signature" (229 bytes)

Powered by blists - more mailing lists