Man page patch (manage mode options clarification)

Man page patch (manage mode options clarification)

[Andre Majorel]

[-- Attachment #1: Type: text/plain, Size: 1756 bytes --]

This one is more debatable than the previous one. It attempts to
clarify the synopses of the manage mode options.

Those options take arguments so make that evident in the synopses.

I'm not entirely sure about the wording. Comments welcome. Is it
clearer than what we have now ?

Before :

  For Manage mode:
     -a, --add
            hot-add listed devices.

     --re-add
            re-add a device that was recently removed from an array.

     -r, --remove
            remove  listed  devices.  They must not be active.  i.e.
            they should be failed or spare devices.

     -f, --fail
            mark listed devices as faulty.

     --set-faulty
            same as --fail.

After :

  For Manage mode:
     -a, --add [component-device ...]
            Hot-add  its  arguments to raid-device.  If no arguments
            are given, this option is a no-op.

     --re-add [component-device ...]
            Re-add its arguments to raid-device.  The arguments must
            be  devices  that  were recently removed from the array.
            If no arguments are given, this option is a no-op.

     -r, --remove [component-device ...]
            Remove its arguments from  raid-device.   The  arguments
            must  not be active, i.e. they should be failed or spare
            devices.  If no arguments are given, this  option  is  a
            no-op.

     -f, --fail [component-device ...]
            Mark  its  arguments  as  faulty.   If  no arguments are
            given, this option is a no-op.

     --set-faulty [component-device ...]
            Same as --fail.

-- 
André Majorel <URL:http://www.teaser.fr/~amajorel/>
Do not use this account for regular correspondence.
See the URL above for contact information.

[-- Attachment #2: mdadm-2.6-man2.diff --]
[-- Type: text/plain, Size: 1724 bytes --]

diff -ur mdadm-2.6-man1/mdadm.8 mdadm-2.6-man2/mdadm.8
--- mdadm-2.6-man1/mdadm.8	2007-01-14 14:50:25.000000000 +0100
+++ mdadm-2.6-man2/mdadm.8	2007-01-14 15:19:07.000000000 +0100
@@ -13,7 +13,7 @@
 
 .SH SYNOPSIS
 
-.BI mdadm " [mode] <raiddevice> [options] <component-devices>"
+.BI mdadm " [mode] <raid-device> [options] <component-devices>"
 
 .SH DESCRIPTION
 RAID devices are virtual devices created from two or more
@@ -836,25 +836,30 @@
 .SH For Manage mode:
 
 .TP
-.BR -a ", " --add
-hot-add listed devices.
+\fB\-a\fP, \fB\-\-add\fP [\fIcomponent-device\fP ...]
+Hot-add its arguments to \fIraid-device\fP.
+If no arguments are given, this option is a no-op.
 
 .TP
-.BR --re-add
-re-add a device that was recently removed from an array.
+\fB\-\-re\-add\fP [\fIcomponent-device\fP ...]
+Re-add its arguments to \fIraid-device\fP.
+The arguments must be devices that were recently removed from the array.
+If no arguments are given, this option is a no-op.
 
 .TP
-.BR -r ", " --remove
-remove listed devices.  They must not be active.  i.e. they should
-be failed or spare devices.
+\fB\-r\fP, \fB\-\-remove\fP [\fIcomponent-device\fP ...]
+Remove its arguments from \fIraid-device\fP.
+The arguments must not be active, i.e. they should be failed or spare devices.
+If no arguments are given, this option is a no-op.
 
 .TP
-.BR -f ", " --fail
-mark listed devices as faulty.
+\fB\-f\fP, \fB\-\-fail\fP [\fIcomponent-device\fP ...]
+Mark its arguments as faulty.
+If no arguments are given, this option is a no-op.
 
 .TP
-.BR --set-faulty
-same as --fail.
+\fB\-\-set\-faulty\fP [\fIcomponent-device\fP ...]
+Same as \fB\-\-fail\fP.
 
 .P
 Each of these options require that the first device list is the array

Re: Man page patch (manage mode options clarification)

[Neil Brown]

On Sunday January 14, aym-xunil@teaser.fr wrote:
> This one is more debatable than the previous one. It attempts to
> clarify the synopses of the manage mode options.
> 
> Those options take arguments so make that evident in the synopses.
> 
> I'm not entirely sure about the wording. Comments welcome. Is it
> clearer than what we have now ?

I don't like it, though it is very possibly that the current text
could be improved.

I don't see the devices as arguments to the flags.  They are arguments
to "mdadm" and the flag say what it should do with the arguments.

Maybe it is a subtle difference.  Maybe I just need more people to say
"Neil is wrong, Andre is right"...  Maybe someone else will have an
even better idea....

Thanks anyway.

NeilBrown


> 
> Before :
> 
>   For Manage mode:
>      -a, --add
>             hot-add listed devices.
> 
>      --re-add
>             re-add a device that was recently removed from an array.
> 
>      -r, --remove
>             remove  listed  devices.  They must not be active.  i.e.
>             they should be failed or spare devices.
> 
>      -f, --fail
>             mark listed devices as faulty.
> 
>      --set-faulty
>             same as --fail.
> 
> After :
> 
>   For Manage mode:
>      -a, --add [component-device ...]
>             Hot-add  its  arguments to raid-device.  If no arguments
>             are given, this option is a no-op.
> 
>      --re-add [component-device ...]
>             Re-add its arguments to raid-device.  The arguments must
>             be  devices  that  were recently removed from the array.
>             If no arguments are given, this option is a no-op.
> 
>      -r, --remove [component-device ...]
>             Remove its arguments from  raid-device.   The  arguments
>             must  not be active, i.e. they should be failed or spare
>             devices.  If no arguments are given, this  option  is  a
>             no-op.
> 
>      -f, --fail [component-device ...]
>             Mark  its  arguments  as  faulty.   If  no arguments are
>             given, this option is a no-op.
> 
>      --set-faulty [component-device ...]
>             Same as --fail.
> 
> -- 
> André Majorel <URL:http://www.teaser.fr/~amajorel/>
> Do not use this account for regular correspondence.
> See the URL above for contact information.
> diff -ur mdadm-2.6-man1/mdadm.8 mdadm-2.6-man2/mdadm.8
> --- mdadm-2.6-man1/mdadm.8	2007-01-14 14:50:25.000000000 +0100
> +++ mdadm-2.6-man2/mdadm.8	2007-01-14 15:19:07.000000000 +0100
> @@ -13,7 +13,7 @@
>  
>  .SH SYNOPSIS
>  
> -.BI mdadm " [mode] <raiddevice> [options] <component-devices>"
> +.BI mdadm " [mode] <raid-device> [options] <component-devices>"
>  
>  .SH DESCRIPTION
>  RAID devices are virtual devices created from two or more
> @@ -836,25 +836,30 @@
>  .SH For Manage mode:
>  
>  .TP
> -.BR -a ", " --add
> -hot-add listed devices.
> +\fB\-a\fP, \fB\-\-add\fP [\fIcomponent-device\fP ...]
> +Hot-add its arguments to \fIraid-device\fP.
> +If no arguments are given, this option is a no-op.
>  
>  .TP
> -.BR --re-add
> -re-add a device that was recently removed from an array.
> +\fB\-\-re\-add\fP [\fIcomponent-device\fP ...]
> +Re-add its arguments to \fIraid-device\fP.
> +The arguments must be devices that were recently removed from the array.
> +If no arguments are given, this option is a no-op.
>  
>  .TP
> -.BR -r ", " --remove
> -remove listed devices.  They must not be active.  i.e. they should
> -be failed or spare devices.
> +\fB\-r\fP, \fB\-\-remove\fP [\fIcomponent-device\fP ...]
> +Remove its arguments from \fIraid-device\fP.
> +The arguments must not be active, i.e. they should be failed or spare devices.
> +If no arguments are given, this option is a no-op.
>  
>  .TP
> -.BR -f ", " --fail
> -mark listed devices as faulty.
> +\fB\-f\fP, \fB\-\-fail\fP [\fIcomponent-device\fP ...]
> +Mark its arguments as faulty.
> +If no arguments are given, this option is a no-op.
>  
>  .TP
> -.BR --set-faulty
> -same as --fail.
> +\fB\-\-set\-faulty\fP [\fIcomponent-device\fP ...]
> +Same as \fB\-\-fail\fP.
>  
>  .P
>  Each of these options require that the first device list is the array
-
To unsubscribe from this list: send the line "unsubscribe linux-raid" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html