- grammar and language fixes

- hard sentence breaks
- trim EXIT STATUS section and move it to DIAGNOSTICS as well as use .Er
  macro
- sort SEE ALSO

MFC after:	7 days

sbin/geom/class/virstor/gvirstor.8

@@ -29,7 +29,7 @@
 .Os
 .Sh NAME
 .Nm gvirstor
-.Nd "provides virtual data storage geom"
+.Nd "control utility for virtual data storage devices"
 .Sh SYNOPSIS
 .Nm
 .Cm label
@@ -72,9 +72,10 @@ utility is used for setting up a virtual storage device of arbitrary
 large size
 .Pq for example, several TB ,
 consisting of an arbitrary number of physical storage devices with the
-total size which is equal to or smaller than the virtual size.  Data
+total size which is equal to or smaller than the virtual size.
-for the virtual devices will be allocated from physical devices on
+Data for the virtual devices will be allocated from physical devices on
-demand. The idea behind
+demand.
+The idea behind
 .Nm
 is similar to the concept of Virtual Memory in operating systems,
 effectively allowing users to overcommit on storage
@@ -82,35 +83,35 @@ effectively allowing users to overcommit on storage
 The first argument to
 .Nm
 indicates an action to be performed:
-.Bl -tag -width ".Cm destroy"
+.Bl -tag -width ".Cm remove"
 .It Cm label
 Set up a virtual device from the given components with the specified
 .Ar name .
-Metadata are stored in the last sector of every component.
+Metadata is stored in the last sector of every component.
 Argument
 .Fl s Ar virsize
-is the size of new virtual device, with default being 2 TiB
+is the size of new virtual device, with default being set to 2 TiB
 .Pq 2097152 MiB .
 Argument
 .Fl m Ar chunksize
-is the chunk size, with default being 4 MiB
+is the chunk size, with default being set to 4 MiB
 .Pq 4096 KiB .
-The default is thus
+The default arguments are thus
 .Qq Fl s Ar 2097152 Fl m Ar 4096 .
 .It Cm stop
-Turn off an existing virtual device by its
+Turn off an existing virtual device with the given
 .Ar name .
 This command does not touch on-disk metadata.
 As with other GEOM classes, stopped geoms cannot be started manually.
 .It Cm add
-Adds new components to existing virtual device by its
+Adds new components to existing virtual device with the given
 .Ar name .
 The specified virstor device must exist and be active
 .Pq i.e. module loaded, device present in Pa /dev .
 This action can be safely performed while the virstor device is in use
 .Pq Qo hot Qc operation
 .It Cm remove
-Removes components from existing virtual device by its
+Removes components from existing virtual device with the given
 .Ar name .
 Only unallocated providers can be removed.
 .It Cm clear
@@ -140,10 +141,6 @@ Hardcode providers' names in metadata.
 .It Fl v
 Be more verbose.
 .El
-.Sh EXIT STATUS
-The
-.Nm
-utility exits 0 on success, and 1 if an error occurs.
 .Sh EXAMPLES
 The following example shows how to create a virtual device of default size
 .Pq 2 TiB ,
@@ -165,12 +162,13 @@ To add a new physical device / component to an active virstor device:
 .No gvirstor add Ar mydata Ar ad8
 .Ed
 .Pp
-This will add physical storage
+This will add physical storage of
 .Ar ad8
 to
 .Pa /dev/virstor/mydata
 device.
-To see device status information
+.Pp
+To see the device status information
 .Pq including how much physical storage is still available for the virtual device ,
 use:
 .Bd -literal -offset indent
@@ -192,17 +190,20 @@ tunable variables.
 .Ed
 .Pp
 This sysctl controls verbosity of the kernel module, in the range
