update usage output and manual pages for both Ethereal and Tethereal to reflect the latest changes in the command line.

clarifications of some command line parameter descriptions in the manual pages

this also fixes #221

svn path=/trunk/; revision=14545

2 files changed, 130 insertions, 118 deletions

diff --git a/doc/ethereal.pod b/doc/ethereal.pod
index d15c43a14b..87f2f067d8 100644
--- a/doc/ethereal.pod
+++ b/doc/ethereal.pod
@@ -7,31 +7,31 @@ ethereal - Interactively browse network traffic
 
 B<ethereal>
 S<[ B<-a> capture autostop condition ] ...>
-S<[ B<-b> ring buffer options] ...>
-S<[ B<-B> capture buffer size (Win32 only) ] ...>
-S<[ B<-c> count ]>
-S<[ B<-f> capture filter expression ]>
+S<[ B<-b> capture ring buffer option ] ...>
+S<[ B<-B> capture buffer size (Win32 only) ] >
+S<[ B<-c> capture packet count ]>
+S<[ B<-f> capture filter ]>
 S<[ B<-g> packet number ]>
 S<[ B<-h> ]>
-S<[ B<-i> interface ]> 
+S<[ B<-i> capture interface ]> 
 S<[ B<-k> ]>
 S<[ B<-l> ]>
 S<[ B<-L> ]>
 S<[ B<-m> font ]>
 S<[ B<-n> ]>
-S<[ B<-N> resolving flags ] >
+S<[ B<-N> name resolving flags ] >
 S<[ B<-o> preference/recent setting ] ...>
 S<[ B<-p> ]>
 S<[ B<-Q> ]>
 S<[ B<-r> infile ]>
-S<[ B<-R> display filter expression ]>
+S<[ B<-R> read (display) filter ]>
 S<[ B<-S> ]>
-S<[ B<-s> snaplen ]>
+S<[ B<-s> capture snaplen ]>
 S<[ B<-t> time stamp format ]>
 S<[ B<-v> ]>
 S<[ B<-w> savefile]>
-S<[ B<-y> link type ]>
-S<[ B<-z> statistics-string ]>
+S<[ B<-y> capture link type ]>
+S<[ B<-z> statistics ]>
 S<[ infile ]>
 
 =head1 DESCRIPTION
@@ -184,24 +184,24 @@ B<files>:I<value> Stop writing to capture files after I<value> number of files w
 
 Cause B<Ethereal> to run in "multiple files" mode.  In "multiple files" mode, 
 B<Ethereal> will write to several capture files. When the first capture file 
-fills up, B<Ethereal> will switch writing to the next file.
-Their name is based on the number of the file and on the creation date 
-and time.
+fills up, B<Ethereal> will switch writing to the next file and so on.
 
-If the I<files> option is set, B<Ethereal> will fill up files until the last 
-file, at which point it'll discard the data in the first file and start 
-writing to that file and so on. If the I<files> option is not set, B<Ethereal> 
-will fill up new files until one of the capture stop conditions match.
+The created filenames are based on the filename given with the B<-w> flag, the number of 
+the file and on the creation date and time, 
+e.g. savefile_00001_20050604120117.pcap, savefile_00001_20050604120523.pcap, ...
 
-If the optional I<duration> is specified, B<Ethereal> will switch also 
-to the next file when the specified number of seconds has elapsed even
-if the current file is not completely filled up.
+With the I<files> option it's also possible to form a "ring buffer". 
+This will fill up new files until the number of files specified, 
+at which point B<Ethereal> will discard the data in the first file and start 
+writing to that file and so on. If the I<files> option is not set,
+new files filled up until one of the capture stop conditions match (or 
+until the disk if full).
 
 The criterion is of the form I<key>B<:>I<value>,
 where I<key> is one of:
 
 B<duration>:I<value> switch to the next file after I<value> seconds have 
-elapsed.
+elapsed, even if the current file is not completely filled up.
 
 B<filesize>:I<value> switch to the next file after it reaches a size of 
 I<value> kilobytes (where a kilobyte is 1000 bytes, not 1024 bytes). 
@@ -217,7 +217,7 @@ disk. If you encounter packet drops while capturing, try to increase this size.
 
 =item -c
 
-Set the default number of packets to read when capturing live
+Set the maximum number of packets to read when capturing live
 data.
 
 =item -f
@@ -226,7 +226,7 @@ Set the capture filter expression.
 
 =item -g
 
-After reading in a capture file using B<-r>, go to the given I<packet number>.
+After reading in a capture file using the B<-r> flag, go to the given I<packet number>.
 
 =item -h
 
