btrfs-progs: docs: typo fixups and formatting updates

Signed-off-by: David Sterba <[email protected]>

Documentation/Deduplication.rst

@@ -64,7 +64,7 @@ a source file, destination file and the range. The blocks from both files are
 compared for exact match before merging to the same range (i.e. there's no
 hash based comparison). Pages representing the extents in memory are locked
 prior to deduplication and prevent concurrent modification by buffered writes
-or mmaped writes. Blocks are compared byte by byte and not using any hash-based
+or mmapped writes. Blocks are compared byte by byte and not using any hash-based
 approach, i.e. the existing checksums are not used.
 
 Limitations, compatibility

Documentation/Experimental.rst

@@ -36,5 +36,5 @@ for larger code blocks.
 
 Each feature should be tracked in an issue with label **experimental** (list of
 active issues https://github.com/kdave/btrfs-progs/labels/experimental), with a
-description and a todo list items. Individual tasks can be tracked in other
+description and a TODO list items. Individual tasks can be tracked in other
 issues if needed.

Documentation/Feature-by-version.rst

@@ -19,7 +19,7 @@ features see [[Status]] page.
         Automatic repair of broken data from a good copy
 
 3.2 - root backups
-        Save a few previous versions of the most imporant tree roots at commit time, used by *-o recovery*
+        Save a few previous versions of the most important tree roots at commit time, used by *-o recovery*
 
 3.3 - integrity checker
         Optional infrastructure to verify integrity of written metadata blocks
@@ -57,14 +57,14 @@ features see [[Status]] page.
         .. note::
            Default since btrfs-progs 3.12
 
-3.7 - hole puching
+3.7 - hole punching
         Implement the FALLOC_FL_PUNCH_HOLE mode of *fallocate*
 
 3.8 - device replace
         Efficient replacement of existing device (add/remove in one go)
 
 3.9 - raid 5/6 *(incomplete)*
-        Basic support for RAD5/6 profiles, no crash resiliency, replace and scrub support
+        Basic support for RAID5/6 profiles, no crash resiliency, replace and scrub support
 
 3.9 - snapshot-aware defrag
         Defrag does not break links between shared extents (snapshots, reflinked files)
@@ -88,10 +88,10 @@ features see [[Status]] page.
 3.10 - qgroup rescan
         Sync qgroups with existing filesystem data
 
-3.12 - uuid tree
+3.12 - UUID tree
         A map of subvolume/UUID that vastly speeds up send/receive
 
-3.12 - out-of-bound dedup
+3.12 - out-of-bound deduplication
         Support for deduplicating extents on a given set of files.
 
 3.14 - no-holes
@@ -106,10 +106,10 @@ features see [[Status]] page.
 3.16 - search ioctl v2
         The extended SEARCH_TREE ioctl able to get more than a 4k data
 
-3.18 - auto blockgroup reclaim
-        Automatically remove blockgroups (aka. chunks) that become completely empty.
+3.18 - auto block group reclaim
+        Automatically remove block groups (aka. chunks) that become completely empty.
 
-3.19 - raid56: scrub, replace
+3.19 - RAID56: scrub, replace
         Scrub and device replace works on RAID56 filesystems.
 
 4.x
@@ -145,7 +145,7 @@ features see [[Status]] page.
            big-endian machines, x86* is ok
 
 4.5 - balance filter updates
-        Conversion to data/DUP profile possible through balance filters -- on single-device filesytem.
+        Conversion to data/DUP profile possible through balance filters -- on single-device filesystem.
 
         .. note::
            mkfs.btrfs allows creating DUP on single device in the non-mixed mode since 4.4
@@ -172,7 +172,7 @@ features see [[Status]] page.
         .. note::
            mkfs.btrfs allows creating DUP on multiple devices since 4.5.1
 
-4.12 - raid56: auto repair
+4.12 - RAID56: auto repair
         Scrub will attempt auto-repair (similar to raid1/raid10)
 
 4.13 - statx
@@ -189,7 +189,7 @@ features see [[Status]] page.
 
 4.14 - improved degraded mount
         Allow degraded mount based on the chunk constraints, not device number
-        constraints. Eg. when one device is missing but the remaining one holds
+        constraints. E.g. when one device is missing but the remaining one holds
         all *single* chunks.
 
 4.14 - *deprecated user transaction ioctl*
@@ -211,14 +211,14 @@ features see [[Status]] page.
         Debugging functionality to verify extent references. New mount option
         <i>ref-verify</i>, must be built with CONFIG_BTRFS_FS_REF_VERIFY.
 
-4.15 - zlib level
-        Allow to set the zlib compression level via mount option, e.g. like
-        *compress=zlib:9*. The levels match the default zlib compression
+4.15 - ZLIB level
+        Allow to set the ZLIB compression level via mount option, e.g. like
+        *compress=zlib:9*. The levels match the default ZLIB compression
         levels. The default is 3.
 
 4.15 - v2 of LOGICAL_INO ioctl
         An enhanced version of ioctl that can translate logical extent offset
-        to inode numbers, "who owns this block". For certain usecases the V1
+        to inode numbers, "who owns this block". For certain use cases the V1
         performs bad and this is addressed by V2.
         [https://git.kernel.org/linus/d24a67b2d997c860a42516076f3315c2ad2d2884
         Read more.]
@@ -267,7 +267,7 @@ features see [[Status]] page.
         INO_LOOKUP ioctl.
 
 4.19 - defrag ro/rw
-        Allow to run defrag on files that are normally accesible for
+        Allow to run defrag on files that are normally accessible for
         read-write, but are currently opened in read-only mode.
 
 5.x
@@ -288,9 +288,9 @@ features see [[Status]] page.
         Unregister devices previously added by the scan ioctl, same effect as
         if the kernel module is reloaded.
 
-5.1 - zstd level
-        Allow to set the zstd compression level via mount option, e.g. like
-        *compress=zstd:9*. The levels match the default zstd compression
+5.1 - ZSTD level
+        Allow to set the ZSTD compression level via mount option, e.g. like
+        *compress=zstd:9*. The levels match the default ZSTD compression
         levels. The default is 3, maximum is 15.
 
 5.2 - pre-write checks
@@ -315,7 +315,7 @@ features see [[Status]] page.
 
 5.7 - faster balance cancel
         More cancellation points in balance that will shorten the time to stop
-        processing once <tt>btrfs balance cancel</tt> is called.
+        processing once ``btrfs balance cancel`` is called.
 
 5.7 - *removed flag BTRFS_SUBVOL_CREATE_ASYNC*
         Remove support of flag BTRFS_SUBVOL_CREATE_ASYNC from subvolume creation ioctl.
@@ -335,7 +335,7 @@ features see [[Status]] page.
 
 5.10 - exclusive ops in sysfs
         Export which filesystem exclusive operation is running (balance,
-        resize, device add/delete/relpace, ...)
+        resize, device add/delete/replace, ...)
 
 5.11 - remove *inode_cache*
         Remove inode number caching feature (mount -o inode_cache)
