FAQ 2 - Color XTerm

There is a discrepancy between the xterm(1) man page and FAQ-2
regarding the "correct" way to enable color display of man pages.

I've limited the changes to the following:

	#1: Added the suggested method from xterm(1) as the first way
	to do it. 
	
	#2: Retained the previously suggested method of copying the 
	entire contents of /etc/X11/app-defaults/XTerm-color file into
	the users ~/.Xdefaults

	#3: Gave a (possibly) better (or at least less breakable) method
	for using /etc/X11/app-defaults/XTerm-color

Questions:

1.) I'm not sure if #2 is still wanted considering #1 and #3?

2.) There are a lot of lines ending in a space. Should I fix those 
as well?

3.) I've already done all the work to "promote" the various questions 
in the "manual pages" section to actual numbered FAQ items. Since I'm 
unsure if this is a desired change, I haven't included it in this diff. 
Please let me know?

Since Nick's personal "faq-help.html" page suggests creating diffs from
the www/faq/ directory, I did it as suggested rather than from the top
of the www branch.

# cd /usr/www/faq
# cvs diff -u faq2.html >/home/arc/diff_www_faq_faq2_html.diff


Index: faq2.html
===================================================================
RCS file: /cvs/www/faq/faq2.html,v
retrieving revision 1.90
diff -u -r1.90 faq2.html
--- faq2.html	1 Nov 2006 01:41:18 -0000	1.90
+++ faq2.html	1 Apr 2007 17:24:02 -0000
@@ -478,14 +478,58 @@
 <h3>How do I get color man pages on XTerm?</h3>
 
 <p>
-The default configuration file for
-<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=xterm&amp;sektion=1">xterm(1)</a> does not display color man pages.
-In order to get color output, copy the file 
-<tt>/etc/X11/app-defaults/XTerm-color</tt>
-to your home directory, and rename it "<tt>.Xdefaults</tt>".
-Be careful not to overwrite any current settings in "<tt>.Xdefaults</tt>".
-This file contains all the settings you need to enable color in XTerm.
-However, three lines need to be uncommented before this can work:
+The default configuration file for <a
+href="http://www.openbsd.org/cgi-bin/man.cgi?query=xterm&amp;sektion=1"
+>xterm(1)</a> does not display man pages with color.
+In order to get color output in xterm, add the following lines to the
+<tt>~/.Xresources</tt> file in your home directory (create this file if
+the file does not already exist):
+
+<blockquote>
+<pre>
+xterm*customization: -color
+*VT100*colorULMode: on
+*VT100*underLine: off
+*VT100*colorBDMode: on
+</pre>
+</blockquote>
+
+Though not entirely necessary, it is also wise to set the $TERM variable
+to "<tt>xterm-color</tt>" so applications running in the xterm can tell
+if color support is available.
+You can do this in your shell resource file (such as <tt>~/.kshrc</tt>)
+or more easily, by adding one more line to your <tt>~/.Xresources</tt>
+file:
+
+<blockquote>
+<pre>
+xterm*termName: xterm-color
+</pre>
+</blockquote>
+
+After making changes to your <tt>~/.Xresources</tt> file you will need
+to either restart the X Window System or make the X Resources Database
+aware of the changes with <a
+href="http://www.openbsd.org/cgi-bin/man.cgi?query=xrdb&amp;sektion=1"
+>xrdb(1)</a>:
+
+<blockquote>
+<pre>
+$ <b>xrdb -merge ~/.Xresources</b>
+</pre>
+</blockquote>
+
+<p>
+You will also need to restart any <a
+href="http://www.openbsd.org/cgi-bin/man.cgi?query=xterm&amp;sektion=1"
+>xterm(1)</a> sessions which you have open for the changes to take
+effect.
+
+<p>
+An alternative to the above approach is to copy the contents of
+<tt>/etc/X11/app-defaults/XTerm-color</tt> into the
+<tt>~/.Xdefaults</tt> in your home directory and uncomment the
+following three lines by removing the ! at the start of the line:
 
 <blockquote>
 <pre>
@@ -495,23 +539,51 @@
 </pre>
 </blockquote>
 
-The rest of this file allows you to choose colors for various settings.
-The relevant ones to the man pages are:
+<p>
+Since the above approach might break during system upgrades due to
+changes made to <tt>/etc/X11/app-defaults/XTerm-color</tt>, a better
+approach is to just include the default file and alter the needed
+parameters by adding the following lines to the <tt>~/.Xresources</tt>
+file in your home directory:
 
 <blockquote>
 <pre>
-*VT100*colorUL: yellow
-*VT100*colorBD: white
+#include "/etc/X11/app-defaults/XTerm-color"
+*VT100*colorULMode: on
+*VT100*underLine: off
+*VT100*colorBDMode: on
 </pre>
 </blockquote>
 
-That produces rather hellish looking man pages, so customise as necessary:
-may we suggest red for "colorUL" and magenta for "colorBD"?
+<p>
+Some consider the default colors used for bold or underlined text in man
+pages to be ugly but you can change them easily by adding the following
+lines to your <tt>~/.Xresources</tt> file:
 
-There is also a man page viewer for X11 available,
-<a href="http://www.openbsd.org/cgi-bin/man.cgi?query=xman&amp;sektion=1">xman(1)</a>,
-which provides an alternative (graphical) interface to the manual pages.
+<blockquote>
+<pre>
+*VT100*colorBD: red
+*VT100*colorUL: magenta
+</pre>
+</blockquote>
+
+<p>
+The textual names of the colors (i.e. &quot;red&quot;,
+&quot;blue&quot; and etc.), are defined in
+<tt>/etc/X11/app-defaults/XTerm-color</tt> can be redefined in either
+the <tt>~/.Xresources</tt> or <tt>~/.Xdefaults</tt> files in your home
+directory.
+What colors will work on your system is dependent on your hardware.
+
+<p>
+There is also a man page viewer for X11 available, <a
+href="http://www.openbsd.org/cgi-bin/man.cgi?query=xman&amp;sektion=1"
+>xman(1)</a>, which provides an alternative (graphical) interface to the
+manual pages.
+You can also configure colors for xman through either the
+<tt>~/.Xresources</tt> or <tt>~/.Xdefaults</tt> files.
 See the manual pages for xterm and xman for more information.
+
 
 <h3>How do I write my own manual page?</h3>