make a complete redesign of the files section

svn path=/trunk/; revision=14547

1 files changed, 72 insertions, 50 deletions

diff --git a/doc/tethereal.pod b/doc/tethereal.pod
index 584a9b338c..012826cb97 100644
--- a/doc/tethereal.pod
+++ b/doc/tethereal.pod
@@ -805,17 +805,20 @@ in B<Tethereal> see the I<ethereal-filter(4)> manual page.
 
 =head1 FILES
 
-The global preferences file, F<preferences>, which is installed in the
-F<ethereal> directory under the F<share> subdirectory of the main
-installation directory (for example, F</usr/local/share/ethereal>) on
-UNIX-compatible systems, and in the main installation directory (for
-example, F<C:\Program Files\Ethereal>) on Windows systems, and the
-personal preferences file, which is 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, contain system-wide and
-personal preference settings, respectively.  The files contain
-preference settings of the form I<prefname>B<:>I<value>, one per line,
+These files contains various B<Ethereal> configuration values.
+
+=over 4
+
+=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>, 
+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
 which it should be set; white space is allowed between B<:> and
@@ -823,39 +826,41 @@ 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.
 
-The system-wide preference file is read first, if it exists, overriding
-B<Tethereal>'s default values; the personal preferences file is then
-read, if it exists, overriding default values and values read from the
-system-wide preference file.
+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.
+
+The personal preferences file, is searched 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 disabled protocols file, which is F<$HOME/.ethereal/disabled_protos>
-on UNIX-compatible systems and F<%APPDATA%\Ethereal\disabled_protos>
-(or, if %APPDATA% isn't defined, F<%USERPROFILE%\Application
-Data\Ethereal\disabled_protos>) on Windows systems, contain a list of
+The I<disabled_protos> file contains a list of
 protocols that have been disabled, so that their dissectors are never
 called.  The file contains 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.
+end of the line. The same directory as for the personal preferences file is used.
 
-If the personal F<hosts> file, in F<$HOME/.ethereal/hosts> file on
-UNIX-compatible systems, or the F<%APPDATA%\Ethereal\hosts> file (or, if
-%APPDATA% isn't defined, the F<%USERPROFILE%\Application
-Data\Ethereal\hosts> file) on Windows systems, exists, the entries in
+=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>
 file syntax; each line contains one IP address and name, separated by
-whitespace.
+whitespace. The same directory as for the personal preferences file is used.
 
-The global F<ethers> file, which is found 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, is consulted
-to correlate 6-byte hardware addresses to names.  If an address is not
-found in the global F<ethers> file, the personal F<ethers> file, in
-F<$HOME/.ethereal/ethers> on UNIX-compatible systems, and in
-F<%APPDATA%\Ethereal\ethers> (or, if %APPDATA% isn't defined, the
-F<%USERPROFILE%\Application Data\Ethereal\ethers> file) on Windows
-systems is consulted next.  Each line contains one hardware address and
+=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.
+
+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:
@@ -864,19 +869,24 @@ following three lines are valid lines of an F<ethers> file:
   c0-00-ff-ff-ff-ff          TR_broadcast
   00.00.00.00.00.00          Zero_broadcast
 
-The F<manuf> file, which is installed in the F<etc> directory under the
-main installation directory (for example, F</usr/local/etc>) on
+The global F<ethers> file is searched 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, matches 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
+example, F<C:\Program Files\Ethereal>) on Windows systems.
+
+The personal F<ethers> file is searched in the same directory as the personal 
+preferences file.
+
+=item Name Resolution (manuf)
+
+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:
 
   00:00:0C      Cisco
 
 can be provided, with the 3-byte OUI and the name for a vendor, and
-entries of the form
+entries of the form:
 
   00-00-0C-07-AC/40     All-HSRP-routers
 
@@ -886,15 +896,18 @@ 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
 multiple of 8.
 
-The global F<ipxnets> file, which is found in the F</etc> directory on
+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>) on Windows systems, correlates
-4-byte IPX network numbers to names.  If a network number is not found
-in the global F<ipxnets> file, the personal F<ipxnets> file, in
-F<$HOME/.ethereal/ipxnets> on UNIX-compatible systems, and in
-F<%APPDATA%\Ethereal\ipxnets> (or, if %APPDATA% isn't defined, the
-F<%USERPROFILE%\Application Data\Ethereal\ipxnets> file) on Windows
-systems, is consulted next.  The format is the same as the F<ethers>
+example, F<C:\Program Files\Ethereal\manuf>) on Windows systems.
+
+=item Name Resolution (ipxnets)
+
+The F<ipxnets> files are used to correlate 4-byte IPX network numbers to 
+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. 
@@ -905,6 +918,15 @@ 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
+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.
+
+=back
+
 =head1 SEE ALSO
 
 I<ethereal-filter(4)> I<ethereal(1)>, I<editcap(1)>, I<tcpdump(8)>, I<pcap(3)>