Skip to contentSkip to conversation

Documentation: filesystems: Convert jfs.txt to reStructedText format.

PATCH Superseded Shobhit Kukreti 4 participants 8 messages Jul 6, 2019 – Jul 31, 2019

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Documentation: filesystems: Convert jfs.txt to reStructedText format.

This converts the plain text documentation of jfs.txt to reStructuredText format. Added to documentation build process and verified with make htmldocs

Signed-off-by Shobhit Kukreti <shobhitkukreti at gmail.com>
---
 Documentation/filesystems/index.rst |  1 +
 Documentation/filesystems/jfs.rst   | 74 +++++++++++++++++++++++++++++++++++++
 Documentation/filesystems/jfs.txt   | 52 --------------------------
 3 files changed, 75 insertions(+), 52 deletions(-)
 create mode 100644 Documentation/filesystems/jfs.rst
 delete mode 100644 Documentation/filesystems/jfs.txt
Documentation/filesystems/index.rst +1 -0
index 1131c34..d700330 100644
@@ -41,3 +41,4 @@ Documentation for individual filesystem types can be found here.
    :maxdepth: 2
 
    binderfs.rst
+   jfs
Documentation/filesystems/jfs.rst new file +74 -0

74 lines not on this page · raw message

Documentation/filesystems/jfs.txt deleted +0 -52

52 lines not on this page · raw message

Signature · 1 line
2.7.4
maintainer
#1 lore raw
Quoted 4 lines · On Sat, 6 Jul 2019 16:22:39 -0700 Shobhit Kukreti <shobhitkukreti at…

This converts the plain text documentation of jfs.txt to reStructuredText format. Added to documentation build process and verified with make htmldocs

Signed-off-by Shobhit Kukreti <shobhitkukreti at gmail.com>

Thanks for working to make the kernel documentation better. That said, I do have a request...

Quoted 29 lines
---
 Documentation/filesystems/index.rst |  1 +
 Documentation/filesystems/jfs.rst   | 74 +++++++++++++++++++++++++++++++++++++
 Documentation/filesystems/jfs.txt   | 52 --------------------------
 3 files changed, 75 insertions(+), 52 deletions(-)
 create mode 100644 Documentation/filesystems/jfs.rst
 delete mode 100644 Documentation/filesystems/jfs.txt
Documentation/filesystems/index.rst +1 -0
index 1131c34..d700330 100644
@@ -41,3 +41,4 @@ Documentation for individual filesystem types can be found here.
    :maxdepth: 2
 
    binderfs.rst
+   jfs
Documentation/filesystems/jfs.rst new file +6 -0
new file mode 100644
index 0000000..bfb6110
@@ -0,0 +1,74 @@
+===========================================
+IBM's Journaled File System (JFS) for Linux
+===========================================
+
+JFS Homepage:  http://jfs.sourceforge.net/
+

Documentation/filesystems/jfs.rst line 16

Quoted 10 lines
Documentation/filesystems/jfs.rst new file +10 -0
+Following Mount Options are Supported
+
+(*) == default
+ .. tabularcolumns:: |p{1.3cm}|p{1.3cm}|p{8.0cm}|
+
+.. cssclass:: longtable
+
+.. flat-table::   
+  :header-rows:  0
+  :stub-columns: 0

Please don't use flat-table unless you really need to. It makes the documents harder to read in plain-text form, which is something we want to avoid whenever possible. A simple definition list seems more appropriate for this information.

(I should really update the documentation to discourage use of flat-table).

Note that the merge window is open, so expect me to be even slower than usual to respond to things for the next couple of weeks.

Thanks,

jon

#2 lore raw
In reply to Shobhit Kukreti

Documentation/filesystems/index.rst Documentation for individual filesystem types can be found here. · line 44

Quoted 6 lines · Shobhit Kukreti

+++ b/Documentation/filesystems/index.rst

Documentation/filesystems/index.rst +1 -0
@@ -41,3 +41,4 @@ Documentation for individual filesystem types can be found here.
    :maxdepth: 2
 
    binderfs.rst
+   jfs

This is the wrong place for this file. See earlier conversation with Sheriff Esseson, and the patch from me to move binderfs.

