iowatcher: Update usage info and improve man page

Bring the man page and usage string up-to-date with the new -p behaviour
and improve the formatting and content of the man page.

Signed-off-by: Andrew Price <anprice@redhat.com>

2 files changed, 86 insertions, 50 deletions

diff --git a/iowatcher/iowatcher.1 b/iowatcher/iowatcher.1
index d9b77b8..3044abf 100644
--- a/iowatcher/iowatcher.1
+++ b/iowatcher/iowatcher.1
@@ -1,4 +1,4 @@
-.TH iowatcher 1
+.TH iowatcher "1" "April 2014" "iowatcher" "User Commands"
 
 .SH NAME
 iowatcher - Create visualizations from blktrace results
@@ -15,17 +15,17 @@ iowatcher graphs the results of a blktrace run.  It can graph the result of an e
 \fB--help\fP
 Print a brief usage summary.
 .TP
-\fB-d, --device\fP <device>
+\fB-d, --device\fP \fIdevice\fP
 Controls which device you are tracing.  You can only trace one device at a time for now.  It is sent directly to blktrace, and only needed when you are making a new trace.
 .TP
-\fB-D, --blktrace-destination\fP <destination>
+\fB-D, --blktrace-destination\fP \fIdestination\fP
 Destination for blktrace.
 .TP
 \fB-p, --prog\fP
 Run a program while blktrace is run. The program and its arguments must be
 specified after all other options.  Note that this option previously required
-the program to be given as a single argument but it now flags that iowatcher
-should expect extra arguments to be run during the trace.
+the program to be given as a single argument but it now tells \fBiowatcher\fP
+to expect extra arguments which it should be run during the trace.
 .TP
 \fB--\fP
 End option parsing. If \fB--prog\fP is specified, everything after \fB--\fP is
@@ -35,92 +35,128 @@ be mistaken for an option.
 \fB-K, --keep-movie-svgs\fP
 Keep the SVG files generated for movie mode.
 .TP
-\fB-t, --trace\fP <file|directory>
-Controls the name of the blktrace file.  iowatcher uses a dump from blkparse, so -t tries to guess the name of the corresponding per CPU blktrace data files if the dump file doesn't already exist.
-If you want more than one trace in a given graph, you can specify -t more than once.
-If a directory is specified, iowatcher will use the name of the directory as the base name of the dump file and all trace files found inside the directory will be processed.
-.TP
-\fB-l, --label\fP <label>
-Sets a label in the graph for a trace file.  The labels are added in the same order the trace files are added.
-.TP
-\fB-m, --movie\fP [spindle|rect]
-Create a movie.  The file format depends on the extension used in the -o filename.* option.  If you specify an .ogv or .ogg extension, the result will be Ogg Theora video, if png2theora is available.
-If you use an .mp4 extension, the result will be an mp4 video if ffmpeg is available.  You can use any other extension, but the end result will be an mp4.
-You can use --movie=spindle or --movie=rect, which changes the style of the IO mapping.
-.TP
-\fB-T, --title\fP <title>
-Set a title to be placed at the top of the graph.
-.TP
-\fB-o, --output\fP <file>
-Output filename (default: trace.svg).
-.TP
-\fB-r, --rolling\fP <seconds>
-Control the duration for the rolling average.  iowatcher tries to smooth out bumpy graphs by averaging the current second with seconds from the past.  Larger numbers here give you flatter graphs.
-.TP
-\fB-h, --height\fP <height>
+\fB-t, --trace\fP \fIpath\fP
+Specify the name of the file or directory in which blktrace output is located.
+\fBiowatcher\fP uses a dump from blkparse, so this option tries to guess the
+name of the corresponding per-CPU blktrace data files if the dump file doesn't
+already exist.  To add multiple traces to a given graph, you can specify
+\fB--trace\fP more than once.  If \fIpath\fP is a directory, \fBiowatcher\fP
+will use the name of the directory as the base name of the dump file and all
+trace files found inside the directory will be processed.
+.TP
+\fB-l, --label\fP \fIlabel\fP
+Sets a label in the graph for a trace file.  The labels are added in the same order as the trace files.
+.TP
+\fB-m, --movie\fP \fI[style]\fP
+Create a movie.  The file format depends on the extension used in the \fB-o\fP
+\fIfile\fP option.  If you specify an .ogv or .ogg extension, the result will
+be Ogg Theora video, if png2theora is available.  If you use an .mp4 extension,
+the result will be an mp4 video if ffmpeg is available.  You can use any other
+extension, but the end result will be an mp4.  The accepted \fIstyle\fP values
+are \fBspindle\fP for a circular disc-like effect (default) or \fBrect\fP for a
+rectangular graph style.
+.TP
+\fB-T, --title\fP \fItitle\fP
+Set a \fItitle\fP to be placed at the top of the graph.
+.TP
+\fB-o, --output\fP \fIfile\fP
+Output filename for the SVG image or video. The video format used will depend
+on the file name extension. See \fB--movie\fP for details.
+.TP
+\fB-r, --rolling\fP \fIseconds\fP
+Control the duration for the rolling average.  \fBiowatcher\fP tries to smooth out bumpy graphs by averaging the current second with seconds from the past.  Larger numbers here give you flatter graphs.
+.TP
+\fB-h, --height\fP \fIheight\fP
 Set the height of each graph
 .TP
