docs: improve wording and formatting of blkid man page

Furthermore, explain the device argument right at the beginning,
since it is not an option, and alphabetize -k.

Signed-off-by: Benno Schulenberg <bensberg@justemail.net>

1 files changed, 67 insertions, 70 deletions

diff --git a/misc-utils/blkid.8 b/misc-utils/blkid.8
index 94acdf16e..0d5f4235c 100644
--- a/misc-utils/blkid.8
+++ b/misc-utils/blkid.8
@@ -5,15 +5,14 @@
 .\" 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 2011" "util-linux" "System Administration"
+.TH BLKID 8 "March 2013" "util-linux" "System Administration"
 .SH NAME
 blkid \- locate/print block device attributes
 .SH SYNOPSIS
 .B blkid
-.RB \-L
-.IR label " | "
-.RB \-U
-.IR uuid
+.BI \-L " label"
+|
+.BI \-U " uuid"
 
 .B blkid
 .RB [ \-dghlv ]
@@ -21,22 +20,21 @@ blkid \- locate/print block device attributes
 .IR file ]
 .RB [ \-o
 .IR format ]
-.in +6
 .RB [ \-s
 .IR tag ]
+.in +6
 .RB [ \-t
 .IR NAME=value ]
-[\fIdevice\fR ...]
+.RI [ device " ...]"
 .in -6
 
 .B blkid
-.RB -p
-.RB [ \-O
+.BR -p " [" \-O
 .IR offset ]
-.RB [ \-S
-.IR size ]
 .RB [ \-o
 .IR format ]
+.RB [ \-S
+.IR size ]
 .RB [ \-s
 .IR tag ]
 .in +9
@@ -44,16 +42,15 @@ blkid \- locate/print block device attributes
 .IR list ]
 .RB [ \-u
 .IR list ]
-.IR device " ... "
+.IR device " ..."
 .in -9
 
 .B blkid
-.RB -i
-.RB [ \-o
+.BR -i " [" \-o
 .IR format ]
 .RB [ \-s
 .IR tag ]
-.IR device " ... "
+.IR device " ..."
 
 .SH DESCRIPTION
 The
@@ -61,15 +58,25 @@ The
 program is the command-line interface to working with the
 .BR libblkid (3)
 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)
+that a block device holds, and also the attributes (tokens, NAME=value pairs)
 from the content metadata (e.g. LABEL or UUID fields).
 .PP
+When
+.I device
+is specified, tokens from only this device are displayed.
+It is possible to specify multiple
+.I device
+arguments on the command line.
+If none is given, all devices which appear in
+.I /proc/partitions
+are shown, if they are recognized.
+.PP
 Note that
 .B blkid
 reads information directly from devices and for non-root users
-it returns cached unverified information. It's better to use
+it returns cached unverified information.  It is better to use
 .B lsblk --fs
-to get user-friendly overview about filesystems and devices. 
+to get a user-friendly overview of filesystems and devices.
 .BR lsblk (8)
 is also easy to use in scripts.
 .B blkid
@@ -81,22 +88,22 @@ specific NAME=value pair, or displaying NAME=value pairs for one or
 more specified devices.
 .SH OPTIONS
 The \fIsize\fR and \fIoffset\fR arguments may be followed by the multiplicative
-suffixes KiB=1024, MiB=1024*1024, and so on for GiB, TiB, PiB, EiB, ZiB and YiB
-(the "iB" is optional, e.g. "K" has the same meaning as "KiB") or the suffixes
-KB=1000, MB=1000*1000, and so on for GB, TB, PB, EB, ZB and YB.
+suffixes like KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB
+(the "iB" is optional, e.g. "K" has the same meaning as "KiB"), or the suffixes
+KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.
 .TP
 .BI \-c " cachefile"
 Read from
 .I cachefile
