[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master 661e5dec570 3/3: Merge from origin/emacs-30
|
From: |
Eli Zaretskii |
|
Subject: |
master 661e5dec570 3/3: Merge from origin/emacs-30 |
|
Date: |
Sat, 17 Aug 2024 02:50:07 -0400 (EDT) |
branch: master
commit 661e5dec570b7724309e7ec943711cb029193aa0
Merge: 982a7e8ce30 5c9de704cc8
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>
Merge from origin/emacs-30
5c9de704cc8 ; * admin/make-tarball.txt: Minor copyedits.
3fc16357832 ; * doc/lispref/strings.texi (Text Comparison): Improve i...
45a78ec6c57 * lisp/files.el (require-with-check): Improve error messa...
9a04b99b3d3 ; * src/data.c (Fsubrp): Improve docstring.
4f3e8c3b4ed Improve documentation of ERT
ed8904937ec Disambiguate minor-mode variable in its function docstring
505139e0bad Fix project-dired keybinding in manual
9bedb957beb Improve documentation of time-parsing functions
# Conflicts:
# doc/lispref/os.texi
# lisp/calendar/iso8601.el
# lisp/calendar/parse-time.el
---
admin/make-tarball.txt | 66 ++++++++++++++++++++++---------------------
doc/emacs/maintaining.texi | 2 +-
doc/lispref/os.texi | 45 +++++++++++++++++++++++++----
doc/lispref/strings.texi | 9 ++++++
doc/misc/ert.texi | 9 ++++--
lisp/calendar/iso8601.el | 17 +++++++++--
lisp/calendar/parse-time.el | 11 ++++++--
lisp/emacs-lisp/easy-mmode.el | 9 ++++--
lisp/emacs-lisp/ert.el | 20 +++++++------
lisp/files.el | 14 +++++++--
src/data.c | 4 ++-
11 files changed, 144 insertions(+), 62 deletions(-)
diff --git a/admin/make-tarball.txt b/admin/make-tarball.txt
index 9d3de2fa201..15342319829 100644
--- a/admin/make-tarball.txt
+++ b/admin/make-tarball.txt
@@ -137,38 +137,40 @@ General steps (for each step, check for possible errors):
of the format "Bump Emacs version to ...", so that the commit can
be skipped when merging branches (see admin/gitmerge.el).
- The final pretest should be a release candidate.
- Before a release candidate is made, the tasks listed in
- admin/release-process must be completed.
-
- Set the version number to that of the actual release (commit in
- one, as described above). Pick a date about a week from now when
- you intend to make the release. Use M-x add-release-logs from
- admin/admin.el to add entries to etc/HISTORY and the ChangeLog
- file. It's best not to commit these files until the release is
- actually made. Merge the entries from (unversioned) ChangeLog
- into the top of the current versioned ChangeLog.N and commit that
- along with etc/HISTORY. Then you can tag that commit as the
- release.
-
- Alternatively, you can commit and tag with the RC tag right away,
- and delay the final tagging until you actually decide to make a
- release and announce it. The "git tag" command can tag a specific
- commit if you give it the SHA1 of that commit, even if additional
- commits have been pushed in the meantime.
-
- Name the tar file as emacs-XX.Y-rc1.tar. If all goes well in the
- following week, you can simply rename the file and use it for the
- actual release. If you need another release candidate, remember
- to adjust the ChangeLog and etc/HISTORY entries.
-
- If you need to change only a file(s) that cannot possibly affect
- the build (README, ChangeLog, NEWS, etc.) then rather than doing
- an entirely new build, it is better to unpack the existing
- tarfile, modify the file(s), and tar it back up again.
-
- Never replace an existing tarfile! If you need to fix something,
- always upload it with a different name.
+ If this is a final pretest before the release:
+
+ The final pretest should be a release candidate.
+ Before a release candidate is made, the tasks listed in
+ admin/release-process must be completed.
+
+ Set the version number to that of the actual release (commit in
+ one, as described above). Pick a date about a week from now when
+ you intend to make the release. Use M-x add-release-logs from
+ admin/admin.el to add entries to etc/HISTORY and the ChangeLog
+ file. It's best not to commit these files until the release is
+ actually made. Merge the entries from (unversioned) ChangeLog
+ into the top of the current versioned ChangeLog.N and commit that
+ along with etc/HISTORY. Then you can tag that commit as the
+ release.
+
+ Alternatively, you can commit and tag with the RC tag right away,
+ and delay the final tagging until you actually decide to make a
+ release and announce it. The "git tag" command can tag a specific
+ commit if you give it the SHA1 of that commit, even if additional
+ commits have been pushed in the meantime.
+
+ Name the tar file as emacs-XX.Y-rc1.tar. If all goes well in the
+ following week, you can simply rename the file and use it for the
+ actual release. If you need another release candidate, remember
+ to adjust the ChangeLog and etc/HISTORY entries.
+
+ If you need to change only a file(s) that cannot possibly affect
+ the build (README, ChangeLog, NEWS, etc.) then rather than doing
+ an entirely new build, it is better to unpack the existing
+ tarfile, modify the file(s), and tar it back up again.
+
+ Never replace an existing tarfile! If you need to fix something,
+ always upload it with a different name.
4. autoreconf -i -I m4 --force
make bootstrap
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index f4752fa2b29..3c34afbaa20 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1829,7 +1829,7 @@ the current project.
@item C-x p r
Perform query-replace for a regexp in all files that belong to the
current project (@code{project-query-replace-regexp}).
-@item C-x p d
+@item C-x p D
Run Dired in the current project's root directory
(@code{project-dired}).
@item C-x p v
diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index ddaa1de221c..fc456a79032 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1803,15 +1803,50 @@ function will attempt to parse less well-formed time
strings as well.
It parses an incomplete string like ``2024-08-13'' to an incomplete
structure like @samp{(nil nil nil 13 8 2024 nil -1 nil)}, in which
an unknown DST value is @minus{}1 and other unknown values are @code{nil}.
+
+Note that, unlike @code{decode-time} (@pxref{Time Conversion}), this
+function does not interpret the time string, and in particular the
+values of daylight-saving and timezone or UTC offset parts of the
+@var{string} argument do not affect the returned value of date and time,
+they only affect the last two members of the returned decoded time
+structure. For example, if the time-zone information is present in
+@var{string}, the decoded time structure will include it; otherwise the
+time-zone member of the returned value will be @code{nil}. In other
+words, this function simply parses the textual representation of date
+and time into separate numerical values, and doesn't care whether the
+input time is local or UTC.
+
+If a Lisp program passes the return value of this function to some other
+time-related API, it should make sure the @code{nil} members of the
+decoded time structure are interpreted correctly, and in particular the
+lack of time-zone information is interpreted as UTC or local time,
+according to the needs of the calling program.
@end defun
@vindex ISO 8601 date/time strings
@defun iso8601-parse string
-This function acts like @code{parse-time-string} except it is stricter
-and errors out upon invalid input. It can parse all variants of
-the ISO 8601 standard, so in addition to the formats mentioned above,
-it also parses things like ``1998W45-3'' (week number) and
-``1998-245'' (ordinal day number).
+For a more strict function (that will error out upon invalid input),
+Lisp programs can use this function instead. It can parse all variants
+of the ISO 8601 standard, so in addition to the formats mentioned above,
+it also parses things like ``1998W45-3'' (week number) and ``1998-245''
+(ordinal day number). To parse durations, there's
+@code{iso8601-parse-duration}, and to parse intervals, there's
+@code{iso8601-parse-interval}. All these functions return decoded time
+structures, except the final one, which returns three of them (the
+start, the end, and the duration).
+Like @code{parse-time-string}, this function does not interpret the time
+string, and in particular the time-zone designator or UTC offset that is
+part of the @var{string} argument does not affect the returned value of
+date and time, it only affects the last two members of the returned
+decoded time structure. The ISO 8601 standard specifies that date/time
+strings that do not include information about UTC relation are assumed
+to be in local time, but this function does not do that, because it
+doesn't interpret the time values. For example, if the time-zone
+information is present in @var{string}, the decoded time structure will
+include it; otherwise the time-zone member of the returned value will be
+@code{nil}. In other words, this function simply parses the textual
+representation of date and time into separate numerical values, and
+doesn't care whether the input time is local or UTC.
@end defun
@defun iso8601-parse-duration string
diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi
index 31cae4691a4..71d85acb37c 100644
--- a/doc/lispref/strings.texi
+++ b/doc/lispref/strings.texi
@@ -487,7 +487,9 @@ null characters. It may also change @var{string}'s length.
@section Comparison of Characters and Strings
@cindex string equality
@cindex text comparison
+@cindex string comparison
+@cindex compare characters
@defun char-equal character1 character2
This function returns @code{t} if the arguments represent the same
character, @code{nil} otherwise. This function ignores differences
@@ -502,6 +504,7 @@ in case if @code{case-fold-search} is non-@code{nil}.
@end example
@end defun
+@cindex compare strings
@defun string-equal string1 string2
This function returns @code{t} if the characters of the two strings
match exactly. Symbols are also allowed as arguments, in which case
@@ -534,6 +537,7 @@ character codes all being in the range 0--127
(@acronym{ASCII}).
@code{string=} is another name for @code{string-equal}.
@end defun
+@cindex case-insensitive string comparison
@defun string-equal-ignore-case string1 string2
@code{string-equal-ignore-case} compares strings ignoring case
differences, like @code{char-equal} when @code{case-fold-search} is
@@ -665,6 +669,7 @@ This function returns the result of comparing @var{string1}
and
@end defun
@cindex locale-dependent string comparison
+@cindex string collation
@defun string-collate-lessp string1 string2 &optional locale ignore-case
This function returns @code{t} if @var{string1} is less than
@var{string2} in collation order of the specified @var{locale}, which
@@ -719,6 +724,8 @@ If your system does not support a locale environment, this
function
behaves like @code{string-lessp}.
@end defun
+@cindex version comparison
+@cindex comparing version strings
@defun string-version-lessp string1 string2
This function compares strings lexicographically, except it treats
sequences of numerical characters as if they comprised a base-ten
@@ -727,6 +734,7 @@ number, and then compares the numbers. So @samp{foo2.png}
is
@samp{12} is lexicographically ``smaller'' than @samp{2}.
@end defun
+@cindex string starts with prefix
@defun string-prefix-p string1 string2 &optional ignore-case
This function returns non-@code{nil} if @var{string1} is a prefix of
@var{string2}; i.e., if @var{string2} starts with @var{string1}. If
@@ -734,6 +742,7 @@ the optional argument @var{ignore-case} is non-@code{nil},
the
comparison ignores case differences.
@end defun
+@cindex string ends with suffix
@defun string-suffix-p suffix string &optional ignore-case
This function returns non-@code{nil} if @var{suffix} is a suffix of
@var{string}; i.e., if @var{string} ends with @var{suffix}. If the
diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi
index 109dbd0f0ce..1ac0378148b 100644
--- a/doc/misc/ert.texi
+++ b/doc/misc/ert.texi
@@ -203,9 +203,12 @@ different Emacs versions.
@cindex interactive testing
@findex ert
+@findex ert-run-tests-interactively
You can run the tests that are currently defined in your Emacs with the
-command @kbd{M-x ert @key{RET} t @key{RET}}. (For an explanation of the
-@code{t} argument, @pxref{Test Selectors}.) ERT will pop up a new
+command @kbd{M-x ert @key{RET} t @key{RET}} (which is an alias of
+@code{ert-run-tests-interactively}). The @code{t} argument means to run
+all the defined tests, see @ref{Test Selectors}, which also explains how
+to run only some specific part of the tests. ERT will pop up a new
buffer, the ERT results buffer, showing the results of the tests run.
It looks like this:
@@ -474,7 +477,7 @@ to Common Lisp's type specifier syntax:
@item @code{:failed} and @code{:passed} select tests according to their most
recent result.
@item @code{:expected}, @code{:unexpected} select tests according to their
most recent result.
@item A string is a regular expression that selects all tests with matching
names.
-@item A test (i.e., an object of @code{ert-test} data type) selects that test.
+@item A test (i.e., an object of @code{ert-test} data type, see its doc string
for details) selects that test.
@item A symbol selects the test that the symbol names.
@item @code{(member @var{tests}...)} selects the elements of
@var{tests}, a list of tests or symbols naming tests.
diff --git a/lisp/calendar/iso8601.el b/lisp/calendar/iso8601.el
index a31b60eaec2..9da2602cca8 100644
--- a/lisp/calendar/iso8601.el
+++ b/lisp/calendar/iso8601.el
@@ -121,12 +121,23 @@
(defun iso8601-parse (string &optional form)
"Parse an ISO 8601 date/time string and return a `decode-time' structure.
-ISO 8601 date/time strings look like \"2008-03-02T13:47:30+05:30\",
-or like shorter, incomplete strings like date \"2008-03-02\",
-week number \"2008W32\", and ordinal day number \"2008-234\".
+
+The ISO 8601 date/time strings look like \"2008-03-02T13:47:30\"
+or \"2024-04-05T14:30Z\" or \"2024-04-05T12:30−02:00\",
+but shorter, incomplete strings like \"2008-03-02\" are valid, as
+well as variants like \"2008W32\" (week number) and
+\"2008-234\" (ordinal day number).
Values returned are identical to those of `decode-time', except
that an unknown DST value is -1 and other unknown values are nil.
+Note that, unlike `decode-time', this function does not interpret
+the time string, and in particular the time-zone designator or UTC
+offset that is part of STRING does not affect the returned value of
+date and time, it only affects the last two members of the returned
+value. This function simply parses the textual representation of
+date and time into separate numerical values, and doesn't care
+whether the time is local or UTC.
+
See `decode-time' for the meaning of FORM."
(if (not (iso8601-valid-p string))
(signal 'wrong-type-argument (list string))
diff --git a/lisp/calendar/parse-time.el b/lisp/calendar/parse-time.el
index 9538ea92ee5..f6fc7a8c162 100644
--- a/lisp/calendar/parse-time.el
+++ b/lisp/calendar/parse-time.el
@@ -154,8 +154,15 @@ or something resembling an RFC 822 (or later) date-time,
e.g.,
\"Wed, 15 Jan 2020 16:12:21 -0800\". This function is
somewhat liberal in what format it accepts, and will attempt to
return a \"likely\" value even for somewhat malformed strings.
-Values returned are identical to those of `decode-time', except
-that an unknown DST value is -1 and other unknown values are nil.
+The values returned are identical to those of `decode-time', but
+any unknown values other than DST are returned as nil, and an
+unknown DST value is returned as -1.
+Note that, unlike `decode-time', this function does not interpret
+the time string, and in particular the values of DST and TZ do not
+affect the returned value of date and time, they only affect the
+last two members of the returned value. This function simply
+parses the textual representation of date and time into separate
+numerical values, and doesn't care whether the time is local or UTC.
See `decode-time' for the meaning of FORM."
(condition-case ()
diff --git a/lisp/emacs-lisp/easy-mmode.el b/lisp/emacs-lisp/easy-mmode.el
index 944a74a91ee..a140027839e 100644
--- a/lisp/emacs-lisp/easy-mmode.el
+++ b/lisp/emacs-lisp/easy-mmode.el
@@ -91,7 +91,7 @@ Enable the mode if ARG is nil, omitted, or is a positive
number.
Disable the mode if ARG is a negative number.
To check whether the minor mode is enabled in the current buffer,
-evaluate `%s'.
+evaluate %s.
The mode's hook is called both when the mode is enabled and when
it is disabled.")
@@ -128,8 +128,11 @@ it is disabled.")
easy-mmode--arg-docstring
(if global "global " "")
mode-pretty-name
- ;; Avoid having quotes turn into pretty quotes.
- (string-replace "'" "\\='" (format "%S" getter)))))
+ (concat
+ (if (symbolp getter) "the variable ")
+ (format "`%s'"
+ ;; Avoid having quotes turn into pretty
quotes.
+ (string-replace "'" "\\='" (format "%S"
getter)))))))
(let ((start (point)))
(insert argdoc)
(when (fboundp 'fill-region) ;Don't break bootstrap!
diff --git a/lisp/emacs-lisp/ert.el b/lisp/emacs-lisp/ert.el
index 6a665c8181d..2d96e5ce5a9 100644
--- a/lisp/emacs-lisp/ert.el
+++ b/lisp/emacs-lisp/ert.el
@@ -932,14 +932,14 @@ of tests, or t, which refers to all tests named by
symbols in `obarray'.
Valid SELECTORs:
nil -- Selects the empty set.
-t -- Selects UNIVERSE.
+t -- Selects all of UNIVERSE. If UNIVERSE is t, selects all tests.
:new -- Selects all tests that have not been run yet.
:failed, :passed -- Select tests according to their most recent result.
:expected, :unexpected -- Select tests according to their most recent result.
a string -- A regular expression selecting all tests with matching names.
-a test -- (i.e., an object of the ert-test data-type) Selects that test.
-a symbol -- Selects the test that the symbol names, signals an
- `ert-test-unbound' error if none.
+a test -- (i.e., an object of the `ert-test' data-type) Selects that test.
+a symbol -- Selects the test named by the symbol, signals an
+ `ert-test-unbound' error if no such test.
\(member TESTS...) -- Selects the elements of TESTS, a list of tests
or symbols naming tests.
\(eql TEST) -- Selects TEST, a test or a symbol naming a test.
@@ -1375,10 +1375,10 @@ RESULT must be an `ert-test-result-with-condition'."
(defun ert-run-tests-batch (&optional selector)
"Run the tests specified by SELECTOR, printing results to the terminal.
-SELECTOR works as described in `ert-select-tests', except if
-SELECTOR is nil, in which case all tests rather than none will be
-run; this makes the command line \"emacs -batch -l my-tests.el -f
-ert-run-tests-batch-and-exit\" useful.
+SELECTOR selects which tests to run as described in `ert-select-tests' when
+called with its second argument t, except if SELECTOR is nil, in which case
+all tests rather than none will be run; this makes the command line
+ \"emacs -batch -l my-tests.el -f ert-run-tests-batch-and-exit\" useful.
Returns the stats object."
(unless selector (setq selector 't))
@@ -2240,7 +2240,9 @@ STATS is the stats object; LISTENER is the results
listener."
(defun ert-run-tests-interactively (selector)
"Run the tests specified by SELECTOR and display the results in a buffer.
-SELECTOR works as described in `ert-select-tests'."
+SELECTOR selects which tests to run as described in `ert-select-tests'
+when called with its second argument t. Interactively, prompt for
+SELECTOR; the default t means run all the defined tests."
(interactive
(list (let ((default (if ert--selector-history
;; Can't use `first' here as this form is
diff --git a/lisp/files.el b/lisp/files.el
index eadb4a9d0b1..6cbb1b5c632 100644
--- a/lisp/files.el
+++ b/lisp/files.el
@@ -1274,9 +1274,17 @@ NOERROR is equal to `reload'), or otherwise emit a
warning."
(cond
((assoc fn load-history) nil) ;We loaded the right file.
((eq noerror 'reload) (load fn nil 'nomessage))
- (t (funcall (if noerror #'warn #'error)
- "Feature `%S' is now provided by a different file %s"
- feature fn)))))
+ ((and fn (memq feature features))
+ (funcall (if noerror #'warn #'error)
+ "Feature `%S' is now provided by a different file %s"
+ feature fn))
+ (fn
+ (funcall (if noerror #'warn #'error)
+ "Could not load file %s" fn))
+ (t
+ (funcall (if noerror #'warn #'error)
+ "Could not locate file %s in load path"
+ (or filename (symbol-name feature)))))))
res))
(defun file-remote-p (file &optional identification connected)
diff --git a/src/data.c b/src/data.c
index 6fa543c97cf..fd2d9705642 100644
--- a/src/data.c
+++ b/src/data.c
@@ -505,7 +505,9 @@ DEFUN ("user-ptrp", Fuser_ptrp, Suser_ptrp, 1, 1, 0,
#endif
DEFUN ("subrp", Fsubrp, Ssubrp, 1, 1, 0,
- doc: /* Return t if OBJECT is a built-in function. */)
+ doc: /* Return t if OBJECT is a built-in or native compiled Lisp
function.
+
+See also `primitive-function-p' and `native-comp-function-p'. */)
(Lisp_Object object)
{
if (SUBRP (object))