Documentation/filesystems/jfs.rst

Quoted 5 lines
Documentation/filesystems/jfs.rst new file +0 -0
new file mode 100644
index 0000000..bfb6110

Why is git not detecting this as (mostly) a rename?

#3 lore raw

PATCH v2 1/1 Documentation: filesystems: Convert jfs.txt to

This converts the plain text documentation of jfs.txt to reStructuredText format. Added to documentation build process and verified with make htmldocs

Signed-off-by Shobhit Kukreti <shobhitkukreti at gmail.com>

---
Changes in v2:
1. Removed flat-table.
2. Moved jfs.rst from filesystem to admin-guide

 Documentation/admin-guide/index.rst |  1 +
 Documentation/admin-guide/jfs.rst   | 50 +++++++++++++++++++++++++++++++++++
 Documentation/filesystems/jfs.txt   | 52 -------------------------------------
 3 files changed, 51 insertions(+), 52 deletions(-)
 create mode 100644 Documentation/admin-guide/jfs.rst
 delete mode 100644 Documentation/filesystems/jfs.txt
Documentation/admin-guide/index.rst +1 -0
index 8001917..2871b79 100644
@@ -70,6 +70,7 @@ configure specific aspects of kernel behavior to your liking.
    ras
    bcache
    ext4
+   jfs
    pm/index
    thunderbolt
    LSM/index
Documentation/admin-guide/jfs.rst new file +50 -0

50 lines not on this page · raw message

Documentation/filesystems/jfs.txt deleted +0 -52

52 lines not on this page · raw message

Signature · 1 line
2.7.4
#4 lore raw

Re: [PATCH v2] Documentation: filesystems: Convert jfs.txt to

Em Tue, 9 Jul 2019 20:25:25 -0700
Shobhit Kukreti <shobhitkukreti at gmail.com> escreveu:

Quoted 9 lines

This converts the plain text documentation of jfs.txt to reStructuredText format. Added to documentation build process and verified with make htmldocs

Signed-off-by Shobhit Kukreti <shobhitkukreti at gmail.com>

---
Changes in v2:
1. Removed flat-table.
2. Moved jfs.rst from filesystem to admin-guide

Quoted 6 lines
 Documentation/admin-guide/index.rst |  1 +
 Documentation/admin-guide/jfs.rst   | 50 +++++++++++++++++++++++++++++++++++
 Documentation/filesystems/jfs.txt   | 52 -------------------------------------
 3 files changed, 51 insertions(+), 52 deletions(-)
 create mode 100644 Documentation/admin-guide/jfs.rst
 delete mode 100644 Documentation/filesystems/jfs.txt

As commented on ufs patch, please use -M1 to show it as a diff, and not as two separate changes.

Quoted 19 lines
Documentation/admin-guide/index.rst +1 -0
index 8001917..2871b79 100644
@@ -70,6 +70,7 @@ configure specific aspects of kernel behavior to your liking.
    ras
    bcache
    ext4
+   jfs
    pm/index
    thunderbolt
    LSM/index
Documentation/admin-guide/jfs.rst new file +0 -0
new file mode 100644
index 0000000..a0a95e5

Documentation/admin-guide/jfs.rst line 6

Quoted 6 lines
Documentation/admin-guide/jfs.rst new file +6 -0
@@ -0,0 +1,50 @@
+===========================================
+IBM's Journaled File System (JFS) for Linux
+===========================================
+
+JFS Homepage:  `<http://jfs.sourceforge.net/>`_
+

No need. Just keep it as:

JFS Homepage: http://jfs.sourceforge.net/

Sphinx will do the right thing when it finds a URL that starts with http/https.

Documentation/admin-guide/jfs.rst line 8

Quoted 2 lines
Documentation/admin-guide/jfs.rst new file +2 -0
+The following mount options are supported:
+(*) == default

You need a blank line between those two above.

