git: e41e2d586618 - stable/13 - dpv: Fix synopsis formatting & sort options

From: Mateusz Piotrowski <0mp_at_FreeBSD.org>
Date: Sun, 07 Nov 2021 17:55:37 UTC
The branch stable/13 has been updated by 0mp (doc, ports committer):

URL: https://cgit.FreeBSD.org/src/commit/?id=e41e2d5866180787697051a5a16bf48e085d3fa2

commit e41e2d5866180787697051a5a16bf48e085d3fa2
Author:     Mateusz Piotrowski <0mp@FreeBSD.org>
AuthorDate: 2021-11-02 07:05:48 +0000
Commit:     Mateusz Piotrowski <0mp@FreeBSD.org>
CommitDate: 2021-11-07 17:50:23 +0000

    dpv: Fix synopsis formatting & sort options
    
    MFC after:      3 days
    
    (cherry picked from commit a85aa7f9d3bfd26f5dc07f70cb7ba281bfc69f20)
---
 usr.bin/dpv/dpv.1 | 97 +++++++++++++++++++++++++++++++------------------------
 usr.bin/dpv/dpv.c | 30 ++++++++---------
 2 files changed, 70 insertions(+), 57 deletions(-)

diff --git a/usr.bin/dpv/dpv.1 b/usr.bin/dpv/dpv.1
index bf97f9555ea8..801389529946 100644
--- a/usr.bin/dpv/dpv.1
+++ b/usr.bin/dpv/dpv.1
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 26, 2016
+.Dd November 2, 2021
 .Dt DPV 1
 .Os
 .Sh NAME
@@ -33,13 +33,26 @@
 .Sh SYNOPSIS
 .Nm
 .Op options
-.Ar [bytes:]label
+.Sm off
+.Op Ar bytes Cm \&:
+.Ar label
+.Sm on
 .Nm
 .Op options
 .Fl m
-.Ar [bytes1:]label1
+.Sm off
+.Op Ar bytes1 Cm \& :
+. Ar label1
+.Sm on
 .Ar path1
-.Op Ar [bytes2:]label2 path2 ...
+.Oo
+.Sm off
+.Op Ar bytes2 Cm \&:
+.Ar label2
+.Sm on
+.Ar path2
+.Ar ...
+.Oc
 .Sh DESCRIPTION
 .Nm
 provides a dialog progress view, allowing a user to see current throughput rate
@@ -95,10 +108,6 @@ When using
 this is displayed inside the window
 .Pq at the top
 followed by a separator line.
-.It Fl d
-Debug mode.
-Print dialog prompt data to standard out and provide additional debugging on
-standard error.
 .It Fl D
 Do not use the default interface of
 .Xr dialog 3 ,
@@ -111,11 +120,15 @@ is taken from the
 environment variable or simply
 .Dq Li dialog
 if unset or NULL.
+.It Fl d
+Debug mode.
+Print dialog prompt data to standard out and provide additional debugging on
+standard error.
 .It Fl h
 Produce a short syntax usage with brief option descriptions and exit.
 Output is produced on standard error.
-.It Fl i Ar format
-Customize the single-file format string used to update the status line.
+.It Fl I Ar format
+Customize the multi-file format string used to update the status line.
 Ignored when using either
 .Ql Fl D
 or
@@ -124,10 +137,10 @@ which lack the ability to display the status line
 .Pq containing bytes/rate/thread information .
 Default value
 is
-.Dq Li %'10lli bytes read @ %'9.1f bytes/sec. .
-This format is used when handling one file.
-.It Fl I Ar format
-Customize the multi-file format string used to update the status line.
+.Dq Li %'10lli bytes read @ %'9.1f bytes/sec. [%i/%i busy/wait] .
+This format is used when handling more than one file.
+.It Fl i Ar format
+Customize the single-file format string used to update the status line.
 Ignored when using either
 .Ql Fl D
 or
