cli: Fix/update manpage a bit.
[sigrok-cli.git] / doc / sigrok-cli.1
index 7b854a7b261fa35cfaffe024a1b162712e427eda..2150a8451ddb6ba2b2803e18bdefadd414c12a42 100644 (file)
@@ -1,8 +1,8 @@
-.TH SIGROK\-CLI 1 "January 19, 2011"
+.TH SIGROK\-CLI 1 "March 18, 2012"
 .SH "NAME"
 sigrok\-cli \- Command-line client for the sigrok logic analyzer software
 .SH "SYNOPSIS"
 .SH "NAME"
 sigrok\-cli \- Command-line client for the sigrok logic analyzer software
 .SH "SYNOPSIS"
-.B sigrok\-cli \fR[\fB\-hVDiIodptwaf\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fB\-D\fR|\fB\-\-list\-devices\fR] [\fB\-i\fR|\fB\-\-input\-file\fR filename] [\fB\-I\fR|\fB\-\-input\-format\fR format] [\fB\-o\fR|\fB\-\-output\-file\fR filename] [\fB\-d\fR|\fB\-\-device\fR device] [\fB\-p\fR|\fB\-\-probes\fR probelist] [\fB\-t\fR|\fB\-\-triggers\fR triggerlist] [\fB\-w\fR|\fB\-\-wait\-triggers\fR] [\fB\-a\fR|\fB\-\-protocol\-decoders\fR sequence] [\fB\-f\fR|\fB\-\-format\fR format] [\fB\-\-time\fR ms] [\fB\-\-samples\fR numsamples] [\fB\-\-continuous\fR]
+.B sigrok\-cli \fR[\fB\-hVDiIoOdptwa\fR] [\fB\-h\fR|\fB\-\-help\fR] [\fB\-V\fR|\fB\-\-version\fR] [\fB\-D\fR|\fB\-\-list\-devices\fR] [\fB\-i\fR|\fB\-\-input\-file\fR filename] [\fB\-I\fR|\fB\-\-input\-format\fR format] [\fB\-o\fR|\fB\-\-output\-file\fR filename] [\fB\-O\fR|\fB\-\-output-format\fR format] [\fB\-d\fR|\fB\-\-device\fR device] [\fB\-p\fR|\fB\-\-probes\fR probelist] [\fB\-t\fR|\fB\-\-triggers\fR triggerlist] [\fB\-w\fR|\fB\-\-wait\-triggers\fR] [\fB\-a\fR|\fB\-\-protocol\-decoders\fR sequence] [\fB\-\-time\fR ms] [\fB\-\-samples\fR numsamples] [\fB\-\-continuous\fR]
 .SH "DESCRIPTION"
 .B sigrok\-cli
 is a cross-platform command line utility for the
 .SH "DESCRIPTION"
 .B sigrok\-cli
 is a cross-platform command line utility for the
@@ -18,17 +18,21 @@ and for various other use-cases. It can display samples on standard output or
 save them in various file formats.
 .SH "OPTIONS"
 .TP
 save them in various file formats.
 .SH "OPTIONS"
 .TP
-.B "\-V, \-\-version"
-Show version, driver and module information.
-.TP
 .B "\-h, \-\-help"
 Show a help text and exit.
 .TP
 .B "\-h, \-\-help"
 Show a help text and exit.
 .TP
+.B "\-V, \-\-version"
+Show
+.B sigrok-cli
+version, and information about supported hardware drivers, input file
+formats, output file formats, and protocol decoders.
+.TP
 .B "\-D, \-\-list\-devices"
 .B "\-D, \-\-list\-devices"
-List all logic analyzer devices found on the system.
+List all logic analyzer devices found on the system. This actively scans for
+devices (USB, serial port, and others).
 .TP
 .BR "\-i, \-\-input\-file " <filename>
 .TP
 .BR "\-i, \-\-input\-file " <filename>
-Load input from a file instead of a device. If the
+Load input from a file instead of a hardware device. If the
 .B \-\-input\-format
 option is not supplied, sigrok-cli attempts to autodetect the file format of
 the input file.
 .B \-\-input\-format
 option is not supplied, sigrok-cli attempts to autodetect the file format of
 the input file.
@@ -43,8 +47,43 @@ sigrok-cli attempts to autodetect the file format of the input file.
 Save output to a file instead of writing it to stdout. The default format
 used when saving is the sigrok session file format. This can be changed with
 the
 Save output to a file instead of writing it to stdout. The default format
 used when saving is the sigrok session file format. This can be changed with
 the
