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@xxxxxxx> 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