from Graeme Hewson: "Fixes for ethereal config files"

svn path=/trunk/; revision=15041

2 files changed, 63 insertions, 49 deletions

diff --git a/doc/ethereal.pod b/doc/ethereal.pod
index d54ab9df35..b36b5a6b66 100644
--- a/doc/ethereal.pod
+++ b/doc/ethereal.pod
@@ -1991,7 +1991,7 @@ whitespace. The same directory as for the personal preferences file is used.
 
 The F<ethers> files are consulted to correlate 6-byte hardware addresses to 
 names. First the personal F<ethers> file is tried and if an address is not 
-found there the global F<ethers> is tried next.
+found there the global F<ethers> file is tried next.
 
 Each line contains one hardware address and name, separated by
 whitespace.  The digits of the hardware address are separated by colons
diff --git a/doc/tethereal.pod b/doc/tethereal.pod
index 012826cb97..d3257c4285 100644
--- a/doc/tethereal.pod
+++ b/doc/tethereal.pod
@@ -811,69 +811,85 @@ These files contains various B<Ethereal> configuration values.
 
 =item Preferences
 
-The I<preferences> files contain global (system-wide) and personal preference 
-settings. If the system-wide preference file exists, it is read first, 
-overriding the default values. If the personal preferences file 
-exits, it is read then, overriding these values (again). Note: If the command 
-line flag B<-o> is used, it will override these values even once more.
-
-The preferences settings are in the form I<prefname>B<:>I<value>, 
+The F<preferences> files contain global (system-wide) and personal
+preference settings. If the system-wide preference file exists, it is
+read first, overriding the default settings. If the personal preferences
+file exists, it is read next, overriding any previous values. Note: If
+the command line flag B<-o> is used (possibly more than once), it will
+in turn override values from the preferences files.
+
+The preferences settings are in the form I<prefname>B<:>I<value>,
 one per line,
-where I<prefname> is the name of the preference (which is the same name
-that would appear in the preference file), and I<value> is the value to
+where I<prefname> is the name of the preference
+and I<value> is the value to
 which it should be set; white space is allowed between B<:> and
 I<value>.  A preference setting can be continued on subsequent lines by
 indenting the continuation lines with white space.  A B<#> character
-starts a comment that runs to the end of the line.
+starts a comment that runs to the end of the line:
 
-The global preferences file is searched in the
-F<ethereal> directory under the F<share> subdirectory of the main
-installation directory (for example, F</usr/local/share/ethereal/preferences>) on
-UNIX-compatible systems, and in the main installation directory (for
-example, F<C:\Program Files\Ethereal\preferences>) on Windows systems.
+  # Capture in promiscuous mode?
+  # TRUE or FALSE (case-insensitive).
+  capture.prom_mode: TRUE
+
+The global preferences file is looked for in the F<ethereal> directory
+under the F<share> subdirectory of the main installation directory (for
+example, F</usr/local/share/ethereal/preferences>) on UNIX-compatible
+systems, and in the main installation directory (for example,
+F<C:\Program Files\Ethereal\preferences>) on Windows systems.
 
-The personal preferences file, is searched in F<$HOME/.ethereal/preferences> on
+The personal preferences file is looked for in
+F<$HOME/.ethereal/preferences> on
 UNIX-compatible systems and F<%APPDATA%\Ethereal\preferences> (or, if
 %APPDATA% isn't defined, F<%USERPROFILE%\Application
 Data\Ethereal\preferences>) on Windows systems.
 
 =item Disabled (Enabled) Protocols
 
-The I<disabled_protos> file contains a list of
+The F<disabled_protos> files contain system-wide and personal lists of
 protocols that have been disabled, so that their dissectors are never
-called.  The file contains protocol names, one per line, where the
+called.  The files contain protocol names, one per line, where the
 protocol name is the same name that would be used in a display filter
-for the protocol.  A B<#> character starts a comment that runs to the
-end of the line. The same directory as for the personal preferences file is used.
+for the protocol:
+
+  http
+  tcp     # a comment
+
+The global F<disabled_protos> file uses the same directory as the global
+preferences file.
+
+The personal F<disabled_protos> file uses the same directory as the
+personal preferences file.
 
 =item Name Resolution (hosts)
 
-If the personal F<hosts> file exists, the entries in
-that file are used to resolve IPv4 and IPv6 addresses before any other
-attempts are made to resolve them.  That file has the standard F<hosts>
+If the personal F<hosts> file exists, it is
+used to resolve IPv4 and IPv6 addresses before any other
+attempts are made to resolve them.  The file has the standard F<hosts>
 file syntax; each line contains one IP address and name, separated by
