Improve help and manpage.

Add some details on the verbosity and options -T and -A.
These two options are not very clear to me.

Signed-off-by: Stéphane Aulery <lkppo@free.fr>
Signed-off-by: Alan Coopersmith <alan.coopersmith@oracle.com>

2 files changed, 84 insertions, 38 deletions

diff --git a/man/xscope.man b/man/xscope.man
index 0c1e177..a7ff06c 100644
--- a/man/xscope.man
+++ b/man/xscope.man
@@ -3,10 +3,23 @@
 xscope - X Window Protocol Viewer
 .SH SYNOPSIS
 .B xscope
-[\fB-i\fP\fI<in-port>\fP] [\fB-o\fP\fI<out-port>\fP]
-[\fB-h\fP\fI<server-host>\fP] [\fB-d\fP\fI<display-number>\fP]
-[\fB-q\fP] [\fB-v\fP\fI<n>\fP] [\fB-r\fP]
-[\fB-D\fP\fI<debug-level>\fP] [\fB-I\fP] [\fB-S\fP\fI<n>\fP] [\fB-V\fP] [\fB-t\fP]
+[\fB-i\fP\fI<in-port>\fP]
+[\fB-o\fP\fI<out-port>\fP]
+[\fB-h\fP\fI<server-host>\fP]
+[\fB-d\fP\fI<display-number>\fP]
+[\fB-f\fP\fI<filename>\fP]
+[\fB-I\fP]
+[\fB-S\fP\fI<n>\fP]
+[\fB-T\fP]
+[\fB-A\fP]
+[\fB-r\fP]
+[\fB-a\fP\fI<level>\fP]
+[\fB-n\fP\fI<level>\fP]
+[\fB-D\fP\fI<level>\fP]
+[\fB-q\fP]
+[\fB-v\fP\fI<level>\fP]
+[\fB-V\fP]
+[\fB-t\fP]
 .SH DESCRIPTION
 .I Xscope
 sits in-between an X11 client and an X11 server and prints the contents
@@ -37,7 +50,7 @@ component of the DISPLAY is used to select \fIxscope\fP or X11.
 .SH ARGUMENTS
 .PP
 .TP 10
-.BI \-i <input-port>
+.BI \-i <in-port>
 Specify the port that \fIxscope\fP will use to take requests from clients
 (defaults to 1).
 For X11, this port is automatically biased by 6000.
@@ -53,7 +66,7 @@ For X11, this port is automatically biased by 6000.
 Determines the host that  \fIxscope\fP will use to find its X11 server.
 .PP
 .TP 10
-.BI \-d <display>
+.BI \-d <display-number>
 Defines the display number.  The display number is added to the input
 and output port to give the actual ports which are used by  \fIxscope\fP.
 .PP
@@ -63,36 +76,64 @@ Instead of decoding a live session, reads previously captured raw data
 from a file to decode.
 .PP
 .TP 10
-.B \-q
-Quiet output mode.  Gives only the names of requests, replies, errors, and
-events, but does not indicate contents.
+.BI -I
+Enter interactive mode at startup.
 .PP
 .TP 10
-.BI \-v <print-level>
-Determines the level of printing which \fIxscope\fP will provide.  The
-print-level can be 0 (same as quiet mode), 1, 2, 3, 4.  The larger
-numbers give more and more output.  For example, a successful setup
-returns a string which is the name of the vendor of the X11 server.
-At level 1, the explicit field giving the length of the string is
-suppressed since it can be inferred from the string.  At level 2 and
-above the length is explicitly printed.
+.BI -S <n>
+Toggle output on or off when SIGUSR1 is received.  If \fIn\fP is 0,
+the initial state is off.  If \fIn\fP is 1, the initial state is on.
+.PP
+.TP 10
+.BI -T
+Transpose some output with an offset of 0x20.
+.PP
+.TP 10
+.BI -A
+Enables audio.
 .PP
 .TP 10
 .B -r
 Print only raw data without decoding it.
 .PP
 .TP 10
-.BI -D <debug-level>
-Print debugging information at the specified level.
+.BI -a <level>
+Audio verbose output level.
 .PP
 .TP 10
-.BI -I
-Enter interactive mode at startup.
+.BI -n <level>
+Nas verbose output level (1 to 4, 1 by default).
 .PP
 .TP 10
-.BI -S <n>
-Toggle output on or off when SIGUSR1 is received.  If \fIn\fP is 0,
-the initial state is off.  If \fIn\fP is 1, the initial state is on.
+.BI -D <level>
+Print debugging information at the specified level (255 by default) :
+.IP
+\- 2, Trace each procedure entry
+.IP
+\- 4, I/O, connections
+.IP
+\- 8, Scope internals
+.IP
+\- 16, Message protocol
+.IP
+\- 32 to 64, Was malloc, now unused
+.IP
+\- 128 to 256, Really low level
+.PP
+.TP 10
+.B \-q
+Quiet output mode.  Gives only the names of requests, replies, errors, and
+events, but does not indicate contents.
+.PP
+.TP 10
+.BI \-v <level>
+Determines the level of printing which \fIxscope\fP will provide.  The
+level can be 0 (same as quiet mode), 1 (default), 2, 3, 4, 5.  The larger
+numbers give more and more output.  For example, a successful setup
+returns a string which is the name of the vendor of the X11 server.
+At level 1, the explicit field giving the length of the string is
+suppressed since it can be inferred from the string.  At level 2 and
+above the length is explicitly printed.
 .PP
 .TP 10
 .BI -V
diff --git a/scope.c b/scope.c
index 1919569..f87e2dc 100644
--- a/scope.c
+++ b/scope.c
@@ -658,20 +658,25 @@ static void _X_NORETURN
 Usage(void)
 {
     fprintf(stderr,
-            "Usage: xscope\n"
-            "              [-h<server-host>]\n"
-            "              [-i<in-port>]\n"
-            "              [-o<out-port>]\n"
-            "              [-d<display-number>]\n"
-            "              [-v<n>]  -- verbose output\n"
-            "              [-r]  -- raw output\n"
-            "              [-a<n>]  -- audio verbose output\n"
-            "              [-q]  -- quiet output\n"
-            "              [-D<debug-level>]\n"
-            "              [-I]  -- start in interactive mode\n"
-            "              [-S<n>] -- start/stop on SIGUSR1\n"
-            "              [-V]  -- output version information and exit\n"
-            "              [-t]  -- terminate when all clients close\n");
+            "Usage: xscope [options]\n"
+            "Options:\n"
+            "  -i<in-port>         Port used to take requests from clients\n"
+            "  -o<out-port>        Port used to connect to X11\n"
+            "  -h<server-host>     Determines the host used to find its X11 server\n"
+            "  -d<display-number>  Defines the display number\n"
+            "  -f<filename>        Reads previously captured raw data from a file\n"
+            "  -I                  Start in interactive mode\n"
+            "  -S<n>               Start/stop on SIGUSR1 (0/1)\n"
+            "  -T                  Transposes some output with an offset of 0x20\n"
+            "  -A                  Enables audio\n"
+            "  -r                  Raw output\n"
+            "  -a<level>           Audio verbose output\n"
+            "  -n<level>           Nas verbose output\n"
+            "  -D<level>           Debug level (default = 255)\n"
+            "  -q                  Quiet output\n"
+            "  -v<level>           Verbose output (0 to 5, 0=quiet)\n"
+            "  -V                  Output version information and exit\n"
+            "  -t                  Terminate when all clients close\n");
     exit(1);
 }