Skip to contentSkip to conversation

docs: filesystems: sysfs: convert sysfs.txt to reST

PATCH RESEND In review Jaskaran Singh 2 participants 5 messages Nov 5, 2019 – Nov 13, 2019 Documentation

lore
Share & tools
lore
#0 lore raw

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
index 2c3a9f761205..18b5ea780b9b 100644
@@ -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
maintainer
#1 lore raw
Quoted 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 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.

Quoted 1 line

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
index 2c3a9f761205..18b5ea780b9b 100644
@@ -46,4 +46,5 @@ Documentation for filesystem implementations.
 .. toctree::
    :maxdepth: 2
 
+   sysfs
    virtiofs
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +0 -0
similarity index 60%
rename from Documentation/filesystems/sysfs.txt
rename to Documentation/filesystems/sysfs.rst
index ddf15b1b0d5a..de0de5869323 100644

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 -1
 What 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 -4
 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 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

#2 lore raw
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 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.

Quoted 1 line

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 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
index 2c3a9f761205..18b5ea780b9b 100644
@@ -46,4 +46,5 @@ Documentation for filesystem implementations.
 .. toctree::
    :maxdepth: 2
 
+   sysfs
    virtiofs
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +0 -0
similarity index 60%
rename from Documentation/filesystems/sysfs.txt
rename to Documentation/filesystems/sysfs.rst
index ddf15b1b0d5a..de0de5869323 100644

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 19 lines
Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +1 -1
 What 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

Documentation/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 can

access
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 /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 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
subdirectory

Documentation/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
defined

Documentation/filesystems/sysfs.rst renamed from Documentation/filesystems/sysfs.txt +0 -0
@@ -67,15 +72,16 @@ you publicly humiliated and your code rewritten

without 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

maintainer
#3 lore raw
Quoted 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

#4 lore raw
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.