From 0791a058faf0046967a01bd5f0f7bfa6c9b9709f Mon Sep 17 00:00:00 2001
From: Benno Schulenberg <bensberg@justemail.net>
Date: Sun, 27 Feb 2011 16:28:14 +0100
Subject: [PATCH] textual: tweak several manpages, mainly the blkid one

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>
---
 misc-utils/blkid.8  | 97 ++++++++++++++++++++++-----------------------
 misc-utils/findfs.8 |  4 +-
 misc-utils/kill.1   |  4 +-
 misc-utils/look.1   | 13 +++---
 misc-utils/lsblk.8  |  4 +-
 misc-utils/rename.1 |  6 +--
 misc-utils/wipefs.8 | 14 +++----
 7 files changed, 70 insertions(+), 72 deletions(-)

diff --git a/misc-utils/blkid.8 b/misc-utils/blkid.8
index 05711ca8a..1dbb20b07 100644
--- a/misc-utils/blkid.8
+++ b/misc-utils/blkid.8
@@ -5,9 +5,9 @@
 .\" This file may be copied under the terms of the GNU Public License.
 .\"
 .\" Based on uuidgen, Mon Sep 17 10:42:12 2000, Andreas Dilger
-.TH BLKID 8 "February 2009" "Linux" "MAINTENANCE COMMANDS"
+.TH BLKID 8 "February 2011" "Linux" "MAINTENANCE COMMANDS"
 .SH NAME
-blkid \- command\-line utility to locate/print block device attributes
+blkid \- locate/print block device attributes
 .SH SYNOPSIS
 .B blkid
 .RB \-L
@@ -46,8 +46,7 @@ blkid \- command\-line utility to locate/print block device attributes
 .IR list ]
 .RB [ \-u
 .IR list ]
-.I device
-[\fIdevice\fR ...]
+.IR device " ... "
 .in -9
 
 .B blkid
@@ -56,22 +55,21 @@ blkid \- command\-line utility to locate/print block device attributes
 .IR format ]
 .RB [ \-s
 .IR tag ]
-.I device
-[\fIdevice\fR ...]
+.IR device " ... "
 
 .SH DESCRIPTION
 The
 .B blkid
-program is the command-line interface to working with
+program is the command-line interface to working with the
 .BR libblkid (3)
-library.  It can determine the type of content (e.g. filesystem, swap)
-a block device holds, and also attributes (tokens, NAME=value pairs)
+library.  It can determine the type of content (e.g. filesystem or swap)
+that a block device holds, and also attributes (tokens, NAME=value pairs)
 from the content metadata (e.g. LABEL or UUID fields).
 .PP
 .B blkid
 has two main forms of operation: either searching for a device with a
 specific NAME=value pair, or displaying NAME=value pairs for one or