-\fB-w, --width\fP <width>
+\fB-w, --width\fP \fIwidth\fP
 Set the width of each graph
 .TP
-\fB-c, --columns\fP <columns>
-Numbers of columns in graph output
+\fB-c, --columns\fP \fIcolumns\fP
+Number of columns in graph output
 .TP
-\fB-x, --xzoom\fP <min:max>
-Limit processed time range to min:max
+\fB-x, --xzoom\fP \fImin:max\fP
+Limit processed time range to \fImin:max\fP.
 .TP
-\fB-y, --yzoom\fP <min:max>
-Limit processed sectors to min:max
+\fB-y, --yzoom\fP \fImin:max\fP
+Limit processed sectors to \fImin:max\fP.
 .TP
-\fB-a, --io-plot-action\fP <action>
-Plot given action (one of Q,D,C) in IO graph
+\fB-a, --io-plot-action\fP \fIaction\fP
+Plot \fIaction\fP (one of Q, D, or C) in the IO graph.
 .TP
 \fB-P, --per-process-io\fP
-Distinguish between processes in IO graph
+Distinguish between processes in the IO graph.
 .TP
-\fB-O, --only-graph\fP <graph>
-Add a single graph to the output (see GRAPHS).  By default all the graphs are included, but with -O you get only the graphs you ask for.  -O may be used more than once.
+\fB-O, --only-graph\fP \fIgraph\fP
+Add a single graph to the output (see section \fBGRAPHS\fP for options).  By
+default all graphs are included. Use \fB-O\fP to generate only the required
+graphs.  \fB-O\fP may be used more than once.
 .TP
-\fB-N, --no-graph\fP <type>
-Remove a single graph from the output (see GRAPHS).  This may also be used more than once.
+\fB-N, --no-graph\fP \fItype\fP
+Remove a single graph from the output (see section \fBGRAPHS\fP for options).
+This option may be used more than once.
 .SH GRAPHS
-Choices for -O and -N are:
+Values accepted by the \fB-O\fP and \fB-N\fP options are:
+
    io, tput, latency, queue_depth, iops, cpu-sys, cpu-io, cpu-irq, cpu-user, cpu-soft
 
 .SH EXAMPLES
 Generate graph from the existing trace.dump:
 .PP
 .RS
-iowatcher -t trace.dump -o trace.svg
+# iowatcher -t trace
 .RE
 .PP
 Skip the IO graph:
 .PP
 .RS
-iowatcher -t trace.dump -o trace.svg -N io
+# iowatcher -t trace.dump -o trace.svg -N io
 .RE
 .PP
 Only graph tput and latency:
 .PP
 .RS
-iowatcher -t trace.dump -o trace.svg -O tput -O latency
+# iowatcher -t trace.dump -o trace.svg -O tput -O latency
 .RE
 .PP
 Generate a graph from two runs, and label them:
 .PP
 .RS
-iowatcher -t ext4.dump -t xfs.dump -l Ext4 -l XFS -o trace.svg
+# iowatcher -t ext4.dump -t xfs.dump -l Ext4 -l XFS -o trace.svg
 .RE
 .PP
 Run a fio benchmark and store the trace in trace.dump, add a title to the top, use /dev/sda for blktrace:
 .PP
 .RS
-iowatcher -d /dev/sda -t trace.dump -T 'Fio Benchmark' -p 'fio some_job_file'
+# iowatcher -d /dev/sda -t trace.dump -T 'Fio Benchmark' -p fio some_job_file
 .RE
 .PP
 Make a movie from an existing trace:
 .PP
 .RS
-iowatcher -t trace --movie -o trace.mp4
+# iowatcher -t trace --movie -o trace.mp4
 .RE
 
+.SH AUTHORS
+iowatcher was created and is maintained by Chris Mason.
+
+This man page was largely written by Andrew Price based on Chris's original README.
+
+.SH COPYRIGHT
+This program is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License v2 as published by the Free
+Software Foundation.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
+Street, Fifth Floor, Boston, MA 02110-1301 USA
+
+.SH "SEE ALSO"
+.BR blktrace (8),
+.BR blkparse (1),
+.BR fio (1),
+.BR mpstat (1)
diff --git a/iowatcher/main.c b/iowatcher/main.c
index 4441dfc..2b9667c 100644
--- a/iowatcher/main.c
+++ b/iowatcher/main.c
@@ -1344,7 +1344,7 @@ static void print_usage(void)
 		"\t-t (--trace): trace file name (more than one allowed)\n"
 		"\t-F (--fio-trace): fio bandwidth trace (more than one allowed)\n"
 		"\t-l (--label): trace label in the graph\n"
-		"\t-o (--output): output file name (SVG only)\n"
+		"\t-o (--output): output file name for the SVG image or video\n"
 		"\t-p (--prog): run a program while blktrace is run\n"
 		"\t-K (--keep-movie-svgs keep svgs generated for movie mode\n"
 		"\t-m (--movie [=spindle|rect]): create IO animations\n"