2 files changed, 38 insertions, 2 deletions

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 2d67aec0eab..566fab45fbf 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,9 @@
+2010-08-08  Jay Belanger  <jay.p.belanger@gmail.com>
+
+        * calc.texi (Making Selections, Selecting Subformulas)
+        (Customizing Calc): Mention how to use faces to emphasize selected
+        sub-formulas.
+
 2010-08-05  Michael Albinus  <michael.albinus@gmx.de>
 
         * tramp.texi (External packages): File attributes cache flushing
diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi
index ab81cf1bca2..5e4fc5c8486 100644
--- a/doc/misc/calc.texi
+++ b/doc/misc/calc.texi
@@ -21513,7 +21513,11 @@ to
 
 @noindent
 Every character not part of the sub-formula @samp{b} has been changed
-to a dot.  The @samp{*} next to the line number is to remind you that
+to a dot. (If the customizable variable
+@code{calc-highlight-selections-with-faces} is non-nil, then the characters
+not part of the sub-formula are de-emphasized by using a less
+noticeable face instead of using dots. @pxref{Displaying Selections}.)
+The @samp{*} next to the line number is to remind you that
 the formula has a portion of it selected.  (In this case, it's very
 obvious, but it might not always be.  If Embedded mode is enabled,
 the word @samp{Sel} also appears in the mode line because the stack
@@ -21726,6 +21730,9 @@ of the hierarchy simply by pointing to it with the cursor.
 @noindent
 @kindex j d
 @pindex calc-show-selections
+@vindex calc-highlight-selections-with-faces
+@vindex calc-selected-face
+@vindex calc-nonselected-face
 The @kbd{j d} (@code{calc-show-selections}) command controls how
 selected sub-formulas are displayed.  One of the alternatives is
 illustrated in the above examples; if we press @kbd{j d} we switch
@@ -21740,6 +21747,13 @@ by @samp{#} signs:
         . . . .                   2 x + 1
 @end group
 @end smallexample
+If the customizable variable
+@code{calc-highlight-selections-with-faces} is non-nil, then the
+non-selected portion of the formula will be de-emphasized by using a
+less noticeable face (@code{calc-nonselected-face}) instead of dots
+and the selected sub-formula will be highlighted by using a more
+noticeable face (@code{calc-selected-face}) instead of @samp{#}
+signs. (@pxref{Customizing Calc}.)
 
 @node Operating on Selections, Rearranging with Selections, Displaying Selections, Selecting Subformulas
 @subsection Operating on Selections
@@ -34911,7 +34925,7 @@ character of the prefix can simply be typed twice.
 
 Calc is controlled by many variables, most of which can be reset
 from within Calc.  Some variables are less involved with actual
-calculation, and can be set outside of Calc using Emacs's
+calculation and can be set outside of Calc using Emacs's
 customization facilities.  These variables are listed below.
 Typing @kbd{M-x customize-variable RET @var{variable-name} RET}
 will bring up a buffer in which the variable's value can be redefined.
@@ -35197,6 +35211,22 @@ should also be added to @code{calc-embedded-announce-formula-alist}
 and @code{calc-embedded-open-close-plain-alist}.
 @end defvar
 
+@defvar calc-highlight-selections-with-faces
+@defvarx calc-selected-face
+@defvarx calc-nonselected-face
+The variable @code{calc-highlight-selections-with-faces} 
+determines how selected sub-formulas are distinguished.
+If @code{calc-highlight-selections-with-faces} is nil, then 
+a selected sub-formula is distinguished either by changing every
+character not part of the sub-formula with a dot or by changing every
+character in the sub-formula with a @samp{#} sign.  
+If @code{calc-highlight-selections-with-faces} is t,
+then a selected sub-formula is distinguished either by displaying the
+non-selected portion of the formula with @code{calc-nonselected-face} 
+or by displaying the selected sub-formula with
+@code{calc-nonselected-face}. (@pxref{Displaying Selections}.)
+@end defvar
+
 @defvar calc-multiplication-has-precedence
 The variable @code{calc-multiplication-has-precedence} determines
 whether multiplication has precedence over division in algebraic