linux-erofs.lists.ozlabs.org archive mirror
 help / color / mirror / Atom feed
* [PATCH 00/44] Manually convert filesystem FS documents to ReST
@ 2020-02-17 16:11 Mauro Carvalho Chehab
  2020-02-17 16:12 ` [PATCH 15/44] docs: filesystems: convert erofs.txt " Mauro Carvalho Chehab
                   ` (2 more replies)
  0 siblings, 3 replies; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-02-17 16:11 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Latchesar Ionkov, Martin Brandenburg, Jan Kara,
	Dominique Martinet, Amir Goldstein, Bob Copeland, David Howells,
	Joseph Qi, linux-mtd, Tyler Hicks, linux-afs, Mike Marshall,
	Naohiro Aota, Christoph Hellwig, linux-nilfs,
	Andreas Gruenbacher, Sage Weil, Jonathan Corbet,
	Mauro Carvalho Chehab, Richard Weinberger, Mark Fasheh,
	Chris Mason, Ryusuke Konishi, cluster-devel, v9fs-developer,
	Gao Xiang, linux-ext4, Salah Triki, Alexey Dobriyan, devel,
	ecryptfs, Eric Van Hensbergen, Josef Bacik, linux-fsdevel,
	Joel Becker, Tigran A. Aivazian, David Sterba, Jaegeuk Kim,
	ceph-devel, Ilya Dryomov, Anton Altaparmakov, Damien Le Moal,
	Luis de Bethencourt, Nicolas Pitre, linux-ntfs-dev, Jeff Layton,
	linux-f2fs-devel, linux-btrfs, Jan Kara, Bob Peterson,
	Phillip Lougher, Johannes Thumshirn, linux-erofs,
	linux-karma-devel, ocfs2-devel

There are lots of plain text documents under Documentation/filesystems.

Manually convert several of those to ReST and add them to the index file.

