X-Git-Url: https://sigrok.org/gitweb/?p=pulseview.git;a=blobdiff_plain;f=manual%2Fdecoders.txt;h=d50a6983e02457ec686e8d4e105ac55cd3c378c3;hp=186f7e533121f59f24f0e89e803edf42791c61c0;hb=7f030756dbd3a893265bf2fc790a349e1babfc4d;hpb=a0241dc5b5496927dbd275a95a0992cf37a81a85

diff --git a/manual/decoders.txt b/manual/decoders.txt
index 186f7e53..d50a6983 100644
--- a/manual/decoders.txt
+++ b/manual/decoders.txt
@@ -50,14 +50,15 @@ image::pv_decoders_3.png[]
 With the stacked decoder added, we can now see that PulseView has decoded the meaning
 of the I²C commands, so that we don't need to bother searching the reference manual.
 In this view, we can see that the I²C packet was a command to read the date and time,
-which was then reported to be 10.03.2013 23:35:30. 
+which was then reported to be 10.03.2013 23:35:30.
 
-There are all kinds of stacked decoders available, but keep in mind that they're not
-shown in the decoder menu. Stacked decoders require a lower-level decoder first before
-they become stackable. Most of the time, they require either the UART, I²C or SPI decoder.
+In this example, we added the I²C and DS1307 decoders separately. However, when opening
+the decoder selector window, you can also double-click on the DS1307 decoder and PulseView
+will try to auto-resolve the dependencies needed to use this decoder. In case there are
+ambiguities (e.g. when several different protocol decoders offer 'uart' output), it will
+ask you to choose which one to use.
 
-You can check the https://sigrok.org/wiki/Protocol_decoders[List of Protocol Decoders]
-to see which protocol decoders have been created already.
+For a list of available and planned protocol decoders, you can https://sigrok.org/wiki/Protocol_decoders[check the wiki].
 
 === Using Decoders on Analog Signals
 
@@ -81,26 +82,38 @@ or enter custom values as well. They take the form "0.0V" and "0.0V/0.0V", respe
 === Troubleshooting
 
 In case a protocol decoder doesn't provide the expected result, there are several things
-you can check. The first check you should perform is whether the time unit in the ruler
+you can check.
+
+The first check you should perform is whether the time unit in the ruler
 is given as "sa". This is short for "samples" and means that the device didn't provide
 a sample rate and so PulseView has no way of showing a time scale in seconds or
-fractions thereof. While some decoders can run without timing information, others
-cannot.
+fractions thereof. While some decoders can run without timing information, or only
+optionally make use of the time scale, others may not be able to interpret the
+input data since timing information is an essential part of the very protocol.
+
+Another issue to remain aware of is that decoders need enough samples per protocol step
+to reliably interpret the information. In typical cases the minimum sample rate should
+be four to five times the rate of the fastest activity in the protocol.
 
 If a protocol decoder runs but shows you annotations that don't seem to make any sense,
 it's worth double-checking the decoder settings. One common source of error is the
-baud rate, for example. For example, the CAN protocol decoder doesn't know what baud rate
+baud rate. For example, the CAN protocol decoder doesn't know what baud rate
 is used on the bus that you captured, so it could be that a different baud rate is used
 than the one you set. Also, if this is still not the reason for the malfunction, it's
 worth checking whether any of the signals have been captured inverted. Again using the
 CAN bus as an example, the decoder will decode the signal just fine if it's inverted but
 it'll show data even when the signal looks "idle".
 
-When a protocol decoder stops execution because of a bug in the decoder itself, you
+When a protocol decoder stops execution because of an unmet constraint (required input
+not connected, essential parameter not specified) or a bug in the decoder itself, you
 will be presented a static red message in the protocol decoder's display area.
 In that case, you check the log output in the settings menu. There you'll find the Python
-error description which you can use to either debug the decoder (and let us know of the
-fix) or you can copy that information and file a bug report so that we can fix it.
+error description which you can use to either adjust the configuration,
+or debug the decoder (and let us know of the fix) or you can copy that information and
+file a bug report so that we can fix it.
+
+Further helpful knowledge and explanations on logic analyzers can be found in our
+https://sigrok.org/wiki/FAQ#Where_can_I_learn_more_about_logic_analyzers.3F["Learn about logic analyzers" FAQ item].
 
 === Exporting Annotations