Merge from origin/emacs-30

cc5b1a01a2 ; * doc/misc/efaq-w32.texi (Location of init file): Fix a...
6c2aaedfce Fix compilation errors in emacsclient.c with MinGW GCC 15
d56e5ba97e ; * etc/DEBUG: Add link to GCC bug #78685.
80cbd1e31c ; Fix key notation in Introduction to Emacs Lisp
1224e5fd96 ; * lisp/files.el (revert-buffer-restore-functions): Doc ...
79e7eeb329 ; Improve documentation of 'format-time-string'
2838b64fc8 ; * lisp/textmodes/text-mode.el (text-mode-variant): Fix ...
9adb05422e ; Improve obsolescence of 'text-mode-variant'
4858d81848 ; * lisp/files.el (revert-buffer-restore-functions): Doc ...
2a8e223b8d ; Mention early-init file in Emacs FAQ for Windows
14c707b42d ; Isearch: Fix key bindings in docstrings

doc/lispintro/emacs-lisp-intro.texi

@@ -940,21 +940,21 @@ same time, and then press and release @kbd{t}.)
 
 Also, I often refer to one of Emacs's standard commands by listing the
 keys which you press to invoke the command and then giving the name of
-the command in parentheses, like this: @kbd{M-C-\}
+the command in parentheses, like this: @kbd{C-M-\}
 (@code{indent-region}).  What this means is that the
 @code{indent-region} command is customarily invoked by typing
-@kbd{M-C-\}.  (You can, if you wish, change the keys that are typed to
+@kbd{C-M-\}.  (You can, if you wish, change the keys that are typed to
 invoke the command; this is called @dfn{rebinding}.  @xref{Keymaps, ,
-Keymaps}.)  The abbreviation @kbd{M-C-\} means that you type your
+Keymaps}.)  The abbreviation @kbd{C-M-\} means that you type your
-@key{META} key, @key{CTRL} key and @kbd{\} key all at the same time.
+@key{CTRL} key, @key{META} key, and @kbd{\} key all at the same time.
 (On many modern keyboards the @key{META} key is labeled
 @key{ALT}.)
 Sometimes a combination like this is called a keychord, since it is
 similar to the way you play a chord on a piano.  If your keyboard does
 not have a @key{META} key, the @key{ESC} key prefix is used in place
-of it.  In this case, @kbd{M-C-\} means that you press and release your
+of it.  In this case, @kbd{C-M-\} means that you press and release your
 @key{ESC} key and then type the @key{CTRL} key and the @kbd{\} key at
-the same time.  But usually @kbd{M-C-\} means press the @key{CTRL} key
+the same time.  But usually @kbd{C-M-\} means press the @key{CTRL} key
 along with the key that is labeled @key{ALT} and, at the same time,
 press the @kbd{\} key.
 
@@ -962,7 +962,7 @@ In addition to typing a lone keychord, you can prefix what you type
 with @kbd{C-u}, which is called the @dfn{universal argument}.  The
 @kbd{C-u} keychord passes an argument to the subsequent command.
 Thus, to indent a region of plain text by 6 spaces, mark the region,