Mauro Carvalho Chehab (44):
  docs: filesystems: convert 9p.txt to ReST
  docs: filesystems: convert adfs.txt to ReST
  docs: filesystems: convert affs.txt to ReST
  docs: filesystems: convert afs.txt to ReST
  docs: filesystems: convert autofs-mount-control.txt to ReST
  docs: filesystems: convert befs.txt to ReST
  docs: filesystems: convert bfs.txt to ReST
  docs: filesystems: convert btrfs.txt to ReST
  docs: filesystems: convert ceph.txt to ReST
  docs: filesystems: convert cramfs.txt to ReST
  docs: filesystems: convert debugfs.txt to ReST
  docs: filesystems: convert dlmfs.txt to ReST
  docs: filesystems: convert ecryptfs.txt to ReST
  docs: filesystems: convert efivarfs.txt to ReST
  docs: filesystems: convert erofs.txt to ReST
  docs: filesystems: convert ext2.txt to ReST
  docs: filesystems: convert ext3.txt to ReST
  docs: filesystems: convert f2fs.txt to ReST
  docs: filesystems: convert gfs2.txt to ReST
  docs: filesystems: convert gfs2-uevents.txt to ReST
  docs: filesystems: convert hfsplus.txt to ReST
  docs: filesystems: convert hfs.txt to ReST
  docs: filesystems: convert hpfs.txt to ReST
  docs: filesystems: convert inotify.txt to ReST
  docs: filesystems: convert isofs.txt to ReST
  docs: filesystems: convert nilfs2.txt to ReST
  docs: filesystems: convert ntfs.txt to ReST
  docs: filesystems: convert ocfs2-online-filecheck.txt to ReST
  docs: filesystems: convert ocfs2.txt to ReST
  docs: filesystems: convert omfs.txt to ReST
  docs: filesystems: convert orangefs.txt to ReST
  docs: filesystems: convert proc.txt to ReST
  docs: filesystems: convert qnx6.txt to ReST
  docs: filesystems: convert ramfs-rootfs-initramfs.txt to ReST
  docs: filesystems: convert relay.txt to ReST
  docs: filesystems: convert romfs.txt to ReST
  docs: filesystems: convert squashfs.txt to ReST
  docs: filesystems: convert sysfs.txt to ReST
  docs: filesystems: convert sysv-fs.txt to ReST
  docs: filesystems: convert tmpfs.txt to ReST
  docs: filesystems: convert ubifs-authentication.rst.txt to ReST
  docs: filesystems: convert ubifs.txt to ReST
  docs: filesystems: convert udf.txt to ReST
  docs: filesystems: convert zonefs.txt to ReST

 Documentation/filesystems/{9p.txt => 9p.rst}  |  114 +-
 .../filesystems/{adfs.txt => adfs.rst}        |   29 +-
 .../filesystems/{affs.txt => affs.rst}        |   62 +-
 .../filesystems/{afs.txt => afs.rst}          |   73 +-
 ...t-control.txt => autofs-mount-control.rst} |  102 +-
 .../filesystems/{befs.txt => befs.rst}        |   59 +-
 .../filesystems/{bfs.txt => bfs.rst}          |   37 +-
 .../filesystems/{btrfs.txt => btrfs.rst}      |    3 +
 .../filesystems/{ceph.txt => ceph.rst}        |   26 +-
 .../filesystems/{cramfs.txt => cramfs.rst}    |   19 +-
 .../filesystems/{debugfs.txt => debugfs.rst}  |   54 +-
 .../filesystems/{dlmfs.txt => dlmfs.rst}      |   28 +-
 .../{ecryptfs.txt => ecryptfs.rst}            |   44 +-
 .../{efivarfs.txt => efivarfs.rst}            |    5 +-
 .../filesystems/{erofs.txt => erofs.rst}      |  175 +-
 .../filesystems/{ext2.txt => ext2.rst}        |   41 +-
 .../filesystems/{ext3.txt => ext3.rst}        |    2 +
 .../filesystems/{f2fs.txt => f2fs.rst}        |  252 +--
 .../{gfs2-uevents.txt => gfs2-uevents.rst}    |   20 +-
 .../filesystems/{gfs2.txt => gfs2.rst}        |   20 +-
 .../filesystems/{hfs.txt => hfs.rst}          |   23 +-
 .../filesystems/{hfsplus.txt => hfsplus.rst}  |    2 +
 .../filesystems/{hpfs.txt => hpfs.rst}        |  239 ++-
 Documentation/filesystems/index.rst           |   46 +-
 .../filesystems/{inotify.txt => inotify.rst}  |   33 +-
 Documentation/filesystems/isofs.rst           |   64 +
 Documentation/filesystems/isofs.txt           |   48 -
 .../filesystems/{nilfs2.txt => nilfs2.rst}    |   40 +-
 .../filesystems/{ntfs.txt => ntfs.rst}        |  143 +-
 ...lecheck.txt => ocfs2-online-filecheck.rst} |   45 +-
 .../filesystems/{ocfs2.txt => ocfs2.rst}      |   31 +-
 Documentation/filesystems/omfs.rst            |  112 ++
 Documentation/filesystems/omfs.txt            |  106 --
 .../{orangefs.txt => orangefs.rst}            |  187 +-
 .../filesystems/{proc.txt => proc.rst}        | 1498 +++++++++--------
 .../filesystems/{qnx6.txt => qnx6.rst}        |   22 +
 ...itramfs.txt => ramfs-rootfs-initramfs.rst} |   54 +-
 .../filesystems/{relay.txt => relay.rst}      |  129 +-
 .../filesystems/{romfs.txt => romfs.rst}      |   42 +-
 .../{squashfs.txt => squashfs.rst}            |   60 +-
 .../filesystems/{sysfs.txt => sysfs.rst}      |  324 ++--
 .../filesystems/{sysv-fs.txt => sysv-fs.rst}  |  155 +-
 .../filesystems/{tmpfs.txt => tmpfs.rst}      |   44 +-
 .../filesystems/ubifs-authentication.rst      |   10 +-
 .../filesystems/{ubifs.txt => ubifs.rst}      |   25 +-
 .../filesystems/{udf.txt => udf.rst}          |   21 +-
 .../filesystems/{zonefs.txt => zonefs.rst}    |  106 +-
 47 files changed, 2739 insertions(+), 2035 deletions(-)
 rename Documentation/filesystems/{9p.txt => 9p.rst} (63%)
 rename Documentation/filesystems/{adfs.txt => adfs.rst} (85%)
 rename Documentation/filesystems/{affs.txt => affs.rst} (86%)
 rename Documentation/filesystems/{afs.txt => afs.rst} (90%)
 rename Documentation/filesystems/{autofs-mount-control.txt => autofs-mount-control.rst} (89%)
 rename Documentation/filesystems/{befs.txt => befs.rst} (83%)
 rename Documentation/filesystems/{bfs.txt => bfs.rst} (71%)
 rename Documentation/filesystems/{btrfs.txt => btrfs.rst} (96%)
 rename Documentation/filesystems/{ceph.txt => ceph.rst} (91%)
 rename Documentation/filesystems/{cramfs.txt => cramfs.rst} (88%)
 rename Documentation/filesystems/{debugfs.txt => debugfs.rst} (91%)
 rename Documentation/filesystems/{dlmfs.txt => dlmfs.rst} (86%)
 rename Documentation/filesystems/{ecryptfs.txt => ecryptfs.rst} (70%)
 rename Documentation/filesystems/{efivarfs.txt => efivarfs.rst} (85%)
 rename Documentation/filesystems/{erofs.txt => erofs.rst} (54%)
 rename Documentation/filesystems/{ext2.txt => ext2.rst} (91%)
 rename Documentation/filesystems/{ext3.txt => ext3.rst} (88%)
 rename Documentation/filesystems/{f2fs.txt => f2fs.rst} (84%)
 rename Documentation/filesystems/{gfs2-uevents.txt => gfs2-uevents.rst} (94%)
 rename Documentation/filesystems/{gfs2.txt => gfs2.rst} (76%)
 rename Documentation/filesystems/{hfs.txt => hfs.rst} (80%)
 rename Documentation/filesystems/{hfsplus.txt => hfsplus.rst} (95%)
 rename Documentation/filesystems/{hpfs.txt => hpfs.rst} (66%)
 rename Documentation/filesystems/{inotify.txt => inotify.rst} (83%)
 create mode 100644 Documentation/filesystems/isofs.rst
 delete mode 100644 Documentation/filesystems/isofs.txt
 rename Documentation/filesystems/{nilfs2.txt => nilfs2.rst} (89%)
 rename Documentation/filesystems/{ntfs.txt => ntfs.rst} (85%)
 rename Documentation/filesystems/{ocfs2-online-filecheck.txt => ocfs2-online-filecheck.rst} (77%)
 rename Documentation/filesystems/{ocfs2.txt => ocfs2.rst} (88%)
 create mode 100644 Documentation/filesystems/omfs.rst
 delete mode 100644 Documentation/filesystems/omfs.txt
 rename Documentation/filesystems/{orangefs.txt => orangefs.rst} (83%)
 rename Documentation/filesystems/{proc.txt => proc.rst} (65%)
 rename Documentation/filesystems/{qnx6.txt => qnx6.rst} (98%)
 rename Documentation/filesystems/{ramfs-rootfs-initramfs.txt => ramfs-rootfs-initramfs.rst} (91%)
 rename Documentation/filesystems/{relay.txt => relay.rst} (91%)
 rename Documentation/filesystems/{romfs.txt => romfs.rst} (86%)
 rename Documentation/filesystems/{squashfs.txt => squashfs.rst} (91%)
 rename Documentation/filesystems/{sysfs.txt => sysfs.rst} (56%)
 rename Documentation/filesystems/{sysv-fs.txt => sysv-fs.rst} (73%)
 rename Documentation/filesystems/{tmpfs.txt => tmpfs.rst} (86%)
 rename Documentation/filesystems/{ubifs.txt => ubifs.rst} (91%)
 rename Documentation/filesystems/{udf.txt => udf.rst} (83%)
 rename Documentation/filesystems/{zonefs.txt => zonefs.rst} (90%)