@@ -276,17 +276,25 @@ pane from the name of the main text font.
 =item -n
 
 Disable network object name resolution (such as hostname, TCP and UDP port
-names).
+names), the B<-N> flag might override this one.
 
 =item -N
 
-Turn on name resolving for particular types of addresses and port
+Turn on name resolving only for particular types of addresses and port
 numbers, with name resolving for other types of addresses and port
-numbers turned off; the argument is a string that may contain the
-letters B<m> to enable MAC address resolution, B<n> to enable network
-address resolution, and B<t> to enable transport-layer port number
-resolution.  This overrides B<-n> if both B<-N> and B<-n> are present.
-The letter B<C> enables concurrent (asynchronous) DNS lookups.
+numbers turned off. This flag overrides B<-n> if both B<-N> and B<-n> are 
+present. If both B<-N> and B<-n> flags are not present, all name resolutions are 
+turned on.
+
+The argument is a string that may contain the letters:
+
+B<m> to enable MAC address resolution
+
+B<n> to enable network address resolution
+
+B<t> to enable transport-layer port number resolution
+
+B<C> to enable concurrent (asynchronous) DNS lookups
 
 =item -o
 
@@ -295,8 +303,8 @@ read from a preference/recent file. The argument to the flag is a string of
 the form I<prefname>B<:>I<value>, where I<prefname> is the name of the
 preference/recent value (which is the same name that would appear in the 
 preference/recent file), and I<value> is the value to which it should be set. 
-Using the recent settings now replaces the formerly used -B, -P and -T 
-parameters to manipulate the GUI dimensions.
+Since B<Ethereal> 0.10.12, the recent settings replaces the formerly used 
+-B, -P and -T flags to manipulate the GUI dimensions.
 
 =item -p
 
@@ -326,8 +334,7 @@ capture file; packets not matching the filter are discarded.
 
 =item -S
 
-Perform the live packet capture in a separate process, and automatically
-update the packet display as packets are seen.
+Automatically update the packet display as packets are coming in.
 
 =item -s
 
@@ -338,13 +345,19 @@ memory, or saved to disk.
 =item -t
 
 Set the format of the packet timestamp displayed in the packet list
-window.  The format can be one of 'r' (relative), 'a' (absolute), 'ad'
-(absolute with date), or 'd' (delta).  The relative time is the time
-elapsed between the first packet and the current packet.  The absolute
-time is the actual time the packet was captured, with no date displayed;
-the absolute date and time is the actual time and date the packet was
-captured.  The delta time is the time since the previous packet was
-captured.  The default is relative.
+window, the default is relative. The format can be one of:
+
+B<r> relative: The relative time is the time elapsed between the first packet 
+and the current packet
+
+B<a> absolute: The absolute time is the actual time the packet was captured, 
+with no date displayed
+
+B<ad> absolute with date: The absolute date and time is the actual time and 
+date the packet was captured
+
+B<d> delta: The delta time is the time since the previous packet was
+captured
 
 =item -v
 
@@ -1843,12 +1856,12 @@ protocols built into Ethereal are.
 
 =head1 CAPTURE FILTER SYNTAX
 
-See the tcpdump(8) manual page.
+See the manual page of I<tcpdump(8)>.
 
 =head1 DISPLAY FILTER SYNTAX
 
 For a complete table of protocol and protocol fields that are filterable
-in B<Ethereal> see ethereal-filter(4).
+in B<Ethereal> see the I<ethereal-filter(4)> manual page.
 
 =head1 FILES
 
diff --git a/doc/tethereal.pod b/doc/tethereal.pod
index 28093e9762..584a9b338c 100644
--- a/doc/tethereal.pod
+++ b/doc/tethereal.pod
@@ -7,24 +7,24 @@ tethereal - Dump and analyze network traffic
 
 B<tethereal>
 S<[ B<-a> capture autostop condition ] ...>
-S<[ B<-b> number of ring buffer files [:duration] ]>
-S<[ B<-c> count ]>
+S<[ B<-b> capture ring buffer option] ...>
+S<[ B<-c> capture packet count ]>
 S<[ B<-d> <layer type>==<selector>,<decode-as protocol> ]>
 S<[ B<-D> ]>
-S<[ B<-f> capture filter expression ]>
+S<[ B<-f> capture filter ]>
 S<[ B<-F> file format ]>
 S<[ B<-h> ]>
-S<[ B<-i> interface ]> 
+S<[ B<-i> capture interface ]> 
 S<[ B<-l> ]>
 S<[ B<-L> ]>
 S<[ B<-n> ]>