Quoted 22 lines
Documentation/admin-guide/jfs.rst new file +22 -0
+
+**iocharset=name**      Character set to use for converting from Unicode to ASCII. The default is to do no conversion.
+
+**iocharset=utf8**      Use for UTF-8 translations. This requires CONFIG_NLS_UTF8 to be set in the kernel .config file.
+
+**iocharset=none**      specifies the default behavior explicitly.
+
+**resize=value**        Resize the volume to <value> blocks. JFS only supports growing a volume, not shrinking it.
+This option is only valid during a remount, when the volume is mounted read-write. The resize keyword with no value 
+will grow the volume to the full size of the partition.
+
+
+**nointegrity**	        Do not write to the journal. The primary use of this option is to allow for higher performance 
+when restoring a volume from backup media. The integrity of the volume is not guaranteed if the system abnormally abends.
+
+**integrity(*)**	Commit metadata changes to the journal. Use this option to remount a volume where the nointegrity 
+option was previously specified in order to restore normal behavior.
+
+**errors=continue**	Keep going on a filesystem error.
+
+**errors=remount-ro(*)**	Remount the filesystem read-only on an error.
+

Documentation/admin-guide/jfs.rst line 40

Quoted 10 lines
Documentation/admin-guide/jfs.rst new file +10 -0
+**errors=panic**	Panic and halt the machine if an error occurs.
+
+**uid=value**	Override on-disk uid with specified value
+
+**gid=value**	Override on-disk gid with specified value
+
+**umask=value**	Override on-disk umask with specified octal value. For directories, the execute bit will be set if the 
+corresponding  read bit is set.
+
+**discard=minlen, discard, nodiscard(*)**

Please preserve as much as possible the original format.

If you just place the mount option on one line and the description at the next one, e. g.:

iocharset=name
Character set to use for converting from Unicode to ASCII. The default is to do no conversion. Use iocharset=utf8 for UTF-8 translations. This requires CONFIG_NLS_UTF8 to be set in the kernel .config file. iocharset=none specifies the default behavior explicitly.

resize=value
Resize the volume to <value> blocks. JFS only supports growing a volume, not shrinking it. This option is only valid during a remount, when the volume is mounted read-write. The resize keyword with no value will grow the volume to the full size of the partition.
...

It will produce a very nice output, and the changes will be minimum, without any special markup.

Documentation/admin-guide/jfs.rst line 50

Quoted 10 lines
Documentation/admin-guide/jfs.rst new file +10 -0
+
+This enables/disables the use of discard/TRIM commands. The discard/TRIM 
+commands are sent to the underlying block device when blocks are freed. This is useful for SSD devices and 
+sparse/thinly-provisioned LUNs. The FITRIM ioctl command is also available together with the nodiscard option.
+The value of minlen specifies the minimum blockcount, when a TRIM command to the block device is considered useful.
+When no value is given to the discard option, it defaults to 64 blocks, which means 256KiB in JFS. The minlen value 
+of discard overrides the minlen value given on an FITRIM ioctl().
+
+The JFS mailing list can be subscribed to by using the link labeled
+"Mail list Subscribe" at our web page `<http://jfs.sourceforge.net/>`_

Same here: just keep the URL as-is:

The JFS mailing list can be subscribed to by using the link labeled "Mail list Subscribe" at our web page http://jfs.sourceforge.net/

Quoted 48 lines
Documentation/filesystems/jfs.txt deleted +0 -42
deleted file mode 100644
index 41fd757..0000000
@@ -1,52 +0,0 @@
-IBM's Journaled File System (JFS) for Linux
-
-JFS Homepage:  http://jfs.sourceforge.net/
-
-The following mount options are supported:
-(*) == default
-
-iocharset=name	Character set to use for converting from Unicode to
-		ASCII.  The default is to do no conversion.  Use
-		iocharset=utf8 for UTF-8 translations.  This requires
-		CONFIG_NLS_UTF8 to be set in the kernel .config file.
-		iocharset=none specifies the default behavior explicitly.
-
-resize=value	Resize the volume to <value> blocks.  JFS only supports
-		growing a volume, not shrinking it.  This option is only
-		valid during a remount, when the volume is mounted
-		read-write.  The resize keyword with no value will grow
-		the volume to the full size of the partition.
-
-nointegrity	Do not write to the journal.  The primary use of this option
-		is to allow for higher performance when restoring a volume
-		from backup media.  The integrity of the volume is not
-		guaranteed if the system abnormally abends.
-
-integrity(*)	Commit metadata changes to the journal.  Use this option to
-		remount a volume where the nointegrity option was
-		previously specified in order to restore normal behavior.
-
-errors=continue		Keep going on a filesystem error.
-errors=remount-ro(*)	Remount the filesystem read-only on an error.
-errors=panic		Panic and halt the machine if an error occurs.
-
-uid=value	Override on-disk uid with specified value
-gid=value	Override on-disk gid with specified value
-umask=value	Override on-disk umask with specified octal value.  For
-		directories, the execute bit will be set if the corresponding
-		read bit is set.
-
-discard=minlen	This enables/disables the use of discard/TRIM commands.
-discard		The discard/TRIM commands are sent to the underlying
-nodiscard(*)	block device when blocks are freed. This is useful for SSD
-		devices and sparse/thinly-provisioned LUNs.  The FITRIM ioctl