-- 
2.24.1



^ permalink raw reply	[flat|nested] 7+ messages in thread

* [PATCH 15/44] docs: filesystems: convert erofs.txt to ReST
  2020-02-17 16:11 [PATCH 00/44] Manually convert filesystem FS documents to ReST Mauro Carvalho Chehab
@ 2020-02-17 16:12 ` Mauro Carvalho Chehab
  2020-02-18  4:01 ` [PATCH 00/44] Manually convert filesystem FS documents " Matthew Wilcox
  2020-03-02 21:13 ` Jonathan Corbet
  2 siblings, 0 replies; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-02-17 16:12 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Jonathan Corbet, Mauro Carvalho Chehab, linux-fsdevel, Gao Xiang,
	linux-erofs

- Add a SPDX header;
- Add a document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add lists markups;
- Add it to filesystems/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../filesystems/{erofs.txt => erofs.rst}      | 175 ++++++++++--------
 Documentation/filesystems/index.rst           |   1 +
 2 files changed, 103 insertions(+), 73 deletions(-)
 rename Documentation/filesystems/{erofs.txt => erofs.rst} (54%)

diff --git a/Documentation/filesystems/erofs.txt b/Documentation/filesystems/erofs.rst
similarity index 54%
rename from Documentation/filesystems/erofs.txt
rename to Documentation/filesystems/erofs.rst
index db6d39c3ae71..bf145171c2bf 100644
--- a/Documentation/filesystems/erofs.txt
+++ b/Documentation/filesystems/erofs.rst
@@ -1,3 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======================================
+Enhanced Read-Only File System - EROFS
+======================================
+
 Overview
 ========
 
@@ -6,6 +12,7 @@ from other read-only file systems, it aims to be designed for flexibility,
 scalability, but be kept simple and high performance.
 
 It is designed as a better filesystem solution for the following scenarios:
+
  - read-only storage media or
 
  - part of a fully trusted read-only solution, which means it needs to be
@@ -17,6 +24,7 @@ It is designed as a better filesystem solution for the following scenarios:
    for those embedded devices with limited memory (ex, smartphone);
 
 Here is the main features of EROFS:
+
  - Little endian on-disk design;
 
  - Currently 4KB block size (nobh) and therefore maximum 16TB address space;
@@ -24,13 +32,17 @@ Here is the main features of EROFS:
  - Metadata & data could be mixed by design;
 
  - 2 inode versions for different requirements:
+
+   =====================  ============  =====================================
                           compact (v1)  extended (v2)
-   Inode metadata size:   32 bytes      64 bytes
-   Max file size:         4 GB          16 EB (also limited by max. vol size)
-   Max uids/gids:         65536         4294967296
-   File change time:      no            yes (64 + 32-bit timestamp)
-   Max hardlinks:         65536         4294967296
-   Metadata reserved:     4 bytes       14 bytes
+   =====================  ============  =====================================
+   Inode metadata size    32 bytes      64 bytes
+   Max file size          4 GB          16 EB (also limited by max. vol size)
+   Max uids/gids          65536         4294967296
+   File change time       no            yes (64 + 32-bit timestamp)
+   Max hardlinks          65536         4294967296
+   Metadata reserved      4 bytes       14 bytes
+   =====================  ============  =====================================
 
  - Support extended attributes (xattrs) as an option;
 
@@ -43,29 +55,36 @@ Here is the main features of EROFS:
 
 The following git tree provides the file system user-space tools under
 development (ex, formatting tool mkfs.erofs):
->> git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git
+
+- git://git.kernel.org/pub/scm/linux/kernel/git/xiang/erofs-utils.git
 
 Bugs and patches are welcome, please kindly help us and send to the following
 linux-erofs mailing list:
->> linux-erofs mailing list   <linux-erofs@lists.ozlabs.org>
+
+- linux-erofs mailing list   <linux-erofs@lists.ozlabs.org>
 
 Mount options
 =============
 
+===================    =========================================================
 (no)user_xattr         Setup Extended User Attributes. Note: xattr is enabled
                        by default if CONFIG_EROFS_FS_XATTR is selected.
 (no)acl                Setup POSIX Access Control List. Note: acl is enabled
                        by default if CONFIG_EROFS_FS_POSIX_ACL is selected.
 cache_strategy=%s      Select a strategy for cached decompression from now on:
-                         disabled: In-place I/O decompression only;
-                        readahead: Cache the last incomplete compressed physical
+
+		       ==========  =============================================
+                         disabled  In-place I/O decompression only;
+                        readahead  Cache the last incomplete compressed physical
                                    cluster for further reading. It still does
                                    in-place I/O decompression for the rest
                                    compressed physical clusters;
-                       readaround: Cache the both ends of incomplete compressed
+                       readaround  Cache the both ends of incomplete compressed
                                    physical clusters for further reading.
                                    It still does in-place I/O decompression
                                    for the rest compressed physical clusters.
+		       ==========  =============================================
+===================    =========================================================
 
 On-disk details
 ===============
@@ -73,7 +92,7 @@ On-disk details
 Summary
 -------
 Different from other read-only file systems, an EROFS volume is designed
-to be as simple as possible:
+to be as simple as possible::
 
                                 |-> aligned with the block size
    ____________________________________________________________
@@ -83,41 +102,45 @@ to be as simple as possible:
 
 All data areas should be aligned with the block size, but metadata areas
 may not. All metadatas can be now observed in two different spaces (views):
+
  1. Inode metadata space
+
     Each valid inode should be aligned with an inode slot, which is a fixed
     value (32 bytes) and designed to be kept in line with compact inode size.
 
     Each inode can be directly found with the following formula:
          inode offset = meta_blkaddr * block_size + 32 * nid
 
-                                |-> aligned with 8B
-                                           |-> followed closely
-    + meta_blkaddr blocks                                      |-> another slot
-     _____________________________________________________________________
-    |  ...   | inode |  xattrs  | extents  | data inline | ... | inode ...
-    |________|_______|(optional)|(optional)|__(optional)_|_____|__________
-             |-> aligned with the inode slot size
-                  .                   .
-                .                         .
-              .                              .
-            .                                    .
-          .                                         .
-        .                                              .
-      .____________________________________________________|-> aligned with 4B
-      | xattr_ibody_header | shared xattrs | inline xattrs |
-      |____________________|_______________|_______________|
-      |->    12 bytes    <-|->x * 4 bytes<-|               .
-                          .                .                 .
-                    .                      .                   .
-               .                           .                     .
-           ._______________________________.______________________.
-           | id | id | id | id |  ... | id | ent | ... | ent| ... |
-           |____|____|____|____|______|____|_____|_____|____|_____|
-                                           |-> aligned with 4B
-                                                       |-> aligned with 4B
+    ::
+
+				    |-> aligned with 8B
+					    |-> followed closely
+	+ meta_blkaddr blocks                                      |-> another slot
+	_____________________________________________________________________
+	|  ...   | inode |  xattrs  | extents  | data inline | ... | inode ...
+	|________|_______|(optional)|(optional)|__(optional)_|_____|__________
+		|-> aligned with the inode slot size
+		    .                   .
+		    .                         .
+		.                              .
+		.                                    .
+	    .                                         .
+	    .                                              .
+	.____________________________________________________|-> aligned with 4B
+	| xattr_ibody_header | shared xattrs | inline xattrs |
+	|____________________|_______________|_______________|
+	|->    12 bytes    <-|->x * 4 bytes<-|               .
+			    .                .                 .
+			.                      .                   .
+		.                           .                     .
+	    ._______________________________.______________________.
+	    | id | id | id | id |  ... | id | ent | ... | ent| ... |
+	    |____|____|____|____|______|____|_____|_____|____|_____|
+					    |-> aligned with 4B
+							|-> aligned with 4B
 
     Inode could be 32 or 64 bytes, which can be distinguished from a common
-    field which all inode versions have -- i_format:
+    field which all inode versions have -- i_format::
 
         __________________               __________________
        |     i_format     |             |     i_format     |
@@ -132,16 +155,19 @@ may not. All metadatas can be now observed in two different spaces (views):
     proper alignment, and they could be optional for different data mappings.
     _currently_ total 4 valid data mappings are supported:
 
+    ==  ====================================================================
      0  flat file data without data inline (no extent);
      1  fixed-sized output data compression (with non-compacted indexes);
      2  flat file data with tail packing data inline (no extent);
      3  fixed-sized output data compression (with compacted indexes, v5.3+).
+    ==  ====================================================================
 
     The size of the optional xattrs is indicated by i_xattr_count in inode
     header. Large xattrs or xattrs shared by many different files can be
     stored in shared xattrs metadata rather than inlined right after inode.
 
  2. Shared xattrs metadata space
+
     Shared xattrs space is similar to the above inode space, started with
     a specific block indicated by xattr_blkaddr, organized one by one with
     proper align.
@@ -149,11 +175,13 @@ may not. All metadatas can be now observed in two different spaces (views):
     Each share xattr can also be directly found by the following formula:
          xattr offset = xattr_blkaddr * block_size + 4 * xattr_id
 
-                           |-> aligned by  4 bytes
-    + xattr_blkaddr blocks                     |-> aligned with 4 bytes
-     _________________________________________________________________________
-    |  ...   | xattr_entry |  xattr data | ... |  xattr_entry | xattr data  ...
-    |________|_____________|_____________|_____|______________|_______________
+    ::
+
+			    |-> aligned by  4 bytes
+	+ xattr_blkaddr blocks                     |-> aligned with 4 bytes
+	_________________________________________________________________________
+	|  ...   | xattr_entry |  xattr data | ... |  xattr_entry | xattr data  ...
+	|________|_____________|_____________|_____|______________|_______________
 
 Directories
 -----------
@@ -163,19 +191,21 @@ random file lookup, and all directory entries are _strictly_ recorded in
 alphabetical order in order to support improved prefix binary search
 algorithm (could refer to the related source code).
 
-                 ___________________________
-                /                           |
-               /              ______________|________________
-              /              /              | nameoff1       | nameoffN-1
- ____________.______________._______________v________________v__________
-| dirent | dirent | ... | dirent | filename | filename | ... | filename |
-|___.0___|____1___|_____|___N-1__|____0_____|____1_____|_____|___N-1____|
-     \                           ^
-      \                          |                           * could have
-       \                         |                             trailing '\0'
-        \________________________| nameoff0
+::
 
-                             Directory block
+		    ___________________________
+		    /                           |
+		/              ______________|________________
+		/              /              | nameoff1       | nameoffN-1
+    ____________.______________._______________v________________v__________
+    | dirent | dirent | ... | dirent | filename | filename | ... | filename |
+    |___.0___|____1___|_____|___N-1__|____0_____|____1_____|_____|___N-1____|
+	\                           ^
+	\                          |                           * could have
+	\                         |                             trailing '\0'
+	    \________________________| nameoff0
+
+				Directory block
 
 Note that apart from the offset of the first filename, nameoff0 also indicates
 the total number of directory entries in this block since it is no need to
@@ -184,28 +214,27 @@ introduce another on-disk field at all.
 Compression
 -----------
 Currently, EROFS supports 4KB fixed-sized output transparent file compression,
-as illustrated below:
+as illustrated below::
 
-         |---- Variant-Length Extent ----|-------- VLE --------|----- VLE -----
-         clusterofs                      clusterofs            clusterofs
-         |                               |                     |   logical data
-_________v_______________________________v_____________________v_______________
-... |    .        |             |        .    |             |  .          | ...
-____|____.________|_____________|________.____|_____________|__.__________|____
-    |-> cluster <-|-> cluster <-|-> cluster <-|-> cluster <-|-> cluster <-|
-         size          size          size          size          size
-          .                             .                .                   .
-           .                       .               .                  .
-            .                  .              .                .
-      _______._____________._____________._____________._____________________
-         ... |             |             |             | ... physical data
-      _______|_____________|_____________|_____________|_____________________
-             |-> cluster <-|-> cluster <-|-> cluster <-|
-                  size          size          size
+	    |---- Variant-Length Extent ----|-------- VLE --------|----- VLE -----
+	    clusterofs                      clusterofs            clusterofs
+	    |                               |                     |   logical data
+    _________v_______________________________v_____________________v_______________
+    ... |    .        |             |        .    |             |  .          | ...
+    ____|____.________|_____________|________.____|_____________|__.__________|____
+	|-> cluster <-|-> cluster <-|-> cluster <-|-> cluster <-|-> cluster <-|
+	    size          size          size          size          size
+	    .                             .                .                   .
+	    .                       .               .                  .
+		.                  .              .                .
+	_______._____________._____________._____________._____________________
+	    ... |             |             |             | ... physical data
+	_______|_____________|_____________|_____________|_____________________
+		|-> cluster <-|-> cluster <-|-> cluster <-|
+		    size          size          size
 
 Currently each on-disk physical cluster can contain 4KB (un)compressed data
 at most. For each logical cluster, there is a corresponding on-disk index to
 describe its cluster type, physical cluster address, etc.
 
 See "struct z_erofs_vle_decompressed_index" in erofs_fs.h for more details.
-
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 4230f49d2732..03a493b27920 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -61,6 +61,7 @@ Documentation for filesystem implementations.
    dlmfs
    ecryptfs
    efivarfs
+   erofs
    fuse
    overlayfs
    virtiofs
-- 
2.24.1


^ permalink raw reply related	[flat|nested] 7+ messages in thread

* Re: [PATCH 00/44] Manually convert filesystem FS documents to ReST
  2020-02-17 16:11 [PATCH 00/44] Manually convert filesystem FS documents to ReST Mauro Carvalho Chehab
  2020-02-17 16:12 ` [PATCH 15/44] docs: filesystems: convert erofs.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
  2 siblings, 1 reply; 7+ messages in thread