-more devices.
+more specified devices.
 .SH OPTIONS
 The \fIsize\fR and \fIoffset\fR arguments may be followed by binary (2^N) 
 suffixes KiB, MiB, GiB, TiB, PiB and EiB (the "iB" is optional, e.g. "K" has the
@@ -94,12 +92,11 @@ devices which no longer exist.
 Display a usage message and exit.
 .TP
 .B \-i
-Display I/O Limits (aka I/O topology) information. The 'export' output format is
-automatically enabled. This option could be used together with \fB-p\fR option.
+Display I/O Limits (aka I/O topology) information.  The 'export' output format is
+automatically enabled.  This option can be used together with the \fB-p\fR option.
 .TP
 .B \-l
-Look up one device that matches the search parameter specified using
-the
+Look up only one device that matches the search parameter specified with the
 .B \-t
 option.  If there are multiple devices that match the specified search
 parameter, then the device with the highest priority is returned, and/or
@@ -109,33 +106,33 @@ block devices.  If this option is not specified,
 .B blkid
 will print all of the devices that match the search parameter.
 .TP
-.B \-L " label "
-Look up one device that uses the label (same as: -l -o device -t
-LABEL=<label>).  This look up method is able to reliable use /dev/disk/by-label
-udev symlinks (depends on setting in /etc/blkid.conf). Avoid to use the
-symlinks directly. It is not reliable to use the symlinks without verification.
+.BI \-L " label"
+Look up the device that uses this \fIlabel\fR (equal to: -l -o device -t
+LABEL=<label>).  This lookup method is able to reliably use /dev/disk/by-label
+udev symlinks (dependent on a setting in /etc/blkid.conf).  Avoid using the
+symlinks directly; it is not reliable to use the symlinks without verification.
 The \fB-L\fR option works on systems with and without udev.
 
 Unfortunately, the original
 .B blkid(8)
 from e2fsprogs use the \fB-L\fR option as a
-synonym to the \fB-o list\fR option. For better portability use "-l -o device
--t LABEL=<label>" and "-o list" in your scripts rather than -L option.
+synonym for the \fB-o list\fR option.  For better portability, use \fB-l -o device
+-t LABEL=<label>\fR and \fB-o list\fR in your scripts rather than the \fB-L\fR option.
 .TP
-.B \-n " list "
-Restrict probing functions to defined (comma separated) list of superblock types (names).
-The list can be prefixed with "no" to specify the types which should be ignored.
+.BI \-n " list "
+Restrict the probing functions to the specified (comma-separated) \fIlist\fR of
+superblock types (names).
+The list items may be prefixed with "no" to specify the types which should be ignored.
 For example:
 .sp
   blkid -p -n vfat,ext3,ext4 /dev/sda1
 .sp
 probes for vfat, ext3 and ext4 filesystems, and
 .sp
-  blkid -p -u nominix /dev/sda1
+  blkid -p -n nominix /dev/sda1
 .sp
-probes for all supported formats exclude minix filesystem. This option is
-useful with
-\fB-p\fR only.
+probes for all supported formats except minix filesystems.
+This option is only useful together with \fB-p\fR.
 .TP
 .BI \-o " format"
 Display
@@ -152,29 +149,29 @@ print all tags (the default)
 print the value of the tags
 .TP
 .B list
-print the devices in a user-friendly format, this output format is unsupported
+print the devices in a user-friendly format; this output format is unsupported
 for low-level probing (\fB-p\fR or \fB-i\fR)
 .TP
 .B device
-print the device name only, this output format is always enabled for \fB-L\fR
+print the device name only; this output format is always enabled for \fB-L\fR
 and \fB-U\fR options
 .TP
 .B udev
-print key="value" pairs for easy import into the udev environment. The keys are
-prefixed by ID_FS_ or ID_PART_ prefixes.
+print key="value" pairs for easy import into the udev environment; the keys are
+prefixed by ID_FS_ or ID_PART_ prefixes
 
-The udev output returns ID_FS_AMBIVALENT tag if more superblocks are detected,
+The udev output returns the ID_FS_AMBIVALENT tag if more superblocks are detected,
 and ID_PART_ENTRY_* tags are always returned for all partitions including empty
 partitions.
 .TP
 .B export
-print key=value pairs for easy import into the environment.  This output format
-is automatically enabled when I/O Limits (\fB-i\fR option) are requested. 
+print key=value pairs for easy import into the environment; this output format
+is automatically enabled when I/O Limits (\fB-i\fR option) are requested
 .RE
 .TP
 .BI \-O " offset"
-Probe at the given offset (only useful with \fB-p\fR). This option could be
-used together with \fB-i\fR option.
+Probe at the given \fIoffset\fR (only useful with \fB-p\fR).  This option can be
+used together with the \fB-i\fR option.
 .TP
 .BI \-p
 Switch to low-level superblock probing mode (bypass cache).
@@ -212,22 +209,22 @@ and
 If there are no devices specified on the command line, all block devices
 will be searched; otherwise only the specified devices are searched.
 .TP
-.B \-u " list "
-Restrict probing functions to defined (comma separated) list of "usage" types.
-Supported usage types are: filesystem, raid, crypto and other. The list can be
-prefixed with "no" to specify the usage types which should be ignored. For example:
+.BI \-u " list "
+Restrict the probing functions to the specified (comma-separated) \fIlist\fR of "usage" types.
+Supported usage types are: filesystem, raid, crypto and other.  The list items may be
+prefixed with "no" to specify the usage types which should be ignored.  For example:
 .sp
   blkid -p -u filesystem,other /dev/sda1
 .sp
-probes for all filesystems and others (e.g. swap) formats, and
+probes for all filesystem and other (e.g. swap) formats, and
 .sp
   blkid -p -u noraid /dev/sda1
 .sp
-probes for all supported formats exclude RAIDs. This option is useful with
-\fB-p\fR only.
+probes for all supported formats except RAIDs.
+This option is only useful together with \fB-p\fR.
 .TP
-.B \-U " uuid "
-Look up one device that uses the uuid. For more details see the \fB-L\fR option.
+.BI \-U " uuid "
+Look up the device that uses this \fIuuid\fR.  For more details see the \fB-L\fR option.
 .TP
 .B \-v
 Display version number and exit.
@@ -237,9 +234,9 @@ Write the device cache to
 .I writecachefile
 instead of writing it to the default cache file
 .IR /etc/blkid.tab .
-If you don't want to save the cache to the default file, specify
+If you don't want to save the cache at all, specify
 .IR /dev/null.
-If not specified it will be the same file as that given by the
+If not specified, it will be the same file as that given with the
 .B \-c
 option.
 .TP
@@ -256,11 +253,11 @@ If the specified token was found, or if any tags were shown from (specified)
 devices, 0 is returned.
 
 If the specified token was not found, or no (specified) devices could be
-identified an exit code of 2 is returned.
+identified, an exit code of 2 is returned.
 
 For usage or other errors, an exit code of 4 is returned.
 
-If the ambivalent low-level probing result was detected an exit code of 8 is
+If the ambivalent low-level probing result was detected, an exit code of 8 is
 returned.
 .SH AUTHOR
 .B blkid
diff --git a/misc-utils/findfs.8 b/misc-utils/findfs.8
index 107b85b79..92db09d00 100644
--- a/misc-utils/findfs.8
+++ b/misc-utils/findfs.8
@@ -4,7 +4,7 @@
 .\"
 .TH FINDFS 8 "February 2009" "Linux" "MAINTENANCE COMMANDS"
 .SH NAME
-findfs \- Find a filesystem by label or UUID
+findfs \- find a filesystem by label or UUID
 .SH SYNOPSIS
 .B findfs
 .BI LABEL= label
@@ -24,7 +24,7 @@ be printed on stdout.
 .SH AUTHOR
 .B findfs
 was originally written by Theodore Ts'o (tytso@mit.edu) and re-written for
-util-linux package by Karel Zak (kzak@redhat.com).
+the util-linux package by Karel Zak (kzak@redhat.com).
 .SH AVAILABILITY
 The findfs command is part of the util-linux package and is available from
 ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
diff --git a/misc-utils/kill.1 b/misc-utils/kill.1
index 06792a157..07cbdaed8 100644
--- a/misc-utils/kill.1
+++ b/misc-utils/kill.1
@@ -26,8 +26,8 @@ it may be necessary to use the KILL (9) signal, since this signal cannot
 be caught.
 .PP
 Most modern shells have a builtin kill function, with a usage rather similar
-to that of the command described here. The `-a' and `-p' options,
-and the possibility to specify pids by command name is a local extension.
+to that of the command described here.  The `-a' and `-p' options,
+and the possibility to specify processes by command name are a local extension.
 .PP
 If sig is 0, then no signal is sent, but error checking is still performed.
 .SH OPTIONS
diff --git a/misc-utils/look.1 b/misc-utils/look.1
index e4dbb940c..d0386f38a 100644
--- a/misc-utils/look.1
+++ b/misc-utils/look.1
@@ -72,13 +72,13 @@ Options:
 .Bl -tag -width Ds
 .It Fl d
 Dictionary character set and order, i.e. only alphanumeric characters
-are compared. (On by default if no file specified).
+are compared.  (On by default if no file is specified).
 .It Fl f
-Ignore the case of alphabetic characters. (On by default if no file specified).
+Ignore the case of alphabetic characters.  (On by default if no file is specified).
 .It Fl a
 Use the alternate dictionary
-.Pa /usr/share/dict/web2
-.It Fl t
+.Pa /usr/share/dict/web2 .
+.It Fl t Ar termchar
 Specify a string termination character, i.e. only the characters
 in
 .Ar string
@@ -109,8 +109,9 @@ option was specified.
 This was incorrect and the current man page matches the historic
 implementation.
 .Sh HISTORY
-.Nm Look
-appeared in Version 7 AT&T Unix.
+The
+.Nm look
+utility appeared in Version 7 AT&T Unix.
 .Sh AVAILABILITY
 The look command is part of the util-linux package and is available from
 ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
diff --git a/misc-utils/lsblk.8 b/misc-utils/lsblk.8
index b7d33965d..38ff48f00 100644
--- a/misc-utils/lsblk.8
+++ b/misc-utils/lsblk.8
@@ -11,7 +11,7 @@ lsblk \- list block devices
 .IR device...
 .SH DESCRIPTION
 .B lsblk
-lists information about all or the specified block devices. The
+lists information about all or the specified block devices.  The
 .B lsblk
 command reads the
 .I sysfs
@@ -30,7 +30,7 @@ Print the SIZE column in bytes rather than in human-readable format.
 Don't print device holders or slaves.  For example "lsblk --nodeps /dev/sda" prints
 information about the sda device only.
 .IP "\fB\-e, \-\-exclude \fIlist\fP
-Exclude the devices specified by a comma-delimited list of major device numbers.
+Exclude the devices specified by a comma-separated \fIlist\fR of major device numbers.
 Note that RAM disks (major=1) are excluded by default.
 .IP "\fB\-f, \-\-fs\fP
 Output info about filesystems.  This option is equivalent to "-o NAME,FSTYPE,LABEL,MOUNTPOINT".
diff --git a/misc-utils/rename.1 b/misc-utils/rename.1
index 30b0699c1..bd676a8dd 100644
--- a/misc-utils/rename.1
+++ b/misc-utils/rename.1
@@ -3,7 +3,7 @@
 .\"
 .TH RENAME 1 "1 January 2000" "" "Linux Programmer's Manual"
 .SH NAME
-rename \- Rename files
+rename \- rename files
 .SH SYNOPSIS
 .B rename
 .IR  "from to file" ...
@@ -19,9 +19,9 @@ in their name by
 .TP
 .BR \-V , " \-\-version"
 Display version information and exit.
-.TP
 
-For example, given the files
+.SH EXAMPLES
+Given the files
 .IR foo1 ", ..., " foo9 ", " foo10 ", ..., " foo278 ,
 the commands
 
diff --git a/misc-utils/wipefs.8 b/misc-utils/wipefs.8
index 6867dfc24..ebb64bd4f 100644
--- a/misc-utils/wipefs.8
+++ b/misc-utils/wipefs.8
@@ -13,13 +13,13 @@ wipefs \- wipe a filesystem signature from a device
 .I device
 .SH DESCRIPTION
 .B wipefs
-allows to erase filesystem or raid signatures (magic strings) from the
+can erase filesystem or raid signatures (magic strings) from the specified
 .I device
 to make the filesystem invisible for libblkid.
 .B wipefs
-does not erase the whole filesystem or any other data from the device.
-When used without options -a or -o, it lists all visible filesystems and offsets
-of their signatures.
+does not erase the filesystem itself nor any other data from the device.
+When used without options \fB-a\fR or \fB-o\fR, it lists all visible filesystems
+and the offsets of their signatures.
 .SH OPTIONS
 .IP "\fB\-a, \-\-all\fP"
 Erase all available signatures.
@@ -28,9 +28,9 @@ Print help and exit.
 .IP "\fB\-n, \-\-no\-act\fP"
 Causes everything to be done except for the write() call.
 .IP "\fB\-o, \-\-offset\fP \fIoffset\fP
-Specifies location (in bytes) of the signature which should be erased from the
-device. The offset number may include a "0x" prefix, and then the number will be
-read as a hex value. It is possible to specify multiple -o options.
+Specify the location (in bytes) of the signature which should be erased from the
+device.  The \fIoffset\fR number may include a "0x" prefix; then the number will be
+interpreted as a hex value.  It is possible to specify multiple \fB-o\fR options.
 
 The \fIoffset\fR argument may be followed by binary (2^N) suffixes KiB, MiB,
 GiB, TiB, PiB and EiB (the "iB" is optional, e.g. "K" has the same meaning as