Documentation/filesystems/jfs.txt line 52

Quoted 10 lines
Documentation/filesystems/jfs.txt deleted +0 -10
-		command is also available together with the nodiscard option.
-		The value of minlen specifies the minimum blockcount, when
-		a TRIM command to the block device is considered useful.
-		When no value is given to the discard option, it defaults to
-		64 blocks, which means 256KiB in JFS.
-		The minlen value of discard overrides the minlen value given
-		on an FITRIM ioctl().
-
-The JFS mailing list can be subscribed to by using the link labeled
-"Mail list Subscribe" at our web page http://jfs.sourceforge.net/

Thanks,
Mauro

#5 lore raw

PATCH v3 1/1 Documentation: filesystems: Convert jfs.txt to

This converts the plain text documentation of jfs.txt to reStructuredText format. Added to documentation build process and verified with make htmldocs

Signed-off-by Shobhit Kukreti <shobhitkukreti at gmail.com>

---
Changes in v3:
1. Reverted to minimally changed jfs.rst
2. Used -M1 in git format-patch to show files as renamed

Changes in v2:
1. Removed flat-table.
2. Moved jfs.rst from filesystem to admin-guide

 Documentation/admin-guide/index.rst                |  1 +
 .../{filesystems/jfs.txt => admin-guide/jfs.rst}   | 44 ++++++++++++++--------
 2 files changed, 30 insertions(+), 15 deletions(-)
 rename Documentation/{filesystems/jfs.txt => admin-guide/jfs.rst} (51%)
Documentation/admin-guide/index.rst +1 -0
index 8001917..2871b79 100644
@@ -70,6 +70,7 @@ configure specific aspects of kernel behavior to your liking.
    ras
    bcache
    ext4
+   jfs
    pm/index
    thunderbolt
    LSM/index
Documentation/admin-guide/jfs.rst renamed from Documentation/filesystems/jfs.txt +29 -15

74 lines not on this page · raw message

Signature · 1 line
2.7.4
Reviewed-by on v3 1/1
#6 lore raw

Re: [PATCH v3] Documentation: filesystems: Convert jfs.txt to

Em Wed, 10 Jul 2019 08:29:01 -0700
Shobhit Kukreti <shobhitkukreti at gmail.com> escreveu:

Quoted 5 lines

This converts the plain text documentation of jfs.txt to reStructuredText format. Added to documentation build process and verified with make htmldocs

Signed-off-by Shobhit Kukreti <shobhitkukreti at gmail.com>
Reviewed-by Mauro Carvalho Chehab <mchehab+samsung at kernel.org>
Quoted 98 lines

---
Changes in v3:
1. Reverted to minimally changed jfs.rst
2. Used -M1 in git format-patch to show files as renamed

Changes in v2:
1. Removed flat-table.
2. Moved jfs.rst from filesystem to admin-guide

 Documentation/admin-guide/index.rst                |  1 +
 .../{filesystems/jfs.txt => admin-guide/jfs.rst}   | 44 ++++++++++++++--------
 2 files changed, 30 insertions(+), 15 deletions(-)
 rename Documentation/{filesystems/jfs.txt => admin-guide/jfs.rst} (51%)
Documentation/admin-guide/index.rst +1 -0
index 8001917..2871b79 100644
@@ -70,6 +70,7 @@ configure specific aspects of kernel behavior to your liking.
    ras
    bcache
    ext4