-1 to 15. Messages that are marked with higher verbosity levels than
+1 to 15.
-this are suppressed. Default value is 5 and it's not
+Messages that are marked with higher verbosity levels than this are
-recommended to set this tunable to less than 2, because level 1 messages
+suppressed.
-are error events, and level 2 messages are system warnings.
+Default value is 5 and it is not recommended to set this tunable to less
+than 2, because level 1 messages are error events, and level 2 messages
+are system warnings.
 .Bd -literal -offset indent
 .Va int kern.geom.virstor.chunk_watermark
 .Ed
 .Pp
-Value in this sysctl sets warning watermark level for physical chunk usage
+Value in this sysctl sets warning watermark level for physical chunk
-on a single component. The warning is issued when a virstor component
+usage on a single component.
-has less than this many free chunks
+The warning is issued when a virstor component has less than this many
+free chunks
 .Pq default 100 .
 .Bd -literal -offset indent
 .Va int kern.geom.virstor.component_watermark
@@ -217,31 +218,33 @@ All these sysctls are also available as
 .Xr loader 8
 tunables.
 .Sh DIAGNOSTICS
+.Ex -std
+.Pp
 .Nm
 kernel module issues log messages with prefixes in standardized format,
-which is useful for log message filtering and dispatching. Each message
+which is useful for log message filtering and dispatching.
-line begins with
+Each message line begins with
 .Bd -literal -offset indent
 .Li GEOM_VIRSTOR[%d]:
 .Ed
 .Pp
 The number
 .Pq %d
-is message verbosity / importance level, in the range 1 to 15. If a
+is message verbosity / importance level, in the range 1 to 15.
-message filtering, dispatching or operator alert system is used, it is
+If a message filtering, dispatching or operator alert system is used, it
-recommended that messages with levels 1 and 2 be taken seriously
+is recommended that messages with levels 1 and 2 be taken seriously
 .Pq for example, to catch out-of-space conditions as set by watermark
-sysctls .
+sysctls.
 .Sh SEE ALSO
 .Xr geom 4 ,
-.Xr geom 8 ,
-.Xr newfs 8 ,
 .Xr fstab 5 ,
-.Xr glabel 8
+.Xr geom 8 ,
+.Xr glabel 8 ,
+.Xr newfs 8
 .Sh HISTORY
 The
 .Nm
-utility appeared in
+utility first appeared in
 .Fx 7.0 .
 .Sh BUGS
 Commands
@@ -251,15 +254,15 @@ and
 contain unavoidable critical sections which may make the virstor
 device unusable if a power failure
 .Pq or other disruptive event
-happens during their execution.  It's recommended to run them when the
+happens during their execution.
-system is quiescent.
+It is recommended to run them when the system is quiescent.
 .Sh ASSUMPTIONS AND INTERACTION WITH FILE SYSTEMS
 There are several assumptions that
 .Nm
 has in its operation: that the size of the virtual storage device will not
-change once it's set, and that the sizes of individual physical storage
+change once it is set, and that the sizes of individual physical storage
-components will always remain constant during their existence. For
+components will always remain constant during their existence.
-alternative ways to implement virtual or resizable file systems see
+For alternative ways to implement virtual or resizable file systems see
 .Xr zfs 1M ,
 .Xr gconcat 8 and
 .Xr growfs 8 .
@@ -267,17 +270,18 @@ alternative ways to implement virtual or resizable file systems see
 Note that
 .Nm
 has nontrivial interaction with file systems which initialize a large
-number of on-disk structures during newfs.  If such file systems
+number of on-disk structures during newfs.
-attempt to spread their structures across the drive media
+If such file systems attempt to spread their structures across the drive
+media
 .Pq like UFS/UFS2 does ,
 their efforts will be effectively foiled by sequential allocation of
 chunks in
 .Nm
 and all their structures will be physically allocated at the start
-of the first virstor component.  This could have a significant impac
+of the first virstor component.
-t on file system performance
+This could have a significant impact on file system performance
 .Pq which can in some rare cases be even positive .
 .Sh AUTHOR
 .An Ivan Voras Aq ivoras@FreeBSD.org
 .Pp
-Sponsored by Google Summer of Code 2006
+Sponsored by Google Summer of Code 2006.