-.B \-\-format
-option, below.
+.B \-\-output\-format
+option.
+.TP
+.BR "\-O, \-\-output\-format " <formatname>
+Set the output format to use. Use the
+.B \-V
+option to see a list of available output formats. The format name may
+optionally be followed by a colon-separated list of options, where each
+option takes the form
+.BR "key=value" .
+.sp
+Supported formats currently include
+.BR bits ,
+.BR hex ,
+.BR ascii ,
+.BR binary ,
+.BR vcd ,
+.BR ols ", and"
+.BR gnuplot .
+.sp
+The
+.B bits
+or
+.B hex
+formats, for an ASCII bit or ASCII hexadecimal display, can take a "width" option, specifying the number of samples (in bits) to display per line. Thus
+.B hex:width=128
+will display 128 bits per line, in hexadecimal:
+.sp
+ 1:ffff ffff ffff ffff ffff ffff ffff ffff
+ 2:ff00 ff00 ff00 ff00 ff00 ff00 ff00 ff00
+.sp
+The lines always start with the probe number (or name, if defined), followed by a colon. If no format is specified, it defaults to
+.BR bits:width=64 ,
+like this:
+.sp
+ 1:11111111 11111111 11111111 11111111 [...]
+ 2:11111111 00000000 11111111 00000000 [...]
 .TP
 .BR "\-d, \-\-device " <device>
 The device to use for acquisition. It can be specified by ID as reported by
 .TP
 .BR "\-d, \-\-device " <device>
 The device to use for acquisition. It can be specified by ID as reported by
@@ -59,7 +98,7 @@ For example, to set the samplerate on the first device you might specify
 .sp
 .RB "  $ " "sigrok\-cli \-d 0:samplerate=1m"
 .sp
 .sp
 .RB "  $ " "sigrok\-cli \-d 0:samplerate=1m"
 .sp
-Samplerate is a option common to most devices. The argument specifies the
+Samplerate is an option common to most devices. The argument specifies the
 samplerate in Hz. You can also specify the samplerate in kHz, MHz or GHz.
 The following are all equivalent:
 .sp
 samplerate in Hz. You can also specify the samplerate in kHz, MHz or GHz.
 The following are all equivalent:
 .sp
@@ -134,41 +173,6 @@ any pre-trigger data. This option is useful if you don't care about the data
 that came before the trigger (but the logic analyzer hardware delivers this
 data to sigrok nonetheless).
 .TP
 that came before the trigger (but the logic analyzer hardware delivers this
 data to sigrok nonetheless).
 .TP
-.BR "\-f, \-\-format " <formatname>
-Set the output format to use. Use the
-.B \-V
-option to see a list of available output formats. The format name may
-optionally be followed by a colon-separated list of options, where each
-option takes the form
-.BR "key=value" .
-.sp
-Supported formats currently include
-.BR bits ,
-.BR hex ,
-.BR ascii ,
-.BR binary ,
-.BR vcd ,
-.BR ols ", and"
-.BR gnuplot .
-.sp
-The
-.B bits
-or
-.B hex
-formats, for an ASCII bit or ASCII hexadecimal display, can take a "width" option, specifying the number of samples (in bits) to display per line. Thus
-.B hex:width=128
-will display 128 bits per line, in hexadecimal:
-.sp
- 1:ffff ffff ffff ffff ffff ffff ffff ffff
- 2:ff00 ff00 ff00 ff00 ff00 ff00 ff00 ff00
-.sp
-The lines always start with the probe number (or name, if defined), followed by a colon. If no format is specified, it defaults to
-.BR bits:width=64 ,
-like this:
-.sp
- 1:11111111 11111111 11111111 11111111 [...]
- 2:11111111 00000000 11111111 00000000 [...]
-.TP
 .BR "\-\-time " <ms>
 Sample for
 .B <ms>
 .BR "\-\-time " <ms>
 Sample for
 .B <ms>
@@ -201,7 +205,7 @@ Alternatively, you can also use:
 .TP
 To capture data from 4 probes lasting 100ms at 10 MHz starting at the trigger condition 1:high, 2:rising, 3:low, 4:high, use:
 .TP
 .TP
 To capture data from 4 probes lasting 100ms at 10 MHz starting at the trigger condition 1:high, 2:rising, 3:low, 4:high, use:
 .TP
-.B "  sigrok\-cli \-f bits \-p 1\-4 \-\-time 100 \-o samplerate=10m \\\\"
+.B "  sigrok\-cli \-O bits \-p 1\-4 \-\-time 100 \-o samplerate=10m \\\\"
 .B "      \-\-wait\-trigger \-\-triggers 1=1,2=r,3=0,4=1 "
 .SH "EXIT STATUS"
 .B sigrok\-cli
 .B "      \-\-wait\-trigger \-\-triggers 1=1,2=r,3=0,4=1 "
 .SH "EXIT STATUS"
 .B sigrok\-cli