[src/trunk]: src/sbin/raidctl Don't abuse -unfilled for -literal; sort sectio...

[wiz <wiz%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/64f9e6b704cd
branches:  trunk
changeset: 517623:64f9e6b704cd
user:      wiz <wiz%NetBSD.org@localhost>
date:      Fri Nov 16 11:06:46 2001 +0000

description:
Don't abuse -unfilled for -literal; sort sections, sort SEE ALSO, drop
lots of unnecessary .Pps.

diffstat:

 sbin/raidctl/raidctl.8 |  183 +++++++++++++++++++++++-------------------------
 1 files changed, 86 insertions(+), 97 deletions(-)

diffs (truncated from 597 to 300 lines):

diff -r 4f102aace9c5 -r 64f9e6b704cd sbin/raidctl/raidctl.8
--- a/sbin/raidctl/raidctl.8    Fri Nov 16 10:25:42 2001 +0000
+++ b/sbin/raidctl/raidctl.8    Fri Nov 16 11:06:46 2001 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: raidctl.8,v 1.25 2001/11/16 10:25:49 wiz Exp $
+.\"     $NetBSD: raidctl.8,v 1.26 2001/11/16 11:06:46 wiz Exp $
 .\"
 .\" Copyright (c) 1998 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -257,7 +257,6 @@
 may be either the full name of the device, e.g. /dev/rraid0d,
 for the i386 architecture, and /dev/rraid0c
 for all others, or just simply raid0 (for /dev/rraid0d).
-.Pp
 .Ss Configuration file
 The format of the configuration file is complex, and
 only an abbreviated treatment is given here.  In the configuration
@@ -275,7 +274,7 @@
 section, and it specifies
 the number of rows, columns, and spare disks in the RAID set.  For
 example:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 START array
 1 3 0
 .Ed
@@ -289,7 +288,7 @@
 .Sq disks
 section, specifies the actual
 components of the device.  For example:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 START disks
 /dev/sd0e
 /dev/sd1e
@@ -323,7 +322,7 @@
 one of the main components fail.  A simple
 .Sq spare
 section might be:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 START spare
 /dev/sd3e
 .Ed
@@ -340,7 +339,7 @@
 information as sectors per stripe unit, stripe units per parity unit,
 stripe units per reconstruction unit, and the parity configuration to
 use.  This section might look like:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 START layout
 # sectPerSU SUsPerParityUnit SUsPerReconUnit RAID_level
 32 1 1 5
@@ -380,7 +379,7 @@
 .Sq queue
 section.  This is most often
 specified as:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 START queue
 fifo 100
 .Ed
@@ -397,13 +396,17 @@
 discussed in the
 .Sx HISTORY
 section.
-
+.Pp
 See
 .Sx EXAMPLES
 for a more complete configuration file example.
-
+.Sh FILES
+.Bl -tag -width /dev/XXrXraidX -compact
+.It Pa /dev/{,r}raid*
+.Cm raid
+device special files.
+.El
 .Sh EXAMPLES
-
 It is highly recommended that before using the RAID driver for real
 file systems that the system administrator(s) become quite familiar
 with the use of
@@ -424,7 +427,6 @@
 .Sq /dev/rraid0d
 may be used in place of
 .Sq raid0 .
-.Pp
 .Ss Initialization and Configuration
 The initial step in configuring a RAID set is to identify the components
 that will be used in the RAID set.  All components should be the same
@@ -432,7 +434,7 @@
 .Dv FS_RAID ,
 and a typical disklabel entry for a RAID component
 might look like:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 f:  1800000  200495     RAID              # (Cyl.  405*- 4041*)
 .Ed
 .Pp
@@ -472,7 +474,7 @@
 .Xr raid 4
 device.  To configure the device, a configuration
 file which looks something like:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 START array
 # numRow numCol numSpare
 1 3 1
@@ -500,7 +502,7 @@
 in case one of
 the three main drives should fail. A RAID 0 set would be specified in
 a similar way:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 START array
 # numRow numCol numSpare
 1 4 0
@@ -525,7 +527,7 @@
 any of the components fail.
 .Pp
 For a RAID 1 (mirror) set, the following configuration might be used:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 START array
 # numRow numCol numSpare
 1 2 0
@@ -552,7 +554,7 @@
 The first time a RAID set is configured, the
 .Fl C
 option must be used:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 raidctl -C raid0.conf raid0
 .Ed
 .Pp
@@ -570,14 +572,14 @@
 appropriate component labels are added with the
 .Fl I
 option) then raid0 can be configured normally with:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 raidctl -c raid0.conf raid0
 .Ed
 .Pp
 When the RAID set is configured for the first time, it is
 necessary to initialize the component labels, and to initialize the
 parity on the RAID set.  Initializing the component labels is done with:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 raidctl -I 112341 raid0
 .Ed
 .Pp