From: Matthew Wilcox @ 2020-02-18  4:01 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Latchesar Ionkov, Martin Brandenburg, Jan Kara,
	Linux Doc Mailing List, Dominique Martinet, Amir Goldstein,
	Bob Copeland, David Howells, Chris Mason, linux-mtd,
	Ilya Dryomov, linux-afs, Mike Marshall, Naohiro Aota,
	Christoph Hellwig, linux-nilfs, Andreas Gruenbacher, Sage Weil,
	Jonathan Corbet, Richard Weinberger, Tyler Hicks, cluster-devel,
	v9fs-developer, Gao Xiang, linux-ext4, Salah Triki,
	Alexey Dobriyan, devel, Eric Van Hensbergen, ecryptfs,
	Josef Bacik, Bob Peterson, Tigran A. Aivazian, David Sterba,
	Jaegeuk Kim, ceph-devel, Ryusuke Konishi, Anton Altaparmakov,
	Damien Le Moal, Luis de Bethencourt, Nicolas Pitre,
	linux-ntfs-dev, Jeff Layton, linux-f2fs-devel, ocfs2-devel,
	Jan Kara, linux-fsdevel, Phillip Lougher, Johannes Thumshirn,
	linux-erofs, linux-karma-devel, linux-btrfs

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] 7+ messages in thread