-and then type @w{@kbd{C-u 6 M-C-\}}.  (If you do not specify a number,
+and then type @w{@kbd{C-u 6 C-M-\}}.  (If you do not specify a number,
 Emacs either passes the number 4 to the command or otherwise runs the
 command differently than it would otherwise.)  @xref{Arguments, ,
 Numeric Arguments, emacs, The GNU Emacs Manual}.
@@ -1258,7 +1258,7 @@ Interaction mode or Emacs Lisp mode, you have available to you several
 commands to format the Lisp expression so it is easy to read.  For
 example, pressing the @key{TAB} key automatically indents the line the
 cursor is on by the right amount.  A command to properly indent the
-code in a region is customarily bound to @kbd{M-C-\}.  Indentation is
+code in a region is customarily bound to @kbd{C-M-\}.  Indentation is
 designed so that you can see which elements of a list belong to which
 list---elements of a sub-list are indented more than the elements of
 the enclosing list.

doc/lispref/modes.texi

@@ -1510,9 +1510,6 @@ You can thus get the full benefit of adaptive filling
  (see the variable `adaptive-fill-mode').
 \\@{text-mode-map@}
 Turning on Text mode runs the normal hook `text-mode-hook'."
-@end group
-@group
-  (setq-local text-mode-variant t)
   (setq-local require-final-newline mode-require-final-newline))
 @end group
 @end smallexample

doc/lispref/os.texi

@@ -1953,14 +1953,18 @@ This is a synonym for @samp{%H:%M:%S}.
 This stands for the numeric day of week (1--7).  Monday is day 1.
 @item %U
 This stands for the week of the year (01--52), assuming that weeks
-start on Sunday.
+start on Sunday.  If January 1 is not a Sunday, the first partial week
+is week zero.
 @item %V
-This stands for the week of the year according to ISO 8601.
+This stands for the week of the year according to ISO 8601.  Note that,
+unlike @samp{%U} and @samp{%W}, the week according to ISO 8601 does
+@emph{not} roll over to 1 on January 1, but keeps its last number.
 @item %w
 This stands for the numeric day of week (0--6).  Sunday is day 0.
 @item %W
-This stands for the week of the year (01--52), assuming that weeks
+This stands for the week of the year (01--52), assuming that weeks start
-start on Monday.
+on Monday.  If January 1 is not a Monday, the first partial week is week
+zero.
 @item %x
 This has a locale-specific meaning.  In the default locale (named
 @samp{C}), it is equivalent to @samp{%D}.

doc/misc/efaq-w32.texi

@@ -353,6 +353,7 @@ not bundled with Emacs.  @xref{Other useful ports}.
 @section What is my init file?
 @cindex .emacs
 @cindex init file
+@cindex early init file
 
 When Emacs starts up, it attempts to load and execute the contents of
 a file commonly called @file{.emacs} (though it may have other names,
@@ -362,22 +363,31 @@ code to your .emacs, or you can use the Customization interface
 accessible from the @emph{Options} menu.  If the file does not exist,
 Emacs will start with the default settings.
 
+In addition, Emacs 27 and later attempts to load and execute the
+contents of the @file{early-init.el} file.  As its name suggests, this
+file, if it exists, is loaded and executed early on during the Emacs
+startup sequence, before @code{.emacs}, and is intended to contain the
+few initializations which must be performed before @file{.emacs} is
+looked up and loaded.
+
 @node Location of init file
 @section Where do I put my init file?
 @cindex HOME directory
 @cindex .emacs.d
 @cindex _emacs
 @cindex init.el
+@cindex early-init.el
 @cindex registry, setting the HOME directory in
 
-On Windows, the @file{.emacs} file may be called @file{_emacs} for
+On Windows, the @file{.emacs} init file may be called @file{_emacs} for
 backward compatibility with DOS and FAT filesystems where filenames
 could not start with a dot.  Some users prefer to continue using such
 a name due to historical problems various Windows tools had in the
 past with file names that begin with a dot.  The init file may also be
-called @file{.emacs.d/init.el}.  Many of the other files that are
+called @file{.emacs.d/init.el}.  The @file{early-init.el} file and many
-created by Lisp packages are stored in the @file{.emacs.d} directory
+of the other files that are created by Lisp packages are stored in the
-too, which keeps all your Emacs related files in one place.
+@file{.emacs.d} directory too, which keeps all your Emacs related files
+in one place.
 
 All the files mentioned above should go in your @env{HOME} directory.
 The @env{HOME} directory is determined by following the steps below:

etc/DEBUG

@@ -20,7 +20,7 @@ such as --prefix):
     CFLAGS='-O0 -g3'
 
 The -O0 flag is important, as debugging optimized code can be hard, even
-in the case that the -Og compiler option is used.  If the problem
+in the case that the -Og compiler option is used.[1]  If the problem
 happens only with optimized code, you may need to enable optimizations.
 If that happens, try using -Og first instead of -O2, as -Og disables
 some optimizations that make debugging some code exceptionally hard.
@@ -38,6 +38,9 @@ this below under "Debugging Emacs redisplay problems".
 Emacs needs not be installed to be debugged, you can debug the binary
 created in the 'src' directory.
 
+[1]  gcc's -Og has some known problems and limitations, documented here:
+     https://gcc.gnu.org/bugzilla/show_bug.cgi?id=78685
+
 *** Configuring GDB
 
 To start GDB to debug Emacs, you can simply type "gdb ./emacs RET" at

lib-src/emacsclient.c

@@ -1715,8 +1715,13 @@ set_socket (bool no_exit_if_error)
 }
 
 #ifdef HAVE_NTGUI
-FARPROC set_fg;  /* Pointer to AllowSetForegroundWindow.  */
+typedef void (* VOIDFNPTR) (void);
-FARPROC get_wc;  /* Pointer to RealGetWindowClassA.  */
+typedef BOOL (WINAPI *AllowSetForegroundWindow_proc) (DWORD);
+/* Pointer to AllowSetForegroundWindow.  */
+static AllowSetForegroundWindow_proc set_fg;
+typedef UINT (WINAPI *RealGetWindowClassA_proc) (HWND, LPSTR, UINT);
+/* Pointer to RealGetWindowClassA.  */
+static RealGetWindowClassA_proc get_wc;
 
 void w32_set_user_model_id (void);
 
