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 <[email protected]>

Documentation/Administration.rst

@@ -1,7 +1,7 @@
 Administration
 ==============
 
-The main administration tool for BTRFS filesystems is :doc:`btrfs(8)<btrfs>`.
+The main administration tool for BTRFS filesystems is :doc:`btrfs`.
 Please refer to the manual pages of the subcommands for further documentation.
 
 Mount options

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)<btrfs-ioctl>`.
+:doc:`btrfs-ioctl`.

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<man-filesystem-cmd-defragment>`.

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

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

Documentation/Resize.rst

@@ -1,12 +1,13 @@
 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.
 
 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<man-filesystem-resize>` for more.

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.

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

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)<mkfs.btrfs>` 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.

Documentation/btrfs-balance.rst

@@ -56,11 +56,11 @@ start [options] <path>
         ``Options``
 
         -d[<filters>]
-                act on data block groups, see *FILTERS* section for details about *filters*
+                act on data block groups, see section :ref:`FILTERS<man-balance-filters>` for details about *filters*
         -m[<filters>]
-                act on metadata chunks, see *FILTERS* section for details about *filters*
+                act on metadata chunks, see :ref:`FILTERS<man-balance-filters>` for details about *filters*
         -s[<filters>]
-                act on system chunks (requires *-f*), see *FILTERS* section for details about *filters*.
+                act on system chunks (requires *-f*), see :ref:`FILTERS<man-balance-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] <path>
         -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)<btrfs-device>`.
