[PATCH v2 v2] Documentation: proc: fix section numbering in table of contents

[PATCH v2 v2] Documentation: proc: fix section numbering in table of contents

[Baolin Liu]

From: Baolin Liu <liubaolin@kylinos.cn>

Commit e24ccaaf7ec4 ("block: remove last remaining traces of IDE
documentation") removed the IDE section but left its table of
contents entry behind.
Fix the stale entry and renumber the following sections.

Fixes: e24ccaaf7ec4 ("block: remove last remaining traces of IDE documentation")
Signed-off-by: Baolin Liu <liubaolin@kylinos.cn>
---
 Documentation/filesystems/proc.rst | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst
index 7ce02573a3d9..70db35987ee1 100644
--- a/Documentation/filesystems/proc.rst
+++ b/Documentation/filesystems/proc.rst
@@ -23,13 +23,13 @@ fixes/update part 1.1  Stefani Seibold <stefani@seibold.net>    June 9 2009
   1	Collecting System Information
   1.1	Process-Specific Subdirectories
   1.2	Kernel data
-  1.3	IDE devices in /proc/ide
-  1.4	Networking info in /proc/net
-  1.5	SCSI info
-  1.6	Parallel port info in /proc/parport
-  1.7	TTY info in /proc/tty
-  1.8	Miscellaneous kernel statistics in /proc/stat
-  1.9	Ext4 file system parameters
+  1.3	Networking info in /proc/net
+  1.4	SCSI info
+  1.5	Parallel port info in /proc/parport
+  1.6	TTY info in /proc/tty
+  1.7	Miscellaneous kernel statistics in /proc/stat
+  1.8	Ext4 file system parameters
+  1.9	/proc/consoles - Shows registered system consoles
 
   2	Modifying System Parameters
 
-- 
2.51.0

Re: [PATCH v2 v2] Documentation: proc: fix section numbering in table of contents

[Randy Dunlap]

On 4/24/26 2:06 AM, Baolin Liu wrote:
> From: Baolin Liu <liubaolin@kylinos.cn>
> 
> Commit e24ccaaf7ec4 ("block: remove last remaining traces of IDE
> documentation") removed the IDE section but left its table of
> contents entry behind.
> Fix the stale entry and renumber the following sections.
> 
> Fixes: e24ccaaf7ec4 ("block: remove last remaining traces of IDE documentation")
> Signed-off-by: Baolin Liu <liubaolin@kylinos.cn>

LGTM.
Acked-by: Randy Dunlap <rdunlap@infradead.org>

I note that the html-generated TOC is already correct;
e.g., https://docs.kernel.org/filesystems/proc.html#networking-info-in-proc-net
is already section 1.3.

AFAICT, this TOC is for users/readers who use an editor or pager
to read this file, but the patch is useful in that setting.

> ---
>  Documentation/filesystems/proc.rst | 14 +++++++-------
>  1 file changed, 7 insertions(+), 7 deletions(-)
> 
> diff --git a/Documentation/filesystems/proc.rst b/Documentation/filesystems/proc.rst
> index 7ce02573a3d9..70db35987ee1 100644
> --- a/Documentation/filesystems/proc.rst
> +++ b/Documentation/filesystems/proc.rst
> @@ -23,13 +23,13 @@ fixes/update part 1.1  Stefani Seibold <stefani@seibold.net>    June 9 2009
>    1	Collecting System Information
>    1.1	Process-Specific Subdirectories
>    1.2	Kernel data
> -  1.3	IDE devices in /proc/ide
> -  1.4	Networking info in /proc/net
> -  1.5	SCSI info
> -  1.6	Parallel port info in /proc/parport
> -  1.7	TTY info in /proc/tty
> -  1.8	Miscellaneous kernel statistics in /proc/stat
> -  1.9	Ext4 file system parameters
> +  1.3	Networking info in /proc/net
> +  1.4	SCSI info
> +  1.5	Parallel port info in /proc/parport
> +  1.6	TTY info in /proc/tty
> +  1.7	Miscellaneous kernel statistics in /proc/stat
> +  1.8	Ext4 file system parameters
> +  1.9	/proc/consoles - Shows registered system consoles
>  
>    2	Modifying System Parameters
>  

-- 
~Randy

Re: [PATCH v2 v2] Documentation: proc: fix section numbering in table of contents

[Jonathan Corbet]

Randy Dunlap <rdunlap@infradead.org> writes:

> On 4/24/26 2:06 AM, Baolin Liu wrote:
>> From: Baolin Liu <liubaolin@kylinos.cn>
>> 
>> Commit e24ccaaf7ec4 ("block: remove last remaining traces of IDE
>> documentation") removed the IDE section but left its table of
>> contents entry behind.
>> Fix the stale entry and renumber the following sections.
>> 
>> Fixes: e24ccaaf7ec4 ("block: remove last remaining traces of IDE documentation")
>> Signed-off-by: Baolin Liu <liubaolin@kylinos.cn>
>
> LGTM.
> Acked-by: Randy Dunlap <rdunlap@infradead.org>
>
> I note that the html-generated TOC is already correct;
> e.g., https://docs.kernel.org/filesystems/proc.html#networking-info-in-proc-net
> is already section 1.3.

There are advantages to having a computer do a job like that :)

I do really question the value of these manually maintained TOCs; they
are always going to be out of date.  But ...

> AFAICT, this TOC is for users/readers who use an editor or pager
> to read this file, but the patch is useful in that setting.

Others seem to disagree, so we keep them.

I've applied the patch, thanks.

jon

Re: [PATCH v2 v2] Documentation: proc: fix section numbering in table of contents

[Randy Dunlap]

On 4/27/26 2:55 AM, Jonathan Corbet wrote:
> Randy Dunlap <rdunlap@infradead.org> writes:
> 
>> On 4/24/26 2:06 AM, Baolin Liu wrote:
>>> From: Baolin Liu <liubaolin@kylinos.cn>
>>>
>>> Commit e24ccaaf7ec4 ("block: remove last remaining traces of IDE
>>> documentation") removed the IDE section but left its table of
>>> contents entry behind.
>>> Fix the stale entry and renumber the following sections.
>>>
>>> Fixes: e24ccaaf7ec4 ("block: remove last remaining traces of IDE documentation")
>>> Signed-off-by: Baolin Liu <liubaolin@kylinos.cn>
>>
>> LGTM.
>> Acked-by: Randy Dunlap <rdunlap@infradead.org>
>>
>> I note that the html-generated TOC is already correct;
>> e.g., https://docs.kernel.org/filesystems/proc.html#networking-info-in-proc-net
>> is already section 1.3.
> 
> There are advantages to having a computer do a job like that :)
> 
> I do really question the value of these manually maintained TOCs; they
> are always going to be out of date.  But ...
> 
>> AFAICT, this TOC is for users/readers who use an editor or pager
>> to read this file, but the patch is useful in that setting.
> 
> Others seem to disagree, so we keep them.
> 
> I've applied the patch, thanks.

Yes, others do disagree, but my comment was not meant to be an endorsement
for keeping it there. I'm fine without it.

-- 
~Randy

Re: [PATCH v2 v2] Documentation: proc: fix section numbering in table of contents

[Jonathan Corbet]

Your use of HTML email almost certainly prevents your messages from
making it onto the lists; you need to stop doing that.

liubaolin <liubaolin12138@163.com> writes:

>         I mainly work on ext4 kernel development. Recently, I've been
> implementing a feature that changes the usage of the ext4 proc
> parameter mb_stats, which requires updating the ext4 proc parameter
> documentation.  Currently, the ext4 proc parameter documentation is
> explained in two files: "Documentation/admin-guide/ext4.rst" and
> "Documentation/filesystems/proc.rst".
>
>         However, I found that only the ext4 file system describes the
> proc parameters in proc.rst, while other file systems such as btrfs
> and xfs do not describe the proc parameters they use in the file.
> Personally, I also feel that it is unnecessary to explain the ext4
> proc parameters in proc.rst.
>
>         Therefore, I want to make a change by deleting the "Ext4 file
> system parameters" section from the proc.rst file.  After
> modification, the usage and explanation of ext4 proc parameters will
> only be provided in Documentation/admin-guide/ext4.rst.

Documenting things twice is obviously not ideal; readers will wonder
about the truth when they inevitably go out of sync.

>         If you agree, I will submit a patch to remove the "Ext4 file
> system parameters" section.  If you disagree, my subsequent
> modifications to the ext4 proc parameters will be made simultaneously
> to the two documents: Documentation/admin-guide/ext4.rst and
> Documentation/filesystems/proc.rst.  I look forward to your comments
> and replies.

I think that having a single location for that documentation makes
sense.  Whether it's in the individual filesystem docs or centrally
located is up to the filesystem maintainers in the end.  If you move
that documentation out of Documentation/filesystems/proc.rst, it would
be good to add links to the filesystem-specific parameters in its place,
though.

Longer term, it seems to me that much of what's in that file really
belongs in the admin guide, though.

Thanks,

jon

Re: [PATCH v2 v2] Documentation: proc: fix section numbering in table of contents

[liubaolin]

在 2026/4/28 16:57, Jonathan Corbet 写道:
> Your use of HTML email almost certainly prevents your messages from
> making it onto the lists; you need to stop doing that.
> 
I apologize, there was a problem with my newly set up email environment 
that caused the HTML email to be sent. I will pay attention to this in 
the future.

> liubaolin <liubaolin12138@163.com> writes:
> 
>>          I mainly work on ext4 kernel development. Recently, I've been
>> implementing a feature that changes the usage of the ext4 proc
>> parameter mb_stats, which requires updating the ext4 proc parameter
>> documentation.  Currently, the ext4 proc parameter documentation is
>> explained in two files: "Documentation/admin-guide/ext4.rst" and
>> "Documentation/filesystems/proc.rst".
>>
>>          However, I found that only the ext4 file system describes the
>> proc parameters in proc.rst, while other file systems such as btrfs
>> and xfs do not describe the proc parameters they use in the file.
>> Personally, I also feel that it is unnecessary to explain the ext4
>> proc parameters in proc.rst.
>>
>>          Therefore, I want to make a change by deleting the "Ext4 file
>> system parameters" section from the proc.rst file.  After
>> modification, the usage and explanation of ext4 proc parameters will
>> only be provided in Documentation/admin-guide/ext4.rst.
> 
> Documenting things twice is obviously not ideal; readers will wonder
> about the truth when they inevitably go out of sync.
> 
>>          If you agree, I will submit a patch to remove the "Ext4 file
>> system parameters" section.  If you disagree, my subsequent
>> modifications to the ext4 proc parameters will be made simultaneously
>> to the two documents: Documentation/admin-guide/ext4.rst and
>> Documentation/filesystems/proc.rst.  I look forward to your comments
>> and replies.
> 
> I think that having a single location for that documentation makes
> sense.  Whether it's in the individual filesystem docs or centrally
> located is up to the filesystem maintainers in the end.  If you move
> that documentation out of Documentation/filesystems/proc.rst, it would
> be good to add links to the filesystem-specific parameters in its place,
> though.
> 
> Longer term, it seems to me that much of what's in that file really
> belongs in the admin guide, though.
> 
> Thanks,
> 
> jon

Okay, thank you for your reply. I will ask the ext4 maintainers, and if 
they agree, I will submit a patch as you suggested.