@@ -1794,8 +1799,8 @@ w32_give_focus (void)
      emacsclient can allow Emacs to grab the focus by calling the function
      AllowSetForegroundWindow.  Unfortunately, older Windows (W95, W98 and
      NT) lack this function, so we have to check its availability.  */
-  if ((set_fg = GetProcAddress (user32, "AllowSetForegroundWindow"))
+  if ((set_fg = (AllowSetForegroundWindow_proc) (VOIDFNPTR) GetProcAddress (user32, "AllowSetForegroundWindow"))
-      && (get_wc = GetProcAddress (user32, "RealGetWindowClassA")))
+      && (get_wc = (RealGetWindowClassA_proc) (VOIDFNPTR) GetProcAddress (user32, "RealGetWindowClassA")))
     EnumWindows (w32_find_emacs_process, (LPARAM) 0);
 }
 #endif /* HAVE_NTGUI */

lisp/files.el

@@ -7116,14 +7116,21 @@ A customized `revert-buffer-function' need not run this hook.")
 (defvar revert-buffer-preserve-modes)
 
 (defvar revert-buffer-restore-functions '(revert-buffer-restore-read-only)
-  "Functions to preserve any state during `revert-buffer'.
+  "Functions to preserve buffer state during `revert-buffer'.
-The value of this variable is a list of functions that are called before
+The value of this variable is a list of functions that are called
-reverting the buffer.  Each of these functions are called without
+before reverting the buffer.  Each of these functions is called without
-arguments and should return a lambda that can restore a previous state
+arguments and should return a lambda form that can restore a previous
-of the buffer.  Then after reverting the buffer each of these lambdas
+state of the buffer.  After reverting the buffer, each of these lambda
-will be called one by one in the order of the list to restore previous
+forms will be called in order to restore previous states of the buffer.
-states of the buffer.  An example of the buffer state is keeping the
+An example of the buffer state is keeping the buffer read-only, or
-buffer read-only, or keeping minor modes, etc.")
+keeping minor modes, etc.
+
+The default value restores the buffer's read-only state to what it
+was before reverting.
+
+Set this variable to nil to disable restoring any buffer state
+attributes from before reverting.  Then only the file from which the
+buffer is reverted will determine the buffer's state after reverting.")
 
 (defun revert-buffer-restore-read-only ()
   "Preserve read-only state for `revert-buffer'."

lisp/isearch.el

@@ -3058,11 +3058,11 @@ See also the related option `isearch-allow-motion'."
 
 (defcustom isearch-allow-motion nil
   "Whether to allow movement between isearch matches by cursor motion commands.
-If non-nil, the four motion commands \\[beginning-of-buffer], \\[end-of-buffer], \
+If non-nil, the four motion commands \\<isearch-mode-map>\\[beginning-of-buffer], \\[end-of-buffer], \
-\\[scroll-up-command] and \\[scroll-down-command], when invoked during
+\\[scroll-up-command] and \\[scroll-down-command], when invoked
-Isearch, move respectively to the first occurrence of the current search string
+during Isearch, move respectively to the first occurrence of the current
-in the buffer, the last one, the first one after the current window, and the
+search string in the buffer, the last one, the first one after the current
-last one before the current window.
+window, and the last one before the current window.
 If nil, these motion commands normally exit Isearch and are executed.
 See also the related options `isearch-motion-changes-direction' and
 `isearch-allow-scroll'."
@@ -3075,8 +3075,8 @@ See also the related options `isearch-motion-changes-direction' and
   "Whether motion commands during incremental search change search direction.
 If nil, the search direction (forward or backward) does not change when
 motion commands are used during incremental search, except when wrapping.
-If non-nil, the search direction is forward after \\[beginning-of-buffer] and \
+If non-nil, the search direction is forward after \
-\\[scroll-up-command], and
+\\<isearch-mode-map>\\[beginning-of-buffer] and \\[scroll-up-command], and
 backward after \\[end-of-buffer] and \\[scroll-down-command]."
   :type '(choice (const :tag "Off" nil)
                  (const :tag "On" t))

lisp/textmodes/text-mode.el

@@ -40,7 +40,9 @@
 
 (defvar text-mode-variant nil
   "Non-nil if this buffer's major mode is a variant of Text mode.")
-(make-obsolete-variable 'text-mode-variant 'derived-mode-p "27.1")
+(make-obsolete-variable 'text-mode-variant
+                        "\
+don't set it, and instead of testing its value use `derived-mode-p'." "27.1")
 
 ;; Actually defined in textconv.c.
 (defvar text-conversion-style)