@@ -136,24 +149,27 @@ which lack the ability to display the status line
 .Pq containing bytes/rate/thread information .
 Default value
 is
-.Dq Li %'10lli bytes read @ %'9.1f bytes/sec. [%i/%i busy/wait] .
-This format is used when handling more than one file.
+.Dq Li %'10lli bytes read @ %'9.1f bytes/sec. .
+This format is used when handling one file.
 .It Fl k
 Keep tite.
 Prevent visually distracting initialization/exit routines for scripts running
 .Xr dialog 1
 several times.
-.It Fl l
-Line mode.
-Read lines from input instead of bytes.
 .It Fl L Ar size
 Label size.
 If negative, shrink to longest label width.
+.It Fl l
+Line mode.
+Read lines from input instead of bytes.
 .It Fl m
 Multi-input mode.
 Instead of reading bytes from standard input, read from a set of paths
 .Pq one for each label .
 By default, each path is processed sequentially in the order given.
+.It Fl N
+No overrun.
+If enabled, stop reading known-length inputs when input reaches stated length.
 .It Fl n Ar num
 Display at-most
 .Ar num
@@ -162,9 +178,6 @@ If zero, display as many as possible.
 If negative, only display the main progress indicator.
 Default is 0.
 Maximum value is 10.
-.It Fl N
-No overrun.
-If enabled, stop reading known-length inputs when input reaches stated length.
 .It Fl o Ar file
 Output data to
 .Ar file .
@@ -176,10 +189,6 @@ in
 will be replaced with the
 .Ar label
 text.
-.It Fl p Ar text
-Display
-.Ar text
-above the file progress indicator(s).
 .It Fl P Ar size
 Mini-progressbar size.
 If negative, don't display mini-progressbars
@@ -187,6 +196,19 @@ If negative, don't display mini-progressbars
 If zero, auto-adjust based on number of files to read.
 When zero and only one file to read, defaults to -1.
 When zero and more than one file to read, defaults to 17.
+.It Fl p Ar text
+Display
+.Ar text
+above the file progress indicator(s).
+.It Fl T
+Test mode.
+Simulate reading a number of bytes, divided evenly across the number of files,
+while stepping through each percent value of each file to process.
+Appends
+.Dq Li [TEST MODE]
+to the status line
+.Pq to override, use Ql Fl u Ar format .
+No data is actually read.
 .It Fl t Ar title
 Display
 .Ar title
@@ -201,15 +223,6 @@ and
 .Ar title
 are effectively switched
 .Pq see BUGS section below .
-.It Fl T
-Test mode.
-Simulate reading a number of bytes, divided evenly across the number of files,
-while stepping through each percent value of each file to process.
-Appends
-.Dq Li [TEST MODE]
-to the status line
-.Pq to override, use Ql Fl u Ar format .
-No data is actually read.
 .It Fl U Ar num
 Update status line
 .Ar num
@@ -237,6 +250,13 @@ and
 to bump the dialog width.
 Prompts wider than the maximum width will wrap
 .Pq unless using Xr Xdialog 1 ; see BUGS section below .
+.It Fl X
+Enable X11 mode by using
+.Xr Xdialog 1
+instead of
+.Xr dialog 1
+or
+.Xr dialog 3 .
 .It Fl x Ar cmd
 Execute
 .Ar cmd
@@ -259,13 +279,6 @@ in
 will be replaced with the
 .Ar label
 text.
-.It Fl X
-Enable X11 mode by using
-.Xr Xdialog 1
-instead of
-.Xr dialog 1
-or
-.Xr dialog 3 .
 .El
 .Sh ENVIRONMENT
 The following environment variables are referenced by
diff --git a/usr.bin/dpv/dpv.c b/usr.bin/dpv/dpv.c
index 440b5ab6de0f..725b24f6bbe9 100644
--- a/usr.bin/dpv/dpv.c
+++ b/usr.bin/dpv/dpv.c
@@ -496,50 +496,50 @@ usage(void)
 	if (debug) /* No need for usage */
 		exit(EXIT_FAILURE);
 