+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)<mkfs.btrfs>`,
-:doc:`btrfs-device(8)<btrfs-device>`
+:doc:`mkfs.btrfs`,
+:doc:`btrfs-device`

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<man-check-option-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)<mkfs.btrfs>`,
-:doc:`btrfs-scrub(8)<btrfs-scrub>`,
-:doc:`btrfs-rescue(8)<btrfs-rescue>`
+:doc:`mkfs.btrfs`,
+:doc:`btrfs-scrub`,
+:doc:`btrfs-rescue`

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)<mkfs.btrfs>` for more details.
+        :doc:`mkfs.btrfs` for more details.
 -r|--rollback
         rollback to the original ext2/3/4 filesystem if possible
 -l|--label <LABEL>
@@ -43,7 +43,7 @@ OPTIONS
         are supported by old kernels. To disable a feature, prefix it with *^*.
         Description of the features is in section
         :ref:`FILESYSTEM FEATURES<man-mkfs-filesystem-features>` of
-        :doc:`mkfs.btrfs(8)<mkfs.btrfs>`.
+        :doc:`mkfs.btrfs`.
 
         To see all available features that btrfs-convert supports run:
 
@@ -73,4 +73,4 @@ If any problems happened, 1 will be returned.
 SEE ALSO
 --------
 
-:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
+:doc:`mkfs.btrfs`

Documentation/btrfs-device.rst

@@ -47,7 +47,7 @@ remove [options] <device>|<devid> [<device>|<devid>...] <path>
         Device removal must satisfy the profile constraints, otherwise the command
         fails. The filesystem must be converted to profile(s) that would allow the
         removal. This can typically happen when going down from 2 devices to 1 and
-        using the RAID1 profile. See the section *TYPICAL USECASES*.
+        using the RAID1 profile. See the section :ref:`Typical use cases<man-device-typical-use-cases>`.
 
         The operation can take long as it needs to move all data from the device.
 
@@ -76,7 +76,7 @@ delete <device>|<devid> [<device>|<devid>...] <path>
 
 replace <command> [options] <path>
         Alias of whole command group *btrfs replace* for convenience. See
-        :doc:`btrfs-replace(8)<btrfs-replace>`.
+        :doc:`btrfs-replace`.
 
 ready <device>
         Wait until all devices of a multiple-device filesystem are scanned and
@@ -99,7 +99,7 @@ scan [options] [<device> [<device>...]]
         The command can be run repeatedly. Devices that have been already registered
         remain as such. Reloading the kernel module will drop this information. There's
         an alternative way of mounting multiple-device filesystem without the need for
-        prior scanning. See the mount option *device*.
+        prior scanning. See the mount option :ref:`device<mount-option-device>`.
 
         ``Options``
 
@@ -250,7 +250,7 @@ AVAILABILITY
 SEE ALSO
 --------
 
-:doc:`btrfs-balance(8)<btrfs-balance>`
-:doc:`btrfs-device(8)<btrfs-device>`,
-:doc:`btrfs-replace(8)<btrfs-replace>`,
-:doc:`mkfs.btrfs(8)<mkfs.btrfs>`,
+:doc:`btrfs-balance`
+:doc:`btrfs-device`,
+:doc:`btrfs-replace`,
+:doc:`mkfs.btrfs`

Documentation/btrfs-filesystem.rst

@@ -78,6 +78,8 @@ df [options] <path>
 
         If conflicting options are passed, the last one takes precedence.
 
+.. _man-filesystem-cmd-defragment:
+
 defragment [options] <file>|<dir> [<file>|<dir>...]
         Defragment file data on a mounted filesystem. Requires kernel 2.6.33 and newer.
 
@@ -215,6 +217,8 @@ mkswapfile [-s size] file
                 specify UUID to use, or a special value: clear (all zeros), random,
                 time (time-based random)
 
+.. _man-filesystem-resize:
+
 resize [options] [<devid>:][+/-]<size>[kKmMgGtTpPeE]|[<devid>:]max <path>
         Resize a mounted filesystem identified by *path*. A particular device
         can be resized by specifying a *devid*.
@@ -268,8 +272,8 @@ show [options] [<path>|<uuid>|<device>|<label>]
         -m|--mounted
                 probe kernel for mounted BTRFS filesystems
         -d|--all-devices
-                scan all devices under */dev*, otherwise the devices list is extracted from the
-                */proc/partitions* file. This is a fallback option if there's no device node
+                scan all devices under :file:`/dev`, otherwise the devices list is extracted from the
+                :file:`/proc/partitions` file. This is a fallback option if there's no device node
                 manager (like udev) available in the system.
 
         --raw
@@ -350,7 +354,7 @@ usage [options] <path> [<path>...]
           block reserve, used for emergency purposes (like deletion on a full
           filesystem)
         * *Multiple profiles* -- what block group types (data, metadata) have
-          more than one profile (single, raid1, ...), see :doc:`btrfs(5)<btrfs-man5>` section
+          more than one profile (single, raid1, ...), see :doc:`btrfs-man5` section
           :ref:`FILESYSTEMS WITH MULTIPLE PROFILES<man-btrfs5-filesystem-with-multiple-profiles>`.
 
         And on a zoned filesystem there are two more lines in the *Device* section:
@@ -419,26 +423,26 @@ EXAMPLES
 
 **$ btrfs filesystem defrag -v -r dir/**
 
-Recursively defragment files under *dir/*, print files as they are processed.
+Recursively defragment files under :file:`dir/`, print files as they are processed.
 The file names will be printed in batches, similarly the amount of data triggered
 by defragmentation will be proportional to last N printed files. The system dirty
 memory throttling will slow down the defragmentation but there can still be a lot
 of IO load and the system may stall for a moment.
 
 **$ btrfs filesystem defrag -v -r -f dir/**
 
-Recursively defragment files under *dir/*, be verbose and wait until all blocks
+Recursively defragment files under :file:`dir/`, be verbose and wait until all blocks
 are flushed before processing next file. You can note slower progress of the
 output and lower IO load (proportional to currently defragmented file).
 
 **$ btrfs filesystem defrag -v -r -f -clzo dir/**
 
-Recursively defragment files under *dir/*, be verbose, wait until all blocks are
+Recursively defragment files under :file:`dir/`, be verbose, wait until all blocks are
 flushed and force file compression.
 
 **$ btrfs filesystem defrag -v -r -t 64M dir/**
 
-Recursively defragment files under *dir/*, be verbose and try to merge extents
+Recursively defragment files under :file:`dir/`, be verbose and try to merge extents
 to be about 64MiB. As stated above, the success rate depends on actual free
 space fragmentation and the final result is not guaranteed to meet the target
 even if run repeatedly.
@@ -479,5 +483,5 @@ AVAILABILITY
 SEE ALSO
 --------
 
-:doc:`btrfs-subvolume(8)<btrfs-subvolume>`,
-:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
+:doc:`btrfs-subvolume`,
+:doc:`mkfs.btrfs`

Documentation/btrfs-find-root.rst

@@ -33,4 +33,4 @@ If any problems happened, 1 will be returned.
 SEE ALSO
 --------
 
-:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
+:doc:`mkfs.btrfs`

Documentation/btrfs-image.rst

@@ -62,4 +62,4 @@ If any problems happened, 1 will be returned.
 SEE ALSO
 --------
 
-:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
+:doc:`mkfs.btrfs`

Documentation/btrfs-inspect-internal.rst

@@ -165,6 +165,8 @@ logical-resolve [-Pvo] [-s <bufsize>] <logical> <path>
         -v
                 (deprecated) alias for global *-v* option
 
+.. _man-inspect-map-swapfile:
+
 map-swapfile [options] <file>
         (needs root privileges)
 
@@ -194,6 +196,8 @@ min-dev-size [options] <path>
         --id <id>
                 specify the device *id* to query, default is 1 if this option is not used
 
+.. _man-inspect-rootid:
+
 rootid <path>
         for a given file or directory, return the containing tree root id, but for a
         subvolume itself return its own tree id (i.e. subvol id)
@@ -239,4 +243,4 @@ AVAILABILITY
 SEE ALSO
 --------
 
-:doc:`mkfs.btrfs(8)<mkfs.btrfs>`
+:doc:`mkfs.btrfs`