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

@@ -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
+  Emacs can display an indication of the @code{fill-column} position
-fill column indicator is a useful functionality especially in
+(@pxref{Fill Commands}).  The fill-column indicator is a useful
-@code{prog-mode} to indicate the position of a specific column.
+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.
 
-  You can set the buffer-local variables
+  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.
+
+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}}
+There are 2 buffer local variables and a face to customize this 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:
 
 @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
+take positive numerical values for the column, or the special value
-@code{t} which means that the variable @code{fill-column} will be
+@code{t}, which means that the value of the variable
-used.
+@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.
-
+The value @code{nil} disables the indicator.  When the mode is enabled
-When the mode is enabled through the functions
+through the functions @code{display-fill-column-indicator-mode} or
-@code{display-fill-column-indicator-mode} or
+@code{global-display-fill-column-indicator-mode}, they will use the
-@code{global-display-fill-column-indicator-mode}, the initialization
+character specified by this variable, if it is non-@code{nil};
-functions check if this variable is non-@code{nil}, otherwise the
+otherwise Emacs will use the character @samp{U+2502 VERTICAL LINE},
-initialization tries to set it to @code{U+2502} or @samp{|}.
+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
+default values from the face @code{shadow}, but without background
-color.  To change the indicator color you need only set the foreground
+color.  To change the indicator color, you need only set the foreground
 color of this face.
 @end table
 

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

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)
+A good candidate is U+2502, and an alternative is (ascii 124) if the
-if the font in fill-column-indicator face does not support Unicode characters.
+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");