-S<[ B<-N> resolving flags ]>
+S<[ B<-N> name resolving flags ]>
 S<[ B<-o> preference setting ] ...>
 S<[ B<-p> ]>
 S<[ B<-q> ]>
 S<[ B<-r> infile ]>
-S<[ B<-R> display filter expression ]>
-S<[ B<-s> snaplen ]>
+S<[ B<-R> read (display) filter ]>
+S<[ B<-s> capture snaplen ]>
 S<[ B<-S> ]>
 S<[ B<-t> time stamp format ]>
 S<[ B<-T> pdml|psml|ps|text ]>
@@ -32,9 +32,8 @@ S<[ B<-v> ]>
 S<[ B<-V> ]>
 S<[ B<-w> savefile ]>
 S<[ B<-x> ]>
-S<[ B<-y> link type ]>
-S<[ B<-z> statistics-string ]>
-S<[ filter expression ]>
+S<[ B<-y> capture link type ]>
+S<[ B<-z> statistics ]>
 
 =head1 DESCRIPTION
 
@@ -45,7 +44,7 @@ standard output or writing the packets to a file.  B<Tethereal>'s native
 capture file format is B<libpcap> format, which is also the format used
 by B<tcpdump> and various other tools.  
 
-B<Ethereal> can read / import the following file formats:
+B<Tethereal> can read / import the following file formats:
 
 =over 4
 
@@ -243,45 +242,47 @@ Specify a criterion that specifies when B<Tethereal> is to stop writing
 to a capture file.  The criterion is of the form I<test>B<:>I<value>,
 where I<test> is one of:
 
-=for man .RS
+B<duration>:I<value> Stop writing to a capture file after I<value> seconds have elapsed.
 
-=for html <P><DL>
+B<filesize>:I<value> Stop writing to a capture file after it reaches a size of I<value>
+kilobytes (where a kilobyte is 1000 bytes, not 1024 bytes). If this option 
+is used together with the -b option, Ethereal will stop writing to the 
+current capture file and switch to the next one if filesize is reached.
 
-=item duration
+B<files>:I<value> Stop writing to capture files after I<value> number of files were written.
 
-Stop writing to a capture file after I<value> seconds have elapsed.
-
-=item filesize
+=item -b
 
-Stop writing to a capture file after it reaches a size of I<value>
-kilobytes (where a kilobyte is 1000 bytes, not 1024 bytes).
+Cause B<Tethereal> to run in "multiple files" mode.  In "multiple files" mode, 
+B<Tethereal> will write to several capture files. When the first capture file 
+fills up, B<Tethereal> will switch writing to the next file and so on.
 
-=for man .RE
+The created filenames are based on the filename given with the B<-w> flag, the number of 
+the file and on the creation date and time, 
+e.g. savefile_00001_20050604120117.pcap, savefile_00001_20050604120523.pcap, ...
 
-=for html </DL>
+With the I<files> option it's also possible to form a "ring buffer". 
+This will fill up new files until the number of files specified, 
+at which point B<Tethereal> will discard the data in the first file and start 
+writing to that file and so on. If the I<files> option is not set,
+new files filled up until one of the capture stop conditions match (or 
+until the disk if full).
 
-=item -b
+The criterion is of the form I<key>B<:>I<value>,
+where I<key> is one of:
 
-If a maximum capture file size was specified, cause B<Tethereal> to run
-in "ring buffer" mode, with the specified number of files.  In "ring
-buffer" mode, B<Tethereal> will write to several capture files. 
-Their name is based on the number of the file and on the creation date 
-and time.
+B<duration>:I<value> switch to the next file after I<value> seconds have 
+elapsed, even if the current file is not completely filled up.
 
-When the first capture file fills up, B<Tethereal> will switch to writing
-to the next file, until it fills up the last file, at which point it'll
-discard the data in the first file (unless 0 is specified, in which case,
-the number of files is unlimited) and start writing to that file and so on.
+B<filesize>:I<value> switch to the next file after it reaches a size of 
+I<value> kilobytes (where a kilobyte is 1000 bytes, not 1024 bytes). 
 
-If the optional duration is specified, B<Tethereal> will switch also 
-to the next file when the specified number of seconds has elapsed even
-if the current file is not completely fills up.
-
-You can only save files in B<libpcap> format when using a ring buffer.
+B<files>:I<value> begin again with the first file after I<value> number of 
+files were written (form a ring buffer).
 
 =item -c
 
-Set the default number of packets to read when capturing live
+Set the maximum number of packets to read when capturing live
 data.
 
 =item -d
