btrfs-progs: doc: update btrfstune manpage

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

Documentation/btrfstune.asciidoc

@@ -3,7 +3,7 @@ btrfstune(8)
 
 NAME
 ----
-btrfstune - tune various btrfs filesystem parameters
+btrfstune - tune various filesystem parameters
 
 SYNOPSIS
 --------
@@ -11,49 +11,61 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-*btrfstune* is used to tune various btrfs filesystem parameters,you can
+*btrfstune* can be used to enable, disable or set various filesystem
-enable/disable some extended features for btrfs.
+parameters. The filesystem must be unmounted.
+
+The common usecase 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 .
 
 OPTIONS
 -------
--S <value>::
+-S <0|1>::
-Updates the seeding value.
+Enable seeding on a given device. Value 1 will enable seeding, 0 will disable it. +
-A positive value will enable seeding, zero will disable seeding, negtive is not allowed.
+A seeding filesystem is forced to be mounted read-only. A new device can be added
-Enable seeding forces a fs readonly so that you can use it to build other filesystems.
+to the filesystem and will capture all writes keeping the seeding device intact.
 -r::
-Enable extended inode refs.
+Enable extended inode refs (hardlink limit per file in a directory is 65536). Since kernel 3.7.
 -x::
-Enable skinny metadata extent refs.
+Enable skinny metadata extent refs (more efficient representation of extents). Since kernel 3.10.
 -n::
-Enable no-holes feature. More efficient representation of file holes.
+Enable no-holes feature (more efficient representation of file holes). Since kernel 3.14.
 -f::
 Allow dangerous changes, e.g. clear the seeding flag or change fsid. Make sure
 that you are aware of the dangers.
 -u::
-Change fsid to a random generated UUID or continue previous change operation in
+Change fsid to a randomly generated UUID or continue previous fsid change
-case it was interrupted with the original UUID.
+operation in case it was interrupted.
 -U <UUID>::
 Change fsid to <UUID>.
 +
 The <UUID> should be a 36 bytes string in `printf`(3) format
 "%08x-%04x-%04x-%04x-%012x".
-If there is a previous unfinished fsid change, it will only continue if the
+If there is a previous unfinished fsid change, it will continue only if the
-<UUID> matches the unfinished one.
+<UUID> matches the unfinished one or if you use the option '-u'.
 
 WARNING: Cancelling or interrupting a UUID change operation will make the
 filesystem temporarily unmountable.  To fix it, rerun 'btrfstune -u' to restore
-the UUID and wait it complete.
+the UUID and let it complete.
 
-When mounting the new device, btrfs will check whether the seeding flag is set
+WARNING: Clearing the seeding flag on a device may be dangerous.
-when try to open seeding device.  If the user clears the seeding flag of the
+If a previously-seeding device is changed, all filesystems that used that
-seeding device, the new device will not be mountable. Even setting the seeding
+device will become unmountable. Setting the seeding flag back will not fix
-flag back will not fix this problem, because the generation will be changed at
+that. +
-that time. Clear the seeding flag may damage the new filesystem.
+A valid usecase is "seeding device as a base image". Clear the seeding
+flag, update the filesystem and make it seeding again, provided that it's ok
+to throw away all filesystems built on top of the previous base.
 
 EXIT STATUS
 -----------
-*btrfstune* will return 0 if no error happened.
+*btrfstune* returns 0 if no error happened, 1 otherwise.
-If any problems happened, 1 will be returned.
+
+COMPATIBILITY NOTE
+------------------
+This tool exists for historical reasons but is still in use today.  The
+functionality is about to be merged to the main tool someday and *btrfstune*
+will become deprecated and removed afterwards.
 
 SEE ALSO
 --------