losetup.8: Reorder options documentation

Reorder options to match onboard help and group functionally.
Include some missing optional arguments.

[kzak@redhat.com: - don't include available columns in man page,
                  - add comments to the usage()
		  - fix order in usage()
		  - fix typo in usage()]

Signed-off-by: Karel Zak <kzak@redhat.com>

diff --git a/sys-utils/losetup.8 b/sys-utils/losetup.8
index 0853d1a4150b4c7e6d765aa7b2aee72934dc29a0..60e9ff04ff3d8f1e33da6d7a1de14cb420984770 100644 (file)
--- a/sys-utils/losetup.8
+++ b/sys-utils/losetup.8
@@ -65,13 +65,13 @@ to detach loop devices, and to query the status of a loop device.  If only the
 \fIloopdev\fP argument is given, the status of the corresponding loop
 device is shown.  If no option is given, all loop devices are shown.
 .sp
-Note that the old output format (i.e. \fBlosetup -a\fR) with comma-delimited
+Note that the old output format (i.e., \fBlosetup -a\fR) with comma-delimited
 strings is deprecated in favour of the \fB--list\fR output format.
 .sp
 It's possible to create more independent loop devices for the same backing
 file.
 .B This setup may be dangerous, can cause data loss, corruption and overwrites.
-Use \fB\-\-nooverlap\fR to avoid this problem.
+Use \fB\-\-nooverlap\fR with \fB\-\-find\fR during setup to avoid this problem.
 
 .SH OPTIONS
 The \fIsize\fR and \fIoffset\fR
@@ -86,26 +86,18 @@ Show the status of all loop devices.  Note that not all information is accessibl
 for non-root users.  See also \fB\-\-list\fR.  The old output format (as printed
 without \fB--list)\fR is deprecated.
 .TP
-.BR \-c , " \-\-set\-capacity " \fIloopdev
-Force the loop driver to reread the size of the file associated with the
-specified loop device.
-.TP
 .BR \-d , " \-\-detach " \fIloopdev\fR...
 Detach the file or device associated with the specified loop device(s).
 .TP
 .BR \-D , " \-\-detach\-all"
 Detach all associated loop devices.
 .TP
-.BR \-\-direct\-io [ =on | off ]
-Enable or disable direct I/O for the backing file.  The optional argument
-can be either \fBon\fR or \fBoff\fR.  If the argument is omitted, it defaults
-to \fBon\fR.
-.TP
-.BR \-f , " \-\-find"
-Find the first unused loop device.  If a
-.I file
-argument is present, use the found device as loop device.
-Otherwise, just print its name.
+.BR \-f , " \-\-find " "\fR[\fIfile\fR]"
+Find the first unused loop device.  If a \fIfile\fR argument is present, use
+the found device as loop device.  Otherwise, just print its name.
+.IP "\fB\-\-show\fP"
+Display the name of the assigned loop device if the \fB\-f\fP option and a
+\fIfile\fP argument are present.
 .TP
 .BR \-L , " \-\-nooverlap"
 Check for conflicts between loop devices to avoid situation when the same
@@ -113,47 +105,50 @@ backing file is shared between more loop devices. If the file is already used
 by another device then re-use the device rather than a new one. The option
 makes sense only with \fB\-\-find\fP.
 .TP
-.BR \-j , " \-\-associated " \fIfile
-Show the status of all loop devices associated with the given
-.IR file .
-.TP
-.BR \-J , " \-\-json"
-Use JSON format for \fB\-\-list\fP output.
-.TP
-.BR \-l , " \-\-list"
-If a loop device or the \fB-a\fR option is specified, print the default columns
-for either the specified loop device or all loop devices; the default is to
-print info about all devices.  See also \fB\-\-output\fP, \fB\-\-noheadings\fP
-\fB\-\-json\fP and \fB\-\-raw\fP.
-.TP
-.BR \-n , " \-\-noheadings"
-Don't print headings for \fB\-\-list\fP output format.
+.BR \-j , " \-\-associated " \fIfile\fR " \fR[\fB\-o \fIoffset\fR]"
+Show the status of all loop devices associated with the given \fIfile\fR.
 .TP
 .BR \-o , " \-\-offset " \fIoffset
 The data start is moved \fIoffset\fP bytes into the specified file or device.
+.IP "\fB\-\-sizelimit \fIsize\fP"
+The data end is set to no more than \fIsize\fP bytes after the data start.
 .TP
-.BR \-O , " \-\-output " \fIcolumns
-Specify the columns that are to be printed for the \fB\-\-list\fP output.
+.BR \-c , " \-\-set\-capacity " \fIloopdev
+Force the loop driver to reread the size of the file associated with the
+specified loop device.
 .TP
 .BR \-P , " \-\-partscan"
 Force the kernel to scan the partition table on a newly created loop device.