@@ -375,7 +375,7 @@ features see [[Status]] page.
         files. https://www.kernel.org/doc/html/latest/filesystems/fsverity.html
 
 5.15 - idmapped mount
-        Support mount with uid/gid mapped according to another namespace.
+        Support mount with UID/GID mapped according to another namespace.
         https://lwn.net/Articles/837566/
 
 5.16 - ZNS in zoned
@@ -393,7 +393,7 @@ features see [[Status]] page.
            Since kernel 5.17.7 and btrfs-progs 5.17.1
 
 5.17 - *no warning with flushoncommit*
-        Mounting with *-o flushoncommit* does not triggher the (harmless)
+        Mounting with *-o flushoncommit* does not trigger the (harmless)
         warning at each transaction commit
 
         .. note::
@@ -439,7 +439,7 @@ features see [[Status]] page.
         types (data, metadata, system).
 
 5.19 - automatically repair device number mismatch
-        Device information is storead in two places, the number in the super
+        Device information is stored in two places, the number in the super
         block and items in the device tree. When this is goes out of sync, e.g.
         by device removal short before unmount, the next mount could fail.
         The b-tree is an authoritative information an can be used to override
@@ -470,7 +470,7 @@ features see [[Status]] page.
 6.0 - send protocol v2
         Send protocol update that adds new commands and extends existing
         functionality to write large data chunks. Compressed (and encrypted)
-        extents can be optionally emitted and transfered as-is without the need
+        extents can be optionally emitted and transferred as-is without the need
         to recompress (or reencrypt) on the receiving side.
 
 6.0 - sysfs exports commit stats
@@ -506,7 +506,7 @@ features see [[Status]] page.
         An incompatible change that has to be enabled at mkfs time. Add a new
         b-tree item that stores information about block groups in a compact way
         that significantly improves mount time that's usually long due to
-        fragmentation and scatterd b-tree items tracking the individual block
+        fragmentation and scattered b-tree items tracking the individual block
         groups. Requires and also enables the free-space-tree and no-holes
         features.
 
