Update -2, -R and -Y to behave consistently as per the concensus reached on

https://bugs.wireshark.org/bugzilla/show_bug.cgi?id=8223

Mention the new -Y flag and associated changes in the release notes.

svn path=/trunk/; revision=48654

1 files changed, 17 insertions, 15 deletions

diff --git a/doc/tshark.pod b/doc/tshark.pod
index 8d30b0446a..8c3f314e3c 100644
--- a/doc/tshark.pod
+++ b/doc/tshark.pod
@@ -149,7 +149,10 @@ to dump one of several types of internal glossaries and then exit.
 
 =item -2
 
-Perform a two-pass analysis.
+Perform a two-pass analysis. This causes tshark to buffer output until the
+entire first pass is done, but allows it to fill in fields that require future
+knowledge, such as 'response in frame #' fields. Also permits reassembly
+frame dependencies to be calculated correctly.
 
 =item -a  E<lt>capture autostop conditionE<gt>
 
@@ -615,12 +618,14 @@ or stdin here!
 =item -R  E<lt>Read filterE<gt>
 
 Cause the specified filter (which uses the syntax of read/display filters,
-rather than that of capture filters) to be applied before printing a
-decoded form of packets or writing packets to a file; packets not
-matching the filter are discarded rather than being printed or written.
+rather than that of capture filters) to be applied during the first pass of
+analysis. Packets not matching the filter are not considered for future
+passes. Only makes sense with multiple passes, see -2. For regular filtering
+on single-pass dissect see -Y instead.
 
-See the '-Y' option for information about using this at the same time the
-'-Y' option is used.
+Note that forward-looking fields such as 'response in frame #' cannot be used
+with this filter, since they will not have been calculate when this filter is
+applied.
 
 =item -Y  E<lt>displaY filterE<gt>
 
@@ -628,16 +633,13 @@ Cause the specified filter (which uses the syntax of read/display filters,
 rather than that of capture filters) to be applied before printing a
 decoded form of packets or writing packets to a file.  Packets matching the
 filter are printed or written to file; packets that the matching packets 
-depend upon (e.g., fragments), are not printed but are wrtitten to file;
+depend upon (e.g., fragments), are not printed but are written to file;
 packets not matching the filter nor depended upon are discarded rather 
-than being printed or written.  This mode also performs a two-pass
-analysis as is done with the '-2' option, without needing '-2' to be set.
-
-If the '-R' read filter option is also set, then the read filter is applied
-first, and only packets passing that will be considered for the display
-filter, including dependent packets.  In other words, if the '-R' filters
-out fragments, they will not be included even if a packet matching the 
-display filter depended on the fragments.
+than being printed or written.
+
+Use this instead of -R for filtering using single-pass analysis. If doing
+two-pass analysis (see -2) then only packets matching the read filter (if there
+is one) will be checked against this filter.
 
 =item -s  E<lt>capture snaplenE<gt>