-.IP "\fB\-\-raw\fP"
-Use the raw \fB\-\-list\fP output format.
 .TP
 .BR \-r , " \-\-read\-only"
 Set up a read-only loop device.
-.IP "\fB\-\-sizelimit \fIsize\fP"
-The data end is set to no more than \fIsize\fP bytes after the data start.
-.IP "\fB\-\-show\fP"
-Display the name of the assigned loop device if the
-.B \-f
-option and a
-.I file
-argument are present.
+.TP
+.BR \-\-direct\-io [ =on | off ]
+Enable or disable direct I/O for the backing file.  The optional argument
+can be either \fBon\fR or \fBoff\fR.  If the argument is omitted, it defaults
+to \fBon\fR.
 .TP
 .BR \-v , " \-\-verbose"
 Verbose mode.
 .TP
+.BR \-l , " \-\-list"
+If a loop device or the \fB-a\fR option is specified, print the default columns
+for either the specified loop device or all loop devices; the default is to
+print info about all devices.  See also \fB\-\-output\fP, \fB\-\-noheadings\fP,
+\fB\-\-raw\fP, and \fB\-\-json\fP.
+.TP
+.BR \-O , " \-\-output " \fIcolumn\fR[,\fIcolumn\fR]...
+Specify the columns that are to be printed for the \fB\-\-list\fP output.
+Use \fB\-\-help\fR to get a list of all supported columns.
+.TP
+.BR \-n , " \-\-noheadings"
+Don't print headings for \fB\-\-list\fP output format.
+.IP "\fB\-\-raw\fP"
+Use the raw \fB\-\-list\fP output format.
+.TP
+.BR \-J , " \-\-json"
+Use JSON format for \fB\-\-list\fP output.
+.TP
 .BR \-V , " \-\-version"
 Display version information and exit.
 .TP

diff --git a/sys-utils/losetup.c b/sys-utils/losetup.c
index 5f599ead513223f2c20a18b9b275d91b6d512cf0..2218d3b437251888ca1c1139c3ce39b81bdb696f 100644 (file)
--- a/sys-utils/losetup.c
+++ b/sys-utils/losetup.c
@@ -385,6 +385,7 @@ static void usage(FILE *out)
        fputs(USAGE_SEPARATOR, out);
        fputs(_("Set up and control loop devices.\n"), out);
 
+       /* commands */
        fputs(USAGE_OPTIONS, out);
        fputs(_(" -a, --all                     list all used devices\n"), out);
        fputs(_(" -d, --detach <loopdev>...     detach one or more devices\n"), out);
@@ -394,8 +395,8 @@ static void usage(FILE *out)
        fputs(_(" -j, --associated <file>       list all devices associated with <file>\n"), out);
        fputs(_(" -L, --nooverlap               avoid possible conflict between devices\n"), out);
 
+       /* commands options */
        fputs(USAGE_SEPARATOR, out);
-
        fputs(_(" -o, --offset <num>            start at offset <num> into file\n"), out);
        fputs(_("     --sizelimit <num>         device is limited to <num> bytes of the file\n"), out);
        fputs(_(" -P, --partscan                create a partitioned loop device\n"), out);
@@ -404,19 +405,19 @@ static void usage(FILE *out)
        fputs(_("     --show                    print device name after setup (with -f)\n"), out);
        fputs(_(" -v, --verbose                 verbose mode\n"), out);
 
+       /* output options */
        fputs(USAGE_SEPARATOR, out);
-
+       fputs(_(" -J, --json                    use JSON --list output format\n"), out);
        fputs(_(" -l, --list                    list info about all or specified (default)\n"), out);
-       fputs(_(" -O, --output <cols>           specify columns to output for --list\n"), out);
        fputs(_(" -n, --noheadings              don't print headings for --list output\n"), out);
+       fputs(_(" -O, --output <cols>           specify columns to output for --list\n"), out);
        fputs(_("     --raw                     use raw --list output format\n"), out);
-       fputs(_(" -J, --json                    use JSON --list output format\n"), out);
 
        fputs(USAGE_SEPARATOR, out);
        fputs(USAGE_HELP, out);
        fputs(USAGE_VERSION, out);
 
-       fputs(_("\nAvailable --list columns:\n"), out);
+       fputs(_("\nAvailable --output columns:\n"), out);
        for (i = 0; i < ARRAY_SIZE(infos); i++)
                fprintf(out, " %12s  %s\n", infos[i].name, _(infos[i].help));