[Emacs-diffs] scratch/line-numbers e83b128 9/9: Add documentation for display-line-numbers

[Eli Zaretskii]

branch: scratch/line-numbers
commit e83b128a8195e5c63f12832decf70c2953821dc0
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    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.
---
 doc/emacs/basic.texi   |  3 ++-
 doc/emacs/custom.texi  |  1 -
 doc/emacs/display.texi | 54 +++++++++++++++++++++++++++++++++++++++++++++++++-
 doc/emacs/modes.texi   |  5 -----
 etc/NEWS               |  3 ++-
 lisp/cus-start.el      |  2 +-
 src/xdisp.c            |  7 ++++++-
 7 files changed, 64 insertions(+), 11 deletions(-)

diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi
index 6b66c18..5878e7d 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.
address@hidden Mode Line}.
address@hidden 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 c84f4a9..a756a89 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 c4554eb..61ca7e2 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
address@hidden display of line number
address@hidden 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.
 
address@hidden display-line-numbers
address@hidden number lines in a buffer
address@hidden display line numbers
+  If you want to have Emacs display line numbers for every line in the
+buffer, customize the buffer-local variable
address@hidden; it is @code{nil} by default.  This
+variable can have several different values to support various modes of
+line-number display:
+
address@hidden @asis
address@hidden @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.
+
address@hidden @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.
+
address@hidden @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.
+
address@hidden anything else
+Any other address@hidden value is treated as @code{t}.
address@hidden table
+
address@hidden 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
address@hidden 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,
address@hidden, 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 address@hidden, 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 be89340..eb0c88b 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}.
 
address@hidden linum-mode
address@hidden Linum mode
address@hidden
-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 9f4c3bb..b50c770 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 ed17113..a89d5df 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 7851487..bcd7d33 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);