-whitespace. The same directory as for the personal preferences file is used.
+whitespace. The same directory as for the personal preferences file is
+used.
 
 =item Name Resolution (ethers)
 
-The F<ethers> files, are consulted to correlate 6-byte hardware addresses to 
-names. First the global F<ethers> file is tried and if that address is not 
-found there the personal one is tried next.
+The F<ethers> files are consulted to correlate 6-byte hardware addresses to
+names. First the personal F<ethers> file is tried and if an address is not
+found there the global F<ethers> file is tried next.
 
-Each line contains one hardware address and
-name, separated by whitespace.  The digits of the hardware address are
-separated by either a colon (:), a dash (-), or a period (.).  The
-following three lines are valid lines of an F<ethers> file:
+Each line contains one hardware address and name, separated by
+whitespace.  The digits of the hardware address are separated by colons
+(:), dashes (-) or periods (.).  The same separator character must be
+used consistently in an address. The following three lines are valid
+lines of an F<ethers> file:
 
   ff:ff:ff:ff:ff:ff          Broadcast
   c0-00-ff-ff-ff-ff          TR_broadcast
   00.00.00.00.00.00          Zero_broadcast
 
-The global F<ethers> file is searched in the F</etc> directory on
+The global F<ethers> file is looked for in the F</etc> directory on
 UNIX-compatible systems, and in the main installation directory (for
 example, F<C:\Program Files\Ethereal>) on Windows systems.
 
-The personal F<ethers> file is searched in the same directory as the personal 
+The personal F<ethers> file is looked for in the same directory as the personal
 preferences file.
 
 =item Name Resolution (manuf)
@@ -881,25 +897,23 @@ preferences file.
 The F<manuf> file is used to match the 3-byte vendor portion of a 6-byte 
 hardware address with the manufacturer's name; it can also contain well-known 
 MAC addresses and address ranges specified with a netmask.  The format of the 
-file is the same as the F<ethers> file, except that entries of the form:
+file is the same as the F<ethers> files, except that entries of the form:
 
   00:00:0C      Cisco
 
 can be provided, with the 3-byte OUI and the name for a vendor, and
-entries of the form:
+entries such as:
 
   00-00-0C-07-AC/40     All-HSRP-routers
 
 can be specified, with a MAC address and a mask indicating how many bits
-of the address must match.  Trailing zero bytes can be omitted from
-address ranges.  That entry, for example, will match addresses from
-00-00-0C-07-AC-00 through 00-00-0C-07-AC-FF.  The mask need not be a
+of the address must match. The above entry, for example, has 40
+significant bits, or 5 bytes, and would match addresses from
+00-00-0C-07-AC-00 through 00-00-0C-07-AC-FF. The mask need not be a
 multiple of 8.
 
-The F<manuf> file is installed in the F<etc> directory under the
-main installation directory (for example, F</usr/local/etc/manuf>) on
-UNIX-compatible systems, and in the main installation directory (for
-example, F<C:\Program Files\Ethereal\manuf>) on Windows systems.
+The F<manuf> file is looked for in the same directory as the global
+preferences file.
 
 =item Name Resolution (ipxnets)
 
@@ -908,9 +922,9 @@ names. First the global F<ipxnets> file is tried and if that address is not
 found there the personal one is tried next.
 
 The format is the same as the F<ethers>
-file, except that each address if four bytes instead of six. 
-Additionally, the address can be represented a single hexadecimal
-number, as is more common in the IPX world, rather than four hex octets. 
+file, except that each address is four bytes instead of six.
+Additionally, the address can be represented as a single hexadecimal
+number, as is more common in the IPX world, rather than four hex octets.
 For example, these four lines are valid lines of an F<ipxnets> file:
 
   C0.A8.2C.00              HR
@@ -918,12 +932,12 @@ For example, these four lines are valid lines of an F<ipxnets> file:
   00:00:BE:EF              IT_Server1
   110f                     FileServer3
 
-The global F<ipxnets> file is found in the F</etc> directory on
+The global F<ipxnets> file is looked for in the F</etc> directory on
 UNIX-compatible systems, and in the main installation directory (for
 example, F<C:\Program Files\Ethereal>) on Windows systems.
 
-The personal F<ipxnets> file is searched in the same directory as the personal 
-preferences file.
+The personal F<ipxnets> file is looked for in the same directory as the
+personal preferences file.
 
 =back