diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/emacs/custom.texi | 3 | ||||
-rw-r--r-- | doc/emacs/display.texi | 33 | ||||
-rw-r--r-- | doc/emacs/search.texi | 12 | ||||
-rw-r--r-- | doc/lispref/compile.texi | 4 | ||||
-rw-r--r-- | doc/lispref/display.texi | 160 | ||||
-rw-r--r-- | doc/lispref/functions.texi | 24 | ||||
-rw-r--r-- | doc/lispref/hash.texi | 10 | ||||
-rw-r--r-- | doc/lispref/processes.texi | 45 | ||||
-rw-r--r-- | doc/lispref/strings.texi | 27 | ||||
-rw-r--r-- | doc/lispref/tips.texi | 16 | ||||
-rw-r--r-- | doc/lispref/windows.texi | 4 | ||||
-rw-r--r-- | doc/misc/autotype.texi | 26 | ||||
-rw-r--r-- | doc/misc/ede.texi | 4 | ||||
-rw-r--r-- | doc/misc/gnus.texi | 14 |
14 files changed, 312 insertions, 70 deletions
diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 46a2291b74d..6ed43bcb790 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -511,6 +511,9 @@ Set up a customization buffer for just one user option, @var{option}. @item M-x customize-face @key{RET} @var{face} @key{RET} Set up a customization buffer for just one face, @var{face}. +@item M-x customize-icon @key{RET} @var{face} @key{RET} +Set up a customization buffer for just one icon, @var{icon}. + @item M-x customize-group @key{RET} @var{group} @key{RET} Set up a customization buffer for just one group, @var{group}. diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index 96e05a902d6..b87ca81faea 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -24,6 +24,7 @@ the text is displayed. * Faces:: How to change the display style using faces. * Colors:: Specifying colors for faces. * Standard Faces:: The main predefined faces. +* Icons:: How to change how icons look. * Text Scale:: Increasing or decreasing text size in a buffer. * Font Lock:: Minor mode for syntactic highlighting using faces. * Highlight Interactively:: Tell Emacs what text to highlight. @@ -851,6 +852,38 @@ This face is used to display on text-mode terminals the menu item that would be selected if you click a mouse or press @key{RET}. @end table +@node Icons +@section Icons + +Emacs sometimes displays clickable buttons (or other informative +icons), and the look of these can be customized by the user. + +@vindex icon-preference +The main customization point here is the @code{icon-preference} user +option. By using this, you can tell Emacs your overall preferences +for icons. This is a list of icon types, and the first icon type +that's supported will be used. The supported types are: + +@table @code +@item image +Use an image for the icon. + +@item emoji +Use a colorful emoji for the icon. + +@item symbol +Use a monochrome symbol for the icon. + +@item text +Use a simple text for the icon. +@end table + +In addition, each individual icon can be customized with @kbd{M-x +customize-icon}, and themes can further alter the looks of the icons. + +To get a quick description of an icon, use the @kbd{M-x describe-icon} +command. + @node Text Scale @section Text Scale diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi index f4e12d29e99..27d4db85412 100644 --- a/doc/emacs/search.texi +++ b/doc/emacs/search.texi @@ -1428,16 +1428,18 @@ of its accented cousins like @code{@"a} and @code{@'a}, i.e., the match disregards the diacritics that distinguish these variants. In addition, @code{a} matches other characters that resemble it, or have it as part of their graphical representation, -such as U+249C @sc{parenthesized latin small letter a} and U+2100 -@sc{account of} (which looks like a small @code{a} over @code{c}). +such as U+00AA @sc{feminine ordinal indicator} and U+24D0 +@sc{circled latin small letter a} (which looks like a small @code{a} +inside a circle). Similarly, the @acronym{ASCII} double-quote character @code{"} matches all the other variants of double quotes defined by the Unicode standard. Finally, character folding can make a sequence of one or more characters match another sequence of a different length: for example, the sequence of two characters @code{ff} matches U+FB00 -@sc{latin small ligature ff}. Character sequences that are not identical, -but match under character folding are known as @dfn{equivalent -character sequences}. +@sc{latin small ligature ff} and the sequence @code{(a)} matches +U+249C @sc{parenthesized latin small letter a}. Character sequences +that are not identical, but match under character folding are known as +@dfn{equivalent character sequences}. @kindex M-s ' @r{(Incremental Search)} @findex isearch-toggle-char-fold diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index 9bb7b590a2c..60fc11a22ed 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -981,7 +981,9 @@ corresponding compiler @option{-O0}, @option{-O1}, etc.@: command-line options of the compiler. The value @minus{}1 means disable native-compilation: functions and files will be only byte-compiled; however, the @file{*.eln} files will still be produced, they will just -contain the compiled code in bytecode form. +contain the compiled code in bytecode form. (This can be achieved at +function granularity by using the @w{@code{(declare (speed -1))}} +form, @pxref{Declare Form}.) The default value is 2. @end defopt diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index f5fb0aaee70..d2e075c54ec 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -27,6 +27,7 @@ that Emacs presents to the user. * Window Dividers:: Separating windows visually. * Display Property:: Images, margins, text size, etc. * Images:: Displaying images in Emacs buffers. +* Icons:: Displaying icons in Emacs buffers. * Xwidgets:: Displaying native widgets in Emacs buffers. * Buttons:: Adding clickable buttons to Emacs buffers. * Abstract Display:: Emacs's Widget for Object Collections. @@ -6985,6 +6986,165 @@ bytes. An image of size 200x100 with 24 bits per color will have a cache size of 60000 bytes, for instance. @end defun +@node Icons +@section Icons + +Emacs sometimes uses buttons (for clicking on) or small graphics (to +illustrate something). Since Emacs is available on a wide variety of +systems with different capabilities, and users have different +preferences, Emacs provides a facility to handle this in a convenient +way, allowing customization, graceful degradation, accessibility, as +well as themability: @dfn{Icons}. + +The central macro here is @code{define-icon}, and here's a simple +example: + +@lisp +(define-icon outline-open button + '((image "right.svg" "open.xpm" "open.pbm" :height line) + (emoji "▶️") + (symbol "▶" "➤") + (text "open" :face icon-button)) + "Icon used for buttons for opening a section in outline buffers." + :version "29.1" + :help-echo "Open this section") +@end lisp + +Which alternative will actually be displayed depends on the value of +the user option @code{icon-preference} (@pxref{Icons,,, emacs, The GNU +Emacs Manual}) and on the results of run-time checks for what the +current frame's terminal can actually display. + +The macro in the example above defines @code{outline-open} as an icon, +and inherits properties from the icon called @code{button} (so this is +meant as a clickable button to be inserted in a buffer). It is +followed by a list of @dfn{icon types} along with the actual icon +shapes themselves. In addition, there's a doc string and various +keywords that contain additional information and properties. + +To instantiate an icon, you use @code{icon-string}, which will +consult the current Customize theming, and the @code{icon-preference} +user option, and finally what the Emacs is able to actually display. +If @code{icon-preference} is @code{(image emoji symbol text)} (i.e., +allowing all of these forms of icons), in this case, +@code{icon-string} will first check that Emacs is able to display +images at all, and then whether it has support for each of those +different image formats. If that fails, Emacs will check whether +Emacs can display emojis (in the current frame). If that fails, it'll +check whether it can display the symbol in question. If that fails, +it'll use the plain text version. + +For instance, if @code{icon-preference} doesn't contain @code{image} +or @code{emoji}, it'll skip those entries. + +Code can confidently call @code{icon-string} in all circumstances and +be sure that something readable will appear on the screen, no +matter whether the user is on a graphical terminal or a text terminal, +and no matter which features Emacs was built with. + +@defmac define-icon name parent specs doc &rest keywords +Define an icon @var{name}, a symbol, with the display alternatives in +@var{spec}, that can be later instantiated using @code{icon-string}. +The @var{name} is the name of the resulting keyword. + +The resulting icon will inherit specs from @var{parent}, and from +their parent's parents, and so on, and the lowest descendent element +wins. + +@var{specs} is a list of icon specifications. The first element of each +specification is the type, and the rest is something that can be used +as an icon of that type, and then optionally followed by a keyword +list. The following icon types are available: + +@cindex icon types +@table @code +@item image +In this case, there may be many images listed as candidates. Emacs +will choose the first one that the current Emacs instance can show. +If an image is listed is an absolute file name, it's used as is, but it's +otherwise looked up in the list @code{image-load-path} +(@pxref{Defining Images}). + +@item emoji +This should be a (possibly colorful) emoji. + +@item symbol +This should be a (monochrome) symbol character. + +@item text +Icons should also have a textual fallback. This can also be used for +the visually impaired: if @code{icon-preference} is just +@code{(text)}, all icons will be replaced by text. +@end table + +Various keywords may follow the list of icon specifications. For +instance: + +@example +(symbol "▶" "➤" :face icon-button) +@end example + +Unknown keywords are ignored. The following keywords are allowed: + +@cindex icon keywords +@table @code +@item :face +The face to be used for the icon. + +@item :height +This is only valid for @code{image} icons, and can be either a number +(which specifies the height in pixels), or the symbol @code{line}, +which will use the default line height in the currently selected +window. +@end table + +@var{doc} should be a doc string. + +@var{keywords} is a list of keyword/value pairs. The following +keywords are allowed: + +@table @code +@item :version +The (approximate) Emacs version this button first appeared. (This +keyword is mandatory.) + +@item :group +The customization group this icon belongs in. If not present, it is +inferred. + +@item :help-echo +The help string shown when hovering over the icon with the mouse +pointer. +@end table +@end defmac + +@defun icon-string icon +This function returns a string suitable for display in the current +buffer for @var{icon}. +@end defun + +@defun icon-elements icon +Alternatively, you can get a ``deconstructed'' version of @var{icon} +with this function. It returns a plist (@pxref{Property Lists}) where +the keys are @code{string}, @code{face} and @var{image}. (The latter +is only present if the icon is represented by an image.) This can be +useful if the icon isn't to be inserted directly in the buffer, but +needs some sort of pre-processing first. +@end defun + +Icons can be customized with @kbd{M-x customize-icon}. Themes can +specify changes to icons with, for instance: + +@lisp +(custom-theme-set-icons + 'my-theme + '(outline-open ((image :height 100) + (text " OPEN "))) + '(outline-close ((image :height 100) + (text " CLOSE " :face warning)))) +@end lisp + + @node Xwidgets @section Embedded Native Widgets @cindex xwidget diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index e3de6009e90..8e8cc5fd9c0 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -2497,6 +2497,30 @@ the current buffer. @item (modes @var{modes}) Specify that this command is meant to be applicable for @var{modes} only. + +@item (pure @var{val}) +If @var{val} is non-@code{nil}, this function is @dfn{pure} +(@pxref{What Is a Function}). This is the same as the @code{pure} +property of the function's symbol (@pxref{Standard Properties}). + +@item (side-effect-free @var{val}) +If @var{val} is non-@code{nil}, this function is free of side effects, +so the byte compiler can ignore calls whose value is ignored. This is +the same as the @code{side-effect-free} property of the function's +symbol, @pxref{Standard Properties}. + +@item (speed @var{n}) +Specify the value of @code{native-comp-speed} in effect for native +compilation of this function (@pxref{Native-Compilation Variables}). +This allows function-level control of the optimization level used for +native code emitted for the function. In particular, if @var{n} is +@minus{}1, native compilation of the function will emit bytecode +instead of native code for the function. + +@item no-font-lock-keyword +This is valid for macros only. Macros with this declaration are +highlighted by font-lock (@pxref{Font Lock Mode}) as normal functions, +not specially as macros. @end table @end defmac diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi index d3ae673d44d..25a56bd7151 100644 --- a/doc/lispref/hash.texi +++ b/doc/lispref/hash.texi @@ -324,15 +324,13 @@ the same integer. compared case-insensitively. @example -(defun case-fold-string= (a b) - (eq t (compare-strings a nil nil b nil nil t))) -(defun case-fold-string-hash (a) +(defun string-hash-ignore-case (a) (sxhash-equal (upcase a))) -(define-hash-table-test 'case-fold - 'case-fold-string= 'case-fold-string-hash) +(define-hash-table-test 'ignore-case + 'string-equal-ignore-case 'string-hash-ignore-case) -(make-hash-table :test 'case-fold) +(make-hash-table :test 'ignore-case) @end example Here is how you could define a hash table test equivalent to the diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 80c371e1c6a..1ef8fc3d03a 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -3204,20 +3204,39 @@ If the vector does not include the port number, @var{p}, or if @code{:@var{p}} suffix. @end defun -@defun network-lookup-address-info name &optional family -This function is used to perform hostname lookups on @var{name}, which -is expected to be an ASCII-only string, otherwise an error is -signaled. Call @code{puny-encode-domain} on @var{name} -first if you wish to lookup internationalized hostnames. - -If successful it returns a list of Lisp representations of network -addresses, otherwise it returns @code{nil}. In the latter case, it -also displays the error message hopefully explaining what went wrong. - -By default both IPv4 and IPv6 lookups are attempted. The optional -argument @var{family} controls this behavior, specifying the symbol -@code{ipv4} or @code{ipv6} restricts lookups to IPv4 and IPv6 +@defun network-lookup-address-info name &optional family hints +This function perform hostname lookups on @var{name}, which is +expected to be an ASCII-only string, otherwise it signals an error. Call +@code{puny-encode-domain} on @var{name} first if you wish to lookup +internationalized hostnames. + +If successful, this function returns a list of Lisp representations of network +addresses (@pxref{Network Processes}, for a description of the +format), otherwise return @code{nil}. In the latter case, it also logs +an error message hopefully explaining what went wrong. + +By default, this function attempts both IPv4 and IPv6 lookups. The +optional argument @var{family} controls this behavior, specifying the +symbol @code{ipv4} or @code{ipv6} restricts lookups to IPv4 and IPv6 respectively. + +If optional argument @var{hints} is @code{numeric}, the function +treats the @var{name} as a numerical IP address (and does not perform DNS +lookups). This can be used to check whether a string is a valid +numerical representation of an IP address, or to convert a numerical +string to its canonical representation. e.g.@: + +@example +(network-lookup-address-info "127.1" 'ipv4 'numeric) + @result{} ([127 0 0 1 0]) + +(network-lookup-address-info "::1" nil 'numeric) + @result{} ([0 0 0 0 0 0 0 1 0]) +@end example + +Be warned that there are some surprising valid forms, +especially for IPv4, e.g @samp{0xe3010203} and @samp{0343.1.2.3} are both +valid, as are @samp{0} and @samp{1} (but they are invalid for IPv6). @end defun @node Serial Ports diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index addf195fad2..374381e5955 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -560,6 +560,12 @@ Representations}. @code{string-equal} is another name for @code{string=}. @end defun +@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 +@code{t}. +@end defun + @cindex locale-dependent string equivalence @defun string-collate-equalp string1 string2 &optional locale ignore-case This function returns @code{t} if @var{string1} and @var{string2} are @@ -567,11 +573,19 @@ equal with respect to collation rules. A collation rule is not only determined by the lexicographic order of the characters contained in @var{string1} and @var{string2}, but also further rules about relations between these characters. Usually, it is defined by the -@var{locale} environment Emacs is running with. - -For example, characters with different coding points but -the same meaning might be considered as equal, like different grave -accent Unicode characters: +@var{locale} environment Emacs is running with and by the Standard C +library against which Emacs was linked@footnote{ +For more information about collation rules and their locale +dependencies, see @uref{https://unicode.org/reports/tr10/, The Unicode +Collation Algorithm}. Some Standard C libraries, such as the +@acronym{GNU} C Library (a.k.a.@: @dfn{glibc}) implement large +portions of the Unicode Collation Algorithm and use the associated +locale data, Common Locale Data Repository, or @acronym{CLDR}. +}. + +For example, characters with different code points but the same +meaning, like different grave accent Unicode characters, might, in +some locales, be considered as equal: @example @group @@ -759,7 +773,8 @@ The strings are compared by the numeric values of their characters. For instance, @var{str1} is considered less than @var{str2} if its first differing character has a smaller numeric value. If @var{ignore-case} is non-@code{nil}, characters are converted to -upper-case before comparing them. Unibyte strings are converted to +upper-case, using the current buffer's case-table (@pxref{Case +Tables}), before comparing them. Unibyte strings are converted to multibyte for comparison (@pxref{Text Representations}), so that a unibyte string and its conversion to multibyte are always regarded as equal. diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 30146a89ebf..9faf3f33ba8 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -689,6 +689,18 @@ line. This looks nice in the source code, but looks bizarre when users view the documentation. Remember that the indentation before the starting double-quote is not part of the string! +@item +When documentation should display an ASCII apostrophe or grave accent, +use @samp{\\='} or @samp{\\=`} in the documentation string literal so +that the character is displayed as-is. + +@item +In documentation strings, do not quote expressions that are not Lisp symbols, +as these expressions can stand for themselves. For example, write +@samp{Return the list (NAME TYPE RANGE) ...}@: instead of +@samp{Return the list `(NAME TYPE RANGE)' ...}@: or +@samp{Return the list \\='(NAME TYPE RANGE) ...}. + @anchor{Docstring hyperlinks} @item @cindex curly quotes @@ -700,7 +712,7 @@ two exceptions: write @code{t} and @code{nil} without surrounding punctuation. For example: @example - CODE can be `lambda', nil, or t. +CODE can be `lambda', nil, or t. @end example Note that when Emacs displays these doc strings, Emacs will usually @@ -856,7 +868,7 @@ find an alternate phrasing that conveys the meaning. @item Try to avoid using abbreviations such as ``e.g.'' (for ``for example''), ``i.e.'' (for ``that is''), ``no.'' (for ``number''), -``c.f.'' (for ``in contrast to'') and ``w.r.t.'' (for ``with respect +``cf.'' (for ``in contrast to'') and ``w.r.t.'' (for ``with respect to'') as much as possible. It is almost always clearer and easier to read the expanded version.@footnote{We do use these occasionally, but try not to overdo it.} diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 535571b3161..c7f014e2f3b 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -737,7 +737,7 @@ with any other @var{round} it returns the internal value of @cindex window width @cindex width of a window @cindex total width of a window -The @dfn{total width} of a window is the number of lines comprising its +The @dfn{total width} of a window is the number of columns comprising its body and its left and right decorations (@pxref{Basic Windows}). @defun window-total-width &optional window round @@ -747,7 +747,7 @@ the selected window. If @var{window} is internal, the return value is the total width occupied by its descendant windows. If a window's pixel width is not an integral multiple of its frame's -character width, the number of lines occupied by the window is rounded +character width, the number of columns occupied by the window is rounded internally. This is done in a way such that, if the window is a parent window, the sum of the total widths of all its children internally equals the total width of their parent. This means that although two diff --git a/doc/misc/autotype.texi b/doc/misc/autotype.texi index b005c9c34f7..93c65692d01 100644 --- a/doc/misc/autotype.texi +++ b/doc/misc/autotype.texi @@ -92,7 +92,6 @@ completions and expansions of text at point. * Copyrights:: Inserting and updating copyrights. * Executables:: Turning interpreter scripts into executables. * Timestamps:: Updating dates and times in modified files. -* QuickURL:: Inserting URLs based on text at point. * Tempo:: Flexible template insertion. * Hippie Expand:: Expansion of text trying various methods. * Skeleton Language:: Making skeleton commands insert what you want. @@ -478,31 +477,6 @@ The time stamp is written between the brackets or quotes: Time-stamp: <1998-02-18 10:20:51 gildea> @end example -@node QuickURL -@chapter QuickURL: Inserting URLs Based on Text at Point - -@vindex quickurl-url-file -@findex quickurl -@cindex URLs -@kbd{M-x quickurl} can be used to insert a URL into a buffer based on -the text at point. The URLs are stored in an external file defined by -the variable @code{quickurl-url-file} as a list of either cons cells of -the form @code{(@var{key} . @var{URL})} or -lists of the form @code{(@var{key} @var{URL} @var{comment})}. These -specify that @kbd{M-x quickurl} should insert @var{URL} if the word -@var{key} is at point, for example: - -@example -(("FSF" "https://www.fsf.org/" "The Free Software Foundation") - ("emacs" . "https://www.gnu.org/software/emacs/")) -@end example - -@findex quickurl-add-url -@findex quickurl-list -@kbd{M-x quickurl-add-url} can be used to add a new @var{key}/@var{URL} -pair. @kbd{M-x quickurl-list} provides interactive editing of the URL -list. - @node Tempo @chapter Tempo: Flexible Template Insertion diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi index af8e2153dd8..9867883b24a 100644 --- a/doc/misc/ede.texi +++ b/doc/misc/ede.texi @@ -1551,14 +1551,14 @@ This is a URL to be sent to a web site for documentation. @item :web-site-directory @* A directory where web pages can be found by Emacs. -For remote locations use a path compatible with ange-ftp or EFS@. +For remote locations use a path compatible with ange-ftp. You can also use TRAMP for use with rcp & scp. @item :web-site-file @* A file which contains the website for this project. This file can be relative to slot @code{web-site-directory}. -This can be a local file, use ange-ftp, EFS, or TRAMP. +This can be a local file, use ange-ftp or TRAMP. @item :ftp-site Type: @code{string} @* diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index 6b5173d3c2f..7da90dfb1d6 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -17518,16 +17518,16 @@ If you have a directory that has lots of articles in separate files in it, you might treat it as a newsgroup. The files have to have numerical names, of course. -This might be an opportune moment to mention @code{ange-ftp} (and its -successor @code{efs}), that most wonderful of all wonderful Emacs -packages. When I wrote @code{nndir}, I didn't think much about it---a -back end to read directories. Big deal. +This might be an opportune moment to mention @code{ange-ftp}, that +most wonderful of all wonderful Emacs packages. When I wrote +@code{nndir}, I didn't think much about it---a back end to read +directories. Big deal. @code{ange-ftp} changes that picture dramatically. For instance, if you enter the @code{ange-ftp} file name @file{/ftp.hpc.uh.edu:/pub/emacs/ding-list/} as the directory name, -@code{ange-ftp} or @code{efs} will actually allow you to read this -directory over at @samp{sina} as a newsgroup. Distributed news ahoy! +@code{ange-ftp} will actually allow you to read this directory over at +@samp{sina} as a newsgroup. Distributed news ahoy! @code{nndir} will use @acronym{NOV} files if they are present. @@ -26778,7 +26778,7 @@ on finding a separator line between the head and the body. If this variable is @code{nil}, there is no upper read bound. If it is @code{t}, the back ends won't try to read the articles piece by piece, but read the entire articles. This makes sense with some versions of -@code{ange-ftp} or @code{efs}. +@code{ange-ftp}. @item nnheader-head-chop-length @vindex nnheader-head-chop-length |