Add documentation for display-line-numbers

* doc/emacs/custom.texi (Init Rebinding):
* doc/emacs/modes.texi (Minor Modes): Remove references to
linum-mode.
* doc/emacs/display.texi (Display Custom): Describe the
line-number display.
(Optional Mode Line): Fix the index entry to not conflict with
that in "Display Custom".
* doc/emacs/basic.texi (Position Info): Add cross-reference to
"Display Custom", for line-number display.

* src/xdisp.c (syms_of_xdisp): <display-line-numbers>: Mention
display-line-numbers-disable in the doc string.

* lisp/cus-start.el (standard): Fix lst change.

7 files changed, 64 insertions, 11 deletions

diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi
index 6b66c18016b..5878e7da256 100644
--- a/doc/emacs/basic.texi
+++ b/doc/emacs/basic.texi
@@ -630,7 +630,8 @@ Display the line number of point.
 @item M-x line-number-mode
 @itemx M-x column-number-mode
 Toggle automatic display of the current line number or column number.
-@xref{Optional Mode Line}.
+@xref{Optional Mode Line}.  If you want to have a line number
+displayed before each line, see @ref{Display Custom}.
 
 @item M-=
 Display the number of lines, words, and characters that are present in
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi
index c84f4a975d8..a756a89e3f8 100644
--- a/doc/emacs/custom.texi
+++ b/doc/emacs/custom.texi
@@ -1701,7 +1701,6 @@ and mouse events:
 (global-set-key (kbd "C-c y") 'clipboard-yank)
 (global-set-key (kbd "C-M-q") 'query-replace)
 (global-set-key (kbd "<f5>") 'flyspell-mode)
-(global-set-key (kbd "C-<f5>") 'linum-mode)
 (global-set-key (kbd "C-<right>") 'forward-sentence)
 (global-set-key (kbd "<mouse-2>") 'mouse-save-then-kill)
 @end example
diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index c4554eb3187..61ca7e24f84 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -1333,7 +1333,7 @@ characters in the buffer, which means that @samp{k} for 10^3, @samp{M}
 for 10^6, @samp{G} for 10^9, etc., are used to abbreviate.
 
 @cindex line number display
-@cindex display of line number
+@cindex display of current line number
 @findex line-number-mode
   The current line number of point appears in the mode line when Line
 Number mode is enabled.  Use the command @kbd{M-x line-number-mode} to
@@ -1710,6 +1710,58 @@ variable @code{visual-line-fringe-indicators}.
   This section describes variables that control miscellaneous aspects
 of the appearance of the Emacs screen.  Beginning users can skip it.
 
+@vindex display-line-numbers
+@cindex number lines in a buffer
+@cindex display line numbers
+  If you want to have Emacs display line numbers for every line in the
+buffer, customize the buffer-local variable
+@code{display-line-numbers}; it is @code{nil} by default.  This
+variable can have several different values to support various modes of
+line-number display:
+
+@table @asis
+@item @code{t}
+Display (an absolute) line number before each non-continuation screen
+line that displays buffer text.  If the line is a continuation line,
+or if the entire screen line displays a display or an overlay string,
+that line will not be numbered.
+
+@item @code{relative}
+Display relative line numbers before non-continuation lines which show
+buffer text.  The line numbers are relative to the line showing point,
+so the numbers grow both up and down as lines become farther from the
+current line.
+
+@item @code{visual}
+This value causes Emacs to count lines visually: only lines actually
+shown on the display will be counted (disregarding any lines in
+invisible parts of text), and lines which wrap to consume more than
+one screen line will be numbered that many times.  The displayed
+numbers are relative, as with @code{relative} value above.  This is
+handy in modes that fold text, such as Outline mode (@pxref{Outline
+Mode}), and need to move by exact number of screen lines.
+
+@item anything else
+Any other non-@code{nil} value is treated as @code{t}.
+@end table
+
+@vindex display-line-numbers-current-absolute
+When Emacs displays relative line numbers, you can control the number
+displayed before the current line, the line showing point.  By
+default, Emacs displays the absolute number of the current line there,
+even though all the other line numbers are relative.  If you customize
+the variable @code{display-line-numbers-current-absolute} to a
+@code{nil} value, the number displayed for the current line will be
+zero.  This is handy if you don't care about the number of the current
+line, and want to leave more horizontal space for text in large
+buffers.
+
+The line numbers are displayed in a special face @code{line-number}.
+The current line number is displayed in a different face,
+@code{line-number-current-line}, so you can make the current line's
+number have a distinct appearance, which will help locating the line
+showing point.
+
 @vindex visible-bell
   If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts
 to make the whole screen blink when it would normally make an audible bell
diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi
index be893403012..eb0c88b2901 100644
--- a/doc/emacs/modes.texi
+++ b/doc/emacs/modes.texi
@@ -225,11 +225,6 @@ Font-Lock mode automatically highlights certain textual units found in
 programs.  It is enabled globally by default, but you can disable it
 in individual buffers.  @xref{Faces}.
 
-@findex linum-mode
-@cindex Linum mode
-@item
-Linum mode displays each line's line number in the window's left margin.
-
 @item
 Outline minor mode provides similar facilities to the major mode
 called Outline mode.  @xref{Outline Mode}.
diff --git a/etc/NEWS b/etc/NEWS
index 9f4c3bbb3e0..b50c770c505 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -377,6 +377,7 @@ display of raw bytes from octal to hex.
 ** You can now provide explicit field numbers in format specifiers.
 For example, '(format "%2$s %1$s" "X" "Y")' produces "Y X".
 
++++
 ** Emacs now supports optional display of line numbers in the buffer.
 This is similar to what linum-mode provides, but much faster and
 doesn't usurp the display margin for the line numbers.  Customize the
@@ -410,7 +411,7 @@ specify a fixed minimal with of the area allocated to line-number
 display.  The default is nil, meaning that Emacs will dynamically
 calculate the area width, enlarging or shrinking it as needed.
 Setting it to a non-negative integer specifies that as the minimal
-width; selecting a value that is large enough to display all line
+width; selecting a value  that is large enough to display all line
 numbers in a buffer will then keep the line-number display area of
 constant width at all times, if that is desired.
 
diff --git a/lisp/cus-start.el b/lisp/cus-start.el
index ed17113c784..a89d5dff0cd 100644
--- a/lisp/cus-start.el
+++ b/lisp/cus-start.el
@@ -602,7 +602,7 @@ since it could result in memory overflow and make Emacs crash."
                                            :value 2
                                            :format "%v"))
                                  "26.1")
-             (display-line-numbers-current-absolute
+             (display-line-numbers-current-absolute display
                                  (choice
                                   (const :tag "Display actual number of current line"
                                          :value t)
diff --git a/src/xdisp.c b/src/xdisp.c
index 7851487e74e..bcd7d33332f 100644
--- a/src/xdisp.c
+++ b/src/xdisp.c
@@ -32567,7 +32567,12 @@ To add a prefix to continuation lines, use `wrap-prefix'.  */);
 By default, line numbers are displayed before each non-continuation
 line that displays buffer text, i.e. after each newline that came
 from buffer text.  However, if the value is `visual', every screen
-line will have a number.  */);
+line will have a number.
+
+Lisp programs can disable display of a line number of a particular
+screen line by putting the `display-line-numbers-disable' text
+property or overlay property on the first visible character of
+that line.  */);
   Vdisplay_line_numbers = Qnil;
   DEFSYM (Qdisplay_line_numbers, "display-line-numbers");
   Fmake_variable_buffer_local (Qdisplay_line_numbers);