* [PATCH] Documentation: filesystems: better locations for sysfs-pci, sysfs-tagging
@ 2020-10-07 23:31 John Hubbard
2020-10-08 16:04 ` Jonathan Corbet
0 siblings, 1 reply; 3+ messages in thread
From: John Hubbard @ 2020-10-07 23:31 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Mauro Carvalho Chehab, Jan Kara, David Sterba, linux-doc, LKML,
John Hubbard
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 <jhubbard@nvidia.com>
---
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
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [PATCH] Documentation: filesystems: better locations for sysfs-pci, sysfs-tagging
2020-10-07 23:31 [PATCH] Documentation: filesystems: better locations for sysfs-pci, sysfs-tagging John Hubbard
@ 2020-10-08 16:04 ` Jonathan Corbet
2020-10-08 19:28 ` John Hubbard
0 siblings, 1 reply; 3+ messages in thread
From: Jonathan Corbet @ 2020-10-08 16:04 UTC (permalink / raw)
To: John Hubbard
Cc: Mauro Carvalho Chehab, Jan Kara, David Sterba, linux-doc, LKML
On Wed, 7 Oct 2020 16:31:51 -0700
John Hubbard <jhubbard@nvidia.com> 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 <jhubbard@nvidia.com>
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
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] Documentation: filesystems: better locations for sysfs-pci, sysfs-tagging
2020-10-08 16:04 ` Jonathan Corbet
@ 2020-10-08 19:28 ` John Hubbard
0 siblings, 0 replies; 3+ messages in thread
From: John Hubbard @ 2020-10-08 19:28 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Mauro Carvalho Chehab, Jan Kara, David Sterba, linux-doc, LKML
On 10/8/20 9:04 AM, Jonathan Corbet wrote:
> On Wed, 7 Oct 2020 16:31:51 -0700
> John Hubbard <jhubbard@nvidia.com> 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 <jhubbard@nvidia.com>
>
> 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
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2020-10-08 19:32 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-10-07 23:31 [PATCH] Documentation: filesystems: better locations for sysfs-pci, sysfs-tagging John Hubbard
2020-10-08 16:04 ` Jonathan Corbet
2020-10-08 19:28 ` John Hubbard
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).