btrfs-progs: docs: typo fixups and formatting updates

Signed-off-by: David Sterba <dsterba@suse.com>

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
+3.18 - auto block group reclaim
-        Automatically remove blockgroups (aka. chunks) that become completely empty.
+        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
+4.15 - ZLIB level
-        Allow to set the zlib compression level via mount option, e.g. like
+        Allow to set the ZLIB compression level via mount option, e.g. like
-        *compress=zlib:9*. The levels match the default zlib compression
+        *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
+5.1 - ZSTD level
-        Allow to set the zstd compression level via mount option, e.g. like
+        Allow to set the ZSTD compression level via mount option, e.g. like
-        *compress=zstd:9*. The levels match the default zstd compression
+        *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
+        into regular ones. See *fallocate(1)* and *fallocate(2)* manual pages
-	fallocate</code> for more details.
+        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
+        and deleted with the *btrfs<* tool. All subvolumes share the same pool
-	the same pool of free space in the filesystem. See also *default
+        of free space in the filesystem. See also *default subvolume*.
-	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
+github.com way is different in some ways. We, the upstream community, expect that
-the patches meet some criteria (often lacking in github contributions):
+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.
+        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
+        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

Documentation/ch-hardware-considerations.rst

@@ -73,14 +73,14 @@ media itself.
 
 * *Problem*: while the data are written atomically, the contents get changed
 * *Detection*: checksum mismatch on read
-* 'Repair*: use another copy or rebuild from multiple blocks using some
+* *Repair*: use another copy or rebuild from multiple blocks using some
   encoding scheme
 
 **Data get silently written to another offset (3)**
 
 This would be another serious problem as the filesystem has no information
 when it happens. For that reason the measures have to be done ahead of time.
-This problem is also commonly called 'ghost write'.
+This problem is also commonly called *ghost write*.
 
 The metadata blocks have the checksum embedded in the blocks, so a correct
 atomic write would not corrupt the checksum. It's likely that after reading
@@ -88,7 +88,6 @@ such block the data inside would not be consistent with the rest. To rule that
 out there's embedded block number in the metadata block. It's the logical
 block number because this is what the logical structure expects and verifies.
 
-
 The following is based on information publicly available, user feedback,
 community discussions or bug report analyses. It's not complete and further
 research is encouraged when in doubt.
@@ -115,7 +114,7 @@ type of memory is not available in all cases. A memory test should be performed
 in case there's a visible bit flip pattern, though this may not detect a faulty
 memory module because the actual load of the system could be the factor making
 the problems appear. In recent years attacks on how the memory modules operate
-have been demonstrated ('rowhammer') achieving specific bits to be flipped.
+have been demonstrated (*rowhammer*) achieving specific bits to be flipped.
 While these were targeted, this shows that a series of reads or writes can
 affect unrelated parts of memory.
 
@@ -216,7 +215,7 @@ so there is some value in reducing them. Depending on the device class (high
 end/low end) the features like DUP block group profiles may affect the
 reliability in both ways:
 
-* *high end* are typically more reliable and using 'single' for data and
+* *high end* are typically more reliable and using *single* for data and
   metadata could be suitable to reduce device wear
 * *low end* could lack ability to identify errors so an additional redundancy
   at the filesystem level (checksums, *DUP*) could help

Documentation/ch-mount-options.rst

@@ -18,7 +18,7 @@ have been applied.
 acl, noacl
         (default: on)
 
-        Enable/disable support for Posix Access Control Lists (ACLs).  See the
+        Enable/disable support for POSIX Access Control Lists (ACLs).  See the
         ``acl(5)`` manual page for more information about ACLs.
 
         The support for ACL is build-time configurable (BTRFS_FS_POSIX_ACL) and
@@ -110,7 +110,7 @@ compress, compress=<type[:level]>, compress-force, compress-force=<type[:level]>
         Both *zlib* and *zstd* (since version 5.1) expose the compression level as a
         tunable knob with higher levels trading speed and memory (*zstd*) for higher
         compression ratios. This can be set by appending a colon and the desired level.
-        Zlib accepts the range [1, 9] and zstd accepts [1, 15]. If no level is set,
+        ZLIB accepts the range [1, 9] and ZSTD accepts [1, 15]. If no level is set,
         both currently use a default level of 3. The value 0 is an alias for the
         default level.
 
@@ -480,7 +480,7 @@ noatime
         performance because no new access time information needs to be written. Without
         this option, the default is *relatime*, which only reduces the number of
         inode atime updates in comparison to the traditional *strictatime*. The worst
-        case for atime updates under 'relatime' occurs when many files are read whose
+        case for atime updates under *relatime* occurs when many files are read whose
         atime is older than 24 h and which are freshly snapshotted. In that case the
         atime is updated and COW happens - for each file - in bulk. See also
         https://lwn.net/Articles/499293/ - *Atime and btrfs: a bad combination? (LWN, 2012-05-31)*.

Documentation/ch-subvolume-intro.rst

@@ -93,7 +93,7 @@ Case study: system root layouts
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 There are two ways how the system root directory and subvolume layout could be
-organized. The interesting usecase for root is to allow rollbacks to previous
+organized. The interesting use case for root is to allow rollbacks to previous
 version, as one atomic step. If the entire filesystem hierarchy starting in "/"
 is in one subvolume, taking snapshot will encompass all files. This is easy for
 the snapshotting part but has undesirable consequences for rollback. For example,

Documentation/ch-swapfile.rst

@@ -7,7 +7,7 @@ swap subsystem:
 * filesystem - must have only *single* data profile
 * swapfile - the containing subvolume cannot be snapshotted
 * swapfile - must be preallocated (i.e. no holes)
-* swapfile - must be nodatacow (i.e. also nodatasum, no compression)
+* swapfile - must be NODATACOW (i.e. also NODATASUM, no compression)
 
 The limitations come namely from the COW-based design and mapping layer of
 blocks that allows the advanced features like relocation and multi-device

Documentation/ch-volume-management-intro.rst

@@ -20,7 +20,7 @@ Type
 Profile
         A profile describes an allocation policy based on the redundancy/replication
         constraints in connection with the number of devices. The profile applies to
-        data and metadata block groups separately. Eg. *single*, *RAID1*.
+        data and metadata block groups separately. E.g. *single*, *RAID1*.
 
 RAID level
         Where applicable, the level refers to a profile that matches constraints of the

Documentation/ch-zoned-intro.rst

@@ -33,7 +33,7 @@ Incompatible features
 The main constraint of the zoned devices is lack of in-place update of the data.
 This is inherently incompatible with some features:
 
-* nodatacow - overwrite in-place, cannot create such files
+* NODATACOW - overwrite in-place, cannot create such files
 * fallocate - preallocating space for in-place first write
 * mixed-bg - unordered writes to data and metadata, fixing that means using
   separate data and metadata block groups

Documentation/mkfs.btrfs.rst

@@ -258,7 +258,7 @@ extref
 raid56
         (kernel support since 3.9)
 
-        extended format for RAID5/6, also enabled if raid5 or raid6 block groups
+        extended format for RAID5/6, also enabled if RAID5 or RAID6 block groups
         are selected
 
 skinny-metadata