docs: filesystems: sysfs: convert sysfs.txt to reST
PATCH RESEND 1/1 docs: filesystems: sysfs: convert sysfs.txt to reST
This patch converts sysfs.txt to sysfs.rst, and adds a corresponding entry in index.rst.
Most of the whitespacing and indentation is kept similar to the original document.
Changes to the original document include:
- Adding an authors statement in the header.
- Replacing the underscores in the title with asterisks. This is so that the "The" in the title appears in italics in HTML.
- Replacing the tilde (~) headings with equal signs, for reST section headings.
- List out the helper macros with backquotes and corresponding description on the next line.
- Placing C code and shell code in reST code blocks, with an indentation of an 8 length tab.
---
Documentation/filesystems/index.rst | 1 +
.../filesystems/{sysfs.txt => sysfs.rst} | 323 ++++++++++--------
2 files changed, 189 insertions(+), 135 deletions(-)
rename Documentation/filesystems/{sysfs.txt => sysfs.rst} (60%)Documentation/filesystems/index.rst +1 -0
@@ -46,4 +46,5 @@ Documentation for filesystem implementations. .. toctree:: :maxdepth: 2 + sysfs virtiofs
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +188 -135
474 lines not on this page · raw message
Signature · 6 lines
2.21.0 _______________________________________________ Linux-kernel-mentees mailing list [email protected] https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees
Jonathan Corbet
maintainerQuoted 18 lines · On Tue, 5 Nov 2019 12:48:46 +0530 Jaskaran Singh…
This patch converts sysfs.txt to
sysfs.rst, and adds a corresponding entry inindex.rst.Most of the whitespacing and indentation is kept similar to the original document.
Changes to the original document include:
- Adding an authors statement in the header.
- Replacing the underscores in the title with asterisks. This is so that the "The" in the title appears in italics in HTML.
- Replacing the tilde (~) headings with equal signs, for reST section headings.
- List out the helper macros with backquotes and corresponding description on the next line.
- Placing C code and shell code in reST code blocks, with an indentation of an 8 length tab.
Quoted 1 line
Signed-off-by Jaskaran Singh <[email protected]>
Thanks for working to improve the documentation. There are some problems here, none of which are your creation, but I would sure like to resolve them while working with this document.
The first of these is that Documentation/filesystems is really the wrong place for this file - it's covering the internal API for subsystems that want to create entries in sysfs. IMO, it belongs in either the driver-API manual or the core-API manual - probably the latter.
Quoted 23 lines
Documentation/filesystems/index.rst | 1 + .../filesystems/{sysfs.txt => sysfs.rst} | 323 ++++++++++-------- 2 files changed, 189 insertions(+), 135 deletions(-) rename Documentation/filesystems/{sysfs.txt => sysfs.rst} (60%)Documentation/filesystems/index.rst +1
-0@@ -46,4 +46,5 @@ Documentation for filesystem implementations. .. toctree:: :maxdepth: 2 + sysfs virtiofsDocumentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +0
-0
Documentation/filesystems/sysfs.rst line 2
Quoted 5 lines
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +3
-1@@ -1,15 +1,18 @@ +====================================================== +sysfs - *The* filesystem for exporting kernel objects. +====================================================== -sysfs - _The_ filesystem for exporting kernel objects.
Nits: We can really just drop emphasis like that, it doesn't really help anybody. Also the period can go on section headers.
Documentation/filesystems/sysfs.rst line 8
Quoted 6 lines
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +3
-2+Authors: -Patrick Mochel <[email protected]> -Mike Murphy <[email protected]> +- Patrick Mochel <[email protected]> +- Mike Murphy <[email protected]>
I would be absolutely amazed if either of those email addresses works at this point. I'd take them out.
Documentation/filesystems/sysfs.rst line 11
Quoted 4 lines
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +2
-2-Revised: 16 August 2011 -Original: 10 January 2003 +| Revised: 16 August 2011 +| Original: 10 January 2003
Dates like that are a red flag. See below.
Quoted 10 lines
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +1
-1What it is: -~~~~~~~~~~~ +=========== sysfs is a ram-based filesystem initially based on ramfs. It provides a means to export kernel data structures, their attributes, and the@@ -21,16 +24,18 @@ interface. Using sysfs
Documentation/filesystems/sysfs.rst interface. · line 34
Quoted 10 lines
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +4
-2-~~~~~~~~~~~ +=========== sysfs is always compiled in if CONFIG_SYSFS is defined. You can access it by doing: - mount -t sysfs sysfs /sys +.. code-block:: sh + + mount -t sysfs sysfs /sys
In the spirit of minimal markup, I'd do the above as:
it by doing::
mount -t sysfs sysfs /sys
But then I know that others are much more fond of .. code-block and syntax highlighting than I am.
Quoted 21 lines
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +2
-4Directory Creation -~~~~~~~~~~~~~~~~~~ +================== For every kobject that is registered with the system, a directory is created for it in sysfs. That directory is created as a subdirectory@@ -48,7 +53,7 @@ only modified directly by the function sysfs_schedule_callback(). Attributes -~~~~~~~~~~ +========== Attributes can be exported for kobjects in the form of regular files in the filesystem. Sysfs forwards file I/O operations to methods defined@@ -67,15 +72,16 @@ you publicly humiliated and your code rewritten without notice. An attribute definition is simply: -struct attribute { - char * name;
Documentation/filesystems/sysfs.rst you publicly humiliated and your code rewritten without notice. · line 81
Quoted 10 lines
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +6
-3- struct module *owner; - umode_t mode; -}; +.. code-block:: c + struct attribute { + char * name; + struct module *owner; + umode_t mode; + };
Here is where we go pretty far off the rails. If you go looking in include/linux/sysfs.h, the actual definition of this structure is:
struct attribute {
const char *name;
umode_t mode;
#ifdef CONFIG_DEBUG_LOCK_ALLOC
bool ignore_lockdep:1;
struct lock_class_key *key;
struct lock_class_key skey;#endif
};
Most notably, the owner field went away quite some time ago.
Documentation like this is not really useful to anybody; once a reader realizes it doesn't describe current reality, they will justifiably disregard it. This isn't your fault, of course, but converting something like this to RST gives the illusion that it has been updated, when that is very much not the case.
At a bare minimum, an effort like this needs to put a big flashing warning at the top of the file. But it would be soooooo much better to actually update the content as well.
The best way to do that would be to annotate the source with proper kerneldoc comments, then pull them into the documentation rather than repeating the information here. Is there any chance you might be up for taking on a task like this?
Thanks,
jon
_______________________________________________
Linux-kernel-mentees mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/linux-kernel-mentees
Quoted 198 lines · Jonathan Corbet
Quoted 23 lines · On Tue, 5 Nov 2019 12:48:46 +0530 Jaskaran Singh…
This patch converts sysfs.txt to
sysfs.rst, and adds a corresponding
entry inindex.rst.Most of the whitespacing and indentation is kept similar to the original document.
Changes to the original document include:
- Adding an authors statement in the header.
- Replacing the underscores in the title with asterisks. This is
so
that the "The" in the title appears in italics in HTML.
- Replacing the tilde (~) headings with equal signs, for reST
section
headings.
- List out the helper macros with backquotes and corresponding
description
on the next line.
- Placing C code and shell code in reST code blocks, with an
indentation
of an 8 length tab.Quoted 1 line
Signed-off-by Jaskaran Singh <[email protected]>Thanks for working to improve the documentation. There are some problems
here, none of which are your creation, but I would sure like to resolve
them while working with this document.The first of these is that
Documentation/filesystemsis really the wrong
place for this file - it's covering the internal API for subsystems that
want to create entries in sysfs. IMO, it belongs in either the driver-API
manual or the core-API manual - probably the latter.Quoted 26 lines
Documentation/filesystems/index.rst | 1 + .../filesystems/{sysfs.txt => sysfs.rst} | 323 ++++++++++-- ------ 2 files changed, 189 insertions(+), 135 deletions(-) rename Documentation/filesystems/{sysfs.txt => sysfs.rst} (60%)Documentation/filesystems/index.rst +1
-0@@ -46,4 +46,5 @@ Documentation for filesystem implementations. .. toctree:: :maxdepth: 2 + sysfs virtiofsDocumentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +0
-0Documentation/filesystems/sysfs.rst line 2
Quoted 5 lines
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +3
-1@@ -1,15 +1,18 @@ +====================================================== +sysfs - *The* filesystem for exporting kernel objects. +====================================================== -sysfs - _The_ filesystem for exporting kernel objects.Nits: We can really just drop emphasis like that, it doesn't really help
anybody. Also the period can go on section headers.Documentation/filesystems/sysfs.rst line 8
Quoted 6 lines
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +3
-2+Authors: -Patrick Mochel <[email protected]> -Mike Murphy <[email protected]> +- Patrick Mochel <[email protected]> +- Mike Murphy <[email protected]>I would be absolutely amazed if either of those email addresses works at
this point. I'd take them out.Documentation/filesystems/sysfs.rst line 11
Quoted 4 lines
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +2
-2-Revised: 16 August 2011 -Original: 10 January 2003 +| Revised: 16 August 2011 +| Original: 10 January 2003Dates like that are a red flag. See below.
Quoted 19 lines
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +1
-1What it is: -~~~~~~~~~~~ +=========== sysfs is a ram-based filesystem initially based on ramfs. Itprovides
a means to export kernel data structures, their attributes, and
theDocumentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +1
-1@@ -21,16 +24,18 @@ interface. Using sysfs -~~~~~~~~~~~ +=========== sysfs is always compiled in if CONFIG_SYSFS is defined. You canaccess
it by doing:Documentation/filesystems/sysfs.rst interface. · line 34
Quoted 4 lines
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +3
-1- mount -t sysfs sysfs /sys +.. code-block:: sh + + mount -t sysfs sysfs /sysIn the spirit of minimal markup, I'd do the above as:
it by doing::
mount -t sysfs sysfs /sys
But then I know that others are much more fond of .. code-block and syntax
highlighting than I am.Quoted 27 lines
Directory Creation
-~~~~~~~~~~~~~~~~~~
+==================For every kobject that is registered with the system, a directory
is
created for it in sysfs. That directory is created as a
subdirectoryDocumentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +0
-0@@ -48,7 +53,7 @@ only modified directly by the function
sysfs_schedule_callback().Attributes
-~~~~~~~~~~
+==========Attributes can be exported for kobjects in the form of regular
files in
the filesystem. Sysfs forwards file I/O operations to methods
definedDocumentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +0
-0@@ -67,15 +72,16 @@ you publicly humiliated and your code rewrittenwithout notice.
An attribute definition is simply:
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +0
-2-struct attribute { - char * name;Documentation/filesystems/sysfs.rst you publicly humiliated and your code rewritten without notice. · line 81
Quoted 10 lines
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +6
-3- struct module *owner; - umode_t mode; -}; +.. code-block:: c + struct attribute { + char * name; + struct module *owner; + umode_t mode; + };Here is where we go pretty far off the rails. If you go looking in
include/linux/sysfs.h, the actual definition of this structure is:struct attribute { const char *name; umode_t mode; #ifdef CONFIG_DEBUG_LOCK_ALLOC bool ignore_lockdep:1; struct lock_class_key *key; struct lock_class_key skey;#endif
};Most notably, the owner field went away quite some time ago.
Documentation like this is not really useful to anybody; once a reader
realizes it doesn't describe current reality, they will justifiably disregard it. This isn't your fault, of course, but converting something
like this to RST gives the illusion that it has been updated, when that is
very much not the case.At a bare minimum, an effort like this needs to put a big flashing warning
at the top of the file. But it would be soooooo much better to actually
update the content as well.
Quoted 6 lines
The best way to do that would be to annotate the source with proper kerneldoc comments, then pull them into the documentation rather than repeating the information here. Is there any chance you might be up for
taking on a task like this?
Sure! I'll send the documentation patch(es) followed by a v2 for this patch.
Cheers,
Jaskaran.
Quoted 4 lines
Thanks,
jon
Jonathan Corbet
maintainerQuoted 14 lines · On Sat, 09 Nov 2019 18:36:16 +0530 Jaskaran Singh…
Quoted 6 lines
At a bare minimum, an effort like this needs to put a big flashing warning
at the top of the file. But it would be soooooo much better to actually
update the content as well.Quoted 6 lines
The best way to do that would be to annotate the source with proper kerneldoc comments, then pull them into the documentation rather than repeating the information here. Is there any chance you might be up for
taking on a task like this?
Quoted 2 lines
Sure! I'll send the documentation patch(es) followed by a v2 for this patch.
Great. As an alternative, if you like, redo the current patch with the other suggested fixes and a "this is obsolete" warning at the top. Then, after the subsequent improvements land, that warning can eventually be removed again.
Thanks,
jon
Quoted 32 lines · Jonathan Corbet
Quoted 17 lines · On Sat, 09 Nov 2019 18:36:16 +0530 Jaskaran Singh…
Quoted 7 lines
At a bare minimum, an effort like this needs to put a big flashing
warning
at the top of the file. But it would be soooooo much better to actually
update the content as well.Quoted 9 lines
The best way to do that would be to annotate the source with proper
kerneldoc comments, then pull them into the documentation rather than
repeating the information here. Is there any chance you might be up
for
taking on a task like this?Quoted 3 lines
Sure! I'll send the documentation patch(es) followed by a v2 for this
patch.Great. As an alternative, if you like, redo the current patch with the
other suggested fixes and a "this is obsolete" warning at the top. Then,
after the subsequent improvements land, that warning can eventually be
removed again.
Quoted 3 lines
Thanks,
jon
Hopefully I can get the kernel-doc comments right. If not, I'll go with the alternative :)
Cheers,
Jaskaran.