@@ -518,7 +518,7 @@ features see [[Status]] page.
         The overall status of qgroups are exported in
         /sys/sys/fs/btrfs/FSID/qgroups/ .
 
-6.1 - check that subperblock is unchnaged at thaw time
+6.1 - check that subperblock is unchanged at thaw time
         Do full check of super block once a filesystem is thawed. This namely
         happens when system resumes from suspend or hibernation. Accidental
         change by other operating systems will be detected.

Documentation/Glossary.rst

@@ -83,7 +83,7 @@ copy-on-write
 	way. In COW filesystems, files tend to fragment as they are modified.
 	Copy-on-write is also used in the implementation of *snapshots* and
 	*reflink copies*. A copy-on-write filesystem is, in theory,
-	'always' consistent, provided the underlying hardware supports
+	*always* consistent, provided the underlying hardware supports
 	*barriers*.
 
 COW
@@ -142,8 +142,8 @@ fallocate
 	Command line tool in util-linux, and a syscall, that reserves space in
 	the filesystem for a file, without actually writing any file data to
 	the filesystem. First data write will turn the preallocated extents
-	into regular ones. See <code>man 1 fallocate</code> and <code>man 2
-	fallocate</code> for more details.
+        into regular ones. See *fallocate(1)* and *fallocate(2)* manual pages
+        for more details.
 
 filefrag
 	A tool to show the number of extents in a file, and hence the amount of
@@ -160,7 +160,7 @@ free space cache
 
 fsync
 	On Unix and Unix-like operating systems (of which Linux is the latter),
-	the ``lfsync()`` system call causes all buffered file
+	the ``fsync()`` system call causes all buffered file
 	descriptor related data changes to be flushed to the underlying block
 	device. When a file is modified on a modern operating system the
 	changes are generally not written to the disk immediately but rather
@@ -292,9 +292,8 @@ subvolume
 	a reference on the root of another subvolume. Each btrfs filesystem has
 	at least one subvolume, the *top-level subvolume*, which contains
 	everything else in the filesystem. Additional subvolumes can be created
-	and deleted with the *<code>btrfs</code>* tool. All subvolumes share
-	the same pool of free space in the filesystem. See also *default
-	subvolume*.
+        and deleted with the *btrfs<* tool. All subvolumes share the same pool
+        of free space in the filesystem. See also *default subvolume*.
 
 superblock
 	The *block* on the disk, at a fixed known location and of fixed size,

Documentation/Source-repositories.rst

@@ -72,10 +72,10 @@ patches to the mailing list instead. You can link to a branch in any git
 repository if the mails do not make it to the mailing list or for convenience.
 
 The development model of btrfs-progs shares a lot with the kernel model. The
-github way is different in some ways. We, the upstream community, expect that
-the patches meet some criteria (often lacking in github contributions):
+github.com way is different in some ways. We, the upstream community, expect that
+the patches meet some criteria (often lacking in github.com contributions):
 
-* proper **subject line**: eg. prefix with *btrfs-progs: subpart, ...* ,
+* proper **subject line**: e.g. prefix with *btrfs-progs: subpart, ...* ,
   descriptive yet not too long
 * proper **changelog**: the changelogs are often missing or lacking
   explanation *why* the change was made, or *how* is something broken,
@@ -84,7 +84,7 @@ the patches meet some criteria (often lacking in github contributions):
 * the **Signed-off-by** line: this document who authored the change, you can
   read more about the *The Developer's Certificate of Origin*
   `here (chapter 11) <https://www.kernel.org/doc/Documentation/SubmittingPatches>`_]
-* **one logical change** per patch: eg. not mixing bugfixes, cleanups,
+* **one logical change** per patch: e.g. not mixing bug fixes, cleanups,
   features etc., sometimes it's not clear and will be usually pointed out
   during reviews
 

Documentation/btrfs-check.rst

@@ -22,7 +22,7 @@ by the option *--readonly*.
 .. warning::
    Do not use *--repair* unless you are advised to do so by a developer
    or an experienced user, and then only after having accepted that no *fsck*
-   successfully repair all types of filesystem corruption. Eg. some other software
+   successfully repair all types of filesystem corruption. E.g. some other software
    or hardware bugs can fatally damage a volume.
 
 The structural integrity check verifies if internal filesystem objects or

Documentation/btrfs-man5.rst

@@ -19,7 +19,7 @@ tools.  Currently covers:
 #. control device
 #. filesystems with multiple block group profiles
 #. seeding device
-#. raid56 status and recommended practices
+#. RAID56 status and recommended practices
 #. storage model, hardware considerations
 
 
