emacs-27 20c02e6: Improve documentation of display-fill-column-indicator

[Eli Zaretskii]

branch: emacs-27
commit 20c02e628cb6126457e675d824d51ad4286c7c7a
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Improve documentation of display-fill-column-indicator
    
    * lisp/display-fill-column-indicator.el
    (display-fill-column-indicator-mode): Mention the globalized
    version in the doc string.
    
    * doc/emacs/display.texi (Displaying Boundaries): Improve and
    clarify the documentation of display-fill-column-indicator.
    Suggest using the minor mode as the primary means for turning the
    feature on.
    
    * src/xdisp.c (syms_of_xdisp) <display-fill-column-indicator>
    <display-fill-column-indicator-character>: Doc fix.  (Bug#44226)
---
 doc/emacs/display.texi                | 51 ++++++++++++++++++-----------------
 lisp/display-fill-column-indicator.el |  2 ++
 src/xdisp.c                           |  6 +++--
 3 files changed, 33 insertions(+), 26 deletions(-)

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index a4040d9..ed2fa8b 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -1173,31 +1173,34 @@ right-to-left paragraphs.
 @cindex mode, display-fill-column-indicator
 @findex display-fill-column-indicator-mode
 @findex global-display-fill-column-indicator-mode
-  Emacs can add an indicator to display a fill column position.  The
-fill column indicator is a useful functionality especially in
-@code{prog-mode} to indicate the position of a specific column.
+  Emacs can display an indication of the @code{fill-column} position
+(@pxref{Fill Commands}).  The fill-column indicator is a useful
+functionality especially in @code{prog-mode} and its descendants
+(@pxref{Major Modes}) to indicate the position of a specific column
+that has some special meaning for formatting the source code of a
+program.
+
+  To activate the fill-column indication display, use the minor modes
+@w{@kbd{M-x display-fill-column-indicator-mode}} and
+@w{@kbd{M-x global-display-fill-column-indicator-mode}}, which enable
+the indicator locally or globally, respectively.
 
-  You can set the buffer-local variables
+Alternatively, you can set the two buffer-local variables
 @code{display-fill-column-indicator} and
 @code{display-fill-column-indicator-character} to activate the
-indicator and control how it looks, respectively.
+indicator and control the character used for the indication.  Note
+that both variables must be non-@code{nil} for the indication to be
+displayed.  (Turning on the minor mode sets both these variables.)
 
-Alternatively you can type @w{@kbd{M-x display-fill-column-indicator-mode}}
-or @w{@kbd{M-x global-display-fill-column-indicator-mode}} which
-enables the indicator locally or globally, respectively, and also
-chooses the character to use if none is already set.  It is possible
-to use the first one to activate the indicator in a hook and the
-second one to enable it globally.
-
-There are 2 buffer local variables and 1 face to customize this mode:
+There are 2 buffer local variables and a face to customize this mode:
 
 @table @code
 @item display-fill-column-indicator-column
 @vindex display-fill-column-indicator-column
 Specifies the column number where the indicator should be set.  It can
-take positive numerical values for the column or the special value
-@code{t} which means that the variable @code{fill-column} will be
-used.
+take positive numerical values for the column, or the special value
+@code{t}, which means that the value of the variable
+@code{fill-column} will be used.
 
 Any other value disables the indicator.  The default value is @code{t}.
 
@@ -1205,18 +1208,18 @@ Any other value disables the indicator.  The default 
value is @code{t}.
 @vindex display-fill-column-indicator-character
 Specifies the character used for the indicator.  This character can be
 any valid character including Unicode ones if the font supports them.
-
-When the mode is enabled through the functions
-@code{display-fill-column-indicator-mode} or
-@code{global-display-fill-column-indicator-mode}, the initialization
-functions check if this variable is non-@code{nil}, otherwise the
-initialization tries to set it to @code{U+2502} or @samp{|}.
+The value @code{nil} disables the indicator.  When the mode is enabled
+through the functions @code{display-fill-column-indicator-mode} or
+@code{global-display-fill-column-indicator-mode}, they will use the
+character specified by this variable, if it is non-@code{nil};
+otherwise Emacs will use the character @samp{U+2502 VERTICAL LINE},
+falling back to @samp{|} if @code{U+2502} cannot be displayed.
 
 @item fill-column-indicator
 @vindex fill-column-indicator
 Specifies the face used to display the indicator.  It inherits its
-default values from the face @code{shadow} but without background
-color.  To change the indicator color you need only set the foreground
+default values from the face @code{shadow}, but without background
+color.  To change the indicator color, you need only set the foreground
 color of this face.
 @end table
 
diff --git a/lisp/display-fill-column-indicator.el 
b/lisp/display-fill-column-indicator.el
index 3391aa3..2013fb1 100644
--- a/lisp/display-fill-column-indicator.el
+++ b/lisp/display-fill-column-indicator.el
@@ -51,6 +51,8 @@ This uses `display-fill-column-indicator' internally.
 To change the position of the column displayed by default
 customize `display-fill-column-indicator-column'.  You can change the
 character for the indicator setting `display-fill-column-indicator-character'.
+The globalized version is `global-display-fill-column-indicator-mode',
+which see.
 See Info node `Displaying Boundaries' for details."
   :lighter nil
   (if display-fill-column-indicator-mode
diff --git a/src/xdisp.c b/src/xdisp.c
index 03dc4be..6c14a9a 100644
--- a/src/xdisp.c
+++ b/src/xdisp.c
@@ -35025,6 +35025,8 @@ It has no effect when set to 0, or when line numbers 
are not absolute.  */);
 
   DEFVAR_BOOL ("display-fill-column-indicator", Vdisplay_fill_column_indicator,
     doc: /* Non-nil means display the fill column indicator.
+If you set this non-nil, make sure `display-fill-column-indicator-character'
+is also non-nil.
 See Info node `Displaying Boundaries' for details.  */);
   Vdisplay_fill_column_indicator = false;
   DEFSYM (Qdisplay_fill_column_indicator, "display-fill-column-indicator");
@@ -35042,8 +35044,8 @@ See Info node `Displaying Boundaries' for details.  */);
 
   DEFVAR_LISP ("display-fill-column-indicator-character", 
Vdisplay_fill_column_indicator_character,
     doc: /* Character to draw the indicator when 
`display-fill-column-indicator' is non-nil.
-The default is U+2502 but a good alternative is (ascii 124)
-if the font in fill-column-indicator face does not support Unicode characters.
+A good candidate is U+2502, and an alternative is (ascii 124) if the
+font of `fill-column-indicator' face does not support Unicode characters.
 See Info node `Displaying Boundaries' for details.  */);
   Vdisplay_fill_column_indicator_character = Qnil;
   DEFSYM (Qdisplay_fill_column_indicator_character, 
"display-fill-column-indicator-character");