Various man page fixes.

Signed-off-by: NeilBrown <neilb@suse.de>

2 files changed, 38 insertions, 27 deletions

diff --git a/mdadm.8.in b/mdadm.8.in
index 4b82fdcc..6b5017f1 100644
--- a/mdadm.8.in
+++ b/mdadm.8.in
@@ -1332,8 +1332,13 @@ not a name in
 
 .TP
 .BR \-\-path=
-Only used with \-\-fail. Allows the failed device to be automatically replaced
-by a new device without metadata if it appears at specified path.
+Only used with \-\-fail.  The 'path' given will be recorded so that if
+a new device appears at the same location it can be automatically
+added to the same array.  This allows the failed device to be
+automatically replaced by a new device without metadata if it appears
+at specified path.   This option is normally only set by a
+.I udev
+script.
 
 .SH For Monitor mode:
 .TP
@@ -1408,15 +1413,11 @@ message do get through successfully.
 
 .TP
 .BR \-\-no\-sharing
-Allows to run monitoring without moving spares between arrays.
+This inhibits the functionality for moving spares between arrays.
 Only one monitoring process started with
 .B \-\-scan
-is allowed.
-Any subsequent call of
-.B mdadm \-F \-\-scan
-must also use
-.B \-\-no\-sharing
-option.
+but without this flag is allowed, otherwise the two could interfere
+with each other.
 
 .SH ASSEMBLE MODE
 
@@ -1819,7 +1820,7 @@ or
 .B \-\-scan
 will cause the output to be less detailed and the format to be
 suitable for inclusion in
-.BR /etc/mdadm.conf .
+.BR mdadm.conf .
 The exit status of
 .I mdadm
 will normally be 0 unless
@@ -1896,7 +1897,7 @@ or
 is given, then multiple devices that are components of the one array
 are grouped together and reported in a single entry suitable
 for inclusion in
-.BR /etc/mdadm.conf .
+.BR mdadm.conf .
 
 Having
 .B \-\-scan
@@ -2150,7 +2151,7 @@ the original array.
 If the spare group for a degraded array is not defined,
 .I mdadm
 will look at the rules of spare migration specified by POLICY lines in
-.B /etc/mdadm.conf
+.B mdadm.conf
 and then follow similar steps as above if a matching spare is found.
 
 .SH GROW MODE
@@ -2335,8 +2336,8 @@ adds the device to the array and conditionally starts the array.
 
 Note that
 .I mdadm
-will always add devices to an array which were previously working
-(active or spare) parts of that array. The support for automatic
+will normally only add devices to an array which were previously working
+(active or spare) parts of that array.  The support for automatic
 inclusion of a new drive as a spare in some array requires
 a configuration through POLICY in config file.
 
@@ -2671,7 +2672,9 @@ avoid conflicted between multiple arrays that have the same name.  If
 .I mdadm
 can reasonably determine that the array really is meant for this host,
 either by a hostname in the metadata, or by the presence of the array
-in /etc/mdadm.conf, then it will leave off the suffix if possible.
+in
+.BR mdadm.conf ,
+then it will leave off the suffix if possible.
 Also if the homehost is specified as
 .B <ignore>
 .I mdadm
diff --git a/mdadm.conf.5 b/mdadm.conf.5
index ea56b556..65b00293 100644
--- a/mdadm.conf.5
+++ b/mdadm.conf.5
@@ -420,16 +420,16 @@ The known metadata types are
 
 .TP
 .B POLICY
-Allows to specify what automatic behavior is allowed on devices newly
-appearing in the system and provides a way of marking spares that can
-be moved to other array as well as the migration domains.
+This is used to specify what automatic behavior is allowed on devices 
+newly appearing in the system and provides a way of marking spares that can
+be moved to other arrays as well as the migration domains.
 .I Domain
 can be defined through
 .I policy
 line by specifying a domain name for a number of paths from
 .BR /dev/disk/by-path/ .
-A device may belong to several domains. Domain of an array is a union
-of domains of all devices in that array. A spare can be automatically
+A device may belong to several domains. The domain of an array is a union
+of domains of all devices in that array.  A spare can be automatically
 moved from one array to another if the set of the destination array's
 .I domains
 contains all the
@@ -439,11 +439,11 @@ of the new disk or if both arrays have the same
 
 To update hot plug configuration it is necessary to execute
 .B mdadm \-\-udev\-rules
-command after changing config file
+command after changing the config file
 
-Key words used in
+Key words used in the
 .I POLICY
-line and supported values:
+line and supported values are:
 
 .RS 7
 .TP
@@ -456,6 +456,11 @@ any arbitrary string
 .B path=
 file glob matching anything from
 .B /dev/disk/by-path
+.B type=
+either 
+.B disk
+or
+.BR part .
 .TP
 .B action=
 include, re-add, spare, spare-same-slot, or force-spare
@@ -465,7 +470,9 @@ The
 .I action
 item determines the automatic behavior allowed for devices matching the
 .I path
-in the same line. If a device matches several lines with different
+and
+.I type
+in the same line.  If a device matches several lines with different
 .I  actions
 then the most permissive will apply. The ordering of policy lines
 is irrelevant to the end result.
@@ -474,12 +481,13 @@ is irrelevant to the end result.
 allows adding a disk to an array if metadata on that disk matches that array
 .TP
 .B re-add
-will include device in the array if it appears to be a current member
+will include the device in the array if it appears to be a current member
 or a member that was recently removed
 .TP
 .B spare
-as above and additionally: if the device is bare it will
-become a spare (for metadata the same line)
+as above and additionally: if the device is bare it can
+become a spare if there is any array that it is a candidate for based
+on domains and metadata.
 .TP
 .B spare\-same\-slot
 as above and additionally if given slot was used by an array that went