* Re: [PATCH 00/44] Manually convert filesystem FS documents to ReST
  2020-02-18  4:01 ` [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; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-02-18 10:04 UTC (permalink / raw)
  To: Matthew Wilcox
  Cc: Latchesar Ionkov, Martin Brandenburg, Jan Kara,
	Linux Doc Mailing List, Dominique Martinet, Amir Goldstein,
	Bob Copeland, David Howells, Chris Mason, linux-mtd,
	Ilya Dryomov, linux-afs, Mike Marshall, Naohiro Aota,
	Christoph Hellwig, linux-nilfs, Andreas Gruenbacher, Sage Weil,
	Jonathan Corbet, Richard Weinberger, Tyler Hicks, cluster-devel,
	v9fs-developer, Gao Xiang, linux-ext4, Salah Triki,
	Alexey Dobriyan, devel, Eric Van Hensbergen, ecryptfs,
	Josef Bacik, Bob Peterson, Tigran A. Aivazian, David Sterba,
	Jaegeuk Kim, ceph-devel, Ryusuke Konishi, Anton Altaparmakov,
	Damien Le Moal, Luis de Bethencourt, Nicolas Pitre,
	linux-ntfs-dev, Jeff Layton, linux-f2fs-devel, ocfs2-devel,
	Jan Kara, linux-fsdevel, Phillip Lougher, Johannes Thumshirn,
	linux-erofs, linux-karma-devel, linux-btrfs

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] 7+ messages in thread

* Re: [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; 7+ messages in thread
From: Jonathan Corbet @ 2020-02-19  9:32 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Latchesar Ionkov, Martin Brandenburg, Jan Kara,
	Linux Doc Mailing List, Dominique Martinet, Amir Goldstein,
	Bob Copeland, David Howells, Chris Mason, linux-mtd,
	Ilya Dryomov, linux-afs, Mike Marshall, Naohiro Aota,
	Christoph Hellwig, linux-nilfs, Andreas Gruenbacher, Sage Weil,
	Richard Weinberger, Matthew Wilcox, Tyler Hicks, cluster-devel,
	v9fs-developer, Gao Xiang, linux-ext4, Salah Triki,
	Alexey Dobriyan, devel, Eric Van Hensbergen, ecryptfs,
	Josef Bacik, Bob Peterson, Tigran A. Aivazian, David Sterba,
	Jaegeuk Kim, ceph-devel, Ryusuke Konishi, Anton Altaparmakov,
	Damien Le Moal, Luis de Bethencourt, Nicolas Pitre,
	linux-ntfs-dev, Jeff Layton, linux-f2fs-devel, ocfs2-devel,
	Jan Kara, linux-fsdevel, Phillip Lougher, Johannes Thumshirn,
	linux-erofs, linux-karma-devel, linux-btrfs

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] 7+ messages in thread

* Re: [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; 7+ messages in thread
From: Mauro Carvalho Chehab @ 2020-02-19 15:11 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: Latchesar Ionkov, Martin Brandenburg, Jan Kara,
	Linux Doc Mailing List, Dominique Martinet, Amir Goldstein,
	Bob Copeland, David Howells, Chris Mason, linux-mtd,
	Ilya Dryomov, linux-afs, Mike Marshall, Naohiro Aota,
	Christoph Hellwig, linux-nilfs, Andreas Gruenbacher, Sage Weil,
	Richard Weinberger, Matthew Wilcox, Tyler Hicks, cluster-devel,
	v9fs-developer, Gao Xiang, linux-ext4, Salah Triki,
	Alexey Dobriyan, devel, Eric Van Hensbergen, ecryptfs,
	Josef Bacik, Bob Peterson, Tigran A. Aivazian, David Sterba,
	Jaegeuk Kim, ceph-devel, Ryusuke Konishi, Anton Altaparmakov,
	Damien Le Moal, Luis de Bethencourt, Nicolas Pitre,
	linux-ntfs-dev, Jeff Layton, linux-f2fs-devel, ocfs2-devel,
	Jan Kara, linux-fsdevel, Phillip Lougher, Johannes Thumshirn,
	linux-erofs, linux-karma-devel, linux-btrfs

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] 7+ messages in thread

* Re: [PATCH 00/44] Manually convert filesystem FS documents to ReST
  2020-02-17 16:11 [PATCH 00/44] Manually convert filesystem FS documents to ReST Mauro Carvalho Chehab
  2020-02-17 16:12 ` [PATCH 15/44] docs: filesystems: convert erofs.txt " Mauro Carvalho Chehab
  2020-02-18  4:01 ` [PATCH 00/44] Manually convert filesystem FS documents " Matthew Wilcox
@ 2020-03-02 21:13 ` Jonathan Corbet
  2 siblings, 0 replies; 7+ messages in thread