@@ -129,10 +129,10 @@ raid1c34
 
         extended RAID1 mode with copies on 3 or 4 devices respectively
 
-raid56
+RAID56
         (since: 3.9)
 
-        the filesystem contains or contained a raid56 profile of block groups
+        the filesystem contains or contained a RAID56 profile of block groups
 
 rmdir_subvol
         (since: 4.18)
@@ -332,7 +332,7 @@ group profiles *RAID1*.
 Having just one profile is desired as this also clearly defines the profile of
 newly allocated block groups, otherwise this depends on internal allocation
 policy. When there are multiple profiles present, the order of selection is
-RAID6, RAID5, RAID10, RAID1, RAID0 as long as the device number constraints are
+RAID56, RAID10, RAID1, RAID0 as long as the device number constraints are
 satisfied.
 
 Commands that print the warning were chosen so they're brought to user
@@ -385,7 +385,7 @@ Missing/incomplete support
 
 When RAID56 is on the same filesystem with different raid profiles, the space
 reporting is inaccurate, e.g. **df**, **btrfs filesystem df** or **btrfs filesystem
-usage**. When there's only a one profile per block group type (e.g. raid5 for data)
+usage**. When there's only a one profile per block group type (e.g. RAID5 for data)
 the reporting is accurate.
 
 When scrub is started on a RAID56 filesystem, it's started on all devices that

Documentation/btrfs-receive.rst

@@ -53,7 +53,7 @@ A subvolume is made read-only after the receiving process finishes successfully
 -m <ROOTMOUNT>
         the root mount point of the destination filesystem
 
-        By default the mountpoint is searched in */proc/self/mounts*.
+        By default the mount point is searched in */proc/self/mounts*.
         If */proc* is not accessible, e.g. in a chroot environment, use this option to
         tell us where this filesystem is mounted.
 

Documentation/btrfs-rescue.rst

@@ -51,12 +51,12 @@ fix-device-size <device>
                 WARNING: CPU: 3 PID: 439 at fs/btrfs/ctree.h:1559 btrfs_update_device+0x1c5/0x1d0 [btrfs]
 
 clear-uuid-tree <device>
-        Clear uuid tree, so that kernel can re-generate it at next read-write
+        Clear UUID tree, so that kernel can re-generate it at next read-write
         mount.
 
         Since kernel v4.16 there are more sanity check performed, and sometimes
-        non-critical trees like uuid tree can cause problems and reject the mount.
-        In such case, clearing uuid tree may make the filesystem to be mountable again
+        non-critical trees like UUID tree can cause problems and reject the mount.
+        In such case, clearing UUID tree may make the filesystem to be mountable again
         without much risk as it's built from other trees.
 
 super-recover [options] <device>

Documentation/btrfstune.rst

@@ -12,7 +12,7 @@ DESCRIPTION
 **btrfstune** can be used to enable, disable, or set various filesystem
 parameters. The filesystem must be unmounted.
 
-The common usecase is to enable features that were not enabled at mkfs time.
+The common use case is to enable features that were not enabled at mkfs time.
 Please make sure that you have kernel support for the features.  You can find a
 complete list of features and kernel version of their introduction at
 https://btrfs.wiki.kernel.org/index.php/Changelog#By_feature .  Also, the

Documentation/ch-checksumming.rst

@@ -1,5 +1,5 @@
 Data and metadata are checksummed by default, the checksum is calculated before
-write and verifed after reading the blocks from devices. The whole metadata
+write and verified after reading the blocks from devices. The whole metadata
 block has a checksum stored inline in the b-tree node header, each data block
 has a detached checksum stored in the checksum tree.
 

Documentation/ch-compression.rst

@@ -20,11 +20,11 @@ ZLIB
         * levels: 1 to 9, mapped directly, default level is 3
         * good backward compatibility
 LZO
-        * faster compression and decompression than zlib, worse compression ratio, designed to be fast
+        * faster compression and decompression than ZLIB, worse compression ratio, designed to be fast
         * no levels
         * good backward compatibility
 ZSTD
-        * compression comparable to zlib with higher compression/decompression speeds and different ratio
+        * compression comparable to ZLIB with higher compression/decompression speeds and different ratio
         * levels: 1 to 15, mapped directly (higher levels are not available)
         * since 4.14, levels since 5.1
 

Documentation/ch-fs-limits.rst

@@ -1,7 +1,7 @@
 maximum file name length
         255
 
-        This limit is imposed by Linux VFS, the strucutres of BTRFS could store
+        This limit is imposed by Linux VFS, the structures of BTRFS could store
         larger file names.
 
 maximum symlink target length