-instead of reading from the default cache file (see CONFIGURATION FILE section
+instead of reading from the default cache file (see the CONFIGURATION FILE section
 for more details).  If you want to start with a clean cache (i.e. don't report
 devices previously scanned but not necessarily available at this time), specify
 .IR /dev/null .
 .TP
 .B \-d
-Don't encode non-printing characters. The non-printing characters are encoded
-by ^ and M- notation by default. Note that \fB-o udev\fR output format uses
-a different encoding and this encoding cannot be disabled.
+Don't encode non-printing characters.  The non-printing characters are encoded
+by ^ and M- notation by default.  Note that the \fB-o udev\fR output format uses
+a different encoding which cannot be disabled.
 .TP
 .B \-g
 Perform a garbage collection pass on the blkid cache to remove
@@ -106,36 +113,37 @@ 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
+Display information about I/O Limits (aka I/O topology).  The 'export' output format is
 automatically enabled.  This option can be used together with the \fB-p\fR option.
 .TP
+.B \-k
+List all known filesystems and RAIDs and exit.
+.TP
 .B \-l
-Look up only one device that matches the search parameter specified with \fB-t\fR
+Look up only one device that matches the search parameter specified with the \fB-t\fR
 option.  If there are multiple devices that match the specified search
 parameter, then the device with the highest priority is returned, and/or
 the first device found at a given priority.  Device types in order of
-decreasing priority are Device Mapper, EVMS, LVM, MD, and finally regular
+decreasing priority are: Device Mapper, EVMS, LVM, MD, and finally regular
 block devices.  If this option is not specified,
 .B blkid
 will print all of the devices that match the search parameter.
 .TP
-.B \-k
-List all known filesystems and RAIDs and exit.
-.TP
 .BI \-L " label"
-Look up the device that uses this filesystem \fIlabel\fR (equal to: -l -o device -t
-LABEL=<label>).  This lookup method is able to reliably use /dev/disk/by-label
+Look up the device that uses this filesystem \fIlabel\fR; this is equal to
+.BR "-l -o device -t LABEL=\fIlabel\fR" .
+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
 .BR blkid (8)
-from e2fsprogs use the \fB-L\fR option as a
-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.
+from e2fsprogs uses the \fB-L\fR option as a
+synonym for \fB-o list\fR.  For better portability, use \fB-l -o device
+-t LABEL=\fIlabel\fR and \fB-o list\fR in your scripts rather than the \fB-L\fR option.
 .TP
-.BI \-n " list "
+.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.
@@ -151,10 +159,8 @@ probes for all supported formats except minix filesystems.
 This option is only useful together with \fB-p\fR.
 .TP
 .BI \-o " format"
-Display
-.BR blkid 's
-output using the specified format. Note that the variables order and
-devices order is variable. See also \fB-s\fR. The
+Use the specified output format.  Note that the order of variables and
+devices is not fixed.  See also option \fB-s\fR.  The
 .I format
 parameter may be:
 .RS
@@ -167,13 +173,14 @@ print the value of the tags
 .TP
 .B list
 print the devices in a user-friendly format; this output format is unsupported
-for low-level probing (\fB-p\fR or \fB-i\fR). This output format is \fBDEPRECATED\fR
-in favour of
+for low-level probing (\fB-p\fR or \fB-i\fR).
+
+This output format is \fBDEPRECATED\fR in favour of the
 .BR lsblk (8)
 command.
 .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 the \fB-L\fR
 and \fB-U\fR options
 .TP
 .B udev
@@ -182,7 +189,7 @@ prefixed by ID_FS_ or ID_PART_ prefixes
 
 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. This output format is \fBDEPRECATED\fR.
+partitions.  This output format is \fBDEPRECATED\fR.
 .TP
 .B export
 print key=value pairs for easy import into the environment; this output format
@@ -194,7 +201,7 @@ 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).
+Switch to low-level superblock probing mode (bypassing the cache).
 
 Note that low-level probing also returns information about partition table type
 (PTTYPE tag) and partitions (PART_ENTRY_* tags).
@@ -211,9 +218,9 @@ In order to just refresh the cache without showing any tokens, use
 with no other options.
 .TP
 .BI \-S " size"
-Overwrite device/file size (only useful with \fB-p\fR).
+Override the size of device/file (only useful with \fB-p\fR).
 .TP
-.BI \-t " NAME" = "value"
+.BI \-t " NAME" = value
 Search for block devices with tokens named
 .I NAME
 that have the value
@@ -229,7 +236,7 @@ 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
-.BI \-u " list "
+.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:
@@ -243,20 +250,11 @@ probes for all filesystem and other (e.g. swap) formats, and
 probes for all supported formats except RAIDs.
 This option is only useful together with \fB-p\fR.
 .TP
-.BI \-U " uuid "
+.BI \-U " uuid"
 Look up the device that uses this filesystem \fIuuid\fR.  For more details see the \fB-L\fR option.
 .TP
 .B \-v
 Display version number and exit.
-.TP
-.I device
-Display tokens from only the specified device.  It is possible to
-give multiple
-.I device
-options on the command line.  If none is given, all devices which
-appear in
-.I /proc/partitions
-are shown, if they are recognized.
 .SH "RETURN CODE"
 If the specified token was found, or if any tags were shown from (specified)
 devices, 0 is returned.
@@ -266,7 +264,7 @@ 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 an ambivalent low-level probing result was detected, an exit code of 8 is
 returned.
 .SH CONFIGURATION FILE
 The standard location of the
@@ -277,20 +275,20 @@ The following options control the libblkid library:
 .I SEND_UEVENT=<yes|not>
 Sends uevent when
 .I /dev/disk/by-{label,uuid,partuuid,partlabel}/
-symlink does not match with LABEL, UUID, PARTUUID or PARTLABEL on the device. Default is "yes".
+symlink does not match with LABEL, UUID, PARTUUID or PARTLABEL on the device.  Default is "yes".
 .TP
 .I CACHE_FILE=<path>
-Overrides the standard location of the cache file. This setting can be
-overridden by the environment variable BLKID_FILE. Default is
-.I /run/blkid/blkid.tab
+Overrides the standard location of the cache file.  This setting can be
+overridden by the environment variable BLKID_FILE.  Default is
+.IR /run/blkid/blkid.tab ,
 or
 .I /etc/blkid.tab
-on systems without /run directory
+on systems without a /run directory.
 .TP
 .I EVALUATE=<methods>
-Defines LABEL and UUID evaluation method(s). Currently, the libblkid library
-supports "udev" and "scan" methods. More than one methods may be specified in
-a comma separated list. Default is "udev,scan". The "udev" method uses udev
+Defines LABEL and UUID evaluation method(s).  Currently, the libblkid library
+supports the "udev" and "scan" methods.  More than one method may be specified in
+a comma-separated list.  Default is "udev,scan".  The "udev" method uses udev
 .I /dev/disk/by-*
 symlinks and the "scan" method scans all block devices from the
 .I /proc/partitions
@@ -300,8 +298,7 @@ file.
 was written by Andreas Dilger for libblkid and improved by Theodore Ts'o
 and Karel Zak.
 .SH ENVIRONMENT
-.IP LIBBLKID_DEBUG=0xffff
-enables debug output.
+.IP "Setting LIBBLKID_DEBUG=0xffff enables debug output."
 .SH AVAILABILITY
 The blkid command is part of the util-linux package and is available from
 ftp://ftp.kernel.org/pub/linux/utils/util-linux/.