From: Jonathan Corbet @ 2020-03-02 21:13 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Latchesar Ionkov, Martin Brandenburg, Jan Kara,
	Linux Doc Mailing List, Dominique Martinet, Amir Goldstein,
	Bob Copeland, David Howells, Joseph Qi, linux-mtd, Tyler Hicks,
	linux-afs, Mike Marshall, Naohiro Aota, Christoph Hellwig,
	linux-nilfs, Andreas Gruenbacher, Sage Weil, Richard Weinberger,
	Mark Fasheh, Chris Mason, Ryusuke Konishi, cluster-devel,
	v9fs-developer, Gao Xiang, linux-ext4, Salah Triki,
	Alexey Dobriyan, devel, ecryptfs, Eric Van Hensbergen,
	Josef Bacik, linux-fsdevel, Joel Becker, Tigran A. Aivazian,
	David Sterba, Jaegeuk Kim, ceph-devel, Ilya Dryomov,
	Anton Altaparmakov, Damien Le Moal, Luis de Bethencourt,
	Nicolas Pitre, linux-ntfs-dev, Jeff Layton, linux-f2fs-devel,
	linux-btrfs, Jan Kara, Bob Peterson, Phillip Lougher,
	Johannes Thumshirn, linux-erofs, linux-karma-devel, ocfs2-devel

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] 7+ messages in thread

end of thread, other threads:[~2020-03-02 21:14 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-02-17 16:11 [PATCH 00/44] Manually convert filesystem FS documents to ReST Mauro Carvalho Chehab
2020-02-17 16:12 ` [PATCH 15/44] docs: filesystems: convert erofs.txt " Mauro Carvalho Chehab
2020-02-18  4:01 ` [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
2020-02-19 15:11       ` Mauro Carvalho Chehab
2020-03-02 21:13 ` Jonathan Corbet

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).