From a0137082de2559b2e6854b76252f6187aa4b605b Mon Sep 17 00:00:00 2001 From: David Sterba Date: Wed, 28 Jun 2023 19:55:08 +0200 Subject: [PATCH] btrfs-progs: docs: formatting updates - use :file: and :command: - simplify manual page references - add more web links - typo fixes - more cross-references Signed-off-by: David Sterba --- Documentation/Administration.rst | 2 +- Documentation/Custom-ioctls.rst | 2 +- Documentation/Defragmentation.rst | 1 + Documentation/Reflink.rst | 4 +- Documentation/ReleaseChecklist | 2 - Documentation/Resize.rst | 5 +- Documentation/Send-receive.rst | 3 +- Documentation/Status.rst | 2 +- Documentation/Trim.rst | 2 +- Documentation/btrfs-balance.rst | 14 ++-- Documentation/btrfs-check.rst | 10 ++- Documentation/btrfs-convert.rst | 6 +- Documentation/btrfs-device.rst | 14 ++-- Documentation/btrfs-filesystem.rst | 22 +++--- Documentation/btrfs-find-root.rst | 2 +- Documentation/btrfs-image.rst | 2 +- Documentation/btrfs-inspect-internal.rst | 6 +- Documentation/btrfs-man5.rst | 38 +++++----- Documentation/btrfs-map-logical.rst | 2 +- Documentation/btrfs-property.rst | 4 +- Documentation/btrfs-qgroup.rst | 8 +- Documentation/btrfs-quota.rst | 8 +- Documentation/btrfs-receive.rst | 10 +-- Documentation/btrfs-replace.rst | 16 ++-- Documentation/btrfs-rescue.rst | 6 +- Documentation/btrfs-restore.rst | 14 +--- Documentation/btrfs-scrub.rst | 4 +- Documentation/btrfs-select-super.rst | 2 +- Documentation/btrfs-send.rst | 10 +-- Documentation/btrfs-subvolume.rst | 36 ++++++--- Documentation/btrfs.rst | 80 ++++++++++---------- Documentation/btrfstune.rst | 26 +++---- Documentation/ch-balance-filters.rst | 2 +- Documentation/ch-balance-intro.rst | 2 +- Documentation/ch-checksumming.rst | 6 +- Documentation/ch-compression.rst | 4 +- Documentation/ch-convert-intro.rst | 4 +- Documentation/ch-mount-options.rst | 6 +- Documentation/ch-quota-intro.rst | 38 ++++------ Documentation/ch-scrub-intro.rst | 4 +- Documentation/ch-seeding-device.rst | 16 ++-- Documentation/ch-subvolume-intro.rst | 14 ++-- Documentation/ch-swapfile.rst | 11 +-- Documentation/ch-volume-management-intro.rst | 12 +-- Documentation/ch-zoned-intro.rst | 6 +- Documentation/dev/Developer-s-FAQ.rst | 6 +- Documentation/dev/Development-notes.rst | 17 +++-- Documentation/fsck.btrfs.rst | 4 +- Documentation/mkfs.btrfs.rst | 18 ++--- 49 files changed, 279 insertions(+), 254 deletions(-) diff --git a/Documentation/Administration.rst b/Documentation/Administration.rst index e5346f12..6a631f52 100644 --- a/Documentation/Administration.rst +++ b/Documentation/Administration.rst @@ -1,7 +1,7 @@ Administration ============== -The main administration tool for BTRFS filesystems is :doc:`btrfs(8)`. +The main administration tool for BTRFS filesystems is :doc:`btrfs`. Please refer to the manual pages of the subcommands for further documentation. Mount options diff --git a/Documentation/Custom-ioctls.rst b/Documentation/Custom-ioctls.rst index e5bb3363..46d93709 100644 --- a/Documentation/Custom-ioctls.rst +++ b/Documentation/Custom-ioctls.rst @@ -21,4 +21,4 @@ a command if available: - query/set a subset of features on a mounted filesystem Programming documentaion of the ioctls is in the manual page -:doc:`btrfs-ioctl(2)`. +:doc:`btrfs-ioctl`. diff --git a/Documentation/Defragmentation.rst b/Documentation/Defragmentation.rst index e96f3d9e..36694574 100644 --- a/Documentation/Defragmentation.rst +++ b/Documentation/Defragmentation.rst @@ -28,3 +28,4 @@ space layout and fragmentation. Defragmentation can be started together with compression on the given range, and takes precedence over per-file compression property or mount options. +See command :ref:`btrfs filesystem defrag`. diff --git a/Documentation/Reflink.rst b/Documentation/Reflink.rst index 6c48897e..07a920df 100644 --- a/Documentation/Reflink.rst +++ b/Documentation/Reflink.rst @@ -26,8 +26,8 @@ There are some constraints: - works since 5.18 - reflink requires source and target file that have the same status regarding NOCOW and checksums, for example if the source file is NOCOW (once created - with the chattr +C attribute) then the above command won't work unless the + with the :command:`chattr +C` attribute) then the above command won't work unless the target file is pre-created with the +C attribute as well, or the NOCOW - attribute is inherited from the parent directory (chattr +C on the directory) + attribute is inherited from the parent directory (:command:`chattr +C` on the directory) or if the whole filesystem is mounted with *-o nodatacow* that would create the NOCOW files by default diff --git a/Documentation/ReleaseChecklist b/Documentation/ReleaseChecklist index d8bf50c1..98f23e05 100644 --- a/Documentation/ReleaseChecklist +++ b/Documentation/ReleaseChecklist @@ -32,6 +32,4 @@ Release: Post-release: * write and send announcement mail to mailinglist -* update wiki://Main_page#News -* update wiki://Changelog#btrfs-progs * update title on IRC diff --git a/Documentation/Resize.rst b/Documentation/Resize.rst index da19a19e..cc744d5f 100644 --- a/Documentation/Resize.rst +++ b/Documentation/Resize.rst @@ -1,8 +1,8 @@ Resize ====== -A BTRFS mounted filesystem can be resized after creation, grown or shrunk. On a -multi device filesystem the space occupied on each device can be resized +A mounted filesystem can be resized after creation, grown or shrunk. On a +multi-device filesystem the space occupied on each device can be resized independently. Data that reside in the area that would be out of the new size are relocated to the remaining space below the limit, so this constrains the minimum size to which a filesystem can be shrunk. @@ -10,3 +10,4 @@ minimum size to which a filesystem can be shrunk. Growing a filesystem is quick as it only needs to take note of the available space, while shrinking a filesystem needs to relocate potentially lots of data and this is IO intense. It is possible to shrink a filesystem in smaller steps. +See :ref:`btrfs filesystem resize` for more. diff --git a/Documentation/Send-receive.rst b/Documentation/Send-receive.rst index 1d93807a..ba2ae672 100644 --- a/Documentation/Send-receive.rst +++ b/Documentation/Send-receive.rst @@ -20,4 +20,5 @@ The stream is a sequence of encoded commands that change e.g. file metadata (owner, permissions, extended attributes), data extents (create, clone, truncate), whole file operations (rename, delete). The stream can be sent over network, piped directly to the receive command or saved to a file. Each command -in the stream is protected by a CRC32C checksum. +in the stream is protected by a CRC32C checksum. See :doc:`btrfs-send` +and :doc:`btrfs-receive` for more. diff --git a/Documentation/Status.rst b/Documentation/Status.rst index d84dceb5..5a131232 100644 --- a/Documentation/Status.rst +++ b/Documentation/Status.rst @@ -306,7 +306,7 @@ Defrag The data affected by the defragmentation process will be newly written and will consume new space, the links to the original extents will not -be kept. See also :doc:`btrfs-filesystem` . Though +be kept. See also :doc:`btrfs-filesystem` . Though autodefrag affects newly written data, it can read a few adjacent blocks (up to 64KiB) and write the contiguous extent to a new location. The adjacent blocks will be unshared. This happens on a smaller scale than diff --git a/Documentation/Trim.rst b/Documentation/Trim.rst index 8cd23fd4..533fa8a1 100644 --- a/Documentation/Trim.rst +++ b/Documentation/Trim.rst @@ -37,5 +37,5 @@ other factors affecting the memory cells. The device itself could internally relocate the data, however this leads to unexpected performance drop. Running trim periodically could prevent that too. -When a filesystem is created by :doc:`mkfs.btrfs(8)` and is capable +When a filesystem is created by :doc:`mkfs.btrfs` and is capable of trim, then it's by default performed on all devices. diff --git a/Documentation/btrfs-balance.rst b/Documentation/btrfs-balance.rst index 7adef1f2..8522ad96 100644 --- a/Documentation/btrfs-balance.rst +++ b/Documentation/btrfs-balance.rst @@ -56,11 +56,11 @@ start [options] ``Options`` -d[] - act on data block groups, see *FILTERS* section for details about *filters* + act on data block groups, see section :ref:`FILTERS` for details about *filters* -m[] - act on metadata chunks, see *FILTERS* section for details about *filters* + act on metadata chunks, see :ref:`FILTERS` for details about *filters* -s[] - act on system chunks (requires *-f*), see *FILTERS* section for details about *filters*. + act on system chunks (requires *-f*), see :ref:`FILTERS` for details about *filters*. -f force a reduction of metadata integrity, e.g. when going from *raid1* to @@ -84,6 +84,8 @@ status [-v] -v (deprecated) alias for global *-v* option +.. _man-balance-filters: + FILTERS ------- @@ -127,7 +129,7 @@ EXAMPLES -------- A more comprehensive example when going from one to multiple devices, and back, -can be found in section *TYPICAL USECASES* of :doc:`btrfs-device(8)`. +can be found in section *TYPICAL USECASES* of :doc:`btrfs-device`. MAKING BLOCK GROUP LAYOUT MORE COMPACT ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -268,5 +270,5 @@ AVAILABILITY SEE ALSO -------- -:doc:`mkfs.btrfs(8)`, -:doc:`btrfs-device(8)` +:doc:`mkfs.btrfs`, +:doc:`btrfs-device` diff --git a/Documentation/btrfs-check.rst b/Documentation/btrfs-check.rst index 6ade9d51..cf8de9fc 100644 --- a/Documentation/btrfs-check.rst +++ b/Documentation/btrfs-check.rst @@ -12,7 +12,7 @@ DESCRIPTION The filesystem checker is used to verify structural integrity of a filesystem and attempt to repair it if requested. It is recommended to unmount the filesystem prior to running the check, but it is possible to start checking a -mounted filesystem (see *--force*). +mounted filesystem (see :ref:`--force`). By default, :command:`btrfs check` will not modify the device but you can reaffirm that by the option *--readonly*. @@ -128,6 +128,8 @@ DANGEROUS OPTIONS *lowmem* mode does not work with *--repair* yet, and is still considered experimental. +.. _man-check-option-force: + --force allow work on a mounted filesystem and skip mount checks. Note that this should work fine on a quiescent or read-only mounted filesystem @@ -157,6 +159,6 @@ AVAILABILITY SEE ALSO -------- -:doc:`mkfs.btrfs(8)`, -:doc:`btrfs-scrub(8)`, -:doc:`btrfs-rescue(8)` +:doc:`mkfs.btrfs`, +:doc:`btrfs-scrub`, +:doc:`btrfs-rescue` diff --git a/Documentation/btrfs-convert.rst b/Documentation/btrfs-convert.rst index 55d9afa0..973025ab 100644 --- a/Documentation/btrfs-convert.rst +++ b/Documentation/btrfs-convert.rst @@ -31,7 +31,7 @@ OPTIONS set filesystem nodesize, the tree block size in which btrfs stores its metadata. The default value is 16KiB (16384) or the page size, whichever is bigger. Must be a multiple of the sectorsize, but not larger than 65536. See - :doc:`mkfs.btrfs(8)` for more details. + :doc:`mkfs.btrfs` for more details. -r|--rollback rollback to the original ext2/3/4 filesystem if possible -l|--label