Improve btrfs man page

Improve btrfs man page

[Per Nystrom]

Hi,

I am going through the process of replacing a bad drive in a RAID 1
mirror.  The filesystem wouldn't mount because of the missing device,
and the btrfs man pages were not helpful in resolving it.  Specifically,
it would have been very useful to me if this part of the wiki were
included somewhere:

https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices#Replacing_failed_devices

There is no mention in the man pages of the -o degraded mount option,
which is needed to even manipulate the filesystem; nor is there any
mention of the special option "missing" for device delete.

I'm sure I'm not the only one who would turn to man btrfs first when
facing a failed drive.

Thanks,
Per

Re: Improve btrfs man page

[Duncan]

Per Nystrom posted on Sun, 23 Mar 2014 13:38:21 -0700 as excerpted:

> I am going through the process of replacing a bad drive in a RAID 1
> mirror.  The filesystem wouldn't mount because of the missing device,
> and the btrfs man pages were not helpful in resolving it.  Specifically,
> it would have been very useful to me if this part of the wiki were
> included somewhere:
> 
> https://btrfs.wiki.kernel.org/index.php/
Using_Btrfs_with_Multiple_Devices#Replacing_failed_devices
> 
> There is no mention in the man pages of the -o degraded mount option,
> which is needed to even manipulate the filesystem; nor is there any
> mention of the special option "missing" for device delete.
> 
> I'm sure I'm not the only one who would turn to man btrfs first when
> facing a failed drive.

Of course traditionally, mount options are covered in the mount manpage.  
But btrfs is new enough I guess it's not in that manpage yet, which has 
frustrated me too, since that's intuitively where I look.

The mount-manpage alternatives are either the wiki, or the
Documentation/filesystems/btrfs.txt file in the kernel sources.

But you're absolutely correct about btrfs device delete missing.  Btrfs 
device delete is of course in the btrfs manpage, but the one-sentence 
description lacks any hint that "missing" can be used if the device 
simply isn't there any longer.  Fleshing that out a bit beyond the single 
sentence would definitely be useful!

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman