Document the "-o" flag, the fact that the "Preferences" dialog box has

pages for various protocol preferences, and the existence of the global
and personal preferences files.

We still need to document the values that can be put in the preferences
file.

svn path=/trunk/; revision=2127

2 files changed, 58 insertions, 0 deletions

diff --git a/doc/ethereal.pod.template b/doc/ethereal.pod.template
index df9e030e2d..62c918f107 100644
--- a/doc/ethereal.pod.template
+++ b/doc/ethereal.pod.template
@@ -16,6 +16,7 @@ S<[ B<-i> interface ]>
 S<[ B<-k> ]>
 S<[ B<-m> font ]>
 S<[ B<-n> ]>
+S<[ B<-o> preference setting ] ...>
 S<[ B<-P> packet list height ]>
 S<[ B<-Q> ]>
 S<[ B<-r> infile ]>
@@ -123,6 +124,14 @@ Sets the name of the font used by B<Ethereal> for most text.
 Disables network object name resolution (such as hostname, TCP and UDP port
 names).
 
+=item -o
+
+Sets a preference value, overriding the default value and any value read
+from a preference 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 (which is the same name that would appear in the preference
+file), and I<value> is the value to which it should be set.
+
 =item -P
 
 Sets the initial height of the packet list (top) pane.
@@ -458,6 +467,11 @@ until you press the space bar. If the selection bar has a "select"
 behavior, the arrow keys will move the selection bar and change
 the selection to the new item in the packet list or protocol tree.
 
+=item Protocol Preferences
+
+There are also pages for various protocols that Ethereal dissects,
+controlling the way Ethereal handles those protocols.
+
 =back
 
 =item Filters
@@ -762,6 +776,26 @@ type of the field is also given.
 
 =head1 FILES
 
+F</usr/local/etc/ethereal.conf> and F<$HOME/.ethereal/preferences>
+contain system-wide and personal preference settings, respectively.  The
+file contains preference settings of 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 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<Ethereal>'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.
+
+Note that whenever the preferences are saved by using the I<Save> button
+in the I<Edit:Preferences> dialog box, F<$HOME/.ethereal/preferences>
+will be overwritten with the new settings, destroying any comments that
+were in the file.
+
 F</etc/ethers> is consulted to correlate 6-byte hardware addresses to
 names.  If an address is not found in F</etc/ethers>, the
 F<$HOME/.ethereal/ethers> file is consulted next.  Each line contains
diff --git a/doc/tethereal.pod.template b/doc/tethereal.pod.template
index 19649e5581..6b08e5a54e 100644
--- a/doc/tethereal.pod.template
+++ b/doc/tethereal.pod.template
@@ -13,6 +13,7 @@ S<[ B<-F> file format ]>
 S<[ B<-h> ]>
 S<[ B<-i> interface ]> 
 S<[ B<-n> ]>
+S<[ B<-o> preference setting ] ...>
 S<[ B<-r> infile ]>
 S<[ B<-R> filter expression ]>
 S<[ B<-s> snaplen ]>
@@ -133,6 +134,14 @@ interfaces, B<Tethereal> reports an error and doesn't start the capture.
 Disables network object name resolution (such as hostname, TCP and UDP port
 names).
 
+=item -o
+
+Sets a preference value, overriding the default value and any value read
+from a preference 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 (which is the same name that would appear in the preference
+file), and I<value> is the value to which it should be set.
+
 =item -r
 
 Reads packet data from I<file>.
@@ -380,6 +389,21 @@ type of the field is also given.
 
 =head1 FILES
 
+F</usr/local/etc/ethereal.conf> and F<$HOME/.ethereal/preferences>
+contain system-wide and personal preference settings, respectively.  The
+file contains preference settings of 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 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.
+
 F</etc/ethers> is consulted to correlate 6-byte hardware addresses to
 names.  If an address is not found in F</etc/ethers>, the
 F<$HOME/.ethereal/ethers> file is consulted next.  Each line contains