+   jfs
    pm/index
    thunderbolt
    LSM/index
Documentation/admin-guide/jfs.rst renamed from Documentation/filesystems/jfs.txt +24 -13
similarity index 51%
rename from Documentation/filesystems/jfs.txt
rename to Documentation/admin-guide/jfs.rst
index 41fd757..9e12d93 100644
@@ -1,45 +1,59 @@
+===========================================
 IBM's Journaled File System (JFS) for Linux
+===========================================
 
 JFS Homepage:  http://jfs.sourceforge.net/
 
 The following mount options are supported:
+
 (*) == default
 
-iocharset=name	Character set to use for converting from Unicode to
+iocharset=name
+                Character set to use for converting from Unicode to
 		ASCII.  The default is to do no conversion.  Use
 		iocharset=utf8 for UTF-8 translations.  This requires
 		CONFIG_NLS_UTF8 to be set in the kernel .config file.
 		iocharset=none specifies the default behavior explicitly.
 
-resize=value	Resize the volume to <value> blocks.  JFS only supports
+resize=value
+                Resize the volume to <value> blocks.  JFS only supports
 		growing a volume, not shrinking it.  This option is only
 		valid during a remount, when the volume is mounted
 		read-write.  The resize keyword with no value will grow
 		the volume to the full size of the partition.
 
-nointegrity	Do not write to the journal.  The primary use of this option
+nointegrity
+                Do not write to the journal.  The primary use of this option
 		is to allow for higher performance when restoring a volume
 		from backup media.  The integrity of the volume is not
 		guaranteed if the system abnormally abends.
 
-integrity(*)	Commit metadata changes to the journal.  Use this option to
+integrity(*)
+                Commit metadata changes to the journal.  Use this option to
 		remount a volume where the nointegrity option was
 		previously specified in order to restore normal behavior.
 
-errors=continue		Keep going on a filesystem error.
-errors=remount-ro(*)	Remount the filesystem read-only on an error.
-errors=panic		Panic and halt the machine if an error occurs.
+errors=continue
+                        Keep going on a filesystem error.
+errors=remount-ro(*)
+                        Remount the filesystem read-only on an error.
+errors=panic
+                        Panic and halt the machine if an error occurs.
 
-uid=value	Override on-disk uid with specified value
-gid=value	Override on-disk gid with specified value
-umask=value	Override on-disk umask with specified octal value.  For
-		directories, the execute bit will be set if the corresponding
+uid=value
+                Override on-disk uid with specified value
+gid=value
+                Override on-disk gid with specified value
+umask=value
+                Override on-disk umask with specified octal value. For
+                directories, the execute bit will be set if the corresponding
 		read bit is set.
 
-discard=minlen	This enables/disables the use of discard/TRIM commands.
-discard		The discard/TRIM commands are sent to the underlying

Documentation/admin-guide/jfs.rst line 59

Quoted 10 lines
Documentation/admin-guide/jfs.rst renamed from Documentation/filesystems/jfs.txt +5 -2
-nodiscard(*)	block device when blocks are freed. This is useful for SSD
-		devices and sparse/thinly-provisioned LUNs.  The FITRIM ioctl
+discard=minlen, discard/nodiscard(*)
+                This enables/disables the use of discard/TRIM commands.
+		The discard/TRIM commands are sent to the underlying
+                block device when blocks are freed. This is useful for SSD
+                devices and sparse/thinly-provisioned LUNs.  The FITRIM ioctl
 		command is also available together with the nodiscard option.
 		The value of minlen specifies the minimum blockcount, when
 		a TRIM command to the block device is considered useful.

Thanks,
Mauro

maintainer
#7 lore raw

Re: [PATCH v3] Documentation: filesystems: Convert jfs.txt to

In reply to Shobhit Kukreti
Quoted 5 lines · On Wed, 10 Jul 2019 08:29:01 -0700 Shobhit Kukreti <shobhitkukreti at…

This converts the plain text documentation of jfs.txt to reStructuredText format. Added to documentation build process and verified with make htmldocs

Signed-off-by Shobhit Kukreti <shobhitkukreti at gmail.com>

So this kind of fell through the cracks, sorry; I've applied it now.

Thanks,

jon