From e83b128a8195e5c63f12832decf70c2953821dc0 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Fri, 30 Jun 2017 17:33:06 +0300 Subject: [PATCH] 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): : 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 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 "") 'flyspell-mode) -(global-set-key (kbd "C-") 'linum-mode) (global-set-key (kbd "C-") 'forward-sentence) (global-set-key (kbd "") '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); -- 2.39.2