@@ -302,7 +303,7 @@ interface, is printed.  The interface name or the number can be supplied
 to the B<-i> flag to specify an interface on which to capture.
 
 This can be useful on systems that don't have a command to list them  
-(e.g., Windows systems, or UNIX systems lacking B<ifconfig \-a>);
+(e.g., Windows systems, or UNIX systems lacking B<ifconfig -a>);
 the number can be useful on Windows 2000 and later systems, where the
 interface name is a somewhat complex string.
 
@@ -371,17 +372,25 @@ List the data link types supported by the interface and exit.
 =item -n
 
 Disable network object name resolution (such as hostname, TCP and UDP port
-names).
+names), the B<-N> flag might override this one.
 
 =item -N
 
-Turn on name resolving for particular types of addresses and port
+Turn on name resolving only for particular types of addresses and port
 numbers, with name resolving for other types of addresses and port
-numbers turned off; the argument is a string that may contain the
-letters B<m> to enable MAC address resolution, B<n> to enable network
-address resolution, and B<t> to enable transport-layer port number
-resolution.  This overrides B<-n> if both B<-N> and B<-n> are present.
-The letter B<C> enables concurrent (asynchronous) DNS lookups.
+numbers turned off. This flag overrides B<-n> if both B<-N> and B<-n> are 
+present. If both B<-N> and B<-n> flags are not present, all name resolutions are 
+turned on.
+
+The argument is a string that may contain the letters:
+
+B<m> to enable MAC address resolution
+
+B<n> to enable network address resolution
+
+B<t> to enable transport-layer port number resolution
+
+B<C> to enable concurrent (asynchronous) DNS lookups
 
 =item -o
 
@@ -440,52 +449,42 @@ B<-w> flag.
 
 =item -t
 
-Set the format of the packet timestamp printed in summary lines.  The
-format can be one of 'r' (relative), 'a' (absolute), 'ad' (absolute with
-date), or 'd' (delta).  The relative time is the time elapsed between
-the first packet and the current packet.  The absolute time is the
-actual time the packet was captured, with no date displayed; the
-absolute date and time is the actual time and date the packet was
-captured.  The delta time is the time since the previous packet was
-captured.  The default is relative.
+Set the format of the packet timestamp printed in summary lines, the default 
+is relative. The format can be one of:
 
-=item -T
+B<r> relative: The relative time is the time elapsed between the first packet 
+and the current packet
 
-Set the format of the output when viewing decoded packet data.  The
-options are:
+B<a> absolute: The absolute time is the actual time the packet was captured, 
+with no date displayed
 
-=for man .RS
+B<ad> absolute with date: The absolute date and time is the actual time and 
+date the packet was captured
 
-=for html <P><DL>
+B<d> delta: The delta time is the time since the previous packet was
+captured
 
-=item pdml
+=item -T
 
-Packet Details Markup Language, an XML-based format for the details of
+Set the format of the output when viewing decoded packet data.  The
+options are one of:
+
+B<pdml> Packet Details Markup Language, an XML-based format for the details of
 a decoded packet.  This information is equivalent to the packet details
 printed with the B<-V> flag.
 
-=item psml
-
-Packet Summary Markup Language, an XML-based format for the summary
+B<psml> Packet Summary Markup Language, an XML-based format for the summary
 information of a decoded packet.  This information is equivalent to the
 information shown in the one-line summary printed by default.
 
-=item ps
-
-PostScript for a human-readable one-line summary of each of the packets,
+B<ps> PostScript for a human-readable one-line summary of each of the packets,
 or a multi-line view of the details of each of the packets, depending on
 whether the B<-V> flag was specified.
 
-=item text
-
-Text of a human-readable one-line summary of each of the packets, or a
+B<text> Text of a human-readable one-line summary of each of the packets, or a
 multi-line view of the details of each of the packets, depending on
 whether the B<-V> flag was specified.  This is the default.
 
-=for man .RE
-
-=for html </DL>
-
 =item -v
 
 Print the version and exit.
@@ -797,12 +796,12 @@ SIP packets exchanged by the host at IP address 1.2.3.4 .
 
 =head1 CAPTURE FILTER SYNTAX
 
-See manual page of tcpdump(8).
+See the manual page of I<tcpdump(8)>.
 
 =head1 READ FILTER SYNTAX
 
 For a complete table of protocol and protocol fields that are filterable
-in B<Tethereal> see ethereal-filter(4).
+in B<Tethereal> see the I<ethereal-filter(4)> manual page.
 
 =head1 FILES