-	fprintf(stderr, "Usage: %s [options] bytes:label\n", pgm);
-	fprintf(stderr, "       %s [options] -m bytes1:label1 path1 "
-	    "[bytes2:label2 path2 ...]\n", pgm);
+	fprintf(stderr, "Usage: %s [options] [bytes:]label\n", pgm);
+	fprintf(stderr, "       %s [options] -m [bytes1:]label1 path1 "
+	    "[[bytes2:]label2 path2 ...]\n", pgm);
 	fprintf(stderr, "OPTIONS:\n");
 #define OPTFMT "\t%-14s %s\n"
 	fprintf(stderr, OPTFMT, "-a text",
 	    "Append text. Displayed below file progress indicators.");
 	fprintf(stderr, OPTFMT, "-b backtitle",
 	    "String to be displayed on the backdrop, at top-left.");
-	fprintf(stderr, OPTFMT, "-d",
-	    "Debug. Write to standard output instead of dialog.");
 	fprintf(stderr, OPTFMT, "-D",
 	    "Use dialog(1) instead of dialog(3) [default].");
+	fprintf(stderr, OPTFMT, "-d",
+	    "Debug. Write to standard output instead of dialog.");
 	fprintf(stderr, OPTFMT, "-h",
 	    "Produce this output on standard error and exit.");
-	fprintf(stderr, OPTFMT, "-i format",
-	    "Customize status line format. See fdpv(1) for details.");
 	fprintf(stderr, OPTFMT, "-I format",
 	    "Customize status line format. See fdpv(1) for details.");
+	fprintf(stderr, OPTFMT, "-i format",
+	    "Customize status line format. See fdpv(1) for details.");
 	fprintf(stderr, OPTFMT, "-L size",
 	    "Label size. Must be a number greater than 0, or -1.");
 	fprintf(stderr, OPTFMT, "-m",
 	    "Enable processing of multiple file argiments.");
-	fprintf(stderr, OPTFMT, "-n num",
-	    "Display at-most num files per screen. Default is -1.");
 	fprintf(stderr, OPTFMT, "-N",
 	    "No overrun. Stop reading input at stated length, if any.");
+	fprintf(stderr, OPTFMT, "-n num",
+	    "Display at-most num files per screen. Default is -1.");
 	fprintf(stderr, OPTFMT, "-o file",
 	    "Output data to file. First %s replaced with label text.");
-	fprintf(stderr, OPTFMT, "-p text",
-	    "Prefix text. Displayed above file progress indicators.");
 	fprintf(stderr, OPTFMT, "-P size",
 	    "Mini-progressbar size. Must be a number greater than 3.");
-	fprintf(stderr, OPTFMT, "-t title",
-	    "Title string to be displayed at top of dialog(1) box.");
+	fprintf(stderr, OPTFMT, "-p text",
+	    "Prefix text. Displayed above file progress indicators.");
 	fprintf(stderr, OPTFMT, "-T",
 	    "Test mode. Don't actually read any data, but fake it.");
+	fprintf(stderr, OPTFMT, "-t title",
+	    "Title string to be displayed at top of dialog(1) box.");
 	fprintf(stderr, OPTFMT, "-U num",
 	    "Update status line num times per-second. Default is 2.");
 	fprintf(stderr, OPTFMT, "-w",
 	    "Wide. Width of `-p' and `-a' text bump dialog(1) width.");
-	fprintf(stderr, OPTFMT, "-x cmd",
-	    "Send data to executed cmd. First %s replaced with label.");
 	fprintf(stderr, OPTFMT, "-X",
 	    "X11. Use Xdialog(1) instead of dialog(1).");
+	fprintf(stderr, OPTFMT, "-x cmd",
+	    "Send data to executed cmd. First %s replaced with label.");
 	exit(EXIT_FAILURE);
 }