Commit fa6d5652 authored by Glenn Morris's avatar Glenn Morris
Browse files

Merge from origin/emacs-27

35661ef9 (origin/emacs-27) Fix typo in "(elisp) Type Keywords"
1af0e95f Gnus nnir-summary-line-format has no effect
dd366b5d Improve documentation of 'window-text-pixel-size'
fbd49f96 * src/xdisp.c (Fwindow_text_pixel_size): Doc fix.  (Bug#41...
d8593fd1 Minor improvements to EDE and EIEIO manuals
3916e63f Have Fido mode also imitate Ido mode in ignore-case options
cc35b197 Update package-menu-quick-help
bf091062 Improve documentation of 'sort-subr'
73749efa Update Ukrainian transliteration
30a7ee50 Fix Arabic shaping when eww/shr fill the text to be rendered
7d323f07 Silence some byte-compiler warnings in tests
cf473e74 * test/lisp/battery-tests.el: New file.
b07e3b1d Improve format-spec documentation (bug#41571)

# Conflicts:
#	test/lisp/emacs-lisp/package-tests.el
parents 6cb557e7 35661ef9
Pipeline #5795 failed with stage
in 64 minutes and 44 seconds
......@@ -1156,7 +1156,7 @@ in that value.
The usual reason to specify a documentation string for a type is to
provide more information about the meanings of alternatives inside a
@code{:choice} type or the parts of some other composite type.
@code{choice} type or the parts of some other composite type.
@item :help-echo @var{motion-doc}
@kindex help-echo@r{, customization keyword}
......
......@@ -2017,36 +2017,45 @@ it contains.
@defun window-text-pixel-size &optional window from to x-limit y-limit mode-and-header-line
This function returns the size of the text of @var{window}'s buffer in
pixels. @var{window} must be a live window and defaults to the selected
one. The return value is a cons of the maximum pixel-width of any text
line and the maximum pixel-height of all text lines.
The optional argument @var{from}, if non-@code{nil}, specifies the first
text position to consider and defaults to the minimum accessible
position of the buffer. If @var{from} is @code{t}, it uses the minimum
accessible position that is not a newline character. The optional
argument @var{to}, if non-@code{nil}, specifies the last text position
to consider and defaults to the maximum accessible position of the
buffer. If @var{to} is @code{t}, it uses the maximum accessible
position that is not a newline character.
pixels. @var{window} must be a live window and defaults to the
selected one. The return value is a cons of the maximum pixel-width
of any text line and the maximum pixel-height of all text lines. This
function exists to allow Lisp programs to adjust the dimensions of
@var{window} to the buffer text it needs to display.
The optional argument @var{from}, if non-@code{nil}, specifies the
first text position to consider, and defaults to the minimum
accessible position of the buffer. If @var{from} is @code{t}, it
stands for the minimum accessible position that is not a newline
character. The optional argument @var{to}, if non-@code{nil},
specifies the last text position to consider, and defaults to the
maximum accessible position of the buffer. If @var{to} is @code{t},
it stands for the maximum accessible position that is not a newline
character.
The optional argument @var{x-limit}, if non-@code{nil}, specifies the
maximum pixel-width that can be returned. @var{x-limit} @code{nil} or
omitted, means to use the pixel-width of @var{window}'s body
(@pxref{Window Sizes}); this is useful when the caller does not intend
to change the width of @var{window}. Otherwise, the caller should
specify here the maximum width @var{window}'s body may assume. Text
whose x-coordinate is beyond @var{x-limit} is ignored. Since
maximum X coordinate beyond which text should be ignored; it is
therefore also the largest value of pixel-width that the function can
return. If @var{x-limit} @code{nil} or omitted, it means to use the
pixel-width of @var{window}'s body (@pxref{Window Sizes}); this
default means that text of truncated lines wider than the window will
be ignored. This default is useful when the caller does not intend to
change the width of @var{window}. Otherwise, the caller should
specify here the maximum width @var{window}'s body may assume; in
particular, if truncated lines are expected and their text needs to be
accounted for, @var{x-limit} should be set to a large value. Since
calculating the width of long lines can take some time, it's always a
good idea to make this argument as small as needed; in particular, if
the buffer might contain long lines that will be truncated anyway.
The optional argument @var{y-limit}, if non-@code{nil}, specifies the
maximum pixel-height that can be returned. Text lines whose
y-coordinate is beyond @var{y-limit} are ignored. Since calculating the
pixel-height of a large buffer can take some time, it makes sense to
specify this argument; in particular, if the caller does not know the
size of the buffer.
maximum Y coordinate beyond which text is to be ignored; it is
therefore also the maximum pixel-height that the function can return.
If @var{y-limit} is nil or omitted, it means to considers all the
lines of text till the buffer position specified by @var{to}. Since
calculating the pixel-height of a large buffer can take some time, it
makes sense to specify this argument; in particular, if the caller
does not know the size of the buffer.
The optional argument @var{mode-and-header-line} @code{nil} or omitted
means to not include the height of the mode- or header-line of
......
......@@ -28,6 +28,7 @@ keyboard character events.
* Text Comparison:: Comparing characters or strings.
* String Conversion:: Converting to and from characters and strings.
* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}.
* Custom Format Strings:: Formatting custom @code{format} specifications.
* Case Conversion:: Case conversion functions.
* Case Tables:: Customizing case conversion.
@end menu
......@@ -1122,6 +1123,181 @@ may be problematic; for example, @samp{%d} and @samp{%g} can mishandle
NaNs and can lose precision and type, and @samp{#x%x} and @samp{#o%o}
can mishandle negative integers. @xref{Input Functions}.
The functions described in this section accept a fixed set of
specification characters. The next section describes a function
@code{format-spec} which can accept custom specification characters,
such as @samp{%a} or @samp{%z}.
@node Custom Format Strings
@section Custom Format Strings
@cindex custom format string
@cindex custom @samp{%}-sequence in format
Sometimes it is useful to allow users and Lisp programs alike to
control how certain text is generated via custom format control
strings. For example, a format string could control how to display
someone's forename, surname, and email address. Using the function
@code{format} described in the previous section, the format string
could be something like @w{@code{"%s %s <%s>"}}. This approach
quickly becomes impractical, however, as it can be unclear which
specification character corresponds to which piece of information.
A more convenient format string for such cases would be something like
@w{@code{"%f %l <%e>"}}, where each specification character carries
more semantic information and can easily be rearranged relative to
other specification characters, making such format strings more easily
customizable by the user.
The function @code{format-spec} described in this section performs a
similar function to @code{format}, except it operates on format
control strings that use arbitrary specification characters.
@defun format-spec template spec-alist &optional only-present
This function returns a string produced from the format string
@var{template} according to conversions specified in @var{spec-alist},
which is an alist (@pxref{Association Lists}) of the form
@w{@code{(@var{letter} . @var{replacement})}}. Each specification
@code{%@var{letter}} in @var{template} will be replaced by
@var{replacement} when formatting the resulting string.
The characters in @var{template}, other than the format
specifications, are copied directly into the output, including their
text properties, if any. Any text properties of the format
specifications are copied to their replacements.
Using an alist to specify conversions gives rise to some useful
properties:
@itemize @bullet
@item
If @var{spec-alist} contains more unique @var{letter} keys than there
are unique specification characters in @var{template}, the unused keys
are simply ignored.
@item
If @var{spec-alist} contains more than one association with the same
@var{letter}, the closest one to the start of the list is used.
@item
If @var{template} contains the same specification character more than
once, then the same @var{replacement} found in @var{spec-alist} is
used as a basis for all of that character's substitutions.
@item
The order of specifications in @var{template} need not correspond to
the order of associations in @var{spec-alist}.
@end itemize
The optional argument @var{only-present} indicates how to handle
specification characters in @var{template} that are not found in
@var{spec-alist}. If it is @code{nil} or omitted, the function
signals an error. Otherwise, those format specifications and any
occurrences of @samp{%%} in @var{template} are left verbatim in the
output, including their text properties, if any.
@end defun
The syntax of format specifications accepted by @code{format-spec} is
similar, but not identical, to that accepted by @code{format}. In
both cases, a format specification is a sequence of characters
beginning with @samp{%} and ending with an alphabetic letter such as
@samp{s}.
Unlike @code{format}, which assigns specific meanings to a fixed set
of specification characters, @code{format-spec} accepts arbitrary
specification characters and treats them all equally. For example:
@example
@group
(setq my-site-info
(list (cons ?s system-name)
(cons ?t (symbol-name system-type))
(cons ?c system-configuration)
(cons ?v emacs-version)
(cons ?e invocation-name)
(cons ?p (number-to-string (emacs-pid)))
(cons ?a user-mail-address)
(cons ?n user-full-name)))
(format-spec "%e %v (%c)" my-site-info)
@result{} "emacs 27.1 (x86_64-pc-linux-gnu)"
(format-spec "%n <%a>" my-site-info)
@result{} "Emacs Developers <emacs-devel@@gnu.org>"
@end group
@end example
A format specification can include any number of the following flag
characters immediately after the @samp{%} to modify aspects of the
substitution.
@table @samp
@item 0
This flag causes any padding specified by the width to consist of
@samp{0} characters instead of spaces.
@item -
This flag causes any padding specified by the width to be inserted on
the right rather than the left.
@item <
This flag causes the substitution to be truncated on the left to the
given width, if specified.
@item >
This flag causes the substitution to be truncated on the right to the
given width, if specified.
@item ^
This flag converts the substituted text to upper case (@pxref{Case
Conversion}).
@item _
This flag converts the substituted text to lower case (@pxref{Case
Conversion}).
@end table
The result of using contradictory flags (for instance, both upper and
lower case) is undefined.
As is the case with @code{format}, a format specification can include
a width, which is a decimal number that appears after any flags. If a
substitution contains fewer characters than its specified width, it is
padded on the left:
@example
@group
(format-spec "%8a is padded on the left with spaces"
'((?a . "alpha")))
@result{} " alpha is padded on the left with spaces"
@end group
@end example
Here is a more complicated example that combines several
aforementioned features:
@example
@group
(setq my-battery-info
(list (cons ?p "73") ; Percentage
(cons ?L "Battery") ; Status
(cons ?t "2:23") ; Remaining time
(cons ?c "24330") ; Capacity
(cons ?r "10.6"))) ; Rate of discharge
(format-spec "%>^-3L : %3p%% (%05t left)" my-battery-info)
@result{} "BAT : 73% (02:23 left)"
(format-spec "%>^-3L : %3p%% (%05t left)"
(cons (cons ?L "AC")
my-battery-info))
@result{} "AC : 73% (02:23 left)"
@end group
@end example
As the examples in this section illustrate, @code{format-spec} is
often used for selectively formatting an assortment of different
pieces of information. This is useful in programs that provide
user-customizable format strings, as the user can choose to format
with a regular syntax and in any desired order only a subset of the
information that the program makes available.
@node Case Conversion
@section Case Conversion in Lisp
@cindex upper case
......
......@@ -58,7 +58,6 @@ the character after point.
of another buffer.
* Decompression:: Dealing with compressed data.
* Base 64:: Conversion to or from base 64 encoding.
* Interpolated Strings:: Formatting Customizable Strings.
* Checksum/Hash:: Computing cryptographic hashes.
* GnuTLS Cryptography:: Cryptographic algorithms imported from GnuTLS.
* Parsing HTML/XML:: Parsing HTML and XML.
......@@ -2029,8 +2028,15 @@ non-@code{nil} value.
@end enumerate
The argument @var{predicate} is the function to use to compare keys.
If keys are numbers, it defaults to @code{<}; otherwise it defaults to
@code{string<}.
It is called with two arguments, the keys to compare, and should
return non-@code{nil} if the first key should come before the second
in the sorting order. What exactly are the key arguments depends on
what @var{startkeyfun} and @var{endkeyfun} return. If @var{predicate}
is omitted or @code{nil}, it defaults to @code{<} if the keys are
numbers, to @code{compare-buffer-substrings} if the keys are cons
cells (whose @code{car} and @code{cdr} are start and end buffer
positions of the key), and to @code{string<} otherwise (with keys
assumed to be strings).
As an example of @code{sort-subr}, here is the complete function
definition for @code{sort-lines}:
......@@ -4662,69 +4668,6 @@ If optional argument @var{base64url} is non-@code{nil}, then padding
is optional, and the URL variant of base 64 encoding is used.
@end defun
@node Interpolated Strings
@section Formatting Customizable Strings
It is, in some circumstances, useful to present users with a string to
be customized that can then be expanded programmatically. For
instance, @code{erc-header-line-format} is @code{"%n on %t (%m,%l)
%o"}, and each of those characters after the percent signs are
expanded when the header line is computed. To do this, the
@code{format-spec} function is used:
@defun format-spec format specification &optional only-present
@var{format} is the format specification string as in the example
above. @var{specification} is an alist that has elements where the
@code{car} is a character and the @code{cdr} is the substitution.
If @var{only-present} is @code{nil}, errors will be signaled if a
format character has been used that's not present in
@var{specification}. If it's non-@code{nil}, that format
specification is left verbatim in the result.
@end defun
Here's a trivial example:
@example
(format-spec "su - %u %l"
`((?u . ,(user-login-name))
(?l . "ls")))
@result{} "su - foo ls"
@end example
In addition to allowing padding/limiting to a certain length, the
following modifiers can be used:
@table @asis
@item @samp{0}
Pad with zeros instead of the default spaces.
@item @samp{-}
Pad to the right.
@item @samp{^}
Use upper case.
@item @samp{_}
Use lower case.
@item @samp{<}
If the length needs to be limited, remove characters from the left.
@item @samp{>}
Same as previous, but remove characters from the right.
@end table
If contradictory modifiers are used (for instance, both upper and
lower case), then what happens is undefined.
As an example, @samp{"%<010b"} means ``insert the @samp{b} expansion,
but pad with leading zeros if it's less than ten characters, and if
it's more than ten characters, shorten by removing characters from the
left.''
@node Checksum/Hash
@section Checksum/Hash
@cindex MD5 checksum
......
......@@ -955,18 +955,16 @@ The example for Makefiles looks like this:
;;; MAKEFILE
(defclass ede-generic-makefile-project (ede-generic-project)
((buildfile :initform "Makefile")
)
((buildfile :initform "Makefile"))
"Generic Project for makefiles.")
(defmethod ede-generic-setup-configuration ((proj ede-generic-makefile-project) config)
"Setup a configuration for Make."
"Set up a configuration for Make."
(oset config build-command "make -k")
(oset config debug-command "gdb ")
)
(oset config debug-command "gdb "))
(ede-generic-new-autoloader "generic-makefile" "Make"
"Makefile" 'ede-generic-makefile-project)
"Makefile" 'ede-generic-makefile-project)
@end example
This example project will detect any directory with the file
......
......@@ -744,14 +744,21 @@ slot values, and use the previously mentioned set/ref routines.
@anchor{slot-value}
This function retrieves the value of @var{slot} from @var{object}.
Unlike @code{oref}, the symbol for @var{slot} must be quoted.
This is a generalized variable that can be used with @code{setf} to
modify the value stored in @var{slot}. @xref{Generalized
Variables,,,elisp,GNU Emacs Lisp Reference Manual}.
@end defun
@defun set-slot-value object slot value
@anchor{set-slot-value}
This is not a CLOS function, but is the setter for @code{slot-value}
used by the @code{setf} macro. This
function sets the value of @var{slot} from @var{object}. Unlike
This function sets the value of @var{slot} from @var{object}. Unlike
@code{oset}, the symbol for @var{slot} must be quoted.
This is not a CLOS function, but is the obsolete setter for
@code{slot-value} used by the @code{setf} macro. It is therefore
recommended to use @w{@code{(setf (slot-value @var{object} @var{slot})
@var{value})}} instead.
@end defun
@defun slot-makeunbound object slot
......@@ -1072,7 +1079,7 @@ Return a string of the form @samp{#<object-class myobjname>} for @var{obj}.
This should look like Lisp symbols from other parts of Emacs such as
buffers and processes, and is shorter and cleaner than printing the
object's record. It is more useful to use @code{object-print} to get
and object's print form, as this allows the object to add extra display
an object's print form, as this allows the object to add extra display
information into the symbol.
@end defun
......@@ -1227,7 +1234,7 @@ objects on top of records, and thus everything is technically visible,
some functions have been provided. None of these functions are a part
of CLOS.
@defun object-slots obj
@defun eieio-class-slots obj
Return the list of public slots for @var{obj}.
@end defun
......
......@@ -3302,7 +3302,7 @@ If optional arg BUTTON is non-nil, describe its associated package."
'(("install," "delete," "unmark," ("execute" . 1))
("next," "previous")
("Hide-package," "(-toggle-hidden")
("refresh-contents," "g-redisplay," "filter," "help")))
("g-refresh-contents," "/-filter," "help")))
(defun package--prettify-quick-help-key (desc)
"Prettify DESC to be displayed as a help menu."
......@@ -3310,7 +3310,7 @@ If optional arg BUTTON is non-nil, describe its associated package."
(if (listp (cdr desc))
(mapconcat #'package--prettify-quick-help-key desc " ")
(let ((place (cdr desc))
(out (car desc)))
(out (copy-sequence (car desc))))
(add-text-properties place (1+ place)
'(face (bold font-lock-warning-face))
out)
......@@ -3790,6 +3790,9 @@ packages."
(package--has-keyword-p pkg-desc keyword))
(concat "keyword:" (string-join keyword ",")))))
(define-obsolete-function-alias
'package-menu-filter #'package-menu-filter-by-keyword "27.1")
(defun package-menu-filter-by-name (name)
"Filter the \"*Packages*\" buffer by NAME regexp.
Display only packages with name that matches regexp NAME.
......
......@@ -29,35 +29,46 @@
(defun format-spec (format specification &optional only-present)
"Return a string based on FORMAT and SPECIFICATION.
FORMAT is a string containing `format'-like specs like \"su - %u %k\",
while SPECIFICATION is an alist mapping from format spec characters
to values.
FORMAT is a string containing `format'-like specs like \"su - %u %k\".
SPECIFICATION is an alist mapping format specification characters
to their substitutions.
For instance:
(format-spec \"su - %u %l\"
`((?u . ,(user-login-name))
\\=`((?u . ,(user-login-name))
(?l . \"ls\")))
Each format spec can have modifiers, where \"%<010b\" means \"if
the expansion is shorter than ten characters, zero-pad it, and if
it's longer, chop off characters from the left side\".
Each %-spec may contain optional flag and width modifiers, as
follows:
The following modifiers are allowed:
%<flags><width>character
* 0: Use zero-padding.
* -: Pad to the right.
* ^: Upper-case the expansion.
* _: Lower-case the expansion.
* <: Limit the length by removing chars from the left.
* >: Limit the length by removing chars from the right.
The following flags are allowed:
Any text properties on a %-spec itself are propagated to the text
that it generates.
* 0: Pad to the width, if given, with zeros instead of spaces.
* -: Pad to the width, if given, on the right instead of the left.
* <: Truncate to the width, if given, on the left.
* >: Truncate to the width, if given, on the right.
* ^: Convert to upper case.
* _: Convert to lower case.
If ONLY-PRESENT, format spec characters not present in
SPECIFICATION are ignored, and the \"%\" characters are left
where they are, including \"%%\" strings."
The width modifier behaves like the corresponding one in `format'
when applied to %s.
For example, \"%<010b\" means \"substitute into the output the
value associated with ?b in SPECIFICATION, either padding it with
leading zeros or truncating leading characters until it's ten
characters wide\".
Any text properties of FORMAT are copied to the result, with any
text properties of a %-spec itself copied to its substitution.
ONLY-PRESENT indicates how to handle %-spec characters not
present in SPECIFICATION. If it is nil or omitted, emit an
error; otherwise leave those %-specs and any occurrences of
\"%%\" in FORMAT verbatim in the result, including their text
properties, if any."
(with-temp-buffer
(insert format)
(goto-char (point-min))
......
......@@ -663,7 +663,7 @@ A non-nil `specs' arg must be an alist with `nnir-query-spec' and
(let ((backend (car (gnus-server-to-method server))))
(if backend
(nnoo-change-server backend server definitions)
(add-hook 'gnus-summary-prepared-hook 'nnir-mode)
(add-hook 'gnus-summary-generate-hook 'nnir-mode)
(nnoo-change-server 'nnir server definitions))))
(deffoo nnir-request-group (group &optional server dont-check _info)
......@@ -1850,8 +1850,11 @@ is also searched."
(defun nnir-mode ()
(when (eq (car (gnus-find-method-for-group gnus-newsgroup-name)) 'nnir)
(setq gnus-summary-line-format
(or nnir-summary-line-format gnus-summary-line-format))
(when (and nnir-summary-line-format
(not (string= nnir-summary-line-format
gnus-summary-line-format)))
(setq gnus-summary-line-format nnir-summary-line-format)
(gnus-update-format-specifications nil 'summary))
(when (bound-and-true-p gnus-registry-enabled)
(remove-hook 'gnus-summary-article-delete-hook 'gnus-registry-action t)
(remove-hook 'gnus-summary-article-move-hook 'gnus-registry-action t)
......
......@@ -330,7 +330,10 @@ if that doesn't produce a completion match."
icomplete-hide-common-prefix nil
completion-styles '(flex)
completion-flex-nospace nil
completion-category-defaults nil)))
completion-category-defaults nil
completion-ignore-case t
read-buffer-completion-ignore-case t
read-file-name-completion-ignore-case t)))
;;;###autoload
(define-minor-mode fido-mode
......
......@@ -152,6 +152,7 @@ If the argument is nil, we return the display table to its standard state."
(aset standard-display-table ?љ [?l ?j])
(aset standard-display-table ?њ [?n ?j])
(aset standard-display-table ?џ [?d ?z])
(aset standard-display-table ?ґ [?g])
(aset standard-display-table ?Є [?Y ?e])
(aset standard-display-table ?Ї [?Y ?i])
......@@ -166,6 +167,7 @@ If the argument is nil, we return the display table to its standard state."
(aset standard-display-table ?Љ [?L ?j])
(aset standard-display-table ?Њ [?N ?j])
(aset standard-display-table ?Џ [?D ?j])
(aset standard-display-table ?Ґ [?G])
(when (equal cyrillic-language "Bulgarian")
(aset standard-display-table ?щ [?s ?h ?t])
......@@ -182,7 +184,9 @@ If the argument is nil, we return the display table to its standard state."
(aset standard-display-table ?й [?i])
(aset standard-display-table ?Й [?Y])
(aset standard-display-table ?ю [?i ?u])
(aset standard-display-table ?я [?i ?a]))))
(aset standard-display-table ?я [?i ?a])
(aset standard-display-table ?г [?h])
(aset standard-display-table ?Г [?H]))))
;;
(provide 'cyril-util)
......
......@@ -26,6 +26,7 @@ along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>. */
#include "composite.h"
#include "font.h"
#include "dispextern.h"
#include "buffer.h"
#ifdef HAVE_NTGUI
......@@ -438,7 +439,11 @@ hbfont_shape (Lisp_Object lgstring, Lisp_Object direction)
/* If the caller didn't provide a meaningful DIRECTION, let HarfBuzz
guess it. */
if (!NILP (direction))
if (!NILP (direction)
/* If they bind bidi-display-reordering to nil, the DIRECTION
they provide is meaningless, and we should let HarfBuzz guess
the real direction. */
&& !NILP (BVAR (current_buffer, bidi_display_reordering)))
{
hb_direction_t dir = HB_DIRECTION_LTR;
if (EQ (direction, QL2R))
......
......@@ -10449,33 +10449,43 @@ in_display_vector_p (struct it *it)
DEFUN ("window-text-pixel-size", Fwindow_text_pixel_size, Swindow_text_pixel_size, 0, 6, 0,
doc: /* Return the size of the text of WINDOW's buffer in pixels.
WINDOW must be a live window and defaults to the selected one. The
return value is a cons of the maximum pixel-width of any text line and
the maximum pixel-height of all text lines.
return value is a cons of the maximum pixel-width of any text line
and the pixel-height of all the text lines in the accessible portion
of buffer text.
This function exists to allow Lisp programs to adjust the dimensions
of WINDOW to the buffer text it needs to display.
 
The optional argument FROM, if non-nil, specifies the first text
position and defaults to the minimum accessible position of the buffer.
If FROM is t, use the minimum accessible position that starts a