2020-10-08 00:02:29

by John Hubbard

[permalink] [raw]
Subject: [PATCH] Documentation: filesystems: better locations for sysfs-pci, sysfs-tagging

sysfs-pci and sysfs-tagging were mis-filed: their locations with
Documentation/ implied that they were related to file systems. Actually,
each topic is about a very specific *use* of sysfs, and sysfs *happens*
to be a (virtual) filesystem, so this is not really the right place.

It's jarring to be reading about filesystems in general and then come
across these specific details about PCI, and tagging...and then back to
general filesystems again.

Move sysfs-pci and sysfs-tagging to a location under the sysfs topic.

Signed-off-by: John Hubbard <[email protected]>
---

Hi,

I'm not sure if the "toctree, maxdepth: 1" is the ideal way to do this,
but the output in the browser looks about right to me, anyway.

thanks,
John Hubbard
NVIDIA

Documentation/filesystems/index.rst | 2 --
Documentation/filesystems/sysfs.rst | 14 ++++++++++++++
2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 4c536e66dc4c..98f59a864242 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -34,8 +34,6 @@ algorithms work.
quota
seq_file
sharedsubtree
- sysfs-pci
- sysfs-tagging

automount-support

diff --git a/Documentation/filesystems/sysfs.rst b/Documentation/filesystems/sysfs.rst
index ab0f7795792b..39da2f5c235f 100644
--- a/Documentation/filesystems/sysfs.rst
+++ b/Documentation/filesystems/sysfs.rst
@@ -416,3 +416,17 @@ ABI between the kernel and user space. As for any ABI, it is important that
this ABI is stable and properly documented. All new sysfs attributes must be
documented in Documentation/ABI. See also Documentation/ABI/README for more
information.
+
+sysfs and PCI
+~~~~~~~~~~~~~
+.. toctree::
+ :maxdepth: 1
+
+ sysfs-pci
+
+sysfs and tagging
+~~~~~~~~~~~~~~~~~
+.. toctree::
+ :maxdepth: 1
+
+ sysfs-tagging
--
2.28.0


2020-10-08 16:07:30

by Jonathan Corbet

[permalink] [raw]
Subject: Re: [PATCH] Documentation: filesystems: better locations for sysfs-pci, sysfs-tagging

On Wed, 7 Oct 2020 16:31:51 -0700
John Hubbard <[email protected]> wrote:

> sysfs-pci and sysfs-tagging were mis-filed: their locations with
> Documentation/ implied that they were related to file systems. Actually,
> each topic is about a very specific *use* of sysfs, and sysfs *happens*
> to be a (virtual) filesystem, so this is not really the right place.
>
> It's jarring to be reading about filesystems in general and then come
> across these specific details about PCI, and tagging...and then back to
> general filesystems again.
>
> Move sysfs-pci and sysfs-tagging to a location under the sysfs topic.
>
> Signed-off-by: John Hubbard <[email protected]>

I see why you want to do this, but I have to wonder if moving them out of
Documentation/filesystems entirely might not be a better approach.
sysfs-pci.rst might better belong in the admin guide or under PCI/, while
sysfs-tagging.rst could go under networking/.

Make sense?

Thanks,

jon

2020-10-08 21:22:12

by John Hubbard

[permalink] [raw]
Subject: Re: [PATCH] Documentation: filesystems: better locations for sysfs-pci, sysfs-tagging

On 10/8/20 9:04 AM, Jonathan Corbet wrote:
> On Wed, 7 Oct 2020 16:31:51 -0700
> John Hubbard <[email protected]> wrote:
>
>> sysfs-pci and sysfs-tagging were mis-filed: their locations with
>> Documentation/ implied that they were related to file systems. Actually,
>> each topic is about a very specific *use* of sysfs, and sysfs *happens*
>> to be a (virtual) filesystem, so this is not really the right place.
>>
>> It's jarring to be reading about filesystems in general and then come
>> across these specific details about PCI, and tagging...and then back to
>> general filesystems again.
>>
>> Move sysfs-pci and sysfs-tagging to a location under the sysfs topic.
>>
>> Signed-off-by: John Hubbard <[email protected]>
>
> I see why you want to do this, but I have to wonder if moving them out of
> Documentation/filesystems entirely might not be a better approach.
> sysfs-pci.rst might better belong in the admin guide or under PCI/, while
> sysfs-tagging.rst could go under networking/.
>
> Make sense?
>

Absolutely, I'll post a v2 that does it that way.

thanks,
--
John Hubbard
NVIDIA