doc: mention lack of decoder signal name matching in manpage

[sigrok-cli.git] / doc / sigrok-cli.1

diff --git a/doc/sigrok-cli.1 b/doc/sigrok-cli.1
index 545b4d5677bd5fbf55a927b45a03b160c1dc998e..eac5942df7d0ebee19607133b4c660db2371cb43 100644 (file)
--- a/doc/sigrok-cli.1
+++ b/doc/sigrok-cli.1
@@ -1,4 +1,4 @@
-.TH SIGROK\-CLI 1 "May 04, 2014"
+.TH SIGROK\-CLI 1 "September 13, 2017"
 .SH "NAME"
 sigrok\-cli \- Command-line client for the sigrok software
 .SH "SYNOPSIS"
@@ -22,12 +22,16 @@ Show a help text and exit.
 .B "\-V, \-\-version"
 Show
 .B sigrok-cli
-version, and information about supported hardware drivers, input file
+version and the versions of libraries used.
+.TP
+.B "\-L, \-\-list-supported"
+Show information about supported hardware drivers, input file
 formats, output file formats, and protocol decoders.
 .TP
 \fB\-d, \-\-driver\fP <drivername>
 A driver must always be selected (unless doing a global scan). Use the
-\fB-V\fP option to get a list of available drivers.
+.BR "\-L " ( "\-\-list-supported" ")"
+option to get a list of available drivers.
 .sp
 Drivers can take options, in the form \fBkey=value\fP
 separated by colons.
@@ -73,7 +77,7 @@ When loading an input file, assume it's in the specified format. If this
 option is not supplied (in addition to
 .BR \-\-input\-file ),
 sigrok-cli attempts to autodetect the file format of the input file. Use the
-.B \-V
+.BR "\-L " ( "\-\-list-supported" ")"
 option to see a list of available input formats.
 .sp
 The format name may optionally be followed by a colon-separated list of
@@ -89,26 +93,14 @@ option.
 .TP
 .BR "\-O, \-\-output\-format " <formatname>
 Set the output format to use. Use the
-.B \-V
+.BR "\-L " ( "\-\-list-supported" ")"
 option to see a list of available output formats.
 .sp
 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 ,
-.BR gnuplot ,
-.BR chronovu-la8 ,
-.BR csv ", and"
-.BR analog .
-.sp
-The
+For example, the
 .B bits
 or
 .B hex
@@ -198,7 +190,7 @@ nonetheless).
 This option allows the user to specify a comma-separated list of protocol
 decoders to be used in this session. The decoders are specified by their
 ID, as shown in the
-.B \-\-version
+.BR "\-L " ( "\-\-list-supported" ")"
 output.
 .sp
 Example:
@@ -237,6 +229,36 @@ is an option supported by the
 protocol decoder. Additionally, the user tells sigrok to decode the SPI
 protocol using channel 1 as MISO signal for SPI, channel 5 as MOSI, channel 3
 as CLK, and channel 0 as CS# signal.
+.sp
+Notice that the
+.B sigrok\-cli
+application does not support "name matching". Instead it's assumed that the
+traces in the input stream match the order of the decoder's input signals,
+or that users explicitly specify the input channel to decoder signal mapping.
+.br
+.sp
+When multiple decoders are specified in the same
+.BR -P
+option, they will be stacked on top of each other in the specified order.
+.sp
+Example:
+.sp
+ $
+.B "sigrok\-cli \-i <file.sr> \-P i2c,eeprom24xx"
+.br
+ $
+.B "sigrok\-cli \-i <file.sr> \-P uart:baudrate=31250,midi"
+.sp
+When multiple
+.BR -P
+options are specified, each of them creates one decoder stack, which
+executes in parallel to other decoder stacks.
+.sp
+Example:
+.sp
+ $
+.B "sigrok\-cli \-i <file.sr> \-P uart:tx=D0:rx=D1 \-P timing:data=D2"
+.sp
 .TP
 .BR "\-A, \-\-protocol\-decoder\-annotations " <annotations>
 By default, only the stack's topmost protocol decoder's annotation output is
@@ -306,6 +328,10 @@ binary class you're interested in)
 .sp
 Not every decoder generates binary output.
 .TP
+.BR "\-\-protocol\-decoder\-samplenum
+When given, decoder annotations will include sample numbers, too.
+This allows consumers to receive machine readable timing information.
+.TP
 .BR "\-l, \-\-loglevel " <level>
 Set the libsigrok and libsigrokdecode loglevel. At the moment \fBsigrok-cli\fP
 doesn't support setting the two loglevels independently. The higher the