From 9e79f199ffad18a58c8031d347e8cfb297e12407 Mon Sep 17 00:00:00 2001 From: Alexander Gramiak Date: Thu, 4 Apr 2019 11:31:43 -0600 Subject: ; * src/fontset.c (set-fontset-font): Use uppercase arg in docstring --- src/fontset.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/fontset.c b/src/fontset.c index 8e0c5746fe7..34e0c0d4820 100644 --- a/src/fontset.c +++ b/src/fontset.c @@ -1447,7 +1447,7 @@ or t for the default fontset. TARGET may be a single character to use FONT-SPEC for. -Target may be a cons (FROM . TO), where FROM and TO are characters. +TARGET may be a cons (FROM . TO), where FROM and TO are characters. In that case, use FONT-SPEC for all the characters in the range between FROM and TO (inclusive). -- cgit v1.2.1 From a8cffcf27f4d4f7e35462e2ccb011d231f1a61cc Mon Sep 17 00:00:00 2001 From: Mauro Aranda Date: Fri, 5 Apr 2019 17:40:12 -0300 Subject: Fix typo in a doc string * lisp/autorevert.el (global-auto-revert-mode): Fix a typo. (Bug#35165) --- lisp/autorevert.el | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lisp/autorevert.el b/lisp/autorevert.el index 242344fe9d1..58c5dba3160 100644 --- a/lisp/autorevert.el +++ b/lisp/autorevert.el @@ -472,7 +472,7 @@ If `global-auto-revert-non-file-buffers' is non-nil, this mode may also revert some non-file buffers, as described in the documentation of that variable. It ignores buffers with modes matching `global-auto-revert-ignore-modes', and buffers with a -non-nil vale of `global-auto-revert-ignore-buffer'. +non-nil value of `global-auto-revert-ignore-buffer'. When a buffer is reverted, a message is generated. This can be suppressed by setting `auto-revert-verbose' to nil. -- cgit v1.2.1 From 6dc42c562c5ae3ca5a7d7eb4223cd82554e3cfad Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 6 Apr 2019 10:16:16 +0300 Subject: Improve commentary in frame.el * lisp/frame.el: Improve commentary for display-* functions. (Bug#35058) --- lisp/frame.el | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/lisp/frame.el b/lisp/frame.el index 9438b4a72ed..a0e62e1d69d 100644 --- a/lisp/frame.el +++ b/lisp/frame.el @@ -1691,6 +1691,14 @@ for FRAME." ;;;; Frame/display capabilities. +;; These functions should make the features they test explicit in +;; their names, so that when capabilities or the corresponding Emacs +;; features change, it will be easy to find all the tests for such +;; capabilities by a simple text search. See more about the history +;; and the intent of these functions in +;; http://lists.gnu.org/archive/html/bug-gnu-emacs/2019-04/msg00004.html +;; or in https://debbugs.gnu.org/cgi/bugreport.cgi?bug=35058#17. + (declare-function msdos-mouse-p "dosfns.c") (defun display-mouse-p (&optional display) -- cgit v1.2.1 From 92ce2dd48bd3f31b848f0258ad79af01a7197b44 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 6 Apr 2019 11:04:37 +0300 Subject: Improve documentation of window parameters * doc/lispref/windows.texi (Cyclic Window Ordering): Describe the effect of the 'other-window' window parameter. (Window Parameters): Improve the descriptions of window parameters. Move the detailed description of the 'quit-restore' window parameter from here... (Quitting Windows): ...to here. (Bug#35063) --- doc/lispref/windows.texi | 93 ++++++++++++++++++++++++++---------------------- 1 file changed, 51 insertions(+), 42 deletions(-) diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 7f0fcffaaf1..27940e12c79 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -1956,7 +1956,13 @@ The optional argument @var{all-frames} has the same meaning as in @code{next-window}. This function does not select a window that has a non-@code{nil} -@code{no-other-window} window parameter (@pxref{Window Parameters}). +@code{no-other-window} window parameter (@pxref{Window Parameters}), +provided that @code{ignore-window-parameters} is @code{nil}. + +If the @code{other-window} parameter of the selected window is a +function, and @code{ignore-window-parameters} is @code{nil}, that +function will be called with the arguments @var{count} and +@var{all-frames} instead of the normal operation of this function. @end deffn @defun walk-windows fun &optional minibuf all-frames @@ -3903,8 +3909,33 @@ described next to deal with the window and its buffer. This function handles @var{window} and its buffer after quitting. The optional argument @var{window} must be a live window and defaults to the selected one. The function's behavior is determined by the four -elements of the @code{quit-restore} window parameter (@pxref{Window -Parameters}), which is set to @code{nil} afterwards. +elements of the list specified by the @code{quit-restore} window +parameter (@pxref{Window Parameters}), which is set to @code{nil} +afterwards. + +The first element of the @code{quit-restore} parameter is one of the +symbols @code{window}, meaning that the window has been specially +created by @code{display-buffer}; @code{frame}, a separate frame has +been created; @code{same}, the window has only ever displayed this +buffer; or @code{other}, the window showed another buffer before. +@code{frame} and @code{window} affect how the window is quit, while +@code{same} and @code{other} affect the redisplay of buffers +previously shown in this window. + +The second element is either one of the symbols @code{window} or +@code{frame}, or a list whose elements are the buffer shown in the +window before, that buffer's window start and window point positions, +and the window's height at that time. If that buffer is still live +when the window is quit, then the function @code{quit-restore-window} +reuses the window to display the buffer. + +The third element is the window selected at the time the parameter was +created. If @code{quit-restore-window} deletes the window passed to +it as argument, it then tries to reselect this window. + +The fourth element is the buffer whose display caused the creation of +this parameter. @code{quit-restore-window} deletes the specified window +only if it still shows that buffer. The window is deleted entirely if: 1) the first element of the @code{quit-restore} parameter is one of 'window or 'frame, 2) the @@ -5754,8 +5785,8 @@ and heights, if possible. Frames are not resized by this function. @section Window Parameters @cindex window parameters -This section describes how window parameters can be used to associate -additional information with windows. +This section describes the window parameters that can be used to +associate additional information with windows. @defun window-parameter window parameter This function returns @var{window}'s value for @var{parameter}. The @@ -5888,44 +5919,21 @@ parameter is installed and updated by the function @vindex quit-restore@r{, a window parameter} This parameter is installed by the buffer display functions (@pxref{Choosing Window}) and consulted by @code{quit-restore-window} -(@pxref{Quitting Windows}). It contains four elements: +(@pxref{Quitting Windows}). It is a list of four elements, see the +description of @code{quit-restore-window} in @ref{Quitting Windows} +for details. -The first element is one of the symbols @code{window}, meaning that -the window has been specially created by @code{display-buffer}; -@code{frame}, a separate frame has been created; @code{same}, the -window has only ever displayed this buffer; or @code{other}, the -window showed another buffer before. @code{frame} and @code{window} -affect how the window is quit, while @code{same} and @code{other} -affect the redisplay of buffers previously shown in this window. - -The second element is either one of the symbols @code{window} or -@code{frame}, or a list whose elements are the buffer shown in the -window before, that buffer's window start and window point positions, -and the window's height at that time. If that buffer is still live -when the window is quit, then the function @code{quit-restore-window} -reuses the window to display the buffer. - -The third element is the window selected at the time the parameter was -created. If @code{quit-restore-window} deletes the window passed to -it as argument, it then tries to reselect this window. - -The fourth element is the buffer whose display caused the creation of -this parameter. @code{quit-restore-window} deletes the specified window -only if it still shows that buffer. - -See the description of @code{quit-restore-window} in @ref{Quitting -Windows} for details. - -@item window-side window-slot +@item window-side +@itemx window-slot @vindex window-side@r{, a window parameter} @vindex window-slot@r{, a window parameter} -These parameters are used for implementing side windows (@pxref{Side -Windows}). +These parameters are used internally for implementing side windows +(@pxref{Side Windows}). @item window-atom @vindex window-atom@r{, a window parameter} -This parameter is used for implementing atomic windows, see @ref{Atomic -Windows}. +This parameter is used internally for implementing atomic windows, see +@ref{Atomic Windows}. @item mode-line-format @vindex mode-line-format@r{, a window parameter} @@ -5947,11 +5955,12 @@ affected. @item min-margins @vindex min-margins@r{, a window parameter} -The value of this parameter is a cons cell whose @sc{car} and @sc{cdr}, -if non-@code{nil}, specify the minimum values (in columns) for the left -and right margin of this window. When present, Emacs will use these -values instead of the actual margin widths for determining whether a -window can be split or shrunk horizontally. +The value of this parameter is a cons cell whose @sc{car} and +@sc{cdr}, if non-@code{nil}, specify the minimum values (in columns) +for the left and right margin of this window (@pxref{Display Margins}. +When present, Emacs will use these values instead of the actual margin +widths for determining whether a window can be split or shrunk +horizontally. Emacs never auto-adjusts the margins of any window after splitting or resizing it. It is the sole responsibility of any application setting -- cgit v1.2.1 From a30a6c3019ac09ede1cc47671083b2e9ecdbffdf Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 6 Apr 2019 11:22:13 +0300 Subject: Improve documentation of set-window-start * doc/lispref/windows.texi (Window Start and End): * src/window.c (Fset_window_start): Document that reliable setting of a window start position requires to adjust point to be visible. (Bug#34038) --- doc/lispref/windows.texi | 22 +++++++++++++++------- src/window.c | 7 ++++++- 2 files changed, 21 insertions(+), 8 deletions(-) diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 27940e12c79..f4395c12d26 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -4625,13 +4625,14 @@ This function sets the display-start position of @var{window} to @var{position} in @var{window}'s buffer. It returns @var{position}. The display routines insist that the position of point be visible when a -buffer is displayed. Normally, they change the display-start position -(that is, scroll the window) whenever necessary to make point visible. -However, if you specify the start position with this function using -@code{nil} for @var{noforce}, it means you want display to start at -@var{position} even if that would put the location of point off the -screen. If this does place point off screen, the display routines move -point to the left margin on the middle line in the window. +buffer is displayed. Normally, they select the display-start position +according to their internal logic (and scroll the window if necessary) +to make point visible. However, if you specify the start position +with this function using @code{nil} for @var{noforce}, it means you +want display to start at @var{position} even if that would put the +location of point off the screen. If this does place point off +screen, the display routines attempt to move point to the left margin +on the middle line in the window. For example, if point @w{is 1} and you set the start of the window @w{to 37}, the start of the next line, point will be above the top @@ -4678,6 +4679,13 @@ it is still 1 when redisplay occurs. Here is an example: @end group @end example +If the attempt to make point visible (i.e., in a fully-visible screen +line) fails, the display routines will disregard the requested +window-start position and compute a new one anyway. Thus, for +reliable results Lisp programs that call this function should always +move point to be inside the window whose display starts at +@var{position}. + If @var{noforce} is non-@code{nil}, and @var{position} would place point off screen at the next redisplay, then redisplay computes a new window-start position that works well with point, and thus @var{position} is not used. diff --git a/src/window.c b/src/window.c index 04183abb7c5..dfac3b5b879 100644 --- a/src/window.c +++ b/src/window.c @@ -1704,7 +1704,12 @@ DEFUN ("set-window-start", Fset_window_start, Sset_window_start, 2, 3, 0, doc: /* Make display in WINDOW start at position POS in WINDOW's buffer. WINDOW must be a live window and defaults to the selected one. Return POS. Optional third arg NOFORCE non-nil inhibits next redisplay from -overriding motion of point in order to display at this exact start. */) +overriding motion of point in order to display at this exact start. + +For reliable setting of WINDOW start position, make sure point is +at a position that will be visible when that start is in effect, +otherwise there's a chance POS will be disregarded, e.g., if point +winds up in a partially-visible line. */) (Lisp_Object window, Lisp_Object pos, Lisp_Object noforce) { register struct window *w = decode_live_window (window); -- cgit v1.2.1 From 646d33dbbced04b3454fa5f726309dd96cd089c7 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 6 Apr 2019 11:48:36 +0300 Subject: Fix doc strings of 'vc-version-diff' and 'vc-version-ediff' * lisp/vc/vc.el (vc-version-diff, vc-version-ediff): Describe arguments in the doc strings. (Bug#35019) --- lisp/vc/vc.el | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/lisp/vc/vc.el b/lisp/vc/vc.el index 326284f4446..353299cbed9 100644 --- a/lisp/vc/vc.el +++ b/lisp/vc/vc.el @@ -1814,7 +1814,12 @@ Return t if the buffer had changes, nil otherwise." ;;;###autoload (defun vc-version-diff (_files rev1 rev2) - "Report diffs between revisions of the fileset in the repository history." + "Report diffs between revisions REV1 and REV2 in the repository history. +This compares two revisions of the current fileset. +If REV1 is nil, it defaults to the current revision, i.e. revision +of the last commit. +If REV2 is nil, it defaults to the work tree, i.e. the current +state of each file in the fileset." (interactive (vc-diff-build-argument-list-internal)) ;; All that was just so we could do argument completion! (when (and (not rev1) rev2) @@ -1846,8 +1851,14 @@ saving the buffer." ;;;###autoload (defun vc-version-ediff (files rev1 rev2) - "Show differences between revisions of the fileset in the -repository history using ediff." + "Show differences between REV1 and REV2 of FILES using ediff. +This compares two revisions of the files in FILES. Currently, +only a single file's revisions can be compared, i.e. FILES can +specify only one file name. +If REV1 is nil, it defaults to the current revision, i.e. revision +of the last commit. +If REV2 is nil, it defaults to the work tree, i.e. the current +state of each file in FILES." (interactive (vc-diff-build-argument-list-internal)) ;; All that was just so we could do argument completion! (when (and (not rev1) rev2) -- cgit v1.2.1 From a5da653319a3018074debfc7b4fdd90ac7ea838c Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Mon, 8 Apr 2019 19:53:48 +0300 Subject: * src/editfns.c (Fnarrow_to_region): Doc fix. (Bug#35163) --- src/editfns.c | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/editfns.c b/src/editfns.c index f5edbb71d2e..9b76ae23ffd 100644 --- a/src/editfns.c +++ b/src/editfns.c @@ -3840,8 +3840,9 @@ but is not deleted; if you save the buffer in a file, the invisible text is included in the file. \\[widen] makes all visible again. See also `save-restriction'. -When calling from a program, pass two arguments; positions (integers -or markers) bounding the text that should remain visible. */) +When calling from Lisp, pass two arguments START and END: +positions (integers or markers) bounding the text that should +remain visible. */) (register Lisp_Object start, Lisp_Object end) { CHECK_NUMBER_COERCE_MARKER (start); -- cgit v1.2.1