btrfs-progs: docs: update quota pages

As reported, some of the information is not up to date regarding status.

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

Author: kdave

Documentation/btrfs-qgroup.rst

@@ -13,11 +13,7 @@ DESCRIPTION
 
 .. note::
    To use qgroup you need to enable quota first using :command:`btrfs quota enable`
-   command.
-
-.. warning::
-   Qgroup is not stable yet and will impact performance in current mainline
-   kernel (v4.14).
+   command, see :doc:`btrfs-quota`.
 
 QGROUP
 ------
@@ -26,10 +22,10 @@ Quota groups or qgroup in btrfs make a tree hierarchy, the leaf qgroups are
 attached to subvolumes. The size limits are set per qgroup and apply when any
 limit is reached in tree that contains a given subvolume.
 
-The limits are separated between shared and exclusive and reflect the extent
+The limits are separated between *shared* and *exclusive* and reflect the extent
 ownership. For example a fresh snapshot shares almost all the blocks with the
 original subvolume, new writes to either subvolume will raise towards the
-exclusive limit.
+exclusive limit. Extent sharing is also result of *reflink* or *deduplication*.
 
 .. note::
    Qgroup limit only works when qgroup is in a consistent state.
@@ -40,11 +36,12 @@ exclusive limit.
 The qgroup identifiers conform to *level/id* where level 0 is reserved to the
 qgroups associated with subvolumes. Such qgroups are created automatically.
 
-The qgroup hierarchy is built by commands :command:`create` and :command:`assign`.
+The qgroup hierarchy is built by commands :command:`btrfs qgroup create` and
+:command:`btrfs qgroup assign`.
 
 .. note::
-   If the qgroup of a subvolume is destroyed, quota about the subvolume will
-   not be functional until qgroup *0/<subvolume id>* is created again.
+   If the qgroup of a subvolume is destroyed, quota related to the subvolume
+   will not be functional until qgroup *0/<subvolume id>* is created again.
 
 SUBCOMMAND
 ----------
@@ -78,8 +75,9 @@ destroy <qgroupid> <path>
 
 clear-stale <path>
 	Clear all stale qgroups whose subvolume does not exist anymore, this is the
-	level 0 qgroup like 0/subvolid. Higher level qgroups are not deleted even
-	if they don't have any child qgroups.
+	level 0 qgroup like *0/subvolid*. Higher level qgroups are not deleted even
+        if they don't have any child qgroups as they are always created by the
+        user and their deletion should be verified first.
 
 limit [options] <size>|none [<qgroupid>] <path>
         Limit the size of a qgroup to *size* or no limit in the btrfs filesystem
@@ -161,21 +159,21 @@ show [options] <path>
 
 SPECIAL PATHS
 -------------
-For `btrfs qgroup show` subcommand, the ``path`` column may has some special
-strings:
+For :command:`btrfs qgroup show` command, the :file:`path` column can print
+special values:
 
 `<toplevel>`
-	The toplevel subvolume
+	The toplevel subvolume.
 
 `<under deletion>`
-        The subvolume has been deleted (it's directory removed), but the
+        The subvolume has been deleted (its directory removed), but the
         subvolume metadata not not yet fully cleaned.
 
 `<squota space holder>`
-	For simple quota mode only.
+	For *simple quota* mode only.
 	By its design, a fully deleted subvolume may still have accounting on
-	it, so even the subvolume is gone, the numbers are still here for future
-	accounting.
+        it, so even if the subvolume is gone, the numbers are still here for
+        future accounting.
 
 `<stale>`
 	The qgroup has no corresponding subvolume anymore, and the qgroup
@@ -190,7 +188,7 @@ QUOTA RESCAN
 The rescan reads all extent sharing metadata and updates the respective qgroups
 accordingly.
 
-The information consists of bytes owned exclusively (*excl*) or shared/referred
+The information consists of bytes owned exclusively (*excl*) or shared/referenced
 to (*rfer*). There's no explicit information about which extents are shared or
 owned exclusively.  This means when qgroup relationship changes, extent owners
 change and qgroup numbers are no longer consistent unless we do a full rescan.

Documentation/btrfs-quota.rst

@@ -19,21 +19,16 @@ of a btrfs filesystem. The quota groups (qgroups) are managed by the subcommand
         :ref:`HIERARCHICAL QUOTA GROUP CONCEPTS<man-quota-hierarchical-quota-group-concepts>`
         for a detailed description.
 
-PERFORMANCE IMPLICATIONS
-^^^^^^^^^^^^^^^^^^^^^^^^
+STABILITY AND PERFORMANCE IMPLICATIONS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The qgroup implementation is considered reasonably stable for daily use and has
+been enabled in various distributions.
 
 When quotas are activated, they affect all extent processing, which takes a
 performance hit. Activation of qgroups is not recommended unless the user
 intends to actually use them.
 
-STABILITY STATUS
-^^^^^^^^^^^^^^^^
-
-The qgroup implementation has turned out to be quite difficult as it affects
-the core of the filesystem operation. Qgroup users have hit various corner cases
-over time, such as incorrect accounting or system instability. The situation is
-gradually improving and issues found and fixed.
-
 .. _man-quota-hierarchical-quota-group-concepts:
 
 HIERARCHICAL QUOTA GROUP CONCEPTS

Documentation/ch-quota-intro.rst

@@ -11,7 +11,7 @@ on the fly.
 
 On the other hand, the traditional approach has only a poor solution to
 restrict directories.
-At installation time, the harddisk can be partitioned so that every directory
+At installation time, the storage device can be partitioned so that every directory
 (e.g. :file:`/usr`, :file:`/var`, ...) that needs a limit gets its own partition.  The obvious
 problem is that those limits cannot be changed without a reinstallation.  The
 btrfs subvolume feature builds a bridge.  Subvolumes correspond in many ways to
@@ -37,7 +37,8 @@ space and the amount of exclusively referenced space.
 
 referenced
         space is the amount of data that can be reached from any of the
-        subvolumes contained in the qgroup, while
+        subvolumes contained in the qgroup
+
 exclusive
         is the amount of data where all references to this data can be reached
         from within this qgroup.
@@ -50,12 +51,12 @@ qgroup.  Qgroups are notated as *level/id*, e.g.  the qgroup 3/2 is a qgroup of
 level 3. For level 0, the leading *0/* can be omitted.
 Qgroups of level 0 get created automatically when a subvolume/snapshot gets
 created.  The ID of the qgroup corresponds to the ID of the subvolume, so 0/5
-is the qgroup for the root subvolume.
+is the qgroup for the toplevel subvolume.
 For the :command:`btrfs qgroup` command, the path to the subvolume can also be used
 instead of *0/ID*.  For all higher levels, the ID can be chosen freely.
 
 Each qgroup can contain a set of lower level qgroups, thus creating a hierarchy
-of qgroups. Figure 1 shows an example qgroup tree.
+of qgroups. Here's an example of qgroup tree:
 
 .. code-block:: none
 
@@ -75,8 +76,6 @@ of qgroups. Figure 1 shows an example qgroup tree.
                       |        /         \   /         \
         extents       1       2            3            4
 
-        Figure 1: Sample qgroup hierarchy
-
 At the bottom, some extents are depicted showing which qgroups reference which
 extents.  It is important to understand the notion of *referenced* vs
 *exclusive*.  In the example, qgroup 0/2 references extents 2 and 3, while 1/2