* [Cluster-devel] [PATCH 19/44] docs: filesystems: convert gfs2.txt to ReST
2020-02-17 16:11 [Cluster-devel] [PATCH 00/44] Manually convert filesystem FS documents to ReST Mauro Carvalho Chehab
@ 2020-02-17 16:12 ` Mauro Carvalho Chehab
2020-02-18 13:13 ` Bob Peterson
2020-02-17 16:12 ` [Cluster-devel] [PATCH 20/44] docs: filesystems: convert gfs2-uevents.txt " Mauro Carvalho Chehab
` (2 subsequent siblings)
3 siblings, 1 reply; 10+ messages in thread
From: Mauro Carvalho Chehab @ 2020-02-17 16:12 UTC (permalink / raw)
To: cluster-devel.redhat.com
- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add it to filesystems/index.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../filesystems/{gfs2.txt => gfs2.rst} | 20 +++++++++++++------
Documentation/filesystems/index.rst | 1 +
2 files changed, 15 insertions(+), 6 deletions(-)
rename Documentation/filesystems/{gfs2.txt => gfs2.rst} (76%)
diff --git a/Documentation/filesystems/gfs2.txt b/Documentation/filesystems/gfs2.rst
similarity index 76%
rename from Documentation/filesystems/gfs2.txt
rename to Documentation/filesystems/gfs2.rst
index cc4f2306609e..8d1ab589ce18 100644
--- a/Documentation/filesystems/gfs2.txt
+++ b/Documentation/filesystems/gfs2.rst
@@ -1,5 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==================
Global File System
-------------------
+==================
https://fedorahosted.org/cluster/wiki/HomePage
@@ -14,16 +17,18 @@ on one machine show up immediately on all other machines in the cluster.
GFS uses interchangeable inter-node locking mechanisms, the currently
supported mechanisms are:
- lock_nolock -- allows gfs to be used as a local file system
+ lock_nolock
+ - allows gfs to be used as a local file system
- lock_dlm -- uses a distributed lock manager (dlm) for inter-node locking
- The dlm is found at linux/fs/dlm/
+ lock_dlm
+ - uses a distributed lock manager (dlm) for inter-node locking.
+ The dlm is found at linux/fs/dlm/
Lock_dlm depends on user space cluster management systems found
at the URL above.
To use gfs as a local file system, no external clustering systems are
-needed, simply:
+needed, simply::
$ mkfs -t gfs2 -p lock_nolock -j 1 /dev/block_device
$ mount -t gfs2 /dev/block_device /dir
@@ -37,9 +42,12 @@ GFS2 is not on-disk compatible with previous versions of GFS, but it
is pretty close.
The following man pages can be found at the URL above:
+
+ ============ =============================================
fsck.gfs2 to repair a filesystem
gfs2_grow to expand a filesystem online
gfs2_jadd to add journals to a filesystem online
tunegfs2 to manipulate, examine and tune a filesystem
- gfs2_convert to convert a gfs filesystem to gfs2 in-place
+ gfs2_convert to convert a gfs filesystem to gfs2 in-place
mkfs.gfs2 to make a filesystem
+ ============ =============================================
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index f69d20406be0..f24befe78326 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -65,6 +65,7 @@ Documentation for filesystem implementations.
ext2
ext3
f2fs
+ gfs2
fuse
overlayfs
virtiofs
--
2.24.1
^ permalink raw reply related [flat|nested] 10+ messages in thread
* [Cluster-devel] [PATCH 19/44] docs: filesystems: convert gfs2.txt to ReST
2020-02-17 16:12 ` [Cluster-devel] [PATCH 19/44] docs: filesystems: convert gfs2.txt " Mauro Carvalho Chehab
@ 2020-02-18 13:13 ` Bob Peterson
0 siblings, 0 replies; 10+ messages in thread
From: Bob Peterson @ 2020-02-18 13:13 UTC (permalink / raw)
To: cluster-devel.redhat.com
----- Original Message -----
> - Add a SPDX header;
> - Adjust document title;
> - Some whitespace fixes and new line breaks;
> - Mark literal blocks as such;
> - Add table markups;
> - Add it to filesystems/index.rst.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
> .../filesystems/{gfs2.txt => gfs2.rst} | 20 +++++++++++++------
> Documentation/filesystems/index.rst | 1 +
> 2 files changed, 15 insertions(+), 6 deletions(-)
> rename Documentation/filesystems/{gfs2.txt => gfs2.rst} (76%)
Looks good.
Acked-by: Bob Peterson <rpeterso@redhat.com>
^ permalink raw reply [flat|nested] 10+ messages in thread
* [Cluster-devel] [PATCH 20/44] docs: filesystems: convert gfs2-uevents.txt to ReST
2020-02-17 16:11 [Cluster-devel] [PATCH 00/44] Manually convert filesystem FS documents to ReST Mauro Carvalho Chehab
2020-02-17 16:12 ` [Cluster-devel] [PATCH 19/44] docs: filesystems: convert gfs2.txt " Mauro Carvalho Chehab
@ 2020-02-17 16:12 ` Mauro Carvalho Chehab
2020-02-18 13:13 ` Bob Peterson
2020-02-18 4:01 ` [Cluster-devel] [PATCH 00/44] Manually convert filesystem FS documents " Matthew Wilcox
2020-03-02 21:13 ` Jonathan Corbet
3 siblings, 1 reply; 10+ messages in thread
From: Mauro Carvalho Chehab @ 2020-02-17 16:12 UTC (permalink / raw)
To: cluster-devel.redhat.com
This document is almost in ReST format: all it needs is to have
the titles adjusted and add a SPDX header. In other words:
- Add a SPDX header;
- Add a document title;
- Adjust section titles;
- Add it to filesystems/index.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
.../{gfs2-uevents.txt => gfs2-uevents.rst} | 20 +++++++++++++++----
Documentation/filesystems/index.rst | 1 +
2 files changed, 17 insertions(+), 4 deletions(-)
rename Documentation/filesystems/{gfs2-uevents.txt => gfs2-uevents.rst} (94%)
diff --git a/Documentation/filesystems/gfs2-uevents.txt b/Documentation/filesystems/gfs2-uevents.rst
similarity index 94%
rename from Documentation/filesystems/gfs2-uevents.txt
rename to Documentation/filesystems/gfs2-uevents.rst
index 19a19ebebc34..f162a2c76c69 100644
--- a/Documentation/filesystems/gfs2-uevents.txt
+++ b/Documentation/filesystems/gfs2-uevents.rst
@@ -1,14 +1,18 @@
- uevents and GFS2
- ==================
+.. SPDX-License-Identifier: GPL-2.0
+
+================
+uevents and GFS2
+================
During the lifetime of a GFS2 mount, a number of uevents are generated.
This document explains what the events are and what they are used
for (by gfs_controld in gfs2-utils).
A list of GFS2 uevents
------------------------
+======================
1. ADD
+------
The ADD event occurs at mount time. It will always be the first
uevent generated by the newly created filesystem. If the mount
@@ -21,6 +25,7 @@ with no journal assigned), and read-only (with journal assigned) status
of the filesystem respectively.
2. ONLINE
+---------
The ONLINE uevent is generated after a successful mount or remount. It
has the same environment variables as the ADD uevent. The ONLINE
@@ -29,6 +34,7 @@ RDONLY are a relatively recent addition (2.6.32-rc+) and will not
be generated by older kernels.
3. CHANGE
+---------
The CHANGE uevent is used in two places. One is when reporting the
successful mount of the filesystem by the first node (FIRSTMOUNT=Done).
@@ -52,6 +58,7 @@ cluster. For this reason the ONLINE uevent was used when adding a new
uevent for a successful mount or remount.
4. OFFLINE
+----------
The OFFLINE uevent is only generated due to filesystem errors and is used
as part of the "withdraw" mechanism. Currently this doesn't give any
@@ -59,6 +66,7 @@ information about what the error is, which is something that needs to
be fixed.
5. REMOVE
+---------
The REMOVE uevent is generated at the end of an unsuccessful mount
or at the end of a umount of the filesystem. All REMOVE uevents will
@@ -68,9 +76,10 @@ kobject subsystem.
Information common to all GFS2 uevents (uevent environment variables)
-----------------------------------------------------------------------
+=====================================================================
1. LOCKTABLE=
+--------------
The LOCKTABLE is a string, as supplied on the mount command
line (locktable=) or via fstab. It is used as a filesystem label
@@ -78,6 +87,7 @@ as well as providing the information for a lock_dlm mount to be
able to join the cluster.
2. LOCKPROTO=
+-------------
The LOCKPROTO is a string, and its value depends on what is set
on the mount command line, or via fstab. It will be either
@@ -85,12 +95,14 @@ lock_nolock or lock_dlm. In the future other lock managers
may be supported.
3. JOURNALID=
+-------------
If a journal is in use by the filesystem (journals are not
assigned for spectator mounts) then this will give the
numeric journal id in all GFS2 uevents.
4. UUID=
+--------
With recent versions of gfs2-utils, mkfs.gfs2 writes a UUID
into the filesystem superblock. If it exists, this will
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index f24befe78326..c16e517e37c5 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -66,6 +66,7 @@ Documentation for filesystem implementations.
ext3
f2fs
gfs2
+ gfs2-uevents
fuse
overlayfs
virtiofs
--
2.24.1
^ permalink raw reply related [flat|nested] 10+ messages in thread
* [Cluster-devel] [PATCH 00/44] Manually convert filesystem FS documents to ReST
2020-02-17 16:11 [Cluster-devel] [PATCH 00/44] Manually convert filesystem FS documents to ReST Mauro Carvalho Chehab
2020-02-17 16:12 ` [Cluster-devel] [PATCH 19/44] docs: filesystems: convert gfs2.txt " Mauro Carvalho Chehab
2020-02-17 16:12 ` [Cluster-devel] [PATCH 20/44] docs: filesystems: convert gfs2-uevents.txt " Mauro Carvalho Chehab
@ 2020-02-18 4:01 ` Matthew Wilcox
2020-02-18 10:04 ` Mauro Carvalho Chehab
2020-03-02 21:13 ` Jonathan Corbet
3 siblings, 1 reply; 10+ messages in thread
From: Matthew Wilcox @ 2020-02-18 4:01 UTC (permalink / raw)
To: cluster-devel.redhat.com
On Mon, Feb 17, 2020 at 05:11:46PM +0100, Mauro Carvalho Chehab wrote:
> There are lots of plain text documents under Documentation/filesystems.
>
> Manually convert several of those to ReST and add them to the index file.
I think at least 90% of this material needs to be in admin-guide. Should
we create Documentation/admin-guide/filesystems/ and move most of these
files there?
^ permalink raw reply [flat|nested] 10+ messages in thread
* [Cluster-devel] [PATCH 00/44] Manually convert filesystem FS documents to ReST
2020-02-18 4:01 ` [Cluster-devel] [PATCH 00/44] Manually convert filesystem FS documents " Matthew Wilcox
@ 2020-02-18 10:04 ` Mauro Carvalho Chehab
2020-02-19 9:32 ` Jonathan Corbet
0 siblings, 1 reply; 10+ messages in thread
From: Mauro Carvalho Chehab @ 2020-02-18 10:04 UTC (permalink / raw)
To: cluster-devel.redhat.com
Em Mon, 17 Feb 2020 20:01:46 -0800
Matthew Wilcox <willy@infradead.org> escreveu:
> On Mon, Feb 17, 2020 at 05:11:46PM +0100, Mauro Carvalho Chehab wrote:
> > There are lots of plain text documents under Documentation/filesystems.
> >
> > Manually convert several of those to ReST and add them to the index file.
>
> I think at least 90% of this material needs to be in admin-guide. Should
> we create Documentation/admin-guide/filesystems/ and move most of these
> files there?
It makes sense to me. Yet, there are some of those files that contains
both user-facing and kernel-facing docs at the same place.
Btw, I found the same pattern on *several* other subsystems: when
someone is documenting some feature, it tends to document both kAPI,
uAPI and admin.
Right now, what we did so far on most places were to keep the stuff
together, as splitting them could sometimes be painful.
As we are too close to finish the ReST conversion[1], I would prefer to
first finish it.
Then, do a second pass at files outside the new directories (like
admin-guide), in order to better organize things, eventually splitting
some files into kAPI, uAPI and/or admin-guide.
[1] Looking at next-20200217, after my last doc patches applied on this tree:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=all_docs_merged
excluding (most) false positives, we have now only ~50 text files left to
convert:
$ dirname $(find Documentation/ -type f|grep -vE '\.(rst|svg|dot|py|awk|sh|pl|gitignore|S|yaml|c|inf|vim|modes)'|grep -vE '(Makefile|Kconfig|LICENSE|COPYING-logo|ChangeLog|CREDITS)'|grep -v devicetree/bindings|grep -vE 'Documentation/(ABI|features|output|SubmittingPatches|CodingStyle|logo.gif|dontdiff|sphinx/requirements.txt|admin-guide/kdump/gdbmacros.txt|admin-guide/aoe/udev.txt|EDID/hex|netlabel/draft-ietf-cipso-ipsecurity-01.txt|firmware_class/hotplug-script|target/target-export-device|networking/mac80211-auth-assoc-deauth.txt|sparc/oradax/dax-hv-api.txt)'|grep -v translations)|sort|uniq -c|sort -n
$ echo -n "Total: "
$ dirname $(find Documentation/ -type f|grep -vE '\.(rst|svg|dot|py|awk|sh|pl|gitignore|S|yaml|c|inf|vim|modes)'|grep -vE '(Makefile|Kconfig|LICENSE|COPYING-logo|ChangeLog|CREDITS)'|grep -v devicetree/bindings|grep -vE 'Documentation/(ABI|features|output|SubmittingPatches|CodingStyle|logo.gif|dontdiff|sphinx/requirements.txt|admin-guide/kdump/gdbmacros.txt|admin-guide/aoe/udev.txt|EDID/hex|netlabel/draft-ietf-cipso-ipsecurity-01.txt|firmware_class/hotplug-script|target/target-export-device|networking/mac80211-auth-assoc-deauth.txt|sparc/oradax/dax-hv-api.txt)'|grep -v translations)|wc -l
1 Documentation/filesystems/cifs
1 Documentation/filesystems/configfs
1 Documentation/scsi
1 Documentation/virt/kvm/devices
2 Documentation/admin-guide
3 Documentation
6 Documentation/devicetree
6 Documentation/filesystems/caching
8 Documentation/RCU
21 Documentation/filesystems
Total: 50
Once we get this series merged, I'm planning to prepare and submit a second
series doing the conversion for the other ~20 filesystem files.
Btw, if you want to look how things will become after my patch series,
I'm keeping a html build after all my patch series at:
https://www.infradead.org/~mchehab/kernel_docs/
Cheers,
Mauro
^ permalink raw reply [flat|nested] 10+ messages in thread
* [Cluster-devel] [PATCH 00/44] Manually convert filesystem FS documents to ReST
2020-02-18 10:04 ` Mauro Carvalho Chehab
@ 2020-02-19 9:32 ` Jonathan Corbet
2020-02-19 15:11 ` Mauro Carvalho Chehab
0 siblings, 1 reply; 10+ messages in thread
From: Jonathan Corbet @ 2020-02-19 9:32 UTC (permalink / raw)
To: cluster-devel.redhat.com
On Tue, 18 Feb 2020 11:04:06 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> Then, do a second pass at files outside the new directories (like
> admin-guide), in order to better organize things, eventually splitting
> some files into kAPI, uAPI and/or admin-guide.
I'm looking forward to this phase! Yes it is harder, and it often
requires selling the idea to skeptical maintainers. But that is how,
IMO, we get from where we're at now to something closer to a set of
coherent kernel docs.
Thanks,
jon
^ permalink raw reply [flat|nested] 10+ messages in thread
* [Cluster-devel] [PATCH 00/44] Manually convert filesystem FS documents to ReST
2020-02-19 9:32 ` Jonathan Corbet
@ 2020-02-19 15:11 ` Mauro Carvalho Chehab
0 siblings, 0 replies; 10+ messages in thread
From: Mauro Carvalho Chehab @ 2020-02-19 15:11 UTC (permalink / raw)
To: cluster-devel.redhat.com
Em Wed, 19 Feb 2020 02:32:34 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:
> On Tue, 18 Feb 2020 11:04:06 +0100
> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
>
> > Then, do a second pass at files outside the new directories (like
> > admin-guide), in order to better organize things, eventually splitting
> > some files into kAPI, uAPI and/or admin-guide.
>
> I'm looking forward to this phase! Yes it is harder, and it often
> requires selling the idea to skeptical maintainers. But that is how,
> IMO, we get from where we're at now to something closer to a set of
> coherent kernel docs.
Yeah, fully agreed that this is an important step.
I'm even more anxious for a third phase: filling the gaps. I'm pretty sure
that several important parts of the Kernel aren't properly represented
at Documentation.
Yet, before start writing new things, we should first organizing what we
already have, making them well-organized.
Cheers,
Mauro
^ permalink raw reply [flat|nested] 10+ messages in thread
* [Cluster-devel] [PATCH 00/44] Manually convert filesystem FS documents to ReST
2020-02-17 16:11 [Cluster-devel] [PATCH 00/44] Manually convert filesystem FS documents to ReST Mauro Carvalho Chehab
` (2 preceding siblings ...)
2020-02-18 4:01 ` [Cluster-devel] [PATCH 00/44] Manually convert filesystem FS documents " Matthew Wilcox
@ 2020-03-02 21:13 ` Jonathan Corbet
3 siblings, 0 replies; 10+ messages in thread
From: Jonathan Corbet @ 2020-03-02 21:13 UTC (permalink / raw)
To: cluster-devel.redhat.com
On Mon, 17 Feb 2020 17:11:46 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> There are lots of plain text documents under Documentation/filesystems.
>
> Manually convert several of those to ReST and add them to the index file.
OK, I've finally managed to add all the acks and wrestle this pile into
docs-next - thanks.
jon
^ permalink raw reply [flat|nested] 10+ messages in thread