@@ -604,13 +606,13 @@
 .Fl v
 option may be also used in conjunction with
 .Fl i :
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 raidctl -iv raid0
 .Ed
 .Pp
 This will give more verbose output on the
 status of the initialization:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 Initiating re-write of parity
 Parity Re-write status:
  10% |****                                   | ETA:    06:03 /
@@ -644,7 +646,7 @@
 component) and with a
 .Sq fake
 component.  In the following:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 START array
 # numRow numCol numSpare
 1 2 0
@@ -674,17 +676,16 @@
 in degraded mode.  Once a second physical component is obtained, it
 can be hot-added, the existing data mirrored, and normal operation
 resumed.
-.Pp
 .Ss Maintenance of the RAID set
 After the parity has been initialized for the first time, the command:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 raidctl -p raid0
 .Ed
 .Pp
 can be used to check the current status of the parity.  To check the
 parity and rebuild it necessary (for example, after an unclean
 shutdown) the command:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 raidctl -P raid0
 .Ed
 .Pp
@@ -697,12 +698,12 @@
 .Pp
 To see how the RAID set is doing, the following command can be used to
 show the RAID set's status:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 raidctl -s raid0
 .Ed
 .Pp
 The output will look something like:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 Components:
            /dev/sd1e: optimal
            /dev/sd2e: optimal
@@ -751,12 +752,12 @@
 but the set as a whole can still be clean.
 .Pp
 To check the component label of /dev/sd1e, the following is used:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 raidctl -g /dev/sd1e raid0
 .Ed
 .Pp
 The output of this command will look something like:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 Component label for /dev/sd1e:
    Row: 0 Column: 0 Num Rows: 1 Num Columns: 3
    Version: 2 Serial Number: 13432 Mod Counter: 65
@@ -766,19 +767,18 @@
    Autoconfig: No
    Last configured as: raid0
 .Ed
-.Pp
 .Ss Dealing with Component Failures
 If for some reason
 (perhaps to test reconstruction) it is necessary to pretend a drive
 has failed, the following will perform that function:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 raidctl -f /dev/sd2e raid0
 .Ed
 .Pp
 The system will then be performing all operations in degraded mode,
 where missing data is re-computed from existing data and the parity.
 In this case, obtaining the status of raid0 will return (in part):
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 Components:
            /dev/sd1e: optimal
            /dev/sd2e: failed
@@ -793,7 +793,7 @@
 start a reconstruction, the
 .Fl F
 option must be used:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 raidctl -F /dev/sd2e raid0
 .Ed
 .Pp
@@ -803,7 +803,7 @@
 .Fl F
 option used later, on the same disk, if desired.
 Immediately after the reconstruction is started, the status will report:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 Components:
            /dev/sd1e: optimal
            /dev/sd2e: reconstructing
@@ -825,7 +825,7 @@
 reconstruction is finished the
 .Fl s
 option will show:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 Components:
            /dev/sd1e: optimal
            /dev/sd2e: spared
@@ -850,7 +850,7 @@
 option.  In this example, this would copy the entire contents of
 /dev/sd4e to /dev/sd2e.  Once the copyback procedure is complete, the
 status of the device would be (in part):
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 Components:
            /dev/sd1e: optimal
            /dev/sd2e: optimal
@@ -864,7 +864,7 @@
 The second option after the reconstruction is to simply use /dev/sd4e
 in place of /dev/sd2e in the configuration file.  For example, the
 configuration file (in part) might now look like:
-.Bd -unfilled -offset indent
+.Bd -literal -offset indent
 START array
 1 3 0
 
@@ -885,7 +885,7 @@
 .Pp
 If a component fails and there are no hot spares
 available on-line, the status of the RAID set might (in part) look like:
-.Bd -unfilled -offset indent