diff options
Diffstat (limited to 'doc')
125 files changed, 12894 insertions, 4704 deletions
diff --git a/doc/emacs/ChangeLog.1 b/doc/emacs/ChangeLog.1 index c1c5f5407da..048b7bd99a5 100644 --- a/doc/emacs/ChangeLog.1 +++ b/doc/emacs/ChangeLog.1 @@ -8529,7 +8529,7 @@ * text.texi (Cell Justification): * trouble.texi (After a Crash): * xresources.texi (GTK styles): - Delete duplicate duplicate words. + Delete duplicate words. 2005-07-17 Richard M. Stallman <rms@gnu.org> diff --git a/doc/emacs/Makefile.in b/doc/emacs/Makefile.in index 8bde875e60d..a24c03ead3b 100644 --- a/doc/emacs/Makefile.in +++ b/doc/emacs/Makefile.in @@ -140,6 +140,7 @@ EMACSSOURCES= \ ${srcdir}/xresources.texi \ ${srcdir}/anti.texi \ ${srcdir}/macos.texi \ + $(srcdir)/haiku.texi \ ${srcdir}/msdos.texi \ ${srcdir}/gnu.texi \ ${srcdir}/glossary.texi \ diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi index c2e8b4cae05..77f40c7df2d 100644 --- a/doc/emacs/abbrevs.texi +++ b/doc/emacs/abbrevs.texi @@ -106,8 +106,10 @@ taken as the expansion. For example, to define the abbrev @samp{foo} as mentioned above, insert the text @samp{find outer otter} and then type @kbd{C-u 3 C-x a g f o o @key{RET}}. - An argument of zero to @kbd{C-x a g} means to use the contents of the -region as the expansion of the abbrev being defined. + If you're using @code{transient-mark-mode} (which is the default), +the active region will be used as the expansion of the abbrev being +defined. If not, an argument of zero to @kbd{C-x a g} means to use +the contents of the region. @kindex C-x a l @findex add-mode-abbrev @@ -274,7 +276,7 @@ Edit a list of abbrevs; you can add, alter or remove definitions. @example @var{various other tables@dots{}} (lisp-mode-abbrev-table) -"dk" 0 "define-key" +"ks" 0 "keymap-set" (global-abbrev-table) "dfn" 0 "definition" @end example @@ -411,10 +413,13 @@ away in the buffer to search for an expansion. @vindex dabbrev-check-all-buffers @vindex dabbrev-check-other-buffers +@vindex dabbrev-ignored-buffer-modes After scanning the current buffer, @kbd{M-/} normally searches other buffers. The variables @code{dabbrev-check-all-buffers} and @code{dabbrev-check-other-buffers} can be used to determine which -other buffers, if any, are searched. +other buffers, if any, are searched. Buffers that have major modes +derived from any of the modes in @code{dabbrev-ignored-buffer-modes} +are ignored. @vindex dabbrev-ignored-buffer-names @vindex dabbrev-ignored-buffer-regexps diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi index 196a28be5a1..1a4abdc9ecd 100644 --- a/doc/emacs/basic.texi +++ b/doc/emacs/basic.texi @@ -347,11 +347,11 @@ move to the column number specified by the argument's numeric value. @kindex C-x C-n @findex set-goal-column Use the current column of point as the @dfn{semipermanent goal column} -for @kbd{C-n} and @kbd{C-p} (@code{set-goal-column}) in the current -buffer. When a semipermanent goal column is in effect, those commands -always try to move to this column, or as close as possible to it, -after moving vertically. The goal column remains in effect until -canceled. +(@code{set-goal-column}) in the current buffer. When a semipermanent +goal column is in effect, @kbd{C-n}, @kbd{C-p}, @kbd{<prior>} and +@kbd{<next>} always try to move to this column, or as close as +possible to it, after moving vertically. The goal column remains in +effect until canceled. @item C-u C-x C-n Cancel the goal column. Henceforth, @kbd{C-n} and @kbd{C-p} try to @@ -653,14 +653,14 @@ Toggle automatic display of the current line number or column number. displayed before each line, see @ref{Display Custom}. @item M-= -Display the number of lines, words, and characters that are present in -the region (@code{count-words-region}). @xref{Mark}, for information -about the region. +Display the number of lines, sentences, words, and characters that are +present in the region (@code{count-words-region}). @xref{Mark}, for +information about the region. @item M-x count-words -Display the number of lines, words, and characters that are present in -the buffer. If the region is active (@pxref{Mark}), display the -numbers for the region instead. +Display the number of lines, sentences, words, and characters that are +present in the buffer. If the region is active (@pxref{Mark}), +display the numbers for the region instead. @item C-x = Display the character code of character after point, character position of @@ -689,7 +689,7 @@ narrowed region and the line number relative to the whole buffer. @kindex M-= @findex count-words-region @kbd{M-=} (@code{count-words-region}) displays a message reporting -the number of lines, words, and characters in the region +the number of lines, sentences, words, and characters in the region (@pxref{Mark}, for an explanation of the region). With a prefix argument, @kbd{C-u M-=}, the command displays a count for the entire buffer. diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi index a1ad4926be7..120c957ff86 100644 --- a/doc/emacs/buffers.texi +++ b/doc/emacs/buffers.texi @@ -630,7 +630,6 @@ buffer, but killing an indirect buffer has no effect on its base buffer. One way to use indirect buffers is to display multiple views of an outline. @xref{Outline Views}. -@vindex clone-indirect-buffer-hook A quick and handy way to make an indirect buffer is with the command @kbd{M-x clone-indirect-buffer}. It creates and selects an indirect buffer whose base buffer is the current buffer. With a numeric @@ -638,14 +637,19 @@ argument, it prompts for the name of the indirect buffer; otherwise it uses the name of the current buffer, with a @samp{<@var{n}>} suffix added. @kbd{C-x 4 c} (@code{clone-indirect-buffer-other-window}) works like @kbd{M-x clone-indirect-buffer}, but it selects the new -buffer in another window. These functions run the hook -@code{clone-indirect-buffer-hook} after creating the indirect buffer. +buffer in another window. The more general way to make an indirect buffer is with the command @kbd{M-x make-indirect-buffer}. It creates an indirect buffer named @var{indirect-name} from a buffer @var{base-buffer}, prompting for both using the minibuffer. +@vindex clone-indirect-buffer-hook + The functions that create indirect buffers run the hook +@code{clone-indirect-buffer-hook} after creating the indirect buffer. +When this hook runs, the newly created indirect buffer is the current +buffer. + Note: When a modification is made to the text of a buffer, the modification hooks are run only in the base buffer, because most of the functions on those hooks are not prepared to work correctly in diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index 5b68b1ef9fa..b79fa0a755c 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -138,6 +138,14 @@ of environment variable settings; each element should be a string of the form @code{"@var{envvarname}=@var{value}"}. These environment variable settings override the usual ones. +@vindex compilation-max-output-line-length + Displaying extremely long lines in compilation output can slow Emacs +down. Lines that are longer than +@code{compilation-max-output-line-length} will have the portion that's +exceeds that limit hidden behind a button that can be clicked on to +reveal the hidden portion. Set this variable to @code{nil} to never +hide anything. + @node Compilation Mode @section Compilation Mode @@ -170,7 +178,9 @@ list of customization variables and faces. If you change the variable @code{compilation-auto-jump-to-first-error} to a non-@code{nil} value, Emacs automatically visits the locus of the first error message that -appears in the @file{*compilation*} buffer. +appears in the @file{*compilation*} buffer. (This variable can also +have the values @code{if-location-known} and @code{first-known}, which +modify the conditions for automatically visiting the error locus.) Compilation mode provides the following additional commands. These commands can also be used in @file{*grep*} buffers, where the @@ -279,6 +289,19 @@ window so that the current error message is @var{n} lines from the top, whether or not there is a fringe; the default value, @code{nil}, gives the behavior described above. +@vindex compilation-hidden-output + Compilation output can sometimes be very verbose, and much of it isn't +of particular interest to a user. The +@code{compilation-hidden-output} user option should either be a regexp +or a list of regexps, and output that matches will be made invisible. +For instance, to hide the verbose output from recursive makefiles, you +can say something like: + +@lisp +(setq compilation-hidden-output + '("^make[^\n]+\n")) +@end lisp + @vindex compilation-error-regexp-alist @vindex grep-regexp-alist To parse messages from the compiler, Compilation mode uses the @@ -1734,6 +1757,10 @@ which is provided for evaluating Emacs Lisp expressions interactively. Its major mode is Lisp Interaction mode. You can also enable Lisp Interaction mode by typing @kbd{M-x lisp-interaction-mode}. +@findex scratch-buffer + If you kill the @file{*scratch*} buffer, you can recreate it with +the @kbd{M-x scratch-buffer} command. + @findex eval-print-last-sexp @kindex C-j @r{(Lisp Interaction mode)} In the @file{*scratch*} buffer, and other Lisp Interaction mode diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi index ffab2b2213b..0f7acd87978 100644 --- a/doc/emacs/cmdargs.texi +++ b/doc/emacs/cmdargs.texi @@ -185,6 +185,11 @@ successfully. @item --version @opindex --version Print Emacs version, then exit successfully. + +@item --fingerprint +@opindex --fingerprint +Print the Emacs ``fingerprint'', which is used to uniquely identify +the compiled version of Emacs. @end table @node Initial Options @@ -289,6 +294,22 @@ which will invoke Emacs with @samp{--script} and supply the name of the script file as @var{file}. Emacs Lisp then treats the @samp{#!} on this first line as a comment delimiter. +@item -x +@opindex -x +This option can only be used in executable script files, and should be +invoked like this: + +@example +#!/usr/bin/emacs -x +@end example + +This is like @samp{--script}, but suppresses loading the init files +(like @code{--quick}), and can't be used on a normal command line +(since it doesn't specify the script to load). In addition, when it +reaches the end of the script, it exits Emacs and uses the value of +the final form as the exit value from the script (if the final value +is numerical). Otherwise, it will always exit with a zero value. + @item --no-build-details @opindex --no-build-details @cindex build details @@ -324,6 +345,10 @@ option does this too, but other options like @samp{-q} do not. Do not include the @file{site-lisp} directories in @code{load-path} (@pxref{Init File}). The @samp{-Q} option does this too. +@item --init-directory +@opindex --init-directory +Specify the directory to use when looking for the Emacs init files. + @item --no-splash @opindex --no-splash @cindex splash screen @@ -751,6 +776,10 @@ On MS-Windows, if you set this variable, Emacs will load and initialize the network library at startup, instead of waiting until the first time it is required. +@item WAYLAND_DISPLAY +Pgtk Emacs (built with @option{--with-pgtk}) can run on Wayland natively. +@env{WAYLAND_DISPLAY} specifies the connection to the compositor. + @item emacs_dir On MS-Windows, @env{emacs_dir} is a special environment variable, which indicates the full path of the directory in which Emacs is installed. diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 2d63b2a7175..ff7ab83190c 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -195,7 +195,7 @@ the customization buffer: The first line shows that the variable is named @code{kill-ring-max}, formatted as @samp{Kill Ring Max} for easier -viewing. Its value is @samp{60}. The button labeled @samp{[Hide]}, +viewing. Its value is @samp{120}. The button labeled @samp{[Hide]}, if activated, hides the variable's value and state; this is useful to avoid cluttering up the customization buffer with very long values (for this reason, variables that have very long values may start out @@ -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}. @@ -844,6 +847,21 @@ otherwise stated, affects only the current Emacs session. The only way to alter the variable in future sessions is to put something in your initialization file (@pxref{Init File}). + If you're setting a customizable variable in your initialization +file, and you don't want to use the Customize interface, you can use +the @code{setopt} macro. For instance: + +@findex setopt +@example +(setopt fill-column 75) +@end example + +This works the same as @code{setq}, but if the variable has any +special setter functions, they will be run automatically when using +@code{setopt}. You can also use @code{setopt} on other, +non-customizable variables, but this is less efficient than using +@code{setq}. + @node Hooks @subsection Hooks @cindex hook @@ -1217,6 +1235,28 @@ Manual}. These four keywords are not really variables; setting them in any other context has no special meaning. + If you're editing a file across Emacs versions, and a new mode has +been introduced to handle a file in a newer Emacs version, you can use +several @code{mode} entries to use the new mode (called +@code{my-new-mode}) in the new Emacs, and fall back to the old mode +(called @code{my-old-mode}) in older Emacs versions. If you're +enabling the modes in the first line of the file, can say: + +@example +-*- mode: my-old; mode: my-new -*- +@end example + + Emacs will use the final defined mode it finds, so in older Emacs +versions it will ignore @code{my-new-mode}, while in Emacs versions +where @code{my-new-mode} is defined, it'll ignore @code{my-old-mode}. +Similarly, in a local variable block at the end of the file: + +@example +Local variables: +mode: my-old +mode: my-new +@end example + Do not use the @code{mode} keyword for minor modes. To enable or disable a minor mode in a local variables list, use the @code{eval} keyword with a Lisp expression that runs the mode command @@ -1474,9 +1514,10 @@ as Dired buffers (@pxref{Dired}). Most of the variables reflect the situation on the local machine. Often, they must use a different value when you operate in buffers -with a remote default directory. Think about the shell to be applied -when calling @code{shell} -- it might be @file{/bin/bash} on your -local machine, and @file{/bin/ksh} on a remote machine. +with a remote default directory. Think about the behavior when +calling @code{shell} -- on your local machine, you might use +@file{/bin/bash} and rely on termcap, but on a remote machine, it may +be @file{/bin/ksh} and terminfo. This can be accomplished with @dfn{connection-local variables}. Directory and file local variables override connection-local @@ -1492,6 +1533,10 @@ variables/value pairs in a @dfn{profile}, using the criteria, identifying a remote machine: @example +(connection-local-set-profile-variables 'remote-terminfo + '((system-uses-terminfo . t) + (comint-terminfo-terminal . "dumb-emacs-ansi"))) + (connection-local-set-profile-variables 'remote-ksh '((shell-file-name . "/bin/ksh") (shell-command-switch . "-c"))) @@ -1501,11 +1546,13 @@ criteria, identifying a remote machine: (shell-command-switch . "-c"))) (connection-local-set-profiles - '(:application tramp :machine "remotemachine") 'remote-ksh) + '(:application tramp :machine "remotemachine") + 'remote-terminfo 'remote-ksh) @end example - This code declares two different profiles, @code{remote-ksh} and -@code{remote-bash}. The profile @code{remote-ksh} is applied to all + This code declares three different profiles, @code{remote-terminfo}, +@code{remote-ksh}, and @code{remote-bash}. The profiles +@code{remote-terminfo} and @code{remote-ksh} are applied to all buffers which have a remote default directory matching the regexp @code{"remotemachine"} as host name. Such a criteria can also discriminate for the properties @code{:protocol} (this is the Tramp @@ -1577,7 +1624,7 @@ which overrides the global definitions of some keys. self-inserting because the global keymap binds it to the command @code{self-insert-command}. The standard Emacs editing characters such as @kbd{C-a} also get their standard meanings from the global -keymap. Commands to rebind keys, such as @kbd{M-x global-set-key}, +keymap. Commands to rebind keys, such as @kbd{M-x keymap-global-set}, work by storing the new binding in the proper place in the global map (@pxref{Rebinding}). To view the current key bindings, use the @kbd{C-h b} command. @@ -1727,8 +1774,8 @@ them, it may be convenient to disable completion on those keys by putting this in your init file: @lisp -(define-key minibuffer-local-completion-map " " 'self-insert-command) -(define-key minibuffer-local-completion-map "?" 'self-insert-command) +(keymap-set minibuffer-local-completion-map "SPC" 'self-insert-command) +(keymap-set minibuffer-local-completion-map "?" 'self-insert-command) @end lisp @node Rebinding @@ -1747,19 +1794,19 @@ local keymap, which affects all buffers using the same major mode. Emacs session. @xref{Init Rebinding}, for a description of how to make key rebindings affect future Emacs sessions. -@findex global-set-key -@findex local-set-key -@findex global-unset-key -@findex local-unset-key +@findex keymap-global-set +@findex keymap-local-set +@findex keymap-global-unset +@findex keymap-local-unset @table @kbd -@item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET} +@item M-x keymap-global-set @key{RET} @var{key} @var{cmd} @key{RET} Define @var{key} globally to run @var{cmd}. -@item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET} +@item M-x keymap-local-set @key{RET} @var{key} @var{cmd} @key{RET} Define @var{key} locally (in the major mode now in effect) to run @var{cmd}. -@item M-x global-unset-key @key{RET} @var{key} +@item M-x keymap-global-unset @key{RET} @var{key} Make @var{key} undefined in the global map. -@item M-x local-unset-key @key{RET} @var{key} +@item M-x keymap-local-unset @key{RET} @var{key} Make @var{key} undefined locally (in the major mode now in effect). @end table @@ -1768,11 +1815,11 @@ command (@pxref{Interactive Shell}), replacing the normal global definition of @kbd{C-z}: @example -M-x global-set-key @key{RET} C-z shell @key{RET} +M-x keymap-global-set @key{RET} C-z shell @key{RET} @end example @noindent -The @code{global-set-key} command reads the command name after the +The @code{keymap-global-set} command reads the command name after the key. After you press the key, a message like this appears so that you can confirm that you are binding the key you want: @@ -1793,7 +1840,7 @@ reads another character; if that is @kbd{4}, another prefix character, it reads one more character, and so on. For example, @example -M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET} +M-x keymap-global-set @key{RET} C-x 4 $ spell-other-window @key{RET} @end example @noindent @@ -1801,8 +1848,8 @@ redefines @kbd{C-x 4 $} to run the (fictitious) command @code{spell-other-window}. You can remove the global definition of a key with -@code{global-unset-key}. This makes the key @dfn{undefined}; if you -type it, Emacs will just beep. Similarly, @code{local-unset-key} makes +@code{keymap-global-unset}. This makes the key @dfn{undefined}; if you +type it, Emacs will just beep. Similarly, @code{keymap-local-unset} makes a key undefined in the current major mode keymap, which makes the global definition (or lack of one) come back into effect in that major mode. @@ -1835,11 +1882,11 @@ you can specify them in your initialization file by writing Lisp code. simplest is to use the @code{kbd} function, which converts a textual representation of a key sequence---similar to how we have written key sequences in this manual---into a form that can be passed as an -argument to @code{global-set-key}. For example, here's how to bind +argument to @code{keymap-global-set}. For example, here's how to bind @kbd{C-z} to the @code{shell} command (@pxref{Interactive Shell}): @example -(global-set-key (kbd "C-z") 'shell) +(keymap-global-set "C-z" 'shell) @end example @noindent @@ -1852,69 +1899,24 @@ causes an error; it certainly isn't what you want. and mouse events: @example -(global-set-key (kbd "C-c y") 'clipboard-yank) -(global-set-key (kbd "C-M-q") 'query-replace) -(global-set-key (kbd "<f5>") 'flyspell-mode) -(global-set-key (kbd "C-<f5>") 'display-line-numbers-mode) -(global-set-key (kbd "C-<right>") 'forward-sentence) -(global-set-key (kbd "<mouse-2>") 'mouse-save-then-kill) -@end example - - Instead of using @code{kbd}, you can use a Lisp string or vector to -specify the key sequence. Using a string is simpler, but only works -for @acronym{ASCII} characters and Meta-modified @acronym{ASCII} -characters. For example, here's how to bind @kbd{C-x M-l} to -@code{make-symbolic-link} (@pxref{Copying and Naming}): - -@example -(global-set-key "\C-x\M-l" 'make-symbolic-link) -@end example - - To bind a key sequence including @key{TAB}, @key{RET}, @key{ESC}, or -@key{DEL}, the string should contain the Emacs Lisp escape sequence -@samp{\t}, @samp{\r}, @samp{\e}, or @samp{\d} respectively. Here is -an example which binds @kbd{C-x @key{TAB}} to @code{indent-rigidly} -(@pxref{Indentation}): - -@example -(global-set-key "\C-x\t" 'indent-rigidly) -@end example - - When the key sequence includes function keys or mouse button events, -or non-@acronym{ASCII} characters such as @code{C-=} or @code{H-a}, -you can use a vector to specify the key sequence. Each element in the -vector stands for an input event; the elements are separated by spaces -and surrounded by a pair of square brackets. If a vector element is a -character, write it as a Lisp character constant: @samp{?} followed by -the character as it would appear in a string. Function keys are -represented by symbols (@pxref{Function Keys}); simply write the -symbol's name, with no other delimiters or punctuation. Here are some -examples: - -@example -(global-set-key [?\C-=] 'make-symbolic-link) -(global-set-key [?\M-\C-=] 'make-symbolic-link) -(global-set-key [?\H-a] 'make-symbolic-link) -(global-set-key [f7] 'make-symbolic-link) -(global-set-key [C-mouse-1] 'make-symbolic-link) -@end example - -@noindent -You can use a vector for the simple cases too: - -@example -(global-set-key [?\C-z ?\M-l] 'make-symbolic-link) +(keymap-global-set "C-c y" 'clipboard-yank) +(keymap-global-set "C-M-q" 'query-replace) +(keymap-global-set "<f5>" 'flyspell-mode) +(keymap-global-set "C-<f5>" 'display-line-numbers-mode) +(keymap-global-set "C-<right>" 'forward-sentence) +(keymap-global-set "<mouse-2>" 'mouse-save-then-kill) @end example Language and coding systems may cause problems with key bindings for non-@acronym{ASCII} characters. @xref{Init Non-ASCII}. -@findex define-key +@findex keymap-set +@findex keymap-unset As described in @ref{Local Keymaps}, major modes and minor modes can define local keymaps. These keymaps are constructed when the mode is -loaded for the first time in a session. The function @code{define-key} -can be used to make changes in a specific keymap. This function can -also unset keys, when passed @code{nil} as the binding. +loaded for the first time in a session. The function @code{keymap-set} +can be used to make changes in a specific keymap. To remove a key +binding, use @code{keymap-unset}. Since a mode's keymaps are not constructed until it has been loaded, you must delay running code which modifies them, e.g., by putting it @@ -1926,11 +1928,11 @@ the one for @kbd{C-c C-x x} in Texinfo mode: @example (add-hook 'texinfo-mode-hook (lambda () - (define-key texinfo-mode-map "\C-cp" + (keymap-set texinfo-mode-map "C-c p" 'backward-paragraph) - (define-key texinfo-mode-map "\C-cn" + (keymap-set texinfo-mode-map "C-c n" 'forward-paragraph))) - (define-key texinfo-mode-map "\C-c\C-xx" nil) + (keymap-set texinfo-mode-map "C-c C-x x" nil) @end example @node Modifier Keys @@ -1952,7 +1954,7 @@ between those keystrokes. However, you can bind shifted @key{Control} alphabetical keystrokes in GUI frames: @lisp -(global-set-key (kbd "C-S-n") #'previous-line) +(keymap-global-set "C-S-n" #'previous-line) @end lisp For all other modifiers, you can make the modified alphabetical @@ -2106,7 +2108,7 @@ button, @code{mouse-2} for the next, and so on. Here is how you can redefine the second mouse button to split the current window: @example -(global-set-key [mouse-2] 'split-window-below) +(keymap-global-set "<mouse-2>" 'split-window-below) @end example The symbols for drag events are similar, but have the prefix @@ -2189,7 +2191,7 @@ Thus, here is how to define the command for clicking the first button in a mode line to run @code{scroll-up-command}: @example -(global-set-key [mode-line mouse-1] 'scroll-up-command) +(keymap-global-set "<mode-line> <mouse-1>" 'scroll-up-command) @end example Here is the complete list of these dummy prefix keys and their @@ -2257,6 +2259,22 @@ is included in the message displayed when the command is used: "It's better to use `kill-region' instead.\n") @end example +@findex command-query + As a less heavy-handed alternative to disabling commands, you may +want to be queried before executing a command. For instance, to be +queried before executing the @kbd{M->} (@code{end-of-buffer}) +command, you could put something like the following in your init file: + +@example +(command-query + 'end-of-buffer + "Do you really want to go to the end of the buffer?") +@end example + +By default, you'll be queried with a @kbd{y}/@kbd{n} question, but if +you give a non-@code{nil} value to the third, optional argument, +you'll be queried with @kbd{yes}/@kbd{no} instead. + @findex disable-command @findex enable-command You can make a command disabled either by editing the initialization @@ -2285,6 +2303,8 @@ as a function from Lisp programs. @cindex startup (init file) @cindex XDG_CONFIG_HOME +@c When updating this, also update ``Setting up a customization file'' +@c in efaq.texi. When Emacs is started, it normally tries to load a Lisp program from an @dfn{initialization file}, or @dfn{init file} for short. This file, if it exists, specifies how to initialize Emacs for you. @@ -2376,8 +2396,8 @@ mode when you set them with Customize, but ordinary @code{setq} won't do that; to enable the mode in your init file, call the minor mode command. Finally, a few customizable user options are initialized in complex ways, and these have to be set either via the customize -interface (@pxref{Customization}) or by using -@code{customize-set-variable} (@pxref{Examining}). +interface (@pxref{Customization}), or by using +@code{customize-set-variable}/@code{setopt} (@pxref{Examining}). The second argument to @code{setq} is an expression for the new value of the variable. This can be a constant, a variable, or a @@ -2533,7 +2553,7 @@ Change the coding system used when using the clipboard (@pxref{Communication Coding}). @example -(customize-set-variable 'selection-coding-system 'utf-8) +(setopt selection-coding-system 'utf-8) @end example @item @@ -2583,13 +2603,13 @@ Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link} (@pxref{Init Rebinding}). @example -(global-set-key "\C-xl" 'make-symbolic-link) +(keymap-global-set "C-x l" 'make-symbolic-link) @end example or @example -(define-key global-map "\C-xl" 'make-symbolic-link) +(keymap-set global-map "C-x l" 'make-symbolic-link) @end example Note once again the single-quote used to refer to the symbol @@ -2599,24 +2619,23 @@ Note once again the single-quote used to refer to the symbol Do the same thing for Lisp mode only. @example -(define-key lisp-mode-map "\C-xl" 'make-symbolic-link) +(keymap-set lisp-mode-map "C-x l" 'make-symbolic-link) @end example @item Redefine all keys which now run @code{next-line} in Fundamental mode so that they run @code{forward-line} instead. -@findex substitute-key-definition +@findex keymap-substitute @example -(substitute-key-definition 'next-line 'forward-line - global-map) +(keymap-substitute global-map 'next-line 'forward-line) @end example @item Make @kbd{C-x C-v} undefined. @example -(global-unset-key "\C-x\C-v") +(keymap-global-unset "C-x C-v") @end example One reason to undefine a key is so that you can make it a prefix. @@ -2792,18 +2811,6 @@ strings incorrectly. You should then avoid adding Emacs Lisp code that modifies the coding system in other ways, such as calls to @code{set-language-environment}. - To bind non-@acronym{ASCII} keys, you must use a vector (@pxref{Init -Rebinding}). The string syntax cannot be used, since the -non-@acronym{ASCII} characters will be interpreted as meta keys. For -instance: - -@example -(global-set-key [?@var{char}] 'some-function) -@end example - -@noindent -Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}. - @node Early Init File @subsection The Early Init File @cindex early init file diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi index 6acee25cee1..33e9270d42d 100644 --- a/doc/emacs/dired.texi +++ b/doc/emacs/dired.texi @@ -41,6 +41,7 @@ you to operate on the listed files. @xref{Directories}. * Operating on Files:: How to copy, rename, print, compress, etc. either one file or several files. * Shell Commands in Dired:: Running a shell command on the marked files. +* Shell Command Guessing:: Guessing shell commands for files. * Transforming File Names:: Using patterns to rename multiple files. * Comparison in Dired:: Running @code{diff} by way of Dired. * Subdirectories in Dired:: Adding subdirectories to the Dired buffer. @@ -122,7 +123,7 @@ listing. As an exception, if you type @kbd{C-x C-j} in a Dired buffer, Emacs displays the directory listing of the parent directory and places point on the line that corresponds to the directory where you invoked @code{dired-jump}. Typing @kbd{C-x 4 C-j} -(@code{dired-jump-other-window} has the same effect, but displays the +(@code{dired-jump-other-window}) has the same effect, but displays the Dired buffer in a new window. The variable @code{dired-listing-switches} specifies the options to @@ -748,6 +749,15 @@ never creates such missing directories; the value @code{always}, means Dired automatically creates them; the value @code{ask} means Dired asks you for confirmation before creating them. +@vindex dired-create-destination-dirs-on-trailing-dirsep +If the option @code{dired-create-destination-dirs-on-trailing-dirsep} +is non-@code{nil} in addition to @code{dired-create-destination-dirs}, +a trailing directory separator at the destination directory is treated +specially. In that case, when copying to @samp{test/} and no +directory @samp{test} exists already, it will be created and the +specified source files or directories are copied into the newly +created directory. + @vindex dired-copy-preserve-time If @code{dired-copy-preserve-time} is non-@code{nil}, then copying with this command preserves the modification time of the old file in @@ -767,6 +777,11 @@ symbolic links as links or after dereferencing (like @samp{cp -L}). The default is @code{nil}, which means that the symbolic links are copied by creating new ones. +@vindex dired-keep-marker-copy +The @code{dired-keep-marker-copy} user option controls how this +command handles file marking. The default is to mark all new copies +of files with a @samp{C} mark. + @item D @findex dired-do-delete @kindex D @r{(Dired)} @@ -790,6 +805,14 @@ which to move the files (this is like the shell command @command{mv}). The option @code{dired-create-destination-dirs} controls whether Dired should create non-existent directories in @var{new}. +The option @code{dired-create-destination-dirs-on-trailing-dirsep}, +when set in addition to @code{dired-create-destination-dirs}, controls +wether a trailing directory separator at the destination is treated +specially. In that case, when renaming a directory @samp{old} to +@samp{new/} and no directory @samp{new} exists already, it will be +created and @samp{old} is moved into the newly created directory. +Otherwise, @samp{old} is renamed to @samp{new}. + Dired automatically changes the visited file name of buffers associated with renamed files so that they refer to the new names. @@ -822,6 +845,26 @@ This is like @samp{ln -s}. The argument @var{new} is the directory to make the links in, or (if making just one link) the name to give the link. +@findex dired-do-relsymlink +@kindex Y @r{(Dired)} +@item Y @var{new} @key{RET} +Make relative symbolic links to the specified files +(@code{dired-do-relsymlink}). The argument @var{new} is the directory +to make the links in, or (if making just one link) the name to give +the link. This is like @code{dired-do-symlink} but creates relative +symbolic links. For example: + +@example + foo -> ../bar/foo +@end example + +@noindent +It does not create absolute ones like: + +@example + foo -> /path/that/may/change/any/day/bar/foo +@end example + @findex dired-do-chmod @kindex M @r{(Dired)} @cindex changing file permissions (in Dired) @@ -941,6 +984,18 @@ Byte compile the specified Emacs Lisp files (@code{dired-do-byte-compile}). @xref{Byte Compilation,, Byte Compilation, elisp, The Emacs Lisp Reference Manual}. +@findex dired-do-info +@kindex I @r{(Dired)} +@cindex running info on files (in Dired) +@item I +Run Info on this file (assumed to be a file in Info format). + +@findex dired-do-man +@kindex N @r{(Dired)} +@cindex running man on files (in Dired) +@item N +Run man on this file (assumed to be a file in @code{nroff} format). + @kindex A @r{(Dired)} @findex dired-do-find-regexp @cindex search multiple files (in Dired) @@ -990,6 +1045,7 @@ subdirectories whose names match @code{grep-find-ignored-directories}. @findex dired-do-shell-command @kindex ! @r{(Dired)} @kindex X @r{(Dired)} +@vindex dired-confirm-shell-command The Dired command @kbd{!} (@code{dired-do-shell-command}) reads a shell command string in the minibuffer, and runs that shell command on one or more files. The files that the shell command operates on are @@ -1026,7 +1082,8 @@ list of file names, putting them into one tar file @file{foo.tar}. If you want to use @samp{*} as a shell wildcard with whitespace around it, write @samp{*""}. In the shell, this is equivalent to @samp{*}; but since the @samp{*} is not surrounded by whitespace, Dired does not -treat it specially. +treat it specially. Emacs will prompt for confirmation if you do +this, unless @code{dired-confirm-shell-command} is @code{nil}. @item Otherwise, if the command string contains @samp{?} surrounded by @@ -1065,6 +1122,73 @@ buffer (@pxref{Dired Updating}). @xref{Single Shell}, for information about running shell commands outside Dired. +@node Shell Command Guessing +@section Shell Command Guessing +@cindex guessing shell commands for files (in Dired) + +Based upon the name of a file, Dired tries to guess what shell command +you might want to apply to it. For example, if you have point on a +file named @file{foo.tar} and you press @kbd{!}, Dired will guess that +you want to run @samp{tar xvf}, and suggest that as the default shell +command. + +You can type @kbd{M-n} to get the default into the minibuffer for +editing. If there are several commands for a given file, type +@kbd{M-n} several times to see each matching command in order. + +Dired only tries to guess a command for a single file, never for a +list of marked files. + +@defvar dired-guess-shell-alist-default +This variable specifies the predefined rules for guessing shell +commands suitable for certain files. Set this to @code{nil} to turn +guessing off. The elements of @code{dired-guess-shell-alist-user} +(defined by the user) will override these rules. +@end defvar + +@defvar dired-guess-shell-alist-user +If non-@code{nil}, this variable specifies the user-defined alist of +file regexps and their suggested commands. These rules take +precedence over the predefined rules in the variable +@code{dired-guess-shell-alist-default} when +@code{dired-do-shell-command} is run). The default is @code{nil}. + +Each element of the alist looks like + +@example +(@var{regexp} @var{command}@dots{}) +@end example + +@noindent +where each @var{command} can either be a string or a Lisp expression +that evaluates to a string. If several commands are given, all of +them will temporarily be pushed onto the history. + +A @samp{*} in the shell command stands for the file name that matched +@var{regexp}. When Emacs invokes the @var{command}, it replaces each +instance of @samp{*} with the matched file name. + +To add rules for @samp{.foo} and @samp{.bar} file extensions, add this +to your Init file: + +@example +(setq dired-guess-shell-alist-user + (list + (list "\\.foo$" "@var{foo-command}") ; fixed rule + ;; possibly more rules... + (list "\\.bar$" ; rule with condition test + '(if @var{condition} + "@var{bar-command-1}" + "@var{bar-command-2}")))) +@end example + +@noindent +This will override any predefined rules for the same extensions. +@end defvar + +You can find more user options with @kbd{M-x customize-group @key{RET} +dired-guess @key{RET}}. + @node Transforming File Names @section Transforming File Names in Dired @@ -1114,9 +1238,12 @@ Rename each of the selected files to a lower-case name @itemx % S @var{from} @key{RET} @var{to} @key{RET} @kindex % S @r{(Dired)} @findex dired-do-symlink-regexp -These four commands rename, copy, make hard links and make soft links, -in each case computing the new name by regular-expression substitution -from the name of the old file. +@itemx % Y @var{from} @key{RET} @var{to} @key{RET} +@kindex % Y @r{(Dired)} +@findex dired-do-relsymlink-regexp +These five commands rename, copy, make hard links, make soft links, +and make relative soft links, in each case computing the new name by +regular-expression substitution from the name of the old file. @end table The four regular-expression substitution commands effectively @@ -1274,6 +1401,12 @@ parent directory. @kindex > @r{(Dired)} @item > Move down to the next directory-file line (@code{dired-next-dirline}). + +@findex dired-goto-subdir +@kindex M-G @r{(Dired)} +@item M-G +Prompt for a directory and move to its directory-file line +(@code{dired-goto-subdir}). @end table @node Hiding Subdirectories @@ -1515,14 +1648,12 @@ image-dired}. This prompts for a directory; specify one that has image files. This creates thumbnails for all the images in that directory, and displays them all in the thumbnail buffer. The thumbnails are generated in the background and are loaded as they -become available. This command asks for confirmation if the number of -image files exceeds @code{image-dired-show-all-from-dir-max-files}. +become available. With point in the thumbnail buffer, you can type @key{RET} -(@code{image-dired-display-thumbnail-original-image}) to display a -sized version of it in another window. This sizes the image to fit -the window. Use the arrow keys to move around in the buffer. For -easy browsing, use @key{SPC} +(@code{image-dired-display-thumbnail-original-image}) to display the +image in another window. Use the arrow keys to move around in the +thumbnail buffer. For easy browsing, use @key{SPC} (@code{image-dired-display-next-thumbnail-original}) to advance and display the next image. Typing @key{DEL} (@code{image-dired-display-previous-thumbnail-original}) backs up to @@ -1575,6 +1706,14 @@ rotation is lossless, and uses an external utility called @node Misc Dired Features @section Other Dired Features +@vindex dired-free-space + By default, Dired will display the available space on the disk in +the first line. This is the @code{first} value of the +@code{dired-free-space} variable. If you set this to +@code{separate} instead, Dired will display this on a separate line +(including the space the files in the current directory takes). If +you set this to @code{nil}, the free space isn't displayed at all. + @kindex + @r{(Dired)} @findex dired-create-directory The command @kbd{+} (@code{dired-create-directory}) reads a @@ -1672,9 +1811,18 @@ directory than in this one. It also marks files with no counterpart, in both directories, as always. @cindex drag and drop, Dired - On the X Window System, Emacs supports the drag and drop -protocol. You can drag a file object from another program, and drop -it onto a Dired buffer; this either moves, copies, or creates a link -to the file in that directory. Precisely which action is taken is -determined by the originating program. Dragging files out of a Dired -buffer is currently not supported. +@vindex dired-mouse-drag-files + On the X Window System, Emacs supports the drag and drop protocol. +You can drag a file object from another program, and drop it onto a +Dired buffer; this either moves, copies, or creates a link to the file +in that directory. Precisely which action is taken is determined by +the originating program. Dragging files out of a Dired buffer is also +supported, by enabling the user option @code{dired-mouse-drag-files}, +the mouse can be used to drag files onto other programs. When set to +@code{link}, it will make the other program (typically a file manager) +create a symbolic link to the file; when set to @code{move}, it will +make the other program move the file to a new location, and setting it +to any other non-@code{nil} value will make the other program open or +create a copy of the file. The keyboard modifiers pressed during the +drag-and-drop operation can also control what action the other program +takes towards the file. diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index 6897ef525a2..b7c8825efa2 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. @@ -642,24 +643,41 @@ apply them to specific text when you want the effects they produce. @item default This face is used for ordinary text that doesn't specify any face. Its background color is used as the frame's background color. + @item bold This face uses a bold variant of the default font. + @item italic This face uses an italic variant of the default font. + @item bold-italic This face uses a bold italic variant of the default font. + @item underline This face underlines text. + @item fixed-pitch This face forces use of a fixed-width font. It's reasonable to customize this face to use a different fixed-width font, if you like, but you should not make it a variable-width font. + @item fixed-pitch-serif This face is like @code{fixed-pitch}, except the font has serifs and looks more like traditional typewriting. + @cindex @code{variable-pitch} face @item variable-pitch -This face forces use of a variable-width font. +This face forces use of a variable-width (i.e., proportional) font. +The font size picked for this face matches the font picked for the +default (usually fixed-width) font. + +@item variable-pitch-text +This is like the @code{variable-pitch} face (from which it inherits), +but is slightly larger. A proportional font of the same height as a +monospace font usually appears visually smaller, and can therefore be +harder to read. When displaying longer texts, this face can be a good +choice over the (slightly smaller) @code{variable-pitch} face. + @cindex @code{shadow} face @item shadow This face is used for making the text less noticeable than the surrounding @@ -716,46 +734,62 @@ frame: @table @code @item mode-line @cindex @code{mode-line} face -@cindex faces for mode lines -This face is used for the mode line of the currently selected window, +This is the base face used for the mode lines, as well as header lines and for menu bars when toolkit menus are not used. By default, it's drawn with shadows for a raised effect on graphical displays, and drawn as the inverse of the default face on non-windowed terminals. + +The @code{mode-line-active} and @code{mode-line-inactive} faces (which +are the ones used on the mode lines) inherit from this face. + +@item mode-line-active +@cindex faces for mode lines +Like @code{mode-line}, but used for the mode line of the currently +selected window. This face inherits from @code{mode-line}, so changes +in that face affect mode lines in all windows. + @item mode-line-inactive @cindex @code{mode-line-inactive} face Like @code{mode-line}, but used for mode lines of the windows other than the selected one (if @code{mode-line-in-non-selected-windows} is non-@code{nil}). This face inherits from @code{mode-line}, so changes in that face affect mode lines in all windows. + @item mode-line-highlight @cindex @code{mode-line-highlight} face Like @code{highlight}, but used for mouse-sensitive portions of text on mode lines. Such portions of text typically pop up tooltips (@pxref{Tooltips}) when the mouse pointer hovers above them. + @item mode-line-buffer-id @cindex @code{mode-line-buffer-id} face This face is used for buffer identification parts in the mode line. + @item header-line @cindex @code{header-line} face Similar to @code{mode-line} for a window's header line, which appears at the top of a window just as the mode line appears at the bottom. Most windows do not have a header line---only some special modes, such Info mode, create one. + @item header-line-highlight @cindex @code{header-line-highlight} face Similar to @code{highlight} and @code{mode-line-highlight}, but used for mouse-sensitive portions of text on header lines. This is a separate face because the @code{header-line} face might be customized in a way that does not interact well with @code{highlight}. + @item tab-line @cindex @code{tab-line} face Similar to @code{mode-line} for a window's tab line, which appears at the top of a window with tabs representing window buffers. @xref{Tab Line}. + @item vertical-border @cindex @code{vertical-border} face This face is used for the vertical divider between windows on text terminals. + @item minibuffer-prompt @cindex @code{minibuffer-prompt} face @vindex minibuffer-prompt-properties @@ -765,19 +799,23 @@ By default, Emacs automatically adds this face to the value of properties (@pxref{Text Properties,,, elisp, the Emacs Lisp Reference Manual}) used to display the prompt text. (This variable takes effect when you enter the minibuffer.) + @item fringe @cindex @code{fringe} face The face for the fringes to the left and right of windows on graphic displays. (The fringes are the narrow portions of the Emacs frame between the text area and the window's right and left borders.) @xref{Fringes}. + @item cursor The @code{:background} attribute of this face specifies the color of the text cursor. @xref{Cursor Display}. + @item tooltip This face is used for tooltip text. By default, if Emacs is built with GTK+ support, tooltips are drawn via GTK+ and this face has no effect. @xref{Tooltips}. + @item mouse This face determines the color of the mouse pointer. @end table @@ -814,10 +852,44 @@ 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 +@cindex icons, on clickable buttons + +Emacs sometimes displays clickable buttons (or other informative +icons), and you can customize how these look on display. + +@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 -@cindex adjust buffer face height +@cindex adjust buffer font size +@cindex font size of @code{default} face, increase or decrease @findex text-scale-adjust @kindex C-x C-+ @kindex C-x C-- @@ -825,17 +897,27 @@ would be selected if you click a mouse or press @key{RET}. @kindex C-x C-0 @kindex C-wheel-down @kindex C-wheel-up - To increase the height of the default face in the current buffer, -type @kbd{C-x C-+} or @kbd{C-x C-=}. To decrease it, type @kbd{C-x -C--}. To restore the default (global) face height, type @kbd{C-x -C-0}. These keys are all bound to the same command, + To increase the font size of the @code{default} face in the current +buffer, type @kbd{C-x C-+} or @kbd{C-x C-=}. To decrease it, type +@kbd{C-x C--}. To restore the default (global) font size, type +@kbd{C-x C-0}. These keys are all bound to the same command, @code{text-scale-adjust}, which looks at the last key typed to -determine which action to take. +determine which action to take and adjusts the font size accordingly +by changing the height of the default face. + + Most faces don't have an explicit setting of the @code{:height} +attribute, and thus inherit the height from the @code{default} face. +Those faces are also scaled by the above commands. + + Faces other than @code{default} that have an explicit setting of the +@code{:height} attribute are not affected by these font size changes. +The @code{header-line} face is an exception: it will be scaled even if +it has an explicit setting of the @code{:height} attribute. Similarly, scrolling the mouse wheel with the @kbd{Ctrl} modifier pressed, when the mouse pointer is above buffer text, will increase or -decrease the height of the default face, depending on the direction of -the scrolling. +decrease the font size of the affected faces, depending on the +direction of the scrolling. The final key of these commands may be repeated without the leading @kbd{C-x}. For instance, @kbd{C-x C-= C-= C-=} increases the face @@ -845,27 +927,57 @@ of 1.2; to change this factor, customize the variable to the @code{text-scale-adjust} command restores the default height, the same as typing @kbd{C-x C-0}. -@cindex increase buffer face height +@cindex adjust global font size +@findex global-text-scale-adjust +@vindex global-text-scale-adjust-resizes-frames +@kindex C-x C-M-+ +@kindex C-x C-M-= +@kindex C-x C-M-- +@kindex C-x C-M-0 +@kindex C-M-wheel-down +@kindex C-M-wheel-up + Similarly, to change the sizes of the fonts globally, type @kbd{C-x +C-M-+}, @kbd{C-x C-M-=}, @kbd{C-x C-M--} or @kbd{C-x C-M-0}, or scroll +the mouse wheel with both the @kbd{Ctrl} and @kbd{Meta} modifiers +pressed. To enable frame resizing when the font size is changed +globally, customize the variable +@code{global-text-scale-adjust-resizes-frames} (@pxref{Easy +Customization}). + +@cindex increase buffer font size @findex text-scale-increase -@cindex decrease buffer face height +@cindex decrease buffer font size @findex text-scale-decrease The commands @code{text-scale-increase} and -@code{text-scale-decrease} increase or decrease the height of the -default face, just like @kbd{C-x C-+} and @kbd{C-x C--} respectively. -You may find it convenient to bind to these commands, rather than -@code{text-scale-adjust}. +@code{text-scale-decrease} increase or decrease the size of the font +in the current buffer, just like @kbd{C-x C-+} and @kbd{C-x C--} +respectively. You may find it convenient to bind to these commands, +rather than @code{text-scale-adjust}. -@cindex set buffer face height +@cindex set buffer font size @findex text-scale-set - The command @code{text-scale-set} scales the height of the default -face in the current buffer to an absolute level specified by its -prefix argument. + The command @code{text-scale-set} scales the size of the font in the +current buffer to an absolute level specified by its prefix argument. @findex text-scale-mode The above commands automatically enable the minor mode @code{text-scale-mode} if the current font scaling is other than 1, and disable it otherwise. +@cindex pinch to scale +@findex text-scale-pinch + The command @code{text-scale-pinch} increases or decreases the text +scale based on the distance between fingers on a touchpad when a pinch +gesture is performed by placing two fingers on a touchpad and moving +them towards or apart from each other. This is only available on some +systems with supported hardware. + +@findex mouse-wheel-text-scale + The command @code{mouse-wheel-text-scale} also changes the text +scale. Normally, it is run when you press @key{Ctrl} while moving the +mouse wheel. The text scale is increased when the wheel is moved +downwards, and it is decreased when the wheel is moved upwards. + @node Font Lock @section Font Lock mode @cindex Font Lock mode @@ -960,10 +1072,15 @@ in C comments, use this: @end example @findex font-lock-remove-keywords +@vindex font-lock-ignore @noindent To remove keywords from the font-lock highlighting patterns, use the function @code{font-lock-remove-keywords}. @xref{Search-based Fontification,,, elisp, The Emacs Lisp Reference Manual}. +Alternatively, you can selectively disable highlighting due to some +keywords by customizing the @code{font-lock-ignore} option, +@pxref{Customizing Keywords,,, elisp, The Emacs Lisp Reference +Manual}. @cindex just-in-time (JIT) font-lock @cindex background syntax highlighting @@ -1538,7 +1655,9 @@ charge on the mode-line, by using the command @code{battery-mode-line-format} determines the way the battery charge is displayed; the exact mode-line message depends on the operating system, and it usually shows the current battery charge as a -percentage of the total charge. +percentage of the total charge. The functions in +@code{battery-update-functions} are run after updating the mode line, +and can be used to trigger actions based on the battery status. @cindex mode line, 3D appearance @cindex attributes of mode line, changing @@ -1653,6 +1772,12 @@ characters more prominent on display. @xref{Glyphless Chars,, Glyphless Character Display, elisp, The Emacs Lisp Reference Manual}, for details. +@findex glyphless-display-mode + The @code{glyphless-display-mode} minor mode can be used to toggle +the display of glyphless characters in the current buffer. The +glyphless characters will be displayed as boxes with acronyms of their +names inside. + @cindex curly quotes, and terminal capabilities @cindex curved quotes, and terminal capabilities @cindex @code{homoglyph} face @@ -1837,12 +1962,22 @@ logical lines, so having a fringe indicator for each wrapped line would be visually distracting. You can change this by customizing the variable @code{visual-line-fringe-indicators}. +@vindex word-wrap-whitespace-mode + By default, Emacs only breaks lines after whitespace characters like +@key{SPC} and @key{TAB}, but does not break after whitespace +characters like @key{EN QUAD}. Emacs provides a minor mode called +@code{word-wrap-whitespace-mode} that switches on word wrapping in the +current mode, and sets up which characters to wrap lines on based on +the @code{word-wrap-whitespace-characters} user option. There's also +a globalized version of that mode called +@code{global-word-wrap-whitespace-mode}. + @vindex word-wrap-by-category @findex modify-category-entry @findex char-category-set @findex category-set-mnemonics - By default, Emacs only breaks lines after whitespace characters. -That produces incorrect results when CJK and Latin text are mixed + Only breaking after whitespace character produces incorrect +results when CJK and Latin text are mixed together (because CJK characters don't use whitespace to separate words). You can customize the option @code{word-wrap-by-category} to allow Emacs to break lines after any character with @samp{|} category @@ -2025,3 +2160,14 @@ argument to suppress the effect of bold-face in this case. byte with a decimal value of 128 is displayed as @code{\200}. To change display to the hexadecimal format of @code{\x80}, set the variable @code{display-raw-bytes-as-hex} to @code{t}. +Care may be needed when interpreting a raw byte when copying +text from a terminal containing an Emacs session, or when a terminal's +@code{escape-glyph} face looks like the default face. For example, by +default Emacs displays the four characters @samp{\}, @samp{2}, +@samp{0}, @samp{0} with the same characters it displays a byte with +decimal value 128. The problem can be worse with hex displays, where +the raw byte 128 followed by the character @samp{7} is displayed as +@code{\x807}, which Emacs Lisp reads as the single character U+0807 +SAMARITAN LETTER IT; this confusion does not occur with the +corresponding octal display @code{\2007} because octal escapes contain +at most three digits. diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 24330016576..b43c966f872 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -221,6 +221,7 @@ Appendices * X Resources:: X resources for customizing Emacs. * Antinews:: Information about Emacs version 27. * Mac OS / GNUstep:: Using Emacs under macOS and GNUstep. +* Haiku:: Using Emacs on Haiku. * Microsoft Windows:: Using Emacs on Microsoft Windows and MS-DOS. * Manifesto:: What's GNU? Gnu's Not Unix! @@ -344,14 +345,14 @@ Cut and Paste Operations on Graphical Displays Registers -* Position Registers:: Saving positions in registers. -* Text Registers:: Saving text in registers. -* Rectangle Registers:: Saving rectangles in registers. -* Configuration Registers:: Saving window configurations in registers. -* Number Registers:: Numbers in registers. -* File Registers:: File names in registers. -* Keyboard Macro Registers:: Keyboard macros in registers. -* Bookmarks:: Bookmarks are like registers, but persistent. +* Position Registers:: Saving positions in registers. +* Text Registers:: Saving text in registers. +* Rectangle Registers:: Saving rectangles in registers. +* Configuration Registers:: Saving window configurations in registers. +* Number Registers:: Numbers in registers. +* File and Buffer Registers:: File and buffer names in registers. +* Keyboard Macro Registers:: Keyboard macros in registers. +* Bookmarks:: Bookmarks are like registers, but persistent. Controlling the Display @@ -1182,7 +1183,6 @@ The Emacs Initialization File Dealing with Emacs Trouble -* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. * Stuck Recursive:: '[...]' in mode line around the parentheses. * Screen Garbled:: Garbage on the screen. * Text Garbled:: Garbage in the text. @@ -1190,7 +1190,7 @@ Dealing with Emacs Trouble * Crashing:: What Emacs does when it crashes. * After a Crash:: Recovering editing in an Emacs session that crashed. * Emergency Escape:: What to do if Emacs stops responding. -* Long Lines:: Mitigating slowness due to extremely long lines. +* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. Reporting Bugs @@ -1249,6 +1249,11 @@ Emacs and macOS / GNUstep * Mac / GNUstep Events:: How window system events are handled. * GNUstep Support:: Details on status of GNUstep support. +Emacs and Haiku + +* Haiku Basics:: Basic Emacs usage and installation under Haiku. +* Haiku Fonts:: The various options for displaying fonts on Haiku. + Emacs and Microsoft Windows/MS-DOS * Windows Startup:: How to start Emacs on Windows. @@ -1618,6 +1623,7 @@ Lisp programming. @include anti.texi @include macos.texi +@include haiku.texi @c Includes msdos-xtra. @include msdos.texi @include gnu.texi diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 13c0e6d3144..5b3b15cd38f 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -326,6 +326,48 @@ of @code{require-final-newline} (@pxref{Customize Save}). If you have already visited the same file in the usual (non-literal) manner, this command asks you whether to visit it literally instead. +@findex find-sibling-file +@vindex find-sibling-rules +Files are sometimes (loosely) tied to other files, and you could call +these files @dfn{sibling files}. For instance, when editing C files, +if you have a file called @samp{"foo.c"}, you often also have a file +called @samp{"foo.h"}, and that could be its sibling file. Or you may +have different versions of a file, for instance +@samp{"src/emacs/emacs-27/lisp/allout.el"} and +@samp{"src/emacs/emacs-28/lisp/allout.el"} might be considered +siblings. Emacs provides the @code{find-sibling-file} command to jump +between sibling files, but it's impossible to guess at which files a +user might want to be considered siblings, so Emacs lets you configure +this freely by altering the @code{find-sibling-rules} user option. +This is a list of match/expansion elements. + +For instance, to do the @samp{".c"} to @samp{".h"} mapping, you could +say: + +@lisp +(setq find-sibling-rules + '(("\\([^/]+\\)\\.c\\'" "\\1.h"))) +@end lisp + +(@code{ff-find-related-file} offers similar functionality especially +geared towards C files, @pxref{Other C Commands}.) + +Or, if you want to consider all files under +@samp{"src/emacs/DIR/file-name"} to be siblings of other @var{dir}s, +you could say: + +@lisp +(setq find-sibling-rules + '(("src/emacs/[^/]+/\\(.*\\)\\'" "src/emacs/.*/\\1"))) +@end lisp + +As you can see, this is a list of @var{(MATCH EXPANSION...)} elements. +The @var{match} is a regular expression that matches the visited file +name, and each @var{expansion} may refer to match groups by using +@samp{\\1} and so on. The resulting expansion string is then applied +to the file system to see if any files match this expansion +(interpreted as a regexp). + @vindex find-file-hook @vindex find-file-not-found-functions Two special hook variables allow extensions to modify the operation @@ -378,6 +420,9 @@ With prefix argument (@kbd{C-u}), mark the current buffer as changed. Save the current buffer with a specified file name (@code{write-file}). @item M-x set-visited-file-name Change the file name under which the current buffer will be saved. +@item M-x rename-visited-file +The same as @kbd{M-x set-visited-file-name}, but also rename the file +the buffer is visiting (if any). @end table @kindex C-x C-s @@ -610,10 +655,10 @@ Never make numbered backups; always make single backups. The usual way to set this variable is globally, through your init file or the customization buffer. However, you can set @code{version-control} locally in an individual buffer to control the -making of backups for that buffer's file (@pxref{Locals}). You can -have Emacs set @code{version-control} locally whenever you visit a -given file (@pxref{File Variables}). Some modes, such as Rmail mode, -set this variable. +making of backups for that buffer's file (@pxref{Locals}). Some +modes, such as Rmail mode, set this variable. You can also have Emacs +set @code{version-control} locally whenever you visit a given file +(@pxref{File Variables}). @cindex @env{VERSION_CONTROL} environment variable If you set the environment variable @env{VERSION_CONTROL}, to tell @@ -1476,8 +1521,8 @@ characters that don't match. Then the command exits. If point in the two windows is followed by non-matching text when the command starts, @kbd{M-x compare-windows} tries heuristically to advance up to matching text in the two windows, and then exits. So if -you use @kbd{M-x compare-windows} repeatedly, each time it either -skips one matching range or finds the start of another. +you use @kbd{M-x compare-windows} repeatedly (@pxref{Repeating}), each +time it either skips one matching range or finds the start of another. @vindex compare-ignore-case @vindex compare-ignore-whitespace @@ -1828,6 +1873,22 @@ argument to @kbd{M-x delete-file} or @kbd{M-x delete-directory} makes them delete outright, instead of using the Trash, regardless of @code{delete-by-moving-to-trash}. + If you have @code{delete-by-moving-to-trash} set, and you want to +delete files manually in Emacs from the Trash directory, using +commands like @kbd{D} (@code{dired-do-delete}) doesn't work well in +the Trash directory (it'll just give the file a new name, but won't +delete anything). If you want to be able to do this, you should +create a @code{.dir-locals.el} file containing something like the +following in the Trash directory: + +@example +((dired-mode . ((delete-by-moving-to-trash . nil)))) +@end example + + Note, however, if you use the system ``empty trash'' command, it's +liable to also delete this @code{.dir-locals.el} file, so this should +only be done if you delete files from the Trash directory manually. + @ifnottex If a file is under version control (@pxref{Version Control}), you should delete it using @kbd{M-x vc-delete-file} instead of @kbd{M-x @@ -2164,13 +2225,16 @@ recently-opened files, reading file names from a buffer. @findex recentf-mode @vindex recentf-mode +@findex recentf-open @findex recentf-save-list @findex recentf-edit-list - If you enable Recentf mode, with @kbd{M-x recentf-mode}, the -@samp{File} menu includes a submenu containing a list of recently -opened files. @kbd{M-x recentf-save-list} saves the current -@code{recentf-list} to a file, and @kbd{M-x recentf-edit-list} edits -it. + If you enable Recentf mode, with @kbd{M-x recentf-mode}, Emacs +maintains a list of recently opened files. To open a file from this +list, use the @kbd{M-x recentf-open} command. When this mode is +enabled, the @samp{File} menu will include a submenu that you can use +to visit one of these files. @kbd{M-x recentf-save-list} saves the +current @code{recentf-list} to a file, and @kbd{M-x recentf-edit-list} +edits it. @c FIXME partial-completion-mode (complete.el) is obsolete. The @kbd{M-x ffap} command generalizes @code{find-file} with more @@ -2205,16 +2269,18 @@ window, so this is only necessary if you customize the default behavior by using the options @code{image-auto-resize} and @code{image-auto-resize-on-window-resize}. -@findex image-transform-fit-both +@findex image-transform-fit-to-window @findex image-transform-set-scale @findex image-transform-reset To resize the image manually you can use the command -@code{image-transform-fit-both} bound to @kbd{s b} -that fits the image to both the window height and width. -To scale the image specifying a scale factor, use the command -@code{image-transform-set-scale} bound to @kbd{s s}. -To reset all transformations to the initial state, use -@code{image-transform-reset} bound to @kbd{s 0}. +@code{image-transform-fit-to-window} bound to @kbd{s w} that fits the +image to both the window height and width. To scale the image to a +percentage of its original size, use the command +@code{image-transform-set-percent} bound to @kbd{s p}. To scale +the image specifying a scale factor, use the command +@code{image-transform-set-scale} bound to @kbd{s s}. To reset all +transformations to the initial state, use @code{image-transform-reset} +bound to @kbd{s 0}. @findex image-next-file @findex image-previous-file @@ -2291,6 +2357,29 @@ can be used to transform the image in question to @acronym{PNG} before displaying. GraphicsMagick, ImageMagick and @command{ffmpeg} are currently supported for image conversions. +@findex image-converter-add-handler + In addition, you may wish to add special handlers for certain image +formats. These can be added with the +@code{image-converter-add-handler} function. For instance, to allow +viewing Krita files as simple images, you could say something like: + +@lisp +(image-converter-add-handler + "kra" + (lambda (file data-p) + (if data-p + (error "Can't decode non-files") + (call-process "unzip" nil t nil + "-qq" "-c" "-x" file "mergedimage.png")))) +@end lisp + +The function takes two parameters, where the first is a file name +suffix, and the second is a function to do the ``conversion''. This +function takes two parameters, where the first is the file name or a +string with the data, and the second says whether the first parameter +is data or not, and should output an image in +@code{image-convert-to-format} format in the current buffer. + @findex thumbs-mode @cindex mode, Thumbs The Image-Dired package can also be used to view images as diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index ce43408101d..d78cbffaa71 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -128,6 +128,12 @@ In addition, the text in the region becomes the primary selection non-@code{nil} value, dragging the mouse over a stretch of text also adds the text to the kill ring. The default is @code{nil}. + If this variable is @code{non-empty}, only copy to the kill ring if +the region is non-empty. For instance, if you mouse drag an area that +is less than a half a character, you'd normally get the empty string +in your kill ring, but with @code{non-empty}, this short mouse drag +won't affect the kill ring. + @vindex mouse-scroll-min-lines If you move the mouse off the top or bottom of the window while dragging, the window scrolls at a steady rate until you move the mouse @@ -136,6 +142,12 @@ entirely on the screen. The number of lines scrolled per step depends on how far away from the window edge the mouse has gone; the variable @code{mouse-scroll-min-lines} specifies a minimum step size. +@vindex mouse-drag-mode-line-buffer + If you enable the option @code{mouse-drag-mode-line-buffer} and +dragging files is supported by the window system, then dragging the +mouse on the buffer name portion of the mode line will drag that +buffer's file to another program or frame. + @findex mouse-yank-primary @findex mouse-yank-at-click Clicking with the middle mouse button, @kbd{mouse-2}, moves point to @@ -211,8 +223,8 @@ mouse-wheel-mode}. The variables @code{mouse-wheel-follow-mouse} and buffers are scrolled. The variable @code{mouse-wheel-progressive-speed} determines whether the scroll speed is linked to how fast you move the wheel. This mode also -supports increasing or decreasing the height of the default face, by -default bound to scrolling with the @key{Ctrl} modifier. +supports increasing or decreasing the font size, by default bound to +scrolling with the @key{Ctrl} modifier. @vindex mouse-wheel-scroll-amount-horizontal Emacs also supports horizontal scrolling with the @key{Shift} @@ -512,6 +524,16 @@ frames by specifying @dfn{frame parameters}. @xref{Frame Parameters}. Delete the selected frame (@code{delete-frame}). This signals an error if there is only one frame. +@item C-x 5 u +@kindex C-x 5 u +@findex undelete-frame +@findex undelete-frame-mode +When @code{undelete-frame-mode} is enabled, undelete one of the 16 +most recently deleted frames. Without a prefix argument, undelete the +most recently deleted frame. With a numerical prefix argument between +1 and 16, where 1 is the most recently deleted frame, undelete the +corresponding deleted frame. + @item C-z @kindex C-z @r{(X windows)} Minimize (or iconify) the selected Emacs frame @@ -939,6 +961,7 @@ Speedbar,,speedbar, Speedbar Manual}. @node Multiple Displays @section Multiple Displays @cindex multiple displays +@cindex display server A single Emacs can talk to more than one X display. Initially, Emacs uses just one display---the one specified with the @env{DISPLAY} @@ -1185,6 +1208,18 @@ the variable @code{dnd-open-file-other-window}. The XDND and Motif drag and drop protocols, and the old KDE 1.x protocol, are currently supported. +@vindex dnd-indicate-insertion-point +@vindex dnd-scroll-margin + + It can be difficult to scroll a window or determine where dropped +text will be inserted while dragging text onto an Emacs window. +Setting the option @code{dnd-indicate-insertion-point} to a +non-@code{nil} value makes point move to the location any dropped text +will be inserted when the mouse moves in a window during drag, and +setting @code{dnd-scroll-margin} to an integer value causes a window +to be scrolled if the mouse moves within that many lines of the top +or bottom of the window during drag. + @vindex mouse-drag-and-drop-region Emacs can also optionally drag the region with the mouse into another portion of this or another buffer. To enable that, customize @@ -1209,6 +1244,17 @@ cursor during dragging. To suppress such behavior, set the options @code{mouse-drag-and-drop-region-show-tooltip} and/or @code{mouse-drag-and-drop-region-show-cursor} to @code{nil}. +@vindex mouse-drag-and-drop-region-cross-program +To drag text from Emacs to other programs, set the option +@code{mouse-drag-and-drop-region-cross-program} to a non-@code{nil} +value. + + On the X window system, some programs can drop files on Emacs, +expecting Emacs to save them. Normally, Emacs will prompt for a file +name under which the file will be saved, and then open the file, but +that behavior can be changed by changing the variable +@code{x-dnd-direct-save-function}. @xref{Drag and Drop,,, elisp, The +Emacs Lisp Reference Manual}. @node Menu Bars @section Menu Bars @@ -1623,13 +1669,18 @@ Parameters,,, elisp, The Emacs Lisp Reference Manual}, and also For additional customization options for displaying tooltips, use @kbd{M-x customize-group @key{RET} tooltip @key{RET}}. -@vindex x-gtk-use-system-tooltips - If Emacs is built with GTK+ support, it displays tooltips via GTK+, -using the default appearance of GTK+ tooltips. To disable this, -change the variable @code{x-gtk-use-system-tooltips} to @code{nil}. -If you do this, or if Emacs is built without GTK+ support, most -attributes of the tooltip text are specified by the @code{tooltip} -face, and by X resources (@pxref{X Resources}). +@vindex use-system-tooltips + If Emacs is built with the GTK+ toolkit, Nextstep windowing, or +Haiku windowing support, it displays tooltips via the toolkit, using +the default appearance of the toolkit's tooltips.@footnote{The +foreground and background colors of toolkit-created tooltips on +Nextstep can also be customized by setting the @code{foreground} and +@code{background} frame parameters that are part of +@code{tooltip-frame-parameters}.} To disable this, change the variable +@code{use-system-tooltips} to @code{nil}. If you do this, or if Emacs +is built without the appropriate windowing support, most attributes of +the tooltip text are specified by the @code{tooltip} face, and by X +resources (@pxref{X Resources}). @dfn{GUD tooltips} are special tooltips that show the values of variables when debugging a program with GUD@. @xref{Debugger diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi index 5224e313407..9a537019974 100644 --- a/doc/emacs/glossary.texi +++ b/doc/emacs/glossary.texi @@ -1457,8 +1457,8 @@ level by aborting (q.v.@:) and quitting (q.v.). @xref{Quitting}. @item Transient Mark Mode The default behavior of the mark (q.v.@:) and region (q.v.), in which setting the mark activates it and highlights the region, is called -Transient Mark mode. In GNU Emacs 23 and onwards, it is enabled by -default. @xref{Disabled Transient Mark}. +Transient Mark mode. It is enabled by default. @xref{Disabled +Transient Mark}. @item Transposition Transposing two units of text means putting each one into the place diff --git a/doc/emacs/haiku.texi b/doc/emacs/haiku.texi new file mode 100644 index 00000000000..ac631a39a69 --- /dev/null +++ b/doc/emacs/haiku.texi @@ -0,0 +1,132 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2021--2022 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Haiku +@appendix Emacs and Haiku +@cindex Haiku + + Haiku is a Unix-like operating system that originated as a +re-implementation of the operating system BeOS. + + This section describes the peculiarities of using Emacs built with +the Application Kit, the windowing system native to Haiku. The +oddities described here do not apply to using Emacs on Haiku built +without windowing support, or built with X11. + +@menu +* Haiku Basics:: Basic Emacs usage and installation under Haiku. +* Haiku Fonts:: The various options for displaying fonts on Haiku. +@end menu + +@node Haiku Basics +@section Installation and usage peculiarities under Haiku +@cindex haiku application +@cindex haiku installation + + Emacs installs two separate executables under Haiku; it is up to the +user to decide which one suits him best: A regular executable, with +the lowercase name @code{emacs}, and a binary containing +Haiku-specific application metadata, with the name @code{Emacs}. + +@cindex launching Emacs from the tracker +@cindex tty Emacs in haiku + If you are launching Emacs from the Tracker, or want to make the +Tracker open files using Emacs, you should use the binary named +@code{Emacs}; if you are going to use Emacs in the terminal, or wish +to launch separate instances of Emacs, or do not care for the +aforementioned system integration features, use the binary named +@code{emacs} instead. + +@cindex modifier keys and system keymap (Haiku) +@cindex haiku keymap + On Haiku, unusual modifier keys such as the Hyper key are +unsupported. By default, the super key corresponds with the option +key defined by the operating system, the meta key with the command +key, the control key with the system control key, and the shift key +with the system shift key. On a standard PC keyboard, Haiku should +map these keys to positions familiar to those using a GNU system, but +this may require some adjustment to your system's configuration to +work. + + It is impossible to type accented characters using the system super +key map. + + You can customize the correspondence between modifier keys known to +the system, and those known to Emacs. The variables that allow for +that are described below. + +@cindex modifier key customization (Haiku) +@table @code +@vindex haiku-meta-keysym +@item haiku-meta-keysym +The system modifier key that will be treated as the Meta key by Emacs. +It defaults to @code{command}. + +@vindex haiku-control-keysym +@item haiku-control-keysym +The system modifier key that will be treated as the Control key by +Emacs. It defaults to @code{control}. + +@vindex haiku-super-keysym +@item haiku-super-keysym +The system modifier key that will be treated as the Super key by +Emacs. It defaults to @code{option}. + +@vindex haiku-shift-keysym +@item haiku-shift-keysym +The system modifier key that will be treated as the Shift key by +Emacs. It defaults to @code{shift}. +@end table + +The value of each variable can be one of the symbols @code{command}, +@code{control}, @code{option}, @code{shift}, or @code{nil}. +@code{nil} or any other value will cause the default value to be used +instead. + +@cindex tooltips (haiku) +@cindex haiku tooltips + On Haiku, Emacs defaults to using the system tooltip mechanism. +This usually leads to more responsive tooltips, but the tooltips will +not be able to display text properties or faces. If you need those +features, customize the variable @code{use-system-tooltips} to the +@code{nil} value, and Emacs will use its own implementation of +tooltips. + +@cindex X resources on Haiku + Unlike the X window system, Haiku does not have a system-wide +resource database. Since many important options are specified via +X resources (@pxref{X Resources}), an emulation is provided: upon +startup, Emacs will load a file named @file{GNU Emacs} inside the user +configuration directory (normally @file{/boot/home/config/settings}), +which should be a flattened system message where keys and values are +both strings, and correspond to attributes and their values +respectively. + +You can create such a file with the @command{xmlbmessage} tool. + +@subsection What to do when Emacs crashes +@cindex crashes, Haiku +@cindex haiku debugger +@vindex haiku-debug-on-fatal-error + If the variable @code{haiku-debug-on-fatal-error} is non-nil, Emacs +will launch the system debugger when a fatal signal is received. It +defaults to @code{t}. If GDB cannot be used on your system, please +attach the report generated by the system debugger when reporting a +bug. + +@node Haiku Fonts +@section Font and font backend selection on Haiku +@cindex font backend selection (Haiku) + + Emacs, when built with Haiku windowing support, can be built with +several different font backends. You can specify font backends by +specifying @kbd{-xrm Emacs.fontBackend:BACKEND} on the command line +used to invoke Emacs, where @kbd{BACKEND} is one of the backends +specified below, or on a per-frame basis by changing the +@code{font-backend} frame parameter. + + Two of these backends, @code{ftcr} and @code{ftcrhb} are identical +to their counterparts on the X Window System. There is also a +Haiku-specific backend named @code{haiku}, that uses the App Server to +draw fonts, but does not at present support display of color font and +emoji. diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index 7dcd09b3a13..d206dee3859 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -20,10 +20,28 @@ commands (@code{help-for-help}). You can scroll the list with @key{SPC} and @key{DEL}, then type the help command you want. To cancel, type @kbd{C-g}. +@cindex help buffer Many help commands display their information in a special @dfn{help buffer}. In this buffer, you can type @key{SPC} and @key{DEL} to scroll and type @key{RET} to follow hyperlinks. @xref{Help Mode}. +@vindex help-window-select + By default, help commands display the help buffer in a separate +window without selecting that window. The variable +@code{help-window-select} controls this: its default value is +@code{nil}; if it's customized to the value @code{t}, the help window +is unconditionally selected by help commands, and if its value is +@code{other}, the help window is selected only if there are more than +two windows on the selected frame. + +@vindex help-window-keep-selected + Conversely, many commands in the @samp{*Help*} buffer will pop up a +new window to display the results. For instance, clicking on the link +to show the source code, or using the @key{i} command to display the +manual entry, will (by default) pop up a new window. If +@code{help-window-keep-selected} is changed to non-@code{nil}, the +window displaying the @samp{*Help*} buffer will be reused instead. + @cindex searching documentation efficiently @cindex looking for a subject in documentation If you are looking for a certain feature, but don't know what it is @@ -182,7 +200,10 @@ programming language you are editing (@code{info-lookup-symbol}). @item C-h . Display the help message for a special text area, if point is in one (@code{display-local-help}). (These include, for example, links in -@file{*Help*} buffers.) @xref{Help Echo}. +@file{*Help*} buffers.) @xref{Help Echo}. If you invoke +this command with a prefix argument, @kbd{C-u C-h .}, and point is on +a button or a widget, this command will pop a new buffer that +describes that button/widget. @end table @node Key Help @@ -332,9 +353,9 @@ are included varies depending on the command used. @cindex apropos The @dfn{apropos} commands answer questions like, ``What are the -commands for working with files?'' More precisely, you specify an -@dfn{apropos pattern}, which means either a word, a list of words, or -a regular expression. +commands for working with files?'' More precisely, you specify your +query as an @dfn{apropos pattern}, which is either a word, a list of +words, or a regular expression. Each of the following apropos commands reads an apropos pattern in the minibuffer, searches for items that match the pattern, and @@ -393,6 +414,12 @@ comes with a brief description and a list of keys you can currently invoke it with. In our example, it would say that you can invoke @code{find-file} by typing @kbd{C-x C-f}. +@vindex help-window-select@r{, and apropos commands} + By default, the window showing the apropos buffer with the results +of the query is not selected, but you can cause it to be selected by +customizing the variable @code{help-window-select} to any +non-@code{nil} value. + For more information about a function definition, variable or symbol property listed in an apropos buffer, you can click on it with @kbd{mouse-1} or @kbd{mouse-2}, or move there and type @key{RET}. @@ -461,20 +488,26 @@ Move point back to the previous hyperlink (@code{backward-button}). @item mouse-1 @itemx mouse-2 Follow a hyperlink that you click on. +@item n +@itemx p +Move forward and back between pages in the Help buffer. @item C-c C-c Show all documentation about the symbol at point (@code{help-follow-symbol}). @item C-c C-f @itemx r -Go forward to the next help topic (@code{help-go-forward}). +Go forward in history of help commands (@code{help-go-forward}). @item C-c C-b @itemx l -Go back to the previous help topic (@code{help-go-back}). +Go back in history of help commands (@code{help-go-back}). @item s View the source of the current help topic (if any) (@code{help-view-source}). @item i Look up the current topic in the manual(s) (@code{help-goto-info}). +@item I +Look up the current topic in the Emacs Lisp manual +(@code{help-goto-lispref-info}). @item c Customize the variable or the face (@code{help-customize}). @end table @@ -498,6 +531,35 @@ C-b} or @kbd{l} (@code{help-go-back}). While retracing your steps, you can go forward by using @kbd{C-c C-f} or @kbd{r} (@code{help-go-forward}). +@kindex TAB @r{(Help mode)} +@findex forward-button +@kindex S-TAB @r{(Help mode)} +@findex backward-button + To move between hyperlinks in a help buffer, use @key{TAB} +(@code{forward-button}) to move forward to the next hyperlink and +@kbd{S-@key{TAB}} (@code{backward-button}) to move back to the +previous hyperlink. These commands act cyclically; for instance, +typing @key{TAB} at the last hyperlink moves back to the first +hyperlink. + +@vindex help-clean-buttons + By default, many links in the help buffer are displayed surrounded +by quote characters. If the @code{help-clean-buttons} user option is +non-@code{nil}, these quote characters are removed from the buffer. + +@kindex n @r{(Help mode)} +@kindex p @r{(Help mode)} +@findex help-goto-next-page +@findex help-goto-previous-page + Help buffers produced by some Help commands (like @kbd{C-h b}, which +shows a long list of key bindings) are divided into pages by the +@samp{^L} character. In such buffers, the @kbd{n} +(@code{help-goto-next-page}) command will take you to the next start +of page, and the @kbd{p} (@code{help-goto-previous-page}) command will +take you to the previous start of page. This way you can quickly +navigate between the different kinds of documentation in a help +buffer. + @cindex URL, viewing in help @cindex help, viewing web pages @cindex viewing web pages in help @@ -507,16 +569,6 @@ code definitions, and URLs (web pages). The first two are opened in Emacs, and the third using a web browser via the @code{browse-url} command (@pxref{Browse-URL}). -@kindex TAB @r{(Help mode)} -@findex forward-button -@kindex S-TAB @r{(Help mode)} -@findex backward-button - In a help buffer, @key{TAB} (@code{forward-button}) moves point -forward to the next hyperlink, while @kbd{S-@key{TAB}} -(@code{backward-button}) moves point back to the previous hyperlink. -These commands act cyclically; for instance, typing @key{TAB} at the -last hyperlink moves back to the first hyperlink. - To view all documentation about any symbol in the text, move point to the symbol and type @kbd{C-c C-c} (@code{help-follow-symbol}). This shows the documentation for all the meanings of the symbol---as a diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi index 4369eaab347..bb8d51158ae 100644 --- a/doc/emacs/killing.texi +++ b/doc/emacs/killing.texi @@ -111,24 +111,27 @@ active (@pxref{Using Region}). @kindex M-\ @findex delete-horizontal-space -@kindex M-SPC -@findex just-one-space -@findex cycle-spacing - The other delete commands are those that delete only whitespace +The other delete commands are those that delete only whitespace characters: spaces, tabs and newlines. @kbd{M-\} (@code{delete-horizontal-space}) deletes all the spaces and tab characters before and after point. With a prefix argument, this only -deletes spaces and tab characters before point. @kbd{M-@key{SPC}} -(@code{just-one-space}) does likewise but leaves a single space before +deletes spaces and tab characters before point. + +@findex just-one-space +@code{just-one-space} does likewise but leaves a single space before point, regardless of the number of spaces that existed previously (even if there were none before). With a numeric argument @var{n}, it leaves @var{n} spaces before point if @var{n} is positive; if @var{n} is negative, it deletes newlines in addition to spaces and tabs, -leaving @minus{}@var{n} spaces before point. The command @code{cycle-spacing} -acts like a more flexible version of @code{just-one-space}. It -does different things if you call it repeatedly in succession. -The first call acts like @code{just-one-space}, the next removes -all whitespace, and a third call restores the original whitespace. +leaving @minus{}@var{n} spaces before point. + +@kindex M-SPC +@findex cycle-spacing +@vindex cycle-spacing-actions +The command @code{cycle-spacing} (@kbd{M-@key{SPC}}) acts like a more +flexible version of @code{just-one-space}. It performs different +space cleanup actions defined by @code{cycle-spacing-actions}, in a +cyclic manner, if you call it repeatedly in succession. @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines after the current line. If the current line is blank, it deletes all @@ -353,7 +356,7 @@ other ways to move text around.) @vindex kill-ring-max The maximum number of entries in the kill ring is controlled by the -variable @code{kill-ring-max}. The default is 60. If you make a new +variable @code{kill-ring-max}. The default is 120. If you make a new kill when this limit has been reached, Emacs makes room by deleting the oldest entry in the kill ring. @@ -540,11 +543,11 @@ clipboard. clipboard contents are normally lost. Optionally, Emacs can save the existing clipboard contents to the kill ring, preventing you from losing the old clipboard data. If -@code{save-interprogram-paste-before-kill} changed to a number, then -this data is copied over if it's smaller (in characters) than this -number. If this variable is any other non-@code{nil} value, it's -always copied over---at the risk of high memory consumption if that -data turns out to be large. +@code{save-interprogram-paste-before-kill} has been set to a number, +then the data is copied over if it's smaller (in characters) than +this number. If this variable is any other non-@code{nil} value, the +data is always copied over---at the risk of high memory consumption if +that data turns out to be large. Yank commands, such as @kbd{C-y} (@code{yank}), also use the clipboard. If another application ``owns'' the clipboard---i.e., if @@ -562,6 +565,14 @@ new yank to the clipboard. To prevent kill and yank commands from accessing the clipboard, change the variable @code{select-enable-clipboard} to @code{nil}. +@findex yank-media + Programs can put other things than plain text on the clipboard. For +instance, a web browser will usually let you choose ``Copy Image'' on +images, and this image will be put on the clipboard. On capable +platforms, Emacs can yank these objects with the @code{yank-media} +command---but only in modes that have support for it (@w{@pxref{Yanking +Media,,, elisp, The Emacs Lisp Reference Manual}}). + @cindex clipboard manager @vindex x-select-enable-clipboard-manager Many X desktop environments support a feature called the @@ -599,14 +610,14 @@ yanks the contents of the clipboard at point. @cindex primary selection @cindex selection, primary - Under the X Window System, there exists a @dfn{primary selection} -containing the last stretch of text selected in an X application -(usually by dragging the mouse). Typically, this text can be inserted -into other X applications by @kbd{mouse-2} clicks. The primary -selection is separate from the clipboard. Its contents are more -fragile; they are overwritten each time you select text with the -mouse, whereas the clipboard is only overwritten by explicit cut -or copy commands. + Under the X Window System, PGTK and Haiku, there exists a +@dfn{primary selection} containing the last stretch of text selected +in an X application (usually by dragging the mouse). Typically, this +text can be inserted into other X applications by @kbd{mouse-2} +clicks. The primary selection is separate from the clipboard. Its +contents are more fragile; they are overwritten each time you select +text with the mouse, whereas the clipboard is only overwritten by +explicit cut or copy commands. Under X, whenever the region is active (@pxref{Mark}), the text in the region is saved in the primary selection. This applies regardless @@ -628,6 +639,13 @@ regions to the primary selection entirely. (@kbd{C-y}) to insert this text if @code{select-enable-primary} is set (@pxref{Clipboard}). +@cindex lost-selection-mode + By default, Emacs keeps the region active even after text is +selected in another program; this is contrary to typical X behavior. +To make Emacs deactivate the region after another program places data +in the primary selection, enable the global minor mode +@code{lost-selection-mode}. + @cindex MS-Windows, and primary selection MS-Windows provides no primary selection, but Emacs emulates it within a single Emacs session by storing the selected text internally. @@ -690,6 +708,9 @@ lines, much like @kbd{mouse-1}. If @code{mouse-yank-at-point} is non-@code{nil}, @kbd{M-mouse-2} yanks at point. Then it does not matter precisely where you click, or even which of the frame's windows you click on. @xref{Mouse Commands}. +This user option also effects interactive search: if it is +non-@code{nil}, yanking with the mouse anywhere in the frame will add +the text to the search string. @node Accumulating Text @section Accumulating Text diff --git a/doc/emacs/kmacro.texi b/doc/emacs/kmacro.texi index 5205c0b7167..88df2937659 100644 --- a/doc/emacs/kmacro.texi +++ b/doc/emacs/kmacro.texi @@ -439,7 +439,7 @@ name to execute the last keyboard macro, in its current form. (If you later add to the definition of this macro, that does not alter the name's definition as a macro.) The macro name is a Lisp symbol, and defining it in this way makes it a valid command name for calling with -@kbd{M-x} or for binding a key to with @code{global-set-key} +@kbd{M-x} or for binding a key to with @code{keymap-global-set} (@pxref{Keymaps}). If you specify a name that has a prior definition other than a keyboard macro, an error message is shown and nothing is changed. diff --git a/doc/emacs/m-x.texi b/doc/emacs/m-x.texi index e8c7faebd55..a98b879c882 100644 --- a/doc/emacs/m-x.texi +++ b/doc/emacs/m-x.texi @@ -45,10 +45,11 @@ from running the command by name. @cindex obsolete command When @kbd{M-x} completes on commands, it ignores the commands that -are declared @dfn{obsolete}; for these, you will have to type their -full name. (Obsolete commands are those for which newer, better -alternatives exist, and which are slated for removal in some future -Emacs release.) +were declared @dfn{obsolete} in any previous major version of Emacs; +for these, you will have to type their full name. Commands that were +marked obsolete in the current version of Emacs are listed. (Obsolete +commands are those for which newer, better alternatives exist, and +which are slated for removal in some future Emacs release.) @vindex read-extended-command-predicate In addition, @kbd{M-x} completion can exclude commands that are not diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi index ab143707fdd..d7c432d420e 100644 --- a/doc/emacs/macos.texi +++ b/doc/emacs/macos.texi @@ -223,6 +223,7 @@ keystrokes. Here is a list of these events. @table @key @item ns-open-file +@cindex ns-open-file event @vindex ns-pop-up-frames This event occurs when another Nextstep application requests that Emacs open a file. A typical reason for this would be a user @@ -239,52 +240,29 @@ means to always visit the file in a new frame. A value of @code{nil} means to always visit the file in the selected frame. @item ns-open-temp-file +@cindex ns-open-temp-file event This event occurs when another application requests that Emacs open a temporary file. By default, this is handled by just generating a @code{ns-open-file} event, the results of which are described above. @item ns-open-file-line +@cindex ns-open-file-line event Some applications, such as ProjectBuilder and gdb, request not only a particular file, but also a particular line or sequence of lines in the file. Emacs handles this by visiting that file and highlighting the requested line (@code{ns-open-file-select-line}). -@item ns-drag-n-drop -This event occurs when a user drags an object from another application -into an Emacs frame. The default behavior is to open a file in the -window under the mouse, or to insert text at point of the window under -the mouse. - -The sending application has some limited ability to decide how Emacs -handles the sent object, but the user may override the default -behavior by holding one or more modifier key. - -@table @kbd -@item control -Insert as text in the current buffer. If the object is a file, this -will insert the filename. -@item alt/option -Attempt to open the object as though it is a file or URL. -@item super/command -Perform the default action for the type. This can be useful when an -application is overriding the default behavior. -@end table - -The modifier keys listed above are defined by macOS and are unaffected -by user changes to the modifiers in Emacs. - -@item ns-change-font -This event occurs when the user selects a font in a Nextstep font -panel (which can be opened with @kbd{Cmd-t}). The default behavior is -to adjust the font of the selected frame -(@code{ns-respond-to-changefont}). The name and size of the selected -font are stored in the variables @code{ns-input-font} and -@code{ns-input-fontsize}, respectively. - @item ns-power-off +@cindex ns-power-off event This event occurs when the user logs out and Emacs is still running, or when ``Quit Emacs'' is chosen from the application menu. The default behavior is to save all file-visiting buffers. + +@item ns-show-prefs +@cindex ns-show-prefs event +This event occurs when the user selects ``Preferences'' from the +application menu. By default, it is bound to the command +@code{customize}. @end table @cindex using Nextstep services (macOS) diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index c23907ddfbd..60169d8d8c8 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -1055,15 +1055,6 @@ prefix argument is a repeat count. Move to the next revision entry. A numeric prefix argument is a repeat count. -@item P -Move to the log of the previous file, if showing logs for a multi-file -VC fileset. Otherwise, just move to the beginning of the log. A -numeric prefix argument is a repeat count. - -@item N -Move to the log of the next file, if showing logs for a multi-file VC -fileset. A numeric prefix argument is a repeat count. - @item a Annotate the revision on the current line (@pxref{Old Revisions}). @@ -1325,6 +1316,12 @@ point is on a directory entry, mark all files in that directory tree (@code{vc-dir-mark-all-files}). With a prefix argument, mark all listed files and directories. +@findex vc-dir-mark-by-regexp +@item % +You can use this command to mark files by regexp +(@code{vc-dir-mark-by-regexp}). If given a prefix, unmark files +instead. + @item G Add the file under point to the list of files that the VC should ignore (@code{vc-dir-ignore}). For instance, if the VC is Git, it @@ -1669,6 +1666,9 @@ support additional types of projects. Which files do or don't belong to a project is also determined by the project back-end. For example, the VC back-end doesn't consider ``ignored'' files (@pxref{VC Ignore}) to be part of the project. +Also, the VC Project back-end considers ``untracked'' files by default. +That behavior is controllable with the variable +@code{project-vc-include-untracked}. @menu * Project File Commands:: Commands for handling project files. @@ -1728,6 +1728,7 @@ doesn't seem to belong to a recognizable project, these commands prompt you for the project directory. @findex project-find-file +@vindex vc-directory-exclusion-list The command @kbd{C-x p f} (@code{project-find-file}) is a convenient way of visiting files (@pxref{Visiting}) that belong to the current project. Unlike @kbd{C-x C-f}, this command doesn't require to type @@ -1736,7 +1737,9 @@ base name (i.e., omit the leading directories). In addition, the completion candidates considered by the command include only the files belonging to the current project, and nothing else. If there's a file name at point, this command offers that file as the first element of -the ``future history''. +the ``future history''. If given a prefix, include all files under +the project root, except for @acronym{VCS} directories listed in +@code{vc-directory-exclusion-list}. @findex project-find-regexp The command @kbd{C-x p g} (@code{project-find-regexp}) is similar to @@ -1831,11 +1834,14 @@ buffers as candidates for completion. @findex project-kill-buffers @vindex project-kill-buffer-conditions +@vindex project-kill-buffers-display-buffer-list When you finish working on the project, you may wish to kill all the buffers that belong to the project, to keep your Emacs session smaller. The command @kbd{C-x p k} (@code{project-kill-buffers}) accomplishes that: it kills all the buffers that belong to the current -project that satisfy any of @code{project-kill-buffer-conditions}. +project that satisfy any of @code{project-kill-buffer-conditions}. If +@code{project-kill-buffers-display-buffer-list} is non-@code{nil}, the +buffers to be killed will be displayed first. @node Switching Projects @subsection Switching Projects @@ -2139,7 +2145,10 @@ Find definition of identifier, and display it in a new frame Find definition of identifier at mouse click. @item M-, Go back to where you previously invoked @kbd{M-.} and friends -(@code{xref-pop-marker-stack}). +(@code{xref-go-back}). +@item C-M-, +Go forward to where you previously invoked @kbd{M-,} +(@code{xref-go-forward}). @item M-x xref-etags-mode Switch @code{xref} to use the @code{etags} backend. @end table @@ -2204,15 +2213,17 @@ selects the window showing the first candidate. The default value is buffer, but doesn't select any of them. @kindex M-, -@findex xref-pop-marker-stack -@vindex xref-marker-ring-length +@findex xref-go-back To go back to places @emph{from where} you've displayed the definition, -use @kbd{M-,} (@code{xref-pop-marker-stack}). It jumps back to the +use @kbd{M-,} (@code{xref-go-back}). It jumps back to the point of the last invocation of @kbd{M-.}. Thus you can find and examine the definition of something with @kbd{M-.} and then return to -where you were with @kbd{M-,}. @kbd{M-,} allows you to retrace your -steps to a depth determined by the variable -@code{xref-marker-ring-length}, which defaults to 16. +where you were with @kbd{M-,}. + +@kindex C-M-, +@findex xref-go-forward + If you previously went back too far with @kbd{M-,}, @kbd{C-M-,} +(@code{xref-go-forward}) can be used to go forward again. @findex xref-etags-mode Some major modes install @code{xref} support facilities that might @@ -2312,10 +2323,15 @@ them. @item M-? Find all the references for the identifier at point. -@item M-x xref-query-replace-in-results @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET} +@item M-x xref-query-replace-in-results @key{RET} @var{replacement} @key{RET} +@itemx C-u M-x xref-query-replace-in-results @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET} Interactively replace @var{regexp} with @var{replacement} in the names of all the identifiers shown in the @file{*xref*} buffer. +@item M-x xref-find-references-and-replace @key{RET} @var{from} @key{RET} @var{to} @key{RET} +Interactively rename all instances of the identifier @var{from} to the +new name @var{to}. + @item M-x tags-search @key{RET} @var{regexp} @key{RET} Search for @var{regexp} through the files in the selected tags table. @@ -2353,13 +2369,21 @@ shown. The default value is @code{nil}, which just shows the results in the @file{*xref*} buffer, but doesn't select any of them. @findex xref-query-replace-in-results - @kbd{M-x xref-query-replace-in-results} reads a regexp to match identifier -names and a replacement string, just like ordinary @kbd{M-x -query-replace-regexp}. It then performs the specified replacement in -the names of the matching identifiers in all the places in all the -files where these identifiers are referenced. This is useful when you + @kbd{M-x xref-query-replace-in-results} reads a @var{replacement} +string, just like ordinary @kbd{M-x query-replace-regexp}. It then +renames the identifiers shown in the @file{*xref*} buffer in all the +places in all the files where these identifiers are referenced, such +that their new name is @var{replacement}. This is useful when you rename your identifiers as part of refactoring. This command should -be invoked in the @file{*xref*} buffer generated by @kbd{M-?}. +be invoked in the @file{*xref*} buffer generated by @kbd{M-?}. With a +prefix argument, the command also prompts for a regexp to match +identifier names, and renames that regexp in the names of the matching +identifiers with @var{replacement}. + +@findex xref-find-references-and-replace + @kbd{M-x xref-find-references-and-replace} works similarly to +@code{xref-query-replace-in-results}, but is more convenient when you +want to rename a single identifier specified by its name @var{from}. @findex tags-search @kbd{M-x tags-search} reads a regexp using the minibuffer, then diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi index 91c44d527b3..ad25ed6a8aa 100644 --- a/doc/emacs/mark.texi +++ b/doc/emacs/mark.texi @@ -291,12 +291,23 @@ instead signal an error if the mark is inactive. @cindex Delete Selection mode @cindex mode, Delete Selection @findex delete-selection-mode +@vindex delete-selection-temporary-region By default, text insertion occurs normally even if the mark is active---for example, typing @kbd{a} inserts the character @samp{a}, then deactivates the mark. Delete Selection mode, a minor mode, modifies this behavior: if you enable that mode, then inserting text while the mark is active causes the text in the region to be deleted -first. To toggle Delete Selection mode on or off, type @kbd{M-x +first. However, you can tune this behavior by customizing the +@code{delete-selection-temporary-region} option. Its default value is +@code{nil}, but you can set it to @code{t}, in which case only +temporarily-active regions will be replaced: those which are set by +dragging the mouse (@pxref{Setting Mark}) or by shift-selection +(@pxref{Shift Selection}), as well as by @kbd{C-u C-x C-x} when +Transient Mark Mode is disabled. You can further tune the behavior by +setting @code{delete-selection-temporary-region} to @code{selection}: +then temporary regions by @kbd{C-u C-x C-x} won't be replaced, only +the ones activated by dragging the mouse or shift-selection. To +toggle Delete Selection mode on or off, type @kbd{M-x delete-selection-mode}. @node Mark Ring diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi index 4769b522a66..e71d653210a 100644 --- a/doc/emacs/mini.texi +++ b/doc/emacs/mini.texi @@ -195,7 +195,14 @@ use the @kbd{C-o} (@code{open-line}) command (@pxref{Blank Lines}). often bound to @dfn{completion commands}, which allow you to easily fill in the desired text without typing all of it. @xref{Completion}. As with @key{RET}, you can use @kbd{C-q} to insert a @key{TAB}, -@key{SPC}, or @samp{?} character. +@key{SPC}, or @samp{?} character. If you want to make @key{SPC} and +@key{?} insert normally instead of starting completion, you can put +the following in your init file: + +@lisp +(keymap-unset minibuffer-local-completion-map "SPC") +(keymap-unset minibuffer-local-completion-map "?") +@end lisp For convenience, @kbd{C-a} (@code{move-beginning-of-line}) in a minibuffer moves point to the beginning of the argument text, not the @@ -371,6 +378,20 @@ window. You can display the same list with @kbd{?} used with the completion list: @table @kbd +@vindex minibuffer-completion-auto-choose +@item M-@key{DOWN} +@itemx M-@key{UP} +While in the minibuffer, these keys navigate through the completions +displayed in the completions buffer. When +@code{minibuffer-completion-auto-choose} is non-@code{nil} (which is +the default), using these commands also inserts the current completion +candidate into the minibuffer. If +@code{minibuffer-completion-auto-choose} is @code{nil}, you can use +the @kbd{M-@key{RET}} command to insert the completion candidates into +the minibuffer. By default, that exits the minibuffer, but with a +prefix argument, @kbd{C-u M-@key{RET}} inserts the currently active +candidate without exiting the minibuffer. + @findex switch-to-completions @item M-v @itemx @key{PageUp} @@ -386,7 +407,10 @@ ways (@pxref{Windows}). @itemx mouse-1 @itemx mouse-2 While in the completion list buffer, this chooses the completion at -point (@code{choose-completion}). +point (@code{choose-completion}). With a prefix argument, @kbd{C-u +@key{RET}} inserts the completion at point into the minibuffer, but +doesn't exit the minibuffer---thus, you can change your mind and +choose another candidate. @findex next-completion @item @key{TAB} @@ -617,11 +641,34 @@ completion alternatives in the completion list. @vindex completion-auto-help If @code{completion-auto-help} is set to @code{nil}, the completion commands never display the completion list buffer; you must type -@kbd{?} to display the list. If the value is @code{lazy}, Emacs only +@kbd{?} to display the list. If the value is @code{lazy}, Emacs only shows the completion list buffer on the second attempt to complete. In other words, if there is nothing to complete, the first @key{TAB} echoes @samp{Next char not unique}; the second @key{TAB} shows the -completion list buffer. +completion list buffer. If the value is @code{always}, the completion +list buffer is always shown when completion is attempted. + +The display of the completion list buffer after it is shown for the +first time is also controlled by @code{completion-auto-help}. If the +value is @code{t} or @code{lazy}, the window showing the completions +pops down when Emacs is able to complete (and may pop up again if +Emacs is again unable to complete after you type some more text); if +the value is @code{always}, the window pops down only when you exit +the completion. The value @code{visible} is a hybrid: it behaves like +@code{t} when it decides whether to pop up the window showing the +completion list buffer, and like @code{always} when it decides whether +to pop it down. + +@vindex completion-auto-select + Emacs can optionally select the window showing the completions when +it shows that window. To enable this behavior, customize the user +option @code{completion-auto-select} to @code{t}, which changes the +behavior of @key{TAB} when Emacs pops up the completions: pressing +@kbd{@key{TAB}} will switch to the completion list buffer, and you can +then move to a candidate by cursor motion commands and select it with +@kbd{@key{RET}}. If the value of @code{completion-auto-select} is +@code{second-tab}, then the first @kbd{@key{TAB}} will pop up the +completions list buffer, and the second one will switch to it. @vindex completion-cycle-threshold If @code{completion-cycle-threshold} is non-@code{nil}, completion @@ -638,11 +685,50 @@ behavior only when there are @var{n} or fewer alternatives. @vindex completions-format When displaying completions, Emacs will normally pop up a new buffer -to display the completions. The completions will (by default) be -sorted in columns horizontally in alphabetical order, but this can be -changed by changing the @code{completions-format} user option. If -@code{vertical}, sort the completions vertically in columns instead, -and if @code{one-column}, just use a single column. +to display the completions. The completions will by default be sorted +horizontally, using as many columns as will fit in the window-width, +but this can be changed by customizing the @code{completions-format} +user option. If its value is @code{vertical}, Emacs will sort the +completions vertically instead, and if it's @code{one-column}, Emacs +will use just one column. + +@vindex completions-sort + The @code{completions-sort} user option controls the order in which +the completions are sorted in the @samp{*Completions*} buffer. The +default is @code{alphabetical}, which sorts in alphabetical order. +The value @code{nil} disables sorting. The value can also be a +function, which will be called with the list of completions, and +should return the list in the desired order. + +@vindex completions-max-height + When @code{completions-max-height} is non-@code{nil}, it limits the +size of the completions window. It is specified in lines and include +mode, header line and a bottom divider, if any. For a more complex +control of the Completion window display properties, you can use +@code{display-buffer-alist} (@pxref{Buffer Display Action +Alists,,Action Alists for Buffer Display, elisp, The Emacs Lisp +Reference Manual}). + +@vindex completions-header-format +The variable @code{completions-header-format} is a format spec string to +control the informative line shown before the completions list of +candidates. If it contains a @samp{%s} construct, that get replaced +by the number of completions shown in the completion list buffer. To +suppress the display of the heading line, customize this variable to +@code{nil}. The string that is the value of this variable can have +text properties to change the visual appearance of the heading line; +some useful properties @code{face} or @code{cursor-intangible} +(@pxref{Special Properties,,Properties with Special Meanings, elisp, +The Emacs Lisp Reference Manual}). + +@vindex completions-highlight-face +When @code{completions-highlight-face} names a face, the current +completion candidate, the one that will be selected by typing +@kbd{@key{RET}} or clicking the mouse, will be highlighted using that +face. The default value of this variable is +@code{completions-highlight}; the value is @code{nil} disables this +highlighting. This feature uses the special text property +@code{cursor-face}. @node Minibuffer History @section Minibuffer History diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index 08c86e7a165..da1b87b48bd 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -1,6 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985--1987, 1993--1995, 1997, 2000--2022 Free Software -@c Foundation, Inc. +@c Copyright (C) 1985--2022 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @iftex @chapter Miscellaneous Commands @@ -455,20 +454,27 @@ servers the user has connected to. If this variable is @code{t}, @cindex PostScript file @cindex OpenDocument file @cindex Microsoft Office file +@cindex EPUB file +@cindex CBZ file +@cindex FB2 file +@cindex XPS file +@cindex OXPS file @cindex DocView mode @cindex mode, DocView @cindex document viewer (DocView) @findex doc-view-mode DocView mode is a major mode for viewing DVI, PostScript (PS), PDF, -OpenDocument, and Microsoft Office documents. It provides features -such as slicing, zooming, and searching inside documents. It works by -converting the document to a set of images using the @command{gs} -(GhostScript) or @command{mudraw}/@command{pdfdraw} (MuPDF) commands -and other external tools @footnote{For PostScript files, GhostScript -is a hard requirement. For DVI files, @code{dvipdf} or @code{dvipdfm} -is needed. For OpenDocument and Microsoft Office documents, the -@code{unoconv} tool is needed.}, and displaying those images. +OpenDocument, Microsoft Office, EPUB, CBZ, FB2, XPS and OXPS +documents. It provides features such as slicing, zooming, and +searching inside documents. It works by converting the document to a +set of images using the @command{gs} (GhostScript) or +@command{pdfdraw}/@command{mutool draw} (MuPDF) commands and other +external tools @footnote{PostScript files require GhostScript, DVI +files require @code{dvipdf} or @code{dvipdfm}, OpenDocument and +Microsoft Office documents require the @code{unoconv} tool, and EPUB, +CBZ, FB2, XPS and OXPS files require @code{mutool} to be available.}, +and displaying those images. @findex doc-view-toggle-display @findex doc-view-minor-mode @@ -849,6 +855,9 @@ Restores the position of point as it was before inserting the shell-command output. @end table +In case the output buffer is not the current buffer, shell command +output is appended at the end of this buffer. + @node Interactive Shell @subsection Interactive Subshell @@ -886,6 +895,19 @@ also rename the @file{*shell*} buffer using @kbd{M-x rename-uniquely}, then create a new @file{*shell*} buffer using plain @kbd{M-x shell}. Subshells in different buffers run independently and in parallel. + Emacs attempts to keep track of what the current directory is by +looking at the commands you enter, looking for @samp{cd} commands and +the like. This is an error-prone solution, since there are many ways +to change the current directory, so Emacs also looks for special +@acronym{OSC} (Operating System Commands) escape codes that are +designed to convey this information in a more reliable fashion. You +should arrange for your shell to print the appropriate escape sequence +at each prompt, for instance with the following command: + +@example +printf "\e]7;file://%s%s\e\\" "$HOSTNAME" "$PWD" +@end example + @vindex explicit-shell-file-name @cindex environment variables for subshells @cindex @env{ESHELL} environment variable @@ -1497,14 +1519,20 @@ directory stack if they are not already on it underlying shell, of course. @vindex comint-terminfo-terminal +@vindex system-uses-terminfo @vindex TERM@r{, environment variable, in sub-shell} Comint mode sets the @env{TERM} environment variable to a safe default value, but this value disables some useful features. For example, color is disabled in applications that use @env{TERM} to determine if color is supported. Therefore, Emacs provides an option -@code{comint-terminfo-terminal}, which you can set to a terminal that -is present in your system's terminfo database, in order to take -advantage of advanced features of that terminal. +@code{comint-terminfo-terminal} to let you choose a terminal with more +advanced features, as defined in your system's terminfo database. +Emacs will use this option as the value for @env{TERM} so long as +@code{system-uses-terminfo} is non-nil. + +Both @code{comint-terminfo-terminal} and @code{system-uses-terminfo} +can be declared as connection-local variables to adjust these options +to match what a remote system expects (@pxref{Connection Variables}). @node Terminal emulator @subsection Emacs Terminal Emulator @@ -1614,11 +1642,11 @@ interface is similar to the @code{more} program. @cindex remote host @cindex connecting to remote host @cindex Telnet -@cindex Rlogin +@cindex SSH You can login to a remote computer, using whatever commands you -would from a regular terminal (e.g., using the @command{ssh} or -@command{telnet} or @code{rlogin} commands), from a Term window. +would from a regular terminal (e.g., the @command{ssh} command), from +a Term window. A program that asks you for a password will normally suppress echoing of the password, so the password will not show up in the @@ -1697,6 +1725,11 @@ options. @xref{Initial Options}. When Emacs is started this way, it calls @code{server-start} after initialization and does not open an initial frame. It then waits for edit requests from clients. +@item +Run the command @code{emacsclient} with the @samp{--alternate-editor=""} +command-line option. This starts an Emacs daemon only if no Emacs daemon +is already running. + @cindex systemd unit file @item If your operating system uses @command{systemd} to manage startup, @@ -1763,6 +1796,32 @@ you can give each daemon its own server name like this: emacs --daemon=foo @end example +@findex server-stop-automatically + The Emacs server can optionally be stopped automatically when +certain conditions are met. To do this, call the function +@code{server-stop-automatically} in your init file (@pxref{Init +File}), with one of the following arguments: + +@itemize +@item +With the argument @code{empty}, the server is stopped when it has no +clients, no unsaved file-visiting buffers and no running processes +anymore. + +@item +With the argument @code{delete-frame}, when the last client frame is +being closed, you are asked whether each unsaved file-visiting buffer +must be saved and each unfinished process can be stopped, and if so, +the server is stopped. + +@item +With the argument @code{kill-terminal}, when the last client frame is +being closed with @kbd{C-x C-c} (@code{save-buffers-kill-terminal}), +you are asked whether each unsaved file-visiting buffer must be saved +and each unfinished process can be stopped, and if so, the server is +stopped. +@end itemize + @findex server-eval-at If you have defined a server by a unique server name, it is possible to connect to the server from another Emacs instance and evaluate Lisp @@ -1986,6 +2045,11 @@ the new frame displays the @file{*scratch*} buffer by default. You can customize this behavior with the variable @code{initial-buffer-choice} (@pxref{Entering Emacs}). +@item -r +@itemx --reuse-frame +Create a new graphical client frame if none exists, otherwise use an +existing Emacs frame. + @item -F @var{alist} @itemx --frame-parameters=@var{alist} Set the parameters for a newly-created graphical frame @@ -2718,7 +2782,12 @@ will by default ask you whether to use the locked desktop file. You can avoid the question by customizing the variable @code{desktop-load-locked-desktop} to either @code{nil}, which means never load the desktop in this case, or @code{t}, which means load the -desktop without asking. +desktop without asking. Finally, the @code{check-pid} value means to +load the file if the Emacs process that has locked the desktop is not +running on the local machine. This should not be used in +circumstances where the locking Emacs might still be running on +another machine. This could be the case in multi-user environments +where your home directory is mounted remotely using NFS or similar. @cindex desktop restore in daemon mode When Emacs starts in daemon mode, it cannot ask you any questions, @@ -2800,99 +2869,6 @@ new major mode which provides a command to switch back. These approaches give you more flexibility to go back to unfinished tasks in the order you choose. -@ignore -@c Apart from edt and viper, this is all obsolete. -@c (Can't believe we were saying "most other editors" into 2014!) -@c There seems no point having a node just for those, which both have -@c their own manuals. -@node Emulation -@section Emulation -@cindex emulating other editors -@cindex other editors -@cindex EDT -@cindex vi -@cindex WordStar - - GNU Emacs can be programmed to emulate (more or less) most other -editors. Standard facilities can emulate these: - -@table @asis -@item CRiSP/Brief (PC editor) -@findex crisp-mode -@vindex crisp-override-meta-x -@findex scroll-all-mode -@cindex CRiSP mode -@cindex Brief emulation -@cindex emulation of Brief -@cindex mode, CRiSP -@kbd{M-x crisp-mode} enables key bindings to emulate the CRiSP/Brief -editor. Note that this rebinds @kbd{M-x} to exit Emacs unless you set -the variable @code{crisp-override-meta-x}. You can also use the -command @kbd{M-x scroll-all-mode} or set the variable -@code{crisp-load-scroll-all} to emulate CRiSP's scroll-all feature -(scrolling all windows together). - -@item EDT (DEC VMS editor) -@findex edt-emulation-on -@findex edt-emulation-off -Turn on EDT emulation with @kbd{M-x edt-emulation-on}; restore normal -command bindings with @kbd{M-x edt-emulation-off}. - -Most of the EDT emulation commands are keypad keys, and most standard -Emacs key bindings are still available. The EDT emulation rebindings -are done in the global keymap, so there is no problem switching -buffers or major modes while in EDT emulation. - -@item TPU (DEC VMS editor) -@findex tpu-edt-on -@cindex TPU -@kbd{M-x tpu-edt-on} turns on emulation of the TPU editor emulating EDT. - -@item vi (Berkeley editor) -@findex viper-mode -Viper is an emulator for vi. It implements several levels of -emulation; level 1 is closest to vi itself, while level 5 departs -somewhat from strict emulation to take advantage of the capabilities of -Emacs. To invoke Viper, type @kbd{M-x viper-mode}; it will guide you -the rest of the way and ask for the emulation level. @inforef{Top, -Viper, viper}. - -@item vi (another emulator) -@findex vi-mode -@kbd{M-x vi-mode} enters a major mode that replaces the previously -established major mode. All of the vi commands that, in real vi, enter -input mode are programmed instead to return to the previous major -mode. Thus, ordinary Emacs serves as vi's input mode. - -Because vi emulation works through major modes, it does not work -to switch buffers during emulation. Return to normal Emacs first. - -If you plan to use vi emulation much, you probably want to bind a key -to the @code{vi-mode} command. - -@item vi (alternate emulator) -@findex vip-mode -@kbd{M-x vip-mode} invokes another vi emulator, said to resemble real vi -more thoroughly than @kbd{M-x vi-mode}. Input mode in this emulator -is changed from ordinary Emacs so you can use @key{ESC} to go back to -emulated vi command mode. To get from emulated vi command mode back to -ordinary Emacs, type @kbd{C-z}. - -This emulation does not work through major modes, and it is possible -to switch buffers in various ways within the emulator. It is not -so necessary to assign a key to the command @code{vip-mode} as -it is with @code{vi-mode} because terminating insert mode does -not use it. - -@inforef{Top, VIP, vip}, for full information. - -@item WordStar (old wordprocessor) -@findex wordstar-mode -@kbd{M-x wordstar-mode} provides a major mode with WordStar-like -key bindings. -@end table -@end ignore - @node Hyperlinking @section Hyperlinking and Web Navigation Features @@ -2942,6 +2918,41 @@ one-key commands for scrolling the widget, changing its size, and reloading it. Type @w{@kbd{C-h b}} in that buffer to see the key bindings. +@findex xwidget-webkit-edit-mode +@cindex xwidget-webkit-edit-mode + By default, typing a self-inserting character inside an xwidget +webkit buffer will do nothing, or trigger some special action. To +make those characters and other common editing keys insert themselves +when pressed, you can enable @code{xwidget-webkit-edit-mode}, which +redefines them to be passed through to the WebKit xwidget. + +You can also enable @code{xwidget-webkit-edit-mode} by typing @kbd{e} +inside the xwidget webkit buffer. + +@findex xwidget-webkit-isearch-mode +@cindex searching in webkit buffers + @code{xwidget-webkit-isearch-mode} is a minor mode that behaves +similarly to incremental search (@pxref{Incremental Search}), but +operates on the contents of a WebKit widget instead of the current +buffer. It is bound to @kbd{C-s} and @kbd{C-r} inside xwidget-webkit +buffers. When it is invoked by @kbd{C-r}, the initial search will be +performed in reverse direction. + +Typing any self-inserting character will cause the character to be +inserted into the current search query. Typing @kbd{C-s} will cause +the WebKit widget to display the next search result, while typing +@kbd{C-r} will cause it to display the previous one. + +To leave incremental search, you can type @kbd{C-g}. + +@findex xwidget-webkit-browse-history +@cindex history of webkit buffers + The command @code{xwidget-webkit-browse-history} displays a buffer +containing a list of pages previously loaded by the current WebKit +buffer, and lets you navigate to those pages by hitting @kbd{RET}. + +It is bound to @kbd{H}. + @node Browse-URL @subsection Following URLs @cindex World Wide Web diff --git a/doc/emacs/msdos-xtra.texi b/doc/emacs/msdos-xtra.texi index 9cf04ea8a94..57e1ac90a51 100644 --- a/doc/emacs/msdos-xtra.texi +++ b/doc/emacs/msdos-xtra.texi @@ -105,7 +105,7 @@ following line into your @file{_emacs} file: @smallexample ;; @r{Make the @key{ENTER} key from the numeric keypad act as @kbd{C-j}.} -(define-key function-key-map [kp-enter] [?\C-j]) +(keymap-set function-key-map "<kp-enter>" "C-j") @end smallexample @node MS-DOS Mouse diff --git a/doc/emacs/msdos.texi b/doc/emacs/msdos.texi index 74497b6eab9..dd0787cd38d 100644 --- a/doc/emacs/msdos.texi +++ b/doc/emacs/msdos.texi @@ -986,9 +986,9 @@ printer, put this in your @file{.emacs} file: @section Specifying Fonts on MS-Windows @cindex font specification (MS Windows) - Starting with Emacs 23, fonts are specified by their name, size -and optional properties. The format for specifying fonts comes from the -fontconfig library used in modern Free desktops: + Fonts are specified by their name, size and optional properties. +The format for specifying fonts comes from the fontconfig library used +in modern Free desktops: @example [Family[-PointSize]][:Option1=Value1[:Option2=Value2[...]]] @@ -1181,6 +1181,14 @@ The default is @code{t}, which fits well with the Windows default click-to-focus policy. @end ifnottex + On Windows 10 (version 1809 and higher) and Windows 11, Emacs title +bars and scroll bars will follow the system's Light or Dark mode, +similar to other programs such as Explorer and Command Prompt. To +change the color mode, select @code{Personalization} from +@w{@code{Windows Settings}}, then +@w{@code{Colors->Choose your color}} (or @w{@code{Choose your default +app mode}}); then restart Emacs. + @ifnottex @include msdos-xtra.texi @end ifnottex diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi index f87c1252d3c..5f303418383 100644 --- a/doc/emacs/mule.texi +++ b/doc/emacs/mule.texi @@ -50,13 +50,14 @@ others. @item You can insert non-@acronym{ASCII} characters or search for them. To do that, -you can specify an input method (@pxref{Select Input Method}) suitable +you can specify an Emacs input method (@pxref{Select Input Method}) suitable for your language, or use the default input method set up when you choose your language environment. If your keyboard can produce non-@acronym{ASCII} characters, you can select an appropriate keyboard coding system (@pxref{Terminal Coding}), and Emacs -will accept those characters. Latin-1 characters can also be input by -using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}. +will accept those characters. On graphical displays, modern systems +typically provide their native input methods, and Latin-1 characters +can also be input by using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}. With the X Window System, your locale should be set to an appropriate value to make sure Emacs interprets keyboard input correctly; see @@ -449,10 +450,13 @@ for that key. @cindex input methods An @dfn{input method} is a kind of character conversion designed -specifically for interactive input. In Emacs, typically each language -has its own input method; sometimes several languages that use the same -characters can share one input method. A few languages support several -input methods. +specifically for interactive input. This section describes input +methods that come with Emacs; for native input methods provided by the +underlying OS, @pxref{Unibyte Mode}. + + In Emacs, typically each language has its own input method; +sometimes several languages that use the same characters can share one +input method. A few languages support several input methods. The simplest kind of input method works by mapping @acronym{ASCII} letters into another alphabet; this allows you to use one other alphabet @@ -473,6 +477,10 @@ First, letters are mapped into symbols for particular sounds or tone marks; then, sequences of these that make up a whole syllable are mapped into one syllable sign. +@kindex C-f@r{, when using input methods} +@kindex C-b@r{, when using input methods} +@kindex C-n@r{, when using input methods} +@kindex C-p@r{, when using input methods} Chinese and Japanese require more complex methods. In Chinese input methods, first you enter the phonetic spelling of a Chinese word (in input method @code{chinese-py}, among others), or a sequence of @@ -498,6 +506,7 @@ alternatives in the row are also numbered; the number appears before the alternative. Typing a number selects the associated alternative of the current row and uses it as input. +@kindex TAB@r{, when using Chinese input methods} @key{TAB} in these Chinese input methods displays a buffer showing all the possible characters at once; then clicking @kbd{mouse-2} on one of them selects that alternative. The keys @kbd{C-f}, @kbd{C-b}, @@ -571,11 +580,37 @@ modes that make buffer text or parts of it read-only, such as @code{read-only-mode} and @code{image-mode}, even when an input method is active. +@kindex C-x 8 @key{RET} +@cindex insert character by name or code-point Another facility for typing characters not on your keyboard is by using @kbd{C-x 8 @key{RET}} (@code{insert-char}) to insert a single character based on its Unicode name or code-point; see @ref{Inserting Text}. +@cindex emoji input +@cindex inserting Emoji +@kindex C-x 8 e +@findex emoji-insert +@findex emoji-list +@findex emoji-search + There are specialized commands for inserting Emoji, and these can be +found on the @kbd{C-x 8 e} keymap. @kbd{C-x 8 e e} +(@code{emoji-insert}) will let you navigate through different Emoji +categories and then choose one. @kbd{C-x 8 e l} (@code{emoji-list}) +will pop up a new buffer and list all the Emoji; clicking (or using +@kbd{RET}) on an emoji character will insert it in the current buffer. +Finally, @kbd{C-x 8 e s} (@code{emoji-search}) will allow you to +search for Emoji based on their names. + +@findex emoji-describe + @code{describe-char} displays a lot of information about the +character/glyphs under point (including emojis). It's sometimes +useful to get a quick description of the name, and you can use the +@kbd{C-x 8 e d} (@code{emoji-describe}) command to do that. It's +meant primarily to help distinguish between different Emoji +variants (which can look very similar), but it will also tell you +the names of non-Emoji characters. + @node Select Input Method @section Selecting an Input Method @@ -1767,12 +1802,38 @@ as @code{xterm}, you can arrange for Meta to be converted to @key{ESC} and still be able to type 8-bit characters present directly on the keyboard or using @key{Compose} or @key{AltGr} keys. @xref{User Input}. +@cindex input methods, native +@cindex XIM, X Input Methods +@cindex GTK input methods +Many modern systems provide @dfn{native input methods} for many +languages whose characters don't have keyboard keys assigned to them. +If Emacs was built with support for these native input methods, you +can activate such an input method and type the characters they +support. How to activate and use these input methods depends on the +system and the input method, and will not be described here; see your +system documentation. Here we describe some Emacs facilities to +control the use of the native input methods. + +@vindex x-gtk-use-native-input +In Emacs built with the GTK toolkit, the variable +@code{x-gtk-use-native-input} controls whether Emacs should receive +characters produced by GTK input methods. If the value is @code{nil}, +the default, Emacs uses the X input methods (@acronym{XIM}), otherwise +it uses the GTK input methods. The @code{useXIM} X resource controls +whether to use @acronym{XIM}, and @code{inputStyle} X resource +controls the display on X of preview text generated by the native +input methods; @pxref{Table of Resources}. + +On MS-Windows, Emacs supports native inputs methods provided by +@acronym{IMM}, the Input Method Manager, but that can be turned off if +needed; @pxref{Windows Keyboard}. + @cindex @code{iso-transl} library @cindex compose character @cindex dead character @item You can use the key @kbd{C-x 8} as a compose-character prefix for -entry of non-@acronym{ASCII} Latin-1 and a few other printing +entry of non-@acronym{ASCII} Latin-1 and other printing characters. @kbd{C-x 8} is good for insertion (in the minibuffer as well as other buffers), for searching, and in any other context where a key sequence is allowed. @@ -1961,3 +2022,16 @@ or right of the current screen position, moving to the next or previous screen line as appropriate. Note that this might potentially move point many buffer positions away, depending on the surrounding bidirectional context. + +@cindex bidi formatting control characters + Bidirectional text sometimes uses special formatting characters to +affect the reordering of text for display. The @sc{lrm} and @sc{rlm} +characters, mentioned above, are two such characters, but there are +more of them. They are by default displayed as thin space glyphs on +GUI frames, and as simple spaces on text-mode frames. If you want to +be aware of these special control characters, so that their effect on +display does not come as a surprise, you can turn on the +@code{glyphless-display-mode} (@pxref{Text Display}). This minor mode +will cause these formatting characters to be displayed as acronyms +inside a small box, so that they stand out on display, and make their +effect easier to understand. diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi index caa65bf33b6..7e16c82cf5c 100644 --- a/doc/emacs/package.texi +++ b/doc/emacs/package.texi @@ -89,6 +89,11 @@ list of available packages from package archive servers. If the network is unavailable, it falls back on the most recently retrieved list. +The main command to use in the package list buffer is the @key{x} +command. If the package under point isn't installed already, this +command will install it. If the package under point is already +installed, this command will delete it. + The following commands are available in the package menu: @table @kbd @@ -162,7 +167,10 @@ installed versions (marked with status @samp{obsolete}). @findex package-menu-execute Download and install all packages marked with @kbd{i}, and their dependencies; also, delete all packages marked with @kbd{d} -(@code{package-menu-execute}). This also removes the marks. +(@code{package-menu-execute}). This also removes the marks. If no +packages are marked, this command will install the package under point +(if it isn't installed already), or delete the package under point (if +it's already installed). @item g @item r @@ -320,10 +328,15 @@ version of the package, a newer version is also installed. @section Package Installation @findex package-install +@findex package-update +@findex package-update-all Packages are most conveniently installed using the package menu (@pxref{Package Menu}), but you can also use the command @kbd{M-x package-install}. This prompts for the name of a package with the -@samp{available} status, then downloads and installs it. +@samp{available} status, then downloads and installs it. Similarly, +if you want to update a package, you can use the @kbd{M-x +package-update} command, and if you just want to update all the +packages, you can use the @kbd{M-x package-update-all} command. @cindex package requirements A package may @dfn{require} certain other packages to be installed, @@ -470,6 +483,16 @@ The default value is just @code{'(all)}. installed will be ignored. The @samp{muse} package will be listed in the package menu with the @samp{held} status. +@findex package-recompile +@findex package-recompile-all + Emacs byte code is quite stable, but it's possible for byte code to +become outdated, or for the compiled files to rely on macros that have +changed in new versions of Emacs. You can use the command @w{@kbd{M-x +package-recompile}} to recompile a particular package, or +@w{@kbd{M-x package-recompile-all}} to recompile all the packages. (The +latter command might take quite a while to run if you have many +installed packages.) + @node Package Files @section Package Files and Directory Layout @cindex package directory diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index c3a70a5fc93..795aabee743 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -250,10 +250,10 @@ where it treats each chapter, section, etc., as a definition. together.) @findex imenu - If you type @kbd{M-x imenu}, it reads the name of a definition using -the minibuffer, then moves point to that definition. You can use -completion to specify the name; the command always displays the whole -list of valid names. + If you type @kbd{M-g i} (@code{imenu}), it reads the name of a +definition using the minibuffer, then moves point to that definition. +You can use completion to specify the name; the command always +displays the whole list of valid names. @findex imenu-add-menubar-index Alternatively, you can bind the command @code{imenu} to a mouse @@ -868,6 +868,15 @@ highlighting also when point is in whitespace at the beginning of a line and there is a paren at the first or last non-whitespace position on the line, or when point is at the end of a line and there is a paren at the last non-whitespace position on the line. + +@item +@vindex show-paren-context-when-offscreen +@code{show-paren-context-when-offscreen}, when non-@code{nil}, shows +some context in the echo area when point is in a closing delimiter and +the opening delimiter is offscreen. The context is usually the line +that contains the opening delimiter, except if the opening delimiter +is on its own line, in which case the context includes the previous +nonblank line. @end itemize @cindex Electric Pair mode @@ -1430,9 +1439,13 @@ performs completion using the function, variable, or property names defined in the current Emacs session. In all other respects, in-buffer symbol completion behaves like -minibuffer completion. For instance, if Emacs cannot complete to a -unique symbol, it displays a list of completion alternatives in -another window. @xref{Completion}. +minibuffer completion. For instance, if Emacs cannot complete to +a unique symbol, it displays a list of completion alternatives in +another window. Then you can use the keys @kbd{M-@key{DOWN}} and +@kbd{M-@key{UP}} to navigate through the completions displayed +in the completions buffer without leaving the original buffer, +and the key @kbd{M-@key{RET}} to insert the currently highlighted +completion to the buffer. @xref{Completion}. In Text mode and related modes, @kbd{M-@key{TAB}} completes words based on the spell-checker's dictionary. @xref{Spelling}. @@ -1818,7 +1831,7 @@ sure the keymap is loaded before we try to change it. @example (defun my-bind-clb () - (define-key c-mode-base-map "\C-m" + (keymap-set c-mode-base-map "RET" 'c-context-line-break)) (add-hook 'c-initialization-hook 'my-bind-clb) @end example diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi index 665e9443236..fb936018798 100644 --- a/doc/emacs/regs.texi +++ b/doc/emacs/regs.texi @@ -47,14 +47,14 @@ are similar in spirit to registers, so they are also documented in this chapter. @menu -* Position Registers:: Saving positions in registers. -* Text Registers:: Saving text in registers. -* Rectangle Registers:: Saving rectangles in registers. -* Configuration Registers:: Saving window configurations in registers. -* Number Registers:: Numbers in registers. -* File Registers:: File names in registers. -* Keyboard Macro Registers:: Keyboard macros in registers. -* Bookmarks:: Bookmarks are like registers, but persistent. +* Position Registers:: Saving positions in registers. +* Text Registers:: Saving text in registers. +* Rectangle Registers:: Saving rectangles in registers. +* Configuration Registers:: Saving window configurations in registers. +* Number Registers:: Numbers in registers. +* File and Buffer Registers:: File and buffer names in registers. +* Keyboard Macro Registers:: Keyboard macros in registers. +* Bookmarks:: Bookmarks are like registers, but persistent. @end menu @node Position Registers @@ -238,9 +238,10 @@ register contents into the buffer. @kbd{C-x r +} with no numeric argument increments the register value by 1; @kbd{C-x r n} with no numeric argument stores zero in the register. -@node File Registers -@section Keeping File Names in Registers +@node File and Buffer Registers +@section Keeping File and Buffer Names in Registers @cindex saving file name in a register +@cindex saving buffer name in a register If you visit certain file names frequently, you can visit them more conveniently if you put their names in registers. Here's the Lisp code @@ -265,6 +266,15 @@ puts the file name shown in register @samp{z}. @var{r}}. (This is the same command used to jump to a position or restore a frame configuration.) + Similarly, if there's certain buffers you visit frequently, you +can put their names in registers. For instance, if you visit the +@samp{*Messages*} buffer often, you can use the following snippet to +put that buffer into the @samp{m} register: + +@smallexample +(set-register ?m '(buffer . "*Messages*")) +@end smallexample + @node Keyboard Macro Registers @section Keyboard Macro Registers @cindex saving keyboard macro in a register diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi index 269ea71aa8f..582e764c55f 100644 --- a/doc/emacs/search.texi +++ b/doc/emacs/search.texi @@ -228,8 +228,9 @@ customizing the @code{isearch-wrap-pause} user option. If it is @code{t} (the default), signal an error. (Repeating the search will wrap around.) If @code{no}, issue a @code{ding} and wrap immediately after reaching the last match. If @code{no-ding}, wrap immediately, -but don't @code{ding}. Finally, if @code{nil}, never wrap, but just -stop at the last match. +but don't @code{ding}. With the values @code{no} and @code{no-ding} +the search will try to wrap around also on typing a character. +Finally, if @code{nil}, never wrap, but just stop at the last match. @cindex search ring @findex isearch-ring-advance @@ -422,7 +423,7 @@ characters, that disables character folding during that search. search string. To search for non-@acronym{ASCII} characters, use one of the -following methods: +following methods during incremental search: @itemize @bullet @item @@ -436,14 +437,6 @@ incremental search adds the @samp{control-S} character to the search string. @item -@findex isearch-char-by-name -@kindex C-x 8 RET @r{(Incremental Search)} -Type @kbd{C-x 8 @key{RET}} (@code{isearch-char-by-name}), followed by -a Unicode name or code-point in hex. This adds the specified -character into the search string, similar to the usual -@code{insert-char} command (@pxref{Inserting Text}). - -@item @kindex C-^ @r{(Incremental Search)} @findex isearch-toggle-input-method @findex isearch-toggle-specified-input-method @@ -471,8 +464,26 @@ transient input method (@pxref{transient input method}) with @kbd{C-x \} (@code{isearch-transient-input-method}) to insert a single character to the search string using an input method, and automatically disable the input method afterwards. + +@item +@findex isearch-char-by-name +@kindex C-x 8 RET @r{(Incremental Search)} +Type @kbd{C-x 8 @key{RET}} (@code{isearch-char-by-name}), followed by +a Unicode name or code-point in hex. This adds the specified +character into the search string, similar to the usual +@code{insert-char} command (@pxref{Inserting Text}). @end itemize +@findex isearch-emoji-by-name +@kindex C-x 8 e RET @r{(Incremental Search)} + You can also include Emoji sequences in the search string. Type +@w{@kbd{C-x 8 e @key{RET}}} (@code{isearch-emoji-by-name}), followed +by the Unicode name of an Emoji (for example, @kbd{smiling face} or +@kbd{heart with arrow}). This adds the specified Emoji to the search +string. If you don't know the name of the Emoji you want to search +for, you can use @kbd{C-x 8 e l} (@code{emoji-list}) and @kbd{C-x 8 e +d} (@code{emoji-describe}) (@pxref{Input Methods}). + @kindex M-s o @r{(Incremental Search)} @findex isearch-occur Typing @kbd{M-s o} in incremental search invokes @@ -889,11 +900,13 @@ character folding during incremental regexp search with @kbd{M-s '}, the search becomes a non-regexp search and the search pattern you typed is interpreted as a literal string.) +@cindex pending, in incremental search In some cases, adding characters to the regexp in an incremental regexp search can make the cursor move back and start again. For example, if you have searched for @samp{foo} and you add @samp{\|bar}, the cursor backs up in case the first @samp{bar} precedes the first -@samp{foo}. @xref{Regexps}. +@samp{foo}. (The prompt will change to say ``Pending'' to notify the +user that this recalculation has happened.) @xref{Regexps}. Forward and backward regexp search are not symmetrical, because regexp matching in Emacs always operates forward, starting with the @@ -1015,24 +1028,11 @@ you search for @samp{a.*?$} against the text @samp{abbab} followed by a newline, it matches the whole string. Since it @emph{can} match starting at the first @samp{a}, it does. -@item @kbd{\@{@var{n}\@}} -is a postfix operator specifying @var{n} repetitions---that is, the -preceding regular expression must match exactly @var{n} times in a -row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx} and -nothing else. - -@item @kbd{\@{@var{n},@var{m}\@}} -is a postfix operator specifying between @var{n} and @var{m} -repetitions---that is, the preceding regular expression must match at -least @var{n} times, but no more than @var{m} times. If @var{m} is -omitted, then there is no upper limit, but the preceding regular -expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is -equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to -@samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}. - +@cindex set of alternative characters, in regular expressions +@cindex character set, in regular expressions @item @kbd{[ @dots{} ]} -is a @dfn{character set}, beginning with @samp{[} and terminated by -@samp{]}. +is a @dfn{set of alternative characters}, or a @dfn{character set}, +beginning with @samp{[} and terminated by @samp{]}. In the simplest case, the characters between the two brackets are what this set can match. Thus, @samp{[ad]} matches either one @samp{a} or @@ -1049,9 +1049,10 @@ which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or period. As another example, @samp{[α-ωί]} matches all lower-case Greek letters. +@cindex character classes, in regular expressions You can also include certain special @dfn{character classes} in a character set. A @samp{[:} and balancing @samp{:]} enclose a -character class inside a character alternative. For instance, +character class inside a set of alternative characters. For instance, @samp{[[:alnum:]]} matches any letter or digit. @xref{Char Classes,,, elisp, The Emacs Lisp Reference Manual}, for a list of character classes. @@ -1119,13 +1120,13 @@ no preceding expression on which the @samp{*} can act. It is poor practice to depend on this behavior; it is better to quote the special character anyway, regardless of where it appears. -As a @samp{\} is not special inside a character alternative, it can -never remove the special meaning of @samp{-} or @samp{]}. So you -should not quote these characters when they have no special meaning -either. This would not clarify anything, since backslashes can -legitimately precede these characters where they @emph{have} special -meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax), -which matches any single character except a backslash. +As a @samp{\} is not special inside a set of alternative characters, it can +never remove the special meaning of @samp{-}, @samp{^} or @samp{]}. +You should not quote these characters when they have no special +meaning. This would not clarify anything, since backslashes +can legitimately precede these characters where they @emph{have} +special meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string +syntax), which matches any single character except a backslash. @node Regexp Backslash @section Backslash in Regular Expressions @@ -1190,11 +1191,11 @@ matches the same text that matched the @var{d}th occurrence of a @samp{\( @dots{} \)} construct. This is called a @dfn{back reference}. -After the end of a @samp{\( @dots{} \)} construct, the matcher remembers -the beginning and end of the text matched by that construct. Then, -later on in the regular expression, you can use @samp{\} followed by the -digit @var{d} to mean ``match the same text matched the @var{d}th time -by the @samp{\( @dots{} \)} construct''. +After the end of a @samp{\( @dots{} \)} construct, the matcher +remembers the beginning and end of the text matched by that construct. +Then, later on in the regular expression, you can use @samp{\} +followed by the digit @var{d} to mean ``match the same text matched +the @var{d}th @samp{\( @dots{} \)} construct''. The strings matching the first nine @samp{\( @dots{} \)} constructs appearing in a regular expression are assigned numbers 1 through 9 in @@ -1211,6 +1212,21 @@ If a particular @samp{\( @dots{} \)} construct matches more than once (which can easily happen if it is followed by @samp{*}), only the last match is recorded. +@item @kbd{\@{@var{m}\@}} +is a postfix operator specifying @var{m} repetitions---that is, the +preceding regular expression must match exactly @var{m} times in a +row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx} and +nothing else. + +@item @kbd{\@{@var{m},@var{n}\@}} +is a postfix operator specifying between @var{m} and @var{n} +repetitions---that is, the preceding regular expression must match at +least @var{m} times, but no more than @var{n} times. If @var{n} is +omitted, then there is no upper limit, but the preceding regular +expression must match at least @var{m} times.@* @samp{\@{0,1\@}} is +equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to +@samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}. + @item \` matches the empty string, but only at the beginning of the string or buffer (or its accessible portion) being matched against. @@ -1450,9 +1466,13 @@ letter @code{a} as well as all the other variants like @code{@'a}. @vindex char-fold-include @vindex char-fold-exclude +@vindex char-fold-override You can add new foldings using the customizable variable @code{char-fold-include}, or remove the existing ones using the -customizable variable @code{char-fold-exclude}. +customizable variable @code{char-fold-exclude}. You can also +customize @code{char-fold-override} to @code{t} to disable all the +character equivalences except those you add yourself using +@code{char-fold-include}. @node Replace @section Replacement Commands @@ -1810,12 +1830,18 @@ occurrence of @var{string}. When done, exit the recursive editing level with @kbd{C-M-c} to proceed to the next occurrence. @item e -@itemx E to edit the replacement string in the minibuffer. When you exit the minibuffer by typing @key{RET}, the minibuffer contents replace the current occurrence of the pattern. They also become the new replacement string for any further occurrences. +@item E +is like @kbd{e}, but the next replacement will be done with exact +case. I.e., if you have a @code{query-replace} from @samp{foo} to +@samp{bar}, a text like @samp{Foo} will be normally be replaced with +@samp{Bar}. Use this command to do the current replacement with exact +case. + @item C-l to redisplay the screen. Then you must type another character to specify what to do with this occurrence. diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi index 8c09f62677b..fa8eaf09245 100644 --- a/doc/emacs/text.texi +++ b/doc/emacs/text.texi @@ -474,8 +474,8 @@ insert a curved quote even when Electric Quote is disabled or inactive, you can type @kbd{C-x 8 [} for @t{‘}, @kbd{C-x 8 ]} for @t{’}, @kbd{C-x 8 @{} for @t{“}, and @kbd{C-x 8 @}} for @t{”}. @xref{Inserting Text}. Note that the value of -@code{electric-quote-chars} does not affect these keybindings, they -are not keybindings of @code{electric-quote-mode} but bound in +@code{electric-quote-chars} does not affect these key bindings, they +are not key bindings of @code{electric-quote-mode} but bound in @code{global-map}. @node Filling @@ -996,6 +996,13 @@ specific file (@pxref{File Variables}). major mode's special commands. (The variable @code{outline-minor-mode-prefix} controls the prefix used.) +@vindex outline-minor-mode-use-buttons + If @code{outline-minor-mode-use-buttons} is non-@code{nil}, Outline +minor mode will use buttons (at the start of the header lines) in +addition to ellipsis to show that a section is hidden. Using +@kbd{RET} (or clicking on the button with a mouse) will toggle +displaying the section. + @vindex outline-minor-mode-cycle If the @code{outline-minor-mode-cycle} user option is non-@code{nil}, the @kbd{TAB} and @kbd{S-@key{TAB}} keys are enabled on the @@ -1252,6 +1259,17 @@ and related functions treat hidden text, @pxref{Query Replace}.) You can also automatically make text visible as you navigate in it by using Reveal mode (@kbd{M-x reveal-mode}), a buffer-local minor mode. +@vindex outline-default-state + The @code{outline-default-state} variable controls what headings +will be visible after Outline mode is turned on. If non-@code{nil}, +some headings are initially outlined. If equal to a number, show only +headings up to and including the corresponding level. If equal to +@code{outline-show-all}, all text of buffer is shown. If equal to +@code{outline-show-only-headings}, show only headings, whatever their +level is. If equal to a lambda function or function name, this +function is expected to toggle headings visibility, and will be called +without arguments after the mode is enabled. + @node Outline Views @subsection Viewing One Outline in Multiple Views @@ -1695,17 +1713,17 @@ to work with them. @table @kbd @item C-c C-o Insert @samp{\begin} and @samp{\end} for @LaTeX{} block and position -point on a line between them (@code{tex-latex-block}). +point on a line between them (@code{latex-insert-block}). @item C-c C-e Close the innermost @LaTeX{} block not yet closed -(@code{tex-close-latex-block}). +(@code{latex-close-block}). @end table -@findex tex-latex-block +@findex latex-insert-block @kindex C-c C-o @r{(@LaTeX{} mode)} In @LaTeX{} input, @samp{\begin} and @samp{\end} tags are used to group blocks of text. To insert a block, type @kbd{C-c C-o} -(@code{tex-latex-block}). This prompts for a block type, and inserts +(@code{latex-insert-block}). This prompts for a block type, and inserts the appropriate matching @samp{\begin} and @samp{\end} tags, leaving a blank line between the two and moving point there. @@ -1716,11 +1734,11 @@ completion list contains the standard @LaTeX{} block types. If you want additional block types for completion, customize the list variable @code{latex-block-names}. -@findex tex-close-latex-block +@findex latex-close-block @kindex C-c C-e @r{(@LaTeX{} mode)} @findex latex-electric-env-pair-mode In @LaTeX{} input, @samp{\begin} and @samp{\end} tags must balance. -You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to insert an +You can use @kbd{C-c C-e} (@code{latex-close-block}) to insert an @samp{\end} tag which matches the last unmatched @samp{\begin}. It also indents the @samp{\end} to match the corresponding @samp{\begin}, and inserts a newline after the @samp{\end} tag if point is at the diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi index 93f9c779dbf..887e5c6170f 100644 --- a/doc/emacs/trouble.texi +++ b/doc/emacs/trouble.texi @@ -151,7 +151,6 @@ garbled displays, running out of memory, and crashes and hangs. Emacs. @menu -* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. * Stuck Recursive:: '[...]' in mode line around the parentheses. * Screen Garbled:: Garbage on the screen. * Text Garbled:: Garbage in the text. @@ -159,66 +158,9 @@ Emacs. * Crashing:: What Emacs does when it crashes. * After a Crash:: Recovering editing in an Emacs session that crashed. * Emergency Escape:: What to do if Emacs stops responding. -* Long Lines:: Mitigating slowness due to extremely long lines. +* DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. @end menu -@node DEL Does Not Delete -@subsection If @key{DEL} Fails to Delete -@cindex @key{DEL} vs @key{BACKSPACE} -@cindex @key{BACKSPACE} vs @key{DEL} -@cindex @key{DEL} does not delete - - Every keyboard has a large key, usually labeled @key{BACKSPACE}, -which is ordinarily used to erase the last character that you typed. -In Emacs, this key is supposed to be equivalent to @key{DEL}. - - When Emacs starts up on a graphical display, it determines -automatically which key should be @key{DEL}. In some unusual cases, -Emacs gets the wrong information from the system, and @key{BACKSPACE} -ends up deleting forwards instead of backwards. - - Some keyboards also have a @key{Delete} key, which is ordinarily -used to delete forwards. If this key deletes backward in Emacs, that -too suggests Emacs got the wrong information---but in the opposite -sense. - - On a text terminal, if you find that @key{BACKSPACE} prompts for a -Help command, like @kbd{Control-h}, instead of deleting a character, -it means that key is actually sending the @samp{BS} character. Emacs -ought to be treating @key{BS} as @key{DEL}, but it isn't. - -@findex normal-erase-is-backspace-mode - In all of those cases, the immediate remedy is the same: use the -command @kbd{M-x normal-erase-is-backspace-mode}. This toggles -between the two modes that Emacs supports for handling @key{DEL}, so -if Emacs starts in the wrong mode, this should switch to the right -mode. On a text terminal, if you want to ask for help when @key{BS} -is treated as @key{DEL}, use @key{F1} instead of @kbd{C-h}; @kbd{C-?} -may also work, if it sends character code 127. - - To fix the problem in every Emacs session, put one of the following -lines into your initialization file (@pxref{Init File}). For the -first case above, where @key{BACKSPACE} deletes forwards instead of -backwards, use this line to make @key{BACKSPACE} act as @key{DEL}: - -@lisp -(normal-erase-is-backspace-mode 0) -@end lisp - -@noindent -For the other two cases, use this line: - -@lisp -(normal-erase-is-backspace-mode 1) -@end lisp - -@vindex normal-erase-is-backspace - Another way to fix the problem for every Emacs session is to -customize the variable @code{normal-erase-is-backspace}: the value -@code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is -@key{DEL}, and @code{nil} specifies the other mode. @xref{Easy -Customization}. - @node Stuck Recursive @subsection Recursive Editing Levels @cindex stuck in recursive editing @@ -296,6 +238,31 @@ editing in the same Emacs session. out of memory, because the Buffer Menu needs a fair amount of memory itself, and the reserve supply may not be enough. +@cindex out of memory killer, GNU/Linux +@cindex OOM killer + On GNU/Linux systems, Emacs does not normally get notified about +out-of-memory situations; instead, the OS can kill the Emacs process +when it runs out of memory. This feature is known as the +@dfn{out-of-memory killer}, or @dfn{@acronym{OOM} killer}. When this +behavior is in effect, Emacs is unable to detect the out-of-memory +situation in time, and won't be able to let you save your buffer as +described above. However, it is possible to turn off this behavior of +the OS, and thus allow Emacs a chance to handle the out-of-memory +situation in a more useful manner, before it is killed. To do that, +become the super user, edit the file @code{/etc/sysctl.conf} to +contain the lines shown below, and then invoke the command +@w{@kbd{sysctl -p}} from the shell prompt: + +@example +vm.overcommit_memory=2 +vm.overcommit_ratio=0 +@end example + +@noindent +Please note that the above setting affects all the processes on the +system, and in general the behavior of the system under memory +pressure, not just the Emacs process alone. + @node Crashing @subsection When Emacs Crashes @@ -465,40 +432,62 @@ program. emergency escape---but there are cases where it won't work, when a system call hangs or when Emacs is stuck in a tight loop in C code. -@node Long Lines -@subsection Long Lines -@cindex long lines - - For a variety of reasons (some of which are fundamental to the Emacs -redisplay code and the complex range of possibilities it handles; -others of which are due to modes and features which do not scale well -in unusual circumstances), Emacs can perform poorly when extremely -long lines are present (where ``extremely long'' usually means at -least many thousands of characters). - -@cindex @code{so-long} mode -@findex global-so-long-mode -@vindex so-long-action - A particular problem is that Emacs may ``hang'' for a long time at -the point of visiting a file with extremely long lines. This can be -mitigated by enabling the @file{so-long} library, which detects when a -visited file contains abnormally long lines, and takes steps to -disable features which are liable to cause slowness in that situation. -To enable this library, type @kbd{M-x global-so-long-mode @key{RET}}, -or turn on the @code{global-so-long-mode} in your init file -(@pxref{Init File}), or customize the @code{global-so-long-mode} -option. You can tailor this mode's operation by customizing the -variable @code{so-long-action}. - - The @file{so-long} library can also significantly improve -performance when moving and editing in a buffer with long lines. -Performance is still likely to degrade as you get deeper into the long -lines, but the improvements from using this library can nevertheless -be substantial. - -@findex so-long-commentary - Use @kbd{M-x so-long-commentary} to view the documentation for this -library and learn more about how to enable and configure it. +@node DEL Does Not Delete +@subsection If @key{DEL} Fails to Delete +@cindex @key{DEL} vs @key{BACKSPACE} +@cindex @key{BACKSPACE} vs @key{DEL} +@cindex @key{DEL} does not delete + + Every keyboard has a large key, usually labeled @key{BACKSPACE}, +which is ordinarily used to erase the last character that you typed. +In Emacs, this key is supposed to be equivalent to @key{DEL}. + + When Emacs starts up on a graphical display, it determines +automatically which key should be @key{DEL}. In some unusual cases, +Emacs gets the wrong information from the system, and @key{BACKSPACE} +ends up deleting forwards instead of backwards. + + Some keyboards also have a @key{Delete} key, which is ordinarily +used to delete forwards. If this key deletes backward in Emacs, that +too suggests Emacs got the wrong information---but in the opposite +sense. + + On a text terminal, if you find that @key{BACKSPACE} prompts for a +Help command, like @kbd{Control-h}, instead of deleting a character, +it means that key is actually sending the @samp{BS} character. Emacs +ought to be treating @key{BS} as @key{DEL}, but it isn't. + +@findex normal-erase-is-backspace-mode + In all of those cases, the immediate remedy is the same: use the +command @kbd{M-x normal-erase-is-backspace-mode}. This toggles +between the two modes that Emacs supports for handling @key{DEL}, so +if Emacs starts in the wrong mode, this should switch to the right +mode. On a text terminal, if you want to ask for help when @key{BS} +is treated as @key{DEL}, use @key{F1} instead of @kbd{C-h}; @kbd{C-?} +may also work, if it sends character code 127. + + To fix the problem in every Emacs session, put one of the following +lines into your initialization file (@pxref{Init File}). For the +first case above, where @key{BACKSPACE} deletes forwards instead of +backwards, use this line to make @key{BACKSPACE} act as @key{DEL}: + +@lisp +(normal-erase-is-backspace-mode 0) +@end lisp + +@noindent +For the other two cases, use this line: + +@lisp +(normal-erase-is-backspace-mode 1) +@end lisp + +@vindex normal-erase-is-backspace + Another way to fix the problem for every Emacs session is to +customize the variable @code{normal-erase-is-backspace}: the value +@code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is +@key{DEL}, and @code{nil} specifies the other mode. @xref{Easy +Customization}. @node Bugs @section Reporting Bugs diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi index 2d984f4b926..3ccad507159 100644 --- a/doc/emacs/vc1-xtra.texi +++ b/doc/emacs/vc1-xtra.texi @@ -269,7 +269,7 @@ with the file's version control type. @vindex vc-handled-backends The variable @code{vc-handled-backends} determines which version control systems VC should handle. The default value is @code{(RCS CVS -SVN SCCS SRC Bzr Git Hg Mtn)}, so it contains all the version systems +SVN SCCS SRC Bzr Git Hg)}, so it contains all the version systems that are currently supported. If you want VC to ignore one or more of these systems, exclude its name from the list. To disable VC entirely, set this variable to @code{nil}. diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi index 5a52b0ccb79..4537f8157e8 100644 --- a/doc/emacs/windows.texi +++ b/doc/emacs/windows.texi @@ -442,8 +442,8 @@ selected window write: @example @group -(customize-set-variable - 'display-buffer-alist +(setopt + display-buffer-alist '(("\\*scratch\\*" (display-buffer-same-window)))) @end group @end example @@ -468,8 +468,8 @@ Lisp Reference Manual}) as follows: @example @group -(customize-set-variable - 'display-buffer-base-action +(setopt + display-buffer-base-action '((display-buffer-reuse-window display-buffer-pop-up-frame) (reusable-frames . 0))) @end group @@ -535,8 +535,8 @@ the following form in your initialization file (@pxref{Init File}): @example @group -(customize-set-variable - 'display-buffer-alist +(setopt + display-buffer-alist '(("\\*Completions\\*" display-buffer-below-selected))) @end group @end example @@ -605,7 +605,7 @@ selects the window immediately to the right of the currently selected one, and similarly for the left, up, and down counterparts. @code{windmove-default-keybindings} binds these commands to @kbd{S-right} etc.; doing so disables shift selection for those keys -(@pxref{Shift Selection}). In the same way as keybindings can be +(@pxref{Shift Selection}). In the same way as key bindings can be defined for commands that select windows directionally, you can use @code{windmove-display-default-keybindings} to define keybindings for commands that specify in what direction to display the window for the @@ -613,7 +613,7 @@ buffer that the next command is going to display. Also there is @code{windmove-delete-default-keybindings} to define keybindings for commands that delete windows directionally, and @code{windmove-swap-states-default-keybindings} that defines -keybindings for commands that swap the window contents of the selected +key bindings for commands that swap the window contents of the selected window with the window in the specified direction. The command @kbd{M-x compare-windows} lets you compare the text diff --git a/doc/emacs/xresources.texi b/doc/emacs/xresources.texi index 0c41524f5a9..ab0df3563f5 100644 --- a/doc/emacs/xresources.texi +++ b/doc/emacs/xresources.texi @@ -149,6 +149,15 @@ various X toolkits (GTK+, Lucid, etc.)---we indicate below when this is the case. @table @asis +@item @code{alpha} (class @code{Alpha}) +Sets the @samp{alpha} frame parameter, determining frame transparency +(@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}). + +@item @code{alphaBackground} (class @code{AlphaBackground}) +Sets the @samp{alpha-background} frame parameter, determining background +transparency +(@pxref{Frame Parameters,,, elisp, The Emacs Lisp Reference Manual}). + @item @code{background} (class @code{Background}) Background color (@pxref{Colors}). @@ -332,6 +341,51 @@ Disable use of X input methods (XIM) if @samp{false} or @samp{off}. This is only relevant if your Emacs is built with XIM support. It might be useful to turn off XIM on slow X client/server links. +@item @code{inputStyle} (class @code{InputStyle}) +@cindex inputStyle (X resource) +@cindex input method style, X +This resource controls how preview text generated by X input methods +is displayed. Its value can be on of the following: + +@table @samp +@item callback +Display the contents of the preview text in the current buffer. + +@item offthespot +Display the preview text inside a separate area of the display +provided by Emacs. + +@item overthespot +Display the preview text inside a popup window at the location of +point in the current window. + +@item none +Let the input method decide how to display itself. This is usually +equivalent to @samp{overthespot}, but it might work with more input +methods. + +@item native +Use the toolkit for handling input methods. This is currently +implemented only on GTK. + +@item root +Use some location on display specific to the input method for +displaying the preview text. +@end table + +@item @code{synchronizeResize} (class @code{SynchronizeResize}) +If @samp{off} or @samp{false}, Emacs will not try to tell the window +manager when it has finished redrawing the display in response to a +frame being resized. Otherwise, the window manager will postpone +drawing a frame that was just resized until its contents are updated, +which prevents blank areas of a frame that have not yet been painted +from being displayed. If set to @samp{extended}, it will enable use +of an alternative frame synchronization protocol, which might be +supported by some compositing window managers that don't support the +protocol Emacs uses by default, and causes Emacs to synchronize +display with the monitor refresh rate when a compatible compositing +window manager is in use. + @item @code{verticalScrollBars} (class @code{ScrollBars}) Give frames scroll bars on the left if @samp{left}, on the right if @samp{right}; don't have scroll bars if @samp{off} (@pxref{Scroll Bars}). @@ -395,6 +449,14 @@ Background color. Foreground color for a selected item. @item foreground Foreground color. +@item disabledForeground +Foreground color for a disabled menu item. +@item highlightForeground +Foreground color for a menu item highlighted by the mouse or key +navigation. +@item highlightBackground +Background color for a menu item highlighted by the mouse or key +navigation. @ifnottex @item horizontalSpacing Horizontal spacing in pixels between items. Default is 3. @@ -406,6 +468,12 @@ the associated text. Default is 10. @item shadowThickness Thickness of shadow lines for 3D buttons, arrows, and other graphical elements. Default is 1. +@item borderThickness +Thickness of the external borders of the menu bars and pop-up menus. +Default is 1. +@item cursor +Name of the cursor to use in the menu bars and pop-up menus. Default +is @code{"right_ptr"}. @end ifnottex @item margin Margin of the menu bar, in characters. Default is 1. @@ -549,7 +617,7 @@ those are governed by normal X resources (@pxref{Resources}). The following sections describe how to customize GTK+ resources for Emacs. For details about GTK+ resources, see the GTK+ API document at -@uref{https://developer.gnome.org/gtk2/stable/gtk2-Resource-Files.html}. +@uref{https://developer-old.gnome.org/gtk2/stable/gtk2-Resource-Files.html}. In GTK+ version 3, GTK+ resources have been replaced by a completely different system. The appearance of GTK+ widgets is now determined by @@ -559,7 +627,7 @@ style settings (where @var{theme} is the name of the current GTK+ theme). Therefore, the description of GTK+ resources in this section does not apply to GTK+ 3. For details about the GTK+ 3 styling system, see -@uref{https://developer.gnome.org/gtk3/3.0/GtkCssProvider.html}. +@uref{https://developer-old.gnome.org/gtk3/3.0/GtkCssProvider.html}. @menu * GTK Resource Basics:: Basic usage of GTK+ resources. diff --git a/doc/lispintro/Makefile.in b/doc/lispintro/Makefile.in index d554f3d7a68..42e6d2c1c87 100644 --- a/doc/lispintro/Makefile.in +++ b/doc/lispintro/Makefile.in @@ -63,7 +63,7 @@ ENVADD = \ MAKEINFO="$(MAKEINFO) $(MAKEINFO_OPTS)" DVI_TARGETS = emacs-lisp-intro.dvi -HTML_TARGETS = emacs-lisp-intro.html +HTML_TARGETS = eintr.html PDF_TARGETS = emacs-lisp-intro.pdf PS_TARGETS = emacs-lisp-intro.ps @@ -95,7 +95,7 @@ emacs-lisp-intro.dvi: ${srcs} emacs-lisp-intro.pdf: ${srcs} $(ENVADD) $(TEXI2PDF) $< -emacs-lisp-intro.html: ${srcs} +eintr.html: ${srcs} $(AM_V_GEN)$(MAKEINFO) $(MAKEINFO_OPTS) $(HTML_OPTS) -o $@ $< emacs-lisp-intro.ps: emacs-lisp-intro.dvi diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 860a758e75c..47a5a870fde 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -1,8 +1,6 @@ \input texinfo @c -*- mode: texinfo; coding: utf-8 -*- @comment %**start of header @setfilename ../../info/eintr.info -@c setfilename emacs-lisp-intro.info -@c sethtmlfilename emacs-lisp-intro.html @settitle Programming in Emacs Lisp @include docstyle.texi @syncodeindex vr cp @@ -688,7 +686,7 @@ Your @file{.emacs} File * Text and Auto-fill:: Automatically wrap lines. * Mail Aliases:: Use abbreviations for email addresses. * Indent Tabs Mode:: Don't use tabs with @TeX{} -* Keybindings:: Create some personal keybindings. +* Key Bindings:: Create some personal key bindings. * Keymaps:: More about key binding. * Loading Files:: Load (i.e., evaluate) files automatically. * Autoload:: Make functions available. @@ -3357,7 +3355,7 @@ Both the examples just mentioned work identically to move point forward three sentences. (Since @code{multiply-by-seven} is not bound to a key, it could not be used as an example of key binding.) -(@xref{Keybindings, , Some Keybindings}, to learn how to bind a command +(@xref{Key Bindings, , Some Key Bindings}, to learn how to bind a command to a key.) A @dfn{prefix argument} is passed to an interactive function by typing the @@ -4895,8 +4893,6 @@ result of this, point is placed at the beginning of the buffer and mark is set at the end of the buffer. The whole buffer is, therefore, the region. -@c FIXME: the definition of append-to-buffer has been changed (in -@c 2010-03-30). @node append-to-buffer @section The Definition of @code{append-to-buffer} @findex append-to-buffer @@ -4931,8 +4927,9 @@ buffer to which the text will go, the window it comes from and goes to, and the region that will be copied. @need 1250 -Here is the complete text of the function: +Here is a possible implementation of the function: +@c GNU Emacs 22 @smallexample @group (defun append-to-buffer (buffer start end) @@ -4999,7 +4996,9 @@ name. (The function can handle either.) Since the @code{append-to-buffer} function will be used interactively, the function must have an @code{interactive} expression. (For a review of @code{interactive}, see @ref{Interactive, , Making a -Function Interactive}.) The expression reads as follows: +Function Interactive}.) + +The expression reads as follows: @smallexample @group @@ -5028,7 +5027,7 @@ for true. The first argument to @code{other-buffer}, the exception, is yet another function, @code{current-buffer}. That is not going to be -returned. The second argument is the symbol for true, @code{t}. that +returned. The second argument is the symbol for true, @code{t}. That tells @code{other-buffer} that it may show visible buffers (except in this case, it will not show the current buffer, which makes sense). @@ -5064,33 +5063,6 @@ point and mark. That argument worked fine.) @node append-to-buffer body @subsection The Body of @code{append-to-buffer} -@ignore -in GNU Emacs 22 in /usr/local/src/emacs/lisp/simple.el - -(defun append-to-buffer (buffer start end) - "Append to specified buffer the text of the region. -It is inserted into that buffer before its point. - -When calling from a program, give three arguments: -BUFFER (or buffer name), START and END. -START and END specify the portion of the current buffer to be copied." - (interactive - (list (read-buffer "Append to buffer: " (other-buffer (current-buffer) t)) - (region-beginning) (region-end))) - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore - The body of the @code{append-to-buffer} function begins with @code{let}. As we have seen before (@pxref{let, , @code{let}}), the purpose of a @@ -5109,7 +5081,7 @@ whole by showing a template for @code{append-to-buffer} with the "@var{documentation}@dots{}" (interactive @dots{}) (let ((@var{variable} @var{value})) - @var{body}@dots{}) + @var{body}@dots{})) @end group @end smallexample @@ -5229,19 +5201,39 @@ of filling in the slots of a template: @need 1200 @noindent +@anchor{let* introduced} +@findex let* In this function, the body of the @code{save-excursion} contains only one expression, the @code{let*} expression. You know about a -@code{let} function. The @code{let*} function is different. It has a -@samp{*} in its name. It enables Emacs to set each variable in its -varlist in sequence, one after another. +@code{let} function. The @code{let*} function is different. It +enables Emacs to set each variable in its varlist in sequence, one +after another; such that variables in the latter part of the varlist +can make use of the values to which Emacs set variables earlier in the +varlist. -Its critical feature is that variables later in the varlist can make -use of the values to which Emacs set variables earlier in the varlist. -@xref{fwd-para let, , The @code{let*} expression}. +Looking at the @code{let*} expression in @code{append-to-buffer}: -We will skip functions like @code{let*} and focus on two: the -@code{set-buffer} function and the @code{insert-buffer-substring} -function. +@smallexample +@group +(let* ((append-to (get-buffer-create buffer)) + (windows (get-buffer-window-list append-to t t)) + point) + BODY...) +@end group +@end smallexample + +@noindent +we see that @code{append-to} is bound to the value returned by the +@w{@code{(get-buffer-create buffer)}}. On the next line, +@code{append-to} is used as an argument to +@code{get-buffer-window-list}; this would not be possible with the +@code{let} expression. Note that @code{point} is automatically bound +to @code{nil}, the same way as it would be done in the @code{let} +statement. + +Now let's focus on the functions @code{set-buffer} and +@code{insert-buffer-substring} in the body of the @code{let*} +expression. @need 1250 In the old days, the @code{set-buffer} expression was simply @@ -5259,27 +5251,8 @@ but now it is @end smallexample @noindent -@code{append-to} is bound to @code{(get-buffer-create buffer)} earlier -on in the @code{let*} expression. That extra binding would not be -necessary except for that @code{append-to} is used later in the -varlist as an argument to @code{get-buffer-window-list}. - -@ignore -in GNU Emacs 22 - - (let ((oldbuf (current-buffer))) - (save-excursion - (let* ((append-to (get-buffer-create buffer)) - (windows (get-buffer-window-list append-to t t)) - point) - (set-buffer append-to) - (setq point (point)) - (barf-if-buffer-read-only) - (insert-buffer-substring oldbuf start end) - (dolist (window windows) - (when (= (window-point window) point) - (set-window-point window (point)))))))) -@end ignore +This is because @code{append-to} was bound to @code{(get-buffer-create +buffer)} earlier on in the @code{let*} expression. The @code{append-to-buffer} function definition inserts text from the buffer in which you are currently to a named buffer. It happens that @@ -5376,6 +5349,12 @@ an argument and insert the region into the current buffer. @item mark-whole-buffer Mark the whole buffer as a region. Normally bound to @kbd{C-x h}. +@item let* +Declare a list of variables and give them an initial value; then +evaluate the rest of the expressions in the body of @code{let*}. The +values of the variables can be used to bind ensuing variables in the +list. + @item set-buffer Switch the attention of Emacs to another buffer, but do not change the window being displayed. Used when the program rather than a human is @@ -8771,7 +8750,7 @@ keeps the kill ring from growing too long. It looks like this: The code checks whether the length of the kill ring is greater than the maximum permitted length. This is the value of -@code{kill-ring-max} (which is 60, by default). If the length of the +@code{kill-ring-max} (which is 120, by default). If the length of the kill ring is too long, then this code sets the last element of the kill ring to @code{nil}. It does this by using two functions, @code{nthcdr} and @code{setcdr}. @@ -12877,25 +12856,12 @@ familiar part of this function. @node fwd-para let @unnumberedsubsec The @code{let*} expression -The next line of the @code{forward-paragraph} function begins a -@code{let*} expression. This is different from @code{let}. The -symbol is @code{let*} not @code{let}. - @findex let* -The @code{let*} special form is like @code{let} except that Emacs sets -each variable in sequence, one after another, and variables in the -latter part of the varlist can make use of the values to which Emacs -set variables in the earlier part of the varlist. - -@ignore -( refappend save-excursion, , code save-excursion in code append-to-buffer .) -@end ignore - -(@ref{append save-excursion, , @code{save-excursion} in @code{append-to-buffer}}.) - -In the @code{let*} expression in this function, Emacs binds a total of -seven variables: @code{opoint}, @code{fill-prefix-regexp}, -@code{parstart}, @code{parsep}, @code{sp-parstart}, @code{start}, and +The next line of the @code{forward-paragraph} function begins a +@code{let*} expression (@pxref{let* introduced,,@code{let*} +introduced}), in which Emacs binds a total of seven variables: +@code{opoint}, @code{fill-prefix-regexp}, @code{parstart}, +@code{parsep}, @code{sp-parstart}, @code{start}, and @code{found-start}. The variable @code{parsep} appears twice, first, to remove instances @@ -13692,7 +13658,7 @@ syntax table determines which characters these are." @end ifinfo @need 1000 -If you wish, you can also install this keybinding by evaluating it: +If you wish, you can also install this key binding by evaluating it: @smallexample (global-set-key "\C-c=" '@value{COUNT-WORDS}) @@ -14644,7 +14610,7 @@ almost the same code as for the recursive version of @need 800 @noindent -Let's re-use @kbd{C-c =} as a convenient keybinding: +Let's re-use @kbd{C-c =} as a convenient key binding: @smallexample (global-set-key "\C-c=" 'count-words-defun) @@ -14652,7 +14618,7 @@ Let's re-use @kbd{C-c =} as a convenient keybinding: Now we can try out @code{count-words-defun}: install both @code{count-words-in-defun} and @code{count-words-defun}, and set the -keybinding. Then copy the following to an Emacs Lisp buffer (like, +key binding. Then copy the following to an Emacs Lisp buffer (like, for instance, @file{*scratch*}), place the cursor within the definition, and use the @kbd{C-c =} command. @@ -15166,16 +15132,16 @@ Emacs may produce different results.) @end group @group -(lengths-list-file "./lisp/makesum.el") - @result{} (85 181) +(lengths-list-file "./lisp/hex-util.el") + @result{} (82 71) @end group @group (recursive-lengths-list-many-files '("./lisp/macros.el" "./lisp/mail/mailalias.el" - "./lisp/makesum.el")) - @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 85 181) + "./lisp/hex-util.el")) + @result{} (283 263 480 90 38 32 29 95 178 180 321 218 324 82 71) @end group @end smallexample @@ -15267,27 +15233,13 @@ Sorting the list returned by the @code{recursive-lengths-list-many-files} function is straightforward; it uses the @code{<} function: -@ignore -2006 Oct 29 -In GNU Emacs 22, eval -(progn - (cd "/usr/local/share/emacs/22.0.50/") - (sort - (recursive-lengths-list-many-files - '("./lisp/macros.el" - "./lisp/mail/mailalias.el" - "./lisp/makesum.el")) - '<)) - -@end ignore - @smallexample @group (sort (recursive-lengths-list-many-files '("./lisp/macros.el" "./lisp/mailalias.el" - "./lisp/makesum.el")) + "./lisp/hex-util.el")) '<) @end group @end smallexample @@ -15297,7 +15249,7 @@ In GNU Emacs 22, eval which produces: @smallexample -(29 32 38 85 90 95 178 180 181 218 263 283 321 324 480) +(29 32 38 71 82 90 95 178 180 218 263 283 321 324 480) @end smallexample @noindent @@ -15345,7 +15297,7 @@ as a list that looks like this (but with more elements): @group ("./lisp/macros.el" "./lisp/mail/rmail.el" - "./lisp/makesum.el") + "./lisp/hex-util.el") @end group @end smallexample @@ -15377,7 +15329,10 @@ nil @group (20615 27034 579989 697000) (17905 55681 0 0) -(20615 26327 734791 805000) +(20615 26327 734791 805000)@footnote{If @code{current-time-list} is +@code{nil} the three timestamps are @code{(1351051674579989697 +. 1000000000)}, @code{(1173477761000000000 . 1000000000)}, and +@code{(1351050967734791805 . 1000000000)}, respectively.} 13188 "-rw-r--r--" @end group @@ -15994,7 +15949,7 @@ placing point somewhere in the buffer, typing @kbd{M-:}, typing the and then typing @key{RET}. This causes Emacs to evaluate the expression in the minibuffer, but to use as the value of point the position of point in the @file{*scratch*} buffer. (@kbd{M-:} is the -keybinding for @code{eval-expression}. Also, @code{nil} does not +key binding for @code{eval-expression}. Also, @code{nil} does not appear in the @file{*scratch*} buffer since the expression is evaluated in the minibuffer.) @@ -16561,7 +16516,7 @@ expressions in Emacs Lisp you can change or extend Emacs. * Text and Auto-fill:: Automatically wrap lines. * Mail Aliases:: Use abbreviations for email addresses. * Indent Tabs Mode:: Don't use tabs with @TeX{} -* Keybindings:: Create some personal keybindings. +* Key Bindings:: Create some personal key bindings. * Keymaps:: More about key binding. * Loading Files:: Load (i.e., evaluate) files automatically. * Autoload:: Make functions available. @@ -17105,10 +17060,10 @@ Files'' in @cite{The GNU Emacs Manual}. @end iftex @need 1700 -@node Keybindings -@section Some Keybindings +@node Key Bindings +@section Some Key Bindings -Now for some personal keybindings: +Now for some personal key bindings: @smallexample @group @@ -17130,10 +17085,10 @@ This also shows how to set a key globally, for all modes. @cindex Key setting globally @findex global-set-key The command is @code{global-set-key}. It is followed by the -keybinding. In a @file{.emacs} file, the keybinding is written as +key binding. In a @file{.emacs} file, the keybinding is written as shown: @code{\C-c} stands for Control-C, which means to press the control key and the @kbd{c} key at the same time. The @code{w} means -to press the @kbd{w} key. The keybinding is surrounded by double +to press the @kbd{w} key. The key binding is surrounded by double quotation marks. In documentation, you would write this as @w{@kbd{C-c w}}. (If you were binding a @key{META} key, such as @kbd{M-c}, rather than a @key{CTRL} key, you would write @@ -17147,26 +17102,26 @@ would first try to evaluate the symbol to determine its value. These three things, the double quotation marks, the backslash before the @samp{C}, and the single-quote are necessary parts of -keybinding that I tend to forget. Fortunately, I have come to +key binding that I tend to forget. Fortunately, I have come to remember that I should look at my existing @file{.emacs} file, and adapt what is there. -As for the keybinding itself: @kbd{C-c w}. This combines the prefix +As for the key binding itself: @kbd{C-c w}. This combines the prefix key, @kbd{C-c}, with a single character, in this case, @kbd{w}. This set of keys, @kbd{C-c} followed by a single character, is strictly reserved for individuals' own use. (I call these @dfn{own} keys, since these are for my own use.) You should always be able to create such a -keybinding for your own use without stomping on someone else's -keybinding. If you ever write an extension to Emacs, please avoid +key binding for your own use without stomping on someone else's +key binding. If you ever write an extension to Emacs, please avoid taking any of these keys for public use. Create a key like @kbd{C-c C-w} instead. Otherwise, we will run out of own keys. @need 1250 -Here is another keybinding, with a comment: +Here is another key binding, with a comment: @smallexample @group -;;; Keybinding for 'occur' +;;; Key binding for 'occur' ; I use occur a lot, so let's bind it to a key: (global-set-key "\C-co" 'occur) @end group @@ -17226,8 +17181,8 @@ but moves point into that window. @cindex Rebinding keys Emacs uses @dfn{keymaps} to record which keys call which commands. -When you use @code{global-set-key} to set the keybinding for a single -command in all parts of Emacs, you are specifying the keybinding in +When you use @code{global-set-key} to set the key binding for a single +command in all parts of Emacs, you are specifying the key binding in @code{current-global-map}. Specific modes, such as C mode or Text mode, have their own keymaps; @@ -17482,7 +17437,7 @@ Here is the definition: @end smallexample @need 1250 -Now for the keybinding. +Now for the key binding. Function keys as well as mouse button events and non-@sc{ascii} characters are written within square brackets, without quotation @@ -17776,7 +17731,7 @@ Some systems bind keys unpleasantly. Sometimes, for example, the @key{CTRL} key appears in an awkward spot rather than at the far left of the home row. -Usually, when people fix these sorts of keybindings, they do not +Usually, when people fix these sorts of key bindings, they do not change their @file{~/.emacs} file. Instead, they bind the proper keys on their consoles with the @code{loadkeys} or @code{install-keymap} commands in their boot script and then include @code{xmodmap} commands diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 1fe5a60b356..6a1d125701c 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -541,10 +541,12 @@ file formerly visited. @ref{Text}. @defun buffer-modified-p &optional buffer -This function returns @code{t} if the buffer @var{buffer} has been modified -since it was last read in from a file or saved, or @code{nil} -otherwise. If @var{buffer} is not supplied, the current buffer -is tested. +This function returns non-@code{nil} if @var{buffer} has +been modified since it was last read in from a file or saved, or +@code{nil} otherwise. If @var{buffer} has been auto-saved since the +time it was last modified, this function returns the symbol +@code{autosaved}. If @var{buffer} is @code{nil} or omitted, it +defaults to the current buffer. @end defun @defun set-buffer-modified-p flag @@ -563,8 +565,10 @@ function @code{force-mode-line-update} works by doing this: @end defun @defun restore-buffer-modified-p flag -Like @code{set-buffer-modified-p}, but does not force redisplay -of mode lines. +Like @code{set-buffer-modified-p}, but does not force redisplay of +mode lines. This function also allows @var{flag}'s value to be +the symbol @code{autosaved}, which marks the buffer as modified and +auto-saved after the last modification. @end defun @deffn Command not-modified &optional arg @@ -953,15 +957,67 @@ with a @code{nil} @var{norecord} argument since this may lead to infinite recursion. @end defvar +@defun buffer-match-p condition buffer-or-name &optional arg +This function checks if a buffer designated by @code{buffer-or-name} +satisfies a @code{condition}. Optional third argument @var{arg} is +passed to the predicate function in @var{condition}. A condition can +be one of the following: +@itemize @bullet{} +@item +A string, interpreted as a regular expression. The buffer +satisfies the condition if the regular expression matches the buffer +name. +@item +A predicate function, which should return non-@code{nil} if the buffer +matches. If the function expects one argument, it is called with +@var{buffer-or-name} as the argument; if it expects 2 arguments, the +first argument is @var{buffer-or-name} and the second is @var{arg} +(or @code{nil} if @var{arg} is omitted). +@item +A cons-cell @code{(@var{oper} . @var{expr})} where @var{oper} is one +of +@table @code +@item not +Satisfied if @var{expr} doesn't satisfy @code{buffer-match-p} with +the same buffer and @code{arg}. +@item or +Satisfied if @var{expr} is a list and @emph{any} condition in +@var{expr} satisfies @code{buffer-match-p}, with the same buffer and +@code{arg}. +@item and +Satisfied if @var{expr} is a list and @emph{all} conditions in +@var{expr} satisfy @code{buffer-match-p}, with the same buffer and +@code{arg}. +@item derived-mode +Satisfied if the buffer's major mode derives from @var{expr}. +@item major-mode +Satisfied if the buffer's major mode is equal to @var{expr}. Prefer +using @code{derived-mode} instead when both can work. +@end table +@item t +Satisfied by any buffer. A convenient alternative to @code{""} (empty +string), @code{(and)} (empty conjunction) or @code{always}. +@end itemize +@end defun + +@defun match-buffers condition &optional buffer-list arg +This function returns a list of all buffers that satisfy a +@code{condition}, as defined for @code{buffer-match-p}. By default +all buffers are considered, but this can be restricted via the second +optional @code{buffer-list} argument. Optional third argument +@var{arg} will be used by @var{condition} in the same way as +@code{buffer-match-p} does. +@end defun + @node Creating Buffers @section Creating Buffers @cindex creating buffers @cindex buffers, creating This section describes the two primitives for creating buffers. -@code{get-buffer-create} creates a buffer if it finds no existing buffer -with the specified name; @code{generate-new-buffer} always creates a new -buffer and gives it a unique name. +@code{get-buffer-create} creates a buffer if it finds no existing +buffer with the specified name; @code{generate-new-buffer} always +creates a new buffer and gives it a unique name. Both functions accept an optional argument @var{inhibit-buffer-hooks}. If it is non-@code{nil}, the buffer they create does not run the hooks diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index d948af6b4f1..ede1c4d7622 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -312,6 +312,25 @@ If @var{function} is an interactively callable function specifies how to compute its arguments. Otherwise, the value is @code{nil}. If @var{function} is a symbol, its function definition is used. +When called on an OClosure, the work is delegated to the generic +function @code{oclosure-interactive-form}. +@end defun + +@defun oclosure-interactive-form function +Just like @code{interactive-form}, this function takes a command and +returns its interactive form. The difference is that it is a generic +function and it is only called when @var{function} is an OClosure. +The purpose is to make it possible for some OClosure types to compute +their interactive forms dynamically instead of carrying it in one of +their slots. + +This is used for example for @code{kmacro} functions in order to +reduce their memory size, since they all share the same interactive +form. It is also used for @code{advice} functions, where the +interactive form is computed from the interactive forms of its +components, so as to make this computation more lazily and to +correctly adjust the interactive form when one of its component's +is redefined. @end defun @node Interactive Codes @@ -424,9 +443,9 @@ specification. If the key sequence that invoked the command has and @acronym{ASCII} characters, do not count where @samp{e} is concerned. @item f -A file name of an existing file (@pxref{File Names}). The default -directory is @code{default-directory}. Existing, Completion, Default, -Prompt. +A file name of an existing file (@pxref{File Names}). @xref{Reading +File Names}, for details about default values. Existing, Completion, +Default, Prompt. @item F A file name. The file need not exist. Completion, Default, Prompt. @@ -451,11 +470,11 @@ reads and discards the following up-event. You can get access to that up-event with the @samp{U} code character. This kind of input is used by commands such as @code{describe-key} and -@code{global-set-key}. +@code{keymap-global-set}. @item K A key sequence on a form that can be used as input to functions like -@code{define-key}. This works like @samp{k}, except that it +@code{keymap-set}. This works like @samp{k}, except that it suppresses, for the last input event in the key sequence, the conversions that are normally used (when necessary) to convert an undefined key into a defined one (@pxref{Key Sequence Input}), so this @@ -682,11 +701,6 @@ different ways (e.g., @code{eww-open-in-new-buffer} and mode-specific, as they can be issued by the user from pretty much any context. -Note that specifying command modes is not supported in native-compiled -functions in Emacs 28.1 (but this is fixed in later Emacs versions). -This means that @code{read-extended-command-predicate} isn't supported -in native-compile builds, either. - @node Generic Commands @subsection Select among Command Alternatives @cindex generic commands @@ -883,6 +897,10 @@ keymaps. This command is the normal definition of @kbd{M-S-x} (that's ``meta shift x''). @end deffn +Both these commands prompt for a command name, but with different +completion rules. You can toggle between these two modes by using the +@kbd{M-S-x} command while being prompted. + @node Distinguish Interactive @section Distinguish Interactive Calls @cindex distinguish interactive calls @@ -1132,6 +1150,96 @@ frame, the value is the frame to which the event was redirected. If the last event came from a keyboard macro, the value is @code{macro}. @end defvar +@cindex input devices +@cindex device names +Input events must come from somewhere; sometimes, that is a keyboard +macro, a signal, or `unread-command-events', but it is usually a +physical input device connected to a computer that is controlled by +the user. Those devices are referred to as @dfn{input devices}, and +Emacs associates each input event with the input device from which it +originated. They are identified by a name that is unique to each +input device. + +The ability to determine the precise input device used depends on the +details of each system. When that information is unavailable, Emacs +reports keyboard events as originating from the @samp{"Virtual core +keyboard"}, and other events as originating from the @samp{"Virtual +core pointer"}. (These values are used on every platform because the +X server reports them when detailed device information is not known.) + +@defvar last-event-device +This variable records the name of the input device from which the last +input event read was generated. It is @code{nil} if no such device +exists, i.e., the last input event was read from +@code{unread-command-events}, or it came from a keyboard macro. + +When the X Input Extension is being used on X Windows, the device name +is a string that is unique to each physical keyboard, pointing device +and touchscreen attached to the X server. Otherwise, it is either the +string @samp{"Virtual core pointer"} or @samp{"Virtual core +keyboard"}, depending on whether the event was generated by a pointing +device (such as a mouse) or a keyboard. +@end defvar + +@defun device-class frame name +There are various different types of devices, which can be determined +from their names. This function can be used to determined the correct +type of the device @var{name} for an event originating from +@var{frame}. + +The return value is one of the following symbols (``device classes''): + +@table @code +@item core-keyboard +The core keyboard; this is means the device is a keyboard-like device, +but no other characteristics are unknown. + +@item core-pointer +The core pointer; this means the device is a pointing device, but no +other characteristics are known. + +@item mouse +A computer mouse. + +@item trackpoint +A trackpoint or joystick (or other similar control.) + +@item eraser +The other end of a stylus on a graphics tablet, or a standalone +eraser. + +@item pen +The pointed end of a pen on a graphics tablet, a stylus, or some other +similar device. + +@item puck +A device that looks like a computer mouse, but reports absolute +coordinates relative to some other surface. + +@item power-button +A power button or volume button (or other similar control.) + +@item keyboard +A computer keyboard. + +@item touchscreen +A computer touchpad. + +@item pad +A collection of sensitive buttons, rings, and strips commonly found +around a drawing tablet. + +@item touchpad +An indirect touch device such as a touchpad. + +@item piano +A musical instrument such as an electronic keyboard. + +@item test +A device used by the XTEST extension to report input. +@end table +@end defun + @node Adjusting Point @section Adjusting Point After Commands @cindex adjusting point @@ -1192,7 +1300,9 @@ intended by Lisp code to be used as an event. * Button-Down Events:: A button was pushed and not yet released. * Repeat Events:: Double and triple click (or drag, or down). * Motion Events:: Just moving the mouse, not pushing a button. +* Touchscreen Events:: Tapping and moving fingers on a touchscreen. * Focus Events:: Moving the mouse between frames. +* Xwidget Events:: Events generated by xwidgets. * Misc Events:: Other events the system can generate. * Event Examples:: Examples of the lists for mouse events. * Classifying Events:: Finding the modifier keys in an event symbol. @@ -1331,12 +1441,9 @@ actually treated as the meta key, not this.) It is best to avoid mentioning specific bit numbers in your program. To test the modifier bits of a character, use the function @code{event-modifiers} (@pxref{Classifying Events}). When making key -bindings, you can use the read syntax for characters with modifier bits -(@samp{\C-}, @samp{\M-}, and so on). For making key bindings with -@code{define-key}, you can use lists such as @code{(control hyper ?x)} to -specify the characters (@pxref{Changing Key Bindings}). The function -@code{event-convert-list} converts such a list into an event type -(@pxref{Classifying Events}). +bindings with @code{keymap-set}, you specify these events using +strings like @samp{C-H-x} instead (for ``control hyper x'') +(@pxref{Changing Key Bindings}). @node Function Keys @subsection Function Keys @@ -1854,6 +1961,59 @@ small movements. Otherwise, motion events are not generated as long as the mouse cursor remains pointing to the same glyph in the text. @end defvar +@node Touchscreen Events +@subsection Touchscreen Events +@cindex touchscreen events +@cindex support for touchscreens + +Some window systems provide support for input devices that react to +the user's touching the screen and moving fingers while touching the +screen. These input devices are known as touchscreens, and Emacs +reports the events they generate as @dfn{touchscreen events}. + +Most individual events generated by a touchscreen only have meaning as +part of a larger sequence of other events: for instance, the simple +operation of tapping the touchscreen involves the user placing and +raising a finger on the touchscreen, and swiping the display to +scroll it involves placing a finger, moving it many times upwards or +downwards, and then raising the finger. + +@cindex touch point, in touchscreen events +While a simplistic model consisting of one finger is adequate for taps +and scrolling, more complicated gestures require support for keeping +track of multiple fingers, where the position of each finger is +represented by a @dfn{touch point}. For example, a ``pinch to zoom'' +gesture might consist of the user placing two fingers and moving them +individually in opposite directions, where the distance between the +positions of their individual points determine the amount by which to +zoom the display, and the center of an imaginary line between those +positions determines where to pan the display after zooming. + +The low-level touchscreen events described below can be used to +implement all the touch sequences described above. In those events, +each point is represented by a cons of an arbitrary number identifying +the point and a mouse position list (@pxref{Click Events}) specifying +the position of the finger when the event occurred. + +@table @code +@cindex @code{touchscreen-begin} event +@item (touchscreen-begin @var{point}) +This event is sent when @var{point} is created by the user pressing a +finger against the touchscreen. + +@cindex @code{touchscreen-update} event +@item (touchscreen-update @var{points}) +This event is sent when a point on the touchscreen has changed +position. @var{points} is a list of touch points containing the +up-to-date positions of each touch point currently on the touchscreen. + +@cindex @code{touchscreen-end} event +@item (touchscreen-end @var{point}) +This event is sent when @var{point} is no longer present on the +display, because another program took the grab, or because the user +raised the finger from the touchscreen. +@end table + @node Focus Events @subsection Focus Events @cindex focus event @@ -1890,6 +2050,100 @@ sequence---that is, after a prefix key---then Emacs reorders the events so that the focus event comes either before or after the multi-event key sequence, and not within it. +@node Xwidget Events +@subsection Xwidget events + +Xwidgets (@pxref{Xwidgets}) can send events to update Lisp programs on +their status. These events are dubbed @code{xwidget-events}, and +contain various data describing the nature of the change. + +@table @code +@cindex @code{xwidget-event} event +@item (xwidget-event @var{kind} @var{xwidget} @var{arg}) +This event is sent whenever some kind of update occurs in +@var{xwidget}. There are several types of updates, identified by +their @var{kind}. + +@cindex xwidget callbacks +It is a special event (@pxref{Special Events}), which should be +handled by adding a callback to an xwidget that is called whenever an +xwidget event for @var{xwidget} is received. + +You can add a callback by setting the @code{callback} of an xwidget's +property list, which should be a function that accepts @var{xwidget} +and @var{kind} as arguments. + +@table @code +@cindex @code{load-changed} xwidget event +@item load-changed +This xwidget event indicates that the @var{xwidget} has reached a +particular point of the page-loading process. When these events are +sent, @var{arg} will contain a string that further describes the status +of the widget: + +@table @samp +@cindex @samp{load-started} in xwidgets +@item load-started +This means the widget has begun a page-loading operation. + +@cindex @samp{load-finished} in xwidgets +@item load-finished +This means the @var{xwidget} has finished processing whatever +page-loading operation that it was previously performing. + +@cindex @samp{load-redirected} in xwidgets +@item load-redirected +This means the @var{xwidget} has encountered and followed a redirect +during the page-loading operation. + +@cindex @samp{load-committed} in xwidgets +@item load-committed +This means the @var{xwidget} has committed to a given URL during the +page-loading operation, i.e.@: the URL is the final URL that will be +rendered by @var{xwidget} during the current page-loading operation. +@end table + +@cindex @code{download-callback} xwidget events +@item download-callback +This event indicates that a download of some kind has been completed. +@end table + +In the above events, there can be arguments after @var{arg}, which +itself indicates the URL from which the download file was retrieved: +the first argument after @var{arg} indicates the MIME type of the +download, as a string, while the second argument contains the full +file name of the downloaded file. + +@table @code +@cindex @code{download-started} xwidget events +@item download-started +This event indicates that a download has been started. In these +events, @var{arg} contains the URL of the file that is currently being +downloaded. + +@cindex @code{javascript-callback} xwidget events +@item javascript-callback +This event contains JavaScript callback data. These events are used +internally by @code{xwidget-webkit-execute-script}. +@end table + +@cindex @code{xwidget-display-event} event +@item (xwidget-display-event @var{xwidget} @var{source}) +This event is sent whenever an xwidget requests that another xwidget +be displayed. @var{xwidget} is the xwidget that should be displayed, +and @var{source} is the xwidget that asked to display @var{xwidget}. + +It is also a special event which should be handled through callbacks. +You can add such a callback by setting the @code{display-callback} of +@var{source}'s property list, which should be a function that accepts +@var{xwidget} and @var{source} as arguments. + +@var{xwidget}'s buffer will be set to a temporary buffer. When +displaying the widget, care should be taken to replace the buffer with +the buffer in which the xwidget will be displayed, using +@code{set-xwidget-buffer} (@pxref{Xwidgets}). +@end table + @node Misc Events @subsection Miscellaneous System Events @@ -1917,22 +2171,128 @@ This kind of event indicates that the user deiconified @var{frame} using the window manager. Its standard definition is @code{ignore}; since the frame has already been made visible, Emacs has no work to do. +@cindex @code{touch-end} event +@item (touch-end (@var{position})) +This kind of event indicates that the user's finger moved off the +mouse wheel or the touchpad. The @var{position} element is a mouse +position list (@pxref{Click Events}), specifying the position of the +mouse cursor when the finger moved off the mouse wheel. + @cindex @code{wheel-up} event @cindex @code{wheel-down} event -@item (wheel-up @var{position}) -@itemx (wheel-down @var{position}) +@item (wheel-up @var{position} @var{clicks} @var{lines} @var{pixel-delta}) +@itemx (wheel-down @var{position} @var{clicks} @var{lines} @var{pixel-delta}) These kinds of event are generated by moving a mouse wheel. The @var{position} element is a mouse position list (@pxref{Click Events}), specifying the position of the mouse cursor when the event occurred. +@var{clicks}, if present, is the number of times that the wheel was +moved in quick succession. @xref{Repeat Events}. @var{lines}, if +present and not @code{nil}, is the number of screen lines that should +be scrolled. @var{pixel-delta}, if present, is a cons cell of the +form @w{@code{(@var{x} . @var{y})}}, where @var{x} and @var{y} are the +numbers of pixels by which to scroll in each axis, a.k.a.@: +@dfn{pixelwise deltas}. + +@cindex pixel-resolution wheel events +You can use these @var{x} and @var{y} pixelwise deltas to determine +how much the mouse wheel has actually moved at pixel resolution. For +example, the pixelwise deltas could be used to scroll the display at +pixel resolution, exactly according to the user's turning the mouse +wheel. + @vindex mouse-wheel-up-event @vindex mouse-wheel-down-event -This kind of event is generated only on some kinds of systems. On some -systems, @code{mouse-4} and @code{mouse-5} are used instead. For -portable code, use the variables @code{mouse-wheel-up-event} and -@code{mouse-wheel-down-event} defined in @file{mwheel.el} to determine -what event types to expect for the mouse wheel. +This kind of event is generated only on some kinds of systems. On +some systems, @code{mouse-4} and @code{mouse-5} are used instead. For +portable code, use the variables @code{mouse-wheel-up-event}, +@code{mouse-wheel-up-alternate-event}, @code{mouse-wheel-down-event} +and @code{mouse-wheel-down-alternate-event} defined in +@file{mwheel.el} to determine what event types to expect for the mouse +wheel. + +@vindex mouse-wheel-left-event +@vindex mouse-wheel-right-event +Similarly, some mice can generate @code{mouse-wheel-left-event} and +@code{mouse-wheel-right-event} and can be used to scroll if +@code{mouse-wheel-tilt-scroll} is non-@code{nil}. However, some mice +also generate other events at the same time as they're generating +these scroll events which may get in the way. The way to fix this is +generally to unbind these events (for instance, @code{mouse-6} or +@code{mouse-7}, but this is very hardware and operating system +dependent). + +@cindex @code{pinch} event +@item (pinch @var{position} @var{dx} @var{dy} @var{scale} @var{angle}) +This kind of event is generated by the user performing a ``pinch'' +gesture by placing two fingers on a touchpad and moving them towards +or away from each other. @var{position} is a mouse position list +(@pxref{Click Events}) that provides the position of the mouse pointer +when the event occurred, @var{dx} is the change in the horizontal +distance between the fingers since the last event in the same sequence, +@var{dy} is the vertical movement of the fingers since the last event +in the same sequence, @var{scale} is the ratio of the current distance +between the fingers to that distance at the start of the sequence, and +@var{angle} is the angular difference in degrees between the direction +of the line connecting the fingers in this event and the direction of +that line in the last event of the same sequence. + +As pinch events are only sent at the beginning or during a pinch +sequence, they do not report gestures where the user moves two fingers +on a touchpad in a rotating fashion without pinching the fingers. + +All arguments after @var{position} are floating point numbers. + +This event is usually sent as part of a sequence, which begins with +the user placing two fingers on the touchpad, and ends with the user +removing those fingers. @var{dx}, @var{dy}, and @var{angle} will be +@code{0.0} in the first event of a sequence; subsequent events will +report non-zero values for these members of the event structure. + +@var{dx} and @var{dy} are reported in imaginary relative units, in +which @code{1.0} is the width and height of the touchpad +respectively. They are usually interpreted as being relative to the +size of the object beneath the gesture: image, window, etc. + +@cindex @code{preedit-text} event +@item (preedit-text @var{arg}) +This event is sent when a system input method tells Emacs to display +some text to indicate to the user what will be inserted. The contents +of @var{arg} are dependent on the window system being used. + +On X, @var{arg} is a string describing some text to place behind the +cursor. It can be @code{nil}, which means to remove any text +previously displayed. + +On PGTK frames (@pxref{Frames}), @var{arg} is a list of strings with +information about their color and underline attributes. It has the +following form: + +@example +@group + ((@var{string1} + (ul . @var{underline-color}) + (bg . @var{background-color}) + (fg . @var{foreground-color})) + (@var{string2} + (ul . @var{underline-color}) + (bg . @var{background-color}) + (fg . @var{foreground-color})) + @dots{} + ) +@end group +@end example + +Color information can be omitted, leaving just the text of the +strings. @var{underline-color} can be @code{t}, meaning underlined +text with default underline color, or it can be a string, the name of +the color to draw the underline. + +This is a special event (@pxref{Special Events}), which normally +should not be bound by the user to any command. Emacs will typically +display the text contained in the event in an overlay behind point +when it is received. @cindex @code{drag-n-drop} event @item (drag-n-drop @var{position} @var{files}) @@ -1985,7 +2345,7 @@ example: (interactive) (message "Caught signal %S" last-input-event)) -(define-key special-event-map [sigusr1] 'sigusr-handler) +(keymap-set special-event-map "<sigusr1>" 'sigusr-handler) @end smallexample To test the signal handler, you can make Emacs send a signal to itself: @@ -2086,7 +2446,7 @@ bind it to the @code{signal usr1} event sequence: (defun usr1-handler () (interactive) (message "Got USR1 signal")) -(global-set-key [signal usr1] 'usr1-handler) +(keymap-global-set "<signal> <usr1>" 'usr1-handler) @end smallexample @node Classifying Events @@ -2191,21 +2551,6 @@ This function returns non-@code{nil} if @var{object} is a mouse movement event. @xref{Motion Events}. @end defun -@defun event-convert-list list -This function converts a list of modifier names and a basic event type -to an event type which specifies all of them. The basic event type -must be the last element of the list. For example, - -@example -(event-convert-list '(control ?a)) - @result{} 1 -(event-convert-list '(control meta ?a)) - @result{} -134217727 -(event-convert-list '(control super f1)) - @result{} C-s-f1 -@end example -@end defun - @node Accessing Mouse @subsection Accessing Mouse Events @cindex mouse events, data in @@ -2285,7 +2630,7 @@ POSITION is assumed to lie in a window text area." @end example @end defun -@defun posn-col-row position +@defun posn-col-row position &optional use-window This function returns a cons cell @w{@code{(@var{col} . @var{row})}}, containing the estimated column and row corresponding to buffer position described by @var{position}. The return value is given in @@ -2293,7 +2638,11 @@ units of the frame's default character width and default line height (including spacing), as computed from the @var{x} and @var{y} values corresponding to @var{position}. (So, if the actual characters have non-default sizes, the actual row and column may differ from these -computed values.) +computed values.) If the optional @var{window} argument is +non-@code{nil}, use the default character width in the window +indicated by @var{position} instead of the frame. (This makes a +difference if that window is showing a buffer with a non-default +zooming level, for instance.) Note that @var{row} is counted from the top of the text area. If the window given by @var{position} possesses a header line (@pxref{Header @@ -2352,7 +2701,10 @@ the character at that position. @cindex timestamp of a mouse event @defun posn-timestamp position Return the timestamp in @var{position}. This is the time at which the -event occurred, in milliseconds. +event occurred, in milliseconds. Such a timestamp is reported +relative to an arbitrary starting time that varies according to the +window system in use. On the X Window System, for example, it is the +number of milliseconds since the X server was started. @end defun These functions compute a position list given particular buffer @@ -2425,25 +2777,14 @@ characters in a string is a complex matter, for reasons of historical compatibility, and it is not always possible. We recommend that new programs avoid dealing with these complexities -by not storing keyboard events in strings. Here is how to do that: - -@itemize @bullet -@item -Use vectors instead of strings for key sequences, when you plan to use -them for anything other than as arguments to @code{lookup-key} and -@code{define-key}. For example, you can use -@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and -@code{this-command-keys-vector} instead of @code{this-command-keys}. +by not storing keyboard events in strings containing control +characters or the like, but instead store them in the common Emacs +format as understood by @code{key-valid-p}. -@item -Use vectors to write key sequence constants containing meta characters, -even when passing them directly to @code{define-key}. - -@item -When you have to look at the contents of a key sequence that might be a -string, use @code{listify-key-sequence} (@pxref{Event Input Misc}) -first, to convert it to a list. -@end itemize + If you read a key sequence with @code{read-key-sequence-vector} (or +@code{read-key-sequence}), or access a key sequence with +@code{this-command-keys-vector} (or @code{this-command-keys}), you can +transform this to the recommended format by using @code{key-description}. The complexities stem from the modifier bits that keyboard input characters can include. Aside from the Meta modifier, none of these @@ -2635,10 +2976,14 @@ returns the key sequence as a vector, never as a string. @cindex upper case key sequence @cindex downcasing in @code{lookup-key} @cindex shift-translation +@vindex translate-upper-case-key-bindings If an input character is upper-case (or has the shift modifier) and has no key binding, but its lower-case equivalent has one, then -@code{read-key-sequence} converts the character to lower case. Note -that @code{lookup-key} does not perform case conversion in this way. +@code{read-key-sequence} converts the character to lower case. (This +behavior can be disabled by setting the +@code{translate-upper-case-key-bindings} user option to @code{nil}.) +Note that @code{lookup-key} does not perform case conversion in this +way. @vindex this-command-keys-shift-translated When reading input results in such a @dfn{shift-translation}, Emacs @@ -2871,7 +3216,7 @@ causes it to evaluate @code{help-form} and display the result. It then continues to wait for a valid input character, or keyboard-quit. @end defun -@defun read-multiple-choice prompt choices &optional help-string +@defun read-multiple-choice prompt choices &optional help-string show-help long-form Ask user a multiple choice question. @var{prompt} should be a string that will be displayed as the prompt. @@ -2886,6 +3231,15 @@ a string with a more detailed description of all choices. It will be displayed in a help buffer instead of the default auto-generated description when the user types @kbd{?}. +If optional argument @var{show-help} is non-@code{nil}, the help +buffer will be displayed immediately, before any user input. If it is +a string, use it as the name of the help buffer. + +If optional argument @var{long-form} is non-@code{nil}, the user +will have to type in long-form answers (using @code{completing-read}) +instead of hitting a single key. The answers must be among the second +elements of the values in the @var{choices} list. + The return value is the matching value from @var{choices}. @lisp @@ -2956,7 +3310,7 @@ supplied to input methods (@pxref{Input Methods}). Use if you want to translate characters after input methods operate. @end defvar -@defun keyboard-translate from to +@defun key-translate from to This function modifies @code{keyboard-translate-table} to translate character code @var{from} into character code @var{to}. It creates the keyboard translate table if necessary. @@ -2967,12 +3321,12 @@ make @kbd{C-x}, @kbd{C-c} and @kbd{C-v} perform the cut, copy and paste operations: @example -(keyboard-translate ?\C-x 'control-x) -(keyboard-translate ?\C-c 'control-c) -(keyboard-translate ?\C-v 'control-v) -(global-set-key [control-x] 'kill-region) -(global-set-key [control-c] 'kill-ring-save) -(global-set-key [control-v] 'yank) +(key-translate "C-x" "<control-x>") +(key-translate "C-c" "<control-c>") +(key-translate "C-v" "<control-v>") +(keymap-global-set "<control-x>" 'kill-region) +(keymap-global-set "<control-c>" 'kill-ring-save) +(keymap-global-set "<control-v>" 'yank) @end example @noindent @@ -3729,6 +4083,15 @@ what happens when a disabled command is invoked interactively. Disabling a command has no effect on calling it as a function from Lisp programs. +@findex command-query + The value of the @code{disabled} property can also be a list where +the first element is the symbol @code{query}. In that case, the user +will be queried whether to execute the command. The second element in +the list should be @code{nil} or non-@code{nil} to say whether to use +@code{y-or-n-p} or @code{yes-or-no-p}, respectively, and the third +element is the question to use. The @code{command-query} convenience +function should be used to enable querying for a command. + @deffn Command enable-command command Allow @var{command} (a symbol) to be executed without special confirmation from now on, and alter the user's init file (@pxref{Init diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index f336753a6c3..60fc11a22ed 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -61,7 +61,7 @@ Here is an example: @group (silly-loop 50000000) -@result{} 10.235304117202759 +@result{} 5.200886011123657 @end group @group @@ -71,12 +71,12 @@ Here is an example: @group (silly-loop 50000000) -@result{} 3.705854892730713 +@result{} 0.6239290237426758 @end group @end example - In this example, the interpreted code required 10 seconds to run, -whereas the byte-compiled code required less than 4 seconds. These + In this example, the interpreted code required more than 5 seconds to run, +whereas the byte-compiled code required less than 1 second. These results are representative, but actual results may vary. @node Compilation Functions @@ -135,10 +135,10 @@ definition of @var{symbol} (@pxref{Byte-Code Objects}). @group (byte-compile 'factorial) @result{} -#[(integer) - "^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207" - [integer 1 * factorial] - 4 "Compute factorial of INTEGER."] +#[257 + "\211\300U\203^H^@@\300\207\211\301^BS!_\207" + [1 factorial] 4 + "Compute factorial of INTEGER.\n\n(fn INTEGER)"] @end group @end example @@ -688,11 +688,11 @@ Lisp source; these do not appear in the output of @code{disassemble}. (disassemble 'factorial) @print{} byte-code for factorial: doc: Compute factorial of an integer. - args: (integer) + args: (arg1) @end group @group -0 varref integer ; @r{Get the value of @code{integer} and} +0 dup ; @r{Get the value of @code{integer} and} ; @r{push it onto the stack.} 1 constant 1 ; @r{Push 1 onto stack.} @end group @@ -707,9 +707,9 @@ Lisp source; these do not appear in the output of @code{disassemble}. 7 return ; @r{Return the top element of the stack.} @end group @group -8:1 varref integer ; @r{Push value of @code{integer} onto stack.} +8:1 dup ; @r{Push value of @code{integer} onto stack.} 9 constant factorial ; @r{Push @code{factorial} onto stack.} -10 varref integer ; @r{Push value of @code{integer} onto stack.} +10 stack-ref 2 ; @r{Push value of @code{integer} onto stack.} 11 sub1 ; @r{Pop @code{integer}, decrement value,} ; @r{push new value onto stack.} 12 call 1 ; @r{Call function @code{factorial} using first} @@ -717,9 +717,9 @@ Lisp source; these do not appear in the output of @code{disassemble}. ; @r{push returned value onto stack.} @end group @group -13 mult ; @r{Pop top two values off stack, multiply} +13 mult ; @r{Pop top two values off stack, multiply} ; @r{them, and push result onto stack.} -14 return ; @r{Return the top element of the stack.} +14 return ; @r{Return the top element of the stack.} @end group @end example @@ -740,7 +740,7 @@ The @code{silly-loop} function is somewhat more complex: (disassemble 'silly-loop) @print{} byte-code for silly-loop: doc: Return time before and after N iterations of a loop. - args: (n) + args: (arg1) @end group @group @@ -749,24 +749,21 @@ The @code{silly-loop} function is somewhat more complex: @end group @group 1 call 0 ; @r{Call @code{current-time-string} with no} - ; @r{argument, push result onto stack.} + ; @r{argument, push result onto stack as @code{t1}.} @end group @group -2 varbind t1 ; @r{Pop stack and bind @code{t1} to popped value.} -@end group -@group -3:1 varref n ; @r{Get value of @code{n} from the environment} +2:1 stack-ref 1 ; @r{Get value of the argument @code{n}} ; @r{and push the value on the stack.} -4 sub1 ; @r{Subtract 1 from top of stack.} +3 sub1 ; @r{Subtract 1 from top of stack.} @end group @group -5 dup ; @r{Duplicate top of stack; i.e., copy the top} +4 dup ; @r{Duplicate top of stack; i.e., copy the top} ; @r{of the stack and push copy onto stack.} -6 varset n ; @r{Pop the top of the stack,} - ; @r{and bind @code{n} to the value.} +5 stack-set 3 ; @r{Pop the top of the stack,} + ; @r{and set @code{n} to the value.} -;; @r{(In effect, the sequence @code{dup varset} copies the top of the stack} -;; @r{into the value of @code{n} without popping it.)} +;; @r{(In effect, the sequence @code{dup stack-set} copies the top of} +;; @r{the stack into the value of @code{n} without popping it.)} @end group @group @@ -781,16 +778,15 @@ The @code{silly-loop} function is somewhat more complex: ; @r{else continue.} @end group @group -12 varref t1 ; @r{Push value of @code{t1} onto stack.} +12 dup ; @r{Push value of @code{t1} onto stack.} 13 constant current-time-string ; @r{Push @code{current-time-string}} ; @r{onto the top of the stack.} 14 call 0 ; @r{Call @code{current-time-string} again.} @end group @group -15 unbind 1 ; @r{Unbind @code{t1} in local environment.} -16 list2 ; @r{Pop top two elements off stack, create a} +15 list2 ; @r{Pop top two elements off stack, create a} ; @r{list of them, and push it onto stack.} -17 return ; @r{Return value of the top of stack.} +16 return ; @r{Return value of the top of stack.} @end group @end example diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 34653d70565..d4520ebdee5 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -1286,6 +1286,15 @@ bindings that can then be used inside @var{body}. The variable bindings are produced by destructuring binding of elements of @var{pattern} to the values of the corresponding elements of the evaluated @var{exp}. + +Here's a trivial example: + +@example +(pcase-let ((`(,major ,minor) + (split-string "image/png" "/"))) + minor) + @result{} "png" +@end example @end defmac @defmac pcase-let* bindings body@dots{} @@ -1320,6 +1329,20 @@ Assign values to variables in a @code{setq} form, destructuring each @var{value} according to its respective @var{pattern}. @end defmac +@defmac pcase-lambda lambda-list &rest body +This is like @code{lambda}, but allows each argument to be a pattern. +For instance, here's a simple function that takes a cons cell as the +argument: + +@example +(setq fun + (pcase-lambda (`(,key . ,val)) + (vector key (* val 10)))) +(funcall fun '(foo . 2)) + @result{} [foo 20] +@end example +@end defmac + @node Iteration @section Iteration @cindex iteration diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index 9c635baccf7..6ba35cffffe 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -376,7 +376,7 @@ name) and the new value, and should do whatever is necessary to update the value properly for this option (which may not mean simply setting the option as a Lisp variable); preferably, though, it should not modify its value argument destructively. The default for -@var{setfunction} is @code{set-default}. +@var{setfunction} is @code{set-default-toplevel-value}. If you specify this keyword, the variable's documentation string should describe how to do the same job in hand-written Lisp code. @@ -387,7 +387,7 @@ Specify @var{getfunction} as the way to extract the value of this option. The function @var{getfunction} should take one argument, a symbol, and should return whatever customize should use as the current value for that symbol (which need not be the symbol's Lisp -value). The default is @code{default-value}. +value). The default is @code{default-toplevel-value}. You have to really understand the workings of Custom to use @code{:get} correctly. It is meant for values that are treated in @@ -409,11 +409,11 @@ do not reinitialize it if it is already non-void. @item custom-initialize-default Like @code{custom-initialize-set}, but use the function -@code{set-default} to set the variable, instead of the variable's -@code{:set} function. This is the usual choice for a variable whose -@code{:set} function enables or disables a minor mode; with this choice, -defining the variable will not call the minor mode function, but -customizing the variable will do so. +@code{set-default-toplevel-value} to set the variable, instead of the +variable's @code{:set} function. This is the usual choice for a +variable whose @code{:set} function enables or disables a minor mode; +with this choice, defining the variable will not call the minor mode +function, but customizing the variable will do so. @item custom-initialize-reset Always use the @code{:set} function to initialize the variable. If @@ -424,7 +424,7 @@ This is the default @code{:initialize} function. @item custom-initialize-changed Use the @code{:set} function to initialize the variable, if it is already set or has been customized; otherwise, just use -@code{set-default}. +@code{set-default-toplevel-value}. @item custom-initialize-delay This function behaves like @code{custom-initialize-set}, but it @@ -654,10 +654,14 @@ you can specify that the value must be @code{nil} or @code{t}, but also specify the text to describe each value in a way that fits the specific meaning of the alternative. +@item key +The value is a valid key according to @kbd{key-valid-p}, and suitable +for use with, for example @code{keymap-set}. + @item key-sequence The value is a key sequence. The customization buffer shows the key sequence using the same syntax as the @kbd{kbd} function. @xref{Key -Sequences}. +Sequences}. This is a legacy type; use @code{key} instead. @item coding-system The value must be a coding-system name, and you can do completion with @@ -668,6 +672,10 @@ The value must be a valid color name. The widget provides completion for color names, as well as a sample and a button for selecting a color name from a list of color names shown in a @file{*Colors*} buffer. + +@item fringe-bitmap +The value must be a valid fringe bitmap name. The widget provides +completion. @end table @node Composite Types @@ -737,7 +745,7 @@ If omitted, @var{key-type} and @var{value-type} default to The user can add any key matching the specified key type, but you can give some keys a preferential treatment by specifying them with the -@code{:options} (see @ref{Variable Definitions}). The specified keys +@code{:options} (@pxref{Variable Definitions}). The specified keys will always be shown in the customize buffer (together with a suitable value), with a checkbox to include or exclude or disable the key/value pair from the alist. The user will not be able to edit the keys diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 469ff2d943d..9ae40949d1e 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -77,6 +77,7 @@ debugger recursively. @xref{Recursive Editing}. @menu * Error Debugging:: Entering the debugger when an error happens. +* Debugging Redisplay:: Getting backtraces from redisplay errors. * Infinite Loops:: Stopping and debugging a program that doesn't exit. * Function Debugging:: Entering it when a certain function is called. * Variable Debugging:: Entering it when a variable is modified. @@ -105,6 +106,10 @@ debugger, set the variable @code{debug-on-error} to non-@code{nil}. (The command @code{toggle-debug-on-error} provides an easy way to do this.) +Note that, for technical reasons, you cannot use the facilities +defined in this subsection to debug errors in Lisp that the redisplay +code has invoked. @xref{Debugging Redisplay}, for help with these. + @defopt debug-on-error This variable determines whether the debugger is called when an error is signaled and not handled. If @code{debug-on-error} is @code{t}, @@ -196,12 +201,62 @@ echo area. For example, this can be useful when trying to find the cause of a particular message. @end defvar +@defvar debug-allow-recursive-debug +You can evaluate forms in the current stack frame in the +@samp{*Backtrace*} buffer with the @key{e} command, and while +edebugging you can use the @key{e} and @key{C-x C-e} commands to do +something similar. By default, the debugger is inhibited by these +commands (because (re-)entering the debugger at this point will +usually take you out of the debugging context you're in). Set +@code{debug-allow-recursive-debug} to a non-@code{nil} value to allow +these commands to enter the debugger recursively. +@end defvar + To debug an error that happens during loading of the init file, use the option @samp{--debug-init}. This binds @code{debug-on-error} to @code{t} while loading the init file, and bypasses the @code{condition-case} which normally catches errors in the init file. +@node Debugging Redisplay +@subsection Debugging Redisplay Errors +@cindex redisplay errors +@cindex debugging redisplay errors + +When an error occurs in Lisp code which redisplay has invoked, Emacs's +usual debugging mechanisms are unusable, for technical reasons. This +subsection describes how to get a backtrace from such an error, which +should be helpful in debugging it. + +These directions apply to Lisp forms used, for example, in +@code{:eval} mode line constructs (@pxref{Mode Line Data}), and in all +hooks invoked from redisplay, such as: + +@itemize +@item +@code{fontification-functions} (@pxref{Auto Faces}). +@item +@code{window-scroll-functions} (@pxref{Window Hooks}). +@end itemize + +Note that if you have had an error in a hook function called from +redisplay, the error handling might have removed this function from +the hook. You will thus need to reinitialize that hook somehow, +perhaps with @code{add-hook}, to be able to replay the bug. + +To generate a backtrace in these circumstances, set the variable +@code{backtrace-on-redisplay-error} to non-@code{nil}. When the error +occurs, Emacs will dump the backtrace to the buffer +@file{*Redisplay-trace*}, but won't automatically display it in a +window. This is to avoid needlessly corrupting the redisplay you are +debugging. You will thus need to display the buffer yourself, with a +command such as @code{switch-to-buffer-other-frame} @key{C-x 5 b}. + +@defvar backtrace-on-redisplay-error +Set this variable to non-@code{nil} to enable the generation of a +backtrace when an error occurs in any Lisp called from redisplay. +@end defvar + @node Infinite Loops @subsection Debugging Infinite Loops @cindex infinite loops @@ -387,11 +442,9 @@ possibilities.) variable is temporarily set according to @code{eval-expression-debug-on-error}. If the latter variable is non-@code{nil}, @code{debug-on-error} will temporarily be set to -@code{t}. This means that any further errors that occur while doing a -debugging session will (by default) trigger another backtrace. If -this is not what you want, you can either set -@code{eval-expression-debug-on-error} to @code{nil}, or set -@code{debug-on-error} to @code{nil} in @code{debugger-mode-hook}. +@code{t}. However, further errors that occur while debugging won't +(by default) trigger another debugger, because @code{inhibit-debugger} +will also be bound to non-@code{nil}. The debugger itself must be run byte-compiled, since it makes assumptions about the state of the Lisp interpreter. These @@ -522,6 +575,7 @@ Flag the current frame like @kbd{b}. Then continue execution like @kbd{c}, but temporarily disable break-on-entry for all functions that are set up to do so by @code{debug-on-entry}. +@vindex debug-allow-recursive-debug @item e Read a Lisp expression in the minibuffer, evaluate it (with the relevant lexical environment, if applicable), and print the @@ -530,7 +584,11 @@ variables, and the current buffer, as part of its operation; @kbd{e} temporarily restores their values from outside the debugger, so you can examine and change them. This makes the debugger more transparent. By contrast, @kbd{M-:} does nothing special in the debugger; it shows you -the variable values within the debugger. +the variable values within the debugger. By default, this command +suppresses the debugger during evaluation, so that an error in the +evaluated expression won't add a new error on top of the existing one. +Set the @code{debug-allow-recursive-debug} user option to a +non-@code{nil} value to override this. @item R Like @kbd{e}, but also save the result of evaluation in the diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index b068c7d08c6..69b752688ea 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. @@ -336,7 +337,10 @@ functions call it with no arguments when their argument message is Usually this function is called when the next input event arrives after displaying an echo-area message. The function is expected to clear the message displayed by its counterpart function specified by -@code{set-message-function}. +@code{set-message-function}, but doesn't have to. If the function +wants the echo area to remain uncleared, it should return the symbol +@code{dont-clear-message}; any other value will result in the echo +area being cleared. The default value is the function that clears the message displayed in an active minibuffer. @@ -561,6 +565,26 @@ You can rewrite the previous example with this macro as follows: @end example @end defmac +@defmac with-delayed-message (timeout message) body@dots{} +Sometimes it's unclear whether an operation will take a long time to +execute or not, or it can be inconvenient to implement a progress +reporter. This macro can be used in those situations. + +@lisp +(with-delayed-message (2 (format "Gathering data for %s" entry)) + (setq data (gather-data entry))) +@end lisp + +In this example, if the body takes more than two seconds to execute, +the message will be displayed. If it takes a shorter time than that, +the message won't be displayed. In either case, the body is evaluated +as normally, and the return value of the final element in the body is +the return value of the macro. + +The @var{message} element is evaluated before @var{body}, and is +always evaluated, whether the message is displayed or not. +@end defmac + @node Logging Messages @subsection Logging Messages in @file{*Messages*} @cindex logging echo-area messages @@ -592,6 +616,16 @@ how to display a message and prevent it from being logged: @end example @end defopt +@defvar messages-buffer-name +This variable has the name of the buffer where messages should be +logged to, and defaults to @file{*Messages*}. Some packages may find +it useful to temporarily redirect the output to a different buffer +(perhaps to write the buffer out to a log file later), and they can +bind this variable to a different buffer name. (Note that this buffer +(if it doesn't exist already), will be created and put into +@code{messages-buffer-mode}.) +@end defvar + To make @file{*Messages*} more convenient for the user, the logging facility combines successive identical messages. It also combines successive related messages for the sake of two cases: question @@ -1334,6 +1368,11 @@ are not resized. By default, this mode uses @code{fit-window-to-buffer} (@pxref{Resizing Windows}) for resizing. You can specify a different function by customizing the options @code{temp-buffer-max-height} and @code{temp-buffer-max-width} below. + +The effect of this option can be overridden by providing a suitable +@code{window-height}, @code{window-width} or @code{window-size} action +alist entry for @code{display-buffer} (@pxref{Buffer Display Action +Alists}). @end defopt @defopt temp-buffer-max-height @@ -1972,6 +2011,11 @@ Tables}). The width of a tab character is usually @code{tab-width} (@pxref{Usual Display}). @end defun +@defun char-uppercase-p char +Return non-@code{nil} if @var{char} is an uppercase character +according to Unicode. +@end defun + @defun string-width string &optional from to This function returns the width in columns of the string @var{string}, if it were displayed in the current buffer and the selected window. @@ -1983,7 +2027,8 @@ The return value is an approximation: it only considers the values returned by @code{char-width} for the constituent characters, always takes a tab character as taking @code{tab-width} columns, ignores display properties and fonts, etc. For these reasons, we recommend -using @code{window-text-pixel-size}, described below, instead. +using @code{window-text-pixel-size} or @code{string-pixel-width}, +described below, instead. @end defun @defun truncate-string-to-width string width &optional start-column padding ellipsis ellipsis-text-property @@ -2060,23 +2105,33 @@ displayed in a given window. This function is used by (@pxref{Resizing Windows}) to make a window exactly as large as the text it contains. -@defun window-text-pixel-size &optional window from to x-limit y-limit mode-lines +@defun window-text-pixel-size &optional window from to x-limit y-limit mode-lines ignore-line-at-end 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. This function exists to allow Lisp programs to adjust the dimensions of -@var{window} to the buffer text it needs to display. +@var{window} to the buffer text it needs to display, and for other +similar situations. + +The return value can also optionally (see below) include the buffer +position of the first line whose dimensions were measured. 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. +character. If @var{from} is a cons, its @code{car} specifies a buffer +position, and its @code{cdr} specifies the vertical offset in pixels +from that position to the first screen line whose text is to be +measured. (The measurement will start from the visual beginning of +that screen line.) In that case, the return value will instead be a +list of the pixel-width, pixel-height, and the buffer position of the +first line that was measured. 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 X coordinate beyond which text should be ignored; it is @@ -2096,7 +2151,7 @@ the buffer might contain long lines that will be truncated anyway. The optional argument @var{y-limit}, if non-@code{nil}, specifies the 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 +If @var{y-limit} is @code{nil} or omitted, it means to consider 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 @@ -2110,6 +2165,12 @@ line, if present, in the return value. If it is @code{t}, include the height of all of these lines, if present, in the return value. @end defun +The optional argument @var{ignore-line-at-end} controls whether or +not to count the height of text in @var{to}'s screen line as part of +the returned pixel-height. This is useful if your Lisp program is +only interested in the dimensions of text up to and excluding the +visual beginning of @var{to}'s screen line. + @code{window-text-pixel-size} treats the text displayed in a window as a whole and does not care about the size of individual lines. The following function does. @@ -2175,12 +2236,59 @@ though when this function is run from an idle timer with a delay of zero seconds. @end defun +@defun buffer-text-pixel-size &optional buffer-or-name window from to x-limit y-limit +This is much like @code{window-text-pixel-size}, but can be used when +the buffer isn't shown in a window. (@code{window-text-pixel-size} is +faster when it is, so this function shouldn't be used in that case.) + +@var{buffer-or-name} must specify a live buffer or the name of a live +buffer and defaults to the current buffer. @var{window} must be a +live window and defaults to the selected one; the function will +compute the text dimensions as if @var{buffer} is displayed in +@var{window}. The return value is a cons of the maximum pixel-width +of any text line and the pixel-height of all the text lines of the +buffer specified by @var{buffer-or-name}. + +The optional arguments @var{x-limit} and @var{y-limit} have the same +meaning as with @code{window-text-pixel-size}. +@end defun + +@defun string-pixel-width string +This is a convenience function that uses @code{window-text-pixel-size} +to compute the width of @var{string} (in pixels). +@end defun + @defun line-pixel-height This function returns the height in pixels of the line at point in the selected window. The value includes the line spacing of the line (@pxref{Line Height}). @end defun +@cindex grapheme cluster +@defun string-glyph-split string +When character compositions are in effect, sequence of characters can +be composed for display to form @dfn{grapheme clusters}, for example +to display accented characters, or ligatures, or Emoji, or when +complex text shaping requires that for some scripts. When that +happens, characters no longer map in a simple way to display columns, +and display layout decisions with such strings, such as truncating too +wide strings, can be a complex job. This function helps in performing +suvh jobs: it splits up its argument @var{string} into a list of +substrings, where each substring produces a single grapheme cluster +that should be displayed as a unit. Lisp programs can then use this +list to construct visually-valid substrings of @var{string} which will +look correctly on display, or compute the width of any substring of +@var{string} by adding the width of its constituents in the returned +list, etc. + +For instance, if you want to display a string without the first glyph, +you can say: + +@example +(apply #'insert (cdr (string-glyph-split string)))) +@end example +@end defun + When a buffer is displayed with line numbers (@pxref{Display Custom,,, emacs, The GNU Emacs Manual}), it is sometimes useful to know the width taken for displaying the line numbers. The following function @@ -2367,13 +2475,22 @@ Otherwise, it returns @code{nil}. The following table lists all the face attributes, their possible values, and their effects. +@cindex unspecified, face attribute value Apart from the values given below, each face attribute can have the value @code{unspecified}. This special value means that the face doesn't specify that attribute directly. An @code{unspecified} attribute tells Emacs to refer instead to a parent face (see the description @code{:inherit} attribute below); or, failing that, to an -underlying face (@pxref{Displaying Faces}). The @code{default} face -must specify all attributes. +underlying face (@pxref{Displaying Faces}). (However, +@code{unspecified} is not a valid value in @code{defface}.) + +@cindex reset, face attribute value + A face attribute can also have the value @code{reset}. This special +value stands for the value of the corresponding attribute of the +@code{default} face. + + The @code{default} face must explicitly specify all attributes, and +cannot use the special value @code{reset}. Some of these attributes are meaningful only on certain kinds of displays. If your display cannot handle a certain attribute, the @@ -2394,8 +2511,9 @@ GNU Emacs Manual}. @item :width Relative character width. This should be one of the symbols @code{ultra-condensed}, @code{extra-condensed}, @code{condensed}, -@code{semi-condensed}, @code{normal}, @code{semi-expanded}, -@code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}. +@code{semi-condensed}, @code{normal}, @code{regular}, @code{medium}, +@code{semi-expanded}, @code{expanded}, @code{extra-expanded}, or +@code{ultra-expanded}. @item :height The height of the font. In the simplest case, this is an integer in @@ -2463,13 +2581,16 @@ Underline with the foreground color of the face. @item @var{color} Underline in color @var{color}, a string specifying a color. -@item @code{(:color @var{color} :style @var{style})} +@item @code{(:color @var{color} :style @var{style} :position @var{position})} @var{color} is either a string, or the symbol @code{foreground-color}, meaning the foreground color of the face. Omitting the attribute @code{:color} means to use the foreground color of the face. @var{style} should be a symbol @code{line} or @code{wave}, meaning to use a straight or wavy line. Omitting the attribute @code{:style} -means to use a straight line. +means to use a straight line. @var{position}, if non-nil, means to +display the underline at the descent of the text, instead of at the +baseline level. If it is a number, then it specifies the amount of +pixels above the descent to display the underline. @end table @cindex overlined text @@ -2502,14 +2623,17 @@ Draw a box with lines of width 1, in the foreground color. Draw a box with lines of width 1, in color @var{color}. @item @code{(:line-width (@var{vwidth} . @var{hwidth}) :color @var{color} :style @var{style})} -This way you can explicitly specify all aspects of the box. The values -@var{vwidth} and @var{hwidth} specifies respectively the width of the -vertical and horizontal lines to draw; they default to (1 . 1). -A negative horizontal or vertical width @minus{}@var{n} means to draw a line -of width @var{n} that occupies the space of the underlying text, thus -avoiding any increase in the character height or width. For simplification -the width could be specified with only a single number @var{n} instead -of a list, such case is equivalent to @code{((abs @var{n}) . @var{n})}. +You can explicitly specify all aspects of the box with a plist on this +form. Any element in this plist can be omitted. + +The values @var{vwidth} and @var{hwidth} specifies respectively the +width of the vertical and horizontal lines to draw; they default to (1 +. 1). A negative horizontal or vertical width @minus{}@var{n} means +to draw a line of width @var{n} that occupies the space of the +underlying text, thus avoiding any increase in the character height or +width. For simplification the width could be specified with only a +single number @var{n} instead of a list, such case is equivalent to +@code{((abs @var{n}) . @var{n})}. The value @var{style} specifies whether to draw a 3D box. If it is @code{released-button}, the box looks like a 3D button that is not @@ -2717,8 +2841,9 @@ apply to. Here are the possible values of @var{characteristic}: @item type The kind of window system the terminal uses---either @code{graphic} (any graphics-capable display), @code{x}, @code{pc} (for the MS-DOS -console), @code{w32} (for MS Windows 9X/NT/2K/XP), or @code{tty} (a -non-graphics-capable display). @xref{Window Systems, window-system}. +console), @code{w32} (for MS Windows 9X/NT/2K/XP), @code{haiku} (for +Haiku), @code{pgtk} (for pure GTK), or @code{tty} (a non-graphics-capable +display). @xref{Window Systems, window-system}. @item class What kinds of colors the terminal supports---either @code{color}, @@ -3232,6 +3357,16 @@ if you need to remove the remapping later. ;; Increase the size of the 'default' face by 50%: (face-remap-add-relative 'default :height 1.5) @end example + +Note that buffer-local face remapping does not work reliably for +parent faces of basic faces (@pxref{Basic Faces}). (These are the +faces that are used in mode lines, header lines, and other basic +decorations of windows and frames.) For instance, +@code{mode-line-inactive} inherits from @code{mode-line}, but +remapping @code{mode-line} won't normally have the desired effect on +@code{mode-line-inactive}, especially if done locally for some +buffers. Instead you have to remap @code{mode-line-inactive} +directly. @end defun @defun face-remap-remove-relative cookie @@ -3348,6 +3483,12 @@ function finishes are the ones that really matter. For efficiency, we recommend writing these functions so that they usually assign faces to around 400 to 600 characters at each call. + +When the buffer text includes very long lines, these functions are +called with the buffer narrowed to a relatively small region around +@var{pos}, and with narrowing locked, so the functions cannot use +@code{widen} to gain access to the rest of the buffer. +@xref{Narrowing}. @end defvar @node Basic Faces @@ -3357,10 +3498,10 @@ usually assign faces to around 400 to 600 characters at each call. If your Emacs Lisp program needs to assign some faces to text, it is often a good idea to use certain existing faces or inherit from them, rather than defining entirely new faces. This way, if other users -have customized the basic faces to give Emacs a certain look, your -program will fit in without additional customization. +have customized those existing faces to give Emacs a certain look, +your program will fit in without additional customization. - Some of the basic faces defined in Emacs are listed below. In + Some of the @dfn{basic faces} defined in Emacs are listed below. In addition to these, you might want to make use of the Font Lock faces for syntactic highlighting, if highlighting is not already handled by Font Lock mode, or if some Font Lock faces are not in use. @@ -3372,6 +3513,28 @@ The default face, whose attributes are all specified. All other faces implicitly inherit from it: any unspecified attribute defaults to the attribute on this face (@pxref{Face Attributes}). +@item mode-line-active +@itemx mode-line-inactive +@itemx header-line +@itemx tab-line +Basic faces used for the mode line, header line, and tab line. + +@item tool-bar +@itemx tab-bar +@itemx fringe +@itemx scroll-bar +@itemx window-divider +@itemx border +@itemx child-frame-border +Basic faces used for the corresponding decorations of GUI frames. + +@item cursor +The basic face used for the text cursor. + +@item mouse +The basic face used for displaying mouse-sensitive text when the mouse +pointer is on that text. + @item bold @itemx italic @itemx bold-italic @@ -4466,6 +4629,7 @@ Used to indicate buffer boundaries. Used for different types of fringe cursors. @item @code{exclamation-mark}, @code{question-mark} +@itemx @code{large-circle} Not used by core Emacs features. @end table @@ -4859,9 +5023,7 @@ window on a minibuffer-less frame. The @code{display} text property (or overlay property) is used to insert images into text, and to control other aspects of how text -displays. The value of the @code{display} property should be a -display specification, or a list or vector containing several display -specifications. Display specifications in the same @code{display} +displays. Display specifications in the same @code{display} property value generally apply in parallel to the text they cover. If several sources (overlays and/or a text property) specify values @@ -4869,6 +5031,50 @@ for the @code{display} property, only one of the values takes effect, following the rules of @code{get-char-property}. @xref{Examining Properties}. + The value of the @code{display} property should be a display +specification, or a list or vector containing several display +specifications. + +@defun get-display-property position prop &optional object properties +This convenience function can be used to get a specific display +property, no matter whether the @code{display} property is a vector, a +list or a simple property. This is like @code{get-text-property} +(@pxref{Examining Properties}), but works on the @code{display} +property only. + +@var{position} is the position in the buffer or string to examine, and +@var{prop} is the @code{display} property to return. The optional +@var{object} argument should be either a string or a buffer, and +defaults to the current buffer. If the optional @var{properties} +argument is non-@code{nil}, it should be a @code{display} property, +and in that case, @var{position} and @var{object} are ignored. (This +can be useful if you've already gotten the @code{display} property +with @code{get-char-property}, for instance (@pxref{Examining +Properties}). +@end defun + +@defun add-display-text-property start end prop value &optional object +Add @code{display} property @var{prop} of @var{value} to the text from +@var{start} to @var{end}. + +If any text in the region has a non-@code{nil} @code{display} +property, those properties are retained. For instance: + +@lisp +(add-display-text-property 4 8 'height 2.0) +(add-display-text-property 2 12 'raise 0.5) +@end lisp + +After doing this, the region from 2 to 4 will have the @code{raise} +@code{display} property, the region from 4 to 8 will have both the +@code{raise} and @code{height} @code{display} properties, and finally +the region from 8 to 12 will only have the @code{raise} @code{display} +property. + +If @var{object} is non-@code{nil}, it should be a string or a buffer. +If @code{nil}, this defaults to the current buffer. +@end defun + @cindex display property, unsafe evaluation @cindex security, and display specifications Some of the display specifications allow inclusion of Lisp forms, @@ -5144,6 +5350,24 @@ text that has the specification. It displays all of these spaces be an integer or float. Characters other than spaces are not affected at all; in particular, this has no effect on tab characters. +@item (min-width (@var{width})) +This display specification ensures the text that has it takes at least +@var{width} space on display, by adding a stretch of white space to +the end of the text if the text is shorter than @var{width}. The text +is partitioned using the identity of the parameter, which is why the +parameter is a list with one element. For instance: + +@lisp +(insert (propertize "foo" 'display '(min-width (6.0)))) +@end lisp + +This will add padding after @samp{foo} bringing the total width up to +the width of six normal characters. Note that the affected characters +are identified by the @code{(6.0)} list in the display property, +compared with @code{eq}. The element @var{width} can be either an +integer or a float specifying the required minimum width of the text +(@pxref{Pixel Specification}). + @item (height @var{height}) This display specification makes the text taller or shorter. Here are the possibilities for @var{height}: @@ -5344,13 +5568,19 @@ to modify the set of known names for these dynamic libraries. Supported image formats (and the required support libraries) include PBM and XBM (which do not depend on support libraries and are always available), XPM (@code{libXpm}), GIF (@code{libgif} or -@code{libungif}), JPEG (@code{libjpeg}), TIFF -(@code{libtiff}), PNG (@code{libpng}), and SVG (@code{librsvg}). +@code{libungif}), JPEG (@code{libjpeg}), TIFF (@code{libtiff}), PNG +(@code{libpng}), SVG (@code{librsvg}), and WebP (@code{libwebp}). Each of these image formats is associated with an @dfn{image type symbol}. The symbols for the above formats are, respectively, -@code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, -@code{jpeg}, @code{tiff}, @code{png}, and @code{svg}. +@code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, @code{jpeg}, +@code{tiff}, @code{png}, @code{svg}, and @code{webp}. + + On some platforms, the built-in image support that doesn't require +any optional libraries includes BMP images.@footnote{ +On MS-Windows, this requires @code{w32-use-native-image-API} to be set +non-@code{nil}. +} Furthermore, if you build Emacs with ImageMagick (@code{libMagickWand}) support, Emacs can display any image format @@ -5505,6 +5735,12 @@ are supported, unless the image type is @code{imagemagick}. Positive values rotate clockwise, negative values counter-clockwise. Rotation is performed after scaling and cropping. +@item :flip @var{flip} +If this is @code{t}, the image will be horizontally flipped. +Currently it has no effect if the image type is @code{imagemagick}. +Vertical flipping can be achieved by rotating the image 180 degrees +and toggling this value. + @item :transform-smoothing @var{smooth} If this is @code{t}, any image transform will have smoothing applied; if @code{nil}, no smoothing will be applied. The exact algorithm used @@ -5653,6 +5889,14 @@ When you click the mouse when the mouse pointer is over a hot-spot, an event is composed by combining the @var{id} of the hot-spot with the mouse event; for instance, @code{[area4 mouse-1]} if the hot-spot's @var{id} is @code{area4}. + +Note that the map's coordinates should reflect the displayed image +after all transforms have been done (rotation, scaling and so on), and +also note that Emacs (by default) performs auto-scaling of images, so +to make things match up, you should either specify @code{:scale 1.0} +when creating the image, or use the result of +@code{image-compute-scaling-factor} to compute the elements of the +map. @end table @defun image-mask-p spec &optional frame @@ -5718,13 +5962,10 @@ There are three formats you can use for @var{data}: @itemize @bullet @item A vector of strings or bool-vectors, each specifying one line of the -image. Do specify @code{:height} and @code{:width}. +image. Do specify @code{:data-height} and @code{:data-width}. @item A string containing the same byte sequence as an XBM file would contain. -You must not specify @code{:height} and @code{:width} in this case, -because omitting them is what indicates the data has the format of an -XBM file. The file contents specify the height and width of the image. @item A string or a bool-vector containing the bits of the image (plus @@ -5732,26 +5973,11 @@ perhaps some extra bits at the end that will not be used). It should contain at least @w{@code{@var{stride} * @var{height}}} bits, where @var{stride} is the smallest multiple of 8 greater than or equal to the width of the image. In this case, you should specify -@code{:height}, @code{:width} and @code{:stride}, both to indicate -that the string contains just the bits rather than a whole XBM file, -and to specify the size of the image. +@code{:data-height}, @code{:data-width} and @code{:stride}, both to +indicate that the string contains just the bits rather than a whole +XBM file, and to specify the size of the image. @end itemize -@item :width @var{width} -The value, @var{width}, specifies the width of the image, in pixels. - -@item :height @var{height} -The value, @var{height}, specifies the height of the image, in pixels. - -Note that @code{:width} and @code{:height} can only be used if passing -in data that doesn't specify the width and height (e.g., a string or a -vector containing the bits of the image). @acronym{XBM} files usually -specify this themselves, and it's an error to use these two properties -on these files. Also note that @code{:width} and @code{:height} are -used by most other image formats to specify what the displayed image -is supposed to be, which usually means performing some sort of -scaling. This isn't supported for @acronym{XBM} images. - @item :stride @var{stride} The number of bool vector entries stored for each row; the smallest multiple of 8 greater than or equal to @var{width}. @@ -6354,6 +6580,9 @@ Image type @code{png}. @item TIFF Image type @code{tiff}. Supports the @code{:index} property. @xref{Multi-Frame Images}. + +@item WebP +Image type @code{webp}. @end table @node Defining Images @@ -6505,7 +6734,7 @@ will compute a scaling factor based on the font pixel size. property yourself, but it is easier to use the functions in this section. -@defun insert-image image &optional string area slice +@defun insert-image image &optional string area slice inhibit-isearch This function inserts @var{image} in the current buffer at point. The value @var{image} should be an image descriptor; it could be a value returned by @code{create-image}, or the value of a symbol defined with @@ -6532,7 +6761,9 @@ image. Internally, this function inserts @var{string} in the buffer, and gives it a @code{display} property which specifies @var{image}. @xref{Display -Property}. +Property}. By default, doing interactive searches in the buffer will +consider @var{string} when searching. If @var{inhibit-isearch} is +non-@code{nil}, this is inhibited. @end defun @cindex slice, image @@ -6608,6 +6839,11 @@ cache, it can always be displayed, even if the value of @code{max-image-size} is subsequently changed (@pxref{Image Cache}). @end defvar +@defun image-at-point-p +This function returns @code{t} if point is on an image, and @code{nil} +otherwise. +@end defun + Images inserted with the insertion functions above also get a local keymap installed in the text properties (or overlays) that span the displayed image. This keymap defines the following commands: @@ -6762,6 +6998,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 @@ -6779,7 +7174,10 @@ xwidget object, and then use that object as the display specifier in a @code{display} text or overlay property (@pxref{Display Property}). -@defun make-xwidget type title width height arguments &optional buffer + Embedded widgets can send events notifying Lisp code about changes +occurring within them. (@pxref{Xwidget Events}). + +@defun make-xwidget type title width height arguments &optional buffer related This creates and returns an xwidget object. If @var{buffer} is omitted or @code{nil}, it defaults to the current buffer. If @var{buffer} names a buffer that doesn't exist, it will be @@ -6792,7 +7190,17 @@ The WebKit component. @end table The @var{width} and @var{height} arguments specify the widget size in -pixels, and @var{title}, a string, specifies its title. +pixels, and @var{title}, a string, specifies its title. @var{related} +is used internally by the WebKit widget, and specifies another WebKit +widget that the newly created widget should share settings and +subprocesses with. + +The xwidget that is returned will be killed alongside its buffer +(@pxref{Killing Buffers}). You can also kill it using +@code{kill-xwidget}. Once it is killed, the xwidget may continue to +exist as a Lisp object and act as a @code{display} property until all +references to it are gone, but most actions that can be performed on +live xwidgets will no longer be available. @end defun @defun xwidgetp object @@ -6800,6 +7208,17 @@ This function returns @code{t} if @var{object} is an xwidget, @code{nil} otherwise. @end defun +@defun xwidget-live-p object +This function returns @code{t} if @var{object} is an xwidget that +hasn't been killed, and @code{nil} otherwise. +@end defun + +@defun kill-xwidget xwidget +This function kills @var{xwidget}, by removing it from its buffer and +releasing window system resources it holds. +@end defun + +@cindex xwidget property list @defun xwidget-plist xwidget This function returns the property list of @var{xwidget}. @end defun @@ -6810,7 +7229,12 @@ property list given by @var{plist}. @end defun @defun xwidget-buffer xwidget -This function returns the buffer of @var{xwidget}. +This function returns the buffer of @var{xwidget}. If @var{xwidget} +has been killed, it returns @code{nil}. +@end defun + +@defun set-xwidget-buffer xwidget buffer +This function sets the buffer of @var{xwidget} to @var{buffer}. @end defun @defun get-buffer-xwidgets buffer @@ -6873,6 +7297,130 @@ This function returns the current setting of @var{xwidget}s query-on-exit flag, either @code{t} or @code{nil}. @end defun +@defun xwidget-perform-lispy-event xwidget event frame +Send an input event @var{event} to @var{xwidget}. The precise action +performed is platform-specific. @xref{Input Events}. + +You can optionally pass the frame on which the event was generated via +@var{frame}. On X11, modifier keys in key events will not be +considered if @var{frame} is @code{nil}, and the selected frame is not +an X-Windows frame. + +On GTK, only keyboard and function key events are supported. Mouse, +motion, and click events are dispatched to the xwidget without going +through Lisp code, and as such shouldn't require this function to be +called. +@end defun + +@defun xwidget-webkit-search query xwidget &optional case-insensitive backwards wrap-around +Start an incremental search on the WebKit widget @var{xwidget} with +the string @var{query} as the query. @var{case-insensitive} denotes +whether or not the search is case-insensitive, @var{backwards} +determines if the search is performed backwards towards the start of +the document, and @var{wrap-around} determines whether or not the +search terminates at the end of the document. + +If the function is called while a search query is already present, +then the query specified here will replace the existing query. + +To stop a search query, use @code{xwidget-webkit-finish-search}. +@end defun + +@defun xwidget-webkit-next-result xwidget +Display the next search result in @var{xwidget}. This function will +signal an error if a search query has not been already started in +@var{xwidget} through @code{xwidget-webkit-search}. + +If @code{wrap-around} was non-nil when @code{xwidget-webkit-search} +was called, then the search will restart from the beginning of the +document when its end is reached. +@end defun + +@defun xwidget-webkit-previous-result xwidget +Display the previous search result in @var{xwidget}. This function +signals an error if a search query has not been already started in +@var{xwidget} through @code{xwidget-webkit-search}. + +If @code{wrap-around} was non-nil when @code{xwidget-webkit-search} +was called, then the search will restart from the end of the +document when its beginning is reached. +@end defun + +@defun xwidget-webkit-finish-search xwidget +Finish a search operation started with @code{xwidget-webkit-search} in +@var{xwidget}. If there is no query currently ongoing, this function +signals an error. +@end defun + +@defun xwidget-webkit-load-html xwidget text &optional base-uri +Load @var{text}, a string, into @var{xwidget}, which should be a +WebKit xwidget. Any HTML markup in @var{text} will be processed +by @var{xwidget} while rendering the text. + +Optional argument @var{base-uri}, which should be a string, specifies +the absolute location of the web resources referenced by @var{text}, +to be used for resolving relative links in @var{text}. +@end defun + +@defun xwidget-webkit-goto-history xwidget rel-pos +Make @var{xwidget}, a WebKit widget, load the @var{rel-pos}th element +in its navigation history. + +If @var{rel-pos} is zero, the current page will be reloaded instead. +@end defun + +@defun xwidget-webkit-back-forward-list xwidget &optional limit +Return the navigation history of @var{xwidget}, up to @var{limit} +items in each direction. If not specified, @var{limit} defaults to +50. + +The returned value is a list of the form @w{@code{(@var{back} +@var{here} @var{forward})}}, where @var{here} is the current +navigation item, while @var{back} is a list of items containing the +items recorded by WebKit before the current navigation item, and +@var{forward} is a list of items recorded after the current navigation +item. @var{back}, @var{here} and @var{forward} can all be @code{nil}. + +When @var{here} is @code{nil}, it means that no items have been +recorded yet; if @var{back} or @var{forward} are @code{nil}, it means +that there is no history recorded before or after the current item +respectively. + +Navigation items are themselves lists of the form @w{@code{(@var{idx} +@var{title} @var{uri})}}. In these lists, @var{idx} is an index that +can be passed to @code{xwidget-webkit-goto-history}, @var{title} is +the human-readable title of the item, and @var{uri} is the URI of the +item. The user should normally have no reason to load @var{uri} +manually to reach a specific history item. Instead, @var{idx} should +be passed as an index to @code{xwidget-webkit-goto-history}. +@end defun + +@defun xwidget-webkit-estimated-load-progress xwidget +Return an estimate of how much data is remaining to be transferred +before the page displayed by the WebKit widget @var{xwidget} is fully +loaded. + +The value returned is a float ranging between 0.0 and 1.0. +@end defun + +@defun xwidget-webkit-set-cookie-storage-file xwidget file +Make the WebKit widget @var{xwidget} store cookies in @var{file}. + +@var{file} must be an absolute file name. The new setting will also +affect any xwidget that was created with @var{xwidget} as the +@code{related} argument to @code{make-xwidget}, and widgets related to +those as well. + +If this function is not called at least once on @var{xwidget} or a +related widget, @var{xwidget} will not store cookies on disk at all. +@end defun + +@defun xwidget-webkit-stop-loading xwidget +Terminate any data transfer still in progress in the WebKit widget +@var{xwidget} as part of a page-loading operation. If a page is not +being loaded, this function does nothing. +@end defun + @node Buttons @section Buttons @cindex buttons in buffers @@ -7067,7 +7615,7 @@ This inserts a button with the label @var{label} at point, using text properties. @end defun -@defun button-buttonize string callback &optional data +@defun buttonize string callback &optional data Sometimes it's more convenient to make a string into a button without inserting it into a buffer immediately, for instance when creating data structures that may then, later, be inserted into a buffer. This @@ -7195,7 +7743,7 @@ end of the buffer continues from the other end. If @var{display-message} is non-@code{nil}, the button's help-echo string is displayed. Any button with a non-@code{nil} @code{skip} property is skipped over. Returns the button found, and signals an error if no -buttons can be found. If @var{no-error} is non-@code{nil}, return nil +buttons can be found. If @var{no-error} is non-@code{nil}, return @code{nil} instead of signaling the error. @end deffn @@ -7207,7 +7755,7 @@ end of the buffer continues from the other end. If @var{display-message} is non-@code{nil}, the button's help-echo string is displayed. Any button with a non-@code{nil} @code{skip} property is skipped over. Returns the button found, and signals an error if no -buttons can be found. If @var{no-error} is non-@code{nil}, return nil +buttons can be found. If @var{no-error} is non-@code{nil}, return @code{nil} instead of signaling the error. @end deffn @@ -7543,16 +8091,14 @@ The string is formatted #RRGGBB (hash followed by six hex digits)." (kill-buffer nil)) (setq colorcomp-mode-map - (let ((m (make-sparse-keymap))) - (suppress-keymap m) - (define-key m "i" 'colorcomp-R-less) - (define-key m "o" 'colorcomp-R-more) - (define-key m "k" 'colorcomp-G-less) - (define-key m "l" 'colorcomp-G-more) - (define-key m "," 'colorcomp-B-less) - (define-key m "." 'colorcomp-B-more) - (define-key m " " 'colorcomp-copy-as-kill-and-exit) - m)) + (define-keymap :suppress t + "i" 'colorcomp-R-less + "o" 'colorcomp-R-more + "k" 'colorcomp-G-less + "l" 'colorcomp-G-more + "," 'colorcomp-B-less + "." 'colorcomp-B-more + "SPC" 'colorcomp-copy-as-kill-and-exit)) @end smallexample Note that we never modify the data in each node, which is fixed when the @@ -7855,7 +8401,10 @@ help buffer. The window's display table, if there is one, takes precedence over the buffer's display table. If neither exists, Emacs tries to use the standard display table; if that is @code{nil}, Emacs uses the usual -character display conventions (@pxref{Usual Display}). +character display conventions (@pxref{Usual Display}). (Emacs does +not ``merge'' display tables: For instance, if the window has a +display table, the buffer's display table and the standard display +table are completely ignored.) Note that display tables affect how the mode line is displayed, so if you want to force redisplay of the mode line using a new display @@ -7961,7 +8510,14 @@ there is no available font (on a graphical display), and characters which cannot be encoded by the terminal's coding system (on a text terminal). +@findex glyphless-display-mode +The @code{glyphless-display-mode} minor mode can be used to toggle +displaying glyphless characters in a convenient manner in the current +buffer. If this mode is enabled, all the glyphless characters are +displayed as boxes that display acronyms of their character names. + @defvar glyphless-char-display +For more fine-grained (and global) control, this variable can be used. The value of this variable is a char-table which defines glyphless characters and how they are displayed. Each entry must be one of the following display methods: @@ -7986,7 +8542,11 @@ hexadecimal notation. @item an @acronym{ASCII} string Display a box containing that string. The string should contain at -most 6 @acronym{ASCII} characters. +most 6 @acronym{ASCII} characters. As an exception, if the string +includes just one character, on text-mode terminals that character +will be displayed without a box; this allows to handle such +``acronyms'' as a replacement character for characters that cannot be +displayed by the terminal. @item a cons cell @code{(@var{graphical} . @var{text})} Display with @var{graphical} on graphical displays, and with @@ -8004,7 +8564,7 @@ square brackets, @samp{[]}. The char-table has one extra slot, which determines how to display any character that cannot be displayed with any available font, or cannot be encoded by the terminal's coding system. Its value should be one -of the above display methods, except @code{zero-width} or a cons cell. +of the above display methods, except @code{zero-width}. If a character has a non-@code{nil} entry in an active display table, the display table takes effect; in this case, Emacs does not consult @@ -8042,10 +8602,20 @@ Characters of Unicode General Category [Cf], such as U+200E @sc{left-to-right mark}, but excluding characters that have graphic images, such as U+00AD @sc{soft hyphen}. +@item bidi-control +This is a subset of @code{format-control}, but only includes +characters that are related to bidirectional formatting control, like +U+2069 @sc{pop directional isolate} and U+202A @sc{left-to-right +embedding}. @xref{Bidirectional Display}. + +Characters of Unicode General Category [Cf], such as U+200E +@sc{left-to-right mark}, but excluding characters that have graphic +images, such as U+00AD @sc{soft hyphen}. + @item variation-selectors -Unicode VS-1 through VS-16 (U+FE00 through U+FE0F), which are used to -select between different glyphs for the same codepoints (typically -emojis). +Unicode VS-1 through VS-256 (U+FE00 through U+FE0F and U+E0100 through +U+E01EF), which are used to select between different glyphs for the same +codepoints (typically emojis). @item no-font Characters for which there is no suitable font, or which cannot be @@ -8120,6 +8690,10 @@ Emacs is displaying the frame using the Nextstep interface (used on GNUstep and macOS). @item pc Emacs is displaying the frame using MS-DOS direct screen writes. +@item haiku +Emacs is displaying the frame using the Application Kit on Haiku. +@item pgtk +Emacs is displaying the frame using pure GTK facilities. @item nil Emacs is displaying the frame on a character-based terminal. @end table @@ -8166,13 +8740,15 @@ area. On text-mode (a.k.a.@: ``TTY'') frames, tooltips are always displayed in the echo area. @end defun -@vindex x-gtk-use-system-tooltips -When Emacs is built with GTK+ support, it by default displays tooltips -using GTK+ functions, and the appearance of the tooltips is then -controlled by GTK+ settings. GTK+ tooltips can be disabled by -changing the value of the variable @code{x-gtk-use-system-tooltips} to -@code{nil}. The rest of this subsection describes how to control -non-GTK+ tooltips, which are presented by Emacs itself. +@cindex system tooltips +@vindex use-system-tooltips +When Emacs is built with the GTK+ toolkit or Haiku windowing support, +it by default displays tooltips using toolkit functions, and the +appearance of the tooltips is then controlled by the toolkit's +settings. Toolkit-provided tooltips can be disabled by changing the +value of the variable @code{use-system-tooltips} to @code{nil}. The +rest of this subsection describes how to control non-toolkit tooltips, +which are presented by Emacs itself. @cindex tooltip frames Tooltips are displayed in special frames called tooltip frames, which diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index 8f38e576242..56f7b7bdfad 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -700,8 +700,16 @@ on this process. @table @kbd @item e @var{exp} @key{RET} Evaluate expression @var{exp} in the context outside of Edebug -(@code{edebug-eval-expression}). That is, Edebug tries to minimize its -interference with the evaluation. +(@code{edebug-eval-expression}). That is, Edebug tries to minimize +its interference with the evaluation. The result is shown in the echo +area, or, if this command is given a prefix, pop up a new buffer and +pretty-print the result there. + +By default, this command +suppresses the debugger during evaluation, so that an error in the +evaluated expression won't add a new error on top of the existing one. +Set the @code{debug-allow-recursive-debug} user option to a +non-@code{nil} value to override this. @item M-: @var{exp} @key{RET} Evaluate expression @var{exp} in the context of Edebug itself @@ -711,7 +719,8 @@ Evaluate expression @var{exp} in the context of Edebug itself Evaluate the expression before point, in the context outside of Edebug (@code{edebug-eval-last-sexp}). With the prefix argument of zero (@kbd{C-u 0 C-x C-e}), don't shorten long items (like strings and -lists). +lists). Any other prefix will result in the value being +pretty-printed in a separate buffer. @end table @cindex lexical binding (Edebug) @@ -1266,7 +1275,7 @@ balanced parentheses, recursive processing of forms, and recursion via indirect specifications. Here's a table of the possible elements of a specification list, with -their meanings (see @ref{Specification Examples}, for the referenced +their meanings (@pxref{Specification Examples}, for the referenced examples): @table @code diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 70cdaee2929..a3d1d804086 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -365,6 +365,7 @@ Editing Types * Keymap Type:: What function a keystroke invokes. * Overlay Type:: How an overlay is represented. * Font Type:: Fonts for displaying text. +* Xwidget Type:: Embeddable widgets. Numbers @@ -447,6 +448,9 @@ Symbols * Creating Symbols:: How symbols are kept unique. * Symbol Properties:: Each symbol has a property list for recording miscellaneous information. +* Shorthands:: Properly organize your symbol names but + type less of them. +* Symbols with Position:: Symbol variants containing integer positions Symbol Properties @@ -525,6 +529,7 @@ Variables * Variables with Restricted Values:: Non-constant variables whose value can @emph{not} be an arbitrary Lisp object. * Generalized Variables:: Extending the concept of variables. +* Multisession Variables:: Variables that survive restarting Emacs. Scoping Rules for Variable Bindings @@ -546,6 +551,10 @@ Generalized Variables * Setting Generalized Variables:: The @code{setf} macro. * Adding Generalized Variables:: Defining new @code{setf} forms. +Multisession Variables + +* Multisession Variables:: Variables that survive restarting Emacs. + Functions * What Is a Function:: Lisp functions vs. primitives; terminology. @@ -583,6 +592,7 @@ Advising Emacs Lisp Functions * Advising Named Functions:: Advising named functions. * Advice Combinators:: Ways to compose advice. * Porting Old Advice:: Adapting code using the old defadvice. +* Advice and Byte Code:: Not all functions can be advised. Macros @@ -729,6 +739,7 @@ Reading and Printing Lisp Objects * Output Functions:: Functions to print Lisp objects as text. * Output Variables:: Variables that control what the printing functions do. +* Output Overrides:: Overriding output variables. Minibuffers @@ -839,6 +850,7 @@ Keymaps * Key Lookup:: Finding a key's binding in one keymap. * Functions for Key Lookup:: How to request key lookup. * Changing Key Bindings:: Redefining a key in a keymap. +* Low-Level Key Binding:: Legacy key syntax description. * Remapping Commands:: A keymap can translate one command to another. * Translation Keymaps:: Keymaps for translating sequences of events. * Key Binding Commands:: Interactive interfaces for redefining keys. @@ -1123,6 +1135,7 @@ Frames * Dialog Boxes:: Displaying a box to ask yes or no. * Pointer Shape:: Specifying the shape of the mouse pointer. * Window System Selections::Transferring text to and from other X clients. +* Yanking Media:: Yanking things that aren't plain text. * Drag and Drop:: Internals of Drag-and-Drop implementation. * Color Names:: Getting the definitions of color names. * Text Terminal Colors:: Defining colors for text terminals. @@ -1220,7 +1233,9 @@ Text * Decompression:: Dealing with compressed data. * Base 64:: Conversion to or from base 64 encoding. * Checksum/Hash:: Computing cryptographic hashes. +* Suspicious Text:: Determining whether a string is suspicious. * GnuTLS Cryptography:: Cryptographic algorithms imported from GnuTLS. +* Database:: Interacting with an SQL database. * Parsing HTML/XML:: Parsing HTML and XML. * Atomic Changes:: Installing several buffer changes atomically. * Change Hooks:: Supplying functions to be run when text is changed. diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index 7e5372765f7..44a62dcebca 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -98,6 +98,10 @@ Lisp reader, not to file I/O@. @xref{Input Functions}. @item file-already-exists This is a subcategory of @code{file-error}. @xref{Writing to Files}. +@item permission-denied +This is a subcategory of @code{file-error}, which occurs when the OS +doesn't allow Emacs to access a file or a directory for some reason. + @item file-date-error This is a subcategory of @code{file-error}. It occurs when @code{copy-file} tries and fails to set the last-modification time of diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index e94e222e6a6..ed3cf56e098 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -435,7 +435,7 @@ expansion. @cindex forms, special @cindex evaluation of special forms - A @dfn{special form} is a primitive function specially marked so that + A @dfn{special form} is a primitive specially marked so that its arguments are not all evaluated. Most special forms define control structures or perform variable bindings---things which functions cannot do. diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 08677f789a5..986fb22c75b 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -581,9 +581,12 @@ contents of the file. This is better than simply deleting the buffer contents and inserting the whole file, because (1) it preserves some marker positions and (2) it puts less data in the undo list. -It is possible to read a special file (such as a FIFO or an I/O device) -with @code{insert-file-contents}, as long as @var{replace} and -@var{visit} are @code{nil}. +It is possible to read a special file (such as a FIFO or an I/O +device) with @code{insert-file-contents}, as long as @var{replace}, +and @var{visit} and @var{beg} are @code{nil}. However, you should +normally use an @var{end} argument for these files to avoid inserting +(potentially) unlimited data into the buffer (for instance, when +inserting data from @file{/dev/urandom}). @end defun @defun insert-file-contents-literally filename &optional visit beg end replace @@ -1314,6 +1317,20 @@ on the 19th, @file{aug-20} was written on the 20th, and the file @end example @end defun +@defun file-has-changed-p filename tag +This function returns non-@code{nil} if the time stamp of +@var{filename} has changed since the last call. When called for the +first time for some @var{filename}, it records the last modification +time and size of the file, and returns non-@code{nil} when +@var{filename} exists. Thereafter, when called for the same +@var{filename}, it compares the current time stamp and size with the +recorded ones, and returns non-@code{nil} only if either the time +stamp or the size (or both) are different. This is useful when a Lisp +program wants to re-read a file whenever it changes. With an optional +argument @var{tag}, which must be a symbol, the size and modification +time comparisons are limited to calls with the same tag. +@end defun + @defun file-attributes filename &optional id-format @anchor{Definition of file-attributes} This function returns a list of attributes of file @var{filename}. If @@ -1436,13 +1453,19 @@ is owned by the user with name @samp{lh}. is in the group with name @samp{users}. @item (20614 64019 50040 152000) -was last accessed on October 23, 2012, at 20:12:03.050040152 UTC. +was last accessed on October 23, 2012, at 20:12:03.050040152 UTC@. +(This timestamp is @code{(1351023123050040152 . 1000000000)} +if @code{current-time-list} is @code{nil}.) @item (20000 23 0 0) -was last modified on July 15, 2001, at 08:53:43 UTC. +was last modified on July 15, 2001, at 08:53:43.000000000 UTC@. +(This timestamp is @code{(1310720023000000000 . 1000000000)} +if @code{current-time-list} is @code{nil}.) @item (20614 64555 902289 872000) -last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC. +last had its status changed on October 23, 2012, at 20:20:59.902289872 UTC@. +(This timestamp is @code{(1351023659902289872 . 1000000000)} +if @code{current-time-list} is @code{nil}.) @item 122295 is 122295 bytes long. (It may not contain 122295 characters, though, @@ -2083,6 +2106,9 @@ directory. Therefore, Emacs considers a file name as having two main parts: the @dfn{directory name} part, and the @dfn{nondirectory} part (or @dfn{file name within the directory}). Either part may be empty. Concatenating these two parts reproduces the original file name. +@footnote{Emacs follows the GNU convention to use the term @emph{file name} +instead of the term @emph{pathname}. We use the term @emph{path} only for +search paths, which are lists of directory names.} On most systems, the directory part is everything up to and including the last slash (backslash is also allowed in input on MS-DOS or @@ -2227,6 +2253,19 @@ and @code{file-name-nondirectory}. For example, @end example @end defun +@defun file-name-split filename +This function splits a file name into its components, and can be +thought of as the inverse of @code{string-join} with the appropriate +directory separator. For example, + +@example +(file-name-split "/tmp/foo.txt") + @result{} ("" "tmp" "foo.txt") +(string-join (file-name-split "/tmp/foo.txt") "/") + @result{} "/tmp/foo.txt" +@end example +@end defun + @node Relative File Names @subsection Absolute and Relative File Names @cindex absolute file name @@ -2406,6 +2445,15 @@ You can use this function for directory names and for file names, because it recognizes abbreviations even as part of the name. @end defun +@defun file-parent-directory filename +This function returns the directory name of the parent directory of +@var{filename}. If @var{filename} is at the root directory of the +filesystem, it returns @code{nil}. A relative @var{filename} is +assumed to be relative to @code{default-directory}, and the return +value will also be relative in that case. If the return value is +non-@code{nil}, it ends in a slash. +@end defun + @node File Name Expansion @subsection Functions that Expand Filenames @cindex expansion of file names @@ -3076,10 +3124,16 @@ except those two. It is useful as the @var{match-regexp} argument to returns @code{nil}, if directory @samp{/foo} is empty. @end defvr -@defun file-expand-wildcards pattern &optional full +@defun file-expand-wildcards pattern &optional full regexp This function expands the wildcard pattern @var{pattern}, returning a list of file names that match it. +@var{pattern} is, by default, a ``glob''/wildcard string, e.g., +@samp{"/tmp/*.png"} or @samp{"/*/*/foo.png"}, but can also be a +regular expression if the optional @var{regexp} parameter is non-nil. +In any case, the matches are applied per sub-directory, so a match +can't span a parent/sub directory. + If @var{pattern} is written as an absolute file name, the values are absolute also. @@ -3278,8 +3332,8 @@ first, before handlers for jobs such as remote file access. @ifnottex @noindent -@code{access-file}, @code{add-name-to-file}, -@code{byte-compiler-base-file-name},@* +@code{abbreviate-file-name}, @code{access-file}, +@code{add-name-to-file}, @code{byte-compiler-base-file-name},@* @code{copy-directory}, @code{copy-file}, @code{delete-directory}, @code{delete-file}, @code{diff-latest-backup-file}, @@ -3314,6 +3368,7 @@ first, before handlers for jobs such as remote file access. @code{get-file-buffer}, @code{insert-directory}, @code{insert-file-contents},@* +@code{list-system-processes}, @code{load}, @code{lock-file}, @code{make-auto-save-file-name}, @code{make-directory}, @@ -3322,7 +3377,7 @@ first, before handlers for jobs such as remote file access. @code{make-nearby-temp-file}, @code{make-process}, @code{make-symbolic-link},@* -@code{process-file}, +@code{process-attributes}, @code{process-file}, @code{rename-file}, @code{set-file-acl}, @code{set-file-modes}, @code{set-file-selinux-context}, @code{set-file-times}, @code{set-visited-file-modtime}, @code{shell-command}, @@ -3338,7 +3393,8 @@ first, before handlers for jobs such as remote file access. @iftex @noindent @flushleft -@code{access-file}, @code{add-name-to-file}, +@code{abbreviate-file-name}, @code{access-file}, +@code{add-name-to-file}, @code{byte-com@discretionary{}{}{}piler-base-file-name}, @code{copy-directory}, @code{copy-file}, @code{delete-directory}, @code{delete-file}, @@ -3374,6 +3430,7 @@ first, before handlers for jobs such as remote file access. @code{get-file-buffer}, @code{insert-directory}, @code{insert-file-contents}, +@code{list-system-processes}, @code{load}, @code{lock-file}, @code{make-auto-save-file-name}, @code{make-direc@discretionary{}{}{}tory}, @@ -3382,7 +3439,7 @@ first, before handlers for jobs such as remote file access. @code{make-nearby-temp-file}, @code{make-process}, @code{make-symbolic-link}, -@code{process-file}, +@code{process-attributes}, @code{process-file}, @code{rename-file}, @code{set-file-acl}, @code{set-file-modes}, @code{set-file-selinux-context}, @code{set-file-times}, @code{set-visited-file-modtime}, @code{shell-command}, diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index fa033add0db..262b86672da 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -60,6 +60,8 @@ The frame is displayed on a GNUstep or Macintosh Cocoa graphical terminal. @item pc The frame is displayed on an MS-DOS terminal. +@item pgtk +The frame is displayed using pure GTK facilities. @end table @end defun @@ -105,6 +107,7 @@ window of another Emacs frame. @xref{Child Frames}. * Dialog Boxes:: Displaying a box to ask yes or no. * Pointer Shape:: Specifying the shape of the mouse pointer. * Window System Selections:: Transferring text to and from other X clients. +* Yanking Media:: Yanking things that aren't plain text. * Drag and Drop:: Internals of Drag-and-Drop implementation. * Color Names:: Getting the definitions of color names. * Text Terminal Colors:: Defining colors for text terminals. @@ -170,7 +173,9 @@ usually not run for the initial frame, since Emacs reads the initial file only after creating that frame. However, if the initial frame is specified to use a separate minibuffer frame (@pxref{Minibuffers and Frames}), the functions will be run for both, the minibuffer-less and -the minibuffer frame. +the minibuffer frame. Alternatively, you can add functions to these +hooks in your ``early init file'' (@pxref{Init File}), in which case +they will be in effect for the initial frame as well. @defvar frame-inherited-parameters This variable specifies the list of frame parameters that a newly @@ -213,7 +218,8 @@ The terminal and keyboard coding systems used on the terminal. @item The kind of display associated with the terminal. This is the symbol returned by the function @code{terminal-live-p} (i.e., @code{x}, -@code{t}, @code{w32}, @code{ns}, or @code{pc}). @xref{Frames}. +@code{t}, @code{w32}, @code{ns}, @code{pc}, @code{haiku}, or @code{pgtk}). +@xref{Frames}. @item A list of terminal parameters. @xref{Terminal Parameters}. @@ -452,6 +458,18 @@ monitor, the same string as returned by the function @var{display} should be the name of an X display (a string). @end deffn +@cindex monitor change functions +@defvar display-monitors-changed-functions +This variable is an abnormal hook run when the monitor configuration +changes, which can happen if a monitor is rotated, moved, added or +removed from a multiple-monitor setup, if the primary monitor changes, +or if the resolution of a monitor changes. It is called with a single +argument consisting of the terminal on which the monitor configuration +changed. Programs should call @code{display-monitor-attributes-list} +with the terminal as the argument to retrieve the new monitor +configuration on that terminal. +@end defvar + @node Frame Geometry @section Frame Geometry @cindex frame geometry @@ -677,9 +695,9 @@ The position of the top left corner of the native frame specifies the indicate that position for the various builds: @itemize @w{} -@item (1) non-toolkit and terminal frames +@item (1) non-toolkit, Haiku, and terminal frames -@item (2) Lucid, Motif and MS-Windows frames +@item (2) Lucid, Motif, and MS-Windows frames @item (3) GTK+ and NS frames @end itemize @@ -1728,15 +1746,16 @@ fit will be clipped by the window manager. @item fullscreen This parameter specifies whether to maximize the frame's width, height or both. Its value can be @code{fullwidth}, @code{fullheight}, -@code{fullboth}, or @code{maximized}. A @dfn{fullwidth} frame is as -wide as possible, a @dfn{fullheight} frame is as tall as possible, and -a @dfn{fullboth} frame is both as wide and as tall as possible. A -@dfn{maximized} frame is like a ``fullboth'' frame, except that it usually -keeps its title bar and the buttons for resizing -and closing the frame. Also, maximized frames typically avoid hiding -any task bar or panels displayed on the desktop. A ``fullboth'' frame, -on the other hand, usually omits the title bar and occupies the entire -available screen space. +@code{fullboth}, or @code{maximized}.@footnote{On PGTK frames, setting +the values @code{fullheight} and @code{fullwidth} has no effect.} A +@dfn{fullwidth} frame is as wide as possible, a @dfn{fullheight} frame +is as tall as possible, and a @dfn{fullboth} frame is both as wide and +as tall as possible. A @dfn{maximized} frame is like a ``fullboth'' +frame, except that it usually keeps its title bar and the buttons for +resizing and closing the frame. Also, maximized frames typically +avoid hiding any task bar or panels displayed on the desktop. A +``fullboth'' frame, on the other hand, usually omits the title bar and +occupies the entire available screen space. Full-height and full-width frames are more similar to maximized frames in this regard. However, these typically display an external @@ -2160,6 +2179,21 @@ prevent hanging with those window managers. If non-@code{nil}, the frame is visible on all virtual desktops on systems with virtual desktops. +@vindex shaded@r{, a frame parameter} +@item shaded +If non-@code{nil}, tell the window manager to display the frame in a +way that its contents are hidden, leaving only the title bar. + +@vindex use-frame-synchronization@r{, a frame parameter} +@item use-frame-synchronization +If non-@code{nil}, synchronize the frame redisplay with the refresh +rate of the monitor to avoid graphics tearing. At present, this is +only implemented on Haiku and the X window system inside no-toolkit +and X toolkit builds, does not work correctly with toolkit scroll +bars, and requires a compositing manager supporting the relevant +display synchronization protocols. The @code{synchronizeResize} X +resource must also be set to the string @code{"extended"}. + @vindex inhibit-double-buffering@r{, a frame parameter} @item inhibit-double-buffering If non-@code{nil}, the frame is drawn to the screen without double @@ -2190,7 +2224,10 @@ either via @code{focus-follows-mouse} (@pxref{Input Focus}) or @code{mouse-autoselect-window} (@pxref{Mouse Window Auto-selection}). This may have the unwanted side-effect that a user cannot scroll a non-selected frame with the mouse. Some window managers may not honor -this parameter. +this parameter. On Haiku, it also has the side-effect that the window +will not be able to receive any keyboard input from the user, not even +if the user switches to the frame using the key combination +@kbd{Alt-@key{TAB}}. @vindex undecorated@r{, a frame parameter} @item undecorated @@ -2351,7 +2388,10 @@ driver for OTF and TTF fonts with text shaping by the Uniscribe engine), and @code{harfbuzz} (font driver for OTF and TTF fonts with HarfBuzz text shaping) (@pxref{Windows Fonts,,, emacs, The GNU Emacs Manual}). The @code{harfbuzz} driver is similarly recommended. On -other systems, there is only one available font backend, so it does +Haiku, there can be several font drivers (@pxref{Haiku Fonts,,, emacs, +The GNU Emacs Manual}). + +On other systems, there is only one available font backend, so it does not make sense to modify this frame parameter. @vindex background-mode@r{, a frame parameter} @@ -2419,6 +2459,16 @@ opacity when it is not selected. Some window systems do not support the @code{alpha} parameter for child frames (@pxref{Child Frames}). + +@vindex alpha-background@r{, a frame parameter} +@item alpha-background +@cindex opacity, frame +@cindex transparency, frame +Sets the background transparency of the frame. Unlike the @code{alpha} +frame parameter, this only controls the transparency of the background +while keeping foreground elements such as text fully opaque. It +should be an integer between 0 and 100, where 0 means +completely transparent and 100 means completely opaque (default). @end table The following frame parameters are semi-obsolete in that they are @@ -3246,12 +3296,16 @@ parent frame's window-system window. @cindex reparent frame @cindex nest frame - The @code{parent-frame} parameter can be changed at any time. Setting -it to another frame @dfn{reparents} the child frame. Setting it to -another child frame makes the frame a @dfn{nested} child frame. Setting -it to @code{nil} restores the frame's status as a top-level frame---a -frame whose window-system window is a child of its display's root -window. + The @code{parent-frame} parameter can be changed at any time. +Setting it to another frame @dfn{reparents} the child frame. Setting +it to another child frame makes the frame a @dfn{nested} child frame. +Setting it to @code{nil} restores the frame's status as a top-level +frame---a frame whose window-system window is a child of its display's +root window.@footnote{On Haiku, child frames are only visible when a +parent frame is active, owing to a limitation of the Haiku windowing +system. Owing to the same limitation, child frames are only +guaranteed to appear above their top-level parent; that is to say, the +top-most frame in the hierarchy, which does not have a parent frame.} Since child frames can be arbitrarily nested, a frame can be both a child and a parent frame. Also, the relative roles of child and parent @@ -3479,10 +3533,18 @@ enabled. Typically, @var{body} would use @code{read-event} to read the motion events and modify the display accordingly. @xref{Motion Events}, for the format of mouse motion events. -The value of @code{track-mouse} is that of the last form in @var{body}. -You should design @var{body} to return when it sees the up-event that -indicates the release of the button, or whatever kind of event means -it is time to stop tracking. +The value of @code{track-mouse} is that of the last form in +@var{body}. You should design @var{body} to return when it sees the +up-event that indicates the release of the button, or whatever kind of +event means it is time to stop tracking. Its value also controls how +mouse events are reported while a mouse button is held down: if it is +@code{dropping} or @code{drag-source}, the motion events are reported +relative to the frame underneath the pointer. If there is no such +frame, the events will be reported relative to the frame the mouse +buttons were first pressed on. In addition, the @code{posn-window} of +the mouse position list will be @code{nil} if the value is +@code{drag-source}. This is useful to determine if a frame is not +directly visible underneath the mouse pointer. The @code{track-mouse} form causes Emacs to generate mouse motion events by binding the variable @code{track-mouse} to a @@ -3726,6 +3788,13 @@ still use a menu keymap to implement it. To make the contents vary, add a hook function to @code{menu-bar-update-hook} to update the contents of the menu keymap as necessary. +@defvar x-pre-popup-menu-hook + A normal hook run immediately before a pop-up menu is displayed, +either directly by calling @code{x-popup-menu}, or through a menu +keymap. It won't be called if @code{x-popup-menu} returns for some +other reason without displaying a pop-up menu. +@end defvar + @node Dialog Boxes @section Dialog Boxes @cindex dialog boxes @@ -3829,8 +3898,9 @@ in the buffer. The default is to use the @code{arrow} (non-text) pointer style. @end defopt - When using X, you can specify what the @code{text} pointer style -really looks like by setting the variable @code{x-pointer-shape}. + When using some window systems, you can specify what the @code{text} +pointer style really looks like by setting the variable +@code{x-pointer-shape}. @defvar x-pointer-shape This variable specifies the pointer shape to use ordinarily in the @@ -3878,11 +3948,18 @@ upper-case names, in accord with X Window System conventions. If @var{type} is @code{nil}, that stands for @code{PRIMARY}. If @var{data} is @code{nil}, it means to clear out the selection. -Otherwise, @var{data} may be a string, a symbol, an integer (or a cons -of two integers or list of two integers), an overlay, or a cons of two -markers pointing to the same buffer. An overlay or a pair of markers -stands for text in the overlay or between the markers. The argument -@var{data} may also be a vector of valid non-vector selection values. +Otherwise, @var{data} may be a string, a symbol, an integer, an +overlay, or a cons of two markers pointing to the same buffer. An +overlay or a pair of markers stands for text in the overlay or between +the markers. The argument @var{data} may also be a vector of valid +non-vector selection values. + +If @var{data} is a string, then its text properties can specify values +used for individual data types. For example, if @var{data} has a +property named @code{text/uri-list}, then a call to +@code{gui-get-selection} with the data type @code{text/uri-list} will +result in the value of that property being used instead of @var{data} +itself. This function returns @var{data}. @end deffn @@ -3925,20 +4002,91 @@ For backward compatibility, there are obsolete aliases names of @code{gui-get-selection} and @code{gui-set-selection} before Emacs 25.1. +@node Yanking Media +@section Yanking Media + + If you choose, for instance, ``Copy Image'' in a web browser, that +image is put onto the clipboard, and Emacs can access it via +@code{gui-get-selection}. But in general, inserting image data into +an arbitrary buffer isn't very useful---you can't really do much with +it by default. + + So Emacs has a system to let modes register handlers for these +``complicated'' selections. + +@defun yank-media-handler types handler +@var{types} can be a @acronym{MIME} media type symbol, a regexp to +match these, or a list of these symbols and regexps. For instance: + +@example +(yank-media-handler 'text/html #'my-html-handler) +(yank-media-handler "image/.*" #'my-image-handler) +@end example + +A mode can register as many handlers as required. + + The @var{handler} function is called with two parameters: The +@acronym{MIME} media type symbol and the data (as a string). The +handler should then insert the object into the buffer, or save it, or +do whatever is appropriate for the mode. +@end defun + + The @code{yank-media} command will consult the registered handlers in +the current buffer, compare that with the available media types on the +clipboard, and then pass on the matching selection to the handler (if +any). If there's more than one matching selection, the user is +queried first. + + The @code{yank-media-types} command can be used to explore the +clipboard/primary selection. It lists all the media types that are +currently available, and can be handy when creating handlers---to see +what data is actually available. Some applications put a surprising +amount of different data types on the clipboard. + @node Drag and Drop @section Drag and Drop @cindex drag and drop + When the user drops something from another application over Emacs, +Emacs will try to insert any text and open any URL that was dropped. +If text was dropped, then it will always be inserted at the location +of the mouse pointer when the drop happened, or saved in the kill ring +if insertion failed (which can happen if the buffer is read-only). If +it was an URL, then Emacs tries to call an appropriate handler +function by first matching the URL against regexps defined in +@code{dnd-protocol-alist}, and then against @code{browse-url-handlers} +and @code{browse-url-default-handlers}, and failing that, inserting +the URL as plain text. + +@defvar dnd-protocol-alist + This variable is a list of cons cells of the form +@w{@code{(@var{pattern} . @var{action})}}. @var{pattern} is a regexp +that URLs are matched against after being dropped. @var{action} is a +function that is called with two arguments should a URL being dropped +match @var{pattern}: the URL being dropped, and the action being +performed for the drop (one of the symbols @code{copy}, @code{move}, +@code{link}, @code{private} or @code{ask}). +@end defvar + +@cindex drag and drop, X +@cindex drag and drop, other formats + Emacs implements drag-and-drop for text and URLs individually for +each window system, and does not by default support the dropping of +anything else. Code that wishes to support the dropping of content +types not supported by Emacs can utilize the X-specific interface +described below: + @vindex x-dnd-test-function @vindex x-dnd-known-types - When a user drags something from another application over Emacs, that other -application expects Emacs to tell it if Emacs can handle the data that is -dragged. The variable @code{x-dnd-test-function} is used by Emacs to determine -what to reply. The default value is @code{x-dnd-default-test-function} -which accepts drops if the type of the data to be dropped is present in -@code{x-dnd-known-types}. You can customize @code{x-dnd-test-function} and/or -@code{x-dnd-known-types} if you want Emacs to accept or reject drops based -on some other criteria. + When a user drags something from another application over Emacs on +the X Window System, that other application expects Emacs to tell it +if Emacs can handle the data that was dragged. The variable +@code{x-dnd-test-function} is used by Emacs to determine what to +reply. The default value is @code{x-dnd-default-test-function} which +accepts drops if the type of the data to be dropped is present in +@code{x-dnd-known-types}. You can customize +@code{x-dnd-test-function} and/or @code{x-dnd-known-types} if you want +Emacs to accept or reject drops based on some other criteria. @vindex x-dnd-types-alist If you want to change the way Emacs handles drop of different types @@ -3946,16 +4094,228 @@ or add a new type, customize @code{x-dnd-types-alist}. This requires detailed knowledge of what types other applications use for drag and drop. -@vindex dnd-protocol-alist -@vindex browse-url-handlers -@vindex browse-url-default-handlers - When an URL is dropped on Emacs it may be a file, but it may also be -another URL type (https, etc.). Emacs first checks -@code{dnd-protocol-alist} to determine what to do with the URL@. If -there is no match there, Emacs looks for a match in -@code{browse-url-handlers} and @code{browse-url-default-handlers}. If -still no match has been found, the text for the URL is inserted. If -you want to alter Emacs behavior, you can customize these variables. + Those data types are typically implemented as special data types an +X selection provided by the other application can be converted to. +They can either be the same data types that are typically accepted by +@code{gui-set-selection}, or they can be MIME types, depending on the +specific drag-n-drop protocol being used. Plain text may be +@code{"STRING"} or @code{"text/plain"}, for example. + +@vindex x-dnd-direct-save-function + However, @code{x-dnd-types-alist} does not handle a special kind of +drop sent by a program which wants Emacs to save a file in a location +Emacs must determine by itself. These drops are handled via the +variable @code{x-dnd-direct-save-function}, which should be a function +that accepts two arguments. If the first argument is non-@code{nil}, +then the second argument is a string describing the name (with no +leading directory) that the other program recommends the file be saved +under, and the function should return the complete file name under +which it will be saved. Otherwise, the file has already been saved, +and the second argument is the complete name of the file. The +function should then perform whatever action is appropriate (i.e., +open the file or refresh the directory listing.) + +@cindex initiating drag-and-drop + On capable window systems, Emacs also supports dragging contents +from its frames to windows of other applications. + +@cindex drop target, in drag-and-drop operations +@defun dnd-begin-text-drag text &optional frame action allow-same-frame +This function begins dragging text from @var{frame} to another program +(known as the @dfn{drop target}), and returns the result of +drag-and-drop operation when the text is dropped or the drag-and-drop +operation is canceled. @var{text} is the text that will be inserted +by the drop target. + +@var{action} must be one of the symbols @code{copy} or @code{move}, +where @code{copy} means that @var{text} should be inserted by the drop +target, and @code{move} means the same as @code{copy}, but in addition +the caller may have to delete @var{text} from its source as explained +below. + +@var{frame} is the frame where the mouse is currently held down, or +@code{nil}, which means to use the selected frame. This function may +return immediately if no mouse buttons are held down, so it should be +only called immediately after a @code{down-mouse-1} or similar event +(@pxref{Mouse Events}), with @var{frame} set to the frame where that +event was generated (@pxref{Click Events}). + +@var{allow-same-frame} specifies whether or not drops on top of +@var{frame} itself are to be ignored. + +The return value specifies the action that the drop target actually +performed, and optionally what the caller should do. It can be one of +the following symbols: + +@table @code +@item copy +The drop target inserted the dropped text. + +@item move +The drop target inserted the dropped text, but in addition the caller +should delete @var{text} from wherever it originated, such as its +buffer. + +@item private +The drop target performed some other unspecified action. + +@item nil +The drag-and-drop operation was canceled. +@end table + +@end defun + +@defun dnd-begin-file-drag file &optional frame action allow-same-frame +This function begins dragging @var{file} from @var{frame} to another +program, and returns the result of the drag-and-drop operation when +the file is dropped or the drag-and-drop operation is canceled. + +If @var{file} is a remote file, then a temporary copy will be made. + +@var{action} must be one of the symbols @code{copy}, @code{move} or +@code{link}, where @code{copy} means that @var{file} should be opened +or copied by the drop target, @code{move} means the drop target should +move the file to another location, and @code{link} means the drop +target should create a symbolic link to @var{file}. It is an error to +specify @code{link} as the action if @var{file} is a remote file. + +@var{frame} and @var{allow-same-frame} have the same meaning as in +@code{dnd-begin-text-drag}. + +The return value is the action that the drop target actually +performed, which can be one of the following symbols: + +@table @code +@item copy +The drop target opened or copied @var{file} to a different location. + +@item move +The drop target moved @var{file} to a different location. + +@item link +The drop target (usually a file manager) created a symbolic link to +@var{file}. + +@item private +The drop target performed some other unspecified action. + +@item nil +The drag-and-drop operation was canceled. +@end table + +@end defun + +@defun dnd-begin-drag-files files &optional frame action allow-same-frame +This function is like @code{dnd-begin-file-drag}, except that +@var{files} is a list of files. If the drop target doesn't support +dropping multiple files, then the first file will be used instead. +@end defun + +@defun dnd-direct-save file name &optional frame allow-same-frame +This function is similar to @code{dnd-begin-file-drag} (with the +default action of copy), but instead of specifying the action you +specify the name of the copy created by the target program in +@code{name}. +@end defun + +@cindex initiating drag-and-drop, low-level + The high-level interfaces described above are implemented on top of +a lower-level primitive. If you need to drag content other than files +or text, use the low-level interface @code{x-begin-drag} +instead. However, using it will require detailed knowledge of the +data types and actions used by the programs to transfer content via +drag-and-drop on each platform you want to support. + +@defun x-begin-drag targets &optional action frame return-frame allow-current-frame follow-tooltip +This function begins a drag from @var{frame}, and returns when the +drag-and-drop operation ends, either because the drop was successful, +or because the drop was rejected. The drop occurs when all mouse +buttons are released on top of an X window other than @var{frame} (the +@dfn{drop target}), or any X window if @var{allow-current-frame} is +non-@code{nil}. If no mouse buttons are held down when the +drag-and-drop operation begins, this function may immediately return +@code{nil}. + +@var{targets} is a list of strings describing selection targets, much +like the @var{data-type} argument to @code{gui-get-selection}, that +the drop target can request from Emacs (@pxref{Window System +Selections}). + +@var{action} is a symbol describing the action recommended to the +target. It can either be @code{XdndActionCopy}, which +means to copy the contents of the selection @code{XdndSelection} to +the drop target; or @code{XdndActionMove}, which means copy as with +@code{XdndActionCopy}, and in addition the caller should delete +whatever was stored in that selection after copying it. + +@var{action} may also be an alist which associates between symbols +describing the available actions, and strings that the drop target is +expected to present to the user to choose between the available +actions. + +If @var{return-frame} is non-@code{nil} and the mouse moves over an +Emacs frame after first moving out of @var{frame}, then the frame to +which the mouse moves will be returned immediately. If +@var{return-frame} is the symbol @code{now}, then any frame underneath +the mouse pointer will be returned without waiting for the mouse to +first move out of @var{frame}. @var{return-frame} is useful when you +want to treat dragging content from one frame to another specially, +while also being able to drag content to other programs, but it is not +guaranteed to work on all systems and with all window managers. + +If @var{follow-tooltip} is non-@code{nil}, the position of any tooltip +(such as one shown by @code{tooltip-show}) will follow the location of +the mouse pointer whenever it moves during the drag-and-drop +operation. The tooltip will be hidden once all mouse buttons are +released. + +If the drop was rejected or no drop target was found, this function +returns @code{nil}. Otherwise, it returns a symbol describing the +action the target chose to perform, which can differ from @var{action} +if that isn't supported by the drop target. @code{XdndActionPrivate} +is also a valid return value in addition to @code{XdndActionCopy} and +@code{XdndActionMove}; it means that the drop target chose to perform +an unspecified action, and no further processing is required by the +caller. + +The caller must cooperate with the target to fully perform the action +chosen by the target. For example, callers should delete the buffer +text that was dragged if this function returns @code{XdndActionMove}. +@end defun + +@cindex drag and drop protocols, X + + On X Windows, several different drag-and-drop protocols are +supported by @code{x-begin-drag}. When dragging content that is known +to not be supported by a specific drag-and-drop protocol, it might be +desirable to turn that protocol off, by changing the values of the +following variables: + +@defvar x-dnd-disable-motif-protocol +When this is non-@code{nil}, the Motif drag and drop protocols are +disabled, and dropping onto programs that only understand them will +not work. +@end defvar + +@defvar x-dnd-use-offix-drop +When this is @code{nil}, the OffiX (old KDE) drag and drop protocol is +disabled. When this is the symbol @code{files}, the OffiX protocol +will only be used if @code{"FILE_NAME"} is one of the targets given to +@code{x-begin-drag}. Any other value means to use the OffiX protocol +to drop all supported content. +@end defvar + +@defvar x-dnd-use-unsupported-drop +When one of the @code{"STRING"}, @code{"UTF8_STRING"}, +@code{"COMPOUND_TEXT"} or @code{"TEXT"} targets is present in the list +given to @code{x-begin-drag}, Emacs will try to use synthesized mouse +events and the primary selection to insert the text if the drop target +doesn't support any drag-and-drop protocol at all. + +A side effect is that Emacs will become the owner of the primary +selection upon such a drop. If that is not desired, then the drop +emulation can be disabled by setting this variable to @code{nil}. +@end defvar @node Color Names @section Color Names diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index a70364c3cb5..983dfe2ec59 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -22,6 +22,7 @@ define them. * Function Cells:: Accessing or setting the function definition of a symbol. * Closures:: Functions that enclose a lexical environment. +* OClosures:: Function objects * Advising Functions:: Adding to the definition of a function. * Obsolete Functions:: Declaring functions obsolete. * Inline Functions:: Functions that the compiler will expand inline. @@ -145,7 +146,12 @@ function: This function returns @code{t} if @var{object} is any kind of function, i.e., can be passed to @code{funcall}. Note that @code{functionp} returns @code{t} for symbols that are function names, -and returns @code{nil} for special forms. +and returns @code{nil} for symbols that are macros or special forms. + +If @var{object} is not a function, this function ordinarily returns +@code{nil}. However, the representation of function objects is +complicated, and for efficiency reasons in rare cases this function +can return @code{t} even when @var{object} is not a function. @end defun It is also possible to find out how many arguments an arbitrary @@ -211,6 +217,16 @@ function. For example: @end example @end defun +@defun compiled-function-p object +This function returns @code{t} if @var{object} is a function object +that is not in the form of ELisp source code but something like +machine code or byte code instead. More specifically it returns +@code{t} if the function is built-in (a.k.a.@: ``primitive'', +@pxref{What Is a Function}), or byte-compiled (@pxref{Byte +Compilation}), or natively-compiled (@pxref{Native Compilation}), or +a function loaded from a dynamic module (@pxref{Dynamic Modules}). +@end defun + @defun subr-arity subr This works like @code{func-arity}, but only for built-in functions and without symbol indirection. It signals an error for non-built-in @@ -669,6 +685,22 @@ purposes, it is better to use @code{fset}, which does not keep such records. @xref{Function Cells}. @end defun +@defun function-alias-p object &optional noerror +Checks whether @var{object} is a function alias. If it is, it returns +a list of symbols representing the function alias chain, else +@code{nil}. For instance, if @code{a} is an alias for @code{b}, and +@code{b} is an alias for @code{c}: + +@example +(function-alias-p 'a) + @result{} (b c) +@end example + +If there's a loop in the definitions, an error will be signalled. If +@var{noerror} is non-@code{nil}, the non-looping parts of the chain is +returned instead. +@end defun + You cannot create a new primitive function with @code{defun} or @code{defalias}, but you can use them to change the function definition of any symbol, even one such as @code{car} or @code{x-popup-menu} whose @@ -969,14 +1001,14 @@ side-effects only---the values it returns are ignored, not collected into a list. @code{mapc} always returns @var{sequence}. @end defun -@defun mapconcat function sequence separator +@defun mapconcat function sequence &optional separator @code{mapconcat} applies @var{function} to each element of @var{sequence}; the results, which must be sequences of characters (strings, vectors, or lists), are concatenated into a single string return value. Between each pair of result sequences, @code{mapconcat} inserts the characters from @var{separator}, which also must be a -string, or a vector or list of characters. @xref{Sequences Arrays -Vectors}. +string, or a vector or list of characters; a @code{nil} value is +treated as the empty string. @xref{Sequences Arrays Vectors}. The argument @var{function} must be a function that can take one argument and returns a sequence of characters: a string, a vector, or @@ -994,8 +1026,7 @@ string. @group (mapconcat (lambda (x) (format "%c" (1+ x))) - "HAL-8000" - "") + "HAL-8000") @result{} "IBM.9111" @end group @end example @@ -1494,6 +1525,116 @@ exposed to the rest of the Lisp world is considered an internal implementation detail. For this reason, we recommend against directly examining or altering the structure of closure objects. +@node OClosures +@section Open Closures + +Traditionally, functions are opaque objects which offer no other +functionality but to call them. Emacs Lisp functions aren't fully +opaque since you can extract some info out of them such as their +docstring, their arglist, or their interactive spec, but they are +mostly opaque. This is usually what we want, but occasionally we need +functions to expose a bit more information about themselves. + +OClosures are functions which carry additional type information, +and expose some information in the form of slots which you can access +via accessor functions. + +They are defined in two steps: first @code{oclosure-define} is used to +define new OClosure types by specifying the slots carried by those +OClosures, and then @code{oclosure-lambda} is used to create an +OClosure object of a given type. + +Say we want to define keyboard macros, i.e. interactive functions +which re-execute a sequence of key events. You could do it with +a plain function as follows: +@example +(defun kbd-macro (key-sequence) + (lambda (&optional arg) + (interactive "P") + (execute-kbd-macro key-sequence arg))) +@end example +But with such a definition there is no easy way to extract the +@var{key-sequence} from that function, for example to print it. + +We can solve this problem using OClosures as follows. First we define +the type of our keyboard macros (to which we decided to add +a @code{counter} slot while at it): +@example +(oclosure-define kbd-macro + "Keyboard macro." + keys (counter :mutable t)) +@end example +After which we can rewrite our @code{kbd-macro} function: +@example +(defun kbd-macro (key-sequence) + (oclosure-lambda (kbd-macro (keys key-sequence) (counter 0)) + (&optional arg) + (interactive "p") + (execute-kbd-macro keys arg) + (setq counter (1+ counter)))) +@end example +As you can see, the @code{keys} and @code{counter} slots of the +OClosure can be accessed as local variables from within the body +of the OClosure. But we can now also access them from outside of the +body of the OClosure, for example to describe a keyboard macro: +@example +(defun describe-kbd-macro (km) + (if (not (eq 'kbd-macro (oclosure-type km))) + (message "Not a keyboard macro") + (let ((keys (kbd-macro--keys km)) + (counter (kbd-macro--counter km))) + (message "Keys=%S, called %d times" keys counter)))) +@end example +Where @code{kbd-macro--keys} and @code{kbd-macro--counter} are +accessor functions generated by the @code{oclosure-define} macro. + +@defmac oclosure-define name &optional docstring &rest slots +This macro defines a new OClosure type along with accessor functions +for its slots. @var{name} can be a symbol (the name of +the new type), or a list of the form @code{(@var{name} . @var{type-props})} in +which case @var{type-props} is a list of additional properties. +@var{slots} is a list of slot descriptions where each slot can be +either a symbol (the name of the slot) or it can be of the form +@code{(@var{slot-name} . @var{slot-props})} where @var{slot-props} is +a property list. + +For each slot, the macro creates an accessor function named +@code{@var{name}--@var{slot-name}}. By default slots are immutable. +If you need a slot to be mutable, you need to specify it with the +@code{:mutable} slot property, after which it can be mutated for +example with @code{setf}. + +Beside slot accessors, the macro can create a predicate and +functional update functions according to @var{type-props}: +a @code{(:predicate @var{pred-name})} in the @var{type-props} causes +the definition of a predicate function under the name @var{pred-name}, +and @code{(:copier @var{copier-name} @var{copier-arglist})} causes the +definition of a functional update function which takes an OClosure of +type @var{name} as first argument and returns a copy of it with the +slots named in @var{copier-arglist} modified to the value passed in the +corresponding argument. +@end defmac + +@defmac oclosure-lambda (type . slots) arglist &rest body +This macro creates an anonymous OClosure of type @var{type}. +@var{slots} should be a list of elements of the form @code{(@var{slot-name} +@var{exp})}. +At run time, each @var{exp} is evaluated, in order, after which +the OClosure is created with its slots initialized with the +resulting values. + +When called as a function, the OClosure will accept arguments +according to @var{arglist} and will execute the code in @var{body}. +@var{body} can refer to the value of any of its slot directly as if it +were a local variable that had been captured by static scoping. +@end defmac + +@defun oclosure-type object +This function returns the OClosure type (a symbol) of @var{object} if it is an +OClosure, and @code{nil} otherwise. +@end defun + + @node Advising Functions @section Advising Emacs Lisp Functions @cindex advising functions @@ -1586,6 +1727,7 @@ ways to do it. The added function is also called a piece of @emph{advice}. * Advising Named Functions:: Advising named functions. * Advice Combinators:: Ways to compose advice. * Porting Old Advice:: Adapting code using the old defadvice. +* Advice and Byte Code:: Not all functions can be advised. @end menu @node Core Advising Primitives @@ -2007,6 +2149,37 @@ changing @code{ad-return-value}, whereas new @code{:after} advice cannot, so when porting such old @code{after} advice, you'll need to turn it into new @code{:around} or @code{:filter-return} advice instead. +@c This is its own node because we link to it from *Help* buffers. +@node Advice and Byte Code +@subsection Advice and Byte Code +@cindex compiler macros, advising +@cindex @code{byte-compile} and @code{byte-optimize}, advising + + Not all functions can be reliably advised. The byte compiler may +choose to replace a call to a function with a sequence of instructions +that doesn't call the function you were interested in altering. + +This usually happens due to one of the three following mechanisms: + +@table @asis +@item @code{byte-compile} properties +If a function's symbol has a @code{byte-compile} property, that +property will be used instead of the symbol's function definition. +@xref{Compilation Functions}. + +@item @code{byte-optimize} properties +If a function's symbol has a @code{byte-optimize} property, the byte +compiler may rewrite the function arguments, or decide to use a +different function altogether. + +@item @code{compiler-macro} declare forms +A function can have a special @code{compiler-macro} @code{declare} +form in its definition (@pxref{Declare Form}) that defines an +@dfn{expander} to call when compiling the function. The expander +could then cause the produced byte-code not to call the original +function. +@end table + @node Obsolete Functions @section Declaring Functions Obsolete @cindex obsolete functions @@ -2138,8 +2311,8 @@ worry about how many times the body uses the arguments, as you do for macros. Alternatively, you can define a function by providing the code which -will inline it as a compiler macro. The following macros make this -possible. +will inline it as a compiler macro (@pxref{Declare Form}). The +following macros make this possible. @c FIXME: Can define-inline use the interactive spec? @defmac define-inline name args [doc] [declare] body@dots{} @@ -2295,6 +2468,7 @@ which case the warning message gives no extra details). @var{when} should be a string indicating when the function or macro was first made obsolete. +@cindex compiler macro @item (compiler-macro @var{expander}) This can only be used for functions, and tells the compiler to use @var{expander} as an optimization function. When encountering a call to the @@ -2334,6 +2508,10 @@ the current buffer. Specify that this command is meant to be applicable for @var{modes} only. +@item (interactive-args @var{arg} ...) +Specify the arguments that should be stored for @code{repeat-command}. +Each @var{arg} is on the form @code{@var{argument-name} @var{form}}. + @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} diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi index 34eda45b236..25a56bd7151 100644 --- a/doc/lispref/hash.texi +++ b/doc/lispref/hash.texi @@ -287,9 +287,13 @@ If two objects @var{obj1} and @var{obj2} are @code{equal}, then are the same integer. If the two objects are not @code{equal}, the values returned by -@code{sxhash-equal} are usually different, but not always; once in a -rare while, by luck, you will encounter two distinct-looking objects -that give the same result from @code{sxhash-equal}. +@code{sxhash-equal} are usually different, but not always. +@code{sxhash-equal} is designed to be reasonably fast (since it's used +for indexing hash tables) so it won't recurse deeply into nested +structures. In addition; once in a rare while, by luck, you will +encounter two distinct-looking simple objects that give the same +result from @code{sxhash-equal}. So you can't, in general, use +@code{sxhash-equal} to check whether an object has changed. @b{Common Lisp note:} In Common Lisp a similar function is called @code{sxhash}. Emacs provides this name as a compatibility alias for @@ -320,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/help.texi b/doc/lispref/help.texi index fb0d3c203c8..463039c5a0e 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -158,6 +158,13 @@ the function definition has no documentation string. In that case, @code{documentation} returns @code{nil}. @end defun +@defun function-documentation function +Generic function used by @code{documentation} to extract the raw +docstring from a function object. You can specify how to get the +docstring of a specific function type by adding a corresponding method +to it. +@end defun + @defun face-documentation face This function returns the documentation string of @var{face} as a face. @@ -333,6 +340,16 @@ stands for no text itself. It is used only for a side effect: it specifies @var{mapvar}'s value as the keymap for any following @samp{\[@var{command}]} sequences in this documentation string. +@item \`@var{KEYSEQ}' +stands for a key sequence @var{KEYSEQ}, which will use the same face +as a command substitution. This should be used only when a key +sequence has no corresponding command, for example when it is read +directly with @code{read-key-sequence}. It must be a valid key +sequence according to @code{key-valid-p}. It can also be used with +command names, like @samp{\`M-x foo'}, where you want this to be +fontified like a keyboard sequence, but you want to inhibit +translating it into a key sequence like @samp{\[foo]} does. + @item ` (grave accent) stands for a left quote. This generates a left single quotation mark, an apostrophe, or a grave @@ -348,6 +365,10 @@ depending on the value of @code{text-quoting-style}. quotes the following character and is discarded; thus, @samp{\=`} puts @samp{`} into the output, @samp{\=\[} puts @samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the output. + +@item \+ +This indicates that the symbol directly following should not be marked +as link in the @file{*Help*} buffer. @end table @strong{Please note:} Each @samp{\} must be doubled when written in a @@ -372,7 +393,7 @@ quotes. You can customize it freely according to your personal preference. @end defopt -@defun substitute-command-keys string &optional no-face +@defun substitute-command-keys string &optional no-face include-menus @vindex help-key-binding@r{ (face)} This function scans @var{string} for the above special sequences and replaces them by what they stand for, returning the result as a string. @@ -422,6 +443,9 @@ RET minibuffer-complete-and-exit C-g abort-recursive-edit " +The keymap description will normally exclude menu items, but if +@var{include-menus} is non-@code{nil}, include them. + @group (substitute-command-keys "To abort a recursive edit from the minibuffer, type \ @@ -644,7 +668,7 @@ follows: @smallexample @group -(define-key global-map (string help-char) 'help-command) +(keymap-set global-map (key-description (string help-char)) 'help-command) (fset 'help-command help-map) @end group @end smallexample diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi index 107d036202e..339e1387d2e 100644 --- a/doc/lispref/hooks.texi +++ b/doc/lispref/hooks.texi @@ -280,7 +280,6 @@ kbd-macro-termination-hook signal-hook-function C functions: -redisplay-end-trigger-functions x-lost-selection-functions x-sent-selection-functions @@ -290,7 +289,6 @@ auto-fill-function command-error-function compose-chars-after-function composition-function-table -deferred-action-function input-method-function load-read-function load-source-file-function diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 14d6c34e17d..8d2089bad8b 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -218,6 +218,14 @@ the Emacs executable that dumped them. If you want to use this function in an Emacs that was already dumped, you must run Emacs with the @samp{-batch} option. + +@vindex after-pdump-load-hook +If you're including @samp{.el} files in the dumped Emacs and that +@samp{.el} file has code that is normally run at load time, that code +won't be run when Emacs starts after dumping. To help work around +that problem, you can put functions on the +@code{after-pdump-load-hook} hook. This hook is run when starting +Emacs. @end defun @defun dump-emacs to-file from-file diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index 5afd2f4ecf2..975215d6976 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi @@ -503,9 +503,11 @@ if the information is not available. @example @group emacs-build-time - @result{} (20614 63694 515336 438000) + @result{} (25194 55894 8547 617000) @end group @end example +(This timestamp is @code{(1651169878008547617 . 1000000000)} +if @code{current-time-list} was @code{nil} when Emacs was built.) @end defvar @defvar emacs-version diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 4b9252f1edf..2be31d63a62 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -30,6 +30,7 @@ is found. The whole process is called @dfn{key lookup}. * Key Lookup:: Finding a key's binding in one keymap. * Functions for Key Lookup:: How to request key lookup. * Changing Key Bindings:: Redefining a key in a keymap. +* Low-Level Key Binding:: Legacy key syntax description. * Remapping Commands:: A keymap can translate one command to another. * Translation Keymaps:: Keymaps for translating sequences of events. * Key Binding Commands:: Interactive interfaces for redefining keys. @@ -94,8 +95,15 @@ Manual}. (kbd "<f1> SPC") @result{} [f1 32] (kbd "C-M-<down>") @result{} [C-M-down] @end example + +@findex key-valid-p +The @code{kbd} function is very permissive, and will try to return +something sensible even if the syntax used isn't completely +conforming. To check whether the syntax is actually valid, use the +@code{key-valid-p} function. @end defun + @node Keymap Basics @section Keymap Basics @cindex key binding @@ -349,6 +357,105 @@ A full keymap is more efficient than a sparse keymap when it holds lots of bindings; for just a few, the sparse keymap is better. @end defun +@defun define-keymap &key options... &rest pairs... +You can create a keymap with the functions described above, and then +use @code{keymap-set} (@pxref{Changing Key Bindings}) to specify key +bindings in that map. When writing modes, however, you frequently +have to bind a large number of keys at once, and using +@code{keymap-set} on them all can be tedious and error-prone. Instead +you can use @code{define-keymap}, which creates a keymap and binds a +number of keys. Here's a very basic example: + +@lisp +(define-keymap + "n" #'forward-line + "f" #'previous-line + "C-c C-c" #'quit-window) +@end lisp + +This function creates a new sparse keymap, defines the keystrokes in +@var{pairs}, and returns the new keymap. It signals an error if there +are duplicate key bindings in @var{pairs}. + +@var{pairs} is a list of alternating key bindings and key definitions, +as accepted by @code{keymap-set}. In addition, the key can be the +special symbol @code{:menu}, in which case the definition should be a +menu definition as accepted by @code{easy-menu-define} (@pxref{Easy +Menu}). Here's a brief example of this usage: + +@lisp +(define-keymap :full t + "g" #'eww-reload + :menu '("Eww" + ["Exit" quit-window t] + ["Reload" eww-reload t])) +@end lisp + +A number of keywords can be used before the key/definition pairs to +change features of the new keymap. If any of the feature keywords is +missing from the @code{define-keymap} call, the default value for that +feature is @code{nil}. Here's a list of the available feature +keywords: + +@table @code +@item :full +If non-@code{nil}, create a char-table keymap (as from +@code{make-keymap}) instead of a sparse keymap (as from +@code{make-sparse-keymap} (@pxref{Creating Keymaps}). A sparse keymap +is the default. + +@item :parent +If non-@code{nil}, the value should be a keymap to use as the parent +(@pxref{Inheritance and Keymaps}). + +@item :keymap +If non-@code{nil}, the value should be a keymap. Instead of creating +a new keymap, the specified keymap is modified instead. + +@item :suppress +If non-@code{nil}, the keymap will be suppressed with +@code{suppress-keymap} (@pxref{Changing Key Bindings}). By default, +digits and the minus sign are exempt from suppressing, but if the +value is @code{nodigits}, this suppresses digits and minus-sign like +it does with other characters. + +@item :name +If non-@code{nil}, the value should be a string to use as the menu for +the keymap if you use it as a menu with @code{x-popup-menu} +(@pxref{Pop-Up Menus}). + +@item :prefix +If non-@code{nil}, the value should be a symbol to be used as a prefix +command (@pxref{Prefix Keys}). If this is the case, this symbol is +returned by @code{define-keymap} instead of the map itself. +@end table + +@end defun + +@defmac defvar-keymap name &key options... &rest pairs... +By far, the most common thing to do with a keymap is to bind it to a +variable. This is what virtually all modes do---a mode called +@code{foo} almost always has a variable called @code{foo-mode-map}. + +This macro defines @var{name} as a variable, passes @var{options} +and @var{pairs} to @code{define-keymap}, and uses the result as the +default value for the variable. It signals an error if there are +duplicate key bindings in @var{pairs}. + +@var{options} is like the keywords in @code{define-keymap}, but +there's an additional @code{:doc} keyword that provides the doc +string for the defined variable. + +Here's an example: + +@lisp +(defvar-keymap eww-textarea-map + :parent text-mode-map + "RET" #'forward-line + "TAB" #'shr-next-link) +@end lisp +@end defmac + @defun copy-keymap keymap This function returns a copy of @var{keymap}. This is almost never needed. If you want a keymap that's like another yet with a few @@ -359,7 +466,7 @@ I.e., something like: @group (let ((map (make-sparse-keymap))) (set-keymap-parent map <theirmap>) - (define-key map ...) + (keymap-set map ...) ...) @end group @end example @@ -412,10 +519,10 @@ The effect is that this keymap inherits all the bindings of but can add to them or override them with @var{elements}. If you change the bindings in @var{parent-keymap} using -@code{define-key} or other key-binding functions, these changed +@code{keymap-set} or other key-binding functions, these changed bindings are visible in the inheriting keymap, unless shadowed by the bindings made by @var{elements}. The converse is not true: if you use -@code{define-key} to change bindings in the inheriting keymap, these +@code{keymap-set} to change bindings in the inheriting keymap, these changes are recorded in @var{elements}, but have no effect on @var{parent-keymap}. @@ -474,11 +581,10 @@ override any non-@code{nil} binding in any other of the @var{maps}. @code{button-buffer-map} and @code{special-mode-map}: @example -(defvar help-mode-map - (let ((map (make-sparse-keymap))) - (set-keymap-parent map - (make-composed-keymap button-buffer-map special-mode-map)) - ... map) ... ) +(defvar-keymap help-mode-map + :parent (make-composed-keymap button-buffer-map + special-mode-map) + ...) @end example @@ -610,16 +716,16 @@ active keymap. @result{} nil @end group @group -(local-set-key "\C-p" ctl-x-map) +(keymap-local-set "C-p" ctl-x-map) @result{} nil @end group @group -(key-binding "\C-p\C-f") +(keymap-binding "C-p C-f") @result{} find-file @end group @group -(key-binding "\C-p6") +(keymap-binding "C-p 6") @result{} nil @end group @end example @@ -682,7 +788,7 @@ use, in place of the buffer's default local keymap. @cindex major mode keymap The local keymap is normally set by the buffer's major mode, and every buffer with the same major mode shares the same local keymap. -Hence, if you call @code{local-set-key} (@pxref{Key Binding Commands}) +Hence, if you call @code{keymap-local-set} (@pxref{Key Binding Commands}) to change the local keymap in one buffer, that also affects the local keymaps in other buffers with the same major mode. @@ -698,7 +804,7 @@ active keymaps, except for the global keymap. Secondly, the terminal-local variable @code{overriding-terminal-local-map} specifies a keymap that takes precedence over @emph{all} other keymaps (including @code{overriding-local-map}); this is normally used for -modal/transient keybindings (the function @code{set-transient-map} +modal/transient key bindings (the function @code{set-transient-map} provides a convenient interface for this). @xref{Controlling Active Maps}, for details. @@ -716,39 +822,7 @@ Normally it ignores @code{overriding-local-map} and then it pays attention to them. @var{position} can optionally be either an event position as returned by @code{event-start} or a buffer position, and may change the keymaps as described for -@code{key-binding}. -@end defun - -@defun key-binding key &optional accept-defaults no-remap position -This function returns the binding for @var{key} according to the -current active keymaps. The result is @code{nil} if @var{key} is -undefined in the keymaps. - -The argument @var{accept-defaults} controls checking for default -bindings, as in @code{lookup-key} (@pxref{Functions for Key Lookup}). - -When commands are remapped (@pxref{Remapping Commands}), -@code{key-binding} normally processes command remappings so as to -return the remapped command that will actually be executed. However, -if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores -remappings and returns the binding directly specified for @var{key}. - -If @var{key} starts with a mouse event (perhaps following a prefix -event), the maps to be consulted are determined based on the event's -position. Otherwise, they are determined based on the value of point. -However, you can override either of them by specifying @var{position}. -If @var{position} is non-@code{nil}, it should be either a buffer -position or an event position like the value of @code{event-start}. -Then the maps consulted are determined based on @var{position}. - -Emacs signals an error if @var{key} is not a string or a vector. - -@example -@group -(key-binding "\C-x\C-f") - @result{} find-file -@end group -@end example +@code{keymap-binding}. @end defun @node Searching Keymaps @@ -821,7 +895,7 @@ out with. This function returns the current global keymap. This is the same as the value of @code{global-map} unless you change one or the other. The return value is a reference, not a copy; if you use -@code{define-key} or other functions on it you will alter global +@code{keymap-set} or other functions on it you will alter global bindings. @example @@ -857,7 +931,7 @@ keymap. @end defun @code{current-local-map} returns a reference to the local keymap, not -a copy of it; if you use @code{define-key} or other functions on it +a copy of it; if you use @code{keymap-set} or other functions on it you will alter local bindings. @defun current-minor-mode-maps @@ -991,6 +1065,20 @@ The optional argument @var{on-exit}, if non-@code{nil}, specifies a function that is called, with no arguments, after @var{keymap} is deactivated. +The optional argument @var{message} specifies the message to display +after activating the transient map. If @var{message} is a string, it +is the format string for the message, and any @samp{%k} specifier in +that string is replaced with the list of keys from the transient map. +Any other non-@code{nil} value of @var{message} stands for the default +message format @samp{Repeat with %k}. + +@vindex set-transient-map-timeout +If the optional argument @var{timeout} is non-@code{nil}, it should be +a number that specifies how many seconds of idle time to wait before +deactivating @var{keymap}. The value of the variable +@code{set-transient-map-timeout}, if non-@code{nil}, overrides the +value of this argument. + This function works by adding and removing @var{keymap} from the variable @code{overriding-terminal-local-map}, which takes precedence over all other active keymaps (@pxref{Searching Keymaps}). @@ -1025,7 +1113,7 @@ keymap. Let's use the term @dfn{keymap entry} to describe the value found by looking up an event type in a keymap. (This doesn't include the item string and other extra elements in a keymap element for a menu item, because -@code{lookup-key} and other key lookup functions don't include them in +@code{keymap-lookup} and other key lookup functions don't include them in the returned value.) While any Lisp object may be stored in a keymap as a keymap entry, not all make sense for key lookup. Here is a table of the meaningful types of keymap entries: @@ -1113,22 +1201,18 @@ macro, a symbol that leads to one of them, or @code{nil}. Here are the functions and variables pertaining to key lookup. -@defun lookup-key keymap key &optional accept-defaults +@defun keymap-lookup keymap key &optional accept-defaults no-remap position This function returns the definition of @var{key} in @var{keymap}. All the other functions described in this chapter that look up keys use -@code{lookup-key}. Here are examples: +@code{keymap-lookup}. Here are examples: @example @group -(lookup-key (current-global-map) "\C-x\C-f") +(keymap-lookup (current-global-map) "C-x C-f") @result{} find-file @end group @group -(lookup-key (current-global-map) (kbd "C-x C-f")) - @result{} find-file -@end group -@group -(lookup-key (current-global-map) "\C-x\C-f12345") +(keymap-lookup (current-global-map) "C-x C-f 1 2 3 4 5") @result{} 2 @end group @end example @@ -1139,9 +1223,9 @@ and have extra events at the end that do not fit into a single key sequence. Then the value is a number, the number of events at the front of @var{key} that compose a complete key. -If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key} +If @var{accept-defaults} is non-@code{nil}, then @code{keymap-lookup} considers default bindings as well as bindings for the specific events -in @var{key}. Otherwise, @code{lookup-key} reports only bindings for +in @var{key}. Otherwise, @code{keymap-lookup} reports only bindings for the specific sequence @var{key}, ignoring default bindings except when you explicitly ask about them. (To do this, supply @code{t} as an element of @var{key}; see @ref{Format of Keymaps}.) @@ -1154,11 +1238,11 @@ the second example. @example @group -(lookup-key (current-global-map) "\M-f") +(keymap-lookup (current-global-map) "M-f") @result{} forward-word @end group @group -(lookup-key (current-global-map) "\ef") +(keymap-lookup (current-global-map) "ESC f") @result{} forward-word @end group @end example @@ -1169,6 +1253,20 @@ Unlike @code{read-key-sequence}, this function does not modify the specified events in ways that discard information (@pxref{Key Sequence Input}). In particular, it does not convert letters to lower case and it does not change drag events to clicks. + +Like the normal command loop, @code{keymap-lookup} will remap the +command resulting from looking up @var{key} by looking up the command +in the current keymaps. However, if the optional third argument +@var{no-remap} is non-@code{nil}, @code{keymap-lookup} returns the +command without remapping. + +If the optional argument @var{position} is non-@code{nil}, it +specifies a mouse position as returned by @code{event-start} and +@code{event-end}, and the lookup occurs in the keymaps associated with +that position, instead of in @var{keymap}. @var{position} can also be +a number or a marker, in which case it is interpreted as a buffer +position, and the function uses the keymap properties at that position +instead of at point. @end defun @deffn Command undefined @@ -1176,20 +1274,20 @@ Used in keymaps to undefine keys. It calls @code{ding}, but does not cause an error. @end deffn -@defun local-key-binding key &optional accept-defaults +@defun keymap-local-binding key &optional accept-defaults This function returns the binding for @var{key} in the current local keymap, or @code{nil} if it is undefined there. The argument @var{accept-defaults} controls checking for default bindings, -as in @code{lookup-key} (above). +as in @code{keymap-lookup} (above). @end defun -@defun global-key-binding key &optional accept-defaults +@defun keymap-global-binding key &optional accept-defaults This function returns the binding for command @var{key} in the current global keymap, or @code{nil} if it is undefined there. The argument @var{accept-defaults} controls checking for default bindings, -as in @code{lookup-key} (above). +as in @code{keymap-lookup} (above). @end defun @defun minor-mode-key-binding key &optional accept-defaults @@ -1206,7 +1304,7 @@ modes are omitted, since they would be completely shadowed. Similarly, the list omits non-prefix bindings that follow prefix bindings. The argument @var{accept-defaults} controls checking for default -bindings, as in @code{lookup-key} (above). +bindings, as in @code{keymap-lookup} (above). @end defun @defopt meta-prefix-char @@ -1267,51 +1365,63 @@ change a binding in the global keymap, the change is effective in all buffers (though it has no direct effect in buffers that shadow the global binding with a local one). If you change the current buffer's local map, that usually affects all buffers using the same major mode. -The @code{global-set-key} and @code{local-set-key} functions are +The @code{keymap-global-set} and @code{keymap-local-set} functions are convenient interfaces for these operations (@pxref{Key Binding -Commands}). You can also use @code{define-key}, a more general +Commands}). You can also use @code{keymap-set}, a more general function; then you must explicitly specify the map to change. When choosing the key sequences for Lisp programs to rebind, please follow the Emacs conventions for use of various keys (@pxref{Key Binding Conventions}). -@cindex meta character key constants -@cindex control character key constants - In writing the key sequence to rebind, it is good to use the special -escape sequences for control and meta characters (@pxref{String Type}). -The syntax @samp{\C-} means that the following character is a control -character and @samp{\M-} means that the following character is a meta -character. Thus, the string @code{"\M-x"} is read as containing a -single @kbd{M-x}, @code{"\C-f"} is read as containing a single -@kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as -containing a single @kbd{C-M-x}. You can also use this escape syntax in -vectors, as well as others that aren't allowed in strings; one example -is @samp{[?\C-\H-x home]}. @xref{Character Type}. - - The key definition and lookup functions accept an alternate syntax for -event types in a key sequence that is a vector: you can use a list -containing modifier names plus one base event (a character or function -key name). For example, @code{(control ?a)} is equivalent to -@code{?\C-a} and @code{(hyper control left)} is equivalent to -@code{C-H-left}. One advantage of such lists is that the precise -numeric codes for the modifier bits don't appear in compiled files. - The functions below signal an error if @var{keymap} is not a keymap, -or if @var{key} is not a string or vector representing a key sequence. -You can use event types (symbols) as shorthand for events that are -lists. The @code{kbd} function (@pxref{Key Sequences}) is a -convenient way to specify the key sequence. +or if @var{key} is not a valid key. + +@var{key} is a string representing a single key or a series of key +strokes. Key strokes are separated by a single space character. -@defun define-key keymap key binding +Each key stroke is either a single character, or the name of an +event, surrounded by angle brackets. In addition, any key stroke +may be preceded by one or more modifier keys. Finally, a limited +number of characters have a special shorthand syntax. Here's some +example key sequences: + +@table @kbd +@item f +The key @kbd{f}. + +@item S o m +A three key sequence of the keys @kbd{S}, @kbd{o} and @kbd{m}. + +@item C-c o +A two key sequence of the keys @kbd{c} with the control modifier and +then the key @kbd{o} + +@item H-<left> +The key named @kbd{left} with the hyper modifier. + +@item M-RET +The @kbd{return} key with a meta modifier. + +@item C-M-<space> +The @kbd{space} key with both the control and meta modifiers. +@end table + +The only keys that have a special shorthand syntax are @kbd{NUL}, +@kbd{RET}, @kbd{TAB}, @kbd{LFD}, @kbd{ESC}, @kbd{SPC} and @kbd{DEL}. + +The modifiers have to be specified in alphabetical order: +@samp{A-C-H-M-S-s}, which is @samp{Alt-Control-Hyper-Meta-Shift-super}. + +@defun keymap-set keymap key binding This function sets the binding for @var{key} in @var{keymap}. (If @var{key} is more than one event long, the change is actually made in another keymap reached from @var{keymap}.) The argument @var{binding} can be any Lisp object, but only certain types are meaningful. (For a list of meaningful types, see @ref{Key Lookup}.) -The value returned by @code{define-key} is @var{binding}. +The value returned by @code{keymap-set} is @var{binding}. -If @var{key} is @code{[t]}, this sets the default binding in +If @var{key} is @kbd{<t>}, this sets the default binding in @var{keymap}. When an event has no binding of its own, the Emacs command loop uses the keymap's default binding, if there is one. @@ -1319,7 +1429,7 @@ command loop uses the keymap's default binding, if there is one. @cindex key sequence error Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap) or undefined; otherwise an error is signaled. If some prefix of -@var{key} is undefined, then @code{define-key} defines it as a prefix +@var{key} is undefined, then @code{keymap-set} defines it as a prefix key so that the rest of @var{key} can be defined as specified. If there was previously no binding for @var{key} in @var{keymap}, the @@ -1337,7 +1447,7 @@ bindings in it: @result{} (keymap) @end group @group -(define-key map "\C-f" 'forward-char) +(keymap-set map "C-f" 'forward-char) @result{} forward-char @end group @group @@ -1347,7 +1457,7 @@ map @group ;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.} -(define-key map (kbd "C-x f") 'forward-word) +(keymap-set map "C-x f" 'forward-word) @result{} forward-word @end group @group @@ -1360,14 +1470,14 @@ map @group ;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.} -(define-key map (kbd "C-p") ctl-x-map) +(keymap-set map "C-p" ctl-x-map) ;; @code{ctl-x-map} @result{} [nil @dots{} find-file @dots{} backward-kill-sentence] @end group @group ;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.} -(define-key map (kbd "C-p C-f") 'foo) +(keymap-set map "C-p C-f" 'foo) @result{} 'foo @end group @group @@ -1386,7 +1496,14 @@ changing an entry in @code{ctl-x-map}, and this has the effect of changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the default global map. - The function @code{substitute-key-definition} scans a keymap for +@code{keymap-set} is the general work horse for defining a key in a +keymap. When writing modes, however, you frequently have to bind a +large number of keys at once, and using @code{keymap-set} on them all +can be tedious and error-prone. Instead you can use +@code{define-keymap}, which creates a keymap and binds a number of +keys. @xref{Creating Keymaps}, for details. + +The function @code{substitute-key-definition} scans a keymap for keys that have a certain binding and rebinds them with a different binding. Another feature which is cleaner and can often produce the same results is to remap one command into another (@pxref{Remapping @@ -1485,13 +1602,181 @@ Modes}); then its keymap will automatically inherit from (defvar special-mode-map (let ((map (make-sparse-keymap))) (suppress-keymap map) - (define-key map "q" 'quit-window) + (keymap-set map "q" 'quit-window) @dots{} map)) @end group @end smallexample @end defun +@node Low-Level Key Binding +@section Low-Level Key Binding +@cindex low-level key bindings + + Historically, Emacs has supported a number of different syntaxes for +defining keys. The documented way to bind a key today is to use the +syntax supported by @code{key-valid-p}, which is what all the +functions like @code{keymap-set} and @code{keymap-lookup} supports. +This section documents the old-style syntax and interface functions; +they should not be used in new code. + +@cindex meta character key constants +@cindex control character key constants + @code{define-key} (and other low-level functions that are used to +rebind keys) understand a number of different syntaxes for the keys. + +@table @asis +@item A vector containing lists of keys. +You can use a list containing modifier names plus one base event (a +character or function key name). For example, @code{[(control ?a) +(meta b)]} is equivalent to @kbd{C-a M-b} and @code{[(hyper control +left)]} is equivalent to @kbd{C-H-left}. + +@item A string of characters with modifiers +Internally, key sequences are often represented as strings using the +special escape sequences for shift, control and meta modifiers +(@pxref{String Type}), but this representation can also be used by +users when rebinding keys. A string like @code{"\M-x"} is read as +containing a single @kbd{M-x}, @code{"\C-f"} is read as containing a +single @kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both +read as containing a single @kbd{C-M-x}. + +@item A vector of characters and key symbols +This is the other internal representation of key sequences. It +supports a fuller range of modifiers than the string representation, +and also support function keys. An example is @w{@samp{[?\C-\H-x +home]}}, which represents the @w{@kbd{C-H-x @key{home}}} key sequence. +@xref{Character Type}. +@end table + +@defun define-key keymap key binding &optional remove +This function is like @code{keymap-set} (@pxref{Changing Key +Bindings}, but understands only the legacy key syntaxes. + +In addition, this function also has a @var{remove} argument. If it is +non-@code{nil}, the definition will be removed. This is almost the +same as setting the definition to @code{nil}, but makes a difference +if the @var{keymap} has a parent, and @var{key} is shadowing the same +binding in the parent. With @var{remove}, subsequent lookups will +return the binding in the parent, whereas with a @code{nil} definition the +lookups will return @code{nil}. +@end defun + +Here are other legacy key definition functions and commands, with the +equivalent modern function to use instead in new code. + +@deffn Command global-set-key key binding +This function sets the binding of @var{key} in the current global map +to @var{binding}. Use @code{keymap-global-set} instead. +@end deffn + +@deffn Command global-unset-key key +This function removes the binding of @var{key} from the current +global map. Use @code{keymap-global-unset} instead. +@end deffn + +@deffn Command local-set-key key binding +This function sets the binding of @var{key} in the current local +keymap to @var{binding}. Use @code{keymap-local-set} instead. +@end deffn + +@deffn Command local-unset-key key +This function removes the binding of @var{key} from the current +local map. Use @code{keymap-local-unset} instead. +@end deffn + +@defun substitute-key-definition olddef newdef keymap &optional oldmap +This function replaces @var{olddef} with @var{newdef} for any keys in +@var{keymap} that were bound to @var{olddef}. In other words, +@var{olddef} is replaced with @var{newdef} wherever it appears. The +function returns @code{nil}. Use @code{keymap-substitute} instead. +@end defun + +@defun define-key-after map key binding &optional after +Define a binding in @var{map} for @var{key}, with value @var{binding}, +just like @code{define-key}, but position the binding in @var{map} after +the binding for the event @var{after}. The argument @var{key} should be +of length one---a vector or string with just one element. But +@var{after} should be a single event type---a symbol or a character, not +a sequence. The new binding goes after the binding for @var{after}. If +@var{after} is @code{t} or is omitted, then the new binding goes last, at +the end of the keymap. However, new bindings are added before any +inherited keymap. Use @code{keymap-set-after} instead of this function. +@end defun + +@defun keyboard-translate from to +This function modifies @code{keyboard-translate-table} to translate +character code @var{from} into character code @var{to}. It creates +the keyboard translate table if necessary. Use @code{key-translate} +instead. +@end defun + +@defun key-binding key &optional accept-defaults no-remap position +This function returns the binding for @var{key} according to the +current active keymaps. The result is @code{nil} if @var{key} is +undefined in the keymaps. The argument @var{accept-defaults} controls +checking for default bindings, as in @code{lookup-key} +(@pxref{Functions for Key Lookup}). If @var{no-remap} is +non-@code{nil}, @code{key-binding} ignores command remappings +(@pxref{Remapping Commands}) and returns the binding directly +specified for @var{key}. The optional argument @var{position} should +be either a buffer position or an event position like the value of +@code{event-start}; it tells the function to consult the maps +determined based on that @var{position}. + +Emacs signals an error if @var{key} is not a string or a vector. + +Use @code{keymap-lookup} instead of this function. +@end defun + +@defun lookup-key keymap key &optional accept-defaults +This function returns the definition of @var{key} in @var{keymap}. If +the string or vector @var{key} is not a valid key sequence according +to the prefix keys specified in @var{keymap}, it must be too long and +have extra events at the end that do not fit into a single key +sequence. Then the value is a number, the number of events at the +front of @var{key} that compose a complete key. + +If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key} +considers default bindings as well as bindings for the specific events +in @var{key}. Otherwise, @code{lookup-key} reports only bindings for +the specific sequence @var{key}, ignoring default bindings except when +you explicitly ask about them. + +Use @code{keymap-lookup} instead of this function. +@end defun + +@defun local-key-binding key &optional accept-defaults +This function returns the binding for @var{key} in the current +local keymap, or @code{nil} if it is undefined there. + +The argument @var{accept-defaults} controls checking for default bindings, +as in @code{lookup-key} (above). +@end defun + +@defun global-key-binding key &optional accept-defaults +This function returns the binding for command @var{key} in the +current global keymap, or @code{nil} if it is undefined there. + +The argument @var{accept-defaults} controls checking for default bindings, +as in @code{lookup-key} (above). +@end defun + +@defun event-convert-list list +This function converts a list of modifier names and a basic event type +to an event type which specifies all of them. The basic event type +must be the last element of the list. For example, + +@example +(event-convert-list '(control ?a)) + @result{} 1 +(event-convert-list '(control meta ?a)) + @result{} -134217727 +(event-convert-list '(control super f1)) + @result{} C-s-f1 +@end example +@end defun + @node Remapping Commands @section Remapping Commands @cindex remapping commands @@ -1510,7 +1795,7 @@ definition for a key binding). the following remapping: @smallexample -(define-key my-mode-map [remap kill-line] 'my-kill-line) +(keymap-set my-mode-map "<remap> <kill-line>" 'my-kill-line) @end smallexample @noindent @@ -1525,8 +1810,8 @@ In addition, remapping only works through a single level; in the following example, @smallexample -(define-key my-mode-map [remap kill-line] 'my-kill-line) -(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line) +(keymap-set my-mode-map "<remap> <kill-line>" 'my-kill-line) +(keymap-set my-mode-map "<remap> <my-kill-line>" 'my-other-kill-line) @end smallexample @noindent @@ -1538,7 +1823,7 @@ remapped to @code{my-kill-line}; if an ordinary binding specifies To undo the remapping of a command, remap it to @code{nil}; e.g., @smallexample -(define-key my-mode-map [remap kill-line] nil) +(keymap-set my-mode-map "<remap> <kill-line>" nil) @end smallexample @defun command-remapping command &optional position keymaps @@ -1671,7 +1956,7 @@ to turn the character that follows into a Hyper character: symbol (cons symbol (cdr e))))) -(define-key local-function-key-map "\C-ch" 'hyperify) +(keymap-set local-function-key-map "C-c h" 'hyperify) @end group @end example @@ -1701,55 +1986,34 @@ problematic suffixes/prefixes are @kbd{@key{ESC}}, @kbd{M-O} (which is really @section Commands for Binding Keys This section describes some convenient interactive interfaces for -changing key bindings. They work by calling @code{define-key}. +changing key bindings. They work by calling @code{keymap-set}. - People often use @code{global-set-key} in their init files + People often use @code{keymap-global-set} in their init files (@pxref{Init File}) for simple customization. For example, @smallexample -(global-set-key (kbd "C-x C-\\") 'next-line) -@end smallexample - -@noindent -or - -@smallexample -(global-set-key [?\C-x ?\C-\\] 'next-line) -@end smallexample - -@noindent -or - -@smallexample -(global-set-key [(control ?x) (control ?\\)] 'next-line) +(keymap-global-set "C-x C-\\" 'next-line) @end smallexample @noindent redefines @kbd{C-x C-\} to move down a line. @smallexample -(global-set-key [M-mouse-1] 'mouse-set-point) +(keymap-global-set "M-<mouse-1>" 'mouse-set-point) @end smallexample @noindent redefines the first (leftmost) mouse button, entered with the Meta key, to set point where you click. -@cindex non-@acronym{ASCII} text in keybindings +@cindex non-@acronym{ASCII} text in key bindings Be careful when using non-@acronym{ASCII} text characters in Lisp specifications of keys to bind. If these are read as multibyte text, as they usually will be in a Lisp file (@pxref{Loading Non-ASCII}), you must type the keys as multibyte too. For instance, if you use this: @smallexample -(global-set-key "ö" 'my-function) ; bind o-umlaut -@end smallexample - -@noindent -or - -@smallexample -(global-set-key ?ö 'my-function) ; bind o-umlaut +(keymap-global-set "ö" 'my-function) ; bind o-umlaut @end smallexample @noindent @@ -1760,20 +2024,20 @@ binding, you need to teach Emacs how to decode the keyboard by using an appropriate input method (@pxref{Input Methods, , Input Methods, emacs, The GNU Emacs Manual}). -@deffn Command global-set-key key binding +@deffn Command keymap-global-set key binding This function sets the binding of @var{key} in the current global map to @var{binding}. @smallexample @group -(global-set-key @var{key} @var{binding}) +(keymap-global-set @var{key} @var{binding}) @equiv{} -(define-key (current-global-map) @var{key} @var{binding}) +(keymap-set (current-global-map) @var{key} @var{binding}) @end group @end smallexample @end deffn -@deffn Command global-unset-key key +@deffn Command keymap-global-unset key @cindex unbinding keys This function removes the binding of @var{key} from the current global map. @@ -1784,50 +2048,32 @@ that uses @var{key} as a prefix---which would not be allowed if @smallexample @group -(global-unset-key "\C-l") +(keymap-global-unset "C-l") @result{} nil @end group @group -(global-set-key "\C-l\C-l" 'redraw-display) +(keymap-global-set "C-l C-l" 'redraw-display) @result{} nil @end group @end smallexample - -This function is equivalent to using @code{define-key} as follows: - -@smallexample -@group -(global-unset-key @var{key}) -@equiv{} -(define-key (current-global-map) @var{key} nil) -@end group -@end smallexample @end deffn -@deffn Command local-set-key key binding +@deffn Command keymap-local-set key binding This function sets the binding of @var{key} in the current local keymap to @var{binding}. @smallexample @group -(local-set-key @var{key} @var{binding}) +(keymap-local-set @var{key} @var{binding}) @equiv{} -(define-key (current-local-map) @var{key} @var{binding}) +(keymap-set (current-local-map) @var{key} @var{binding}) @end group @end smallexample @end deffn -@deffn Command local-unset-key key +@deffn Command keymap-local-unset key This function removes the binding of @var{key} from the current local map. - -@smallexample -@group -(local-unset-key @var{key}) -@equiv{} -(define-key (current-local-map) @var{key} nil) -@end group -@end smallexample @end deffn @node Scanning Keymaps @@ -1979,6 +2225,11 @@ If @var{no-remap} is @code{nil}, return the bindings for non-@code{nil}, return the bindings for @var{command}, ignoring the fact that it is remapped. @end table + +If a command maps to a key binding like @code{[some-event]}, and +@code{some-event} has a symbol plist containing a non-@code{nil} +@code{non-key-event} property, then that binding is ignored by +@code{where-is-internal}. @end defun @deffn Command describe-bindings &optional prefix buffer-or-name @@ -2065,7 +2316,7 @@ the keymap. Since @code{define-key} puts new bindings at the front, you should define the menu items starting at the bottom of the menu and moving to the top, if you care about the order. When you add an item to an existing menu, you can specify its position in the menu using -@code{define-key-after} (@pxref{Modifying Menus}). +@code{keymap-set-after} (@pxref{Modifying Menus}). @menu * Simple Menu Items:: A simple kind of menu key binding. @@ -2228,6 +2479,12 @@ This property specifies that @var{string} is the string to display as the keyboard equivalent for this menu item. You can use the @samp{\\[...]} documentation construct in @var{string}. +This property can also be a function (which will be called with no +arguments). This function should return a string. This function will +be called every time the menu is computed, so using a function that +takes a lot of time to compute is not a good idea, and it should +expect to be called from any context. + @item :filter @var{filter-fn} This property provides a way to compute the menu item dynamically. The property value @var{filter-fn} should be a function of one argument; @@ -2676,9 +2933,9 @@ using an indirection through @code{tool-bar-map}. By default, the global map binds @code{[tool-bar]} as follows: @example -(global-set-key [tool-bar] - `(menu-item ,(purecopy "tool bar") ignore - :filter tool-bar-make-keymap)) +(keymap-global-set "<tool-bar>" + `(menu-item ,(purecopy "tool bar") ignore + :filter tool-bar-make-keymap)) @end example @noindent @@ -2813,9 +3070,9 @@ To force recalculation of the tool bar, call When you insert a new item in an existing menu, you probably want to put it in a particular place among the menu's existing items. If you use @code{define-key} to add the item, it normally goes at the front of -the menu. To put it elsewhere in the menu, use @code{define-key-after}: +the menu. To put it elsewhere in the menu, use @code{keymap-set-after}: -@defun define-key-after map key binding &optional after +@defun keymap-set-after map key binding &optional after Define a binding in @var{map} for @var{key}, with value @var{binding}, just like @code{define-key}, but position the binding in @var{map} after the binding for the event @var{after}. The argument @var{key} should be @@ -2829,7 +3086,7 @@ inherited keymap. Here is an example: @example -(define-key-after my-menu [drink] +(keymap-set-after my-menu "<drink>" '("Drink" . drink-command) 'eat) @end example @@ -2841,7 +3098,7 @@ Here is how to insert an item called @samp{Work} in the @samp{Signals} menu of Shell mode, after the item @code{break}: @example -(define-key-after shell-mode-map [menu-bar signals work] +(keymap-set-after shell-mode-map "<menu-bar> <signals> <work>" '("Work" . work-command) 'break) @end example @end defun diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 4a862ab0de2..5c5c615f85d 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -340,6 +340,44 @@ If @var{n} is zero, @code{nthcdr} returns all of @end example @end defun +@defun take n list +This function returns the @var{n} first elements of @var{list}. Essentially, +it returns the part of @var{list} that @code{nthcdr} skips. + +@code{take} returns @var{list} if shorter than @var{n} elements; +it returns @code{nil} if @var{n} is zero or negative. + +@example +@group +(take 3 '(a b c d)) + @result{} (a b c) +@end group +@group +(take 10 '(a b c d)) + @result{} (a b c d) +@end group +@group +(take 0 '(a b c d)) + @result{} nil +@end group +@end example +@end defun + +@defun ntake n list +This is a version of @code{take} that works by destructively modifying +the list structure of the argument. That makes it faster, but the +original value of @var{list} may be lost. + +@code{ntake} returns @var{list} unmodified if shorter than @var{n} +elements; it returns @code{nil} if @var{n} is zero or negative. +Otherwise, it returns @var{list} truncated to its first @var{n} +elements. + +This means that it is usually a good idea to use the return value and +not just rely on the truncation effect unless @var{n} is known to be +positive. +@end defun + @defun last list &optional n This function returns the last link of @var{list}. The @code{car} of this link is the list's last element. If @var{list} is null, @@ -1925,9 +1963,10 @@ and later discarded; this is not possible with a property list. The following functions can be used to manipulate property lists. They all compare property names using @code{eq}. -@defun plist-get plist property +@defun plist-get plist property &optional predicate This returns the value of the @var{property} property stored in the -property list @var{plist}. It accepts a malformed @var{plist} +property list @var{plist}. Comparisons are done with @var{predicate}, +and defaults to @code{eq}. It accepts a malformed @var{plist} argument. If @var{property} is not found in the @var{plist}, it returns @code{nil}. For example, @@ -1943,9 +1982,10 @@ returns @code{nil}. For example, @end example @end defun -@defun plist-put plist property value +@defun plist-put plist property value &optional predicate This stores @var{value} as the value of the @var{property} property in -the property list @var{plist}. It may modify @var{plist} destructively, +the property list @var{plist}. Comparisons are done with @var{predicate}, +and defaults to @code{eq}. It may modify @var{plist} destructively, or it may construct a new list structure without altering the old. The function returns the modified property list, so you can store that back in the place where you got @var{plist}. For example, @@ -1961,19 +2001,20 @@ in the place where you got @var{plist}. For example, @end defun @defun lax-plist-get plist property -Like @code{plist-get} except that it compares properties -using @code{equal} instead of @code{eq}. +This obsolete function is like @code{plist-get} except that it +compares properties using @code{equal} instead of @code{eq}. @end defun @defun lax-plist-put plist property value -Like @code{plist-put} except that it compares properties -using @code{equal} instead of @code{eq}. +This obsolete function is like @code{plist-put} except that it +compares properties using @code{equal} instead of @code{eq}. @end defun -@defun plist-member plist property +@defun plist-member plist property &optional predicate This returns non-@code{nil} if @var{plist} contains the given -@var{property}. Unlike @code{plist-get}, this allows you to distinguish -between a missing property and a property with the value @code{nil}. -The value is actually the tail of @var{plist} whose @code{car} is -@var{property}. +@var{property}. Comparisons are done with @var{predicate}, and +defaults to @code{eq}. Unlike @code{plist-get}, this allows you to +distinguish between a missing property and a property with the value +@code{nil}. The value is actually the tail of @var{plist} whose +@code{car} is @var{property}. @end defun diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 723b4dd20a6..4e4f12dc324 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -149,10 +149,9 @@ up the execution of uncompiled code. Sometimes, this macro expansion cannot be done, owing to a cyclic dependency. In the simplest example of this, the file you are loading refers to a macro defined in another file, and that file in turn requires the file you are -loading. This is generally harmless. Emacs prints a warning +loading. Emacs will issue an error about (@samp{Eager macro-expansion skipped due to cycle@dots{}}) -giving details of the problem, but it still loads the file, just -leaving the macro unexpanded for now. You may wish to restructure +giving details of the problem. You have to restructure your code so that this does not happen. Loading a compiled file does not cause macroexpansion, because this should already have happened during compilation. @xref{Compiling Macros}. @@ -291,29 +290,35 @@ a directory) or @code{nil} (which stands for the current working directory). @end defvar - When Emacs starts up, it sets up the value of @code{load-path} -in several steps. First, it initializes @code{load-path} using -default locations set when Emacs was compiled. Normally, this -is a directory something like + When Emacs starts up, it sets up the value of @code{load-path} in +several steps. First, it looks for the directory containing its own +Lisp files, using default locations set when Emacs was compiled. It +saves this directory in @code{lisp-directory}. Normally, this is a +directory where the @file{*.elc} files are installed, something like @example "/usr/local/share/emacs/@var{version}/lisp" @end example -(In this and the following examples, replace @file{/usr/local} with -the installation prefix appropriate for your Emacs.) -These directories contain the standard Lisp files that come with -Emacs. If Emacs cannot find them, it will not start correctly. +@noindent +where @var{version} is the Emacs version. (In this and the following +examples, replace @file{/usr/local} with the prefix appropriate for +your Emacs installation.) This directory and its subdirectories +contain the standard Lisp files that come with Emacs. If Emacs cannot +find its own Lisp files, it will not start correctly. If you run Emacs from the directory where it was built---that is, an -executable that has not been formally installed---Emacs instead -initializes @code{load-path} using the @file{lisp} -directory in the directory containing the sources from which it -was built. +executable that has not been installed yet---Emacs instead initializes +@code{lisp-directory} using the @file{lisp} subdirectory of the +directory containing the sources from which it was built. + +Emacs then initializes @code{load-path} with this @code{lisp-directory}. @c Though there should be no *.el files in builddir/lisp, so it's pointless. If you built Emacs in a separate directory from the -sources, it also adds the lisp directories from the build directory. -(In all cases, elements are represented as absolute file names.) +sources, it also adds the @file{lisp} subdirectory of the build directory. + +All of these directories are stored in the above two variables as +absolute file names. @cindex site-lisp directories Unless you start Emacs with the @option{--no-site-lisp} option, @@ -333,12 +338,12 @@ and @end example @noindent -The first one is for locally installed files for a specific Emacs -version; the second is for locally installed files meant for use -with all installed Emacs versions. (If Emacs is running uninstalled, -it also adds @file{site-lisp} directories from the source and build -directories, if they exist. Normally these directories do not contain -@file{site-lisp} directories.) +The first one is for locally installed files for the current Emacs +@var{version}; the second is for locally installed files meant for use +with any installed Emacs version. (If Emacs is running uninstalled, +it also adds @file{site-lisp} subdirectories from the source and build +directories, if they exist. However, normally the source and build +directories do not contain @file{site-lisp} subdirectories.) @cindex @env{EMACSLOADPATH} environment variable If the environment variable @env{EMACSLOADPATH} is set, it modifies @@ -360,9 +365,10 @@ export EMACSLOADPATH=/home/foo/.emacs.d/lisp: @end example An empty element in the value of the environment variable, whether -trailing (as in the above example), leading, or embedded, is replaced -by the default value of @code{load-path} as determined by the standard -initialization procedure. If there are no such empty elements, then +trailing (as in the above example, note the trailing @samp{:}), +leading, or embedded, is replaced by the default value of +@code{load-path} as determined by the standard initialization +procedure. If there are no such empty elements, then @env{EMACSLOADPATH} specifies the entire @code{load-path}. You must include either an empty element, or the explicit path to the directory containing the standard Lisp files, else Emacs will not function. @@ -391,11 +397,23 @@ add one or more directories to @code{load-path}. For example: (push "~/.emacs.d/lisp" load-path) @end example +@noindent +@xref{List Variables, push}, for the description of @code{push}. + Dumping Emacs uses a special value of @code{load-path}. If you use a @file{site-load.el} or @file{site-init.el} file to customize the dumped Emacs (@pxref{Building Emacs}), any changes to @code{load-path} that these files make will be lost after dumping. +@defvar lisp-directory +This variable holds a string naming the directory which holds +Emacs's own @file{*.el} and @file{*.elc} files. This is usually the +place where those files are located in the Emacs installation tree, +unless Emacs is run from its build directory in which case it points +to the @file{lisp} subdirectory in the source directory from which +Emacs was built. +@end defvar + @deffn Command locate-library library &optional nosuffix path interactive-call This command finds the precise file name for library @var{library}. It searches for the library in the same way @code{load} does, and the @@ -422,7 +440,7 @@ similarly-named file in a directory earlier on @code{load-path}. For instance, suppose @code{load-path} is set to @example - ("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp") + ("/opt/emacs/site-lisp" "/usr/share/emacs/29.1/lisp") @end example @noindent @@ -482,7 +500,7 @@ automatically. However, if this does make a difference, you can force a particular Lisp file to be interpreted as unibyte by writing @samp{coding: raw-text} in a local variables section. With that designator, the file will unconditionally be interpreted as -unibyte. This can matter when making keybindings to +unibyte. This can matter when making key bindings to non-@acronym{ASCII} characters written as @code{?v@var{literal}}. @node Autoload @@ -510,7 +528,7 @@ primitive for autoloading; any Lisp program can call @code{autoload} at any time. Magic comments are the most convenient way to make a function autoload, for packages installed along with Emacs. These comments do nothing on their own, but they serve as a guide for the command -@code{update-file-autoloads}, which constructs calls to @code{autoload} +@code{loaddefs-generate}, which constructs calls to @code{autoload} and arranges to execute them when Emacs is built. @defun autoload function filename &optional docstring interactive type @@ -552,7 +570,7 @@ An autoloaded keymap loads automatically during key lookup when a prefix key's binding is the symbol @var{function}. Autoloading does not occur for other kinds of access to the keymap. In particular, it does not happen when a Lisp program gets the keymap from the value of a variable -and calls @code{define-key}; not even if the variable name is the same +and calls @code{keymap-set}; not even if the variable name is the same symbol @var{function}. @cindex function cell in autoload @@ -608,22 +626,19 @@ subroutines not loaded successfully because they come later in the file. macro, then an error is signaled with data @code{"Autoloading failed to define function @var{function-name}"}. -@findex update-file-autoloads -@findex make-directory-autoloads +@findex loaddefs-generate @cindex magic autoload comment @cindex autoload cookie @anchor{autoload cookie} A magic autoload comment (often called an @dfn{autoload cookie}) consists of @samp{;;;###autoload}, on a line by itself, just before the real definition of the function in its -autoloadable source file. The command @kbd{M-x update-file-autoloads} +autoloadable source file. The function @code{loaddefs-generate} writes a corresponding @code{autoload} call into @file{loaddefs.el}. (The string that serves as the autoload cookie and the name of the -file generated by @code{update-file-autoloads} can be changed from the +file generated by @code{loaddefs-generate} can be changed from the above defaults, see below.) Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}. -@kbd{M-x make-directory-autoloads} is even more powerful; it updates -autoloads for all files in the current directory. The same magic comment can copy any kind of form into @file{loaddefs.el}. The form following the magic comment is copied @@ -656,7 +671,7 @@ and @code{define-global-minor-mode}. @emph{without} executing it when the file itself is loaded. To do this, write the form @emph{on the same line} as the magic comment. Since it is in a comment, it does nothing when you load the source file; but -@kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where +@code{loaddefs-generate} copies it to @file{loaddefs.el}, where it is executed while building Emacs. The following example shows how @code{doctor} is prepared for @@ -683,14 +698,13 @@ Switch to *doctor* buffer and start giving psychotherapy. @noindent @cindex @code{fn} in function's documentation string -The backslash and newline immediately following the double-quote are a -convention used only in the preloaded uncompiled Lisp files such as -@file{loaddefs.el}; they tell @code{make-docfile} to put the -documentation string in the @file{etc/DOC} file. @xref{Building Emacs}. -See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)} -in the usage part of the documentation string is replaced with the -function's name when the various help functions (@pxref{Help -Functions}) display it. +While the @file{loaddefs.el} isn't for editing, we try to keep it +somewhat readable for people. For instance, control characters in +@code{defvar} values are escaped, and we insert a backslash and +newline immediately following the double-quote of the doc string to +keep the line length down. @samp{(fn)} in the usage part of the +documentation string is replaced with the function's name when the +various help functions (@pxref{Help Functions}) display it. If you write a function definition with an unusual macro that is not one of the known and recognized function definition methods, use of an @@ -709,11 +723,11 @@ corresponding autoload calls written into a file whose name is different from the default @file{loaddefs.el}. Emacs provides two variables to control this: -@defvar generate-autoload-cookie -The value of this variable should be a string whose syntax is a Lisp -comment. @kbd{M-x update-file-autoloads} copies the Lisp form that -follows the cookie into the autoload file it generates. The default -value of this variable is @code{";;;###autoload"}. +@defvar lisp-mode-autoload-regexp +The value of this constant is a regexp that matches autoload cookies. +@code{loaddefs-generate} copies the Lisp form that follows the +cookie into the autoload file it generates. This will match comments +like @samp{;;;###autoload} and @samp{;;;###calc-autoload}. @end defvar @defvar generated-autoload-file @@ -750,7 +764,7 @@ contain definitions matching the prefix being completed. The variable @code{definition-prefixes} holds a hashtable which maps a prefix to the corresponding list of files to load for it. Entries to this mapping are added by calls to @code{register-definition-prefixes} -which are generated by @code{update-file-autoloads} +which are generated by @code{loaddefs-generate} (@pxref{Autoload}). Files which don't contain any definitions worth loading (test files, for example), should set @code{autoload-compute-prefixes} to @code{nil} as a file-local @@ -1017,7 +1031,7 @@ with a call to @code{provide}. The order of the elements in the @cindex symbol, where defined @cindex where was a symbol defined -@defun symbol-file symbol &optional type +@defun symbol-file symbol &optional type native-p This function returns the name of the file that defined @var{symbol}. If @var{type} is @code{nil}, then any kind of definition is acceptable. If @var{type} is @code{defun}, @code{defvar}, or @code{defface}, that @@ -1028,6 +1042,14 @@ The value is normally an absolute file name. It can also be @code{nil}, if the definition is not associated with any file. If @var{symbol} specifies an autoloaded function, the value can be a relative file name without extension. + +If the optional third argument @var{native-p} is non-@code{nil}, and +Emacs was built with native compilation support (@pxref{Native +Compilation}), this function will try to find the @file{.eln} file +that defined @var{symbol}, instead of the @file{.elc} or @file{.el} +file. If such a @file{.eln} file is found and is not outdated, the +function will return its absolute file name; otherwise it will report +the name of either the source or the byte-compiled file. @end defun The basis for @code{symbol-file} is the data in the variable @@ -1048,13 +1070,8 @@ list elements have these forms: The symbol @var{var} was defined as a variable. @item (defun . @var{fun}) The function @var{fun} was defined. -@item (t . @var{fun}) -The function @var{fun} was previously an autoload before this library -redefined it as a function. The following element is always @code{(defun . @var{fun})}, which represents defining @var{fun} as a function. -@item (autoload . @var{fun}) -The function @var{fun} was defined as an autoload. @item (defface . @var{face}) The face @var{face} was defined. @item (require . @var{feature}) @@ -1077,6 +1094,23 @@ The value of @code{load-history} may have one element whose @sc{car} is by adding the symbols defined to the element for the file being visited, rather than replacing that element. @xref{Eval}. +@kindex function-history @r{(function symbol property)} +In addition to @code{load-history}, every function keeps track of its +own history in the symbol property @code{function-history}. +The reason why functions are treated specially in this respect is that +it is common for functions to be defined in two steps in two different +files (typically, one of them is an autoload), so in order to be +able to properly @emph{unload} a file, we need to know more precisely +what that file did to the function definition. + +The symbol property @code{function-history} holds a list of the form +@w{@code{(@var{file1} @var{def2} @var{file2} @var{def3} ...)}}, where +@var{file1} is the last file that changed the definition and +@var{def2} was the definition before @var{file1}, set by @var{file2}, +etc. Logically this list should end with the name of the first file +that defined this function, but to save space this last element +is usually omitted. + @node Unloading @section Unloading @cindex unloading packages @@ -1091,7 +1125,7 @@ It undefines all functions, macros, and variables defined in that library with @code{defun}, @code{defalias}, @code{defsubst}, @code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}. It then restores any autoloads formerly associated with those symbols. -(Loading saves these in the @code{autoload} property of the symbol.) +(Loading saves these in the @code{function-history} property of the symbol.) Before restoring the previous definitions, @code{unload-feature} runs @code{remove-hook} to remove functions defined by the library from certain @@ -1156,7 +1190,7 @@ You don't need to give a directory or extension in the file name @var{library}. Normally, you just give a bare file name, like this: @example -(with-eval-after-load "js" (define-key js-mode-map "\C-c\C-c" 'js-eval)) +(with-eval-after-load "js" (keymap-set js-mode-map "C-c C-c" 'js-eval)) @end example To restrict which files can trigger the evaluation, include a diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index bc2f14883cb..f2adc01c8f7 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -244,6 +244,13 @@ This function works by calling the value)) @end group @end smallexample + +@findex read-string-from-buffer +If you have a long string (for instance, one that is several lines +long) that you wish to edit, using @code{read-string} may not be +ideal. In that case, popping to a new, normal buffer where the user +can edit the string may be more convenient, and you can use the +@code{read-string-from-buffer} function to do that. @end defun @defun read-regexp prompt &optional defaults history @@ -302,6 +309,22 @@ The optional argument @var{history}, if non-@code{nil}, is a symbol specifying a minibuffer history list to use (@pxref{Minibuffer History}). If it is omitted or @code{nil}, the history list defaults to @code{regexp-history}. + +@cindex @code{case-fold}, text property +@findex read-regexp-case-fold-search +The user can use the @kbd{M-c} command to indicate whether case +folding should be on or off. If the user has used this command, the +returned string will have the text property @code{case-fold} set to +either @code{fold} or @code{inhibit-fold}. It is up to the caller of +@code{read-regexp} to actually use this value, and the convenience +function @code{read-regexp-case-fold-search} is provided for that. A +typical usage pattern here might look like: + +@lisp +(let* ((regexp (read-regexp "Search for: ")) + (case-fold-search (read-regexp-case-fold-search regexp))) + (re-search-forward regexp)) +@end lisp @end defun @defopt read-regexp-defaults-function @@ -1115,6 +1138,11 @@ completion command (i.e., one of the commands in not an element of @var{collection}. @xref{Completion Commands}. @item +If a function, it is called with the input as the only argument. The +function should return a non-@code{nil} value if the input is +acceptable. + +@item Any other value of @var{require-match} behaves like @code{t}, except that the exit commands won't exit if it performs completion. @end itemize diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index cb748606ed9..75eb21522f1 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -269,6 +269,18 @@ normal-mode}), but tries to force it not to choose any modes in @var{avoided-modes}, if that argument is non-@code{nil}. @end defun +@defun clean-mode +Changing the major mode clears out most local variables, but it +doesn't remove all artifacts in the buffer (like text properties and +overlays). It's rare to change a buffer from one major mode to +another (except from @code{fundamental-mode} to everything else), so +this is usually not a concern. It can sometimes be convenient (mostly +when debugging a problem in a buffer) to do a ``full reset'' of the +buffer, and that's what the @code{clean-mode} major mode offers. It +will kill all local variables (even the permanently local ones), and +also removes all overlays and text properties. +@end defun + The easiest way to write a major mode is to use the macro @code{define-derived-mode}, which sets up the new mode as a variant of an existing major mode. @xref{Derived Modes}. We recommend using @@ -907,10 +919,8 @@ which in turn may have been changed in a mode hook. Here is a hypothetical example: @example -(defvar hypertext-mode-map - (let ((map (make-sparse-keymap))) - (define-key map [down-mouse-3] 'do-hyper-link) - map)) +(defvar-keymap hypertext-mode-map + "<down-mouse-3>" #'do-hyper-link) (define-derived-mode hypertext-mode text-mode "Hypertext" @@ -1051,12 +1061,22 @@ very end of every properly-written major mode command. @cindex Tabulated List mode Tabulated List mode is a major mode for displaying tabulated data, -i.e., data consisting of @dfn{entries}, each entry occupying one row of -text with its contents divided into columns. Tabulated List mode +i.e., data consisting of @dfn{entries}, each entry occupying one row +of text with its contents divided into columns. Tabulated List mode provides facilities for pretty-printing rows and columns, and sorting the rows according to the values in each column. It is derived from Special mode (@pxref{Basic Major Modes}). +@findex make-vtable +@cindex variable pitch tables + Tabulated List mode is geared towards displaying text using +monospaced fonts, using a single font and text size. If you want to +display a table using variable pitch fonts or images, +@code{make-vtable} can be used instead. vtable also support having +more than a single table in a buffer, or having a buffer that contains +both a table and additional text in it. @xref{Introduction,,, vtable}, +for more information. + Tabulated List mode is intended to be used as a parent mode by a more specialized major mode. Examples include Process Menu mode (@pxref{Process Information}) and Package Menu mode (@pxref{Package @@ -1141,10 +1161,11 @@ re-sorting entries. Comparison is done with @code{equal}. @item @var{contents} is a vector with the same number of elements as @code{tabulated-list-format}. Each vector element is either a string, -which is inserted into the buffer as-is, or a list @code{(@var{label} -. @var{properties})}, which means to insert a text button by calling -@code{insert-text-button} with @var{label} and @var{properties} as -arguments (@pxref{Making Buttons}). +which is inserted into the buffer as-is; an image descriptor, which is +used to insert an image (@pxref{Image Descriptors}); or a list +@w{@code{(@var{label} . @var{properties})}}, which means to insert a +text button by calling @code{insert-text-button} with @var{label} and +@var{properties} as arguments (@pxref{Making Buttons}). There should be no newlines in any of these strings. @end itemize @@ -1334,14 +1355,11 @@ the conventions listed above: ;; @r{Create the keymap for this mode.} @group -(defvar text-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\e\t" 'ispell-complete-word) - @dots{} - map) - "Keymap for `text-mode'. -Many other modes, such as `mail-mode', `outline-mode' and -`indented-text-mode', inherit all the commands defined in this map.") +(defvar-keymap text-mode-map + :doc "Keymap for `text-mode'. +Many other modes, such as `mail-mode' and `outline-mode', inherit all +the commands defined in this map." + "C-M-i" #'ispell-complete-word) @end group @end smallexample @@ -1411,13 +1429,11 @@ common. The following code sets up the common commands: @smallexample @group -(defvar lisp-mode-shared-map - (let ((map (make-sparse-keymap))) - (set-keymap-parent map prog-mode-map) - (define-key map "\e\C-q" 'indent-sexp) - (define-key map "\177" 'backward-delete-char-untabify) - map) - "Keymap for commands shared by all sorts of Lisp modes.") +(defvar-keymap lisp-mode-shared-map + :parent prog-mode-map + :doc "Keymap for commands shared by all sorts of Lisp modes." + "C-M-q" #'indent-sexp + "DEL" #'backward-delete-char-untabify) @end group @end smallexample @@ -1426,16 +1442,12 @@ And here is the code to set up the keymap for Lisp mode: @smallexample @group -(defvar lisp-mode-map - (let ((map (make-sparse-keymap)) - (menu-map (make-sparse-keymap "Lisp"))) - (set-keymap-parent map lisp-mode-shared-map) - (define-key map "\e\C-x" 'lisp-eval-defun) - (define-key map "\C-c\C-z" 'run-lisp) - @dots{} - map) - "Keymap for ordinary Lisp mode. -All commands in `lisp-mode-shared-map' are inherited by this map.") +(defvar-keymap lisp-mode-map + :doc "Keymap for ordinary Lisp mode. +All commands in `lisp-mode-shared-map' are inherited by this map." + :parent lisp-mode-shared-map + "C-M-x" #'lisp-eval-defun + "C-c C-z" #'run-lisp) @end group @end smallexample @@ -1899,6 +1911,16 @@ This means ``use in modes derived from @code{text-mode}, but nowhere else''. (There's an implicit @code{nil} element at the end.) @end defmac +@findex buffer-local-restore-state +@defmac buffer-local-set-state variable value... +Minor modes often set buffer-local variables that affect some features +in Emacs. When a minor mode is switched off, the mode is expected to +restore the previous state of these variables. This convenience macro +helps with doing that: It works much like @code{setq-local}, but +returns an object that can be used to restore these values back to +their previous values/states (using the companion function +@code{buffer-local-restore-state}). +@end defmac @node Mode Line Format @section Mode Line Format @@ -1961,8 +1983,26 @@ This function also forces an update of the menu bar and frame title. @end defun The selected window's mode line is usually displayed in a different -color using the face @code{mode-line}. Other windows' mode lines appear -in the face @code{mode-line-inactive} instead. @xref{Faces}. +color using the face @code{mode-line-active}. Other windows' mode +lines appear in the face @code{mode-line-inactive} instead. +@xref{Faces}. + +@defun mode-line-window-selected-p +If you want to have more extensive differences between the mode lines +in selected and non-selected windows, you can use this predicate in an +@code{:eval} construct. For instance, if you want to display the +buffer name in bold in selected windows, but in italics in the other +windows, you can say something like: + +@lisp +(setq-default + mode-line-buffer-identification + '(:eval (propertize "%12b" + 'face (if (mode-line-window-selected-p) + 'bold + 'italic)))) +@end lisp +@end defun @vindex mode-line-compact Some modes put a lot of data in the mode line, pushing elements at @@ -2534,7 +2574,23 @@ mode line feature, except that it's controlled by This variable, local in every buffer, specifies how to display the header line, for windows displaying the buffer. The format of the value is the same as for @code{mode-line-format} (@pxref{Mode Line Data}). -It is normally @code{nil}, so that ordinary buffers have no header line. +It is normally @code{nil}, so that ordinary buffers have no header +line. + +@findex header-line-indent-mode +If @code{display-line-numbers-mode} is used, and you want the header +line to be indented by the same amount as the buffer contents, you can +use the @code{header-line-indent-mode} minor mode. This minor mode +keeps the @code{header-line-indent} variable updated, so that you can +say something like: + +@lisp +(setq header-line-format + `("" header-line-format ,my-header-line)) +@end lisp + +This can be useful if you're displaying columnar data, and the header +line should align with that data in the buffer. @end defvar @defun window-header-line-height &optional window @@ -3173,7 +3229,9 @@ Non-@code{nil} means that regular expression matching for the sake of You can use @code{font-lock-add-keywords} to add additional search-based fontification rules to a major mode, and -@code{font-lock-remove-keywords} to remove rules. +@code{font-lock-remove-keywords} to remove rules. You can also +customize the @code{font-lock-ignore} option to selectively disable +fontification rules for keywords that match certain criteria. @defun font-lock-add-keywords mode keywords &optional how This function adds highlighting @var{keywords}, for the current buffer @@ -3243,6 +3301,99 @@ mode @emph{and} all modes derived from it, do this instead: font-lock-keyword-face))))) @end smallexample +@defopt font-lock-ignore +@cindex selectively disabling font-lock fontifications +This option defines conditions for selectively disabling +fontifications due to certain Font Lock keywords. If non-@code{nil}, +its value is a list of elements of the following form: + +@example +(@var{symbol} @var{condition} @dots{}) +@end example + +Here, @var{symbol} is a symbol, usually a major or minor mode. The +subsequent @var{condition}s of a @var{symbol}'s list element will be in +effect if @var{symbol} is bound and its value is non-@code{nil}. For +a mode's symbol, it means that the current major mode is derived from +that mode, or that minor mode is enabled in the buffer. When a +@var{condition} is in effect, any fontifications caused by +@code{font-lock-keywords} elements that match the @var{condition} will +be disabled. + +Each @var{condition} can be one of the following: + +@table @asis +@item a symbol +This condition matches any element of Font Lock keywords that +references the symbol. This is usually a face, but can be any symbol +referenced by an element of the @code{font-lock-keywords} list. The +symbol can contain wildcards: @code{*} matches any string in the +symbol'ss name, @code{?} matches a single character, and +@code{[@var{char-set}]}, where @var{char-set} is a string of one or +more characters, matches a single character from the set. + +@item a string +This condition matches any element of Font Lock keywords whose +@var{matcher} is a regexp which matches the string. In other words, +this condition matches a Font Lock rule which highlights the string. +Thus, the string could be a specific program keyword whose +highlighting you want to disable. + +@item @code{(pred @var{function})} +This condition matches any element of Font Lock keywords for which +@var{function}, when called with the element as the argument, returns +non-@code{nil}. + +@item @code{(not @var{condition})} +This matches if @var{condition} doesn’t. + +@item @code{(and @var{condition} @dots{})} +This matches if each of the @var{condition}s matches. + +@item @code{(or @var{condition} @dots{})} +This matches if at least one of the @var{condition}s matches. + +@item @code{(except @var{condition})} +This condition can only be used at top level or inside an +@code{or} clause. It undoes the effect of a previously matching +condition on the same level. +@end table +@end defopt + +As an example, consider the following setting: + +@smallexample +(setq font-lock-ignore + '((prog-mode font-lock-*-face + (except help-echo)) + (emacs-lisp-mode (except ";;;###autoload)") + (whitespace-mode whitespace-empty-at-bob-regexp) + (makefile-mode (except *)))) +@end smallexample + +Line by line, this does the following: + +@enumerate +@item +In all programming modes, disable fontifications due to all font-lock +keywords that apply one of the standard font-lock faces (excluding +strings and comments, which are covered by syntactic Font Lock). + +@item +However, keep any keywords that add a @code{help-echo} text property. + +@item +In Emacs Lisp mode, also keep the highlighting of autoload cookies, +which would have been excluded by the first condition. + +@item +When @code{whitespace-mode} (a minor mode) is enabled, also don't +highlight an empty line at beginning of buffer. + +@item +Finally, in Makefile mode, don't apply any conditions. +@end enumerate + @node Other Font Lock Variables @subsection Other Font Lock Variables @@ -3527,6 +3678,10 @@ the value is @code{nil}, Font Lock will call @code{jit-lock-register} (@pxref{Other Font Lock Variables}) to set up for automatic refontification of buffer text following a modified line to reflect the new syntactic context due to the change. + +To use only syntactic fontification, this variable should +be non-@code{nil}, while @code{font-lock-keywords} should be set to +@code{nil} (@pxref{Font Lock Basics}). @end defvar @defvar font-lock-syntax-table diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index a715b45a6c2..7b5e9adee29 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -1541,6 +1541,7 @@ editing. * Keymap Type:: What function a keystroke invokes. * Overlay Type:: How an overlay is represented. * Font Type:: Fonts for displaying text. +* Xwidget Type:: Embeddable widgets. @end menu @node Buffer Type @@ -1866,6 +1867,20 @@ syntax looks like @samp{#<font-object>}, @samp{#<font-spec>}, and @samp{#<font-entity>} respectively. @xref{Low-Level Font}, for a description of these Lisp objects. +@node Xwidget Type +@subsection Xwidget Type +@cindex xwidget type +@cindex xwidget-view type + + An @dfn{xwidget} is a special display element, such as a web +browser, that can be embedded inside a buffer. Each window that +displays an xwidget will also have an @dfn{xwidget view}, which on +X-Windows corresponds to a single X window used to display the widget. + +Neither of these objects are readable; their print syntaxes look like +@samp{#<xwidget>} and @samp{#<xwidget-view>}, respectively. +@xref{Xwidgets}, for a more detailed description of xwidgets. + @node Circular Objects @section Read Syntax for Circular Objects @cindex circular structure, read syntax @@ -2007,6 +2022,9 @@ with references to further information. @item byte-code-function-p @xref{Byte-Code Type, byte-code-function-p}. +@item compiled-function-p +@xref{Byte-Code Type, compiled-function-p}. + @item case-table-p @xref{Case Tables, case-table-p}. diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index e7ce40b1f25..35828018417 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -329,10 +329,10 @@ file will not inhibit the message for someone else. @end defopt @defopt initial-scratch-message -This variable, if non-@code{nil}, should be a string, which is -treated as documentation to be -inserted into the @file{*scratch*} buffer when Emacs starts up. If it -is @code{nil}, the @file{*scratch*} buffer is empty. +This variable, if non-@code{nil}, should be a string, which is treated +as documentation to be inserted into the @file{*scratch*} buffer when +Emacs starts up or when that buffer is recreated. If it is +@code{nil}, the @file{*scratch*} buffer is empty. @end defopt @noindent @@ -363,6 +363,9 @@ Do not load the @file{site-start} library. @itemx -Q Equivalent to @samp{-q --no-site-file --no-splash}. @c and --no-site-lisp, but let's not mention that here. + +@item --init-directory +Specify the directory to use when finding the Emacs init files. @end table @@ -696,7 +699,7 @@ If you started Emacs from a terminal, the parent process normally resumes control. The low-level primitive for killing Emacs is @code{kill-emacs}. -@deffn Command kill-emacs &optional exit-data +@deffn Command kill-emacs &optional exit-data restart This command calls the hook @code{kill-emacs-hook}, then exits the Emacs process and kills it. @@ -711,6 +714,10 @@ input) can read them. If @var{exit-data} is neither an integer nor a string, or is omitted, that means to use the (system-specific) exit status which indicates successful program termination. + +If @var{restart} is non-@code{nil}, instead of just exiting at the +end, start a new Emacs process, using the same command line arguments +as the currently running Emacs process. @end deffn @cindex SIGTERM @@ -753,6 +760,13 @@ the remaining functions in this hook. Calling @code{kill-emacs} directly does not run this hook. @end defopt +@deffn Command restart-emacs +This command does the same as @code{save-buffers-kill-emacs}, but +instead of just killing the current Emacs process at the end, it'll +restart a new Emacs process, using the same command line arguments as +the currently running Emacs process. +@end deffn + @node Suspending Emacs @subsection Suspending Emacs @cindex suspending Emacs @@ -947,6 +961,9 @@ actually Linux is just the kernel, not the whole system.) @item gnu/kfreebsd A GNU (glibc-based) system with a FreeBSD kernel. +@item haiku +The Haiku operating system, a derivative of the Be Operating System. + @item hpux Hewlett-Packard HPUX operating system. @@ -1297,10 +1314,16 @@ zone. @cindex Lisp timestamp @cindex timestamp, Lisp +@cindex Coordinated Universal Time +@cindex Universal Time +@cindex UTC +@cindex leap seconds Many functions like @code{current-time} and @code{file-attributes} return @dfn{Lisp timestamp} values that count seconds, and that can represent absolute time by counting seconds since the @dfn{epoch} of -1970-01-01 00:00:00 UTC. +1970-01-01 00:00:00 UTC (Coordinated Universal Time). Typically these +counts ignore leap seconds; however, GNU and some other operating +systems can be configured to count leap seconds. Although traditionally Lisp timestamps were integer pairs, their form has evolved and programs ordinarily should not depend on the @@ -1322,11 +1345,7 @@ A pair of integers @code{(@var{ticks} . @var{hz})}, where @var{hz} is positive. This represents @var{ticks}/@var{hz} seconds, which is the same time as plain @var{ticks} if @var{hz} is 1. A common value for @var{hz} is 1000000000, for a nanosecond-resolution -clock.@footnote{Currently @var{hz} should be at least 65536 to avoid -compatibility warnings when the timestamp is passed to standard -functions, as previous versions of Emacs would interpret such a -timestamps differently due to backward-compatibility concerns. These -warnings are intended to be removed in a future Emacs version.} +clock. @item A list of four integers @code{(@var{high} @var{low} @var{micro} @@ -1340,7 +1359,8 @@ This represents the number of seconds using the formula: @tex $high \times 2^{16} + low + micro \times 10^{-6} + pico \times 10^{-12}$. @end tex -In some cases, functions may default to returning two- or +If @code{current-time-list} is @code{t}, +some functions may default to returning two- or three-element lists, with omitted @var{micro} and @var{pico} components defaulting to zero. On all current machines @var{pico} is a multiple of 1000, but this @@ -1349,9 +1369,9 @@ may change as higher-resolution clocks become available. @cindex time value Function arguments, e.g., the @var{time} argument to -@code{current-time-string}, accept a more-general @dfn{time value} +@code{format-time-string}, accept a more-general @dfn{time value} format, which can be a Lisp timestamp, @code{nil} for the current -time, a single floating-point number for seconds, or a list +time, a finite floating-point number for seconds, or a list @code{(@var{high} @var{low} @var{micro})} or @code{(@var{high} @var{low})} that is a truncated list timestamp with missing elements taken to be zero. @@ -1361,8 +1381,8 @@ Time values can be converted to and from calendrical and other forms. Some of these conversions rely on operating system functions that limit the range of possible time values, and signal an error such as @samp{"Specified time is not representable"} if the -limits are exceeded. For instance, a system may not support years -before 1970, or years before 1901, or years far in the future. +limits are exceeded. For instance, a system might not support +timestamps before the epoch, or years far in the future. You can convert a time value into a human-readable string using @code{format-time-string}, into a Lisp timestamp using @code{time-convert}, and into other forms using @@ -1394,13 +1414,28 @@ The operating system limits the range of time and zone values. @end example @end defun +@defvar current-time-list +This boolean variable is a transition aid. If @code{t}, +@code{current-time} and related functions return timestamps in list +form, typically @code{(@var{high} @var{low} @var{micro} @var{pico})}; +otherwise, they use @code{(@var{ticks} . @var{hz})} form. Currently +this variable defaults to @code{t}, for behavior compatible with +previous Emacs versions. Developers are encouraged to test +timestamp-related code with this variable set to @code{nil}, as it +will default to @code{nil} in a future Emacs version, and will be +removed in some version after that. +@end defvar + @defun current-time This function returns the current time as a Lisp timestamp. -Although the timestamp takes the form @code{(@var{high} @var{low} -@var{micro} @var{pico})} in the current Emacs release, this is -planned to change in a future Emacs version. You can use the -@code{time-convert} function to convert a timestamp to some other -form. @xref{Time Conversion}. +If @code{current-time-list} is @code{nil}, +the timestamp has the form @code{(@var{ticks} . @var{hz})} where +@var{ticks} counts clock ticks and @var{hz} is the clock ticks per second. +Otherwise, the timestamp has the list form +@code{(@var{high} @var{low} @var{usec} @var{psec})}. +You can use @code{(time-convert nil t)} or @code{(time-convert nil 'list)} +to obtain a particular form regardless of the value of +@code{current-time-list}. @xref{Time Conversion}. @end defun @defun float-time &optional time @@ -1416,6 +1451,13 @@ as @samp{0.1} but is slightly greater than 1/10. @code{time-to-seconds} is an alias for this function. @end defun +@defun current-cpu-time +Return the current @acronym{CPU} time along with its resolution. The +return value is a pair @code{(CPU-TICKS . TICKS-PER-SEC)}. The +@var{CPU-TICKS} counter can wrap around, so values cannot be +meaningfully compared if too much time has passed between them. +@end defun + @node Time Zone Rules @section Time Zone Rules @cindex time zone rules @@ -1428,11 +1470,11 @@ to default to Universal Time with @code{(setenv "TZ" "UTC0")}. If which is a platform-dependent default time zone. The set of supported @env{TZ} strings is system-dependent. GNU and -many other systems support the tzdata database, e.g., +many other systems support TZDB timezones, e.g., @samp{"America/New_York"} specifies the time zone and daylight saving time history for locations near New York City. GNU and most other systems support POSIX-style @env{TZ} strings, e.g., -@samp{"EST+5EDT,M4.1.0/2,M10.5.0/2"} specifies the rules used in New +@samp{"EST5EDT,M4.1.0,M10.5.0"} specifies the rules used in New York from 1987 through 2006. All systems support the string @samp{"UTC0"} meaning Universal Time. @@ -1484,46 +1526,45 @@ The operating system limits the range of time and zone values. These functions convert time values (@pxref{Time of Day}) to Lisp timestamps, or into calendrical information and vice versa. - Many 32-bit operating systems are limited to system times containing -32 bits of information in their seconds component; these systems -typically handle only the times from 1901-12-13 20:45:52 through -2038-01-19 03:14:07 Universal Time. However, 64-bit and some 32-bit operating -systems have larger seconds components, and can represent times far in -the past or future. - - Calendrical conversion functions always use the Gregorian calendar, even -for dates before the Gregorian calendar was introduced. Year numbers -count the number of years since the year 1 BC, and do not skip zero + Many operating systems use 64-bit signed integers to count seconds, +and can represent times far in the past or future. However, some are +more limited. For example, old-fashioned operating systems that use +32-bit signed integers typically handle only times from 1901-12-13 +20:45:52 through 2038-01-19 03:14:07 Universal Time. + + Calendrical conversion functions use the Gregorian calendar even for +dates before the Gregorian calendar was introduced, and for dates in +the far distant past or future for which the Gregorian calendar +is wildly inaccurate and disagrees with common practice in scientific fields +like astronomy and paleontology, which use Julian-calendar year lengths. +Year numbers count since the year 1 BCE, and do not skip zero as traditional Gregorian years do; for example, the year number -@minus{}37 represents the Gregorian year 38 BC@. +@minus{}37 represents the Gregorian year 38 BCE@. -@defun time-convert time &optional form +@defun time-convert time form This function converts a time value into a Lisp timestamp. -The optional @var{form} argument specifies the timestamp form to be -returned. If @var{form} is the symbol @code{integer}, this function -returns an integer count of seconds. If @var{form} is a positive -integer, it specifies a clock frequency and this function returns an -integer-pair timestamp @code{(@var{ticks} -. @var{form})}.@footnote{Currently a positive integer @var{form} -should be at least 65536 if the returned value is intended to be given -to standard functions expecting Lisp timestamps.} If @var{form} is +The @var{form} argument specifies the timestamp form to be returned. +If @var{form} is the symbol @code{integer}, this function returns an +integer count of seconds. If @var{form} is a positive integer, it +specifies a clock frequency and this function returns an integer-pair +timestamp @code{(@var{ticks} . @var{form})}. If @var{form} is @code{t}, this function treats it as a positive integer suitable for representing the timestamp; for example, it is treated as 1000000000 -if @var{time} is nil and the platform timestamp has nanosecond +if @var{time} is @code{nil} and the platform timestamp has nanosecond resolution. If @var{form} is @code{list}, this function returns an integer list @code{(@var{high} @var{low} @var{micro} @var{pico})}. -Although an omitted or @code{nil} @var{form} currently acts like +Although a @code{nil} @var{form} currently acts like @code{list}, this is planned to change in a future Emacs version, so callers requiring list timestamps should pass @code{list} explicitly. -If @var{time} is infinite or a NaN, this function signals an error. +If @var{time} is not a time value, this function signals an error. Otherwise, if @var{time} cannot be represented exactly, conversion truncates it toward minus infinity. When @var{form} is @code{t}, conversion is always exact so no truncation occurs, and the returned clock resolution is no less than that of @var{time}. By way of -contrast, @code{float-time} can convert any Lisp time value without -signaling an error, although the result might not be exact. +contrast, although @code{float-time} can also convert any time value +without signaling an error, the result might not be exact. @xref{Time of Day}. For efficiency this function might return a value that is @code{eq} to @@ -1608,62 +1649,15 @@ this default may change in future Emacs releases, so callers requiring a particular form should specify @var{form}. @strong{Common Lisp Note:} Common Lisp has different meanings for -@var{dow} and @var{utcoff}, and its @var{second} is an integer between -0 and 59 inclusive. +@var{dow}, @code{dst} and @var{utcoff}, and its @var{second} is an +integer between 0 and 59 inclusive. -To access (or alter) the elements in the time value, the +To access (or alter) the elements in the calendrical information, the @code{decoded-time-second}, @code{decoded-time-minute}, @code{decoded-time-hour}, @code{decoded-time-day}, @code{decoded-time-month}, @code{decoded-time-year}, @code{decoded-time-weekday}, @code{decoded-time-dst} and @code{decoded-time-zone} accessors can be used. - -For instance, to increase the year in a decoded time, you could say: - -@lisp -(setf (decoded-time-year decoded-time) - (+ (decoded-time-year decoded-time) 4)) -@end lisp - -Also see the following function. - -@end defun - -@defun decoded-time-add time delta -This function takes a decoded time structure and adds @var{delta} -(also a decoded time structure) to it. Elements in @var{delta} that -are @code{nil} are ignored. - -For instance, if you want ``same time next month'', you -could say: - -@lisp -(let ((time (decode-time nil nil t)) - (delta (make-decoded-time :month 2))) - (encode-time (decoded-time-add time delta))) -@end lisp - -If this date doesn't exist (if you're running this on January 31st, -for instance), then the date will be shifted back until you get a -valid date (which will be February 28th or 29th, depending). - -Fields are added in a most to least significant order, so if the -adjustment described above happens, it happens before adding days, -hours, minutes or seconds. - -The values in @var{delta} can be negative to subtract values instead. - -The return value is a decoded time structure. -@end defun - -@defun make-decoded-time &key second minute hour day month year dst zone -Return a decoded time structure with only the given keywords filled -out, leaving the rest @code{nil}. For instance, to get a structure -that represents ``two months'', you could say: - -@lisp -(make-decoded-time :month 2) -@end lisp @end defun @defun encode-time time &rest obsolescent-arguments @@ -1673,9 +1667,26 @@ It can act as the inverse of @code{decode-time}. Ordinarily the first argument is a list @code{(@var{second} @var{minute} @var{hour} @var{day} @var{month} @var{year} @var{ignored} @var{dst} @var{zone})} that specifies a -decoded time in the style of @code{decode-time}, so that -@code{(encode-time (decode-time ...))} works. For the meanings of -these list members, see the table under @code{decode-time}. +decoded time in the style of @code{decode-time}. For the meanings of +these list elements, see the table under @code{decode-time}. +In particular, @var{dst} says how to interpret timestamps during a +daylight saving fallback when timestamps are repeated. +If @var{dst} is @minus{}1, the DST value is guessed; if it +is @code{t} or @code{nil} the timestamp with that DST value +is returned, with an error signaled if no such timestamp exists. +Unfortunately a @var{dst} value of @code{t} or @code{nil} does not +disambiguate timestamps duplicated when a TZDB-based timezone moves +further west of Greenwich, such as disambiguating the two +standard-time timestamps 2020-12-27 01:30 when @var{zone} is +@samp{"Europe/Volgograd"}, which at 02:00 that day changed +standard time from 4 to 3 hours east of Greenwich; if you need to +handle situations like this you can use a numeric @var{zone} to +disambiguate instead. + +The first argument can also be a list @code{(@var{second} @var{minute} +@var{hour} @var{day} @var{month} @var{year})}, which is treated like +the list @code{(@var{second} @var{minute} @var{hour} @var{day} +@var{month} @var{year} nil -1 nil)}. As an obsolescent calling convention, this function can be given six or more arguments. The first six arguments @var{second}, @@ -1684,14 +1695,18 @@ specify most of the components of a decoded time. If there are more than six arguments the @emph{last} argument is used as @var{zone} and any other extra arguments are ignored, so that @code{(apply #'encode-time (decode-time ...))} works. In this obsolescent -convention, @var{zone} defaults to the current time zone rule -(@pxref{Time Zone Rules}), and @var{dst} is treated as if it was -@minus{}1. +convention, @var{dst} is @minus{}1 and @var{zone} defaults to the +current time zone rule (@pxref{Time Zone Rules}). +When modernizing an obsolescent caller, ensure that the more-modern +list equivalent contains 9 elements with a @code{dst} element that +is @minus{}1, not @code{nil}. Year numbers less than 100 are not treated specially. If you want them to stand for years above 1900, or years above 2000, you must alter them yourself before you call @code{encode-time}. The operating system limits the range of time and zone values. +However, timestamps ranging from the epoch to the near future are +always supported. The @code{encode-time} function acts as a rough inverse to @code{decode-time}. For example, you can pass the output of @@ -1704,6 +1719,33 @@ the latter to the former as follows: You can perform simple date arithmetic by using out-of-range values for @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}; for example, day 0 means the day preceding the given month. +Take care when doing so, as it is common for this to fail in some cases. +For example: + +@lisp +;; Try to compute the time one month from now. +;; Watch out; this might not work as expected. +(let ((time (decode-time))) + (setf (decoded-time-month time) + (+ (decoded-time-month time) 1)) + time) +@end lisp + +@noindent +Unfortunately, this code might not work as expected if the resulting +time is invalid due to month length differences, +daylight saving transitions, time zone changes, +or missing leap days or leap seconds. For example, if executed on +January 30 this code yields a nonexistent date February 30, +which @code{encode-time} would adjust to early March. +Similarly, adding four years to February 29, 2096 would yield the +nonexistent date February 29, 2100; and adding one hour to 01:30 on +March 13, 2022 in New York would yield a timestamp 02:30 that does not +exist because clocks sprang forward from 02:00 to 03:00 that day. +To avoid some (though not all) of the problem, you +can base calculations on the middle of the affected unit, e.g., start +at the 15th of the month when adding months. Alternatively, you can use the +@file{calendar} and @file{time-date} libraries. @end defun @node Time Parsing @@ -1712,36 +1754,27 @@ for example, day 0 means the day preceding the given month. @cindex time formatting @cindex formatting time values - These functions convert time values to text in a string, and vice versa. -Time values include @code{nil}, numbers, and Lisp timestamps -(@pxref{Time of Day}). + These functions convert time values to text in a string, and vice +versa. Time values are either represented as a Lisp timestamp +(@pxref{Time of Day}) or a decoded time structure (@pxref{Time +Conversion}). @defun date-to-time string This function parses the time-string @var{string} and returns the corresponding Lisp timestamp. The argument @var{string} should represent a date-time, and should be in one of the forms recognized by @code{parse-time-string} (see below). This function assumes Universal -Time if @var{string} lacks explicit time zone information. +Time if @var{string} lacks explicit time zone information, +and assumes earliest values if @var{string} lacks month, day, or time. The operating system limits the range of time and zone values. @end defun @defun parse-time-string string -This function parses the time-string @var{string} into a list of the -following form: - -@example -(@var{sec} @var{min} @var{hour} @var{day} @var{mon} @var{year} @var{dow} @var{dst} @var{tz}) -@end example - -@noindent -The format of this list is the same as what @code{decode-time} accepts -(@pxref{Time Conversion}), and is described in more detail there. Any -@code{dst} element that cannot be determined from the input is set to -@minus{}1, and any other unknown element is set to -@code{nil}. The argument @var{string} should resemble an RFC 822 (or later) or -ISO 8601 string, like ``Fri, 25 Mar 2016 16:24:56 +0100'' or -``1998-09-12T12:21:54-0200'', but this function will attempt to parse -less well-formed time strings as well. +This function parses the time-string @var{string} into a decoded time +structure (@pxref{Time Conversion}). The argument @var{string} should +resemble an RFC 822 (or later) or ISO 8601 string, like ``Fri, 25 Mar +2016 16:24:56 +0100'' or ``1998-09-12T12:21:54-0200'', but this +function will attempt to parse less well-formed time strings as well. @end defun @vindex ISO 8601 date/time strings @@ -1758,11 +1791,11 @@ time structures, except the final one, which returns three of them @end defun @defun format-time-string format-string &optional time zone - -This function converts @var{time} (or the current time, if -@var{time} is omitted or @code{nil}) to a string according to -@var{format-string}. The conversion uses the time zone rule @var{zone}, which -defaults to the current time zone rule. @xref{Time Zone Rules}. The argument +This function converts @var{time} (which should be a Lisp timestamp, +and defaults to the current time if @var{time} is omitted or +@code{nil}) to a string according to @var{format-string}. The +conversion uses the time zone rule @var{zone}, which defaults to the +current time zone rule. @xref{Time Zone Rules}. The argument @var{format-string} may contain @samp{%}-sequences which say to substitute parts of the time. Here is a table of what the @samp{%}-sequences mean: @@ -1957,6 +1990,10 @@ encountered. For example, the default format used by @w{@code{"%Y, %D, %H, %M, %z%S"}} means that the number of seconds will always be produced, but years, days, hours, and minutes will only be shown if they are non-zero. +@item %x +Non-printing control flag that works along the same lines as +@samp{%z}, but instead suppresses printing of trailing zero-value time +elements. @item %% Produces a literal @samp{%}. @end table @@ -2020,25 +2057,28 @@ interactively, it prints the duration in the echo area. These functions perform calendrical computations using time values (@pxref{Time of Day}). As with any time value, a value of @code{nil} for any of their -time-value arguments stands for the current system time, and a single +time-value arguments stands for the current system time, and a finite number stands for the number of seconds since the epoch. @defun time-less-p t1 t2 -This returns @code{t} if time value @var{t1} is less than time value +This returns @code{t} if the time value @var{t1} is less than the time value @var{t2}. -The result is @code{nil} if either argument is a NaN. @end defun @defun time-equal-p t1 t2 -This returns @code{t} if @var{t1} and @var{t2} are equal time values. -The result is @code{nil} if either argument is a NaN. +This returns @code{t} if the two time values @var{t1} and @var{t2} are +equal. The result is @code{nil} if either argument is a NaN. +For the purpose of comparison, a @code{nil} argument represents the +current time with infinite resolution, so this function returns +@code{nil} if one argument is @code{nil} and the other is not, and +callers can therefore use @code{nil} to represent an unknown time +value that does not equal any timestamp. @end defun @defun time-subtract t1 t2 This returns the time difference @var{t1} @minus{} @var{t2} between -two time values, as a Lisp time value. The result is exact and its clock +two time values, as a Lisp timestamp. The result is exact and its clock resolution is no worse than the worse of its two arguments' resolutions. -The result is floating-point only if it is infinite or a NaN@. If you need the difference in units of elapsed seconds, you can convert it with @code{time-convert} or @code{float-time}. @xref{Time Conversion}. @@ -2187,7 +2227,13 @@ In most cases, @var{repeat} has no effect on when @emph{first} call takes place---@var{time} alone specifies that. There is one exception: if @var{time} is @code{t}, then the timer runs whenever the time is a multiple of @var{repeat} seconds after the epoch. This is useful for -functions like @code{display-time}. +functions like @code{display-time}. For instance, the following will +make @var{function} run at every ``whole'' minute (e.g., +@samp{11:03:00}, @samp{11:04:00}, etc): + +@example +(run-at-time t 60 @var{function}) +@end example If Emacs didn't get any CPU time when the timer would have run (for example if the system was busy running another process or if the @@ -2697,6 +2743,13 @@ if it is non-@code{nil}; this can be overridden by binding @code{coding-system-for-write} to a coding system of you choice (@pxref{Explicit Encoding}). +In batch mode, Emacs will enlarge the value of the +@code{gc-cons-percentage} variable from the default of @samp{0.1} up to +@samp{1.0}. Batch jobs that are supposed to run for a long time +should adjust the limit back down again, because this means that less +garbage collection will be performed by default (and more memory +consumed). + @defvar noninteractive This variable is non-@code{nil} when Emacs is running in batch mode. @end defvar @@ -3242,6 +3295,14 @@ Removes an existing file watch specified by its @var{descriptor}. @code{file-notify-add-watch}. @end defun +@deffn Command file-notify-rm-all-watches +Removes all existing file notification watches from Emacs. + +Use this command with caution, because it could have unexpected side +effects on packages relying on file watches. It is intended mainly +for debugging purposes, or when Emacs has been stalled. +@end deffn + @defun file-notify-valid-p descriptor Checks a watch specified by its @var{descriptor} for validity. @var{descriptor} should be an object returned by diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index ca1166caac4..7945232bf8f 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -387,6 +387,16 @@ Return the position that @code{(end-of-line @var{count})} would move to. @end defun +@defun pos-bol &optional count +Like @code{line-beginning-position}, but ignores fields (and is more +efficient). +@end defun + +@defun pos-eol &optional count +Like @code{line-end-position}, but ignores fields (and is more +efficient). +@end defun + @deffn Command forward-line &optional count @cindex beginning of line This function moves point forward @var{count} lines, to the beginning of @@ -1002,6 +1012,12 @@ positions. In an interactive call, @var{start} and @var{end} are set to the bounds of the current region (point and the mark, with the smallest first). + +Note that, in rare circumstances, Emacs may decide to leave, for +performance reasons, the accessible portion of the buffer unchanged +after a call to @code{narrow-to-region}. This can happen when a Lisp +program is called via low-level hooks, such as +@code{jit-lock-functions}, @code{post-command-hook}, etc. @end deffn @deffn Command narrow-to-page &optional move-count @@ -1027,6 +1043,12 @@ It is equivalent to the following expression: @end example @end deffn +Note that, in rare circumstances, Emacs may decide to leave, for +performance reasons, the accessible portion of the buffer unchanged +after a call to @code{widen}. This can happen when a Lisp program is +called via low-level hooks, such as @code{jit-lock-functions}, +@code{post-command-hook}, etc. + @defun buffer-narrowed-p This function returns non-@code{nil} if the buffer is narrowed, and @code{nil} otherwise. diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 3fa6c844ae9..db6b4c35ef7 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -197,7 +197,7 @@ gives special treatment to certain characters, and if these characters occur in the file name, they will confuse the shell. To handle these characters, use the function @code{shell-quote-argument}: -@defun shell-quote-argument argument +@defun shell-quote-argument argument &optional posix This function returns a string that represents, in shell syntax, an argument whose actual contents are @var{argument}. It should work reliably to concatenate the return value into a shell command @@ -227,6 +227,15 @@ a shell command: " " (shell-quote-argument newfile)) @end example + +If the optional @var{posix} argument is non-@code{nil}, @var{argument} +is quoted according to POSIX shell quoting rules, regardless of the +system’s shell. This is useful when your shell could run on a remote +host, which requires a POSIX shell in general. + +@example +(shell-quote-argument "foo > bar" (file-remote-p default-directory)) +@end example @end defun @cindex quoting and unquoting command-line arguments @@ -696,12 +705,13 @@ coding system will apply. @xref{Default Coding Systems}. Initialize the type of device used to communicate with the subprocess. Possible values are @code{pty} to use a pty, @code{pipe} to use a pipe, or @code{nil} to use the default derived from the value of the -@code{process-connection-type} variable. This parameter and the value -of @code{process-connection-type} are ignored if a non-@code{nil} -value is specified for the @code{:stderr} parameter; in that case, the -type will always be @code{pipe}. On systems where ptys are not -available (MS-Windows), this parameter is likewise ignored, and pipes -are used unconditionally. +@code{process-connection-type} variable. If @var{type} is a cons cell +@w{@code{(@var{input} . @var{output})}}, then @var{input} will be used +for standard input and @var{output} for standard output (and standard +error if @code{:stderr} is @code{nil}). + +On systems where ptys are not available (MS-Windows), this parameter +is ignored, and pipes are used unconditionally. @item :noquery @var{query-flag} Initialize the process query flag to @var{query-flag}. @@ -966,6 +976,15 @@ use the function @code{process-tty-name} (@pxref{Process Information}). @end defvar +@defvar process-error-pause-time +If a process sentinel/filter function has an error, Emacs will (by +default) pause Emacs for @code{process-error-pause-time} seconds after +displaying this error, so that users will see the error in question. +However, this can lead to situations where Emacs becomes unresponsive +(if there's a lot of these errors happening), so this can be disabled +by setting @code{process-error-pause-time} to 0. +@end defvar + @node Deleting Processes @section Deleting Processes @cindex deleting processes @@ -993,16 +1012,18 @@ terminated (due to calling @code{exit} or to a signal). If it is they exit. @end defopt -@defun delete-process process +@defun delete-process &optional process This function deletes a process, killing it with a @code{SIGKILL} signal if the process was running a program. The argument may be a process, the name of a process, a buffer, or the name of a buffer. (A buffer or buffer-name stands for the process that -@code{get-buffer-process} returns.) Calling @code{delete-process} on -a running process terminates it, updates the process status, and runs -the sentinel immediately. If the process has already terminated, -calling @code{delete-process} has no effect on its status, or on the -running of its sentinel (which will happen sooner or later). +@code{get-buffer-process} returns, and a missing or @code{nil} +@var{process} means that the current buffer's process should be +killed.) Calling @code{delete-process} on a running process +terminates it, updates the process status, and runs the sentinel +immediately. If the process has already terminated, calling +@code{delete-process} has no effect on its status, or on the running +of its sentinel (which will happen sooner or later). If the process object represents a network, serial, or pipe connection, its status changes to @code{closed}; otherwise, it changes @@ -1222,15 +1243,24 @@ that are already closed, the value is either 0 or 256, depending on whether the connection was closed normally or abnormally. @end defun -@defun process-tty-name process +@defun process-tty-name process &optional stream This function returns the terminal name that @var{process} is using for its communication with Emacs---or @code{nil} if it is using pipes instead of a pty (see @code{process-connection-type} in -@ref{Asynchronous Processes}). If @var{process} represents a program -running on a remote host, the terminal name used by that program on -the remote host is provided as process property @code{remote-tty}. If -@var{process} represents a network, serial, or pipe connection, the -value is @code{nil}. +@ref{Asynchronous Processes}). By default, this function returns the +terminal name if any of @var{process}'s standard streams use a +terminal. If @var{stream} is one of @code{stdin}, @code{stdout}, or +@code{stderr}, this function returns the terminal name (or @code{nil}, +as above) that @var{process} uses for that stream specifically. You +can use this to determine whether a particular stream uses a pipe or a +pty. + +If @var{process} represents a program running on a remote host, this +function returns the @emph{local} terminal name that communicates with +@var{process}; you can get the terminal name used by that program on +the remote host with the process property @code{remote-tty}. If +@var{process} represents a network, serial, or pipe connection, this +function always returns @code{nil}. @end defun @defun process-coding-system process @@ -1413,11 +1443,13 @@ non-@code{nil}, you can think of this function as typing @kbd{C-c} on the terminal by which Emacs talks to the subprocess. @end defun -@defun kill-process &optional process current-group -This function kills the process @var{process} by sending the +@deffn Command kill-process &optional process current-group +This command kills the process @var{process} by sending the signal @code{SIGKILL}. This signal kills the subprocess immediately, -and cannot be handled by the subprocess. -@end defun +and cannot be handled by the subprocess. Interactively, it'll prompt +the user for a process name, defaulting to the process (if any) in the +current buffer. +@end deffn @defun quit-process &optional process current-group This function sends the signal @code{SIGQUIT} to the process @@ -1452,7 +1484,7 @@ incoming data from the connection. For serial connections, data that arrived during the time the process was stopped might be lost. @end defun -@deffn Command signal-process process signal +@deffn Command signal-process process signal &optional remote This function sends a signal to process @var{process}. The argument @var{signal} specifies which signal to send; it should be an integer, or a symbol whose name is a signal. @@ -1460,12 +1492,18 @@ or a symbol whose name is a signal. The @var{process} argument can be a system process @acronym{ID} (an integer); that allows you to send signals to processes that are not children of Emacs. @xref{System Processes}. + +If @var{process} is a process object which contains the property +@code{remote-pid}, or @var{process} is a number and @var{remote} is a +remote file name, @var{process} is interpreted as process on the +respective remote host, which will be the process to signal. @end deffn Sometimes, it is necessary to send a signal to a non-local asynchronous process. This is possible by writing an own -@code{interrupt-process} implementation. This function must be added -then to @code{interrupt-process-functions}. +@code{interrupt-process} or @code{signal-process} implementation. +This function must be added then to @code{interrupt-process-functions} +or @code{signal-process-functions}, respectively. @defvar interrupt-process-functions This variable is a list of functions to be called for @@ -1478,6 +1516,17 @@ default function, which shall always be the last in this list, is This is the mechanism, how Tramp implements @code{interrupt-process}. @end defvar +@defvar signal-process-functions +This variable is a list of functions to be called for +@code{signal-process}. The arguments of the functions are the same as +for @code{signal-process}. These functions are called in the order of +the list, until one of them returns non-@code{nil}. The default +function, which shall always be the last in this list, is +@code{internal-default-signal-process}. + +This is the mechanism, how Tramp implements @code{signal-process}. +@end defvar + @node Output from Processes @section Receiving Output from Processes @cindex process output @@ -1491,20 +1540,11 @@ a buffer, which is called the associated buffer of the process default filter discards the output. If the subprocess writes to its standard error stream, by default -the error output is also passed to the process filter function. If -Emacs uses a pseudo-TTY (pty) for communication with the subprocess, -then it is impossible to separate the standard output and standard -error streams of the subprocess, because a pseudo-TTY has only one -output channel. In that case, if you want to keep the output to those -streams separate, you should redirect one of them to a file---for -example, by using an appropriate shell command via -@code{start-process-shell-command} or a similar function. - - Alternatively, you could use the @code{:stderr} parameter with a +the error output is also passed to the process filter function. +Alternatively, you could use the @code{:stderr} parameter with a non-@code{nil} value in a call to @code{make-process} (@pxref{Asynchronous Processes, make-process}) to make the destination -of the error output separate from the standard output; in that case, -Emacs will use pipes for communicating with the subprocess. +of the error output separate from the standard output. When a subprocess terminates, Emacs reads any pending output, then stops reading output from that subprocess. Therefore, if the @@ -1920,7 +1960,6 @@ because @var{seconds} can be floating point to specify waiting a fractional number of seconds. If @var{seconds} is 0, the function accepts whatever output is pending but does not wait. -@c Emacs 22.1 feature If @var{process} is a process, and the argument @var{just-this-one} is non-@code{nil}, only output from that process is handled, suspending output from other processes until some output has been received from that @@ -2221,9 +2260,8 @@ query flag of all processes is ignored. In addition to accessing and manipulating processes that are subprocesses of the current Emacs session, Emacs Lisp programs can -also access other processes running on the same machine. We call -these @dfn{system processes}, to distinguish them from Emacs -subprocesses. +also access other processes. We call these @dfn{system processes}, to +distinguish them from Emacs subprocesses. Emacs provides several primitives for accessing system processes. Not all platforms support these primitives; on those which don't, @@ -2235,6 +2273,9 @@ system. Each process is identified by its @acronym{PID}, a numerical process ID that is assigned by the OS and distinguishes the process from all the other processes running on the same machine at the same time. + +If @code{default-directory} points to a remote host, processes of that +host are returned. @end defun @defun process-attributes pid @@ -2246,6 +2287,9 @@ attribute @var{key}s that this function can return are listed below. Not all platforms support all of these attributes; if an attribute is not supported, its association will not appear in the returned alist. +If @code{default-directory} points to a remote host, @var{pid} is +regarded as process of that host. + @table @code @item euid The effective user ID of the user who invoked the process. The @@ -2371,8 +2415,9 @@ occupied by the process in the machine's physical memory. @item pcpu The percentage of the CPU time used by the process since it started. -The corresponding @var{value} is a floating-point number between 0 and -100. +The corresponding @var{value} is a nonnegative floating-point number. +Although in theory the number can exceed 100 on a multicore platform, +it is usually less than 100 because Emacs is typically single-threaded. @item pmem The percentage of the total physical memory installed on the machine @@ -3159,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. +@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 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. +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 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 +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 @@ -3425,20 +3489,64 @@ type values: @itemx byte Unsigned byte, with length 1. -@item uint @var{bitlen} -Unsigned integer in network byte order, with @var{bitlen} bits. +@item uint @var{bitlen} &optional @var{le} +Unsigned integer in network byte order (big-endian), with @var{bitlen} bits. @var{bitlen} has to be a multiple of 8. +If @var{le} is non-@code{nil}, then use little-endian byte order. -@item uintr @var{bitlen} -Unsigned integer in little endian order, with @var{bitlen} bits. +@item sint @var{bitlen} @var{le} +Signed integer in network byte order (big-endian), with @var{bitlen} bits. @var{bitlen} has to be a multiple of 8. +If @var{le} is non-@code{nil}, then use little-endian byte order. @item str @var{len} -String of bytes of length @var{len}. +Unibyte string (@pxref{Text Representations}) of length @var{len} bytes. +When packing, the first @var{len} bytes of the input string are copied +to the packed output. If the input string is shorter than @var{len}, +the remaining bytes will be null (zero) unless a pre-allocated string +was provided to @code{bindat-pack}, in which case the remaining bytes +are left unmodified. If the input string is multibyte with only ASCII +and @code{eight-bit} characters, it is converted to unibyte before it +is packed; other multibyte strings signal an error. When unpacking, +any null bytes in the packed input string will appear in the unpacked +output. @item strz &optional @var{len} -Zero-terminated string of bytes, can be of arbitrary length or in a fixed-size -field with length @var{len}. +If @var{len} is not provided, this is a variable-length +null-terminated unibyte string (@pxref{Text Representations}). When +packing into @code{strz}, the entire input string is copied to the +packed output followed by a null (zero) byte. (If pre-allocated +string is provided for packing into @code{strz}, that pre-allocated +string should have enough space for the additional null byte appended +to the output string contents, @pxref{Bindat Functions}). The length +of the packed output is the length of the input string plus one (for +the null terminator). The input string must not contain any null +bytes. If the input string is multibyte with only ASCII and +@code{eight-bit} characters, it is converted to unibyte before it is +packed; other multibyte strings signal an error. When unpacking a +@code{strz}, the resulting output string will contain all bytes up to +(but excluding) the null byte that terminated the input string. + +If @var{len} is provided, @code{strz} behaves the same as @code{str}, +but with a couple of differences: + +@itemize @bullet +@item +When packing, a null terminator is written after the packed input +string if the number of characters in the input string is less than +@var{len}. + +@item +When unpacking, the first null byte encountered in the packed string +is interpreted as the terminating byte, and it and all subsequent +bytes are excluded from the result of the unpacking. +@end itemize + +@quotation Caution +The packed output will not be null-terminated unless the input string +is shorter than @var{len} bytes or it contains a null byte within the +first @var{len} bytes. +@end quotation @item vec @var{len} [@var{type}] Vector of @var{len} elements. The type of the elements is given by @@ -3458,7 +3566,7 @@ and @code{#x1c} @code{#x28} to @w{@code{(3 5 10 11 12)}}. @item fill @var{len} @var{len} bytes used as a mere filler. In packing, these bytes are -are left unchanged, which normally means they remain zero. +left unchanged, which normally means they remain zero. When unpacking, this just returns nil. @item align @var{len} diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index fe4de0abbb2..5ee139a11d3 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -549,12 +549,12 @@ can act. It is poor practice to depend on this behavior; quote the special character anyway, regardless of where it appears. As a @samp{\} is not special inside a character alternative, it can -never remove the special meaning of @samp{-} or @samp{]}. So you -should not quote these characters when they have no special meaning -either. This would not clarify anything, since backslashes can -legitimately precede these characters where they @emph{have} special -meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax), -which matches any single character except a backslash. +never remove the special meaning of @samp{-}, @samp{^} or @samp{]}. +You should not quote these characters when they have no special +meaning. This would not clarify anything, since backslashes +can legitimately precede these characters where they @emph{have} +special meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string +syntax), which matches any single character except a backslash. In practice, most @samp{]} that occur in regular expressions close a character alternative and hence are special. However, occasionally a @@ -823,21 +823,22 @@ the characters that stand for them. matches any character whose syntax is not @var{code}. @cindex category, regexp search for -@item \c@var{c} -matches any character whose category is @var{c}. Here @var{c} is a -character that represents a category: thus, @samp{c} for Chinese -characters or @samp{g} for Greek characters in the standard category -table. You can see the list of all the currently defined categories -with @kbd{M-x describe-categories @key{RET}}. You can also define -your own categories in addition to the standard ones using the -@code{define-category} function (@pxref{Categories}). - -@item \C@var{c} -matches any character whose category is not @var{c}. +@item \c@var{code} +matches any character whose category is @var{code}. Here @var{code} +is a character that represents a category: for example, in the standard +category table, @samp{c} stands for Chinese characters and @samp{g} +stands for Greek characters. You can see the list of all the +currently defined categories with @w{@kbd{M-x describe-categories +@key{RET}}}. You can also define your own categories in addition to +the standard ones using the @code{define-category} function +(@pxref{Categories}). + +@item \C@var{code} +matches any character whose category is not @var{code}. @end table The following regular expression constructs match the empty string---that is, -they don't use up any characters---but whether they match depends on the +they don't consume any characters---but whether they match depends on the context. For all, the beginning and end of the accessible portion of the buffer are treated as if they were the actual beginning and end of the buffer. @@ -2045,7 +2046,7 @@ feature for matching regular expressions from end to beginning. It's not worth the trouble of implementing that. @end deffn -@defun string-match regexp string &optional start +@defun string-match regexp string &optional start inhibit-modify This function returns the index of the start of the first match for the regular expression @var{regexp} in @var{string}, or @code{nil} if there is no match. If @var{start} is non-@code{nil}, the search starts @@ -2070,8 +2071,10 @@ For example, The index of the first character of the string is 0, the index of the second character is 1, and so on. -If this function finds a match, the index of the first character beyond -the match is available as @code{(match-end 0)}. @xref{Match Data}. +By default, if this function finds a match, the index of the first +character beyond the match is available as @code{(match-end 0)}. +@xref{Match Data}. If @var{inhibit-modify} is non-@code{nil}, the +match data isn't modified. @example @group @@ -2092,16 +2095,18 @@ This predicate function does what @code{string-match} does, but it avoids modifying the match data. @end defun -@defun looking-at regexp +@defun looking-at regexp &optional inhibit-modify This function determines whether the text in the current buffer directly following point matches the regular expression @var{regexp}. ``Directly following'' means precisely that: the search is ``anchored'' and it can succeed only starting with the first character following point. The result is @code{t} if so, @code{nil} otherwise. -This function does not move point, but it does update the match data. -@xref{Match Data}. If you need to test for a match without modifying -the match data, use @code{looking-at-p}, described below. +This function does not move point, but it does update the match data +(if @var{inhibit-modify} is @code{nil} or missing, which is the +default). @xref{Match Data}. As a convenience, instead of using the +@var{inhibit-modify} argument, you can use @code{looking-at-p}, +described below. In this example, point is located directly before the @samp{T}. If it were anywhere else, the result would be @code{nil}. @@ -2208,13 +2213,13 @@ backtracking specified by the POSIX standard for regular expression matching. @end deffn -@defun posix-looking-at regexp +@defun posix-looking-at regexp &optional inhibit-modify This is like @code{looking-at} except that it performs the full backtracking specified by the POSIX standard for regular expression matching. @end defun -@defun posix-string-match regexp string &optional start +@defun posix-string-match regexp string &optional start inhibit-modify This is like @code{string-match} except that it performs the full backtracking specified by the POSIX standard for regular expression matching. @@ -2850,7 +2855,7 @@ Display some help, then ask again. @defvar multi-query-replace-map This variable holds a keymap that extends @code{query-replace-map} by -providing additional keybindings that are useful in multi-buffer +providing additional key bindings that are useful in multi-buffer replacements. The additional bindings are: @table @code diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index c3f4cff3015..1f6f80521c0 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -446,8 +446,7 @@ useful example of @code{sort}. @cindex seq library @cindex sequences, generalized The @file{seq.el} library provides the following additional sequence -manipulation macros and functions, prefixed with @code{seq-}. To use -them, you must first load the @file{seq} library. +manipulation macros and functions, prefixed with @code{seq-}. All functions defined in this library are free of side-effects; i.e., they do not modify any sequence (list, vector, or string) that @@ -577,6 +576,20 @@ starting from the first one for which @var{predicate} returns @code{nil}. @end example @end defun +@defun seq-split sequence length + This function returns a list consisting of sub-sequences of +@var{sequence} of (at most) length @var{length}. (The final element +may be shorter than @var{length} if the length of @var{sequence} isn't +a multiple of @var{length}. + +@example +@group +(seq-split [0 1 2 3 4] 2) +@result{} ([0 1] [2 3] [4]) +@end group +@end example +@end defun + @defun seq-do function sequence This function applies @var{function} to each element of @var{sequence} in turn (presumably for side effects), and returns diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi index c6b3397ae11..bba1dc2eee9 100644 --- a/doc/lispref/streams.texi +++ b/doc/lispref/streams.texi @@ -21,6 +21,7 @@ reading) or where to put it (if printing). * Output Streams:: Various data types that can be used as output streams. * Output Functions:: Functions to print Lisp objects as text. * Output Variables:: Variables that control what the printing functions do. +* Output Overrides:: Overriding output variables. @end menu @node Streams Intro @@ -327,6 +328,15 @@ For example: @end example @end defun +@defun read-positioning-symbols &optional stream +This function reads one textual expression from @var{stream}, like +@code{read} does, but additionally positions the read symbols to the +positions in @var{stream} where they occurred. Only the symbol +@code{nil} is not positioned, this for efficiency reasons. +@xref{Symbols with Position}. This function is used by the byte +compiler. +@end defun + @defvar standard-input This variable holds the default input stream---the stream that @code{read} uses when the @var{stream} argument is @code{nil}. @@ -358,6 +368,15 @@ mode for @var{stream}. On POSIX hosts, it always returns a non-@code{nil} value and does nothing except flushing pending output. @end defun +@defun readablep object +@cindex readable syntax +This predicate says whether @var{object} has @dfn{readable syntax}, +i.e., it can be written out and then read back by the Emacs Lisp +reader. If it can't, this function returns @code{nil}; if it can, +this function returns a printed representation (via @code{prin1}, +@pxref{Output Functions}) of @var{object}. +@end defun + @node Output Streams @section Output Streams @cindex stream (for printing) @@ -616,7 +635,7 @@ characters are used. @code{print} returns @var{object}. For example: @end example @end defun -@defun prin1 object &optional stream +@defun prin1 object &optional stream overrides This function outputs the printed representation of @var{object} to @var{stream}. It does not print newlines to separate output as @code{print} does, but it does use quoting characters just like @@ -631,6 +650,10 @@ This function outputs the printed representation of @var{object} to @result{} " came back" @end group @end example + +If @var{overrides} is non-@code{nil}, it should either be @code{t} +(which tells @code{prin1} to use the defaults for all printer related +variables), or a list of settings. @xref{Output Overrides}, for details. @end defun @defun princ object &optional stream @@ -667,7 +690,16 @@ This function outputs @var{character} to @var{stream}. It returns @var{character}. @end defun -@defun prin1-to-string object &optional noescape +@defun flush-standard-output +If you have Emacs-based batch scripts that send output to the +terminal, Emacs will automatically display the output whenever you +write a newline characters to @code{standard-output}. This function +allows you to flush to @code{standard-output} without sending a +newline character first, which enables you to display incomplete +lines. +@end defun + +@defun prin1-to-string object &optional noescape overrides @cindex object to string This function returns a string containing the text that @code{prin1} would have printed for the same argument. @@ -681,6 +713,10 @@ would have printed for the same argument. (prin1-to-string (mark-marker)) @result{} "#<marker at 2773 in strings.texi>" @end group + +If @var{overrides} is non-@code{nil}, it should either be @code{t} +(which tells @code{prin1} to use the defaults for all printer related +variables), or a list of settings. @xref{Output Overrides}, for details. @end example If @var{noescape} is non-@code{nil}, that inhibits use of quoting @@ -872,6 +908,32 @@ If non-@code{nil}, this variable enables detection of circular and shared structure in printing. @xref{Circular Objects}. @end defvar +@defvar print-unreadable-function +By default, Emacs prints unreadable objects as @samp{#<...>"}. For +instance: + +@example +(prin1-to-string (make-marker)) + @result{} "#<marker in no buffer>" +@end example + +If this variable is non-@code{nil}, it should be a function that will +be called to handle printing of these objects. The function will be +called with two arguments: the object and the @var{noescape} flag used by +the printing functions (@pxref{Output Functions}). + +The function should return either @code{nil} (print the object as +usual), or a string (which will be printed), or any other object +(don't print the object). For instance: + +@example +(let ((print-unreadable-function + (lambda (object escape) "hello"))) + (prin1-to-string (make-marker))) + @result{} "hello" +@end example +@end defvar + @defvar print-gensym If non-@code{nil}, this variable enables detection of uninterned symbols (@pxref{Creating Symbols}) in printing. When this is enabled, @@ -918,3 +980,84 @@ Letter, Number, Punctuation, Symbol and Private-use (@pxref{Character Properties}), as well as the control characters having their own escape syntax such as newline. @end defvar + +@node Output Overrides +@section Overriding Output Variables +@cindex overrides, in output functions +@cindex output variables, overriding + +The previous section (@pxref{Output Functions}) lists the numerous +variables that control how the Emacs Lisp printer formats data for +outputs. These are generally available for users to change, but +sometimes you want to output data in the default format, or override +the user settings in some other way. For instance, if you're storing +Emacs Lisp data in a file, you don't want that data to be shortened by +a @code{print-length} setting. + +The @code{prin1} and @code{prin1-to-string} functions therefore have +an optional @var{overrides} argument. This argument can either be +@code{t} (which means that all printing variables should be reset to +the default values), or a list of settings for some of the variables. +Each element in the list can be either @code{t} (which means ``reset +to defaults'', and will usually be the first element of the list), or +a pair whose @code{car} is a symbol that stands for an output variable +and whose @code{cdr} is the value for that variable. + +For instance, this prints using nothing but defaults: + +@lisp +(prin1 object nil t) +@end lisp + +This prints @var{object} using the current printing settings, but +overrides the value of @code{print-length} to be 5: + +@lisp +(prin1 object nil '((length . 5))) +@end lisp + +And finally, this prints @var{object} using only default settings, but +with @code{print-length} bound to 5: + +@lisp +(prin1 object nil '(t (length . 5))) +@end lisp + +Below is a list of symbols that can be used, and which variables they +map to: + +@table @code +@item length +This overrides @code{print-length}. +@item level +This overrides @code{print-level}. +@item circle +This overrides @code{print-circle}. +@item quoted +This overrides @code{print-quoted}. +@item escape-newlines +This overrides @code{print-escape-newlines}. +@item escape-control-characters +This overrides @code{print-escape-control-characters}. +@item escape-nonascii +This overrides @code{print-escape-nonascii}. +@item escape-multibyte +This overrides @code{print-escape-multibyte}. +@item charset-text-property +This overrides @code{print-charset-text-property}. +@item unreadeable-function +This overrides @code{print-unreadable-function}. +@item gensym +This overrides @code{print-gensym}. +@item continuous-numbering +This overrides @code{print-continuous-numbering}. +@item number-table +This overrides @code{print-number-table}. +@item float-format +This overrides @code{float-output-format}. +@item integers-as-characters +This overrides @code{print-integers-as-characters}. +@end table + +In the future, more overrides may be offered that do not map directly +to a variable, but can only be used via this parameter. diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 89120575f52..374381e5955 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -430,13 +430,16 @@ middle of a character representation. This function measures the string length in characters or bytes, and thus is generally inappropriate if you need to shorten strings for display purposes; use @code{truncate-string-to-width} or -@code{window-text-pixel-size} instead (@pxref{Size of Displayed -Text}). +@code{window-text-pixel-size} or @code{string-glyph-split} instead +(@pxref{Size of Displayed Text}). @end defun -@defun string-lines string &optional omit-nulls +@defun string-lines string &optional omit-nulls keep-newlines Split @var{string} into a list of strings on newline boundaries. If -@var{omit-nulls}, remove empty lines from the results. +the optional argument @var{omit-nulls} is non-@code{nil}, remove empty +lines from the results. If the optional argument @var{keep-newlines} +is non-@code{nil}, don't remove the trailing newlines from the result +strings. @end defun @defun string-pad string length &optional padding start @@ -557,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 diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index a951e9be8ae..336fa9c9182 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -23,15 +23,15 @@ otherwise. @end defun @menu -* Symbol Components:: Symbols have names, values, function definitions +* Symbol Components:: Symbols have names, values, function definitions and property lists. -* Definitions:: A definition says how a symbol will be used. -* Creating Symbols:: How symbols are kept unique. -* Symbol Properties:: Each symbol has a property list +* Definitions:: A definition says how a symbol will be used. +* Creating Symbols:: How symbols are kept unique. +* Symbol Properties:: Each symbol has a property list for recording miscellaneous information. -* Shorthands:: Properly organize your symbol names but +* Shorthands:: Properly organize your symbol names but type less of them. - +* Symbols with Position:: Symbol variants containing integer positions @end menu @node Symbol Components @@ -432,8 +432,8 @@ symbol's property list cell (@pxref{Symbol Components}), in the form of a property list (@pxref{Property Lists}). @menu -* Symbol Plists:: Accessing symbol properties. -* Standard Properties:: Standard meanings of symbol properties. +* Symbol Plists:: Accessing symbol properties. +* Standard Properties:: Standard meanings of symbol properties. @end menu @node Symbol Plists @@ -751,3 +751,70 @@ those names. @item Symbol forms whose names start with @samp{#_} are not transformed. @end itemize + +@node Symbols with Position +@section Symbols with Position +@cindex symbol with position + +@cindex bare symbol +A @dfn{symbol with position} is a symbol, the @dfn{bare symbol}, +together with an unsigned integer called the @dfn{position}. These +objects are intended for use by the byte compiler, which records in +them the position of each symbol occurrence and uses those positions +in warning and error messages. + +The printed representation of a symbol with position uses the hash +notation outlined in @ref{Printed Representation}. It looks like +@samp{#<symbol foo at 12345>}. It has no read syntax. You can cause +just the bare symbol to be printed by binding the variable +@code{print-symbols-bare} to non-@code{nil} around the print +operation. The byte compiler does this before writing its output to +the compiled Lisp file. + +For most purposes, when the flag variable +@code{symbols-with-pos-enabled} is non-@code{nil}, symbols with +positions behave just as bare symbols do. For example, @samp{(eq +#<symbol foo at 12345> foo)} has a value @code{t} when that variable +is set (but @code{nil} when it isn't set). Most of the time in Emacs this +variable is @code{nil}, but the byte compiler binds it to @code{t} +when it runs. + +Typically, symbols with position are created by the byte compiler +calling the reader function @code{read-positioning-symbols} +(@pxref{Input Functions}). One can also be created with the function +@code{position-symbol}. + +@defvar symbols-with-pos-enabled +When this variable is non-@code{nil}, symbols with position behave +like the contained bare symbol. Emacs runs a little more slowly in +this case. +@end defvar + +@defvar print-symbols-bare +When bound to non-nil, the Lisp printer prints only the bare symbol of +a symbol with position, ignoring the position. +@end defvar + +@defun symbol-with-pos-p symbol. +This function returns @code{t} if @var{symbol} is a symbol with +position, @code{nil} otherwise. +@end defun + +@defun bare-symbol symbol +This function returns the bare symbol contained in @var{symbol}, or +@var{symbol} itself if it is already a bare symbol. For any other +type of object, it signals an error. +@end defun + +@defun symbol-with-pos-pos symbol +This function returns the position, a number, from a symbol with +position. For any other type of object, it signals an error. +@end defun + +@defun position-symbol sym pos +Make a new symbol with position. @var{sym} is either a bare symbol or +a symbol with position, and supplies the symbol part of the new +object. @var{pos} is either an integer which becomes the number part +of the new object, or a symbol with position whose position is used. +Emacs signals an error if either argument is invalid. +@end defun diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 72fb674aa5a..8b859042ad0 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -59,7 +59,9 @@ the character after point. * Decompression:: Dealing with compressed data. * Base 64:: Conversion to or from base 64 encoding. * Checksum/Hash:: Computing cryptographic hashes. +* Suspicious Text:: Determining whether a string is suspicious. * GnuTLS Cryptography:: Cryptographic algorithms imported from GnuTLS. +* Database:: Interacting with an SQL database. * Parsing HTML/XML:: Parsing HTML and XML. * Parsing JSON:: Parsing and generating JSON values. * JSONRPC:: JSON Remote Procedure Call protocol @@ -241,10 +243,8 @@ using a function specified by the variable The default filter function consults the obsolete wrapper hook @code{filter-buffer-substring-functions} (see the documentation string of the macro @code{with-wrapper-hook} for the details about this -obsolete facility), and the obsolete variable -@code{buffer-substring-filters}. If both of these are @code{nil}, it -returns the unaltered text from the buffer, i.e., what -@code{buffer-substring} would return. +obsolete facility). If it is @code{nil}, it returns the unaltered +text from the buffer, i.e., what @code{buffer-substring} would return. If @var{delete} is non-@code{nil}, the function deletes the text between @var{start} and @var{end} after copying it, like @@ -280,22 +280,12 @@ the same as those of @code{filter-buffer-substring}. The first hook function is passed a @var{fun} that is equivalent to the default operation of @code{filter-buffer-substring}, i.e., it -returns the buffer-substring between @var{start} and @var{end} -(processed by any @code{buffer-substring-filters}) and optionally -deletes the original text from the buffer. In most cases, the hook -function will call @var{fun} once, and then do its own processing of -the result. The next hook function receives a @var{fun} equivalent to -this, and so on. The actual return value is the result of all the -hook functions acting in sequence. -@end defvar - -@defvar buffer-substring-filters -The value of this obsolete variable should be a list of functions -that accept a single string argument and return another string. -The default @code{filter-buffer-substring} function passes the buffer -substring to the first function in this list, and the return value of -each function is passed to the next function. The return value of the -last function is passed to @code{filter-buffer-substring-functions}. +returns the buffer-substring between @var{start} and @var{end} and +optionally deletes the original text from the buffer. In most cases, +the hook function will call @var{fun} once, and then do its own +processing of the result. The next hook function receives a @var{fun} +equivalent to this, and so on. The actual return value is the result +of all the hook functions acting in sequence. @end defvar @defun current-word &optional strict really-word @@ -599,6 +589,19 @@ This command indents to the left margin if that is not zero. The value returned is @code{nil}. @end deffn +@deffn Command ensure-empty-lines &optional number-of-empty-lines +This command can be used to ensure that you have a specific number of +empty lines before point. (An ``empty line'' is here defined as a +line with no characters on it---a line with space characters isn't an +empty line.) It defaults to ensuring that there's a single empty line +before point. + +If point isn't at the beginning of a line, a newline character is +inserted first. If there's more empty lines before point than +specified, the number of empty lines is reduced. Otherwise it's +increased to the specified number. +@end deffn + @defvar overwrite-mode This variable controls whether overwrite mode is in effect. The value should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary}, @@ -1019,6 +1022,9 @@ text in @var{string} according to the @code{yank-handler} text property, as well as the variables @code{yank-handled-properties} and @code{yank-excluded-properties} (see below), before inserting the result into the current buffer. + +@var{string} will be run through @code{yank-transform-functions} (see +below) before inserting. @end defun @defun insert-buffer-substring-as-yank buf &optional start end @@ -1093,6 +1099,23 @@ or specifying key bindings. It takes effect after @code{yank-handled-properties}. @end defopt +@defvar yank-transform-functions +This variable is a list of functions. Each function is called (in +order) with the string to be yanked as the argument, and should +return a (possibly transformed) string. This variable can be set +globally, but can also be used to create new commands that are +variations on @code{yank}. For instance, to create a command that +works like @code{yank}, but cleans up whitespace before inserting, you +could say something like: + +@lisp +(defun yank-with-clean-whitespace () + (interactive) + (let ((yank-transform-functions + '(string-clean-whitespace))) + (call-interactively #'yank))) +@end lisp +@end defvar @node Yank Commands @subsection Functions for Yanking @@ -1329,7 +1352,7 @@ that @kbd{C-y} should yank. @defopt kill-ring-max The value of this variable is the maximum length to which the kill ring can grow, before elements are thrown away at the end. The default -value for @code{kill-ring-max} is 60. +value for @code{kill-ring-max} is 120. @end defopt @node Undo @@ -1493,6 +1516,11 @@ continuing to undo. This function does not bind @code{undo-in-progress}. @end defun +@defmac with-undo-amalgamate body@dots{} +This macro removes all the undo boundaries inserted during the +execution of @var{body} so that it can be undone as a single step. +@end defmac + Some commands leave the region active after execution in such a way that it interferes with selective undo of that command. To make @code{undo} ignore the active region when invoked immediately after such a command, @@ -1633,6 +1661,47 @@ The variable @code{paragraph-separate} controls how to distinguish paragraphs. @xref{Standard Regexps}. @end deffn +@defun pixel-fill-region start end pixel-width +Most Emacs buffers use monospaced text, so all the filling functions +(like @code{fill-region}) work based on the number of characters and +@code{char-width}. However, Emacs can render other types of things, +like text that contains images and using proportional fonts, and the +@code{pixel-fill-region} exists to handle that. It fills the region +of text between @var{start} and @var{end} at pixel granularity, so +text using variable-pitch fonts or several different fonts looks +filled regardless of different character sizes. The argument +@var{pixel-width} specifies the maximum pixel width a line is allowed +to have after filling; it is the pixel-resolution equivalent of the +@code{fill-column} in @code{fill-region}. For instance, this Lisp +snippet will insert text using a proportional font, and then fill this +to be no wider than 300 pixels: + +@lisp +(insert (propertize + "This is a sentence that's ends here." + 'face 'variable-pitch)) +(pixel-fill-region (point) (point-max) 300) +@end lisp + +If @var{start} isn't at the start of a line, the horizontal position +of @var{start}, converted to pixel units, will be used as the +indentation prefix on subsequent lines. + +@findex pixel-fill-width +The @code{pixel-fill-width} helper function can be used to compute the +pixel width to use. If given no arguments, it'll return a value +slightly less than the width of the current window. The first +optional value, @var{columns}, specifies the number of columns using +the standard, monospaced fonts, e.g. @code{fill-column}. The second +optional value is the window to use. You'd typically use it like +this: + +@lisp +(pixel-fill-region + start end (pixel-fill-width fill-column)) +@end lisp +@end defun + @deffn Command fill-individual-paragraphs start end &optional justify citation-regexp This command fills each paragraph in the region according to its individual fill prefix. Thus, if the lines of a paragraph were indented @@ -2915,6 +2984,12 @@ character after position @var{pos} in @var{object} (a buffer or string). The argument @var{object} is optional and defaults to the current buffer. +If @var{position} is at the end of @var{object}, the value is +@code{nil}, but note that buffer narrowing does not affect the value. +That is, if @var{object} is a buffer or @code{nil}, and the buffer is +narrowed and @var{position} is at the end of the narrowed buffer, the +result may be non-@code{nil}. + If there is no @var{prop} property strictly speaking, but the character has a property category that is a symbol, then @code{get-text-property} returns the @var{prop} property of that symbol. @@ -2967,6 +3042,12 @@ properties take precedence over this variable. This function returns the entire property list of the character at @var{position} in the string or buffer @var{object}. If @var{object} is @code{nil}, it defaults to the current buffer. + +If @var{position} is at the end of @var{object}, the value is +@code{nil}, but note that buffer narrowing does not affect the value. +That is, if @var{object} is a buffer or @code{nil}, and the buffer is +narrowed and @var{position} is at the end of the narrowed buffer, the +result may be non-@code{nil}. @end defun @defvar default-text-properties @@ -3399,7 +3480,7 @@ This will give you a list of all those URLs. @end defun @defun text-property-search-backward prop &optional value predicate not-current -This is just like @code{text-property-search-backward}, but searches +This is just like @code{text-property-search-forward}, but searches backward instead. Point is placed at the beginning of the matched region instead of the end, though. @end defun @@ -3487,16 +3568,30 @@ special modes that implement their own highlighting. @item mouse-face @kindex mouse-face @r{(text property)} -This property is used instead of @code{face} when the mouse is on or -near the character. For this purpose, ``near'' means that all text -between the character and where the mouse is have the same -@code{mouse-face} property value. +This property is used instead of @code{face} when the mouse pointer +hovers over the text which has this property. When this happens, the +entire stretch of text that has the same @code{mouse-face} property +value, not just the character under the mouse, is highlighted. Emacs ignores all face attributes from the @code{mouse-face} property that alter the text size (e.g., @code{:height}, @code{:weight}, and @code{:slant}). Those attributes are always the same as for the unhighlighted text. +@item cursor-face +@kindex cursor-face @r{(text property)} +@findex cursor-face-highlight-mode +@vindex cursor-face-highlight-nonselected-window +This property is similar to @code{mouse-face}, but it is used when +point (not the mouse) is inside text that has this property. The +highlighting happens only if the mode +@code{cursor-face-highlight-mode} is enabled. When the variable +@code{cursor-face-highlight-nonselected-window} is non-@code{nil}, the +text with this face is highlighted even if the window is not selected, +similarly to what @code{highlight-nonselected-windows} does for the +region (@pxref{Mark,, The Mark and the Region, emacs, The GNU Emacs +Manual}). + @item fontified @kindex fontified @r{(text property)} This property says whether the text is ready for display. If @@ -3610,6 +3705,11 @@ edited even in read-only buffers. @xref{Read Only Buffers}. A non-@code{nil} @code{invisible} property can make a character invisible on the screen. @xref{Invisible Text}, for details. +@kindex inhibit-isearch @r{(text property)} +@item inhibit-isearch +A non-@code{nil} @code{inhibit-isearch} property will make isearch +skip the text. + @item intangible @kindex intangible @r{(text property)} If a group of consecutive characters have equal and non-@code{nil} @@ -3635,9 +3735,20 @@ property is obsolete; use the @code{cursor-intangible} property instead. @item cursor-intangible @kindex cursor-intangible @r{(text property)} @findex cursor-intangible-mode +@cindex rear-nonsticky, and cursor-intangible property When the minor mode @code{cursor-intangible-mode} is turned on, point is moved away from any position that has a non-@code{nil} @code{cursor-intangible} property, just before redisplay happens. +Note that ``stickiness'' of the property (@pxref{Sticky Properties}) +is taken into account when computing allowed cursor positions, so (for +instance) to insert a stretch of five @samp{x} characters into which +the cursor can't enter, you should do something like: + +@lisp +(insert + (propertize "xxxx" 'cursor-intangible t) + (propertize "x" 'cursor-intangible t 'rear-nonsticky t)) +@end lisp @vindex cursor-sensor-inhibit When the variable @code{cursor-sensor-inhibit} is non-@code{nil}, the @@ -3944,6 +4055,8 @@ of the kill ring. To insert with inheritance, use the special primitives described in this section. Self-inserting characters inherit properties because they work using these primitives. +@cindex front-sticky text property +@cindex rear-nonsticky text property When you do insertion with inheritance, @emph{which} properties are inherited, and from where, depends on which properties are @dfn{sticky}. Insertion after a character inherits those of its properties that are @@ -4176,7 +4289,7 @@ position. The action code is always @code{t}. For example, here is how Info mode handles @key{mouse-1}: @smallexample -(define-key Info-mode-map [follow-link] 'mouse-face) +(keymap-set Info-mode-map "<follow-link>" 'mouse-face) @end smallexample @item a function @@ -4189,9 +4302,9 @@ For example, here is how pcvs enables @kbd{mouse-1} to follow links on file names only: @smallexample -(define-key map [follow-link] - (lambda (pos) - (eq (get-char-property pos 'face) 'cvs-filename-face))) +(keymap-set map "<follow-link>" + (lambda (pos) + (eq (get-char-property pos 'face) 'cvs-filename-face))) @end smallexample @item anything else @@ -4723,9 +4836,8 @@ converting to and from this code. This function converts the region from @var{beg} to @var{end} into base 64 code. It returns the length of the encoded text. An error is signaled if a character in the region is multibyte, i.e., in a -multibyte buffer the region must contain only characters from the -charsets @code{ascii}, @code{eight-bit-control} and -@code{eight-bit-graphic}. +multibyte buffer the region must contain only ASCII characters or raw +bytes. Normally, this function inserts newline characters into the encoded text, to avoid overlong lines. However, if the optional argument @@ -4874,6 +4986,92 @@ It should be somewhat more efficient on larger buffers than @c according to what we find useful. @end defun +@node Suspicious Text +@section Suspicious Text +@cindex suspicious text +@cindex insecure text +@cindex security vulnerabilities in text + + Emacs can display text from many external sources, like email and Web +sites. Attackers may attempt to confuse the user reading this text by +using obfuscated @acronym{URL}s or email addresses, and tricking the +user into visiting a web page they didn't intend to visit, or sending +an email to the wrong address. + +This usually involves using characters from scripts that visually look +like @acronym{ASCII} characters (i.e., are homoglyphs), but there are +also other techniques used, like using bidirectional overrides, or +having an @acronym{HTML} link text that says one thing, while the +underlying @acronym{URL} points somewhere else. + +@cindex suspicious text strings +To help identify these @dfn{suspicious text strings}, Emacs provides a +library to do a number of checks on text. (See +@url{https://www.unicode.org/reports/tr39/, UTS #39: Unicode Security +Mechanisms} for the rationale behind the checks that are available and +more details about them.) Packages that present data that might be +suspicious should use this library to flag suspicious text on display. + +@vindex textsec-check +@defun textsec-suspicious-p object type +This function is the high-level interface function that packages +should use. It respects the @code{textsec-check} user option, which +allows the user to disable the checks. + +This function checks @var{object} (whose data type depends on +@var{type}) to see if it looks suspicious when interpreted as a thing +of @var{type}. The available types and the corresponding @var{object} +data types are: + +@table @code +@item domain +Check whether a domain (e.g., @samp{www.gnu.org} looks suspicious. +@var{object} should be a string, the domain name. + +@item url +Check whether an @acronym{URL} (e.g., @samp{http://gnu.org/foo/bar}) +looks suspicious. @var{object} should be a string, the @acronym{URL} +to check. + +@item link +Check whether an @acronym{HTML} link (e.g., @samp{<a +href='http://gnu.org'>fsf.org</a>} looks suspicious. In this case, +@var{object} should be a @code{cons} cell where the @code{car} is the +@acronym{URL} string, and the @code{cdr} is the link text. The link +is deemed suspicious if the link text contains a domain name, and that +domain name points to something other than the @acronym{URL}. + +@item email-address +Check whether an email address (e.g., @samp{foo@@example.org}) looks +suspicious. @var{object} should be a string. + +@item local-address +Check whether the local part of an email address (the bit before the +@samp{@@} sign) looks suspicious. @var{object} should be a string. + +@item name +Check whether a name (used in an email address header) looks +suspicious. @var{object} should be a string. + +@item email-address-header +Check whether a full RFC2822 email address header (e.g., +@samp{=?utf-8?Q?=C3=81?= <foo@@example.com>}) looks suspicious. +@var{object} should be a string. +@end table + +If @var{object} is suspicious, this function returns a string that +explains why it is suspicious. If @var{object} is not suspicious, the +function returns @code{nil}. +@end defun + +@vindex textsec-suspicious@r{ (face)} +If the text is suspicious, the application should mark the suspicious +text with the @code{textsec-suspicious} face, and make the explanation +returned by @code{textsec-suspicious-p} available to the user in some way +(for example, in a tooltip). The application might also prompt the +user for confirmation before taking any action on a suspicious string +(like sending an email to a suspicious email address). + @node GnuTLS Cryptography @section GnuTLS Cryptography @cindex MD5 checksum @@ -5066,6 +5264,201 @@ On success, it returns a list of a binary string (the output) and the IV used. @end defun +@node Database +@section Database +@cindex database access, SQLite + + Emacs can be compiled with built-in support for accessing SQLite +databases. This section describes the facilities available for +accessing SQLite databases from Lisp programs. + +@defun sqlite-available-p +The function returns non-@code{nil} if built-in SQLite support is +available in this Emacs session. +@end defun + +When SQLite support is available, the following functions can be used. + +@cindex database object +@defun sqlite-open &optional file +This function opens @var{file} as an SQLite database file. If +@var{file} doesn't exist, a new database will be created and stored in +that file. If @var{file} is omitted or @code{nil}, a new in-memory +database is created instead. + +The return value is a @dfn{database object} that can be used as the +argument to most of the subsequent functions described below. +@end defun + +@defun sqlitep object +This predicate returns non-@code{nil} if @var{object} is an SQLite +database object. The database object returned by the +@code{sqlite-open} function satisfies this predicate. +@end defun + +@defun sqlite-close db +Close the database @var{db}. It's usually not necessary to call this +function explicitly---the database will automatically be closed if +Emacs shuts down or the database object is garbage collected. +@end defun + +@defun sqlite-execute db statement &optional values +Execute the @acronym{SQL} @var{statement}. For instance: + +@lisp +(sqlite-execute db "insert into foo values ('bar', 2)") +@end lisp + +If the optional @var{values} parameter is present, it should be either +a list or a vector of values to bind while executing the statement. +For instance: + +@lisp +(sqlite-execute db "insert into foo values (?, ?)" '("bar" 2)) +@end lisp + +This has exactly the same effect as the previous example, but is more +efficient and safer (because it doesn't involve any string parsing or +interpolation). + +@code{sqlite-execute} returns the number of affected rows. For +instance, an @samp{insert} statement will return @samp{1}, whereas an +@samp{update} statement may return zero or a higher number. + +Strings in SQLite are, by default, stored as @code{utf-8}, and +selecting a text column will decode the string using that charset. +Selecting a blob column will return the raw data without any decoding +(i.e., it will return a unibyte string containing the bytes as stored +in the database). Inserting binary data into blob columns, however, +requires some care, as @code{sqlite-execute} will, by default, +interpret all strings as @code{utf-8}. + +So if you have, for instance, @acronym{GIF} data in a unibyte string +called @var{gif}, you have to mark it specially to let +@code{sqlite-execute} know this: + +@lisp +(put-text-property 0 1 'coding-system 'binary gif) +(sqlite-execute db "insert into foo values (?, ?)" (list gif 2)) +@end lisp + +@end defun + +@defun sqlite-select db query &optional values result-type +Select some data from @var{db} and return them. For instance: + +@lisp +(sqlite-select db "select * from foo where key = 2") + @result{} (("bar" 2)) +@end lisp + +As with the @code{sqlite-execute}, you can optionally pass in a list +or a vector of values that will be bound before executing the select: + +@lisp +(sqlite-select db "select * from foo where key = ?" [2]) + @result{} (("bar" 2)) +@end lisp + +This is usually more efficient and safer than the method used by the +previous example. + +By default, this function returns a list of matching rows, where each +row is a list of column values. If @var{return-type} is @code{full}, +the names of the columns (as a list of strings) will be returned as +the first element in the return value. + +@cindex statement object +If @var{return-type} is @code{set}, this function will return a +@dfn{statement object} instead. This object can be examined by using +the @code{sqlite-next}, @code{sqlite-columns} and @code{sqlite-more-p} +functions. If the result set is small, it's often more convenient to +just return the data directly, but if the result set is large (or if +you won't be using all the data from the set), using the @code{set} +method will allocate a lot less memory, and is therefore more +memory-efficient. +@end defun + +@defun sqlite-next statement +This function returns the next row in the result set @var{statement}, +typically an object returned by @code{sqlite-select}. + +@lisp +(sqlite-next stmt) + @result{} ("bar" 2) +@end lisp +@end defun + +@defun sqlite-columns statement +This function returns the column names of the result set +@var{statement}, typically an object returned by @code{sqlite-select}. + +@lisp +(sqlite-columns stmt) + @result{} ("name" "issue") +@end lisp +@end defun + +@defun sqlite-more-p statement +This predicate says whether there is more data to be fetched from the +result set @var{statement}, typically an object returned by +@code{sqlite-select}. +@end defun + +@defun sqlite-finalize statement +If @var{statement} is not going to be used any more, calling this +function will free the resources used by @var{statement}. This is +usually not necessary---when the @var{statement} object is +garbage-collected, Emacs will automatically free its resources. +@end defun + +@defun sqlite-transaction db +Start a transaction in @var{db}. When in a transaction, other readers +of the database won't access the results until the transaction has +been committed by @code{sqlite-commit}. +@end defun + +@defun sqlite-commit db +End a transaction in @var{db} and write the data out to its file. +@end defun + +@defun sqlite-rollback db +End a transaction in @var{db} and discard any changes that have been +made by the transaction. +@end defun + +@defmac with-sqlite-transaction db body@dots{} +Like @code{progn} (@pxref{Sequencing}), but executes @var{body} with a +transaction held, and commits the transaction at the end. +@end defmac + +@defun sqlite-pragma db pragma +Execute @var{pragma} in @var{db}. A @dfn{pragma} is usually a command +that affects the database overall, instead of any particular table. +For instance, to make SQLite automatically garbage collect data that's +no longer needed, you can say: + +@lisp +(sqlite-pragma db "auto_vacuum = FULL") +@end lisp + +This function returns non-@code{nil} on success and @code{nil} if the +pragma failed. Many pragmas can only be issued when the database is +brand new and empty. +@end defun + +@defun sqlite-load-extension db module +Load the named extension @var{module} into the database @var{db}. +Extensions are usually shared-library files; on GNU and Unix systems, +they have the @file{.so} file-name extension. +@end defun + +@findex sqlite-mode-open-file +If you wish to list the contents of an SQLite file, you can use the +@code{sqlite-mode-open-file} command. This will pop to a buffer using +@code{sqlite-mode}, which allows you to examine (and alter) the +contents of an SQLite database. + @node Parsing HTML/XML @section Parsing HTML and XML @cindex parsing html @@ -5080,12 +5473,15 @@ available in this Emacs session. When libxml2 support is available, the following functions can be used to parse HTML or XML text into Lisp object trees. -@defun libxml-parse-html-region start end &optional base-url discard-comments +@defun libxml-parse-html-region &optional start end base-url discard-comments This function parses the text between @var{start} and @var{end} as HTML, and returns a list representing the HTML @dfn{parse tree}. It attempts to handle real-world HTML by robustly coping with syntax mistakes. +If @var{start} or @var{end} are @code{nil}, they default to the values +from @code{point-min} and @code{point-max}, respectively. + The optional argument @var{base-url}, if non-@code{nil}, should be a string specifying the base URL for relative URLs occurring in links. @@ -5131,7 +5527,7 @@ buffer. The argument @var{dom} should be a list as generated by @end defun @cindex parsing xml -@defun libxml-parse-xml-region start end &optional base-url discard-comments +@defun libxml-parse-xml-region &optional start end base-url discard-comments This function is the same as @code{libxml-parse-html-region}, except that it parses the text as XML rather than HTML (so it is stricter about syntax). diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index eddbbfe8b90..3a1f6de12b2 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -252,6 +252,13 @@ themselves; Lisp programmers find this disconcerting. Please put a copyright notice and copying permission notice on the file if you distribute copies. @xref{Library Headers}. +@item +For variables holding (or functions returning) a file or directory name, +avoid using @code{path} in its name, preferring @code{file}, +@code{file-name}, or @code{directory} instead, since Emacs follows the +GNU convention to use the term @emph{path} only for search paths, +which are lists of directory names. + @end itemize @node Key Binding Conventions @@ -682,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 +719,11 @@ Note that when Emacs displays these doc strings, Emacs will usually display @samp{`} (grave accent) as @samp{‘} (left single quotation mark) and @samp{'} (apostrophe) as @samp{’} (right single quotation mark), if the display supports displaying these characters. -@xref{Keys in Documentation}. +@xref{Keys in Documentation}. (Some previous versions of this section +recommended using the non-@acronym{ASCII} single quotation marks +directly in doc strings, but this is now discouraged, since that leads +to broken help string displays on terminals that don't support +displaying those characters.) @cindex hyperlinks in documentation strings Help mode automatically creates a hyperlink when a documentation string diff --git a/doc/lispref/two-volume.make b/doc/lispref/two-volume.make index aaad040dc08..f401d4a1f2a 100644 --- a/doc/lispref/two-volume.make +++ b/doc/lispref/two-volume.make @@ -35,7 +35,7 @@ vol1.pdf: elisp1med-fns-ready elisp1med-aux-ready elisp1med-toc-ready $(tex1) # vol2.pdf: elisp2med-fns-ready elisp2med-aux-ready elisp2med-toc-ready - @echo "Final TeX run for volume 2..." + $(info Final TeX run for volume 2...) cp elisp2med-toc-ready elisp2-toc-ready.toc cp elisp2med-fns-ready vol2.fns cp elisp2med-aux-ready vol2.aux @@ -123,7 +123,7 @@ elisp1med-init: elisp1-fns-ready elisp1-aux-ready elisp1init-toc-ready $(texinfo mv vol1.toc elisp1med-toc # elisp2med-init: elisp2-fns-ready elisp2-aux-ready elisp2init-toc-ready $(texinfodir)/texinfo.tex - @echo "Final TeX run for volume 2..." + $(info Final TeX run for volume 2...) cp elisp2init-toc-ready elisp2-toc-ready.toc cp elisp2-fns-ready vol2.fns cp elisp2-aux-ready vol2.aux @@ -211,7 +211,7 @@ elisp1-init: elisp.texi touch $@ # elisp2-init: elisp.texi - @echo "Initial TeX run for volume 2..." + $(info Initial TeX run for volume 2...) rm -f vol2.aux vol2.toc $(tex2) texindex vol2.?? diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index b9f50ecc6ac..80d6a01412b 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -44,6 +44,7 @@ representing the variable. * Variables with Restricted Values:: Non-constant variables whose value can @emph{not} be an arbitrary Lisp object. * Generalized Variables:: Extending the concept of variables. +* Multisession Variables:: Variables that survive restarting Emacs. @end menu @node Global Variables @@ -363,7 +364,7 @@ where you are in Emacs. @cindex evaluation error @cindex infinite recursion This variable defines the limit on the total number of local variable -bindings and @code{unwind-protect} cleanups (see @ref{Cleanups,, +bindings and @code{unwind-protect} cleanups (@pxref{Cleanups,, Cleaning Up from Nonlocal Exits}) that are allowed before Emacs signals an error (with data @code{"Variable binding depth exceeds max-specpdl-size"}). @@ -526,10 +527,11 @@ If @var{symbol} has a buffer-local binding in the current buffer, rather than the buffer-local binding. It sets the default value if the default value is void. @xref{Buffer-Local Variables}. -If @var{symbol} is already lexically bound (e.g., if the @code{defvar} -form occurs in a @code{let} form with lexical binding enabled), then -@code{defvar} sets the dynamic value. The lexical binding remains in -effect until its binding construct exits. @xref{Variable Scoping}. +If @var{symbol} is already let bound (e.g., if the @code{defvar} +form occurs in a @code{let} form), then @code{defvar} sets the toplevel +default value, like @code{set-default-toplevel-value}. +The let binding remains in effect until its binding construct exits. +@xref{Variable Scoping}. @cindex @code{eval-defun}, and @code{defvar} forms @cindex @code{eval-last-sexp}, and @code{defvar} forms @@ -686,7 +688,7 @@ entire computation of the value into the @code{defvar}, like this: @example (defvar my-mode-map (let ((map (make-sparse-keymap))) - (define-key map "\C-c\C-a" 'my-command) + (keymap-set map "C-c C-a" 'my-command) @dots{} map) @var{docstring}) @@ -702,25 +704,6 @@ important if the user has run hooks to alter part of the contents (such as, to rebind keys). Third, evaluating the @code{defvar} form with @kbd{C-M-x} will reinitialize the map completely. - Putting so much code in the @code{defvar} form has one disadvantage: -it puts the documentation string far away from the line which names the -variable. Here's a safe way to avoid that: - -@example -(defvar my-mode-map nil - @var{docstring}) -(unless my-mode-map - (let ((map (make-sparse-keymap))) - (define-key map "\C-c\C-a" 'my-command) - @dots{} - (setq my-mode-map map))) -@end example - -@noindent -This has all the same advantages as putting the initialization inside -the @code{defvar}, except that you must type @kbd{C-M-x} twice, once on -each form, if you do want to reinitialize the variable. - @node Accessing Variables @section Accessing Variable Values @@ -879,6 +862,40 @@ error is signaled. @end example @end defun +@defmac setopt [symbol form]@dots{} +This is like @code{setq} (see above), but meant for user options. +This macro uses the Customize machinery to set the variable(s). In +particular, @code{setopt} will run the setter function associated with +the variable. For instance, if you have: + +@example +@group +(defcustom my-var 1 + "My var." + :type 'number + :set (lambda (var val) + (set-default var val) + (message "We set %s to %s" var val))) +@end group +@end example + +@noindent +then the following, in addition to setting @code{my-var} to @samp{2}, +will also issue a message: + +@example +(setopt my-var 2) +@end example + +@code{setopt} also checks whether the value is valid for the user +option. For instance, using @code{setopt} to set a user option +defined with a @code{number} type to a string will signal an error. + +The @code{setopt} macro can be used on regular, non-user option +variables, but is much less efficient than @code{setq}. The main use +case for this macro is setting user options in the user's init file. +@end defmac + @node Watching Variables @section Running a function when a variable is changed. @cindex variable watchpoints @@ -1695,12 +1712,14 @@ buffer-local variables interactively. @end deffn @cindex local variables, killed by major mode -@defun kill-all-local-variables +@defun kill-all-local-variables &optional kill-permanent This function eliminates all the buffer-local variable bindings of the -current buffer except for variables marked as permanent and local -hook functions that have a non-@code{nil} @code{permanent-local-hook} -property (@pxref{Setting Hooks}). As a result, the buffer will see -the default values of most variables. +current buffer. As a result, the buffer will see the default values +of most variables. By default, for variables marked as permanent and +local hook functions that have a non-@code{nil} +@code{permanent-local-hook} property (@pxref{Setting Hooks}) won't be +killed, but if the optional @var{kill-permanent} argument is +non-@code{nil}, even these variables will be killed. This function also resets certain other information pertaining to the buffer: it sets the local keymap to @code{nil}, the syntax table to the @@ -2277,13 +2296,28 @@ list in @var{variables} is an alist of the form '((null-device . "/dev/null"))) @end group @end example + +@findex connection-local-get-profile-variables +If you want to append variable settings to an existing profile, you +could use the function @code{connection-local-get-profile-variables} +in order to retrieve the existing settings, like + +@example +@group +(connection-local-set-profile-variables + 'remote-bash + (append + (connection-local-get-profile-variables 'remote-bash) + '((shell-command-dont-erase-buffer . t)))) +@end group +@end example @end defun -@defvar connection-local-profile-alist +@deffn {User Option} connection-local-profile-alist This alist holds the connection profile symbols and the associated variable settings. It is updated by @code{connection-local-set-profile-variables}. -@end defvar +@end deffn @defun connection-local-set-profiles criteria &rest profiles This function assigns @var{profiles}, which are symbols, to all remote @@ -2337,11 +2371,11 @@ Therefore, the example above would be equivalent to defined by @code{connection-local-set-profile-variables}. @end defun -@defvar connection-local-criteria-alist +@deffn {User Option} connection-local-criteria-alist This alist contains connection criteria and their assigned profile names. The function @code{connection-local-set-profiles} updates this list. -@end defvar +@end deffn @defun hack-connection-local-variables criteria This function collects applicable connection-local variables @@ -2400,6 +2434,37 @@ are unwound. Example: @end example @end defmac +@defvar connection-local-default-application +The default application, a symbol, to be applied in +@code{with-connection-local-variables}. It defaults to @code{tramp}, +but in case you want to overwrite Tramp's settings temporarily, you +could let-bind it like + +@example +@group +(connection-local-set-profile-variables + 'my-remote-perl + '((perl-command-name . "/usr/local/bin/perl5") + (perl-command-switch . "-e %s"))) +@end group + +@group +(connection-local-set-profiles + '(:application 'my-app :protocol "ssh" :machine "remotehost") + 'my-remote-perl) +@end group + +@group +(let ((default-directory "/ssh:remotehost:/working/dir/") + (connection-local-default-application 'my-app)) + (with-connection-local-variables + do something useful)) +@end group +@end example + +This variable must not be changed globally. +@end defvar + @defvar enable-connection-local-variables If @code{nil}, connection-local variables are ignored. This variable shall be changed temporarily only in special modes. @@ -2614,17 +2679,46 @@ cdar nthcdr A call to any of the following Emacs-specific functions: @smallexample -alist-get process-get -frame-parameter process-sentinel -terminal-parameter window-buffer -keymap-parent window-display-table -match-data window-dedicated-p -overlay-get window-hscroll -overlay-start window-parameter -overlay-end window-point -process-buffer window-start -process-filter default-value +alist-get overlay-start +default-value overlay-get +face-background process-buffer +face-font process-filter +face-foreground process-get +face-stipple process-sentinel +face-underline-p terminal-parameter +file-modes window-buffer +frame-parameter window-dedicated-p +frame-parameters window-display-table +get-register window-hscroll +getenv window-parameter +keymap-parent window-point +match-data window-start +overlay-end @end smallexample + +@item +A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])}, +where @var{subplace} is itself a valid generalized variable whose +current value is a string, and where the value stored is also a +string. The new string is spliced into the specified part of the +destination string. For example: + +@example +(setq a (list "hello" "world")) + @result{} ("hello" "world") +(cadr a) + @result{} "world" +(substring (cadr a) 2 4) + @result{} "rl" +(setf (substring (cadr a) 2 4) "o") + @result{} "o" +(cadr a) + @result{} "wood" +a + @result{} ("hello" "wood") +@end example + +@c FIXME? Also 'eq'? (see gv.el) @end itemize @noindent @@ -2725,13 +2819,13 @@ implemented this way: (gv-define-expander substring (lambda (do place from &optional to) (gv-letplace (getter setter) place - (macroexp-let2* nil ((start from) (end to)) - (funcall do `(substring ,getter ,start ,end) + (macroexp-let2* (from to) + (funcall do `(substring ,getter ,from ,to) (lambda (v) - (macroexp-let2 nil v v + (macroexp-let2* (v) `(progn ,(funcall setter `(cl--set-substring - ,getter ,start ,end ,v)) + ,getter ,from ,to ,v)) ,v)))))))) @end example @end defmac @@ -2744,7 +2838,7 @@ of Common Lisp could be implemented this way: @example (defmacro incf (place &optional n) (gv-letplace (getter setter) place - (macroexp-let2 nil v (or n 1) + (macroexp-let2* ((v (or n 1))) (funcall setter `(+ ,v ,getter))))) @end example @@ -2757,6 +2851,16 @@ expression manipulating @var{place} via @var{getter} and @var{setter}. Consult the source file @file{gv.el} for more details. +@defun make-obsolete-generalized-variable obsolete-name current-name when +This function makes the byte compiler warn that the generalized +variable @var{obsolete-name} is obsolete. If @var{current-name} is a +symbol, then the warning message says to use @var{current-name} +instead of @var{obsolete-name}. If @var{current-name} is a string, +this is the message. @var{when} should be a string indicating when +the variable was first made obsolete (usually a version number +string). +@end defun + @cindex CL note---no @code{setf} functions @quotation @b{Common Lisp note:} Common Lisp defines another way to specify the @@ -2769,3 +2873,157 @@ form that has not already had an appropriate expansion defined. In Common Lisp, this is not an error since the function @code{(setf @var{func})} might be defined later. @end quotation + +@node Multisession Variables +@section Multisession Variables + +@cindex multisession variable + When you set a variable to a value and then close Emacs and restart +it, that value won't be automatically restored. Users usually set +normal variables in their startup files, or use Customize +(@pxref{Customization}) to set user options permanently, and various +packages have various files where they store the data (e.g., Gnus +stores this in @file{.newsrc.eld} and the URL library stores cookies +in @file{~/.emacs.d/url/cookies}). + +For things in between these two extremes (i.e., configuration which +goes in the startup file, and massive application state that goes into +separate files), Emacs provides a facility to replicate data between +sessions called @dfn{multisession variables}. (This facility may not +be available on all systems.) To give you an idea of how these are +meant to be used, here's a small example: + +@lisp +@group +(define-multisession-variable foo-var 0) +(defun my-adder (num) + (interactive "nAdd number: ") + (setf (multisession-value foo) + (+ (multisession-value foo) num)) + (message "The new number is: %s" (multisession-value foo))) +@end group +@end lisp + +@noindent +This defines the variable @code{foo-var} and binds it to a special +multisession object which is initialized with the value @samp{0} (if +the variable doesn't already exist from a previous session). The +@code{my-adder} command queries the user for a number, adds this to +the old (possibly saved value), and then saves the new value. + +This facility isn't meant to be used for huge data structures, but +should be performant for most values. + +@defmac define-multisession-variable name initial-value &optional doc &rest args +This macro defines @var{name} as a multisession variable, and gives it +the @var{initial-value} if this variable hasn't been assigned a value +earlier. @var{doc} is the doc string, and several keyword arguments can +be used in @var{args}: + +@table @code +@item :package @var{package-symbol} +This keyword says that a multisession variable belongs to the package +specified by @var{package-symbol}. The combination of +@var{package-symbol} and @var{name} has to be unique. If +@var{package-symbol} isn't given, this will default to the first +``segment'' of the @var{name} symbol's name, which is the part of its +name up to and excluding the first @samp{-}. For instance, if +@var{name} is @code{foo-var} and @var{package-symbol} isn't given, +@var{package-symbol} will default to @code{foo}. + +@cindex synchronized multisession variables +@item :synchronized @var{bool} +Multisession variables can be @dfn{synchronized} if @var{bool} is +non-@code{nil}. This means that if there're two concurrent Emacs +instances running, and the other Emacs changes the multisession +variable @code{foo-var}, the current Emacs instance will retrieve that +modified data when accessing the value. If @var{synchronized} is +@code{nil} or missing, this won't happen, and the values in all +Emacs sessions using the variable will be independent of each other. + +@item :storage @var{storage} +Use the specified @var{storage} method. This can be either +@code{sqlite} (in Emacs compiled with SQLite support) or @code{files}. +If not given, this defaults to the value of the +@code{multisession-storage} variable, described below. +@end table +@end defmac + +@defun multisession-value variable +This function returns the current value of @var{variable}. If this +variable hasn't been accessed before in this Emacs session, or if it's +changed externally, it will be read in from external storage. If not, +the current value in this session is returned as is. It is an error +to call this function for a @var{variable} that is not a multisession +variable. + +Values retrieved via @code{multisession-value} may or may not be +@code{eq} to each other, but they will always be @code{equal}. + +This is a generalized variable (@pxref{Generalized Variables}), so the +way to update such a variable is to say, for instance: + +@lisp +(setf (multisession-value foo-bar) 'zot) +@end lisp + +Only Emacs Lisp values that have a readable print syntax +(@pxref{Printed Representation}) can be saved this way. + +If the multisession variable is synchronized, setting it may update +the value first. For instance: + +@lisp +(cl-incf (multisession-value foo-bar)) +@end lisp + +This first checks whether the value has changed in a different +Emacs instance, retrieves that value, and then adds 1 to that value and +stores it. But note that this is done without locking, so if many +instances are updating the value at the same time, it's unpredictable +which instance ``wins''. +@end defun + +@defun multisession-delete object +This function deletes @var{object} and its value from its persistent +storage. +@end defun + +@c FIXME: this lacks the documentation of the form of the arguments. +@defun make-multisession +You can also make persistent values that aren't tied to a specific +variable, but are tied to an explicit package and key. + +@example +(setq foo (make-multisession :package "mail" + :key "friends")) +(setf (multisession-value foo) 'everybody) +@end example + +This supports the same keywords as +@code{define-multisession-variable}, but also supports a +@code{:initial-value} keyword, which specifies the default value. +@end defun + +@defopt multisession-storage +This variable controls how the multisession variables are stored. It +value defaults to @code{files}, which means that the values are stored +in a one-file-per-variable structure inside the directory specified by +@code{multisession-directory}. If this value is @code{sqlite} +instead, the values are stored in an SQLite database; this is only +available if Emacs was built with SQLite support. +@end defopt + +@defopt multisession-directory +The multisession variables are stored under this directory, which +defaults to @file{multisession/} subdirectory of the +@code{user-emacs-directory}, which is typically +@file{~/.emacs.d/multisession/}. +@end defopt + +@findex multisession-edit-mode +@deffn Command list-multisession-values +This command pops up a buffer listing all the multisession variables, +and enters a special mode @code{multisession-edit-mode} which allows +you to delete them and edit their values. +@end deffn diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 597e31fe85e..c7f014e2f3b 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -829,14 +829,18 @@ This function returns the height, in lines, of the body of window @var{window}. If @var{window} is omitted or @code{nil}, it defaults to the selected window; otherwise it must be a live window. -If the optional argument @var{pixelwise} is non-@code{nil}, this -function returns the body height of @var{window} counted in pixels. +The optional argument @var{pixelwise} defines the units to use for the +height. If @code{nil}, return the body height of @var{window} in +characters, rounded down to the nearest integer, if necessary. This +means that if a line at the bottom of the text area is only partially +visible, that line is not counted. It also means that the height of a +window's body can never exceed its total height as returned by +@code{window-total-height}. -If @var{pixelwise} is @code{nil}, the return value is rounded down to -the nearest integer, if necessary. This means that if a line at the -bottom of the text area is only partially visible, that line is not -counted. It also means that the height of a window's body can never -exceed its total height as returned by @code{window-total-height}. +If @var{pixelwise} is @code{remap} and the default face is remapped +(@pxref{Face Remapping}), use the remapped face to determine the +character height. For any other non-@code{nil} value, return the +height in pixels. @end defun @cindex window body width @@ -857,14 +861,18 @@ This function returns the width, in columns, of the body of window @var{window}. If @var{window} is omitted or @code{nil}, it defaults to the selected window; otherwise it must be a live window. -If the optional argument @var{pixelwise} is non-@code{nil}, this -function returns the body width of @var{window} in units of pixels. +The optional argument @var{pixelwise} defines the units to use for the +width. If @code{nil}, return the body width of @var{window} in +characters, rounded down to the nearest integer, if necessary. This +means that if a column on the right of the text area is only partially +visible, that column is not counted. It also means that the width of +a window's body can never exceed its total width as returned by +@code{window-total-width}. -If @var{pixelwise} is @code{nil}, the return value is rounded down to -the nearest integer, if necessary. This means that if a column on the -right of the text area is only partially visible, that column is not -counted. It also means that the width of a window's body can never -exceed its total width as returned by @code{window-total-width}. +If @var{pixelwise} is @code{remap} and the default face is remapped +(@pxref{Face Remapping}), use the remapped face to determine the +character width. For any other non-@code{nil} value, return the width +in pixels. @end defun @cindex window body size @@ -1150,11 +1158,13 @@ frame to its buffer using the command @code{fit-frame-to-buffer}. This command adjusts the size of @var{frame} to display the contents of its buffer exactly. @var{frame} can be any live frame and defaults to the selected one. Fitting is done only if @var{frame}'s root window is -live. The arguments @var{max-height}, @var{min-height}, @var{max-width} -and @var{min-width} specify bounds on the new total size of -@var{frame}'s root window. @var{min-height} and @var{min-width} default -to the values of @code{window-min-height} and @code{window-min-width} -respectively. +live. + +The arguments @var{max-height}, @var{min-height}, @var{max-width} and +@var{min-width}, if non-@code{nil}, specify bounds on the new body size +of @var{frame}'s root window. A non-@code{nil} value specified by any +of these arguments overrides the corresponding value specified by +the option @code{fit-frame-to-buffer-sizes} described below. If the optional argument @var{only} is @code{vertically}, this function may resize the frame vertically only. If @var{only} is @@ -1179,10 +1189,10 @@ here can be overridden for a specific frame by that frame's @defopt fit-frame-to-buffer-sizes This option specifies size boundaries for @code{fit-frame-to-buffer}. -It specifies the total maximum and minimum lines and maximum and minimum -columns of the root window of any frame that shall be fit to its buffer. -If any of these values is non-@code{nil}, it overrides the corresponding -argument of @code{fit-frame-to-buffer}. +It specifies the maximum and minimum lines and maximum and minimum +columns of the root window's body of any frame that shall be fit to its +buffer. Any value this option specifies will be overridden by the +corresponding argument of @code{fit-frame-to-buffer}, if non-@code{nil}. @end defopt @deffn Command shrink-window-if-larger-than-buffer &optional window @@ -2596,13 +2606,11 @@ default value is an empty display action, i.e., @w{@code{(nil . nil)}}. @defopt display-buffer-alist The value of this option is an alist mapping conditions to display -actions. Each condition may be either a regular expression matching a -buffer name or a function that takes two arguments: a buffer name and -the @var{action} argument passed to @code{display-buffer}. If either -the name of the buffer passed to @code{display-buffer} matches a -regular expression in this alist, or the function specified by a -condition returns non-@code{nil}, then @code{display-buffer} uses the -corresponding display action to display the buffer. +actions. Each condition is passed to @code{buffer-match-p}, along +with the buffer name and the @var{action} argument passed to +@code{display-buffer}. If it returns a non-nil value, then +@code{display-buffer} uses the corresponding display action to display +the buffer. @end defopt @defopt display-buffer-base-action @@ -2838,6 +2846,11 @@ the function specified in @code{pop-up-frame-function} the newly created frame's parameters. @end defun +@defun display-buffer-full-frame buffer alist +This function displays the buffer on the current frame, deleting all +other windows so that it takes up the full frame. +@end defun + @defun display-buffer-in-child-frame buffer alist This function tries to display @var{buffer} in a child frame (@pxref{Child Frames}) of the selected frame, either reusing an @@ -2968,13 +2981,14 @@ follows: @code{nil} means consider only windows on the selected frame. (Actually, the last frame used that is not a minibuffer-only frame.) @item -@code{t} means consider windows on all frames. -@item @code{visible} means consider windows on all visible frames. @item 0 means consider windows on all visible or iconified frames. @item A frame means consider windows on that frame only. +@item +@code{t} means consider windows on all frames. (Note that this value +is rarely the right thing to use---it might also return a tooltip frame.) @end itemize Note that the meaning of @code{nil} differs slightly from that of the @@ -3038,6 +3052,11 @@ desired total height with respect to the total height of its frame's root window. @item +A cons cell whose @sc{car} is @code{body-lines} and whose @sc{cdr} is an +integer that specifies the height of the chosen window's body in frame +lines. + +@item If the value specifies a function, that function is called with one argument---the chosen window. The function is supposed to adjust the height of the window; its return value is ignored. Suitable functions @@ -3071,16 +3090,47 @@ desired total width with respect to the total width of the frame's root window. @item +A cons cell whose @sc{car} is @code{body-columns} and whose @sc{cdr} is +an integer that specifies the width of the chosen window's body in frame +columns. + +@item If the value specifies a function, that function is called with one argument---the chosen window. The function is supposed to adjust the width of the window; its return value is ignored. @end itemize -By convention, the width of the chosen window is adjusted only if the -window is part of a horizontal combination (@pxref{Windows and -Frames}) to avoid changing the width of other, unrelated windows. -Also, this entry should be processed under only certain conditions -which are specified right below this list. +@vindex window-size@r{, a buffer display action alist entry} +@item window-size +This entry is a combination of the two preceding ones and can be used to +adjust the chosen window's height @emph{and} width. Since windows can +be resized in one direction only without affecting other windows, +@code{window-size} is effective only to set up the size of a window +appearing alone on a frame. The value can be one of the following: + +@itemize @bullet +@item +@code{nil} means to leave the size of the chosen window alone. + +@item +A cons cell of two integers specifies the desired total width and height +of the chosen window in lines and columns. It's effect is to adjust the +size of the frame accordingly. + +@item +A cons cell whose @sc{car} equals @code{body-chars} and whose @sc{cdr} +is a cons cell of two integers---the desired body width and height of +the chosen window in frame columns and lines. It's effect is to adjust +the size of the frame accordingly. + +@item +If the value specifies a function, that function is called with one +argument---the chosen window. The function is supposed to adjust the +size of the window's frame; its return value is ignored. +@end itemize + +This entry should be processed under only certain conditions which are +specified right below this list. @vindex dedicated@r{, a buffer display action alist entry} @item dedicated @@ -3181,6 +3231,14 @@ the window was created earlier by @code{display-buffer} to show the buffer and never was used to show another buffer until it was reused by the current invocation of @code{display-buffer}. +If no @code{window-height}, @code{window-width} or @code{window-size} +entry was specified, the window may still be resized automatically when +the buffer is temporary and @code{temp-buffer-resize-mode} has been +enabled, @ref{Temporary Displays}. In that case, the @sc{cdr} of a +@code{window-height}, @code{window-width} or @code{window-size} entry +can be used to inhibit or override the default behavior of +@code{temp-buffer-resize-mode} for specific buffers or invocations of +@code{display-buffer}. @node Choosing Window Options @subsection Additional Options for Displaying Buffers @@ -3248,6 +3306,13 @@ window has at least that many columns. If the value is @code{nil}, that means not to split this way. @end defopt +@defopt display-buffer-avoid-small-windows +If non-@code{nil}, this should be a number. Windows that have fewer +lines than that will be avoided when choosing an existing window. The +value is interpreted in units of the frame's canonical line height, +like @code{window-total-height} does (@pxref{Window Sizes}). +@end defopt + @defopt even-window-sizes This variable, if non-@code{nil}, causes @code{display-buffer} to even window sizes whenever it reuses an existing window, and that window is @@ -3333,8 +3398,8 @@ functions it should try instead as, for example: @example @group -(customize-set-variable - 'display-buffer-base-action +(setopt + display-buffer-base-action '((display-buffer-reuse-window display-buffer-same-window display-buffer-in-previous-window display-buffer-use-some-window))) @@ -3348,8 +3413,8 @@ Instead of customizing this variable to @code{t}, customize @example @group -(customize-set-variable - 'display-buffer-base-action +(setopt + display-buffer-base-action '((display-buffer-reuse-window display-buffer-pop-up-frame) (reusable-frames . 0))) @end group @@ -3365,8 +3430,8 @@ specifying the action function @code{display-buffer-same-window}. @example @group -(customize-set-variable - 'display-buffer-alist +(setopt + display-buffer-alist (cons '("\\*foo\\*" (display-buffer-same-window)) display-buffer-alist)) @end group @@ -3439,8 +3504,8 @@ another frame. Such a user might provide the following customization: @example @group -(customize-set-variable - 'display-buffer-base-action +(setopt + display-buffer-base-action '((display-buffer-reuse-window display-buffer-pop-up-frame) (reusable-frames . 0))) @end group @@ -3485,8 +3550,8 @@ In fact, this: @example @group -(customize-set-variable - 'display-buffer-base-action +(setopt + display-buffer-base-action '(display-buffer-pop-up-frame (reusable-frames . 0))) @end group @end example @@ -3542,8 +3607,8 @@ by customizing the option @code{display-buffer-alist} as follows: @example @group -(customize-set-variable - 'display-buffer-alist +(setopt + display-buffer-alist '(("\\*foo\\*" (display-buffer-reuse-window display-buffer-pop-up-frame)))) @end group @@ -3565,8 +3630,8 @@ we would have to specify that separately, however: @example @group -(customize-set-variable - 'display-buffer-alist +(setopt + display-buffer-alist '(("\\*foo\\*" (display-buffer-reuse-window display-buffer-pop-up-frame) (reusable-frames . visible)))) @@ -3672,8 +3737,8 @@ written that as @example @group -(customize-set-variable - 'display-buffer-alist +(setopt + display-buffer-alist '(("\\*foo\\*" (display-buffer-reuse-window display-buffer-pop-up-frame) (inhibit-same-window . t) @@ -3816,8 +3881,8 @@ follows: @example @group -(customize-set-variable - 'display-buffer-alist +(setopt + display-buffer-alist '(("\\*foo\\*" (display-buffer-below-selected display-buffer-at-bottom) (inhibit-same-window . t) @@ -3830,8 +3895,8 @@ To add a customization for a second buffer one would then write: @example @group -(customize-set-variable - 'display-buffer-alist +(setopt + display-buffer-alist '(("\\*foo\\*" (display-buffer-below-selected display-buffer-at-bottom) (inhibit-same-window . t) @@ -4121,6 +4186,13 @@ ignore this option, for example, when there is only one buffer left these functions can switch to. @end defopt +@defopt switch-to-prev-buffer-skip-regexp +This user option should be either a regular expression or a list of +regular expressions. Buffers whose names match one of those regular +expressions will be ignored by @code{switch-to-prev-buffer} and +@code{switch-to-next-buffer} (except when there's no other buffer to +switch to). +@end defopt @node Dedicated Windows @section Dedicated Windows @@ -5456,7 +5528,7 @@ pixels, rather than in units of the normal line height. @end example @end defun -@defun set-window-vscroll window lines &optional pixels-p +@defun set-window-vscroll window lines &optional pixels-p preserve-vscroll-p This function sets @var{window}'s vertical scroll position to @var{lines}. If @var{window} is @code{nil}, the selected window is used. The argument @var{lines} should be zero or positive; if not, it @@ -5478,6 +5550,12 @@ The return value is the result of this rounding. If @var{pixels-p} is non-@code{nil}, @var{lines} specifies a number of pixels. In this case, the return value is @var{lines}. + +Normally, the vscroll does not take effect on windows that aren't the +@code{minibuffer-scroll-window} or the selected window when the +mini-window is resized (@pxref{Minibuffer Windows}). This ``frozen'' +behavior is disabled when the @var{preserve-vscroll-p} parameter is +non-@code{nil}, which means to set the vscroll as usual. @end defun @defvar auto-window-vscroll @@ -6071,11 +6149,10 @@ configuration on the current frame. This function returns @code{t} if @var{object} is a window configuration. @end defun -@defun compare-window-configurations config1 config2 -This function compares two window configurations as regards the -structure of windows, but ignores the values of point and the -saved scrolling positions---it can return @code{t} even if those -aspects differ. +@defun window-configuration-equal-p config1 config2 +This function says whether two window configurations have the same +window layout, but ignores the values of point and the saved scrolling +positions---it can return @code{t} even if those aspects differ. @end defun @defun window-configuration-frame config diff --git a/doc/man/emacs.1.in b/doc/man/emacs.1.in index 9fdf65e0ff7..7b2b5539795 100644 --- a/doc/man/emacs.1.in +++ b/doc/man/emacs.1.in @@ -1,5 +1,5 @@ .\" See section COPYING for copyright and redistribution information. -.TH EMACS 1 "2021-09-28" "GNU Emacs @version@" "GNU" +.TH EMACS 1 "2022-06-07" "GNU Emacs @version@" "GNU" . . .SH NAME @@ -117,6 +117,10 @@ Load .IR user 's init file. .TP +.BI \-\-init\-directory= "directory" +Start emacs with user-emacs-directory set to +.IR directory . +.TP .BI \-t " file\fR,\fP " \-\-terminal= "file" Use specified .I file diff --git a/doc/man/emacsclient.1 b/doc/man/emacsclient.1 index ba64efa282c..e5d1bbe09ae 100644 --- a/doc/man/emacsclient.1 +++ b/doc/man/emacsclient.1 @@ -1,5 +1,5 @@ .\" See section COPYING for conditions for redistribution. -.TH EMACSCLIENT 1 "2020-10-18" "GNU Emacs" "GNU" +.TH EMACSCLIENT 1 "2021-11-05" "GNU Emacs" "GNU" .\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection .\" other params are allowed: see man(7), man(1) .SH NAME @@ -69,6 +69,9 @@ start Emacs in daemon mode, and try to connect to it. .B -c, \-\-create-frame Create a new frame instead of trying to use the current Emacs frame. .TP +.B -r \-\-reuse-frame +Reuse an existing frame if one exists, otherwise create a new frame. +.TP .B \-F, \-\-frame-parameters=ALIST Set the parameters of a newly-created frame. .TP diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index 1e3398701fc..1d881a5fc7f 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -74,7 +74,7 @@ INFO_COMMON = auth autotype bovine calc ccmode cl \ mairix-el message mh-e modus-themes newsticker nxml-mode octave-mode \ org pcl-cvs pgg rcirc remember reftex sasl \ sc semantic ses sieve smtpmail speedbar srecode todo-mode transient \ - tramp url vhdl-mode vip viper widget wisent woman + tramp url vhdl-mode vip viper vtable widget wisent woman ## Info files to install on current platform. INFO_INSTALL = $(INFO_COMMON) $(DOCMISC_W32) @@ -130,12 +130,12 @@ info: $(INFO_TARGETS) ## Used by top-level Makefile. ## Base file names of output info files. +INFO_BASES = $(patsubst %.info,%,$(notdir $(INFO_INSTALL))) echo-info: - @echo "$(INFO_INSTALL) " | \ - sed -e 's|[^ ]*/||g' -e 's/\.info//g' -e "s/ */.info /g" + @: $(info $(addsuffix .info,$(INFO_BASES))) echo-sources: - @echo ${SOURCES} + @: $(info $(SOURCES)) dvi: $(DVI_TARGETS) @@ -185,7 +185,8 @@ $(foreach ifile,$(filter-out info.info,$(INFO_TARGETS)),$(eval $(call info_templ ## Extra dependencies. -need_emacsver = calc cl dired-x efaq efaq-w32 erc ido reftex woman +## FIXME Updating this list manually is unreliable. +need_emacsver = calc cl dired-x efaq efaq-w32 erc forms ido newsticker reftex remember woman need_emacsver_prefix = $(addprefix ${buildinfodir}/,${need_emacsver}) $(need_emacsver_prefix:=.info) $(need_emacsver:=.dvi) $(need_emacsver:=.pdf) $(need_emacsver:=.html) : ${emacsdir}/emacsver.texi @@ -233,6 +234,10 @@ ${buildinfodir}/tramp.info tramp.html: ${srcdir}/trampver.texi abs_top_builddir = @abs_top_builddir@ + +# Prevent any settings in the user environment causing problems. +unexport EMACSDATA EMACSDOC EMACSLOADPATH EMACSPATH + EMACS = ${abs_top_builddir}/src/emacs emacs = "${EMACS}" -batch --no-site-file --no-site-lisp --eval '(setq load-prefer-newer t)' @@ -243,6 +248,7 @@ emacs = "${EMACS}" -batch --no-site-file --no-site-lisp --eval '(setq load-prefe define org_template $(1:.org=.texi): $(1) ${top_srcdir}/lisp/org/ox-texinfo.el $${AM_V_GEN}cd "$${srcdir}" && $${emacs} -l ox-texinfo \ + --eval '(setq gc-cons-threshold 50000000)' \ -f org-texinfo-export-to-texinfo-batch $$(notdir $$<) $$(notdir $$@) endef diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi index e4254faabb9..9dc63af6bcc 100644 --- a/doc/misc/auth.texi +++ b/doc/misc/auth.texi @@ -191,7 +191,7 @@ get fancy, the default and simplest configuration is: (setq auth-sources '("secrets:Login")) ;;; use pass (@file{~/.password-store}) ;;; (@pxref{The Unix password store}) -(setq auth-sources '(password-store)) +(auth-source-pass-enable) ;;; JSON data in format [@{ "machine": "SERVER", ;;; "login": "USER", "password": "PASSWORD" @}...] (setq auth-sources '("~/.authinfo.json.gpg")) @@ -305,7 +305,8 @@ The @dfn{Secret Service API} is a standard from to securely store passwords and other confidential information. This API is implemented by system daemons such as the GNOME Keyring and the KDE Wallet (these are GNOME and KDE packages respectively and should -be available on most modern GNU/Linux systems). +be available on most modern GNU/Linux systems). It has been tested +also with KeePassXC. The auth-source library uses the @file{secrets.el} library to connect through the Secret Service API@. You can also use that library in @@ -360,15 +361,19 @@ Collections can be created and deleted by the functions Usually, this is not done from within Emacs. Do not delete standard collections such as @code{"login"}. -The special collection @code{"session"} exists for the lifetime of the -corresponding client session (in our case, Emacs's lifetime). It is -created automatically when Emacs uses the Secret Service interface and -it is deleted when Emacs is killed. Therefore, it can be used to -store and retrieve secret items temporarily. The @code{"session"} -collection is better than a persistent collection when the secret -items should not live longer than Emacs. The session collection can -be specified either by the string @code{"session"}, or by @code{nil}, -whenever a collection parameter is needed in the following functions. +With GNOME Keyring, there exists a special collection called +@code{"session"}, which has the lifetime of the user being logged in. +Its data are not stored on disk and go away when the user logs out. +Therefore, it can be used to store and retrieve secret items +temporarily. The @code{"session"} collection is better than a +persistent collection when the secret items should not live +permanently. The @code{"session"} collection can be addressed either +by the string @code{"session"}, or by @code{nil}, whenever a +collection parameter is needed. + +However, other Secret Service provider don't create this temporary +@code{"session"} collection. You shall check first that this +collection exists, before you use it. @defun secrets-list-items collection Returns all the item labels of @var{collection} as a list. @@ -379,10 +384,10 @@ This function creates a new item in @var{collection} with label @var{item} and password @var{password}. The label @var{item} does not have to be unique in @var{collection}. @var{attributes} are key-value pairs set for the created item. The keys are keyword symbols, -starting with a colon. Example: +starting with a colon; values are strings. Example: @example -;;; The session is "session", the label is "my item" +;;; The collection is "session", the label is "my item" ;;; and the secret (password) is "geheim". (secrets-create-item "session" "my item" "geheim" :method "sudo" :user "joe" :host "remote-host") @@ -461,6 +466,10 @@ then fall back to @file{~/.authinfo.gpg}. "~/.authinfo.gpg")) @end example +Attribute values in the auth-source spec, which are not strings (like +port numbers), are stringified prior calling the @file{secrets.el} +functions. + @node The Unix password store @chapter The Unix password store @@ -574,10 +583,7 @@ from Gnus's @code{nnimap.el}. :create t)))) (if found (list (plist-get found :user) - (let ((secret (plist-get found :secret))) - (if (functionp secret) - (funcall secret) - secret)) + (auth-info-password found) (plist-get found :save-function)) nil))) @end example @@ -597,7 +603,7 @@ Later, after a successful login, @code{nnimap.el} calls the @example (when (functionp (nth 2 credentials)) - (funcall (nth 2 credentials))) + (funcall (nth 2 credentials))) @end example This will work whether the @code{:save-function} was provided or not. @@ -632,6 +638,16 @@ This function forgets any cached data matching @var{spec}. It returns the number of items forgotten. @end defun +@defun auth-source-pick-first-password &rest spec +This function returns the password of the first record found by +applying @code{auth-source-search} to @var{spec}. +@end defun + +@defun auth-info-password auth-info +This function extracts the password string from the @var{auth-info} +record. +@end defun + @node GnuPG and EasyPG Assistant Configuration @appendix GnuPG and EasyPG Assistant Configuration @@ -640,14 +656,8 @@ before @file{~/.authinfo}, the auth-source library will try to read the GnuPG encrypted @file{.gpg} file first, before the unencrypted file. -In Emacs 23 or later there is an option @code{auto-encryption-mode} to -automatically decrypt @file{*.gpg} files. It is enabled by default. -If you are using earlier versions of Emacs, you will need: - -@lisp -(require 'epa-file) -(epa-file-enable) -@end lisp +There is an option @code{auto-encryption-mode} to automatically +decrypt @file{*.gpg} files. It is enabled by default. If you want your GnuPG passwords to be cached, set up @code{gpg-agent} or EasyPG Assistant 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/calc.texi b/doc/misc/calc.texi index 32d2dd6f24a..98f59b89c01 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -29877,6 +29877,12 @@ with no argument copies only the number itself into the kill ring, whereas @kbd{C-k} with a prefix argument of 1 copies the number with its trailing newline. +You can customize @code{calc-kill-line-numbering} to nil to exclude +line numbering from kills and copies made by @code{calc-kill} and +@code{calc-copy-as-kill}. This option does not affect calc kill and +copy commands which operate on the region, as that would not make +sense. + @node Yanking Into Stack @section Yanking into the Stack diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index 9da18cd9201..1f12c30b1f8 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -283,6 +283,7 @@ Font Locking * Font Locking Preliminaries:: * Faces:: * Doc Comments:: +* Wrong Comment Style:: * Misc Font Locking:: * AWK Mode Font Locking:: @@ -6277,6 +6278,32 @@ expressions for the operands. @comment ------------------------------------------------------------ +@defun c-lineup-argcont-+ +@findex lineup-argcont-+ (c-) +Indent a continued argument @code{c-basic-offset} spaces from the +start of the first argument at the current level of nesting on a +previous line. + +@example +@group +foo (xyz, uvw, aaa + bbb + ccc + + ddd + eee + fff); <- c-lineup-argcont-+ + <--> c-basic-offset +@end group +@end example + +Only continuation lines like this are touched, @code{nil} being +returned on lines which are the start of an argument. + +Within a gcc @code{asm} block, @code{:} is recognized as an argument +separator, but of course only between operand specifications, not in the +expressions for the operands. + +@workswith @code{arglist-cont}, @code{arglist-cont-nonempty}. +@end defun + +@comment ------------------------------------------------------------ + @defun c-lineup-arglist-operators @findex lineup-arglist-operators @r{(c-)} Line up lines starting with an infix operator under the open paren. diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 4eb3d85d2ba..a6747b1096a 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -444,7 +444,7 @@ the ``rest'' argument is bound to the keyword list as it appears in the call. For example: @example -(cl-defun find-thing (thing &rest rest &key need &allow-other-keys) +(cl-defun find-thing (thing thing-list &rest rest &key need &allow-other-keys) (or (apply 'cl-member thing thing-list :allow-other-keys t rest) (if need (error "Thing not found")))) @end example @@ -843,6 +843,7 @@ constructs. * Iteration:: @code{cl-do}, @code{cl-dotimes}, @code{cl-dolist}, @code{cl-do-symbols}. * Loop Facility:: The Common Lisp @code{loop} macro. * Multiple Values:: @code{cl-values}, @code{cl-multiple-value-bind}, etc. +* Macro-Writing Macros:: @code{cl-with-gensyms}, @code{cl-once-only}. @end menu @node Assignment @@ -919,69 +920,6 @@ cl-caaar@dots{}cl-cddddr cl-first@dots{}cl-tenth Note that for @code{cl-getf} (as for @code{nthcdr}), the list argument of the function must itself be a valid @var{place} form. -@item -General Emacs Lisp functions: -@example -buffer-file-name getenv -buffer-modified-p global-key-binding -buffer-name local-key-binding -buffer-string mark -buffer-substring mark-marker -current-buffer marker-position -current-case-table mouse-position -current-column point -current-global-map point-marker -current-input-mode point-max -current-local-map point-min -current-window-configuration read-mouse-position -default-file-modes screen-height -documentation-property screen-width -face-background selected-window -face-background-pixmap selected-screen -face-font selected-frame -face-foreground standard-case-table -face-underline-p syntax-table -file-modes visited-file-modtime -frame-height window-height -frame-parameters window-width -frame-visible-p x-get-secondary-selection -frame-width x-get-selection -get-register -@end example - -Most of these have directly corresponding ``set'' functions, like -@code{use-local-map} for @code{current-local-map}, or @code{goto-char} -for @code{point}. A few, like @code{point-min}, expand to longer -sequences of code when they are used with @code{setf} -(@code{(narrow-to-region x (point-max))} in this case). - -@item -A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])}, -where @var{subplace} is itself a valid generalized variable whose -current value is a string, and where the value stored is also a -string. The new string is spliced into the specified part of the -destination string. For example: - -@example -(setq a (list "hello" "world")) - @result{} ("hello" "world") -(cadr a) - @result{} "world" -(substring (cadr a) 2 4) - @result{} "rl" -(setf (substring (cadr a) 2 4) "o") - @result{} "o" -(cadr a) - @result{} "wood" -a - @result{} ("hello" "wood") -@end example - -The generalized variable @code{buffer-substring}, listed above, -also works in this way by replacing a portion of the current buffer. - -@c FIXME? Also 'eq'? (see cl-lib.el) - @c Currently commented out in cl.el. @ignore @item @@ -1245,6 +1183,12 @@ blocks for other macros like @code{cl-incf}, and @code{cl-pushnew}. The @code{cl-letf} and @code{cl-letf*} macros are used in the processing of symbol macros; @pxref{Macro Bindings}. +@defmac with-memoization @var{place} @var{code}@dots{} +This macro provides a simple way to do memoization. @var{code} is +evaluated and then stashed in @var{place}. If @var{place}'s value is +non-@code{nil}, return that value instead of evaluating @var{code}. +@end defmac + @node Variable Bindings @section Variable Bindings @@ -1374,19 +1318,10 @@ bar A @code{setq} of a symbol macro is treated the same as a @code{setf}. I.e., @code{(setq foo 4)} in the above would be equivalent to -@code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}. - -Likewise, a @code{let} or @code{let*} binding a symbol macro is -treated like a @code{cl-letf} or @code{cl-letf*}. This differs from true -Common Lisp, where the rules of lexical scoping cause a @code{let} -binding to shadow a @code{symbol-macrolet} binding. In this package, -such shadowing does not occur, even when @code{lexical-binding} is -@c See https://debbugs.gnu.org/12119 -@code{t}. (This behavior predates the addition of lexical binding to -Emacs Lisp, and may change in future to respect @code{lexical-binding}.) -At present in this package, only @code{lexical-let} and -@code{lexical-let*} will shadow a symbol macro. @xref{Obsolete -Lexical Binding}. +@code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) +4)}. A @code{let} (or @code{let*}, @code{lambda}, ...) binding of +the same symbol will locally shadow the symbol macro as is the case in +Common Lisp. There is no analogue of @code{defmacro} for symbol macros; all symbol macros are local. A typical use of @code{cl-symbol-macrolet} is in the @@ -2507,6 +2442,86 @@ in @code{cl-multiple-value-bind}. Since a perfect emulation is not feasible in Emacs Lisp, this package opts to keep it as simple and predictable as possible. +@node Macro-Writing Macros +@section Macro-Writing Macros + +@noindent +This package includes two classic Common Lisp macro-writing macros to +help render complex macrology easier to read. + +@defmac cl-with-gensyms names@dots{} body +This macro expands to code that executes @var{body} with each of the +variables in @var{names} bound to a fresh uninterned symbol, or +@dfn{gensym}, in Common Lisp parlance. For macros requiring more than +one gensym, use of @code{cl-with-gensyms} shortens the code and +renders one's intentions clearer. Compare: + +@example +(defmacro my-macro (foo) + (let ((bar (gensym "bar")) + (baz (gensym "baz")) + (quux (gensym "quux"))) + `(let ((,bar (+ @dots{}))) + @dots{}))) + +(defmacro my-macro (foo) + (cl-with-gensyms (bar baz quux) + `(let ((,bar (+ @dots{}))) + @dots{}))) +@end example +@end defmac + +@defmac cl-once-only ((variable form)@dots{}) body +This macro is primarily to help the macro programmer ensure that forms +supplied by the user of the macro are evaluated just once by its +expansion even though the result of evaluating the form is to occur +more than once. Less often, this macro is used to ensure that forms +supplied by the macro programmer are evaluated just once. + +Each @var{variable} may be used to refer to the result of evaluating +@var{form} in @var{body}. @code{cl-once-only} binds each +@var{variable} to a fresh uninterned symbol during the evaluation of +@var{body}. Then, @code{cl-once-only} wraps the final expansion in +code to evaluate each @var{form} and bind the result to the +corresponding uninterned symbol. Thus, when the macro writer +substitutes the value for @var{variable} into the expansion they are +effectively referring to the result of evaluating @var{form}, rather +than @var{form} itself. Another way to put this is that each +@var{variable} is bound to an expression for the (singular) result of +evaluating @var{form}. + +The most common case is where @var{variable} is one of the arguments +to the macro being written, so @code{(variable variable)} may be +abbreviated to just @code{variable}. + +For example, consider this macro: + +@example +(defmacro my-list (x y &rest forms) + (let ((x-result (gensym)) + (y-result (gensym))) + `(let ((,x-result ,x) + (,y-result ,y)) + (list ,x-result ,y-result ,x-result ,y-result + (progn ,@@forms)))) +@end example + +In a call like @w{@code{(my-list (pop foo) @dots{})}} the intermediate +binding to @code{x-result} ensures that the @code{pop} is not done +twice. But as a result the code is rather complex: the reader must +keep track of how @code{x-result} really just means the first +parameter of the call to the macro, and the required use of multiple +gensyms to avoid variable capture by @code{(progn ,@@forms)} obscures +things further. @code{cl-once-only} takes care of these details: + +@example +(defmacro my-list (x y &rest forms) + (cl-once-only (x y) + `(list ,x ,y ,x ,y + (progn ,@@forms)))) +@end example +@end defmac + @node Macros @chapter Macros @@ -2862,6 +2877,7 @@ out the property and value cells. @node Creating Symbols @section Creating Symbols +@cindex gensym @noindent These functions create unique symbols, typically for use as @@ -5014,13 +5030,13 @@ The above @code{incf} example could be written using @example (defmacro incf (place &optional n) (gv-letplace (getter setter) place - (macroexp-let2 nil v (or n 1) + (cl-once-only ((v (or n 1))) (funcall setter `(+ ,v ,getter))))) @end example @ignore (defmacro concatf (place &rest args) (gv-letplace (getter setter) place - (macroexp-let2 nil v (mapconcat 'identity args "") + (cl-once-only ((v `(mapconcat 'identity ',args))) (funcall setter `(concat ,getter ,v))))) @end ignore @end defmac diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi index 0b4f53ba136..bb97446d127 100644 --- a/doc/misc/dbus.texi +++ b/doc/misc/dbus.texi @@ -795,13 +795,7 @@ and interface. Example: (dbus-get-all-managed-objects :session "org.gnome.SettingsDaemon" "/") -@result{} (("/org/gnome/SettingsDaemon/MediaKeys" - ("org.gnome.SettingsDaemon.MediaKeys") - ("org.freedesktop.DBus.Peer") - ("org.freedesktop.DBus.Introspectable") - ("org.freedesktop.DBus.Properties") - ("org.freedesktop.DBus.ObjectManager")) - ("/org/gnome/SettingsDaemon/Power" +@result{} (("/org/gnome/SettingsDaemon/Power" ("org.gnome.SettingsDaemon.Power.Keyboard") ("org.gnome.SettingsDaemon.Power.Screen") ("org.gnome.SettingsDaemon.Power" diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi index 754ccf4065c..002164ed91f 100644 --- a/doc/misc/dired-x.texi +++ b/doc/misc/dired-x.texi @@ -92,7 +92,6 @@ For @file{dired-x.el} as distributed with GNU Emacs @value{EMACSVER}. * Introduction:: * Installation:: * Omitting Files in Dired:: -* Shell Command Guessing:: * Virtual Dired:: * Advanced Mark Commands:: * Multiple Dired Directories:: @@ -135,9 +134,6 @@ Some features provided by Dired Extra: Omitting uninteresting files from Dired listing (@pxref{Omitting Files in Dired}). @item -Guessing shell commands in Dired buffers -(@pxref{Shell Command Guessing}). -@item Running Dired command in non-Dired buffers (@pxref{Virtual Dired}). @item @@ -165,10 +161,6 @@ When @file{dired-x.el} is loaded, some standard Dired functions from Dired}), if it is active. @code{dired-find-buffer-nocreate} and @code{dired-initial-position} respect the value of @code{dired-find-subdir} (@pxref{Miscellaneous Commands}). -@code{dired-clean-up-after-deletion} respects the value of -@code{dired-clean-up-buffers-too}. @code{dired-read-shell-command} uses -@code{dired-guess-shell-command} (@pxref{Shell Command Guessing}) to -offer a smarter default command. @node Installation @chapter Installation @@ -186,7 +178,6 @@ In your @file{~/.emacs} file, or in the system-wide initialization file (with-eval-after-load 'dired (require 'dired-x) ;; Set dired-x global variables here. For example: - ;; (setq dired-guess-shell-gnutar "gtar") ;; (setq dired-x-hands-off-my-keys nil) )) (add-hook 'dired-mode-hook @@ -438,111 +429,6 @@ Loading @file{dired-x.el} will install Dired Omit by putting call @code{dired-extra-startup}, which in turn calls @code{dired-omit-startup} in your @code{dired-mode-hook}. -@node Shell Command Guessing -@chapter Shell Command Guessing -@cindex guessing shell commands for files. - -Based upon the name of a file, Dired tries to guess what shell -command you might want to apply to it. For example, if you have point -on a file named @file{foo.tar} and you press @kbd{!}, Dired will guess -you want to @samp{tar xvf} it and suggest that as the default shell -command. - -The default is mentioned in brackets and you can type @kbd{M-n} to get -the default into the minibuffer and then edit it, e.g., to change -@samp{tar xvf} to @samp{tar tvf}. If there are several commands for a given -file, e.g., @samp{xtex} and @samp{dvips} for a @file{.dvi} file, you can type -@kbd{M-n} several times to see each of the matching commands. - -Dired only tries to guess a command for a single file, never for a list -of marked files. - -The following variables control guessing of shell commands: - -@defvar dired-guess-shell-alist-default -This variable specifies the predefined rules for guessing shell -commands suitable for certain files. Set this to @code{nil} to turn -guessing off. The elements of @code{dired-guess-shell-alist-user} -(defined by the user) will override these rules. -@end defvar - -@defvar dired-guess-shell-alist-user -If non-@code{nil}, this variables specifies the user-defined alist of -file regexps and their suggested commands. These rules take -precedence over the predefined rules in the variable -@code{dired-guess-shell-alist-default} (to which they are prepended) -when @code{dired-do-shell-command} is run). The default is -@code{nil}. - -Each element of the alist looks like - -@example -(@var{regexp} @var{command}@dots{}) -@end example - -@noindent -where each @var{command} can either be a string or a Lisp expression -that evaluates to a string. If several commands are given, all of -them will temporarily be pushed onto the history. - -A @samp{*} in the shell command stands for the file name that matched -@var{regexp}. When Emacs invokes the @var{command}, it replaces each -instance of @samp{*} with the matched file name. - -You can set this variable in your @file{~/.emacs}. For example, -to add rules for @samp{.foo} and @samp{.bar} file extensions, write - -@example -(setq dired-guess-shell-alist-user - (list - (list "\\.foo$" "@var{foo-command}");; fixed rule - ;; possibly more rules... - (list "\\.bar$";; rule with condition test - '(if @var{condition} - "@var{bar-command-1}" - "@var{bar-command-2}")))) -@end example - -@noindent -This will override any predefined rules for the same extensions. -@end defvar - -@defvar dired-guess-shell-case-fold-search -If this variable is non-@code{nil}, -@code{dired-guess-shell-alist-default} and -@code{dired-guess-shell-alist-user} are matched case-insensitively. -The default is @code{t}. -@end defvar - -@cindex passing GNU Tar its @samp{z} switch. -@defvar dired-guess-shell-gnutar -If this variable is non-@code{nil}, it specifies the name of the GNU -Tar executable (e.g., @file{tar} or @file{gnutar}). GNU Tar's -@samp{z} switch is used for compressed archives. If you don't have -GNU Tar, set this to @code{nil}: a pipe using @command{zcat} is then -used instead. The default is @code{nil}. -@end defvar - -@cindex @code{gzip} -@defvar dired-guess-shell-gzip-quiet -A non-@code{nil} value of this variable means that @samp{-q} is passed -to @command{gzip}, possibly overriding a verbose option in the @env{GZIP} -environment variable. The default is @code{t}. -@end defvar - -@cindex @code{znew} -@defvar dired-guess-shell-znew-switches nil -This variable specifies a string of switches passed to @command{znew}. -An example is @samp{-K} which will make @command{znew} keep a @file{.Z} -file when it is smaller than the @file{.gz} file. The default is -@code{nil}: no additional switches are passed to @command{znew}. -@end defvar - -@defvar dired-shell-command-history nil -This variable holds the history list for commands that read -dired-shell commands. -@end defvar - @node Virtual Dired @chapter Virtual Dired @@ -884,15 +770,6 @@ normal and a wildcard buffer for the same directory, @kbd{C-x d @key{RET}} will toggle between those two. @end table -@table @kbd -@findex dired-goto-subdir -@kindex M-G -@item M-G -(@code{dired-goto-subdir}) Go to the header line of an inserted directory. -This command reads its argument, with completion derived from the names of the -inserted subdirectories. -@end table - @table @code @item dired-vm @@ -920,55 +797,6 @@ to @kbd{V}. Otherwise, @code{dired-bind-rmail} will be bound. @findex dired-rmail Bound to @kbd{V} if @code{dired-bind-vm} is @code{nil}. Run Rmail on this file (assumed to be mail folder in Rmail format). - -@item dired-info -@kindex I -@cindex running info. -@findex dired-info -Bound to @kbd{I}. Run Info on this file (assumed to be a file in Info -format). - -@vindex dired-bind-info -If the variable @code{dired-bind-info} is @code{nil}, @code{dired-info} will -not be bound to @kbd{I}. - -@item dired-man -@cindex running man. -@kindex N -@findex dired-man -Bound to @kbd{N}. Run man on this file (assumed to be a file in @code{nroff} -format). - -@vindex dired-bind-man -If the variable @code{dired-bind-man} is @code{nil}, @code{dired-man} will not -be bound to @kbd{N}. - -@item dired-do-relsymlink -@cindex relative symbolic links. -@kindex Y -@findex dired-do-relsymlink -Bound to @kbd{Y}. Relative symlink all marked (or next ARG) files into a -directory, or make a relative symbolic link to the current file. This creates -relative symbolic links like - -@example - foo -> ../bar/foo -@end example - -@noindent -not absolute ones like - -@example - foo -> /ugly/path/that/may/change/any/day/bar/foo -@end example - -@item dired-do-relsymlink-regexp -@kindex %Y -@findex dired-do-relsymlink-regexp -Bound to @kbd{%Y}. Relative symlink all marked files containing -@var{regexp} to @var{newname}. See functions -@code{dired-do-rename-regexp} and @code{dired-do-relsymlink} for more -info. @end table @node Bugs diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi index 518b30fea89..9867883b24a 100644 --- a/doc/misc/ede.texi +++ b/doc/misc/ede.texi @@ -99,7 +99,7 @@ learn and adopt GNU ways of doing things. @chapter @ede{} Project Concepts @ede{} is a generic interface for managing projects. It specifies a -single set of menus and keybindings, while supporting multiple ways to +single set of menus and key bindings, while supporting multiple ways to express a project via a build system. In the subsequent chapters, we will describe the different project @@ -144,7 +144,7 @@ init file: Activating @ede{} adds a menu named @samp{Development} to the menu bar. This menu provides several menu items for high-level @ede{} -commands. These menu items, and their corresponding keybindings, are +commands. These menu items, and their corresponding key bindings, are independent of the type of project you are actually working on. @node Quick Start @@ -271,7 +271,7 @@ Projects. You can create targets either from a buffer, or from a @code{dired} directory buffer. Note: If for some reason a directory list buffer, or file does not have the -@samp{Project} menu item, or if @ede{} keybindings don't work, just +@samp{Project} menu item, or if @ede{} key bindings don't work, just use @kbd{M-x revert-buffer @key{RET}} to force a refresh. Sometimes creating a new project doesn't restart buffers correctly. @@ -958,7 +958,7 @@ The example for Makefiles looks like this: ((buildfile :initform "Makefile")) "Generic Project for makefiles.") -(defmethod ede-generic-setup-configuration ((proj ede-generic-makefile-project) config) +(cl-defmethod ede-generic-setup-configuration ((proj ede-generic-makefile-project) config) "Set up a configuration for Make." (oset config build-command "make -k") (oset config debug-command "gdb ")) @@ -1059,7 +1059,7 @@ examples. @menu * Development Overview:: * Detecting a Project:: -* User interface methods:: Methods associated with keybindings +* User interface methods:: Methods associated with key bindings * Base project methods:: The most basic methods on @ede{} objects. * Sourcecode objects:: Defining new sourcecode classes. * Compiler and Linker objects:: Defining new compilers and linkers. @@ -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/ediff.texi b/doc/misc/ediff.texi index 8a7de88d655..cbc7556aa82 100644 --- a/doc/misc/ediff.texi +++ b/doc/misc/ediff.texi @@ -1869,7 +1869,8 @@ These variables specify the options to pass to the above utilities. In @code{ediff-diff-options}, it may be useful to specify options such as @samp{-w} that ignore certain kinds of changes. However, Ediff does not let you use the option @samp{-c}, as it doesn't recognize this -format yet. +format yet. (If you alter this variable, it should be done via the +Customize interface instead of using @code{setq} directly.) @item ediff-coding-system-for-read @vindex ediff-coding-system-for-read diff --git a/doc/misc/efaq-w32.texi b/doc/misc/efaq-w32.texi index 35ff01a336c..46c257e42e5 100644 --- a/doc/misc/efaq-w32.texi +++ b/doc/misc/efaq-w32.texi @@ -691,9 +691,9 @@ question also. @node CUA @subsection Standard Windows key bindings @findex cua-mode -@cindex CUA keybindings +@cindex CUA key bindings @cindex shift key, selecting with -@cindex standard Windows keybindings +@cindex standard Windows key bindings @cindex paste with C-v @cindex cut with C-x @cindex copy with C-c @@ -701,7 +701,7 @@ question also. @cindex C-x to cut @cindex C-v to paste -The keybindings of Emacs predate modern GUIs, and the keys that were +The key bindings of Emacs predate modern GUIs, and the keys that were chosen by later GUIs for cut and copy were given important functions as extended keymaps in Emacs. CUA mode attempts to let both bindings co-exist by defining C-x and C-c as @code{kill-region} and @@ -930,9 +930,9 @@ an indication of whether the font is outline (.TTF, .ATM) or raster (.FON) based when fonts are listed, which may let you differentiate between two fonts with the same name and different technologies. -Starting with Emacs 23, the preferred font name format will be moving -to the simpler and more flexible fontconfig format. XLFD names will -continue to be supported for backward compatibility. +Starting with Emacs 23, the preferred font name format is the simpler +and more flexible fontconfig format. XLFD names will continue to be +supported for backward compatibility. @example XLFD: -*-Courier New-normal-r-*-*-13-*-*-*-c-*-iso8859-1 diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi index 32fdcb80586..43fa0054346 100644 --- a/doc/misc/efaq.texi +++ b/doc/misc/efaq.texi @@ -9,10 +9,9 @@ @copying Copyright @copyright{} 2001--2022 Free Software Foundation, Inc.@* -Copyright @copyright{} 1994, 1995, 1996, 1997, 1998, 1999, 2000 -Reuven M. Lerner@* -Copyright @copyright{} 1992, 1993 Steven Byrnes@* -Copyright @copyright{} 1990, 1991, 1992 Joseph Brian Wells@* +Copyright @copyright{} 1994--2000 Reuven M. Lerner@* +Copyright @copyright{} 1992--1993 Steven Byrnes@* +Copyright @copyright{} 1990--1992 Joseph Brian Wells@* @quotation This list of frequently asked questions about GNU Emacs with answers @@ -28,9 +27,6 @@ latest version of the FAQ is archived. The FAQ may be copied and redistributed under these conditions, except that the FAQ may not be embedded in a larger literary work unless that work itself allows free copying and redistribution. - -[This version has been heavily edited since it was included in the Emacs -distribution in 1999.] @end quotation @end copying @@ -151,7 +147,7 @@ and @key{Meta} @item @key{DEL}: @key{Delete}, usually @strong{not} the same as -@key{Backspace}; same as @kbd{C-?} (see @ref{Backspace invokes help}, if +@key{Backspace}; same as @kbd{C-?} (@pxref{Backspace invokes help}, if deleting invokes Emacs help) @item @@ -259,12 +255,13 @@ name displayed by this will be the full pathname of the installed @code{data-directory}, and @kbd{C-h v} displays the value and the documentation of a variable.) -The location of your Info directory (i.e., where Info documentation -is stored) is kept in the variable @code{Info-default-directory-list}. Use -@kbd{C-h v Info-default-directory-list @key{RET}} to see the value of -this variable, which will be a list of directory names. The last -directory in that list is probably where most Info files are stored. By -default, Emacs Info documentation is placed in @file{/usr/local/share/info}. +The location of your Info directory (i.e., where Info documentation is +stored) is kept in the variable @code{Info-directory-list}. Use +@kbd{C-h v Info-directory-list @key{RET}} to see the value of this +variable, which will be a list of directory names (after Info has been +started). The last directory in that list is probably where most Info +files are stored. By default, Emacs Info documentation is placed in +@file{/usr/local/share/info}. For information on some of the files in the @file{etc} directory, @pxref{Informational files for Emacs}. @@ -545,11 +542,11 @@ printed manual}. @cindex Reference cards, in other languages @item You can get a printed reference card listing commands and keys to -invoke them. You can order one from the FSF for $2 (or 10 for $18), -or you can print your own from the @file{etc/refcards/refcard.tex} or -@file{etc/refcards/refcard.pdf} files in the Emacs distribution. -The Emacs distribution comes with translations of the reference card -into several languages; look for files named +invoke them. You can order one from the FSF, or you can print your +own from the @file{etc/refcards/refcard.tex} or +@file{etc/refcards/refcard.pdf} files in the Emacs distribution. The +Emacs distribution comes with translations of the reference card into +several languages; look for files named @file{etc/refcards/@var{lang}-refcard.*}, where @var{lang} is a two-letter code of the language. For example, the German version of the reference card is in the files @file{etc/refcards/de-refcard.tex} @@ -696,12 +693,13 @@ of the file in parentheses, like this: @item You can create your own Info directory. You can tell Emacs where that Info directory is by adding its pathname to the value of the variable -@code{Info-default-directory-list}. For example, to use a private Info -directory which is a subdirectory of your home directory named @file{Info}, -you could put this in your @file{.emacs} file: +@code{Info-default-directory-list}. For example, to use a private +Info directory which is a subdirectory of your home directory named +@file{Info}, you could put this in your init file (@pxref{Setting up a +customization file}): @lisp -(add-to-list 'Info-default-directory-list "~/Info") +(add-to-list 'Info-default-directory-list "~/Info/") @end lisp You will need a top-level Info file named @file{dir} in this directory @@ -793,7 +791,7 @@ informational files about Emacs and relevant aspects of the GNU project are available for you to read. The following files (and others) are available in the @file{etc} -directory of the Emacs distribution (see @ref{File-name conventions}, if +directory of the Emacs distribution (@pxref{File-name conventions}, if you're not sure where that is). Many of these files are available via the Emacs @samp{Help} menu, or by typing @kbd{C-h ?} (@kbd{M-x help-for-help}). @@ -881,10 +879,11 @@ divergent TECO command sets and key bindings at MIT, and completed by RMS. Many people have said that TECO code looks a lot like line noise; you -can read more at @uref{news:alt.lang.teco}. Someone has written a TECO -implementation in Emacs Lisp (to find it, see @ref{Packages that do not -come with Emacs}); it would be an interesting project to run the -original TECO Emacs inside of Emacs. +can read more on +@uref{https://en.wikipedia.org/wiki/TECO_(text_editor), Wikipedia}. +Someone has written a TECO implementation in Emacs Lisp (to find it, +see @ref{Packages that do not come with Emacs}); it would be an +interesting project to run the original TECO Emacs inside of Emacs. @cindex Why Emacs? For some not-so-serious alternative reasons for Emacs to have that @@ -1607,35 +1606,38 @@ is better to write ``Emacs and XEmacs.'' @end menu @node Setting up a customization file -@section How do I set up a @file{.emacs} file properly? +@section How do I set up an init file properly? @cindex @file{.emacs} file, setting up -@cindex @file{.emacs} file, locating +@cindex @file{.emacs.d/init.el} file, setting up @cindex Init file, setting up +@cindex Init file, locating @cindex Customization file, setting up +When Emacs is started, it normally tries to load a Lisp program from +an @dfn{initialization file}, or @dfn{init file} for short. This +file, if it exists, specifies how to initialize Emacs for you. +Traditionally, file @file{~/.emacs} is used as the init file, although +Emacs also looks at @file{~/.emacs.el}, @file{~/.emacs.d/init.el}, +@file{~/.config/emacs/init.el}, or other locations. @xref{Init File,,, emacs, The GNU Emacs Manual}. -In general, new Emacs users should not be provided with @file{.emacs} -files, because this can cause confusing non-standard behavior. Then -they send questions to -@url{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs, -the help-gnu-emacs mailing list} asking why Emacs -isn't behaving as documented. - Emacs includes the Customize facility (@pxref{Using Customize}). This allows users who are unfamiliar with Emacs Lisp to modify their -@file{.emacs} files in a relatively straightforward way, using menus +init files in a relatively straightforward way, using menus rather than Lisp code. While Customize might indeed make it easier to configure Emacs, consider taking a bit of time to learn Emacs Lisp and modifying your -@file{.emacs} directly. Simple configuration options are described +init file directly. Simple configuration options are described rather completely in @ref{Init File,,, emacs, The GNU Emacs Manual}, for users interested in performing frequently requested, basic tasks. -Sometimes users are unsure as to where their @file{.emacs} file should -be found. Visiting the file as @file{~/.emacs} from Emacs will find -the correct file. +In general, new Emacs users should not be provided with init +files, because this can cause confusing non-standard behavior. Then +they send questions to +@url{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs, +the help-gnu-emacs mailing list} asking why Emacs +isn't behaving as documented. @node Using Customize @section How do I start using Customize? @@ -1743,21 +1745,22 @@ always use custom terminal definition with @samp{setb24} and @samp{setf24}. @node Debugging a customization file -@section How do I debug a @file{.emacs} file? -@cindex Debugging @file{.emacs} file -@cindex @file{.emacs} debugging +@section How do I debug an init file? +@cindex Debugging @file{.emacs.d/init.el} file +@cindex Debugging init file +@cindex @file{.emacs.d/init.el} debugging @cindex Init file debugging @cindex @samp{-debug-init} option Start Emacs with the @samp{-debug-init} command-line option. This -enables the Emacs Lisp debugger before evaluating your @file{.emacs} +enables the Emacs Lisp debugger before evaluating your init file, and places you in the debugger if something goes wrong. The top line in the @file{trace-back} buffer will be the error message, and the second or third line of that buffer will display the Lisp code from your -@file{.emacs} file that caused the problem. +init file that caused the problem. You can also evaluate an individual function or argument to a function -in your @file{.emacs} file by moving the cursor to the end of the +in your init file by moving the cursor to the end of the function or argument and typing @kbd{C-x C-e} (@kbd{M-x eval-last-sexp}). @@ -1787,7 +1790,8 @@ You can similarly display the current column with @end lisp @noindent -in your @file{.emacs} file. This feature is off by default. +in your init file (@pxref{Setting up a customization file}). This +feature is off by default. The @code{"%c"} format specifier in the variable @code{mode-line-format} will insert the current column's value into the mode line. See the @@ -1806,9 +1810,8 @@ optional display. Alternatively, you can use the customize @code{display-line-numbers-type} with the same value as you would use with @code{display-line-numbers}. -There is also the @samp{linum} package (distributed with Emacs since -version 23.1) which will henceforth become obsolete. Users and -developers are encouraged to use @samp{display-line-numbers} instead. +There is also the @samp{linum} package which will henceforth become +obsolete. We recommend using @samp{display-line-numbers} instead. @node Displaying the current file name in the titlebar @section How can I modify the titlebar to contain the current file name? @@ -1834,7 +1837,7 @@ machine at which Emacs was invoked. This is done by setting To modify the behavior such that frame titlebars contain the buffer's name regardless of the number of existing frames, include the following -in your @file{.emacs}: +in your init file (@pxref{Setting up a customization file}): @lisp (setq frame-title-format "%b") @@ -1844,9 +1847,10 @@ in your @file{.emacs}: @section How do I turn on abbrevs by default just in mode @var{mymode}? @cindex Abbrevs, turning on by default -Abbrev mode expands abbreviations as you type them. To turn it on in a -specific buffer, use @kbd{M-x abbrev-mode}. To turn it on in every -buffer by default, put this in your @file{.emacs} file: +Abbrev mode expands abbreviations as you type them. To turn it on in +a specific buffer, use @kbd{M-x abbrev-mode}. To turn it on in every +buffer by default, put this in your init file (@pxref{Setting up a +customization file}): @lisp (setq-default abbrev-mode t) @@ -1896,7 +1900,8 @@ the script. Use @kbd{C-h v} (or @kbd{M-x describe-variable}) on @cindex Highlighting and replacing text Use @code{delete-selection-mode}, which you can start automatically by -placing the following Lisp form in your @file{.emacs} file: +placing the following Lisp form in your init file (@pxref{Setting up a +customization file}): @lisp (delete-selection-mode 1) @@ -2034,9 +2039,10 @@ The default maximum line width is 70, determined by the variable To turn on @code{auto-fill-mode} just once for one buffer, use @kbd{M-x auto-fill-mode}. -To turn it on for every buffer in a certain mode, you must use the hook -for that mode. For example, to turn on @code{auto-fill} mode for all -text buffers, including the following in your @file{.emacs} file: +To turn it on for every buffer in a certain mode, you must use the +hook for that mode. For example, to turn on @code{auto-fill} mode for +all text buffers, including the following in your init file +(@pxref{Setting up a customization file}): @lisp (add-hook 'text-mode-hook 'turn-on-auto-fill) @@ -2091,7 +2097,8 @@ option: emacs -f server-start @end example -or by invoking @code{server-start} from @file{.emacs}: +or by invoking @code{server-start} from init file (@pxref{Setting up a +customization file}): @lisp (if (@var{some conditions are met}) (server-start)) @@ -2162,7 +2169,8 @@ f() @} @end example -@noindent To achieve this, add the following line to your @file{.emacs}: +@noindent To achieve this, add the following line to your init file +(@pxref{Setting up a customization file}): @lisp (c-set-offset 'case-label '+) @@ -2213,7 +2221,8 @@ the line or the block according to what you just specified. @item If you don't like the result, go back to step 1. Otherwise, add the -following line to your @file{.emacs}: +following line to your init file (@pxref{Setting up a customization +file}): @lisp (c-set-offset '@var{syntactic-symbol} @var{offset}) @@ -2243,8 +2252,8 @@ customizations inside a C mode hook, like this: @noindent Using @code{c-mode-hook} avoids the need to put a @w{@code{(require -'cc-mode)}} into your @file{.emacs} file, because @code{c-set-offset} -might be unavailable when @code{cc-mode} is not loaded. +'cc-mode)}} into your init file, because @code{c-set-offset} might be +unavailable when @code{cc-mode} is not loaded. Note that @code{c-mode-hook} runs for C source files only; use @code{c++-mode-hook} for C@t{++} sources, @code{java-mode-hook} for @@ -2316,8 +2325,8 @@ usage: xset [-display host:dpy] option ... @cindex Previous line, indenting according to @cindex Text indentation -Such behavior is automatic (in Text mode) in Emacs 20 and later. From the -@file{etc/NEWS} file for Emacs 20.2: +Such behavior is automatic (in Text mode). From the @file{etc/NEWS} +file for Emacs 20.2: @example ** In Text mode, now only blank lines separate paragraphs. This makes @@ -2355,7 +2364,8 @@ new paragraph. There are many packages available to deal with this @cindex Pairs of parentheses, highlighting @cindex Matching parentheses -Call @code{show-paren-mode} in your @file{.emacs} file: +Call @code{show-paren-mode} in your init file (@pxref{Setting up a +customization file}): @lisp (show-paren-mode 1) @@ -2460,8 +2470,9 @@ Emacs Lisp @dfn{form}: @item If you want it evaluated every time you run Emacs, put it in a file -named @file{.emacs} in your home directory. This is known as ``your -@file{.emacs} file,'' and contains all of your personal customizations. +named @file{.emacs.d/init.el} in your home directory. This is known +as ``your init file,'' and contains all of your personal +customizations (@pxref{Setting up a customization file}). @item You can type the form in the @file{*scratch*} buffer, and then type @@ -2499,7 +2510,7 @@ about them. Set the default value of the variable @code{tab-width}. For example, to set @key{TAB} stops every 10 characters, insert the following in your -@file{.emacs} file: +init file (@pxref{Setting up a customization file}): @lisp (setq-default tab-width 10) @@ -2641,8 +2652,9 @@ Quick command-line switch descriptions are also available. For example, You probably don't want to do this, since backups are useful, especially when something goes wrong. -To avoid seeing backup files (and other ``uninteresting'' files) in Dired, -load @code{dired-x} by adding the following to your @file{.emacs} file: +To avoid seeing backup files (and other ``uninteresting'' files) in +Dired, load @code{dired-x} by adding the following to your init file +(@pxref{Setting up a customization file}): @lisp (with-eval-after-load 'dired @@ -2651,7 +2663,7 @@ load @code{dired-x} by adding the following to your @file{.emacs} file: With @code{dired-x} loaded, @kbd{C-x M-o} toggles omitting in each dired buffer. You can make omitting the default for new dired buffers by putting the -following in your @file{.emacs}: +following in your init file: @lisp (add-hook 'dired-mode-hook 'dired-omit-mode) @@ -2891,31 +2903,32 @@ and cause an annoying delay in display, so several features exist to work around this. @cindex Just-In-Time syntax highlighting -In Emacs 21 and later, turning on @code{font-lock-mode} automatically -activates the new @dfn{Just-In-Time fontification} provided by -@code{jit-lock-mode}. @code{jit-lock-mode} defers the fontification of -portions of buffer until you actually need to see them, and can also -fontify while Emacs is idle. This makes display of the visible portion -of a buffer almost instantaneous. For details about customizing -@code{jit-lock-mode}, type @kbd{C-h f jit-lock-mode @key{RET}}. +Turning on @code{font-lock-mode} automatically activates +@dfn{Just-In-Time fontification} provided by @code{jit-lock-mode}. +@code{jit-lock-mode} defers the fontification of portions of buffer +until you actually need to see them, and can also fontify while Emacs +is idle. This makes display of the visible portion of a buffer almost +instantaneous. For details about customizing @code{jit-lock-mode}, +type @kbd{C-h f jit-lock-mode @key{RET}}. @cindex Levels of syntax highlighting @cindex Decoration level, in @code{font-lock-mode} -In versions of Emacs before 21, different levels of decoration are -available, from slight to gaudy. More decoration means you need to wait -more time for a buffer to be fontified (or a faster machine). To -control how decorated your buffers should become, set the value of -@code{font-lock-maximum-decoration} in your @file{.emacs} file, with a -@code{nil} value indicating default (usually minimum) decoration, and a -@code{t} value indicating the maximum decoration. For the gaudiest -possible look, then, include the line +Different levels of decoration are available, from slight to gaudy. +More decoration means you need to wait more time for a buffer to be +fontified (or a faster machine). To control how decorated your +buffers should become, set the value of +@code{font-lock-maximum-decoration} in your init file (@pxref{Setting +up a customization file}), with a @code{nil} value indicating default +(usually minimum) decoration, and a @code{t} value indicating the +maximum decoration. For the gaudiest possible look, then, include the +line @lisp (setq font-lock-maximum-decoration t) @end lisp @noindent -in your @file{.emacs} file. You can also set this variable such that +in your init file. You can also set this variable such that different modes are highlighted in a different ways; for more information, see the documentation for @code{font-lock-maximum-decoration} with @kbd{C-h v} (or @kbd{M-x @@ -2942,7 +2955,8 @@ customize-variable @key{RET} scroll-conservatively @key{RET}} and set it to a large value like, say, 10000. For an explanation of what this means, @pxref{Auto Scrolling,,, emacs, The GNU Emacs Manual}. -Alternatively, use the following Lisp form in your @file{.emacs}: +Alternatively, use the following Lisp form in your init file +(@pxref{Setting up a customization file}): @lisp (setq scroll-conservatively most-positive-fixnum) @@ -2971,7 +2985,8 @@ default, a backslash (@samp{\}) will appear in the mode line. @cindex Single space following periods @cindex Periods, one space following -Add the following line to your @file{.emacs} file: +Add the following line to your init file (@pxref{Setting up a +customization file}): @lisp (setq sentence-end-double-space nil) @@ -2985,11 +3000,7 @@ Add the following line to your @file{.emacs} file: In many systems, @code{ls} is aliased to @samp{ls --color}, which prints using ANSI color escape sequences. Emacs includes the @code{ansi-color} package, which lets Shell mode recognize these -escape sequences. In Emacs 23.2 and later, the package is enabled by -default; in earlier versions you can enable it by typing @kbd{M-x -ansi-color-for-comint-mode} in the Shell buffer, or by adding -@code{(add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on)} to -your init file. +escape sequences. It is enabled by default. @node Fullscreen mode on MS-Windows @section How can I start Emacs in fullscreen mode on MS-Windows? @@ -2997,15 +3008,15 @@ your init file. @cindex Fullscreen mode Beginning with Emacs 24.4 either run Emacs with the @samp{--maximized} -command-line option or put the following form in your @file{.emacs} -file: +command-line option or put the following form in your init file +(@pxref{Setting up a customization file}): @lisp (add-hook 'emacs-startup-hook 'toggle-frame-maximized) @end lisp With older versions use the function @code{w32-send-sys-command}. For -example, you can put the following in your @file{.emacs} file: +example, you can put the following in your init file: @lisp (add-hook 'emacs-startup-hook @@ -3159,10 +3170,9 @@ Emacs has an inherent fixed limitation on the size of buffers. This limit is stricter than the maximum size of objects supported by other programs on the same architecture. -The maximum buffer size on 32-bit machines is 512 MBytes beginning -with version 23.2. If Emacs was built using the -@code{--with-wide-int} flag, the maximum buffer size on 32-bit -machines is 2 GB. +The maximum buffer size on 32-bit machines is 512 MBytes. If Emacs +was built using the @code{--with-wide-int} flag, the maximum buffer +size on 32-bit machines is 2 GB. Emacs compiled on a 64-bit machine can handle much larger buffers; up to @code{most-positive-fixnum} (2.3 exabytes). @@ -3226,8 +3236,8 @@ with the following Lisp form, The above solutions try to prevent the shell from producing the @samp{^M} characters in the first place. If this is not possible (e.g., if you use a Windows shell), you can get Emacs to remove these -characters from the buffer by adding this to your @file{.emacs} init -file: +characters from the buffer by adding this to your init file +(@pxref{Setting up a customization file}): @smalllisp (add-hook 'comint-output-filter-functions #'comint-strip-ctrl-m) @@ -3249,8 +3259,8 @@ stty -icrnl -onlcr -echo susp ^Z @cindex @code{explicit-shell-file-name} This might happen because Emacs tries to look for the shell in a wrong place. If you know where your shell executable is, set the variable -@code{explicit-shell-file-name} in your @file{.emacs} file to point to -its full file name. +@code{explicit-shell-file-name} in your init file (@pxref{Setting up a +customization file}) to point to its full file name. @cindex Antivirus programs, and Shell Mode Some people have trouble with Shell Mode on MS-Windows because of @@ -3292,18 +3302,18 @@ if ("$term" == emacs) set term=dumb @node Errors with init files @section Why does Emacs say @samp{Error in init file}? -@cindex Error in @file{.emacs} +@cindex Error in @file{.emacs.d/init.el} @cindex Error in init file @cindex Init file, errors in -@cindex @file{.emacs} file, errors in -@cindex Debugging @file{.emacs} file +@cindex @file{.emacs.d/init.el} file, errors in +@cindex Debugging init file -An error occurred while loading either your @file{.emacs} file or the +An error occurred while loading either your init file or the system-wide file @file{site-lisp/default.el}. Emacs pops the @file{*Messages*} buffer, and puts there some additional information about the error, to provide some hints for debugging. -For information on how to debug your @file{.emacs} file, see +For information on how to debug your init file, see @ref{Debugging a customization file}. It may be the case that you need to load some package first, or use a @@ -3473,56 +3483,13 @@ bottom of files by setting the variable @code{enable-local-eval}. @xref{File Variables,,, emacs, The GNU Emacs Manual}. @item -Synthetic X events. (Yes, a risk; use @samp{MIT-MAGIC-COOKIE-1} or -better.) - -Emacs accepts synthetic X events generated by the @code{SendEvent} -request as though they were regular events. As a result, if you are -using the trivial host-based authentication, other users who can open X -connections to your X workstation can make your Emacs process do -anything, including run other processes with your privileges. - -The only fix for this is to prevent other users from being able to open -X connections. The standard way to prevent this is to use a real -authentication mechanism, such as @samp{MIT-MAGIC-COOKIE-1}. If using -the @code{xauth} program has any effect, then you are probably using -@samp{MIT-MAGIC-COOKIE-1}. Your site may be using a superior -authentication method; ask your system administrator. - -If real authentication is not a possibility, you may be satisfied by -just allowing hosts access for brief intervals while you start your X -programs, then removing the access. This reduces the risk somewhat by -narrowing the time window when hostile users would have access, but -@emph{does not eliminate the risk}. - -On most computers running Unix and X, you enable and disable -access using the @code{xhost} command. To allow all hosts access to -your X server, use - -@example -xhost + -@end example +Browsing the web. -@noindent -at the shell prompt, which (on an HP machine, at least) produces the -following message: - -@example -access control disabled, clients can connect from any host -@end example - -To deny all hosts access to your X server (except those explicitly -allowed by name), use - -@example -xhost - -@end example - -On the test HP computer, this command generated the following message: - -@example -access control enabled, only authorized clients can connect -@end example +Emacs relies on C libraries to parse images, and historically, many of +these have had exploitable weaknesses. If you're browsing the web +with the eww browser, it will usually download and display images +using these libraries. If an image library has a weakness, it may be +used by an attacker to gain access. @end itemize @@ -3632,8 +3599,8 @@ and any Emacs Info files that might be in @file{/usr/local/share/info/}. @cindex Apple computers, Emacs for @cindex Macintosh, Emacs for @cindex macOS, Emacs for -Beginning with version 22.1, Emacs supports macOS natively. -See the file @file{nextstep/INSTALL} in the distribution. +Emacs supports macOS natively. See the file @file{nextstep/INSTALL} +in the distribution. @cindex FAQ for Emacs on MS-Windows @cindex Emacs for MS-Windows @@ -3642,8 +3609,8 @@ There is a separate FAQ for Emacs on MS-Windows, @pxref{Top,,,efaq-w32,FAQ for Emacs on MS Windows}. @cindex GNUstep, Emacs for -Beginning with version 23.1, Emacs supports GNUstep natively. -See the file @file{nextstep/INSTALL} in the distribution. +Emacs supports GNUstep natively. See the file @file{nextstep/INSTALL} +in the distribution. @cindex MS-DOS, Emacs for @cindex DOS, Emacs for @@ -3851,7 +3818,6 @@ information is available from * Compose Character:: * Binding combinations of modifiers and function keys:: * Meta key does not work in xterm:: -* SPC no longer completes file names:: @end menu @node Binding keys to commands @@ -3860,9 +3826,10 @@ information is available from @cindex Keys, binding to commands @cindex Commands, binding keys to -Keys can be bound to commands either interactively or in your -@file{.emacs} file. To interactively bind keys for all modes, type -@kbd{M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET}}. +Keys can be bound to commands either interactively or in your init +file (@pxref{Setting up a customization file}). To interactively bind +keys for all modes, type @kbd{M-x global-set-key @key{RET} @var{key} +@var{cmd} @key{RET}}. To bind a key just in the current major mode, type @kbd{M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET}}. @@ -3873,7 +3840,7 @@ To make the process of binding keys interactively easier, use the following ``trick'': First bind the key interactively, then immediately type @kbd{C-x @key{ESC} @key{ESC} C-a C-k C-g}. Now, the command needed to bind the key is in the kill ring, and can be yanked into your -@file{.emacs} file. If the key binding is global, no changes to the +init file. If the key binding is global, no changes to the command are required. For example, @lisp @@ -3881,9 +3848,9 @@ command are required. For example, @end lisp @noindent -can be placed directly into the @file{.emacs} file. If the key binding is -local, the command is used in conjunction with the @samp{add-hook} function. -For example, in TeX mode, a local binding might be +can be placed directly into your init file. If the key binding is +local, the command is used in conjunction with the @samp{add-hook} +function. For example, in TeX mode, a local binding might be @lisp (add-hook 'tex-mode-hook @@ -3941,14 +3908,15 @@ of these forms before attempting to bind the key sequence: @end lisp @node Terminal setup code works after Emacs has begun -@section Why doesn't this [terminal or window-system setup] code work in my @file{.emacs} file, but it works just fine after Emacs starts up? -@cindex Terminal setup code in @file{.emacs} +@section Why doesn't this [terminal or window-system setup] code work in my init file, but it works just fine after Emacs starts up? +@cindex Terminal setup code in init file -During startup, Emacs initializes itself according to a given code/file -order. If some of the code executed in your @file{.emacs} file needs to -be postponed until the initial terminal or window-system setup code has -been executed but is not, then you will experience this problem (this -code/file execution order is not enforced after startup). +During startup, Emacs initializes itself according to a given +code/file order. If some of the code executed in your init file +(@pxref{Setting up a customization file}) needs to be postponed until +the initial terminal or window-system setup code has been executed but +is not, then you will experience this problem (this code/file +execution order is not enforced after startup). To postpone the execution of Emacs Lisp code until after terminal or window-system setup, treat the code as a @dfn{lambda list} and add it to @@ -4297,10 +4265,6 @@ If there is an @code{rlogin} connection between @code{xterm} and Emacs, the of every character. @item -If Emacs is running on Ultrix, it is reported that evaluating -@code{(set-input-mode t nil)} helps. - -@item If all else fails, you can make @code{xterm} generate @kbd{@key{ESC} W} when you type @kbd{M-W}, which is the same conversion Emacs would make if it got the @kbd{M-W} anyway. In X11R4, the following resource @@ -4325,22 +4289,6 @@ You might have to replace @samp{Meta} with @samp{Alt}. @end itemize -@node SPC no longer completes file names -@section Why doesn't @key{SPC} complete file names anymore? -@cindex @kbd{SPC} file name completion - -Starting with Emacs 22.1, @kbd{SPC} no longer completes file names in -the minibuffer, so that file names with embedded spaces could be typed -without the need to quote the spaces. - -You can get the old behavior by binding @kbd{SPC} to -@code{minibuffer-complete-word} in the minibuffer, as follows: - -@lisp -(define-key minibuffer-local-filename-completion-map (kbd "SPC") - 'minibuffer-complete-word) -@end lisp - @c ------------------------------------------------------------ @node Alternate character sets @chapter Alternate character sets @@ -4389,8 +4337,7 @@ Emacs Manual}. For more sophisticated methods, @cindex bidirectional scripts Emacs supports display and editing of bidirectional scripts, such as -Arabic, Farsi, and Hebrew, since version 24.1. -@xref{New in Emacs 24, bidirectional display}. +Arabic, Farsi, and Hebrew. @node How to add fonts @@ -4418,7 +4365,8 @@ arrange for these two commands to run whenever you log in, e.g., by adding them to your window-system startup file, such as @file{~/.xsessionrc} or @file{~/.gnomerc}. -Now, add the following line to your @file{~/.emacs} init file: +Now, add the following line to your init file (@pxref{Setting up a +customization file}): @lisp (add-to-list 'bdf-directory-list "/usr/share/emacs/fonts/bdf") @@ -4428,15 +4376,15 @@ Now, add the following line to your @file{~/.emacs} init file: (Again, modify the file name if you installed the fonts elsewhere.) Finally, if you wish to use the installed fonts with @code{ps-print}, -add the following line to your @file{~/.emacs}: +add the following line to your init file: @lisp (setq ps-multibyte-buffer 'bdf-font-except-latin) @end lisp -You can now use the Emacs font menu to select the @samp{bdf: 16-dot medium} -fontset, or you can select it by setting the default font in your -@file{~/.emacs}: +You can now use the Emacs font menu to select the @samp{bdf: 16-dot +medium} fontset, or you can select it by setting the default font in +your init file: @lisp (set-frame-font "fontset-bdf") @@ -4498,9 +4446,9 @@ yourself by putting @end lisp @noindent -in your @file{.emacs} file. You can automatically include an @samp{FCC} -field by putting something like the following in your @file{.emacs} -file: +in your init file (@pxref{Setting up a customization file}). You can +automatically include an @samp{FCC} field by putting something like +the following in your init file: @lisp (setq mail-archive-file-name (expand-file-name "~/outgoing")) @@ -4532,8 +4480,7 @@ To expand them before this, use @kbd{M-x expand-mail-aliases}. Emacs normally only reads the @file{.mailrc} file once per session, when you start to compose your first mail message. If you edit the file after this, you can use @kbd{M-x build-mail-aliases} to make Emacs -reread it. Prior to Emacs 24.1, this is not an interactive command, so -you must instead type @kbd{M-: (build-mail-aliases) @key{RET}}. +reread it. @item If you like, you can expand mail aliases as abbrevs, as soon as you @@ -4631,7 +4578,7 @@ gnus @end example It is probably unwise to automatically start your mail or news reader -from your @file{.emacs} file. This would cause problems if you needed to run +from your init file. This would cause problems if you needed to run two copies of Emacs at the same time. Also, this would make it difficult for you to start Emacs quickly when you needed to. diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi index a367a83eae9..18a2b74033e 100644 --- a/doc/misc/eieio.texi +++ b/doc/misc/eieio.texi @@ -700,18 +700,18 @@ slot values, and use the previously mentioned set/ref routines. @defun slot-value object slot @anchor{slot-value} This function retrieves the value of @var{slot} from @var{object}. +It can also be used on objects defined by @code{cl-defstruct}. 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}. +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 function sets the value of @var{slot} from @var{object}. -This is not a CLOS function, but is the obsolete setter for -@code{slot-value} used by the @code{setf} macro. It is therefore +This is not a CLOS function. It is therefore recommended to use @w{@code{(setf (slot-value @var{object} @var{slot}) @var{value})}} instead. @end defun @@ -856,11 +856,12 @@ You can also create a generic method with @code{cl-defmethod} (@pxref{Methods}). When a method is created and there is no generic method in place with that name, then a new generic will be created, and the new method will use it. -@end defmac -In CLOS, a generic call also be used to provide an argument list and -dispatch precedence for all the arguments. In @eieio{}, dispatching -only occurs for the first argument, so the @var{arglist} is not used. +In CLOS, a generic method can also be used to provide an argument list +and dispatch precedence for all the arguments. In @eieio{}, +dispatching only occurs for the first argument, so the @var{arglist} +is not used. +@end defmac @node Methods @section Methods diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi index ed9cccf4899..5f4e1a639be 100644 --- a/doc/misc/emacs-mime.texi +++ b/doc/misc/emacs-mime.texi @@ -403,9 +403,9 @@ This selects the function used to render @acronym{HTML}. The predefined renderers are selected by the symbols @code{shr}, @code{gnus-w3m}, @code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more information about -emacs-w3m}, @code{links}, @code{lynx}, @code{w3m-standalone} or -@code{html2text}. You can also specify a function, which will be -called with a @acronym{MIME} handle as the argument. +emacs-w3m}, @code{links}, @code{lynx}, or @code{w3m-standalone}. You +can also specify a function, which will be called with a +@acronym{MIME} handle as the argument. @item mm-html-inhibit-images @vindex mm-html-inhibit-images @@ -454,7 +454,8 @@ setting this option to non-@code{nil}. The default value is @code{t}. @item mm-external-terminal-program @vindex mm-external-terminal-program -The program used to start an external terminal. +This should be a list of strings; typically something like +@samp{("xterm" "-e")} or @samp{("gnome-terminal" "--")}. @item mm-enable-external @vindex mm-enable-external diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index 46a465aaf4d..3db83197f9e 100644 --- a/doc/misc/erc.texi +++ b/doc/misc/erc.texi @@ -2,13 +2,15 @@ @c %**start of header @setfilename ../../info/erc.info @settitle ERC Manual +@set ERCVER 5.4.1 +@set ERCDIST as distributed with Emacs @value{EMACSVER} @include docstyle.texi @syncodeindex fn cp @include emacsver.texi @c %**end of header @copying -This manual is for ERC as distributed with Emacs @value{EMACSVER}. +This manual is for ERC @value{ERCVER} @value{ERCDIST}. Copyright @copyright{} 2005--2022 Free Software Foundation, Inc. @@ -88,7 +90,28 @@ Advanced Usage ERC is a powerful, modular, and extensible IRC client for Emacs. It is distributed with Emacs since version 22.1. -It comes with the following capabilities enabled by default. +IRC is short for Internet Relay Chat. When using IRC, you can +communicate with other users on the same IRC network. There are many +different networks---if you search for ``IRC networks'' in your +favorite search engine, you will find up-to-date lists of IRC networks +catering to various interests and topics. + +To use IRC, you need an IRC client such as ERC. Using the client, you +connect to an IRC server. Once you've done that, you will have access +to all available channels on that server's network. A channel is +basically a chat room, and what you type in a channel will be shown to +all other users in that channel. You can be in several channels at +the same time---ERC will show each channel in its own buffer. + +IRC channel names always begin with a @samp{#} character. For +example, the Emacs channel on Libera.Chat is @samp{#emacs}, and the +ERC channel is @samp{#erc}. Do not confuse them with the hashtags +used on many social media platforms. + +You can also send private messages to other IRC users on the same +network, even if they are not in the same channels as you. + +ERC comes with the following capabilities enabled by default. @itemize @bullet @item Flood control @@ -112,7 +135,11 @@ It comes with the following capabilities enabled by default. @cindex settings The command @kbd{M-x erc} will start ERC and prompt for the server to -connect to. +connect to. If you're unsure of which server or network to connect +to, we suggest starting with ``irc.libera.chat''. There you will find +the @samp{#emacs} channels where you can chat with other Emacs users, +and if you're having trouble with ERC, you can join the @samp{#erc} +channel and ask for help there. If you want to place ERC settings in their own file, you can place them in @file{~/.emacs.d/.ercrc.el}, creating it if necessary. @@ -518,20 +545,27 @@ Non-interactively, it takes the following keyword arguments. @item @var{server} @item @var{port} @item @var{nick} +@item @var{user} @item @var{password} @item @var{full-name} +@item @var{id} @end itemize -That is, if called with the following arguments, @var{server} and -@var{full-name} will be set to those values, whereas -@code{erc-compute-port} and @code{erc-compute-nick} will be invoked -for the values of the other parameters. +For example, calling the command like so -@example +@example lisp (erc :server "irc.libera.chat" :full-name "J. Random Hacker") @end example + +@noindent +sets @var{server} and @var{full-name} directly while leaving the rest +up to functions like @code{erc-compute-port}. Note that some +arguments can't be specified interactively. @var{id}, in particular, +is rarely needed (@pxref{Network Identifier}). + @end defun +@noindent To connect securely over an encrypted TLS connection, use @kbd{M-x erc-tls}. @@ -543,21 +577,25 @@ Non-interactively, it takes the following keyword arguments. @item @var{server} @item @var{port} @item @var{nick} +@item @var{user} @item @var{password} @item @var{full-name} +@item @var{id} @item @var{client-certificate} @end itemize -That is, if called with the following arguments, @var{server} and -@var{full-name} will be set to those values, whereas -@code{erc-compute-port} and @code{erc-compute-nick} will be invoked -for the values of the other parameters, and @code{client-certificate} -will be @code{nil}. +That is, if called in the following manner -@example +@example lisp (erc-tls :server "irc.libera.chat" :full-name "J. Random Hacker") @end example +@noindent +the command will set @var{server} and @var{full-name} accordingly, +while helpers, like @code{erc-compute-nick}, will determine other +parameters, and some, like @code{client-certificate}, will just be +@code{nil}. + To use a certificate with @code{erc-tls}, specify the optional @var{client-certificate} keyword argument, whose value should be as described in the documentation of @code{open-network-stream}: if @@ -692,29 +730,139 @@ ERC should automatically attempt to connect with another nickname. You can manually set another nickname with the /NICK command. @end defopt +@subheading User +@defun erc-compute-user &optional user +Determine a suitable value to send as the first argument of the +opening @samp{USER} IRC command by consulting the following sources: + +@itemize +@item +@var{user}, the argument passed to this function +@item +The option @code{erc-email-userid}, assuming @code{erc-anonymous-login} +is non-@code{nil} +@item +The result of calling the function @code{user-login-name} +@end itemize + +@end defun + +@defopt erc-email-userid +A permanent username value to send for all connections. It should be +a string abiding by the rules of the network. +@end defopt + @subheading Password @cindex password @defopt erc-prompt-for-password -If non-@code{nil} (the default), @kbd{M-x erc} prompts for a password. +If non-@code{nil} (the default), @kbd{M-x erc} and @kbd{M-x erc-tls} +prompt for a server password. This only affects interactive +invocations of @code{erc} and @code{erc-tls}. @end defopt +@noindent If you prefer, you can set this option to @code{nil} and use the @code{auth-source} mechanism to store your password. For instance, if -you use @file{~/.authinfo} as your auth-source backend, then put +the option @code{auth-sources} contains @file{~/.authinfo}, put something like the following in that file: @example -machine irc.example.net login "#fsf" password sEcReT +machine irc.example.net login mynick password sEcReT @end example @noindent -ERC also consults @code{auth-source} to find any channel keys required -for the channels that you wish to autojoin, as specified by the -variable @code{erc-autojoin-channels-alist}. +For server passwords, that is, passwords sent for the IRC @samp{PASS} +command, the @samp{host} field (@w{@code{machine irc.example.net}} in +the above example) +corresponds to the @var{server} parameter used by @code{erc} and +@code{erc-tls}. Unfortunately, specifying a network, like +@samp{Libera.Chat}, or a specific network server, like +@samp{platinum.libera.chat}, won't normally work for looking up a server +password because such information isn't available during opening +introductions. (Actually, ERC @emph{can} find entries with arbitrary +@samp{host} values for any context, including server passwords, but +that requires customizing the more advanced options below.) + +If ERC can't find a suitable server password, it will just skip the IRC +@samp{PASS} command altogether, something users may want when using +CertFP or engaging NickServ via ERC's ``services'' module. If that is +what you'd like to do, you can also customize the option +@code{erc-auth-source-server-function} to @code{nil} to skip +server-password lookup for all servers. Note that some networks and +IRCds may accept account-services authentication via server password +using the nonstandard @samp{mynick:sEcReT} convention. + +As just mentioned, you can also use @code{auth-source} to authenticate +to account services the traditional way, through a bot called +@samp{NickServ}. To tell ERC to do that, set +@code{erc-use-auth-source-for-nickserv-password} to @code{t}. For +these and most other queries, entries featuring custom identifiers and +networks are matched first, followed by network-specific servers and +dialed endpoints (typically, the @var{server} argument passed to +@code{erc}). The following netrc-style entries appear in order of +precedence: -For more details, @pxref{Top,,auth-source, auth, Emacs auth-source Library}. +@example +machine Libera/cellphone login MyNick password sEcReT +machine Libera.Chat login MyNick password sEcReT +machine zirconium.libera.chat login MyNick password sEcReT +machine irc.libera.chat login MyNick password sEcReT +@end example +@noindent +Remember that field labels vary per backend, so @samp{machine} (in +netrc's case) maps to auth-source's generalized notion of a host, +hence the @samp{:host} keyword property. Also, be sure to mind the +syntax of your chosen backend medium. For example, always quote +channel names in a netrc file. + +If this all seems overly nuanced or just plain doesn't appeal to you, +see options @code{erc-auth-source-services-function} and friends, described +below. These let you query auth-source your way. Most users can +simply ignore the passed-in arguments and get by with something like +the following: + +@lisp +(defun my-fancy-auth-source-func (&rest _) + (let* ((host (read-string "host: " nil nil "default")) + (pass (auth-source-pick-first-password :host host))) + (if (and pass (string-search "libera" host)) + (concat "MyNick:" pass) + pass))) +@end lisp + +Lastly, ERC also consults @code{auth-source} to find ``keys'' that may +be required by certain channels you join. When modifying a +traditional @code{auth-source} entry for this purpose, put the channel +name in the @samp{user} field (for example, @samp{login "#fsf"}, in +netrc's case). The actual key goes in the @samp{password} (or +@samp{secret}) field. + +@noindent +For details, @pxref{Top,,auth-source, auth, Emacs auth-source Library}. + +@defopt erc-auth-source-server-function +@end defopt +@defopt erc-auth-source-services-function +@end defopt +@defopt erc-auth-source-join-function + +ERC calls these functions with keyword arguments recognized by +@code{auth-source-search}, namely, those deemed most relevant to the +current context, if any. For example, with NickServ queries, +@code{:user} is the ``desired'' nickname rather than the current one. +Generalized names, like @code{:user} and @code{:host}, are always used +over back-end specific ones, like @code{:login} or @code{:machine}. +ERC expects a string to use as the secret or nil, if the search fails. + +@findex erc-auth-source-search +The default value for all three options is the function +@code{erc-auth-source-search}. It tries to merge relevant contextual +parameters with those provided or discovered from the logical connection +or the underlying transport. Some auth-source back ends may not be +compatible; netrc, plstore, json, and secrets are currently supported. +@end defopt @subheading Full name @@ -725,10 +873,14 @@ This tries a number of increasingly more default methods until a non-@code{nil} value is found. @itemize @bullet -@item @var{full-name} (the argument passed to this function) -@item The @code{erc-user-full-name} option -@item The value of the IRCNAME environment variable -@item The result from the @code{user-full-name} function +@item +@var{full-name} (the argument passed to this function) +@item +The @code{erc-user-full-name} option +@item +The value of the IRCNAME environment variable +@item +The result from the @code{user-full-name} function @end itemize @end defun @@ -739,6 +891,31 @@ User full name. This can be either a string or a function to call. @end defopt + +@subheading ID +@anchor{Network Identifier} + +ERC uses an abstract designation, called @dfn{network context +identifier}, for referring to a connection internally. While normally +derived from a combination of logical and physical connection +parameters, an ID can also be explicitly provided via an entry-point +command (like @code{erc-tls}). Use this in rare situations where ERC +would otherwise have trouble discerning between connections. + +One such situation might arise when using multiple connections to the +same network with the same nick but different (nonstandard) @samp{device} +identifiers, which some bouncers may support. Another might be when +mimicking the experience offered by popular standalone clients, which +normally offer ``named'' persistent configurations with server buffers +reflecting those names. Yet another use case might involve +third-party code needing to identify a connection unequivocally, but in +a human-friendly way suitable for UI components. + +When providing an ID as an entry-point argument, strings and symbols +make the most sense, but any reasonably printable object is +acceptable. + + @node Sample Configuration @section Sample Configuration @cindex configuration, sample @@ -800,12 +977,6 @@ stuff, to the current ERC buffer." (setq erc-autojoin-channels-alist '(("Libera.Chat" "#emacs" "#erc"))) -;; Rename server buffers to reflect the current network name instead -;; of SERVER:PORT (e.g., "Libera.Chat" instead of -;; "irc.libera.chat:6667"). This is useful when using a bouncer like -;; ZNC where you have multiple connections to the same server. -(setq erc-rename-buffers t) - ;; Interpret mIRC-style color commands in IRC chats (setq erc-interpret-mirc-color t) @@ -864,15 +1035,6 @@ lurkers. The function @code{erc-lurker-p} determines whether a given nickname is considered a lurker. @end defopt -@defopt erc-rename-buffers -If non, @code{nil}, this will rename server buffers to reflect the -current network name instead of IP:PORT - -@example -(setq erc-rename-buffers t) -@end example -@end defopt - @node Getting Help and Reporting Bugs @chapter Getting Help and Reporting Bugs @cindex help, getting @@ -897,7 +1059,7 @@ contributors are frequently around and willing to answer your questions. @item -To report a bug in ERC, use @kbd{M-x report-emacs-bug}. +To report a bug in ERC, use @kbd{M-x erc-bug}. @end itemize diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi index aeae6aef8c7..1b7f38daadf 100644 --- a/doc/misc/ert.texi +++ b/doc/misc/ert.texi @@ -109,6 +109,7 @@ Appendix @end menu @end ifnottex + @node Introduction @chapter Introduction @cindex introduction to ERT @@ -123,7 +124,7 @@ commands to run them to verify whether the definitions that are currently loaded in Emacs pass the tests. Some Lisp files have comments like the following (adapted from the -package @code{pp.el}): +package @file{pp.el}): @lisp ;; (pp-to-string '(quote quote)) ; expected: "'quote" @@ -320,7 +321,7 @@ Show the list of @code{should} forms executed in the test @kindex m@r{, in ert results buffer} @findex ert-results-pop-to-messages-for-test-at-point Show any messages that were generated (with the Lisp function -@code{message}) in in a test or any of the code that it invoked +@code{message}) in a test or any of the code that it invoked (@code{ert-results-pop-to-messages-for-test-at-point}). @item L @@ -358,6 +359,7 @@ Prompt for a test and then show its documentation. @end table + @node Running Tests in Batch Mode @section Running Tests in Batch Mode @cindex running tests in batch mode @@ -375,7 +377,7 @@ emacs -batch -l ert -l my-tests.el -f ert-run-tests-batch-and-exit @end example This command will start up Emacs in batch mode, load ERT, load -@code{my-tests.el}, and run all tests defined in it. It will exit +@file{my-tests.el}, and run all tests defined in it. It will exit with a zero exit status if all tests passed, or nonzero if any tests failed or if anything else went wrong. It will also print progress messages and error diagnostics to standard output. @@ -390,12 +392,37 @@ summary as shown below: emacs -batch -l ert -f ert-summarize-tests-batch-and-exit output.log @end example +@vindex ert-batch-print-level +@vindex ert-batch-print-length +ERT attempts to limit the output size for failed tests by choosing +conservative values for @code{print-level} and @code{print-length} +when printing Lisp values. This can in some cases make it difficult +to see which portions of those values are incorrect. Use +@code{ert-batch-print-level} and @code{ert-batch-print-length} +to customize that: + +@example +emacs -batch -l ert -l my-tests.el \ + --eval "(let ((ert-batch-print-level 10) \ + (ert-batch-print-length 120)) \ + (ert-run-tests-batch-and-exit))" +@end example + +@vindex ert-batch-backtrace-line-length +Even modest settings for @code{print-level} and @code{print-length} can +produce extremely long lines in backtraces, however, with attendant +pauses in execution progress. Set +@code{ert-batch-backtrace-line-length} to t to use the value of +@code{backtrace-line-length}, @code{nil} to stop any limitations on backtrace +line lengths (that is, to get full backtraces), or a positive integer to +limit backtrace line length to that number. + @vindex ert-quiet By default, ERT in batch mode is quite verbose, printing a line with result after each test. This gives you progress information: how many tests have been executed and how many there are. However, in some cases this much output may be undesirable. In this case, set -@code{ert-quiet} variable to a non-nil value: +@code{ert-quiet} variable to a non-@code{nil} value: @example emacs -batch -l ert -l my-tests.el \ @@ -414,10 +441,22 @@ emacs -batch -l ert -l my-tests.el \ -eval '(ert-run-tests-batch-and-exit "to-match")' @end example +@vindex EMACS_TEST_VERBOSE@r{, environment variable} By default, ERT test failure summaries are quite brief in batch mode---only the names of the failed tests are listed. If the -EMACS_TEST_VERBOSE environment variable is set, the failure summaries -will also include the data from the failing test. +@env{EMACS_TEST_VERBOSE} environment variable is set and is non-empty, +the failure summaries will also include the data from the failing +test. + +@vindex EMACS_TEST_JUNIT_REPORT@r{, environment variable} +ERT can produce JUnit test reports in batch mode. If the environment +variable @env{EMACS_TEST_JUNIT_REPORT} is set, ERT will produce for +every test package @file{my-tests.el} a corresponding JUnit test +report @file{my-tests.xml}. The function +@code{ert-summarize-tests-batch-and-exit} collects all these package +test reports into a new JUnit test report, with the respective name of +that environment variable. + @node Test Selectors @section Test Selectors @@ -486,8 +525,10 @@ to find where a test was defined if the test was loaded from a file. * Expected Failures:: Tests for known bugs. * Tests and Their Environment:: Don't depend on customizations; no side effects. * Useful Techniques:: Some examples. +* erts files:: Files containing many buffer tests. @end menu + @node The @code{should} Macro @section The @code{should} Macro @@ -768,6 +809,121 @@ for testing. Usually, this makes the interfaces easier to use as well. +@node erts files +@section erts files + +@findex ert-test-erts-file +Many relevant Emacs tests depend on comparing the contents of a buffer +before and after executing a particular function. These tests can be +written the normal way---making a temporary buffer, inserting the +``before'' text, running the function, and then comparing with the +expected ``after'' text. However, this often leads to test code +that's pretty difficult to read and write, especially when the text in +question is multi-line. + +So ert provides a function called @code{ert-test-erts-file} that takes +two parameters: the name of a specially-formatted @dfn{erts} file, and +(optionally) a function that performs the transform. + +@findex erts-mode +These erts files can be edited with the @code{erts-mode} major mode. + +An erts file is divided into sections by the (@samp{=-=}) separator. + +Here's an example file containing two tests: + +@example +Name: flet + +=-= +(cl-flet ((bla (x) +(* x x))) +(bla 42)) +=-= +(cl-flet ((bla (x) + (* x x))) + (bla 42)) +=-=-= + +Name: defun + +=-= +(defun x () + (print (quote ( thingy great + stuff)))) +=-=-= +@end example + +A test starts with a line containing just @samp{=-=} and ends with a +line containing just @samp{=-=-=}. The test may be preceded by +freeform text (for instance, comments), and also name/value pairs (see +below for a list of them). + +If there is a line with @samp{=-=} inside the test, that designates +the start of the ``after'' text. Otherwise, the ``before'' and +``after'' texts are assumed to be identical, which you typically see +when writing indentation tests. + +@code{ert-test-erts-file} puts the ``before'' section into a temporary +buffer, calls the transform function, and then compares with the +``after'' section. + +Here's an example usage: + +@lisp +(ert-test-erts-file "elisp.erts" + (lambda () + (emacs-lisp-mode) + (indent-region (point-min) (point-max)))) +@end lisp + +A list of the name/value specifications that can appear before a test +follows. The general syntax is @samp{Name: Value}, but continuation +lines can be used (along the same lines as in mail---subsequent lines +that start with a space are part of the value). + +@example +Name: foo +Code: (indent-region + (point-min) (point-max)) +@end example + +@table @samp +@item Name +All tests should have a name. This name will appear in ERT output if +the test fails, and helps to identify the failing test. + +@item Code +This is the code that will be run to do the transform. This can also +be passed in via the @code{ert-test-erts-file} call, but @samp{Code} +overrides that. It's used not only in the following test, but in all +subsequent tests in the file (until overridden by another @samp{Code} +specification). + +@item No-Before-Newline +@itemx No-After-Newline +These specifications say whether the ``before'' or ``after'' portions +have a newline at the end. (This would otherwise be impossible to +specify.) + +@item Point-Char +Sometimes it's useful to be able to put point at a specific place +before executing the transform function. @samp{Point-Char: |} will +make @code{ert-test-erts-file} place point where @samp{|} is in the +``before'' form (and remove that character), and will check that it's +where the @samp{|} character is in the ``after'' form (and issue a +test failure if that isn't the case). (This is used in all subsequent +tests, unless overridden by a new @samp{Point-Char} spec.) + +@item Skip +If this is present and value is a form that evaluates to a +non-@code{nil} value, the test will be skipped. +@end table + +If you need to use the literal line single line @samp{=-=} in a test +section, you can quote it with a @samp{\} character. + + @node How to Debug Tests @chapter How to Debug Tests @@ -969,6 +1125,7 @@ For information on mocks, stubs, fixtures, or test suites, see below. * Fixtures and Test Suites:: How ERT differs from tools for other languages. @end menu + @node Mocks and Stubs @section Other Tools for Emacs Lisp @cindex mocks and stubs @@ -1043,11 +1200,13 @@ e.g., to run quick tests during interactive development and slow tests less often. This can be achieved with the @code{:tag} argument to @code{ert-deftest} and @code{tag} test selectors. + @node Index @unnumbered Index @printindex cp + @node GNU Free Documentation License @appendix GNU Free Documentation License @include doclicense.texi diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index f01023a1dca..13f13163dd7 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -201,7 +201,7 @@ history and invoking commands in a script file. * Aliases:: * History:: * Completion:: -* for loop:: +* Control Flow:: * Scripts:: @end menu @@ -219,24 +219,54 @@ same name; if there is no match, it then tries to execute it as an external command. The semicolon (@code{;}) can be used to separate multiple command -invocations on a single line. A command invocation followed by an -ampersand (@code{&}) will be run in the background. Eshell has no job -control, so you can not suspend or background the current process, or -bring a background process into the foreground. That said, background -processes invoked from Eshell can be controlled the same way as any -other background process in Emacs. +invocations on a single line. You can also separate commands with +@code{&&} or @code{||}. When using @code{&&}, Eshell will execute the +second command only if the first succeeds (i.e.@: has an exit +status of 0); with @code{||}, Eshell will execute the second command +only if the first fails. + +A command invocation followed by an ampersand (@code{&}) will be run +in the background. Eshell has no job control, so you can not suspend +or background the current process, or bring a background process into +the foreground. That said, background processes invoked from Eshell +can be controlled the same way as any other background process in +Emacs. @node Arguments @section Arguments -Command arguments are passed to the functions as either strings or -numbers, depending on what the parser thinks they look like. If you -need to use a function that takes some other data type, you will need to -call it in an Elisp expression (which can also be used with -@ref{Expansion, expansions}). As with other shells, you can -escape special characters and spaces with the backslash (@code{\}) and -apostrophes (@code{''}) and double quotes (@code{""}). This is needed -especially for file names with special characters like pipe -(@code{|}), which could be part of remote file names. +Ordinarily, command arguments are parsed by Eshell as either strings +or numbers, depending on what the parser thinks they look like. To +specify an argument of some other data type, you can use an +@ref{Dollars Expansion, Elisp expression}: + +@example +~ $ echo (list 1 2 3) +(1 2 3) +@end example + +Additionally, many built-in Eshell commands (@pxref{Built-ins, Eshell +commands}) will flatten the arguments they receive, so passing a list +as an argument will ``spread'' the elements into multiple arguments: + +@example +~ $ printnl (list 1 2) 3 +1 +2 +3 +@end example + +@subsection Quoting and escaping + +As with other shells, you can escape special characters and spaces +with by prefixing the character with a backslash (@code{\}), or by +surrounding the string with apostrophes (@code{''}) or double quotes +(@code{""}). This is needed especially for file names with special +characters like pipe (@code{|}), which could be part of remote file +names. + +When using expansions (@pxref{Expansion}) in an Eshell command, the +result may potentially be of any data type. To ensure that the result +is always a string, the expansion can be surrounded by double quotes. @node Built-ins @section Built-in commands @@ -271,8 +301,30 @@ Some of the built-in commands have different behavior from their external counterparts, and some have no external counterpart. Most of these will print a usage message when given the @code{--help} option. +In some cases, a built-in command's behavior can be configured via +user settings, some of which are mentioned below. For example, +certain commands have two user settings to allow them to overwrite +files without warning and to ensure that they always prompt before +overwriting files. If both settings are non-@code{nil}, the commands +always prompt. If both settings are @code{nil} (the default), the +commands signal an error. + +Several commands observe the value of +@code{eshell-default-target-is-dot}. If non-@code{nil}, then the +default target for the commands @command{cp}, @command{mv}, and +@command{ln} is the current directory. + +A few commands are wrappers for more niche Emacs features, and can be +loaded as part of the eshell-xtra module. @xref{Extension modules}. + @table @code +@item . +@cmindex . +Source an Eshell file in the current environment. This is not to be +confused with the command @command{source}, which sources a file in a +subshell environment. + @item addpath @cmindex addpath Adds a given path or set of paths to the PATH environment variable, or, @@ -282,26 +334,144 @@ with no arguments, prints the current paths in this variable. @cmindex alias Define an alias (@pxref{Aliases}). This adds it to the aliases file. +@item basename +@cmindex basename +Return a file name without its directory. + +@item cat +@cmindex cat +Concatenate file contents into standard output. If in a pipeline, or +if the file is not a regular file, directory, or symlink, then this +command reverts to the system's definition of @command{cat}. + +@item cd +@cmindex cd +This command changes the current working directory. Usually, it is +invoked as @kbd{cd @var{dir}} where @file{@var{dir}} is the new +working directory. But @command{cd} knows about a few special +arguments: + +@itemize @minus{} +@item +When it receives no argument at all, it changes to the home directory. + +@item +Giving the command @kbd{cd -} changes back to the previous working +directory (this is the same as @kbd{cd $-}). + +@item +The command @kbd{cd =} shows the directory ring. Each line is +numbered. + +@item +With @kbd{cd =foo}, Eshell searches the directory ring for a directory +matching the regular expression @samp{foo}, and changes to that +directory. + +@item +With @kbd{cd -42}, you can access the directory stack slots by number. + +@item +If @code{eshell-cd-shows-directory} is non-@code{nil}, @command{cd} +will report the directory it changes to. If +@code{eshell-list-files-after-cd} is non-@code{nil}, then @command{ls} +is called with any remaining arguments after changing directories. +@end itemize + @item clear @cmindex clear -Scrolls the contents of the eshell window out of sight, leaving a blank window. -If provided with an optional non-nil argument, the scrollback contents are -cleared instead. +Scrolls the contents of the Eshell window out of sight, leaving a +blank window. If provided with an optional non-@code{nil} argument, +the scrollback contents are cleared instead. + +@item clear-scrollback +@cmindex clear-scrollback +Clear the scrollback contents of the Eshell window. Unlike the +command @command{clear}, this command deletes content in the Eshell +buffer. + +@item cp +@cmindex cp +Copy a file to a new location or copy multiple files to the same +directory. + +If @code{eshell-cp-overwrite-files} is non-@code{nil}, then +@command{cp} will overwrite files without warning. If +@code{eshell-cp-interactive-query} is non-@code{nil}, then +@command{cp} will ask before overwriting anything. @item date @cmindex date -Similar to, but slightly different from, the GNU Coreutils +Print the current local time as a human-readable string. This command +is similar to, but slightly different from, the GNU Coreutils @command{date} command. @item define @cmindex define -Define a varalias. +Define a variable alias. @xref{Variable Aliases, , , elisp, The Emacs Lisp Reference Manual}. @item diff @cmindex diff -Use Emacs's internal @code{diff} (not to be confused with -@code{ediff}). @xref{Comparing Files, , , emacs, The GNU Emacs Manual}. +Compare files using Emacs's internal @code{diff} (not to be confused +with @code{ediff}). @xref{Comparing Files, , , emacs, The GNU Emacs +Manual}. + +If @code{eshell-plain-diff-behavior} is non-@code{nil}, then this +command does not use Emacs's internal @code{diff}. This is the same +as using @samp{alias diff '*diff $*'}. + +@item dirname +@cmindex dirname +Return the directory component of a file name. + +@item dirs +@cmindex dirs +Prints the directory stack. Directories can be added or removed from +the stack using the commands @command{pushd} and @command{popd}, +respectively. + +@item du +@cmindex du +Summarize disk usage for each file. + +@item echo +@cmindex echo +Echoes its input. By default, this prints in a Lisp-friendly fashion +(so that the value is useful to a Lisp command using the result of +@command{echo} as an argument). If a single argument is passed, +@command{echo} prints that; if multiple arguments are passed, it +prints a list of all the arguments; otherwise, it prints the empty +string. + +If @code{eshell-plain-echo-behavior} is non-@code{nil}, @command{echo} +will try to behave more like a plain shell's @command{echo}, printing +each argument as a string, separated by a space. + +@item env +@cmindex env +Prints the current environment variables. Unlike in Bash, this +command does not yet support running commands with a modified +environment. + +@item exit +@cmindex exit +Exit Eshell and save the history. By default, this command kills the +Eshell buffer, but if @code{eshell-kill-on-exit} is @code{nil}, then +the buffer is merely buried instead. + +@item export +@cmindex export +Set environment variables using input like Bash's @command{export}, as +in @samp{export @var{var1}=@var{val1} @var{var2}=@var{val2} @dots{}}. + +@item expr +@cmindex expr +An implementation of @command{expr} using the Calc package. +@xref{Top,,, calc, The GNU Emacs Calculator}. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. @item grep @cmindex grep @@ -313,13 +483,36 @@ Use Emacs's internal @code{diff} (not to be confused with @cmindex fgrep @itemx glimpse @cmindex glimpse -The @command{grep} commands are compatible with GNU @command{grep}, but -use Emacs's internal @code{grep} instead. +The @command{grep} commands are compatible with GNU @command{grep}, +but use Emacs's internal @code{grep} instead. +@xref{Grep Searching, , , emacs, The GNU Emacs Manual}. + +If @code{eshell-plain-grep-behavior} is non-@code{nil}, then these +commands do not use Emacs's internal @code{grep}. This is the same as +using @samp{alias grep '*grep $*'}, though this setting applies to all +of the built-in commands for which you would need to create a separate +alias. + +@item history +@cmindex history +Prints Eshell's input history. With a numeric argument @var{N}, this +command prints the @var{N} most recent items in the history. @item info @cmindex info -Same as the external @command{info} command, but uses Emacs's internal -Info reader. +Browse the available Info documentation. This command is the same as +the external @command{info} command, but uses Emacs's internal Info +reader. +@xref{Misc Help, , , emacs, The GNU Emacs Manual}. + +@item intersection +@cmindex intersection +A wrapper around the function @code{cl-intersection} (@pxref{Lists as +Sets,,, cl, GNU Emacs Common Lisp Emulation}). This command +can be used for comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. @item jobs @cmindex jobs @@ -337,46 +530,152 @@ Eshell version of @code{list}. Allows you to create a list using Eshell syntax, rather than Elisp syntax. For example, @samp{listify foo bar} and @code{("foo" "bar")} both evaluate to @code{("foo" "bar")}. +@item ln +@cmindex ln +Create links to files. + +If @code{eshell-ln-overwrite-files} is non-@code{nil}, @command{ln} +will overwrite files without warning. If +@code{eshell-ln-interactive-query} is non-@code{nil}, then +@command{ln} will ask before overwriting files. + @item locate @cmindex locate Alias to Emacs's @code{locate} function, which simply runs the external @command{locate} command and parses the results. @xref{Dired and Find, , , emacs, The GNU Emacs Manual}. +If @code{eshell-plain-locate-behavior} is non-@code{nil}, then Emacs's +internal @code{locate} is not used. This is the same as using +@samp{alias locate '*locate $*'}. + +@item ls +@cmindex ls +Lists the contents of directories. + +If @code{eshell-ls-use-colors} is non-@code{nil}, the contents of a +directory is color-coded according to file type and status. These +colors and the regexps used to identify their corresponding files can +be customized via @w{@kbd{M-x customize-group @key{RET} eshell-ls @key{RET}}}. + +The user option @code{eshell-ls-date-format} determines how the date +is displayed when using the @option{-l} option. The date is produced +using the function @code{format-time-string} (@pxref{Time Parsing,,, +elisp, GNU Emacs Lisp Reference Manual}). + +The user option @code{eshell-ls-initial-args} contains a list of +arguments to include with any call to @command{ls}. For example, you +can include the option @option{-h} to always use a more human-readable +format. + +The user option @code{eshell-ls-default-blocksize} determines the +default blocksize used when displaying file sizes with the option +@option{-s}. + @item make @cmindex make Run @command{make} through @code{compile} when run asynchronously (e.g., @samp{make &}). @xref{Compilation, , , emacs, The GNU Emacs Manual}. Otherwise call the external @command{make} command. +@item man +@cmindex man +Display Man pages using the Emacs @code{man} command. +@xref{Man Page, , , emacs, The GNU Emacs Manual}. + +@item mismatch +@cmindex mismatch +A wrapper around the function @code{cl-mismatch} (@pxref{Searching +Sequences,,, cl, GNU Emacs Common Lisp Emulation}). This command can +be used for comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. + +@item mkdir +@cmindex mkdir +Make new directories. + +@item mv +@cmindex mv +Move or rename files. + +If @code{eshell-mv-overwrite-files} is non-@code{nil}, @command{mv} +will overwrite files without warning. If +@code{eshell-mv-interactive-query} is non-@code{nil}, @command{mv} +will prompt before overwriting anything. + @item occur @cmindex occur Alias to Emacs's @code{occur}. @xref{Other Repeating Search, , , emacs, The GNU Emacs Manual}. +@item popd +@cmindex popd +Pop a directory from the directory stack and switch to a another place +in the stack. + @item printnl @cmindex printnl Print the arguments separated by newlines. -@item cd -@cmindex cd -This command changes the current working directory. Usually, it is -invoked as @samp{cd foo} where @file{foo} is the new working directory. -But @command{cd} knows about a few special arguments: - -When it receives no argument at all, it changes to the home directory. - -Giving the command @samp{cd -} changes back to the previous working -directory (this is the same as @samp{cd $-}). - -The command @samp{cd =} shows the directory stack. Each line is -numbered. - -With @samp{cd =foo}, Eshell searches the directory stack for a directory -matching the regular expression @samp{foo} and changes to that -directory. - -With @samp{cd -42}, you can access the directory stack by number. +@item pushd +@cmindex pushd +Push the current directory onto the directory stack, then change to +another directory. + +If @code{eshell-pushd-dunique} is non-@code{nil}, then only unique +directories will be added to the stack. If +@code{eshell-pushd-dextract} is non-@code{nil}, then @samp{pushd ++@var{n}} will pop the @var{n}th directory to the top of the stack. + +@item pwd +@cmindex pwd +Prints the current working directory. + +@item rm +@cmindex rm +Removes files, buffers, processes, or Emacs Lisp symbols, depending on +the argument. + +If @code{eshell-rm-interactive-query} is non-@code{nil}, @command{rm} +will prompt before removing anything. If +@code{eshell-rm-removes-directories} is non-@code{nil}, then +@command{rm} can also remove directories. Otherwise, @command{rmdir} +is required. + +@item rmdir +@cmindex rmdir +Removes directories if they are empty. + +@item set-difference +@cmindex set-difference +A wrapper around the function @code{cl-set-difference} (@pxref{Lists as +Sets,,, cl, GNU Emacs Common Lisp Emulation}). This command +can be used for comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. + +@item set-exclusive-or +@cmindex set-exclusive-or +A wrapper around the function @code{cl-set-exclusive-or} (@pxref{Lists +as Sets,,, cl, GNU Emacs Common Lisp Emulation}). This command can be +used for comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. + +@item setq +@cmindex setq +Set variable values, using the function @code{setq} like a command. +@xref{Setting Variables,,, elisp, GNU Emacs Lisp Reference Manual}. + +@item source +@cmindex source +Source an Eshell file in a subshell environment. This is not to be +confused with the command @command{.}, which sources a file in the +current environment. @item su @cmindex su @@ -386,48 +685,243 @@ Uses TRAMP's @command{su} or @command{sudo} method @pxref{Inline methods, , , tr to run a command via @command{su} or @command{sudo}. These commands are in the eshell-tramp module, which is disabled by default. + +@item substitute +@cmindex substitute +A wrapper around the function @code{cl-substitute} (@pxref{Sequence +Functions,,, cl, GNU Emacs Common Lisp Emulation}). This command can +be used for comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. + +@item time +@cmindex time +Show the time elapsed during a command's execution. + +@item umask +@cmindex umask +Set or view the default file permissions for newly created files and +directories. + +@item union +@cmindex union +A wrapper around the function @code{cl-union} (@pxref{Lists as Sets,,, +cl, GNU Emacs Common Lisp Emulation}). This command can be used for +comparing lists of strings. + +This command can be loaded as part of the eshell-xtra module, which is +disabled by default. + +@item unset +@cmindex unset +Unset an environment variable. + +@item wait +@cmindex wait +Wait until a process has successfully completed. + +@item which +@cmindex which +Identify a command and its location. + +@item whoami +@cmindex whoami +Print the current user. This Eshell version of @command{whoami} +supports Tramp. @end table +@subsection Defining new built-in commands +While Eshell can run Lisp functions directly as commands, it may be +more convenient to provide a special built-in command for +Eshell. Built-in commands are just ordinary Lisp functions designed +to be called from Eshell. When defining an Eshell-specific version of +an existing function, you can give that function a name starting with +@code{eshell/} so that Eshell knows to use it. + +@defmac eshell-eval-using-options name macro-args options body@dots{} +This macro processes a list of @var{macro-args} for the command +@var{name} using a set of command line @var{options}. If the +arguments are parsed successfully, it will store the resulting values +in local symbols and execute @var{body}; any remaining arguments will +be available in the locally let-bound variable @code{args}. The +return value is the value of the last form in @var{body}. + +If an unknown option was passed in @var{macro-args} and an external +command was specified (see below), this macro will start a process for +that command and throw the tag @code{eshell-external} with the new +process as its value. + +@var{options} should be a list beginning with one or more elements of +the following form, with each element representing a particular +command-line switch: + +@example +(@var{short} @var{long} @var{value} @var{symbol} @var{help-string}) +@end example + +@table @var +@item short +This element, if non-nil, should be a character to be used as a short +switch, like @code{-@var{short}}. At least one of this element and +@var{long} must be non-nil. + +@item long +This element, if non-nil, should be a string to be used as a long +switch, like @code{--@var{long}}. + +@item value +This element is the value associated with the option. It can be +either: + +@table @asis +@item @code{t} +The option needs a value to be specified after the switch. + +@item @code{nil} +The option is given the value @code{t}. + +@item anything else +The option is given the specified value. +@end table + +@item symbol +This element is the Lisp symbol that will be bound to @var{value}. If +@var{symbol} is @code{nil}, specifying this switch will instead call +@code{eshell-show-usage}, and so is appropriate for an option like +@code{--help}. + +@item help-string +This element is a documentation string for the option, which will be +displayed when @code{eshell-show-usage} is invoked. +@end table + +After the list of command-line switch elements, @var{options} can +include additional keyword arguments to control how +@code{eshell-eval-using-options} behaves. Some of these take +arguments, while others don't. The recognized keywords are: + +@table @code +@item :external @var{string} +Specify @var{string} as an external command to run if there are +unknown switches in @var{macro-args}. + +@item :usage @var{string} +Set @var{string} as the initial part of the command's documentation +string. It appears before the options are listed. + +@item :post-usage @var{string} +Set @var{string} to be the (optional) trailing part of the command's +documentation string. It appears after the list of options, but +before the final part of the documentation about the associated +external command, if there is one. + +@item :show-usage +If present, then show the usage message if the command is called with +no arguments. + +@item :preserve-args +Normally, @code{eshell-eval-using-options} flattens the list of +arguments in @var{macro-args} and converts each to a string. If this +keyword is present, avoid doing that, instead preserving the original +arguments. This is useful for commands which want to accept arbitrary +Lisp objects. + +@item :parse-leading-options-only +If present, do not parse dash or switch arguments after the first +positional argument. Instead, treat them as positional arguments +themselves. +@end table + +For example, you could handle a subset of the options for the +@code{ls} command like this: + +@example +(eshell-eval-using-options + "ls" macro-args + '((?a nil nil show-all "show all files") + (?I "ignore" t ignore-pattern "ignore files matching pattern") + (nil "help" nil nil "show this help message") + :external "ls" + :usage "[OPTION]... [FILE]... + List information about FILEs (the current directory by default).") + ;; List the files in ARGS somehow... + ) +@end example + +@end defmac + +@node Variables +@section Variables +Since Eshell is just an Emacs @acronym{REPL}@footnote{ +Short for ``Read-Eval-Print Loop''. +} +, it does not have its own scope, and simply stores variables the same +you would in an Elisp program. Eshell provides a command version of +@code{setq} for convenience. + @subsection Built-in variables Eshell knows a few built-in variables: @table @code -@item $+ +@vindex $PWD @vindex $+ +@item $PWD +@itemx $+ This variable always contains the current working directory. -@item $- +@vindex $OLDPWD @vindex $- +@item $OLDPWD +@itemx $- This variable always contains the previous working directory (the current working directory from before the last @code{cd} command). +When using @code{$-}, you can also access older directories in the +directory ring via subscripting, e.g.@: @samp{$-[1]} refers to the +working directory @emph{before} the previous one. -@item $_ @vindex $_ -It refers to the last argument of the last command. +@item $_ +This refers to the last argument of the last command. With a +subscript, you can access any argument of the last command. For +example, @samp{$_[1]} refers to the second argument of the last +command (excluding the command name itself). -@item $$ @vindex $$ -This is the result of the last command. In case of an external -command, it is @code{t} or @code{nil}. +@item $$ +This is the result of the last command. For external commands, it is +@code{t} if the exit code was 0 or @code{nil} otherwise. -@item $? +@vindex eshell-lisp-form-nil-is-failure @vindex $? -This variable contains the exit code of the last command (0 or 1 for -Lisp functions, based on successful completion). +@item $? +This variable contains the exit code of the last command. If the last +command was a Lisp function, it is 0 for successful completion or 1 +otherwise. If @code{eshell-lisp-form-nil-is-failure} is +non-@code{nil}, then a command with a Lisp form, like +@samp{(@var{command} @var{args}@dots{})}, that returns @code{nil} will +set this variable to 2. + +@vindex $COLUMNS +@vindex $LINES +@item $COLUMNS +@itemx $LINES +These variables tell the number of columns and lines, respectively, +that are currently visible in the Eshell window. They are both +copied to the environment, so external commands invoked from +Eshell can consult them to do the right thing. + +@item $INSIDE_EMACS +This variable indicates to external commands that they are being +invoked from within Emacs so they can adjust their behavior if +necessary. Its value is @code{@var{emacs-version},eshell}. @end table @xref{Aliases}, for the built-in variables @samp{$*}, @samp{$1}, @samp{$2}, @dots{}, in alias definitions. -@node Variables -@section Variables -Since Eshell is just an Emacs REPL@footnote{Read-Eval-Print Loop}, it -does not have its own scope, and simply stores variables the same you -would in an Elisp program. Eshell provides a command version of -@code{setq} for convenience. - @node Aliases @section Aliases @@ -524,19 +1018,46 @@ command for which this function provides completions; you can also name the function @code{pcomplete/MAJOR-MODE/COMMAND} to define completions for a specific major mode. -@node for loop -@section @code{for} loop +@node Control Flow +@section Control Flow Because Eshell commands can not (easily) be combined with lisp forms, -Eshell provides a command-oriented @command{for}-loop for convenience. -The syntax is as follows: +Eshell provides command-oriented control flow statements for +convenience. -@example -@code{for VAR in TOKENS @{ command invocation(s) @}} -@end example +Most of Eshell's control flow statements accept a @var{conditional}. +This can take a few different forms. If @var{conditional} is a dollar +expansion, the condition is satisfied if the result is a +non-@code{nil} value. If @var{conditional} is a @samp{@{ +@var{subcommand} @}} or @samp{(@var{lisp form})}, the condition is +satisfied if the command's exit status is 0. -where @samp{TOKENS} is a space-separated sequence of values of -@var{VAR} for each iteration. This can even be the output of a -command if @samp{TOKENS} is replaced with @samp{@{ command invocation @}}. +@table @code + +@item if @var{conditional} @{ @var{true-commands} @} +@itemx if @var{conditional} @{ @var{true-commands} @} @{ @var{false-commands} @} +Evaluate @var{true-commands} if @var{conditional} is satisfied; +otherwise, evaluate @var{false-commands}. + +@item unless @var{conditional} @{ @var{false-commands} @} +@itemx unless @var{conditional} @{ @var{false-commands} @} @{ @var{true-commands} @} +Evaluate @var{false-commands} if @var{conditional} is not satisfied; +otherwise, evaluate @var{true-commands}. + +@item while @var{conditional} @{ @var{commands} @} +Repeatedly evaluate @var{commands} so long as @var{conditional} is +satisfied. + +@item until @var{conditional} @{ @var{commands} @} +Repeatedly evaluate @var{commands} until @var{conditional} is +satisfied. + +@item for @var{var} in @var{list}@dots{} @{ @var{commands} @} +Iterate over each element of of @var{list}, storing the element in +@var{var} and evaluating @var{commands}. If @var{list} is not a list, +treat it as a list of one element. If you specify multiple +@var{lists}, this will iterate over each of them in turn. + +@end table @node Scripts @section Scripts @@ -560,15 +1081,42 @@ parsers (such as @command{cpp} and @command{m4}), but in a command shell, they are less often used for constants, and usually for using variables and string manipulation.@footnote{Eshell has no string-manipulation expansions because the Elisp library already -provides many functions for this.} For example, @code{$var} on a line -expands to the value of the variable @code{var} when the line is +provides many functions for this.} For example, @code{$@var{var}} on +a line expands to the value of the variable @var{var} when the line is executed. Expansions are usually passed as arguments, but may also be -used as commands.@footnote{E.g., entering just @samp{$var} at the prompt -is equivalent to entering the value of @code{var} at the prompt.} +used as commands.@footnote{E.g., entering just @samp{$@var{var}} at +the prompt is equivalent to entering the value of @var{var} at the +prompt.} + +You can concatenate expansions with regular string arguments or even +other expansions. In the simplest case, when the expansion returns a +string value, this is equivalent to ordinary string concatenation; for +example, @samp{$@{echo "foo"@}bar} returns @samp{foobar}. The exact +behavior depends on the types of each value being concatenated: + +@table @asis + +@item both strings +Concatenate both values together. + +@item one or both numbers +Concatenate the string representation of each value, converting back to +a number if possible. + +@item one or both (non-@code{nil}) lists +Concatenate ``adjacent'' elements of each value (possibly converting +back to a number as above). For example, @samp{$list("a" "b")c} +returns @samp{("a" "bc")}. + +@item anything else +Concatenate the string representation of each value. + +@end table @menu * Dollars Expansion:: * Globbing:: +* Argument Predication and Modification:: @end menu @node Dollars Expansion @@ -589,67 +1137,423 @@ Expands to the value bound to @var{var}. This is useful to disambiguate the variable name when concatenating it with another value, such as @samp{$"@var{var}"-suffix}. -@item $#@var{var} -Expands to the length of the value bound to @var{var}. Raises an error -if the value is not a sequence -(@pxref{Sequences Arrays Vectors, Sequences, , elisp, The Emacs Lisp Reference Manual}). - @item $(@var{lisp}) Expands to the result of evaluating the S-expression @code{(@var{lisp})}. On its own, this is identical to just @code{(@var{lisp})}, but with the @code{$}, -it can be used in a string, such as @samp{/some/path/$(@var{lisp}).txt}. +it can be used inside double quotes or within a longer string, such as +@samp{/some/path/$(@var{lisp}).txt}. @item $@{@var{command}@} -Returns the output of @command{@var{command}}, which can be any valid Eshell -command invocation, and may even contain expansions. +Returns the output of @command{@var{command}}, which can be any valid +Eshell command invocation, and may even contain expansions. Similar +to @code{$(@var{lisp})}, this is identical to @code{@{@var{command}@}} +when on its own, but the @code{$} allows it to be used inside double +quotes or as part of a string. + +Normally, the output is split line-by-line, returning a list (or the +first element if there's only one line of output); if +@code{eshell-convert-numeric-arguments} is non-@code{nil} and every +line of output looks like a number, convert each line to a number. +However, when this expansion is surrounded by double quotes, it +returns the output as a single string instead. @item $<@var{command}> As with @samp{$@{@var{command}@}}, evaluates the Eshell command invocation @command{@var{command}}, but writes the output to a temporary file and returns the file name. -@item $@var{var}[i] -Expands to the @code{i}th element of the value bound to @var{var}. If -the value is a string, it will be split at whitespace to make it a list. -Again, raises an error if the value is not a sequence. +@item $@var{expr}[@var{i...}] +Expands to the @var{i}th element of the result of @var{expr}, an +expression in one of the above forms listed here. If multiple indices +are supplied, this will return a list containing the elements for each +index. The exact behavior depends on the type of @var{expr}'s value: + +@table @asis + +@item a sequence +Expands to the element at the (zero-based) index @var{i} of the +sequence (@pxref{Sequences Arrays Vectors, Sequences, , elisp, The +Emacs Lisp Reference Manual}). -@item $@var{var}[: i] -As above, but now splitting occurs at the colon character. +@item a string +Split the string at whitespace, and then expand to the @var{i}th +element of the resulting sequence. -@item $@var{var}[: i j] -As above, but instead of returning just a string, it now returns a list -of two strings. If the result is being interpolated into a larger -string, this list will be flattened into one big string, with each -element separated by a space. +@item an alist +If @var{i} is a non-numeric value, expand to the value associated with +the key @code{"@var{i}"} in the alist. For example, if @var{var} is +@samp{(("dog" . "fido") ("cat" . "felix"))}, then +@samp{$@var{var}[dog]} expands to @code{"fido"}. Otherwise, this +behaves as with sequences; e.g., @samp{$@var{var}[0]} expands to +@code{("dog" . "fido")}. @xref{Association List Type, Association +Lists, , elisp, The Emacs Lisp Reference Manual}. -@item $@var{var}["\\\\" i] -Separate on backslash characters. Actually, the first argument -- if it -doesn't have the form of a number, or a plain variable name -- can be -any regular expression. So to split on numbers, use -@samp{$@var{var}["[0-9]+" 10 20]}. +@item anything else +Signals an error. -@item $@var{var}[hello] -Calls @code{assoc} on @var{var} with @code{"hello"}, expecting it to be -an alist (@pxref{Association List Type, Association Lists, , elisp, -The Emacs Lisp Reference Manual}). +@end table + +Multiple sets of indices can also be specified. For example, if +@var{var} is @samp{((1 2) (3 4))}, then @samp{$@var{var}[0][1]} will +expand to @code{2}, i.e.@: the second element of the first list member +(all indices are zero-based). -@item $#@var{var}[hello] -Returns the length of the @code{cdr} of the element of @var{var} whose -car is equal to @code{"hello"}. +@item $@var{expr}[@var{regexp} @var{i...}] +As above (when @var{expr} expands to a string), but use @var{regexp} +to split the string. @var{regexp} can be any form other than a +number. For example, @samp{$@var{var}[: 0]} will return the first +element of a colon-delimited string. + +@item $#@var{expr} +Expands to the length of the result of @var{expr}, an expression in +one of the above forms. For example, @samp{$#@var{var}} returns the +length of the variable @var{var} and @samp{$#@var{var}[0]} returns the +length of the first element of @var{var}. Again, signals an error if +the result of @var{expr} is not a string or a sequence. @end table @node Globbing @section Globbing -Eshell's globbing syntax is very similar to that of Zsh. Users coming -from Bash can still use Bash-style globbing, as there are no -incompatibilities. Most globbing is pattern-based expansion, but there -is also predicate-based expansion. @xref{Filename Generation, , , -zsh, The Z Shell Manual}, -for full syntax. To customize the syntax and behavior of globbing in -Eshell see the Customize@footnote{@xref{Easy Customization, , , emacs, -The GNU Emacs Manual}.} -groups ``eshell-glob'' and ``eshell-pred''. +@vindex eshell-glob-case-insensitive +Eshell's globbing syntax is very similar to that of Zsh +(@pxref{Filename Generation, , , zsh, The Z Shell Manual}). Users +coming from Bash can still use Bash-style globbing, as there are no +incompatibilities. + +By default, globs are case sensitive, except on MS-DOS/MS-Windows +systems. You can control this behavior via the +@code{eshell-glob-case-insensitive} option. You can further customize +the syntax and behavior of globbing in Eshell via the Customize group +``eshell-glob'' (@pxref{Easy Customization, , , emacs, The GNU Emacs +Manual}). + +@table @samp + +@item * +Matches any string (including the empty string). For example, +@samp{*.el} matches any file with the @file{.el} extension. + +@item ? +Matches any single character. For example, @samp{?at} matches +@file{cat} and @file{bat}, but not @file{goat}. + +@item **/ +Matches zero or more subdirectories in a file name. For example, +@samp{**/foo.el} matches @file{foo.el}, @file{bar/foo.el}, +@file{bar/baz/foo.el}, etc. Note that this cannot be combined with +any other patterns in the same file name segment, so while +@samp{foo/**/bar.el} is allowed, @samp{foo**/bar.el} is not. + +@item ***/ +Like @samp{**/}, but follows symlinks as well. + +@cindex character sets, in Eshell glob patterns +@cindex character classes, in Eshell glob patterns +@item [ @dots{} ] +Defines a @dfn{character set} (@pxref{Regexps, , , emacs, The GNU +Emacs Manual}). A character set matches characters between the two +brackets; for example, @samp{[ad]} matches @file{a} and @file{d}. You +can also include ranges of characters in the set by separating the +start and end with @samp{-}. Thus, @samp{[a-z]} matches any +lower-case @acronym{ASCII} letter. Note that, unlike in Zsh, +character ranges are interpreted in the Unicode codepoint order, not +in the locale-dependent collation order. + +Additionally, you can include @dfn{character classes} in a character +set. A @samp{[:} and balancing @samp{:]} enclose a character class +inside a character set. For instance, @samp{[[:alnum:]]} +matches any letter or digit. @xref{Char Classes, , , elisp, The Emacs +Lisp Reference Manual}, for a list of character classes. + +@cindex complemented character sets, in Eshell glob patterns +@item [^ @dots{} ] +Defines a @dfn{complemented character set}. This behaves just like a +character set, but matches any character @emph{except} the ones +specified. + +@cindex groups, in Eshell glob patterns +@item ( @dots{} ) +Defines a @dfn{group}. A group matches the pattern between @samp{(} +and @samp{)}. Note that a group can only match a single file name +component, so a @samp{/} inside a group will signal an error. + +@item @var{x}|@var{y} +Inside of a group, matches either @var{x} or @var{y}. For example, +@samp{e(m|sh)-*} matches any file beginning with @file{em-} or +@file{esh-}. + +@item @var{x}# +Matches zero or more copies of the glob pattern @var{x}. For example, +@samp{fo#.el} matches @file{f.el}, @file{fo.el}, @file{foo.el}, etc. + +@item @var{x}## +Matches one or more copies of the glob pattern @var{x}. Thus, +@samp{fo#.el} matches @file{fo.el}, @file{foo.el}, @file{fooo.el}, +etc. + +@item @var{x}~@var{y} +Matches anything that matches the pattern @var{x} but not @var{y}. For +example, @samp{[[:digit:]]#~4?} matches @file{1} and @file{12}, but +not @file{42}. Note that unlike in Zsh, only a single @samp{~} +operator can be used in a pattern, and it cannot be inside of a group +like @samp{(@var{x}~@var{y})}. + +@end table + +@node Argument Predication and Modification +@section Argument Predication and Modification +@cindex argument predication +@cindex argument modification +Eshell supports @dfn{argument predication}, to filter elements of a +glob, and @dfn{argument modification}, to manipulate argument values. +These are similar to glob qualifiers in Zsh (@pxref{Glob Qualifiers, , +, zsh, The Z Shell Manual}). + +Predicates and modifiers are introduced with @samp{(@var{filters})} +after any list argument, where @var{filters} is a list of predicates +or modifiers. For example, @samp{*(.)} expands to all regular files +in the current directory and @samp{*(^@@:U^u0)} expands to all +non-symlinks not owned by @code{root}, upper-cased. + +Some predicates and modifiers accept string parameters, such as +@samp{*(u'@var{user}')}, which matches all files owned by @var{user}. +These parameters must be surrounded by delimiters; you can use any of +the following pairs of delimiters: @code{"@dots{}"}, @code{'@dots{}'}, +@code{/@dots{}/}, @code{|@dots{}|}, @code{(@dots{})}, +@code{[@dots{}]}, @code{<@dots{}>}, or @code{@{@dots{}@}}. + +You can customize the syntax and behavior of predicates and modifiers +in Eshell via the Customize group ``eshell-pred'' (@pxref{Easy +Customization, , , emacs, The GNU Emacs Manual}). + +@menu +* Argument Predicates:: +* Argument Modifiers:: +@end menu + +@node Argument Predicates +@subsection Argument Predicates +You can use argument predicates to filter lists of file names based on +various properties of those files. This is most useful when combined +with globbing, but can be used on any list of files names. Eshell +supports the following argument predicates: + +@table @asis + +@item @samp{/} +Matches directories. + +@item @samp{.} @r{(Period)} +Matches regular files. + +@item @samp{@@} +Matches symbolic links. + +@item @samp{=} +Matches sockets. + +@item @samp{p} +Matches named pipes. + +@item @samp{%} +Matches block or character devices. + +@item @samp{%b} +Matches block devices. + +@item @samp{%c} +Matches character devices. + +@item @samp{*} +Matches regular files that can be executed by the current user. + +@item @samp{r} +@item @samp{A} +@item @samp{R} +Matches files that are readable by their owners (@samp{r}), their +groups (@samp{A}), or the world (@samp{R}). + +@item @samp{w} +@item @samp{I} +@item @samp{W} +Matches files that are writable by their owners (@samp{w}), their +groups (@samp{I}), or the world (@samp{W}). + +@item @samp{x} +@item @samp{E} +@item @samp{X} +Matches files that are executable by their owners (@samp{x}), their +groups (@samp{E}), or the world (@samp{X}). + +@item @samp{s} +Matches files with the setuid flag set. + +@item @samp{S} +Matches files with the setgid flag set. + +@item @samp{t} +Matches files with the sticky bit set. + +@item @samp{U} +Matches files owned by the current effective user ID. + +@item @samp{G} +Matches files owned by the current effective group ID. + +@item @samp{l@option{[+-]}@var{n}} +Matches files with @var{n} links. With @option{+} (or @option{-}), +matches files with more than (or less than) @var{n} links, +respectively. + +@item @samp{u@var{uid}} +@item @samp{u'@var{user-name}'} +Matches files owned by user ID @var{uid} or user name @var{user-name}. + +@item @samp{g@var{gid}} +@item @samp{g'@var{group-name}'} +Matches files owned by group ID @var{gid} or group name +@var{group-name}. + +@item @samp{a@option{[@var{unit}]}@option{[+-]}@var{n}} +@item @samp{a@option{[+-]}'@var{file}'} +Matches files last accessed exactly @var{n} days ago. With @option{+} +(or @option{-}), matches files accessed more than (or less than) +@var{n} days ago, respectively. + +With @var{unit}, @var{n} is a quantity in that unit of time, so +@samp{aw-1} matches files last accessed within one week. @var{unit} +can be @samp{M} (30-day months), @samp{w} (weeks), @samp{h} (hours), +@samp{m} (minutes), or @samp{s} (seconds). + +If @var{file} is specified instead, compare against the modification +time of @file{file}. Thus, @samp{a-'hello.txt'} matches all files +accessed after @file{hello.txt} was last accessed. + +@item @samp{m@option{[@var{unit}]}@option{[+-]}@var{n}} +@item @samp{m@option{[+-]}'@var{file}'} +Like @samp{a}, but examines modification time. + +@item @samp{c@option{[@var{unit}]}@option{[+-]}@var{n}} +@item @samp{c@option{[+-]}'@var{file}'} +Like @samp{a}, but examines status change time. + +@item @samp{L@option{[@var{unit}]}@option{[+-]}@var{n}} +Matches files exactly @var{n} bytes in size. With @option{+} (or +@option{-}), matches files larger than (or smaller than) @var{n} +bytes, respectively. + +With @var{unit}, @var{n} is a quantity in that unit of size, so +@samp{Lm+5} matches files larger than 5 MiB in size. @var{unit} can +be one of the following (case-insensitive) characters: @samp{m} +(megabytes), @samp{k} (kilobytes), or @samp{p} (512-byte blocks). + +@end table + +The @samp{^} and @samp{-} operators are not argument predicates +themselves, but they modify the behavior of all subsequent predicates. +@samp{^} inverts the meaning of subsequent predicates, so +@samp{*(^RWX)} expands to all files whose permissions disallow the +world from accessing them in any way (i.e., reading, writing to, or +modifying them). When examining a symbolic link, @samp{-} applies the +subsequent predicates to the link's target instead of the link itself. + +@node Argument Modifiers +@subsection Argument Modifiers +You can use argument modifiers to manipulate argument values. For +example, you can sort lists, remove duplicate values, capitalize +words, etc. All argument modifiers are prefixed by @samp{:}, so +@samp{$exec-path(:h:u:x/^\/home/)} lists all of the unique parent +directories of the elements in @code{exec-path}, excluding those in +@file{/home}. + +@table @samp + +@item E +Re-evaluates the value as an Eshell argument. For example, if +@var{foo} is @code{"$@{echo hi@}"}, then the result of @samp{$foo(:E)} +is @code{hi}. + +@item L +Converts the value to lower case. + +@item U +Converts the value to upper case. + +@item C +Capitalizes the value. + +@item h +Treating the value as a file name, gets the directory name (the +``head''). For example, @samp{foo/bar/baz.el(:h)} expands to +@samp{foo/bar/}. + +@item t +Treating the value as a file name, gets the base name (the ``tail''). +For example, @samp{foo/bar/baz.el(:h)} expands to @samp{baz.el}. + +@item e +Treating the value as a file name, gets the final extension of the +file, excluding the dot. For example, @samp{foo.tar.gz(:e)} +expands to @code{gz}. + +@item r +Treating the value as a file name, gets the file name excluding the +final extension. For example, @samp{foo/bar/baz.tar.gz(:r)} expands +to @samp{foo/bar/baz.tar}. + +@item q +Marks that the value should be interpreted by Eshell literally, so +that any special characters like @samp{$} no longer have any special +meaning. + +@item s/@var{pattern}/@var{replace}/ +Replaces the first instance of the regular expression @var{pattern} +with @var{replace}. Signals an error if no match is found. + +As with other modifiers taking string parameters, you can use +different delimiters to separate @var{pattern} and @var{replace}, such +as @samp{s'@dots{}'@dots{}'}, @samp{s[@dots{}][@dots{}]}, or even +@samp{s[@dots{}]/@dots{}/}. + +@item gs/@var{pattern}/@var{replace}/ +Replaces all instances of the regular expression @var{pattern} with +@var{replace}. + +@item i/@var{pattern}/ +Filters a list of values to include only the elements matching the +regular expression @var{pattern}. + +@item x/@var{pattern}/ +Filters a list of values to exclude all the elements matching the +regular expression @var{pattern}. + +@item S +@item S/@var{pattern}/ +Splits the value using the regular expression @var{pattern} as a +delimiter. If @var{pattern} is omitted, split on spaces. + +@item j +@item j/@var{delim}/ +Joins a list of values, inserting the string @var{delim} between each +value. If @var{delim} is omitted, use a single space as the +delimiter. + +@item o +Sorts a list of strings in ascending lexicographic order, comparing +pairs of characters according to their character codes (@pxref{Text +Comparison, , , elisp, The Emacs Lisp Reference Manual}). + +@item O +Sorts a list of strings in descending lexicographic order. + +@item u +Removes any duplicate elements from a list of values. + +@item R +Reverses the order of a list of values. + +@end table @node Input/Output @chapter Input/Output @@ -721,6 +1625,48 @@ the output function. The output function is called once on each line of output until @code{nil} is passed, indicating end of output. +@section Running Shell Pipelines Natively +When constructing shell pipelines that will move a lot of data, it is +a good idea to bypass Eshell's own pipelining support and use the +operating system shell's instead. This is especially relevant when +executing commands on a remote machine using Eshell's Tramp +integration: using the remote shell's pipelining avoids copying the +data which will flow through the pipeline to local Emacs buffers and +then right back again. + +Eshell recognizes a special syntax to make it easier to convert +pipelines so as to bypass Eshell's pipelining. Prefixing at least one +@code{|}, @code{<} or @code{>} with an asterisk marks a command as +intended for the operating system shell. To make it harder to invoke +this functionality accidentally, it is also required that the asterisk +be preceded by whitespace or located at the start of input. For +example, + +@example + cat *.ogg *| my-cool-decoder >file +@end example + +Executing this command will not copy all the data in the *.ogg files, +nor the decoded data, into Emacs buffers, as would normally happen. + +The command is interpreted as extending up to the next @code{|} +character which is not preceded by an unescaped asterisk following +whitespace, or the end of the input if there is no such character. +Thus, all @code{<} and @code{>} redirections occurring before the next +asterisk-unprefixed @code{|} are implicitly prefixed with (whitespace +and) asterisks. An exception is that Eshell-specific redirects right +at the end of the command are excluded. This allows input like this: + +@example + foo *| baz >#<buffer quux> +@end example + +@noindent which is equivalent to input like this: + +@example + sh -c "foo | baz" >#<buffer quux> +@end example + @node Extension modules @chapter Extension modules Eshell provides a facility for defining extension modules so that they @@ -751,6 +1697,7 @@ Eshell module.} You also need to load the following as shown: * Key rebinding:: * Smart scrolling:: * Terminal emulation:: +* Electric forward slash:: @end menu @node Writing a module @@ -783,6 +1730,61 @@ This section is not yet written. This section is not yet written. +@node Electric forward slash +@section Electric forward slash + +To help with supplying absolute file name arguments to remote +commands, you can add the @code{eshell-elecslash} module to +@code{eshell-modules-list}. Then, typing @kbd{/} as the first +character of a command line argument will automatically insert the +Tramp prefix @file{/method:host:}. If this is not what you want +(e.g.@: because you want to refer to a local file), you can type +another @kbd{/} to undo the automatic insertion. Typing @kbd{~/} also +inserts the Tramp prefix. The automatic insertion applies only when +@code{default-directory} is remote and the command is a Lisp function. +In particular, typing arguments to external commands doesn't insert +the prefix. + +The result is that in most cases of supplying absolute file name +arguments to commands you should see the Tramp prefix inserted +automatically only when that's what you'd reasonably expect. This +frees you from having to keep track of whether commands are Lisp +functions or external when typing command line arguments. For +example, suppose you execute + +@example + cd /ssh:root@@example.com: + find /etc -name "*gnu*" +@end example + +@noindent and in reviewing the output of the command, you identify a +file @file{/etc/gnugnu} that should be moved somewhere else. So you +type + +@example + mv /etc/gnugnu /tmp +@end example + +@noindent But since @command{mv} refers to the local Lisp function +@code{eshell/mv}, not a remote shell command, to say this is to +request that the local file @file{/etc/gnugnu} be moved into the local +@file{/tmp} directory. After you add @code{eshell-elecslash} to +@code{eshell-modules-list}, then when you type the above @command{mv} +invocation you will get the following input, which is what you +intended: + +@example + mv /ssh:root@@example.com:/etc/gnugnu /ssh:root@@example.com:/tmp +@end example + +The code that determines whether or not the Tramp prefix should be +inserted uses simple heuristics. A limitation of the current +implementation is that it inspects whether only the command at the +very beginning of input is a Lisp function or external program. Thus +when chaining commands with the operators @code{&&}, @code{||}, +@code{|} and @code{;}, the electric forward slash is active only +within the first command. + @node Bugs and ideas @chapter Bugs and ideas @cindex reporting bugs and ideas @@ -820,14 +1822,6 @@ alias arg=blah function arg () @{ blah $* @} @end example -@item @samp{for i in 1 2 3 @{ grep -q a b && *echo has it @} | wc -l} outputs result after prompt - -In fact, piping to a process from a looping construct doesn't work in -general. If I change the call to @code{eshell-copy-handles} in -@code{eshell-rewrite-for-command} to use @code{eshell-protect}, it seems -to work, but the output occurs after the prompt is displayed. The whole -structured command thing is too complicated at present. - @item Pcomplete sometimes gets stuck You press @key{TAB}, but no completions appear, even though the @@ -854,11 +1848,6 @@ scrolls back. @item Menu support was removed, but never put back -@item Using C-p and C-n with rebind gets into a locked state - -This happened a few times in Emacs 21, but has been irreproducible -since. - @item If an interactive process is currently running, @kbd{M-!} doesn't work @item Use a timer instead of @code{sleep-for} when killing child processes @@ -972,11 +1961,6 @@ glob match. At the moment, this is not supported. -@item Error if a glob doesn't expand due to a predicate - -An error should be generated only if @code{eshell-error-if-no-glob} is -non-@code{nil}. - @item @samp{(+ @key{RET} @key{SPC} @key{TAB}} does not cause @code{indent-according-to-mode} to occur @item Create @code{eshell-auto-accumulate-list} @@ -1152,11 +2136,10 @@ it). @item Make the shell spawning commands be visual -That is, make (@command{su}, @command{bash}, @command{telnet}, -@command{rlogin}, @command{rsh}, etc.)@: be part of -@code{eshell-visual-commands}. The only exception is if the shell is -being used to invoke a single command. Then, the behavior should be -based on what that command is. +That is, make (@command{su}, @command{bash}, @command{ssh}, etc.)@: be +part of @code{eshell-visual-commands}. The only exception is if the +shell is being used to invoke a single command. Then, the behavior +should be based on what that command is. @item Create a smart viewing command named @command{open} @@ -1186,11 +2169,12 @@ only. That way, it could be listed as a login shell. @item The first keypress after @kbd{M-x watson} triggers @code{eshell-send-input} -@item Make @kbd{/} electric +@item Make @kbd{/} more electric -So that it automatically expands and corrects pathnames. Or make -pathname completion for Pcomplete auto-expand @samp{/u/i/std@key{TAB}} to -@samp{/usr/include/std@key{TAB}}. +@noindent so that it automatically expands and corrects file names, +beyond what the @code{em-elecslash} module is able to do. Or make +file name completion for Pcomplete auto-expand +@samp{/u/i/std@key{TAB}} to @samp{/usr/include/std@key{TAB}}. @item Write the @command{pushd} stack to disk along with @code{last-dir-ring} diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi index e9cf4cfade9..0037ba78d3b 100644 --- a/doc/misc/eudc.texi +++ b/doc/misc/eudc.texi @@ -192,9 +192,9 @@ email composition buffers (@pxref{Inline Query Expansion}) @lisp (with-eval-after-load "message" - (define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-inline)) + (define-key message-mode-map [(control ?c) (tab)] 'eudc-expand-try-all)) (with-eval-after-load "sendmail" - (define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-inline)) + (define-key mail-mode-map [(control ?c) (tab)] 'eudc-expand-try-all)) @end lisp @menu @@ -254,7 +254,9 @@ To: * Smith @noindent will return all LDAP entries with surnames that begin with @code{Smith}. In every LDAP query it makes, EUDC implicitly appends -the wildcard character to the end of the last word. +the wildcard character to the end of the last word, except if the word +corresponds to an attribute which is a member of +`eudc-ldap-no-wildcard-attributes'. @menu * Emacs-only Configuration:: Configure with @file{.emacs} @@ -281,19 +283,20 @@ LDAP: @vindex message-mode-map @findex eudc-expand-inline +@findex eudc-expand-try-all @vindex eudc-server-hotlist @vindex ldap-host-parameters-alist @lisp (with-eval-after-load "message" - (define-key message-mode-map (kbd "TAB") 'eudc-expand-inline)) -(customize-set-variable 'eudc-server-hotlist - '(("" . bbdb) - ("ldaps://ldap.gnu.org" . ldap))) -(customize-set-variable 'ldap-host-parameters-alist - '(("ldaps://ldap.gnu.org" - base "ou=people,dc=gnu,dc=org" - binddn "gnu\\emacsuser" - passwd ldap-password-read))) + (define-key message-mode-map (kbd "TAB") 'eudc-expand-try-all)) +(setopt eudc-server-hotlist + '(("" . bbdb) + ("ldaps://ldap.gnu.org" . ldap))) +(setopt ldap-host-parameters-alist + '(("ldaps://ldap.gnu.org" + base "ou=people,dc=gnu,dc=org" + binddn "gnu\\emacsuser" + passwd ldap-password-read))) @end lisp @findex ldap-password-read @@ -337,17 +340,18 @@ configure EUDC for LDAP: @vindex message-mode-map @findex eudc-expand-inline +@findex eudc-expand-try-all @vindex eudc-server-hotlist @vindex ldap-host-parameters-alist @lisp (with-eval-after-load "message" - (define-key message-mode-map (kbd "TAB") 'eudc-expand-inline)) -(customize-set-variable 'eudc-server-hotlist - '(("" . bbdb) - ("ldaps://ldap.gnu.org" . ldap))) -(customize-set-variable 'ldap-host-parameters-alist - '(("ldaps://ldap.gnu.org" - auth-source t))) + (define-key message-mode-map (kbd "TAB") 'eudc-expand-try-all)) +(setopt eudc-server-hotlist + '(("" . bbdb) + ("ldaps://ldap.gnu.org" . ldap))) +(setopt ldap-host-parameters-alist + '(("ldaps://ldap.gnu.org" + auth-source t))) @end lisp For this example where we only care about one server, the server name @@ -366,15 +370,16 @@ and the @file{.emacs} expressions become: @vindex message-mode-map @findex eudc-expand-inline +@findex eudc-expand-try-all @vindex eudc-server-hotlist @vindex ldap-host-parameters-alist @lisp (with-eval-after-load "message" - (define-key message-mode-map (kbd "TAB") 'eudc-expand-inline)) -(customize-set-variable 'eudc-server-hotlist - '(("" . bbdb) ("" . ldap))) -(customize-set-variable 'ldap-host-parameters-alist - '(("" auth-source t))) + (define-key message-mode-map (kbd "TAB") 'eudc-expand-try-all)) +(setopt eudc-server-hotlist + '(("" . bbdb) ("" . ldap))) +(setopt ldap-host-parameters-alist + '(("" auth-source t))) @end lisp @node Troubleshooting @@ -418,11 +423,12 @@ all macOS versions since 10.0 (which was released 2001). configurations. @file{eudcb-mab.el} reverse engineers the format of the database file -used by the macOS Contacts app, and accesses its contents directly. -While this may promise some performance advantages, it comes at the -cost of using an undocumented interface. Hence, users of -@file{eudcb-mab.el} are recommended to double check the compatibility -of @file{eudcb-mab.el} before upgrading to a new version of macOS. +using the external command-line utility named contacts, which needs to +be installed separately. While this may promise some performance +advantages, it comes at the cost of using an undocumented interface. +Hence, users of @file{eudcb-mab.el} are recommended to double check +the compatibility of @file{eudcb-mab.el} and the required, external +command-line utility before upgrading to a new version of macOS. @file{eudcb-mab.el} is retained for backwards compatibility with existing configurations, and may be removed in a future release. @@ -708,32 +714,49 @@ be passed to the program. @node Inline Query Expansion @section Inline Query Expansion - -Inline query expansion is a powerful method to get completion from your -directory server. The most common usage is for expanding names to email -addresses in mail message buffers. The expansion is performed by the -command @kbd{M-x eudc-expand-inline} which is available from the -@samp{Expand Inline Query} menu item but can also be conveniently -bound to a key shortcut (@pxref{Installation}). The operation is -controlled by the variables @code{eudc-inline-expansion-format}, -@code{eudc-inline-query-format}, +@subsection Inline Query Expansion Using a Key Binding + +Inline query expansion is a powerful method to get completion from +your directory servers. The most common usage is for expanding names +to email addresses in mail message buffers. The expansion is +performed by the command @kbd{M-x eudc-expand-try-all} which is +available from the @samp{Expand Inline Query Trying All Servers} menu +item but can also be conveniently bound to a key shortcut +(@pxref{Installation}). The operation is controlled by the variables +@code{eudc-inline-expansion-format}, @code{eudc-inline-query-format}, @code{eudc-expanding-overwrites-query} and @code{eudc-multiple-match-handling-method}. -If the query fails for a server, other servers may be tried successively -until one of them finds a match (@pxref{Multi-server Queries}). +If the query fails for a server, other servers may be tried +successively until one of them finds a match (@pxref{Multi-server +Queries}), or all servers can be tried and all matches returned. + +@deffn Command eudc-expand-try-all try-all-servers-p +Query some or all servers and expand the query string before point. +The query string consists of the buffer substring from the point back +to the preceding comma, colon or beginning of line. +@code{eudc-inline-query-format} controls how individual words are +mapped onto directory attribute names. After querying the server or +servers for the given string, the expansion specified by +@code{eudc-inline-expansion-format} is inserted in the buffer at +point. If multiple matches are available, a selection window is +displayed. If @var{try-all-servers-p} is non-@code{nil} then all +servers are queried. +@end deffn -@deffn Command eudc-expand-inline replace-p +@deffn Command eudc-expand-inline save-query-as-kill-p Query the server and expand the query string before point. The query string consists of the buffer substring from the point back to the -preceding comma, colon or beginning of -line. @code{eudc-inline-query-format} controls how individual words -are mapped onto directory attribute names. After querying the server -for the given string, the expansion specified by +preceding comma, colon or beginning of line. +@code{eudc-inline-query-format} controls how individual words are +mapped onto directory attribute names. After querying the server for +the given string, the expansion specified by @code{eudc-inline-expansion-format} is inserted in the buffer at -point. If @var{replace-p} is @code{t} then this expansion replaces the -query string in the buffer. If @code{eudc-expanding-overwrites-query} -is non-@code{nil} then the meaning of @var{replace-p} is negated. +point. If multiple matches are available, a selection window is +displayed. If @var{save-query-as-kill-p} is @code{t} then the query +string is saved to the kill ring. If +@code{eudc-expansion-save-query-as-kill} is non-@code{nil} then the +meaning of @var{save-query-as-kill-p} is negated. @end deffn @defvar eudc-inline-query-format @@ -776,12 +799,73 @@ against the @code{cn} attribute of LDAP servers: @end defvar @defvar eudc-inline-expansion-format -This variable lets you control exactly what is inserted into the buffer -upon an inline expansion request. It is a list whose first element is a -string passed to @code{format}. Remaining elements are symbols -corresponding to directory attribute names. The corresponding attribute -values are passed as additional arguments to @code{format}. Default is -@code{("%s %s <%s>" firstname name email)}. +This variable lets you control exactly what is inserted into the +buffer upon an inline expansion request. It can be set to @code{nil}, +to a function, or to a list. Default is @code{nil}. + +When the value is a list, the first element is a string passed to +@code{format}. Remaining elements are symbols corresponding to +directory attribute names. The corresponding attribute values are +passed as additional arguments to @code{format}. + +When the value is @code{nil}, the expansion result will be formatted +according to @url{https://datatracker.ietf.org/doc/html/rfc5322, RFC +5322}. The @var{phrase} part will be formatted as ``firstname name'', +quoting the result if necessary. No @var{comment} part will be added +in this case. This will produce any of the default formats +@center @var{address} +@center @var{first} @code{<}@var{address}@code{>} +@center @var{last} @code{<}@var{address}@code{>} +@center @var{first} @var{last} @code{<}@var{address}@code{>} +depending on whether a first and/or last name are returned by the +query, or not. + +When the value is a function, the expansion result will be formatted +according to @url{https://datatracker.ietf.org/doc/html/rfc5322, RFC +5322}, and the referenced function is called to format the +@var{phrase}, and @var{comment} parts, respectively. The formatted +@var{phrase} part will be quoted if necessary. Thus one can produce +any of the formats: +@center @var{address} +@center @var{phrase} @code{<}@var{address}@code{>} +@center @var{address} @code{(}@var{comment}@code{)} +@center @var{phrase} @code{<}@var{address}@code{>} @code{(}@var{comment}@code{)} + +Email address specifications, as are generated by inline expansion, +need to comply with RFC 5322 in order to be useful in email +messages. When an invalid address specification is present in an email +message header, the message is likely to be rejected by a receiving +MTA. It is hence recommended to switch old configurations, which use +a list value, to the new @code{nil}, or function value type since it +ensures that the inserted address specifications will be in line with +@url{https://datatracker.ietf.org/doc/html/rfc5322, RFC 5322}. At +minimum, and to achieve the same semantics as with the old list +default value, this variable should now be set to @code{nil}: +@lisp +(customize-set-variable 'eudc-inline-expansion-format nil) +@end lisp + +A function value can for example be used to get @emph{``last, first +<address>''} instead of the default @emph{``first last <address>''}: +@lisp +(defun my-phrase-last-comma-first (search-res-alist) + (let* (phrase + (my-attrs (eudc-translate-attribute-list '(firstname name))) + (first-name (cdr (assq (nth 0 my-attrs) search-res-alist))) + (last-name (cdr (assq (nth 1 my-attrs) search-res-alist))) + (comment nil)) + (setq phrase (concat last-name ", " first-name)) + (cons phrase comment))) + +(customize-set-variable 'eudc-inline-expansion-format + #'my-phrase-last-comma-first) +@end lisp +To set the @var{comment} part, too, instead of @code{nil} as in this +example, also provide a string as the @code{cdr} of the @code{cons} +being returned. Do not include any double quotes in the @var{phrase} +part, as they are added automatically if needed. Neither include +parentheses in the @var{comment} part as they, too, are added +automatically. @end defvar @defvar eudc-multiple-match-handling-method @@ -803,6 +887,29 @@ An error is signaled. The expansion aborts. Default is @code{select} @end defvar +@subsection Inline Query Expansion Using completion-at-point + +In addition to providing a dedicated EUDC function for binding to a +key shortcut (@pxref{Inline Query Expansion}), EUDC also provides a +function to contribute search results to the Emacs in-buffer +completion system available via the function +@code{completion-at-point} (@pxref{Identifier +Inquiries,,,maintaining}) in @code{message-mode} buffers +(@pxref{Top,Message,, message, Message}). When using this mechanism, +queries are made in the multi-server query mode of operation +(@pxref{Multi-server Queries}). + +When a buffer in @code{message-mode} is created, EUDC's inline +expansion function is automatically added to the variable +@code{completion-at-point-functions}. As a result, whenever +@code{completion-at-point} is invoked in a @code{message-mode} buffer, +EUDC will be queried for email addresses matching the words before +point. Since this will be useful only when editing specific message +header fields that require specifying one or more email addresses, an +additional check is performed whether point is actually in one of +those header fields. Thus, any matching email addresses will be +offered for completion in suitable message header fields only, and not +in other places, like for example the body of the message. @node The Server Hotlist diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi index b3ec52f7ab8..1060cd805ab 100644 --- a/doc/misc/eww.texi +++ b/doc/misc/eww.texi @@ -305,6 +305,7 @@ state the directionality. @vindex shr-max-image-proportion @vindex shr-blocked-images +@vindex shr-allowed-images @cindex Image Display Loading random images from the web can be problematic due to their size or content. By customizing @code{shr-max-image-proportion} you @@ -380,6 +381,32 @@ thus allowing for the use of the usual substitutions, such as @code{\[eww-reload]} for the current key binding of the @code{eww-reload} command. +@vindex eww-auto-rename-buffer + If the @code{eww-auto-rename-buffer} user option is non-@code{nil}, +EWW buffers will be renamed after rendering a document. If this is +@code{title}, rename based on the title of the document. If this is +@code{url}, rename based on the @acronym{URL} of the document. This +can also be a user-defined function, which is called with no +parameters in the EWW buffer, and should return a string. + +@cindex utm +@vindex eww-url-transformers + EWW runs the URLs through @code{eww-url-transformers} before using +them. This user option is a list of functions, where each function is +called with the URL as the parameter, and should return the (possibly) +transformed URL. By default, this variable contains +@code{eww-remove-tracking}, which removes the common @samp{utm_} +trackers from links. + +@cindex video +@vindex shr-use-xwidgets-for-media + If Emacs has been built with xwidget support, EWW can use that to +display @samp{<video>} elements. However, this support is still +experimental, and on some systems doesn't work (and even worse) may +crash your Emacs, so this feature is off by default. If you wish to +switch it on, set @code{shr-use-xwidgets-for-media} to a +non-@code{nil} value. + @node Command Line @chapter Command Line Usage diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi index 451d6c76c4b..953e4605e98 100644 --- a/doc/misc/flymake.texi +++ b/doc/misc/flymake.texi @@ -1,4 +1,4 @@ -\input texinfo @c -*-texinfo; coding: utf-8 -*- +\input texinfo @c -*- mode: texinfo; coding: utf-8 -*- @comment %**start of header @setfilename ../../info/flymake.info @set VERSION 1.2 @@ -265,6 +265,9 @@ This section summarizes customization variables used for the configuration of the Flymake user interface. @vtable @code +@item flymake-mode-line-lighter +The name of the mode. Defaults to @samp{Flymake}. + @item flymake-mode-line-format Format to use for the Flymake mode line indicator. @@ -1145,7 +1148,7 @@ file are parsed. For @file{file.h}, the include directives to look for are @code{#include "file.h"}, @code{#include "../file.h"}, etc. Each include is checked against a list of include directories -(see @ref{Getting the include directories}) to be sure it points to the +(@pxref{Getting the include directories}) to be sure it points to the correct @file{file.h}. First matching master file found stops the search. The master file is then diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi index fd961be2f52..6d09fd4ec96 100644 --- a/doc/misc/gnus-faq.texi +++ b/doc/misc/gnus-faq.texi @@ -1,7 +1,7 @@ @c \input texinfo @c -*-texinfo-*- @c Uncomment 1st line before texing this file alone. @c %**start of header -@c Copyright (C) 1995, 2001--2022 Free Software Foundation, Inc. +@c Copyright (C) 1995--2022 Free Software Foundation, Inc. @c @c @setfilename gnus-faq.info @c @settitle Frequently Asked Questions @@ -13,7 +13,6 @@ @section Frequently Asked Questions @menu -* FAQ - Changes:: * FAQ - Introduction:: About Gnus and this FAQ. * FAQ 1 - Installation FAQ:: Installation of Gnus. * FAQ 2 - Startup / Group buffer:: Start up questions and the @@ -41,21 +40,6 @@ This is the new Gnus Frequently Asked Questions list. Please submit features and suggestions to the @email{ding@@gnus.org, ding list}. -@node FAQ - Changes -@subsection Changes - - - -@itemize @bullet - -@item -2008-06-15: Adjust for message-fill-column. Add x-face-file. -Clarify difference between ding and gnu.emacs.gnus. Remove -reference to discontinued service. - -@item -2006-04-15: Added tip on how to delete sent buffer on exit. -@end itemize @node FAQ - Introduction @subsection Introduction @@ -63,11 +47,11 @@ reference to discontinued service. This is the Gnus Frequently Asked Questions list. Gnus is a Usenet Newsreader and Electronic Mail User Agent implemented -as a part of Emacs. It's been around in some form for almost a decade -now, and has been distributed as a standard part of Emacs for much of -that time. Gnus 5 is the latest (and greatest) incarnation. The +as a part of Emacs. It's been around in some form since the early +1990s, and has been distributed as a standard part of Emacs for much +of that time. Gnus 5 is the latest (and greatest) incarnation. The original version was called GNUS, and was written by Masanobu UMEDA@. -When autumn crept up in '94, Lars Magne Ingebrigtsen grew bored and +When autumn crept up in 1994, Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus. Its biggest strength is the fact that it is extremely @@ -84,11 +68,6 @@ would like to thank Steve Baur and Per Abrahamsen for doing a wonderful job with this FAQ before him. We would like to do the same: thanks, Justin! -This version is much nicer than the unofficial hypertext -versions that are archived at Utrecht, Oxford, Smart Pages, Ohio -State, and other FAQ archives. See the resources question below -if you want information on obtaining it in another format. - The information contained here was compiled with the assistance of the Gnus development mailing list, and any errors or misprints are the Gnus team's fault, sorry. @@ -98,12 +77,9 @@ misprints are the Gnus team's fault, sorry. @menu * FAQ 1-1:: What is the latest version of Gnus? -* FAQ 1-2:: What's new in 5.10? -* FAQ 1-3:: Where and how to get Gnus? -* FAQ 1-4:: What to do with the tarball now? -* FAQ 1-5:: I sometimes read references to No Gnus and Oort Gnus, +* FAQ 1-2:: Where and how to get Gnus? +* FAQ 1-3:: I sometimes read references to No Gnus and Oort Gnus, what are those? -* FAQ 1-6:: Which version of Emacs do I need? @end menu @node FAQ 1-1 @@ -113,108 +89,28 @@ What is the latest version of Gnus? @subsubheading Answer -Jingle please: Gnus 5.10 is released, get it while it's -hot! As well as the step in version number is rather -small, Gnus 5.10 has tons of new features which you -shouldn't miss. The current release (5.13) should be at -least as stable as the latest release of the 5.8 series. +The latest version of Gnus is bundled with Emacs. @node FAQ 1-2 @subsubheading Question 1.2 -What's new in 5.10? - -@subsubheading Answer - -First of all, you should have a look into the file -GNUS-NEWS in the toplevel directory of the Gnus tarball, -there the most important changes are listed. Here's a -short list of the changes I find especially -important/interesting: - -@itemize @bullet - -@item -Major rewrite of the Gnus agent, Gnus agent is now -active by default. - -@item -Many new article washing functions for dealing with -ugly formatted articles. - -@item -Anti Spam features. - -@item -Message-utils now included in Gnus. - -@item -New format specifiers for summary lines, e.g., %B for -a complex trn-style thread tree. -@end itemize - -@node FAQ 1-3 -@subsubheading Question 1.3 - Where and how to get Gnus? @subsubheading Answer Gnus is bundled with Emacs. -@node FAQ 1-4 -@subsubheading Question 1.4 - -What to do with the tarball now? - -@subsubheading Answer - -Untar it via @samp{tar xvzf gnus.tar.gz} and do the common -@samp{./configure; make; make install} circle. -(under MS-Windows either get the Cygwin environment from -@uref{https://www.cygwin.com} -which allows you to do what's described above or unpack the -tarball with some packer (e.g., Winace) -and use the batch-file make.bat included in the tarball to install -Gnus.) If you don't want to (or aren't allowed to) install Gnus -system-wide, you can install it in your home directory and add the -following lines to your ~/.emacs: - -@example -(add-to-list 'load-path "/path/to/gnus/lisp") -(add-to-list 'Info-default-directory-list "/path/to/gnus/texi/") -@end example -@noindent - -Make sure that you don't have any Gnus related stuff -before this line, on MS Windows use something like -"C:/path/to/lisp" (yes, "/"). - -@node FAQ 1-5 -@subsubheading Question 1.5 +@node FAQ 1-3 +@subsubheading Question 1.3 I sometimes read references to No Gnus and Oort Gnus, what are those? @subsubheading Answer -Oort Gnus was the name of the development version of -Gnus, which became Gnus 5.10 in autumn 2003. No Gnus is -the name of the current development version which will -once become Gnus 5.12 or Gnus 6. (If you're wondering why -not 5.11, the odd version numbers are normally used for -the Gnus versions bundled with Emacs) - -@node FAQ 1-6 -@subsubheading Question 1.6 - -Which version of Emacs do I need? - -@subsubheading Answer - -Gnus 5.13 requires an Emacs version that is greater than or equal -to Emacs 23.1, although there are some features that -only work on Emacs 24. +Oort Gnus was the name of the development version of Gnus, which +became Gnus 5.10 in autumn 2003. No Gnus was the name of the +development version that became Gnus 5.12. @node FAQ 2 - Startup / Group buffer @subsection Startup / Group buffer @@ -653,8 +549,7 @@ about the server there. (add-to-list 'gnus-secondary-select-methods '(nnimap "Give the baby a name" (nnimap-address "imap.yourProvider.net") - (nnimap-port 143) - (nnimap-list-pattern "archive.*"))) + (nnimap-port 143))) @end example @noindent @@ -748,9 +643,8 @@ in @file{~/.gnus.el} to load enough old articles to prevent teared threads, repl all articles (Warning: Both settings enlarge the amount of data which is fetched when you enter a group and slow down the process of entering a group). -If you already use Gnus 5.10, you can say -@samp{/o N} -In summary buffer to load the last N messages, this feature is not available in 5.8.8 +You can say @samp{/o N} in the summary buffer to load the last N +messages. If you don't want all old messages, but the parent of the message you're just reading, you can say @samp{^}, if you want to retrieve the whole thread @@ -850,11 +744,10 @@ Can I use some other browser than w3m to render my HTML-mails? @subsubheading Answer -Only if you use Gnus 5.10 or younger. In this case you've got the -choice between shr, w3m, links, lynx and html2text, which -one is used can be specified in the variable -mm-text-html-renderer, so if you want links to render your -mail say +You've got the choice between @samp{shr}, @samp{w3m}, @samp{links}, +and @samp{lynx}. Which one is used is specified in the variable +@code{mm-text-html-renderer}, so if you want links to render your +mail, say: @example (setq mm-text-html-renderer 'links) @@ -877,8 +770,7 @@ long lines'' (@samp{W w}), ``Decode ROT13'' the dumb quoting used by many users of Microsoft products (@samp{W Y f} gives you full deuglify. See @samp{W Y C-h} or have a look at the menus for -other deuglifications). Outlook deuglify is only available since -Gnus 5.10. +other deuglifications). @node FAQ 4-9 @subsubheading Question 4.9 @@ -1068,7 +960,7 @@ you'll find useful things like positioning the cursor and tabulators which allow you a summary in table form, but sadly hard tabulators are broken in 5.8.8. -Since 5.10, Gnus offers you some very nice new specifiers, +Gnus offers you some very nice new specifiers, e.g., %B which draws a thread-tree and %&user-date which gives you a date where the details are dependent of the articles age. Here's an example which uses both: @@ -1275,7 +1167,7 @@ How to set stuff like From, Organization, Reply-To, signature...? @subsubheading Answer There are other ways, but you should use posting styles -for this. (See below why). +for this. (See below why.) This example should make the syntax clear: @example @@ -1359,19 +1251,14 @@ Is there a spell-checker? Perhaps even on-the-fly spell-checking? @subsubheading Answer -You can use ispell.el to spell-check stuff in Emacs. So the -first thing to do is to make sure that you've got either -@uref{https://www.cs.hmc.edu/~geoff/ispell.html, ispell} -or @uref{http://aspell.net, aspell} -installed and in your Path. Then you need -ispell.el -and for on-the-fly spell-checking -@uref{https://www-sop.inria.fr/members/Manuel.Serrano/flyspell/flyspell.html, flyspell.el}. -Ispell.el is shipped with Emacs, -flyspell.el is shipped with Emacs, so there should be no need to install them -manually. +You can use ispell.el to spell-check stuff in Emacs, and flyspell.el +for on-the-fly spell-checking. So the first thing to do is to make +sure that you've got either +@uref{https://hunspell.github.io/, hunspell}, +@uref{https://www.cs.hmc.edu/~geoff/ispell.html, ispell} or +@uref{http://aspell.net, aspell} installed and in your Path. -Ispell.el assumes you use ispell, if you choose aspell say +Ispell.el assumes you use ispell. If you use aspell say @example (setq ispell-program-name "aspell") @@ -1524,14 +1411,14 @@ Now you only have to tell Gnus to include the X-face in your postings by saying @end example @noindent -in @file{~/.gnus.el}. If you use Gnus 5.10, you can simply add an entry +in @file{~/.gnus.el}. You can add an entry @example (x-face-file "~/.xface") @end example @noindent -to gnus-posting-styles. +to @code{gnus-posting-styles}. @node FAQ 5-9 @subsubheading Question 5.9 @@ -1549,21 +1436,6 @@ Put this in @file{~/.gnus.el}: @end example @noindent -if you already use Gnus 5.10, if you still use 5.8.8 or -5.9 try this instead: - -@example -(with-eval-after-load "gnus-msg" - (unless (boundp 'gnus-confirm-mail-reply-to-news) - (defadvice gnus-summary-reply (around reply-in-news activate) - "Request confirmation when replying to news." - (interactive) - (when (or (not (gnus-news-group-p gnus-newsgroup-name)) - (y-or-n-p "Really reply by mail to article author?")) - ad-do-it)))) -@end example -@noindent - @node FAQ 5-10 @subsubheading Question 5.10 @@ -1571,14 +1443,7 @@ How to tell Gnus not to generate a sender header? @subsubheading Answer -Since 5.10 Gnus doesn't generate a sender header by -default. For older Gnus' try this in @file{~/.gnus.el}: - -@example -(with-eval-after-load "message" - (add-to-list 'message-syntax-checks '(sender . disabled))) -@end example -@noindent +Gnus doesn't generate a sender header by default. @node FAQ 5-11 @subsubheading Question 5.11 @@ -1759,7 +1624,7 @@ more then one article." You can now say @samp{M-x my-archive-article} in summary buffer to archive the article under the cursor in a nnml -group. (Change nnml to your preferred back end) +group. (Change nnml to your preferred back end.) Of course you can also make sure the cache is enabled by saying @@ -1786,7 +1651,7 @@ if you found the posting there, tell Google to display the raw message, look for the message-id, and say @samp{M-^ the@@message.id @key{RET}} in a summary buffer. -Since Gnus 5.10 there's also a Gnus interface for +There's a Gnus interface for groups.google.com which you can call with @samp{G W}) in group buffer. @@ -1800,25 +1665,6 @@ instead. Further on there are the gnus-summary-limit-to-foo functions, which can help you, too. -Of course you can also use grep to search through your -local mail, but this is both slow for big archives and -inconvenient since you are not displaying the found mail -in Gnus. Here nnir comes into action. Nnir is a front end -to search engines like swish-e or swish++ and -others. You index your mail with one of those search -engines and with the help of nnir you can search through -the indexed mail and generate a temporary group with all -messages which met your search criteria. If this sounds -cool to you, get nnir.el from -@c FIXME Isn't this file in Gnus? -@ignore -@c Dead link 2013/7. -@uref{ftp://ls6-ftp.cs.uni-dortmund.de/pub/src/emacs/} -or -@end ignore -@uref{ftp://ftp.is.informatik.uni-duisburg.de/pub/src/emacs/}. -Instructions on how to use it are at the top of the file. - @node FAQ 6-4 @subsubheading Question 6.4 @@ -1967,16 +1813,9 @@ So what was this thing about the Agent? The Gnus agent is part of Gnus, it allows you to fetch mail and news and store them on disk for reading them later when you're offline. It kind of mimics offline -newsreaders like Forte Agent. If you want to use -the Agent place the following in @file{~/.gnus.el} if you are -still using 5.8.8 or 5.9 (it's the default since 5.10): - -@example -(setq gnus-agent t) -@end example -@noindent +newsreaders like Forte Agent. It is enabled by default. -Now you've got to select the servers whose groups can be +You've got to select the servers whose groups can be stored locally. To do this, open the server buffer (that is press @samp{^} while in the group buffer). Now select a server by moving point to @@ -2081,10 +1920,9 @@ I can't find anything in the Gnus manual about X @subsubheading Answer There's not only the Gnus manual but also the manuals for message, -emacs-mime, sieve, EasyPG Assistant, and pgg. Those packages are -distributed with Gnus and used by Gnus but aren't really part of core -Gnus, so they are documented in different info files, you should have -a look in those manuals, too. +emacs-mime, sieve, and EasyPG Assistant. Those packages are +distributed with Emacs and used by Gnus. They are documented in +separate info files, so you should have a look in those manuals, too. @node FAQ 8-3 @subsubheading Question 8.3 @@ -2191,12 +2029,12 @@ How to speed up the process of entering a group? @subsubheading Answer -A speed killer is setting the variable -gnus-fetch-old-headers to anything different from @code{nil}, -so don't do this if speed is an issue. +A speed killer is setting the variable @code{gnus-fetch-old-headers} +to anything different from @code{nil}, so don't do this if speed is an +issue. -You could increase the value of gc-cons-threshold -by saying something like +You could increase the value of @code{gc-cons-threshold} by saying +something like: @example (setq gc-cons-threshold 3500000) @@ -2234,10 +2072,6 @@ between core Gnus and the real NNTP-, POP3-, IMAP- or whatever-server which offers Gnus a standardized interface to functions like "get message", "get Headers" etc. -@item Emacs -When the term Emacs is used in this FAQ, it means GNU -Emacs. - @item Message In this FAQ message means either a mail or a posting to a Usenet Newsgroup or to some other fancy back end, no matter diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index 67e9b5a98bd..738ff94b9fc 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -883,10 +883,7 @@ History * Gnus Versions:: What Gnus versions have been released. * Why?:: What's the point of Gnus? -* Compatibility:: Just how compatible is Gnus with @sc{gnus}? * Conformity:: Gnus tries to conform to all standards. -* Emacsen:: Gnus can be run on a few modern Emacsen. -* Gnus Development:: How Gnus is developed. * Contributors:: Oodles of people. * New Features:: Pointers to some of the new stuff in Gnus. @@ -1004,7 +1001,7 @@ The fundamental building blocks of Gnus are @dfn{servers}, @dfn{groups}, and @dfn{articles}. Servers can be local or remote. Each server maintains a list of groups, and those groups contain articles. Because Gnus presents a unified interface to a wide variety -of servers, the vocabulary doesn't always quite line up (see @ref{FAQ +of servers, the vocabulary doesn't always quite line up (@pxref{FAQ - Glossary}, for a more complete glossary). Thus a local maildir is referred to as a ``server'' (@pxref{Finding the News}) the same as a Usenet or IMAP server is; ``groups'' (@pxref{Group Buffer}) might mean @@ -1806,8 +1803,7 @@ long as Gnus is active. @end menu You can customize the Group Mode tool bar, see @kbd{M-x -customize-apropos @key{RET} gnus-group-tool-bar}. This feature is only -available in Emacs. +customize-apropos @key{RET} gnus-group-tool-bar}. The tool bar icons are now (de)activated correctly depending on the cursor position. Therefore, moving around in the Group Buffer is @@ -4499,7 +4495,7 @@ command or better use it as a prefix key. For example: (gnus-group-jump-to-group "nndraft:drafts"))) @end lisp -On keys reserved for users in Emacs and on keybindings in general +On keys reserved for users in Emacs and on key bindings in general @xref{Keymaps, Keymaps, , emacs, The Emacs Editor}. @item ^ @@ -4839,8 +4835,7 @@ group buffer (@pxref{Selecting a Group}). You can have as many summary buffers open as you wish. You can customize the Summary Mode tool bar, see @kbd{M-x -customize-apropos @key{RET} gnus-summary-tool-bar}. This feature is only -available in Emacs. +customize-apropos @key{RET} gnus-summary-tool-bar}. @kindex v @r{(Summary)} @cindex keys, reserved for users (Summary) @@ -8621,14 +8616,6 @@ uuencoded files that have had trailing spaces deleted. @vindex gnus-uu-pre-uudecode-hook Hook run before sending a message to @code{uudecode}. -@item gnus-uu-view-with-metamail -@vindex gnus-uu-view-with-metamail -@cindex metamail -Non-@code{nil} means that @code{gnus-uu} will ignore the viewing -commands defined by the rule variables and just fudge a @acronym{MIME} -content type based on the file name. The result will be fed to -@code{metamail} for viewing. - @item gnus-uu-save-in-digest @vindex gnus-uu-save-in-digest Non-@code{nil} means that @code{gnus-uu}, when asked to save without @@ -9364,9 +9351,6 @@ Use @uref{http://links.twibright.com/, Links}. @item lynx Use @uref{https://lynx.browser.org/, Lynx}. -@item html2text -Use html2text---a simple @acronym{HTML} converter included with Gnus. - @end table @item W D F @@ -9843,6 +9827,13 @@ Gravatarify the @code{From} header (@code{gnus-treat-from-gravatar}). Gravatarify all mail headers (i.e., @code{Cc}, @code{To}) (@code{gnus-treat-from-gravatar}). +@item W D e +@kindex W D e @r{(Summary)} +@findex gnus-article-emojize-symbols +Some symbols have both a non-emoji presentation and an emoji +presentation. This command will make Gnus choose the emoji presentation +(@code{gnus-article-emojize-symbols}). + @item W D D @kindex W D D @r{(Summary)} @findex gnus-article-remove-images @@ -11569,8 +11560,8 @@ things to work: To handle @acronym{PGP} and @acronym{PGP/MIME} messages, you have to install an OpenPGP implementation such as GnuPG@. The Lisp interface to GnuPG included with Emacs is called EasyPG (@pxref{Top, ,EasyPG, -epa, EasyPG Assistant user's manual}), but PGG (@pxref{Top, ,PGG, pgg, -PGG Manual}), and Mailcrypt are also supported. +epa, EasyPG Assistant user's manual}), but Mailcrypt is also +supported. @item To handle @acronym{S/MIME} message, you need to install OpenSSL@. OpenSSL 0.9.6 @@ -11608,18 +11599,16 @@ public-key matching the @samp{From:} header as the recipient; @item mml1991-use @vindex mml1991-use Symbol indicating elisp interface to OpenPGP implementation for -@acronym{PGP} messages. The default is @code{epg}, but @code{pgg}, -and @code{mailcrypt} are also supported although -deprecated. By default, Gnus uses the first available interface in -this order. +@acronym{PGP} messages. The default is @code{epg}, but +@code{mailcrypt} is also supported although deprecated. By default, +Gnus uses the first available interface in this order. @item mml2015-use @vindex mml2015-use Symbol indicating elisp interface to OpenPGP implementation for @acronym{PGP/MIME} messages. The default is @code{epg}, but -@code{pgg}, and @code{mailcrypt} are also supported -although deprecated. By default, Gnus uses the first available -interface in this order. +@code{mailcrypt} is also supported although deprecated. By default, +Gnus uses the first available interface in this order. @end table @@ -12185,6 +12174,7 @@ controlling variable is a predicate list, as described above. @vindex gnus-treat-capitalize-sentences @vindex gnus-treat-overstrike @vindex gnus-treat-strip-cr +@vindex gnus-treat-emojize-symbols @vindex gnus-treat-strip-headers-in-body @vindex gnus-treat-strip-leading-blank-lines @vindex gnus-treat-strip-multiple-blank-lines @@ -12236,6 +12226,7 @@ possible but those listed are probably sufficient for most people. @item gnus-treat-capitalize-sentences (t, integer) @item gnus-treat-overstrike (t, integer) @item gnus-treat-strip-cr (t, integer) +@item gnus-treat-emojize-symbols (t, integer) @item gnus-treat-strip-headers-in-body (t, integer) @item gnus-treat-strip-leading-blank-lines (t, first, integer) @item gnus-treat-strip-multiple-blank-lines (t, integer) @@ -13465,7 +13456,7 @@ Also @pxref{Formatting Variables}. @subsection Server Commands @cindex server commands -The following keybinding are available in the server buffer. Be aware +The following key bindings are available in the server buffer. Be aware that some of the commands will only work on servers that you've added through this interface (with @kbd{a}), not with servers you've defined in your init files. @@ -14829,12 +14820,17 @@ mail belongs in that group. The last of these groups should always be a general one, and the regular expression should @emph{always} be @samp{""} so that it matches any mails that haven't been matched by any of the other regexps. (These rules are -processed from the beginning of the alist toward the end. The first rule -to make a match will ``win'', unless you have crossposting enabled. In -that case, all matching rules will ``win''.) If no rule matched, the mail -will end up in the @samp{bogus} group. When new groups are created by -splitting mail, you may want to run @code{gnus-group-find-new-groups} to -see the new groups. This also applies to the @samp{bogus} group. +processed from the beginning of the alist toward the end. + +If multiple rules match (excluding the general @samp{""} group), mail +is crossposted to all these groups. However, if +@code{nnmail-crosspost} is set to @code{nil}, the first rule to make a +match will ``win''. + +If no rule matched, the mail will end up in the @samp{bogus} group. +When new groups are created by splitting mail, you may want to run +@code{gnus-group-find-new-groups} to see the new groups. This also +applies to the @samp{bogus} group. If you like to tinker with this yourself, you can set this variable to a function of your choice. This function will be called without any @@ -15426,8 +15422,6 @@ files. If a positive number, delete files older than number of days (the deletion will only happen when receiving new mail). You may also set @code{mail-source-delete-incoming} to @code{nil} and call @code{mail-source-delete-old-incoming} from a hook or interactively. -@code{mail-source-delete-incoming} defaults to @code{10} in alpha Gnusae -and @code{2} in released Gnusae. @xref{Gnus Development}. @item mail-source-delete-old-incoming-confirm @vindex mail-source-delete-old-incoming-confirm @@ -15435,10 +15429,6 @@ If non-@code{nil}, ask for confirmation before deleting old incoming files. This variable only applies when @code{mail-source-delete-incoming} is a positive number. -@item mail-source-ignore-errors -@vindex mail-source-ignore-errors -If non-@code{nil}, ignore errors when reading mail from a mail source. - @item mail-source-directory @vindex mail-source-directory Directory where incoming mail source files (if any) will be stored. The @@ -17347,11 +17337,6 @@ changes to a wiki (e.g., @url{https://cliki.net/site/recent-changes}). @acronym{RSS} has a quite regular and nice interface, and it's possible to get the information Gnus needs to keep groups updated. -Note: you had better use Emacs which supports the @code{utf-8} coding -system because @acronym{RSS} uses UTF-8 for encoding non-@acronym{ASCII} -text by default. It is also used by default for non-@acronym{ASCII} -group names. - @kindex G R @r{(Group)} Use @kbd{G R} from the group buffer to subscribe to a feed---you will be prompted for the location, the title and the description of the feed. @@ -17400,7 +17385,7 @@ The directory where @code{nnrss} stores its files. The default is @vindex nnrss-file-coding-system The coding system used when reading and writing the @code{nnrss} groups data files. The default is the value of -@code{mm-universal-coding-system} (which defaults to @code{emacs-mule}). +@code{mm-universal-coding-system} (which defaults to @code{utf-8-emacs}). @item nnrss-ignore-article-fields @vindex nnrss-ignore-article-fields @@ -17508,16 +17493,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. @@ -18040,7 +18025,7 @@ find all messages that have been received recently from certain groups: (list (cons 'query (format-time-string "SENTSINCE %d-%b-%Y" - (time-subtract (current-time) + (time-subtract nil (days-to-time (car args))))) (cons 'criteria ""))) (group-spec (cadr args))) @@ -18068,6 +18053,17 @@ parameter of @code{nnselect-rescan} will allow automatic refreshing. A refresh can always be invoked manually through @code{gnus-group-get-new-news-this-group}. +By default a compressed version of the selection is stored (for +permanent groups) along with other group information in the newsrc. +For cases where this might be undesirable (for example if the +selection is a very long list that doesn't compress well) a +non-@code{nil} group parameter of @code{nnselect-always-regenerate} +will prevent the list from being stored, and instead regenerate the +list each time it is needed. If more flexibility is desired, +@code{nnselect-get-artlist-override-function} and +@code{nnselect-store-artlist-override-function} may be set to +functions that get and store the list of articles. + Gnus includes engines for searching a variety of backends. While the details of each search engine vary, the result of a search is always a vector of the sort used by the nnselect method, and the results of @@ -21630,6 +21626,9 @@ are: @item @code{gnus-search-namazu} + +@item +@code{gnus-search-mu} @end itemize If you need more granularity, you can specify a search engine in the @@ -21644,7 +21643,7 @@ buffer. That might look like: (config-file "/home/user/.mail/.notmuch_config"))) @end example -Search engines like notmuch, namazu and mairix are similar in +Search engines like notmuch, namazu, mairix and mu are similar in behavior: they use a local executable to create an index of a message store, and run command line search queries against those messages, and return a list of absolute file names of matching messages. @@ -21664,7 +21663,9 @@ engine. @item remove-prefix The directory part to be removed from the filenames returned by the search query. This absolute path should include everything up to the -top level of the message store. +top level of the message store. Note that this is the path to the +location of the actual messages, not to the search engine's indexes +(nor, in the case of Mairix, to its symlink directories). @item switches Additional command-line switches to be fed to the search program. The @@ -21681,8 +21682,8 @@ The customization options are formed on the pattern non-standard notmuch program, you might set @code{gnus-search-notmuch-program} to @file{/usr/local/bin/notmuch}. This would apply to all notmuch engines. The engines that use these -options are: ``notmuch'', ``namazu'', ``mairix'', ``swish-e'' and -``swish++''. +options are: ``notmuch'', ``namazu'', ``mairix'', ``mu'', ``swish-e'' +and ``swish++''. Alternately, the options can be set directly on your Gnus server definitions, for instance, in the @code{nnmaildir} example above. @@ -21723,6 +21724,12 @@ articles are drawn. If you want to create a @emph{persistent} group that sticks around after exit from the summary buffer, you can call @code{gnus-group-make-search-group} (bound to @kbd{G g}). +Unlike persistent groups, ephemeral groups by default do not run +articles through the expiry process on exiting. If you want expiry to +happen in ephemeral search groups you can customize the variable +@code{nnselect-allow-ephemeral-expiry}. In all cases the expiry +process uses the underlying group's expiry parameters. + So you just performed a search whose results are so fabulous you wished you had done a persistent search rather than an ephemeral one? No problem; you can create such a group by calling @@ -21930,7 +21937,7 @@ you can set up a local @acronym{IMAP} server, which you then access via @code{nnimap}. This is a rather massive setup for accessing some mbox files, so just change to MH or Maildir already... However, if you're really, really passionate about using mbox, you might want to look into -the package @file{mairix.el}, which comes with Emacs 23. +the package @file{mairix.el}, which comes with Emacs. @node What nnmairix does @subsection What nnmairix does @@ -24129,37 +24136,19 @@ If you want to see them in the Cc and To fields, set: @end lisp -@subsubsection Toolbar +@subsubsection Tool bar @table @code -@item gnus-use-toolbar -@vindex gnus-use-toolbar -This variable specifies the position to display the toolbar. If -@code{nil}, don't display toolbars. If it is non-@code{nil}, it should -be one of the symbols @code{default}, @code{top}, @code{bottom}, -@code{right}, and @code{left}. @code{default} means to use the default -toolbar, the rest mean to display the toolbar on the place which those -names show. The default is @code{default}. - -@item gnus-toolbar-thickness -@vindex gnus-toolbar-thickness -Cons of the height and the width specifying the thickness of a toolbar. -The height is used for the toolbar displayed on the top or the bottom, -the width is used for the toolbar displayed on the right or the left. -The default is that of the default toolbar. - -@item gnus-group-toolbar -@vindex gnus-group-toolbar -The toolbar in the group buffer. - -@item gnus-summary-toolbar -@vindex gnus-summary-toolbar -The toolbar in the summary buffer. +@item gnus-group-tool-bar +@vindex gnus-group-tool-bar +Specifies the tool bar in the group buffer. It can be either a list +or a symbol referring to a list. -@item gnus-summary-mail-toolbar -@vindex gnus-summary-mail-toolbar -The toolbar in the summary buffer of mail groups. +@item gnus-summary-tool-bar +@vindex gnus-summary-tool-bar +Specifies the tool bar in the summary buffer. It can be either a list +or a symbol referring to a list. @end table @@ -24202,8 +24191,7 @@ people have started putting nonsense addresses into their @code{From} lines. I think this is counterproductive---it makes it difficult for people to send you legitimate mail in response to things you write, as well as making it difficult to see who wrote what. This rewriting may -perhaps be a bigger menace than the unsolicited commercial email itself -in the end. +perhaps be a bigger menace than the spam itself in the end. The biggest problem I have with email spam is that it comes in under false pretenses. I press @kbd{g} and Gnus merrily informs me that I @@ -24229,33 +24217,13 @@ This is annoying. Here's what you can do about it. @cindex UCE @cindex unsolicited commercial email -First, some background on spam. - -If you have access to e-mail, you are familiar with spam (technically -termed @acronym{UCE}, Unsolicited Commercial E-mail). Simply put, it -exists because e-mail delivery is very cheap compared to paper mail, -so only a very small percentage of people need to respond to an UCE to -make it worthwhile to the advertiser. Ironically, one of the most -common spams is the one offering a database of e-mail addresses for -further spamming. Senders of spam are usually called @emph{spammers}, -but terms like @emph{vermin}, @emph{scum}, @emph{sociopaths}, and -@emph{morons} are in common use as well. - Spam comes from a wide variety of sources. It is simply impossible to -dispose of all spam without discarding useful messages. A good -example is the TMDA system, which requires senders -unknown to you to confirm themselves as legitimate senders before -their e-mail can reach you. Without getting into the technical side -of TMDA, a downside is clearly that e-mail from legitimate sources may -be discarded if those sources can't or won't confirm themselves -through the TMDA system. Another problem with TMDA is that it -requires its users to have a basic understanding of e-mail delivery -and processing. +dispose of all spam without discarding useful messages. The simplest approach to filtering spam is filtering, at the mail server or when you sort through incoming mail. If you get 200 spam -messages per day from @samp{random-address@@vmadmin.com}, you block -@samp{vmadmin.com}. If you get 200 messages about @samp{VIAGRA}, you +messages per day from @samp{random-address@@example.org}, you block +@samp{example.org}. If you get 200 messages about @samp{VIAGRA}, you discard all messages with @samp{VIAGRA} in the message. If you get lots of spam from Bulgaria, for example, you try to filter all mail from Bulgarian IPs. @@ -24366,7 +24334,7 @@ In my experience, this will sort virtually everything into the right group. You still have to check the @samp{spam} group from time to time to check for legitimate mail, though. If you feel like being a good net citizen, you can even send off complaints to the proper authorities on -each unsolicited commercial email---at your leisure. +each spam---at your leisure. This works for me. It allows people an easy way to contact me (they can just press @kbd{r} in the usual way), and I'm not bothered at all with @@ -24382,8 +24350,8 @@ Be careful with this approach. Spammers are wise to it. @cindex Vipul's Razor @cindex DCC -The days where the hints in the previous section were sufficient in -avoiding spam are coming to an end. There are many tools out there +The days where the hints in the previous section were sufficient to +avoid spam are over. There are many tools out there that claim to reduce the amount of spam you get. This section could easily become outdated fast, as new products replace old, but fortunately most of these tools seem to have similar interfaces. Even @@ -24464,7 +24432,7 @@ spam. And here is the nifty function: @subsection Hashcash @cindex hashcash -A novel technique to fight spam is to require senders to do something +One technique to fight spam is to require senders to do something costly and demonstrably unique for each message they send. This has the obvious drawback that you cannot rely on everyone in the world using this technique, since it is not part of the Internet standards, @@ -25121,8 +25089,8 @@ The @code{gnus-article-sort-by-chars} entry simplifies detection of false positives for me. I receive lots of worms (sweN, @dots{}), that all have a similar size. Grouping them by size (i.e., chars) makes finding other false positives easier. (Of course worms aren't @i{spam} -(@acronym{UCE}, @acronym{UBE}) strictly speaking. Anyhow, bogofilter is -an excellent tool for filtering those unwanted mails for me.) +strictly speaking. Anyhow, bogofilter is an excellent tool for +filtering those unwanted mails for me.) @item @b{Ham folders:} @@ -26764,7 +26732,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 @@ -26903,10 +26871,7 @@ renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs. @menu * Gnus Versions:: What Gnus versions have been released. * Why?:: What's the point of Gnus? -* Compatibility:: Just how compatible is Gnus with @sc{gnus}? * Conformity:: Gnus tries to conform to all standards. -* Emacsen:: Gnus can be run on a few modern Emacsen. -* Gnus Development:: How Gnus is developed. * Contributors:: Oodles of people. * New Features:: Pointers to some of the new stuff in Gnus. @end menu @@ -26986,61 +26951,6 @@ every one of you to explore and invent. May Gnus never be complete. @kbd{C-u 100 M-x all-hail-emacs}. -@node Compatibility -@subsection Compatibility - -@cindex compatibility -Gnus was designed to be fully compatible with @sc{gnus}. Almost all key -bindings have been kept. More key bindings have been added, of course, -but only in one or two obscure cases have old bindings been changed. - -Our motto is: -@quotation -@cartouche -@center In a cloud bones of steel. -@end cartouche -@end quotation - -All commands have kept their names. Some internal functions have changed -their names. - -The @code{gnus-uu} package has changed drastically. @xref{Decoding -Articles}. - -One major compatibility question is the presence of several summary -buffers. All variables relevant while reading a group are -buffer-local to the summary buffer they belong in. Although many -important variables have their values copied into their global -counterparts whenever a command is executed in the summary buffer, this -change might lead to incorrect values being used unless you are careful. - -All code that relies on knowledge of @sc{gnus} internals will probably -fail. To take two examples: Sorting @code{gnus-newsrc-alist} (or -changing it in any way, as a matter of fact) is strictly verboten. Gnus -maintains a hash table that points to the entries in this alist (which -speeds up many functions), and changing the alist directly will lead to -peculiar results. - -Packages like @code{expire-kill} will no longer work. As a matter of -fact, you should probably remove all old @sc{gnus} packages (and other -code) when you start using Gnus. More likely than not, Gnus already -does what you have written code to make @sc{gnus} do. (Snicker.) - -Even though old methods of doing things are still supported, only the -new methods are documented in this manual. If you detect a new method of -doing something while reading this manual, that does not mean you have -to stop doing it the old way. - -Gnus understands all @sc{gnus} startup files. - -@findex gnus-bug -@cindex reporting bugs -@cindex bugs -Overall, a casual user who hasn't written much code that depends on -@sc{gnus} internals should suffer no problems. If problems occur, -please let me know by issuing that magic command @kbd{M-x gnus-bug}. - - @node Conformity @subsection Conformity @@ -27123,79 +27033,6 @@ mentioned above, don't hesitate to drop a note to Gnus Towers and let us know. -@node Emacsen -@subsection Emacsen -@cindex Emacsen -@cindex Mule -@cindex Emacs - -This version of Gnus should work on: - -@itemize @bullet - -@item -Emacs 23.1 and up. - -@end itemize - -This Gnus version will absolutely not work on any Emacsen older than -that. Not reliably, at least. Older versions of Gnus may work on older -Emacs versions. Particularly, Gnus 5.10.8 should also work on Emacs -20.7. - -@c No-merge comment: The paragraph added in v5-10 here must not be -@c synced here! - -@node Gnus Development -@subsection Gnus Development - -Gnus is developed in a two-phased cycle. The first phase involves much -discussion on the development mailing list @samp{ding@@gnus.org}, where people -propose changes and new features, post patches and new back ends. This -phase is called the @dfn{alpha} phase, since the Gnusae released in this -phase are @dfn{alpha releases}, or (perhaps more commonly in other -circles) @dfn{snapshots}. During this phase, Gnus is assumed to be -unstable and should not be used by casual users. Gnus alpha releases -have names like ``Oort Gnus'' and ``No Gnus''. @xref{Gnus Versions}. - -After futzing around for 10--100 alpha releases, Gnus is declared -@dfn{frozen}, and only bug fixes are applied. Gnus loses the prefix, -and is called things like ``Gnus 5.10.1'' instead. Normal people are -supposed to be able to use these, and these are mostly discussed on the -@samp{gnu.emacs.gnus} newsgroup. This newgroup is mirrored to the -mailing list @samp{info-gnus-english@@gnu.org} which is carried on Gmane -as @samp{gmane.emacs.gnus.user}. These releases are finally integrated -in Emacs. - -@cindex Incoming* -@vindex mail-source-delete-incoming -Some variable defaults differ between alpha Gnusae and released Gnusae, -in particular, @code{mail-source-delete-incoming}. This is to prevent -lossage of mail if an alpha release hiccups while handling the mail. -@xref{Mail Source Customization}. - -The division of discussion between the ding mailing list and the Gnus -newsgroup is not purely based on publicity concerns. It's true that -having people write about the horrible things that an alpha Gnus release -can do (sometimes) in a public forum may scare people off, but more -importantly, talking about new experimental features that have been -introduced may confuse casual users. New features are frequently -introduced, fiddled with, and judged to be found wanting, and then -either discarded or totally rewritten. People reading the mailing list -usually keep up with these rapid changes, while people on the newsgroup -can't be assumed to do so. - -So if you have problems with or questions about the alpha versions, -direct those to the ding mailing list @samp{ding@@gnus.org}. This list -is also available on Gmane as @samp{gmane.emacs.gnus.general}. - -@cindex Incoming* -@vindex mail-source-delete-incoming -Some variable defaults differ between alpha Gnusae and released Gnusae, -in particular, @code{mail-source-delete-incoming}. This is to prevent -lossage of mail if an alpha release hiccups while handling the mail. -@xref{Mail Source Customization}. - @node Contributors @subsection Contributors @cindex contributors @@ -28868,7 +28705,7 @@ gnus-agent-cache nil)} reverts to the old behavior. @item Dired integration -@code{gnus-dired-minor-mode} (see @ref{Other modes}) installs key +@code{gnus-dired-minor-mode} (@pxref{Other modes}) installs key bindings in dired buffers to send a file as an attachment, open a file using the appropriate mailcap entry, and print a file using the mailcap entry. @@ -29773,19 +29610,6 @@ Ahem. Make sure your computer is switched on. @item -Make sure that you really load the current Gnus version. If you have -been running @sc{gnus}, you need to exit Emacs and start it up again before -Gnus will work. - -@item -Try doing an @kbd{M-x gnus-version}. If you get something that looks -like @c -@samp{Gnus v5.13} @c Adjust ../Makefile.in if you change this line! -@c -you have the right files loaded. Otherwise you have some old @file{.el} -files lying around. Delete these. - -@item Read the help group (@kbd{G h} in the group buffer) for a @acronym{FAQ} and a how-to. @@ -29793,7 +29617,7 @@ Read the help group (@kbd{G h} in the group buffer) for a @vindex max-lisp-eval-depth Gnus works on many recursive structures, and in some extreme (and very rare) cases Gnus may recurse down ``too deeply'' and Emacs will beep at -you. If this happens to you, set @code{max-lisp-eval-depth} to 500 or +you. If this happens to you, set @code{max-lisp-eval-depth} to 2000 or something like that. @end enumerate @@ -29804,10 +29628,9 @@ If all else fails, report the problem as a bug. @findex gnus-bug If you find a bug in Gnus, you can report it with the @kbd{M-x -gnus-bug} command. @kbd{M-x set-variable @key{RET} debug-on-error -@key{RET} t @key{RET}}, and send me the backtrace. I will fix bugs, -but I can only fix them if you send me a precise description as to how -to reproduce the bug. +gnus-bug} command. @kbd{M-x toggle-debug-on-error}, and send me the +backtrace. I will fix bugs, but I can only fix them if you send me a +precise description as to how to reproduce the bug. You really can never be too detailed in a bug report. Always use the @kbd{M-x gnus-bug} command when you make bug reports, even if it creates @@ -29838,7 +29661,7 @@ edebug. Debugging Lisp code is documented in the Elisp manual (@pxref{Debugging, , Debugging Lisp Programs, elisp, The GNU Emacs Lisp Reference Manual}). To get you started with edebug, consider if you discover some weird behavior when pressing @kbd{c}, the first -step is to do @kbd{C-h k c} and click on the hyperlink (Emacs only) in +step is to do @kbd{C-h k c} and click on the hyperlink in the documentation buffer that leads you to the function definition, then press @kbd{M-x edebug-defun @key{RET}} with point inside that function, return to Gnus and press @kbd{c} to invoke the code. You will be @@ -29850,7 +29673,7 @@ evaluate expressions using @kbd{M-:} or inspect variables using @cindex elp @cindex profile @cindex slow -Sometimes, a problem do not directly generate an elisp error but +Sometimes, a problem do not directly generate an Emacs Lisp error but manifests itself by causing Gnus to be very slow. In these cases, you can use @kbd{M-x toggle-debug-on-quit} and press @kbd{C-g} when things are slow, and then try to analyze the backtrace (repeating the procedure diff --git a/doc/misc/htmlfontify.texi b/doc/misc/htmlfontify.texi index 56f853b0bb2..dabe2e36ff4 100644 --- a/doc/misc/htmlfontify.texi +++ b/doc/misc/htmlfontify.texi @@ -632,7 +632,7 @@ Convert an Emacs :foreground property to a CSS color property. (hfy-flatten-style @var{style}) @end lisp -Take @var{style} (see @ref{hfy-face-to-style-i}, @ref{hfy-face-to-style}) +Take @var{style} (@pxref{hfy-face-to-style-i}, @pxref{hfy-face-to-style}) and merge any multiple attributes appropriately. Currently only font-size is merged down to a single occurrence---others may need special handling, but I haven't encountered them yet. Returns a @ref{hfy-style-assoc}. @@ -840,7 +840,7 @@ See @ref{hfy-display-class} for details of valid values for @var{class}. @end lisp Find face in effect at point P@. If overlays are to be considered -(see @ref{hfy-optimizations}) then this may return a @code{defface} style +(@pxref{hfy-optimizations}) then this may return a @code{defface} style list of face properties instead of a face symbol. @item hfy-bgcol diff --git a/doc/misc/idlwave.texi b/doc/misc/idlwave.texi index 5261f993bc4..0ba87b2e58b 100644 --- a/doc/misc/idlwave.texi +++ b/doc/misc/idlwave.texi @@ -217,7 +217,7 @@ Integrity checks and auto-termination of logical blocks. @item Routine name space conflict search with likelihood-of-use ranking. @item -Support for @file{imenu} (Emacs) and @file{func-menu} (XEmacs). +Support for @file{imenu}. @item Documentation support. @item @@ -2298,12 +2298,11 @@ Regexp matching the start of a document library header. @cindex Motion commands @cindex Program structure, moving through @cindex Code structure, moving through -@cindex @file{Func-menu}, XEmacs package -@cindex @file{Imenu}, Emacs package +@cindex @file{Imenu} @cindex Function definitions, jumping to @cindex Procedure definitions, jumping to -IDLWAVE supports both @file{Imenu} and @file{Func-menu}, two packages +IDLWAVE supports @file{Imenu}, a package which make it easy to jump to the definitions of functions and procedures in the current file with a pop-up selection. To bind @file{Imenu} to a mouse-press, use in your @file{.emacs}: @@ -2670,7 +2669,7 @@ As a special case, any error message in the output will be displayed @node Debugging IDL Programs @section Debugging IDL Programs @cindex Debugging -@cindex Keybindings for debugging +@cindex Key bindings for debugging @cindex Toolbar Programs can be compiled, run, and debugged directly from the source @@ -4117,17 +4116,6 @@ configuration files (e.g., @file{.cshrc}), but from the file @file{~/.MacOSX/environment.plist}. Either include your path settings there, or start Emacs and IDLWAVE from the shell. -@item @strong{I'm getting errors like @samp{Symbol's value as variable is void: -cl-builtin-gethash} on completion or routine info.} - -This error arises if you upgraded Emacs from 20.x to 21.x without -re-installing IDLWAVE@. Old Emacs and new Emacs are not byte-compatible -in compiled lisp files. Presumably, you kept the original .elc files in -place, and this is the source of the error. If you recompile (or just -"make; make install") from source, it should resolve this problem. -Another option is to recompile the @file{idlw*.el} files by hand using -@kbd{M-x byte-compile-file}. - @item @strong{@kbd{M-@key{TAB}} doesn't complete words, it switches windows on my desktop.} diff --git a/doc/misc/ido.texi b/doc/misc/ido.texi index 9e0f8dc8776..c8f9762b553 100644 --- a/doc/misc/ido.texi +++ b/doc/misc/ido.texi @@ -476,13 +476,13 @@ M-x customize-variable @key{RET} ido-xxxxx @key{RET} @end example @vindex ido-setup-hook -To modify the keybindings, use the @code{ido-setup-hook}. For example: +To modify the key bindings, use the @code{ido-setup-hook}. For example: @example (add-hook 'ido-setup-hook 'ido-my-keys) (defun ido-my-keys () - "Add my keybindings for Ido." + "Add my key bindings for Ido." (define-key ido-completion-map " " 'ido-next-match)) @end example diff --git a/doc/misc/info.texi b/doc/misc/info.texi index 98e0dceb5a2..4db35ebf0fc 100644 --- a/doc/misc/info.texi +++ b/doc/misc/info.texi @@ -1083,7 +1083,9 @@ If you aren't sure which manual documents the topic you are looking for, try the @kbd{M-x info-apropos} command in Emacs, or the @kbd{M-x index-apropos} command in the stand-alone reader. It prompts for a string and then looks up that string in all the indices of all the -Info documents installed on your system. +Info documents installed on your system. In Emacs, giving a prefix +argument to the command will try to search for a regular expression +instead of a string. @node Go to node @section @kbd{g} goes to a node by name @@ -1191,8 +1193,9 @@ info-stnd, GNU Info}. The list of directories to search for Info files. Each element is a string (directory name) or @code{nil} (try default directory). If not initialized Info uses the environment variable @env{INFOPATH} to -initialize it, or @code{Info-default-directory-list} if there is no -@env{INFOPATH} variable in the environment. +initialize it, or @code{Info-default-directory-list} in addition to +the value returned by the @code{Info--default-directory-list} function +if there is no @env{INFOPATH} variable in the environment. If you wish to customize the Info directory search list for both Emacs Info and stand-alone Info, it is best to set the @env{INFOPATH} diff --git a/doc/misc/mairix-el.texi b/doc/misc/mairix-el.texi index 4414528f3b3..3632c64bd46 100644 --- a/doc/misc/mairix-el.texi +++ b/doc/misc/mairix-el.texi @@ -60,6 +60,8 @@ database. * Using:: List of interactive functions * Extending:: Support your favorite mail reader! * GNU Free Documentation License:: The license for this documentation. +* Function Index: Function Index. +* Variable Index: Variable Index. @end menu @node About @@ -339,4 +341,14 @@ And that's it! @appendix GNU Free Documentation License @include doclicense.texi +@node Function Index +@unnumbered Function Index + +@printindex fn + +@node Variable Index +@unnumbered Variable Index + +@printindex vr + @bye diff --git a/doc/misc/message.texi b/doc/misc/message.texi index b0510f00373..6a6beb7a1ff 100644 --- a/doc/misc/message.texi +++ b/doc/misc/message.texi @@ -1152,12 +1152,11 @@ programs are required to make things work, and some small general hints. @uref{https://www.gnupg.org/, GNU Privacy Guard} or @uref{https://www.openssl.org/, OpenSSL}. The default Emacs interface to the S/MIME implementation is EasyPG (@pxref{Top,,EasyPG Assistant -User's Manual, epa, EasyPG Assistant User's Manual}), which has been -included in Emacs since version 23 and which relies on the command -line tool @command{gpgsm} provided by @acronym{GnuPG}. That tool -implements certificate management, including certificate revocation -and expiry, while such tasks need to be performed manually, if OpenSSL -is used. +User's Manual, epa, EasyPG Assistant User's Manual}), which is +included in Emacs and relies on the command line tool @command{gpgsm} +provided by @acronym{GnuPG}. That tool implements certificate +management, including certificate revocation and expiry, while such +tasks need to be performed manually, if OpenSSL is used. The choice between EasyPG and OpenSSL is controlled by the variable @code{mml-smime-use}, which needs to be set to the value @code{epg} @@ -1250,8 +1249,8 @@ as @uref{https://www.gnupg.org/, GNU Privacy Guard}. Pre-OpenPGP implementations such as PGP 2.x and PGP 5.x are also supported. The default Emacs interface to the PGP implementation is EasyPG (@pxref{Top,,EasyPG Assistant User's Manual, epa, EasyPG Assistant -User's Manual}), but PGG (@pxref{Top, ,PGG, pgg, PGG Manual}) and -Mailcrypt are also supported. @xref{PGP Compatibility}. +User's Manual}), but Mailcrypt is also supported. @xref{PGP +Compatibility}. As stated earlier, messages encrypted with OpenPGP can be formatted according to two different standards, namely @acronym{PGP} or @@ -1340,8 +1339,7 @@ your PGP implementation, so we refer to it. If you have imported your old PGP 2.x key into GnuPG, and want to send signed and encrypted messages to your fellow PGP 2.x users, you'll discover that the receiver cannot understand what you send. One -solution is to use PGP 2.x instead (e.g., if you use @code{pgg}, set -@code{pgg-default-scheme} to @code{pgp}). You could also convince your +solution is to use PGP 2.x instead. You could also convince your fellow PGP 2.x users to convert to GnuPG@. @vindex mml-signencrypt-style-alist As a final workaround, you can make the sign and encryption work in @@ -2553,6 +2551,22 @@ if @code{nil} let the mailer mail back a message to report errors. When non-@code{nil}, Gnus will ask for confirmation when sending a message. +@item message-server-alist +@vindex message-server-alist +An alist describing the rules for generating the +@code{X-Message-SMTP-Method} header to insert before sending out a new +message, if the message doesn't yet have such a header. Each element +of the alist should be of the form +@w{@code{(@var{cond} . @var{method})}}. If @var{cond} is a string, it +will be compared with the @code{From} header, and if they compare +equal, the corresponding @var{method} will be inserted as a string +into the message headers as the SMTP Method. If @var{cond} is a +function, it will be called in the message buffer without any +arguments, and the corresponding @var{method} will be inserted into +the message headers as the SMTP Method if the function returns a +non-@code{nil} value; if @var{method} is nil, the value returned by +the function @code{cond} is used instead. + @end table diff --git a/doc/misc/mh-e.texi b/doc/misc/mh-e.texi index d42f71a022e..2106c674f37 100644 --- a/doc/misc/mh-e.texi +++ b/doc/misc/mh-e.texi @@ -213,10 +213,8 @@ more niceties about GNU Emacs and MH@. Now I'm fully hooked on both of them. The MH-E package is distributed with Emacs@footnote{Version -@value{VERSION} of MH-E appeared in Emacs 24.4. It is supported in GNU -Emacs 23 and higher, as well as XEmacs 21.4.22 and 21.5.31. MH-E is -known not to work with GNU Emacs versions 20 and below, and XEmacs -version 21.5.9--21.5.16. It is compatible with MH versions 6.8.4 and +@value{VERSION} of MH-E appeared in Emacs 24.4. +It is compatible with MH versions 6.8.4 and higher, all versions of nmh, and GNU mailutils 1.0 and higher}, so you shouldn't have to do anything special to use it. Gnus is also required; version 5.10 or higher is recommended. This manual covers @@ -1018,16 +1016,16 @@ Send multimedia messages (@pxref{Adding Attachments}). Read HTML messages (@pxref{HTML}). @c ------------------------- @item -Use aliases and identities (see @ref{Aliases}, @pxref{Identities}). +Use aliases and identities (@pxref{Aliases}, @pxref{Identities}). @c ------------------------- @item -Create different views of your mail (see @ref{Threading}, @pxref{Limits}). +Create different views of your mail (@pxref{Threading}, @pxref{Limits}). @c ------------------------- @item Deal with junk mail (@pxref{Junk}). @c ------------------------- @item -Handle signed and encrypted messages (see @ref{Reading PGP}, +Handle signed and encrypted messages (@pxref{Reading PGP}, @pxref{Sending PGP}). @c ------------------------- @item @@ -1038,7 +1036,7 @@ Process mail that was sent with @command{shar} or @command{uuencode} Use sequences conveniently (@pxref{Sequences}). @c ------------------------- @item -Use the speedbar, tool bar, and menu bar (see @ref{Speedbar}, see @ref{Tool +Use the speedbar, tool bar, and menu bar (@pxref{Speedbar}, @pxref{Tool Bar}, @pxref{Menu Bar}). @c ------------------------- @item @@ -1490,7 +1488,7 @@ Binding} of @samp{m}. @cindex Unix commands, @command{xbuffy} You can use @command{xbuffy} to automate the incorporation of this -mail using the Emacs 23 command @command{emacsclient} as follows: +mail using the Emacs command @command{emacsclient} as follows: @smallexample box ~/mail/mh-e @@ -1501,9 +1499,6 @@ box ~/mail/mh-e command emacsclient --eval '(mh-inc-spool-mh-e)' @end smallexample -In XEmacs, the command @command{gnuclient} is used in a similar -fashion. - @findex mh-inc-folder @kindex i @vindex mh-inc-folder-hook @@ -2090,8 +2085,7 @@ and @samp{X-Image-URL:} will be used. The option This feature will be turned on by default if your system supports it. The first header field used, if present, is the Gnus-specific -@samp{Face:} field@footnote{The @samp{Face:} field appeared in GNU -Emacs 21 and XEmacs. For more information, see +@samp{Face:} field@footnote{For more information, see @uref{https://quimby.gnus.org/circus/face/}.}. @cindex @command{uncompface} @@ -2104,12 +2098,9 @@ Emacs 21 and XEmacs. For more information, see Next is the traditional @samp{X-Face:} header field@footnote{The display of this field requires the @uref{ftp://ftp.cs.indiana.edu/pub/faces/compface/compface.tar.Z, -@command{uncompface} program}. Recent versions of XEmacs have internal -support for @samp{X-Face:} images. If your version of XEmacs does not, -then you'll need both @command{uncompface} and the -@uref{http://www.jpl.org/ftp/pub/elisp/, @samp{x-face} package}.}. MH-E -renders the foreground and background of the image using the -associated attributes of the face @code{mh-show-xface}. +@command{uncompface} program}.} MH-E renders the foreground and +background of the image using the associated attributes of the face +@code{mh-show-xface}. @cindex @command{convert} @cindex @command{wget} @@ -2562,13 +2553,6 @@ produces pretty nice output, and it highlights links. It renders @samp{–} and @samp{®} okay. It sometimes fails to wrap lines properly. It always downloads remote images. @c ------------------------- -@cindex browser, @samp{html2text} -@cindex @samp{html2text} -@item @samp{html2text} -The @samp{html2text} browser requires an external program. Some users -have reported problems with it, such as filling the entire message as -if it were one paragraph, or displaying chunks of raw HTML. -@c ------------------------- @cindex browser, @samp{links} @cindex @samp{links} @item @samp{links} @@ -2830,24 +2814,6 @@ The appearance of the buttons is controlled by the faces @code{mh-show-pgg-unknown} depending on the validity of the signature. The latter is used whether the signature is unknown or untrusted. -@cindex @samp{pgg} customization group -@cindex PGG -@cindex customization group, @samp{pgg} - -The @samp{pgg} customization group may have some settings which may -interest you. -@iftex -See @cite{The PGG Manual}. -@end iftex -@ifinfo -@xref{Top, , The PGG Manual, pgg, The PGG Manual}. -@end ifinfo -@ifhtml -See -@uref{https://www.gnu.org/software/emacs/manual/pgg.html, -@cite{The PGG Manual}}. -@end ifhtml - @node Printing @section Printing Your Mail @@ -5594,33 +5560,6 @@ variety of mail security mechanisms. The default is @samp{PGP (MIME)} if it is supported; otherwise, the default is @samp{None}. Other mechanisms include vanilla @samp{PGP} and @samp{S/MIME}. -@cindex @samp{pgg} customization group -@cindex PGG -@cindex customization group, @samp{pgg} - -The @samp{pgg} customization group may have some settings which may -interest you. -@iftex -See @cite{The PGG Manual}. -@end iftex -@ifinfo -@xref{Top, , The PGG Manual, pgg, The PGG Manual}. -@end ifinfo -@ifhtml -See -@uref{https://www.gnu.org/software/emacs/manual/pgg.html, -@cite{The PGG Manual}}. -@end ifhtml - -@cindex header field, @samp{Fcc} -@cindex @samp{Fcc} header field -@vindex pgg-encrypt-for-me - -In particular, I turn on the option @code{pgg-encrypt-for-me} so that -all messages I encrypt are encrypted with my public key as well. If -you keep a copy of all of your outgoing mail with a @samp{Fcc:} header -field, this setting is vital so that you can read the mail you write! - @node Checking Recipients @section Checking Recipients @@ -6448,17 +6387,9 @@ too long to list here). @item mh-tool-bar-search-function Function called by the tool bar search button (default: @code{mh-search}). -@c ------------------------- -@item mh-xemacs-tool-bar-position -Tool bar location (default: @samp{Same As Default Tool Bar}). -@c ------------------------- -@item mh-xemacs-use-tool-bar-flag -If @samp{on}, use tool bar (default: @samp{on}, if supported). @end vtable -In GNU Emacs, icons for some of MH-E's functions are added to the tool -bar. In XEmacs, you have the opportunity to create a separate tool bar for -the MH-E icons. +Icons for some of MH-E's functions are added to the tool bar. @vindex mh-tool-bar-folder-buttons @vindex mh-tool-bar-letter-buttons @@ -6480,24 +6411,6 @@ option @code{mh-tool-bar-search-function}. By default, this is set to Function} from the @samp{Value Menu} and enter a function of your own choosing. -@vindex mh-xemacs-use-tool-bar-flag - -XEmacs provides a couple of extra options. The first, -@code{mh-xemacs-use-tool-bar-flag}, controls whether to show the MH-E -icons at all. By default, this option is turned on if the window -system supports tool bars. If your system doesn't support tool bars, -then you won't be able to turn on this option. - -@vindex mh-xemacs-tool-bar-position - -The second extra option is @code{mh-xemacs-tool-bar-position} which -controls the placement of the tool bar along the four edges of the -frame. You can choose from one of @samp{Same As Default Tool Bar}, -@samp{Top}, @samp{Bottom}, @samp{Left}, or @samp{Right}. If this -variable is set to anything other than @samp{Same As Default Tool Bar} -and the default tool bar is in a different location, then two tool -bars will be displayed: the MH-E tool bar and the default tool bar. - @node Searching @chapter Searching Through Messages diff --git a/doc/misc/modus-themes.org b/doc/misc/modus-themes.org index 5451f806736..1b4bf88a0cc 100644 --- a/doc/misc/modus-themes.org +++ b/doc/misc/modus-themes.org @@ -1,25 +1,23 @@ -#+title: Modus themes for GNU Emacs -#+author: Protesilaos Stavrou -#+email: info@protesilaos.com -#+language: en -#+options: ':t toc:nil author:t email:t num:t -#+startup: content - -#+macro: stable-version 1.6.0 -#+macro: release-date 2021-09-29 -#+macro: development-version 1.7.0-dev -#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@ -#+macro: space @@texinfo:@: @@ -#+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@ - -#+texinfo_filename: modus-themes.info -#+texinfo_dir_category: Emacs misc features -#+texinfo_dir_title: Modus Themes: (modus-themes) -#+texinfo_dir_desc: Highly accessible themes (WCAG AAA) -#+texinfo_header: @set MAINTAINERSITE @uref{https://protesilaos.com,maintainer webpage} -#+texinfo_header: @set MAINTAINER Protesilaos Stavrou -#+texinfo_header: @set MAINTAINEREMAIL @email{info@protesilaos.com} -#+texinfo_header: @set MAINTAINERCONTACT @uref{mailto:info@protesilaos.com,contact the maintainer} +#+title: Modus themes for GNU Emacs +#+author: Protesilaos Stavrou +#+email: info@protesilaos.com +#+language: en +#+options: ':t toc:nil author:t email:t num:t +#+startup: content +#+macro: stable-version 2.6.0 +#+macro: release-date 2022-08-19 +#+macro: development-version 2.7.0-dev +#+macro: file @@texinfo:@file{@@$1@@texinfo:}@@ +#+macro: space @@texinfo:@: @@ +#+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@ +#+texinfo_filename: modus-themes.info +#+texinfo_dir_category: Emacs misc features +#+texinfo_dir_title: Modus Themes: (modus-themes) +#+texinfo_dir_desc: Elegant, highly legible and customizable themes +#+texinfo_header: @set MAINTAINERSITE @uref{https://protesilaos.com,maintainer webpage} +#+texinfo_header: @set MAINTAINER Protesilaos Stavrou +#+texinfo_header: @set MAINTAINEREMAIL @email{info@protesilaos.com} +#+texinfo_header: @set MAINTAINERCONTACT @uref{mailto:info@protesilaos.com,contact the maintainer} #+texinfo: @insertcopying @@ -34,6 +32,10 @@ explicitly marked as such. Current development target is {{{development-version}}}. ++ Homepage: https://protesilaos.com/emacs/modus-themes. ++ Git repository: https://git.sr.ht/~protesilaos/modus-themes. ++ Mailing list: https://lists.sr.ht/~protesilaos/modus-themes. + #+toc: headlines 8 insert TOC here, with eight headline levels * COPYING @@ -42,7 +44,7 @@ Current development target is {{{development-version}}}. :custom_id: h:b14c3fcb-13dd-4144-9d92-2c58b3ed16d3 :end: -Copyright (C) 2020-2022 Free Software Foundation, Inc. +Copyright (C) 2020-2022 Free Software Foundation, Inc. #+begin_quote Permission is granted to copy, distribute and/or modify this document @@ -82,9 +84,22 @@ themes strive to achieve as close to full face coverage as possible ([[#h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19][Face coverage]]). Furthermore, the themes are designed to empower users with red-green -color deficiency (deuteranopia). This is achieved through customization -options which have the effect of replacing all relevant instances of -green with a variant of blue ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]). +color deficiency (deuteranopia). This is achieved in three ways: + +1. The conformance with the highest legibility standard means that text + is always readable no matter the perception of its hue. + +2. Most contexts use colors on the blue-cyan-magenta-purple side of the + spectrum. Put differently, green and/or red are seldom used, thus + minimizing the potential for confusion. + + [[#h:0b26cb47-9733-4cb1-87d9-50850cb0386e][Why are colors mostly variants of blue, magenta, cyan?]]. + +3. In contexts where a red/green color-coding is unavoidable, we provide + a universal toggle to customize the themes so that a red/blue scheme + is used instead. + + [[#h:3ed03a48-20d8-4ce7-b214-0eb7e4c79abe][Option for red-green color deficiency or deuteranopia]]. Starting with version 0.12.0 and onwards, the themes are built into GNU Emacs. @@ -95,7 +110,7 @@ Emacs. :end: #+cindex: Screenshots -Check the web page with [[https://protesilaos.com/modus-themes-pictures/][the screen shots]]. There are lots of scenarios +Check the web page with [[https://protesilaos.com/emacs/modus-themes-pictures/][the screen shots]]. There are lots of scenarios on display that draw attention to details and important aspects in the design of the themes. They also showcase the numerous customization options. @@ -108,7 +123,7 @@ options. :end: #+cindex: Changelog -Please refer to the [[https://protesilaos.com/modus-themes-changelog][web page with the change log]]. It is comprehensive +Please refer to the [[https://protesilaos.com/emacs/modus-themes-changelog][web page with the change log]]. It is comprehensive and covers everything that goes into every tagged release of the themes. * Installation @@ -152,14 +167,10 @@ The themes are now ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][ The ~modus-themes~ package is available from the GNU ELPA archive, which is configured by default. -Prior to querying any package archive, make sure to have updated the -index, with {{{kbd(M-x package-refresh-contents)}}}. Then all you need to do +Prior to querying any package archive, make sure to update the index, +with {{{kbd(M-x package-refresh-contents)}}}. Then all you need to do is type {{{kbd(M-x package-install)}}} and specify the ~modus-themes~. -Note that older versions of the themes used to be distributed as -standalone packages. This practice has been discontinued starting with -version 1.0.0 of this project. - Once installed, the themes are ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]. ** Install on GNU/Linux @@ -185,6 +196,9 @@ sudo apt install elpa-modus-themes They are now ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]. +NOTE that Debian's package is severely out-of-date as of this writing +2022-07-24 09:57 +0300. + *** GNU Guix :properties: :custom_id: h:a4ca52cd-869f-46a5-9e16-4d9665f5b88e @@ -198,6 +212,34 @@ guix package -i emacs-modus-themes They are now ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]. +** Dealing with byte compilation errors +:properties: +:custom_id: h:e6268471-e847-4c9d-998f-49a83257b7f1 +:end: + +From time to time, we receive bug reports pertaining to errors with byte +compilation. These seldom have to do with faulty code in the themes: it +might be a shortcoming of =package.el=, some regression in the current +development target of Emacs, a misconfiguration in an otherwise exotic +setup, and the like. + +The common solution with a stable version of Emacs is to: + +1. Delete the =modus-themes= package. +2. Close the current Emacs session. +3. Install the =modus-themes= again. + +For those building Emacs directly from source, the solution may involve +reverting to an earlier commit in emacs.git. + +At any rate, if you encounter such an issue please report it: we will +either fix the bug on our end if it is truly ours, or help forward it to +the relevant upstream maintainer. Whatever you do, please understand +that a build failure does not mean we are necessarily doing something +wrong. + +[[#h:6536c8d5-3f98-43ab-a787-b94120e735e8][Issues you can help with]]. + * Enable and load :properties: :custom_id: h:3f3c3728-1b34-437d-9d0c-b110f5b161a9 @@ -209,16 +251,16 @@ They are now ready to be used: [[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable #+cindex: Essential configuration #+vindex: modus-themes-after-load-theme-hook -Users of the built-in themes can load and automatically enable the theme -of their preference by adding either form to their init file: +Users of the built-in themes cannot ~require~ the package as usual +because there is no package to speak of. Instead, things are simpler as +all one needs is to load the theme of their preference by adding either +form to their init file: #+begin_src emacs-lisp (load-theme 'modus-operandi) ; Light theme (load-theme 'modus-vivendi) ; Dark theme #+end_src -This is all one needs. - Users of packaged variants of the themes must add a few more lines to ensure that everything works as intended. First, one has to require the main library before loading either theme: @@ -247,28 +289,43 @@ a theme with either of the following expressions: Changes to the available customization options must always be evaluated before loading a theme ([[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization Options]]). An exception to this norm is when using the various Custom interfaces or with commands like -{{{kbd(M-x customize-set-variable)}}}, which automatically reload the theme by -default ([[#h:9001527a-4e2c-43e0-98e8-3ef72d770639][Option for inhibiting theme reload]]). This is how a basic setup -could look like: +{{{kbd(M-x customize-set-variable)}}}, which can optionally +automatically reload the theme ([[#h:9001527a-4e2c-43e0-98e8-3ef72d770639][Option for inhibiting theme reload]]). + +This is how a basic setup could look like: #+begin_src emacs-lisp +;;; For the built-in themes which cannot use `require': +;; Add all your customizations prior to loading the themes +(setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil + modus-themes-region '(bg-only no-extend)) + +;; Load the theme of your choice: +(load-theme 'modus-operandi) ;; OR (load-theme 'modus-vivendi) + +(define-key global-map (kbd "<f5>") #'modus-themes-toggle) + + + +;;; For packaged versions which must use `require': (require 'modus-themes) -;; Your customisations here. For example: -(setq modus-themes-bold-constructs t - modus-themes-mode-line '3d) +;; Add all your customizations prior to loading the themes +(setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil + modus-themes-region '(bg-only no-extend)) -;; Load the theme files before enabling a theme (else you get an error). +;; Load the theme files before enabling a theme (modus-themes-load-themes) -;; Enable the theme of your preference: -(modus-themes-load-operandi) +;; Load the theme of your choice: +(modus-themes-load-operandi) ;; OR (modus-themes-load-vivendi) -;; Optionally add a key binding for the toggle between the themes: (define-key global-map (kbd "<f5>") #'modus-themes-toggle) #+end_src -[[#h:e979734c-a9e1-4373-9365-0f2cd36107b8][Sample configuration for use-package]]. +[[#h:e979734c-a9e1-4373-9365-0f2cd36107b8][Sample configuration with and without use-package]]. With those granted, bear in mind a couple of technical points on ~modus-themes-load-operandi~ and ~modus-themes-load-vivendi~, as well as @@ -279,29 +336,45 @@ With those granted, bear in mind a couple of technical points on 2. The functions will run the ~modus-themes-after-load-theme-hook~ as their final step. This can be employed for bespoke configurations - ([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]). Experienced users may not wish to rely - on such a hook and the functions that run it: they may prefer a - custom solution ([[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme loading]]). + ([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]). Experienced users may not wish to rely on + such a hook and the functions that run it: they may prefer a custom + solution ([[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme loading]]). -** Sample configuration for use-package +** Sample configuration with and without use-package :properties: :custom_id: h:e979734c-a9e1-4373-9365-0f2cd36107b8 :end: #+cindex: use-package configuration +#+cindex: sample configuration It is common for Emacs users to rely on ~use-package~ for declaring package configurations in their setup. We use this as an example: #+begin_src emacs-lisp +;;; For the built-in themes which cannot use `require': +(use-package emacs + :init + ;; Add all your customizations prior to loading the themes + (setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil + modus-themes-region '(bg-only no-extend)) + :config + ;; Load the theme of your choice: + (load-theme 'modus-operandi) ;; OR (load-theme 'modus-vivendi) + :bind ("<f5>" . modus-themes-toggle)) + + + +;;; For packaged versions which must use `require': (use-package modus-themes - :ensure ; omit this to use the built-in themes + :ensure :init ;; Add all your customizations prior to loading the themes (setq modus-themes-italic-constructs t modus-themes-bold-constructs nil modus-themes-region '(bg-only no-extend)) - ;; Load the theme files before enabling a theme (else you get an error). + ;; Load the theme files before enabling a theme (modus-themes-load-themes) :config ;; Load the theme of your choice: @@ -309,6 +382,39 @@ package configurations in their setup. We use this as an example: :bind ("<f5>" . modus-themes-toggle)) #+end_src +The same without ~use-package~: + +#+begin_src emacs-lisp +;;; For the built-in themes which cannot use `require': +;; Add all your customizations prior to loading the themes +(setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil + modus-themes-region '(bg-only no-extend)) + +;; Load the theme of your choice: +(load-theme 'modus-operandi) ;; OR (load-theme 'modus-vivendi) + +(define-key global-map (kbd "<f5>") #'modus-themes-toggle) + + + +;;; For packaged versions which must use `require': +(require 'modus-themes) + +;; Add all your customizations prior to loading the themes +(setq modus-themes-italic-constructs t + modus-themes-bold-constructs nil + modus-themes-region '(bg-only no-extend)) + +;; Load the theme files before enabling a theme +(modus-themes-load-themes) + +;; Load the theme of your choice: +(modus-themes-load-operandi) ;; OR (modus-themes-load-vivendi) + +(define-key global-map (kbd "<f5>") #'modus-themes-toggle) +#+end_src + [[#h:e68560b3-7fb0-42bc-a151-e015948f8a35][Differences between loading and enabling]]. Note: make sure not to customize the variable ~custom-theme-load-path~ @@ -325,7 +431,7 @@ package declaration of the themes. The reason we recommend ~load-theme~ instead of the other option of ~enable-theme~ is that the former does a kind of "reset" on the face -specs. It quite literally loads (or re-loads) the theme. Whereas the +specs. It quite literally loads (or reloads) the theme. Whereas the latter simply puts an already loaded theme at the top of the list of enabled items, re-using whatever state was last loaded. @@ -339,9 +445,9 @@ it might appear to the unsuspecting user that the themes are somehow broken whenever they try to assign a new value to a customization option or some face. -This "reset" that ~load-theme~ conducts does, however, come at the cost -of being somewhat slower than ~enable-theme~. Users who have a stable -setup and who seldom update their variables during a given Emacs +This "reset" that ~load-theme~ brings about does, however, come at the +cost of being somewhat slower than ~enable-theme~. Users who have a +stable setup and who seldom update their variables during a given Emacs session, are better off using something like this: #+begin_src emacs-lisp @@ -352,7 +458,9 @@ session, are better off using something like this: (enable-theme 'modus-operandi) ;; OR (enable-theme 'modus-vivendi) #+end_src -[[#h:e979734c-a9e1-4373-9365-0f2cd36107b8][Sample configuration for use-package]]. +[[#h:b40aca50-a3b2-4c43-be58-2c26fcd14237][Toggle themes without reloading them]]. + +[[#h:e979734c-a9e1-4373-9365-0f2cd36107b8][Sample configuration with and without use-package]]. With the above granted, other sections of the manual discuss how to configure custom faces, where ~load-theme~ is expected, though @@ -372,7 +480,8 @@ without any further tweaks. By default, all customization options are set to nil, unless otherwise noted in this manual. Remember that all customization options must be evaluated before loading -a theme ([[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]). +a theme ([[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]). If the theme is already active, it must be +reloaded for changes in user options to come into force. Below is a summary of what you will learn in the subsequent sections of this manual. @@ -380,10 +489,12 @@ this manual. #+begin_src emacs-lisp (setq modus-themes-italic-constructs t modus-themes-bold-constructs nil - modus-themes-no-mixed-fonts nil + modus-themes-mixed-fonts nil modus-themes-subtle-line-numbers nil - modus-themes-success-deuteranopia t + modus-themes-intense-mouseovers nil + modus-themes-deuteranopia t modus-themes-tabs-accented t + modus-themes-variable-pitch-ui nil modus-themes-inhibit-reload t ; only applies to `customize-set-variable' and related modus-themes-fringes nil ; {nil,'subtle,'intense} @@ -391,13 +502,24 @@ this manual. ;; Options for `modus-themes-lang-checkers' are either nil (the ;; default), or a list of properties that may include any of those ;; symbols: `straight-underline', `text-also', `background', - ;; `intense' + ;; `intense' OR `faint'. modus-themes-lang-checkers nil ;; Options for `modus-themes-mode-line' are either nil, or a list ;; that can combine any of `3d' OR `moody', `borderless', - ;; `accented', `padded'. - modus-themes-mode-line '(padded accented borderless) + ;; `accented', a natural number for extra padding (or a cons cell + ;; of padding and NATNUM), and a floating point for the height of + ;; the text relative to the base font size (or a cons cell of + ;; height and FLOAT) + modus-themes-mode-line '(accented borderless (padding . 4) (height . 0.9)) + + ;; Same as above: + ;; modus-themes-mode-line '(accented borderless 4 0.9) + + ;; Options for `modus-themes-markup' are either nil, or a list + ;; that can combine any of `bold', `italic', `background', + ;; `intense'. + modus-themes-markup '(background italic) ;; Options for `modus-themes-syntax' are either nil (the default), ;; or a list of properties that may include any of those symbols: @@ -420,46 +542,59 @@ this manual. ;; `bold', `italic', `background' modus-themes-links '(neutral-underline background) + ;; Options for `modus-themes-box-buttons' are either nil (the + ;; default), or a list that can combine any of `flat', `accented', + ;; `faint', `variable-pitch', `underline', `all-buttons', the + ;; symbol of any font weight as listed in `modus-themes-weights', + ;; and a floating point number (e.g. 0.9) for the height of the + ;; button's text. + modus-themes-box-buttons '(variable-pitch flat faint 0.9) + ;; Options for `modus-themes-prompts' are either nil (the ;; default), or a list of properties that may include any of those ;; symbols: `background', `bold', `gray', `intense', `italic' modus-themes-prompts '(intense bold) - modus-themes-completions 'moderate ; {nil,'moderate,'opinionated} - - modus-themes-mail-citations nil ; {nil,'faint,'monochrome} + ;; The `modus-themes-completions' is an alist that reads three + ;; keys: `matches', `selection', `popup'. Each accepts a nil + ;; value (or empty list) or a list of properties that can include + ;; any of the following (for WEIGHT read further below): + ;; + ;; `matches' - `background', `intense', `underline', `italic', WEIGHT + ;; `selection' - `accented', `intense', `underline', `italic', `text-also' WEIGHT + ;; `popup' - same as `selected' + ;; `t' - applies to any key not explicitly referenced (check docs) + ;; + ;; WEIGHT is a symbol such as `semibold', `light', or anything + ;; covered in `modus-themes-weights'. Bold is used in the absence + ;; of an explicit WEIGHT. + modus-themes-completions '((matches . (extrabold)) + (selection . (semibold accented)) + (popup . (accented intense))) + + modus-themes-mail-citations nil ; {nil,'intense,'faint,'monochrome} ;; Options for `modus-themes-region' are either nil (the default), ;; or a list of properties that may include any of those symbols: ;; `no-extend', `bg-only', `accented' modus-themes-region '(bg-only no-extend) - ;; Options for `modus-themes-diffs': nil, 'desaturated, - ;; 'bg-only, 'deuteranopia, 'fg-only-deuteranopia - modus-themes-diffs 'fg-only-deuteranopia + ;; Options for `modus-themes-diffs': nil, 'desaturated, 'bg-only + modus-themes-diffs 'desaturated modus-themes-org-blocks 'gray-background ; {nil,'gray-background,'tinted-background} modus-themes-org-agenda ; this is an alist: read the manual or its doc string - '((header-block . (variable-pitch scale-title)) - (header-date . (grayscale workaholic bold-today)) - (event . (accented scale-small)) + '((header-block . (variable-pitch 1.3)) + (header-date . (grayscale workaholic bold-today 1.1)) + (event . (accented varied)) (scheduled . uniform) - (habit . traffic-light-deuteranopia)) + (habit . traffic-light)) modus-themes-headings ; this is an alist: read the manual or its doc string - '((1 . (overline background)) - (2 . (rainbow overline)) - (t . (no-bold))) - - modus-themes-variable-pitch-ui nil - modus-themes-variable-pitch-headings t - modus-themes-scale-headings t - modus-themes-scale-1 1.1 - modus-themes-scale-2 1.15 - modus-themes-scale-3 1.21 - modus-themes-scale-4 1.27 - modus-themes-scale-title 1.33) + '((1 . (overline background variable-pitch 1.3)) + (2 . (rainbow overline 1.1)) + (t . (semibold)))) #+end_src ** Option for inhibiting theme reload @@ -470,7 +605,10 @@ this manual. :end: #+vindex: modus-themes-inhibit-reload -Symbol: ~modus-themes-inhibit-reload~ +Brief: Toggle reloading of the active theme when an option is changed +through the Customize UI. + +Symbol: ~modus-themes-inhibit-reload~ (=boolean= type) Possible values: @@ -483,35 +621,43 @@ currently active Modus theme. Enable this behavior by setting this variable to ~nil~. -** Option for color-coding success state +Regardless of this option, the active theme must be reloaded for changes +to user options to take effect ([[#h:3f3c3728-1b34-437d-9d0c-b110f5b161a9][Enable and load]]). + +** Option for red-green color deficiency or deuteranopia :properties: -:alt_title: Success' color-code -:description: Toggle blue color for success or done states +:alt_title: Deuteranopia style +:description: Toggle red/blue color-coding instead of red/green :custom_id: h:3ed03a48-20d8-4ce7-b214-0eb7e4c79abe :end: -#+vindex: modus-themes-success-deuteranopia +#+vindex: modus-themes-deuteranopia + +Brief: When non-nil use red/blue color-coding instead of red/green, +where appropriate. -Symbol: ~modus-themes-success-deuteranopia~ +Symbol: ~modus-themes-deuteranopia~ (=boolean= type) Possible values: 1. ~nil~ (default) 2. ~t~ -The default is to colorise all faces that denote "success", "done", or -similar with a variant of green. - -With a non-nil value (~t~), use variants of blue instead of green. This -is meant to empower users with red-green color deficiency. - -The present customization option should apply to all contexts where -there can be a color-coded distinction between success and failure, -to-do and done, and so on. +This is to account for red-green color deficiency, also know as +deuteranopia and variants. It applies to all contexts where there can +be a color-coded distinction between failure or success, a to-do or done +state, a mark for deletion versus a mark for selection (e.g. in Dired), +current and lazily highlighted search matches, removed lines in diffs as +opposed to added ones, and so on. -Diffs, which have a red/green dichotomy by default, can also be -configured to conform with deuteranopia. +Note that this does not change all colors throughout the active theme, +but only applies to cases that have color-coding significance. For +example, regular code syntax highlighting is not affected. There is no +such need because of the themes' overarching commitment to the highest +legibility standard, which ensures that text is readable regardless of +hue, as well as the predominance of colors on the +blue-cyan-magenta-purple side of the spectrum. -[[#h:ea7ac54f-5827-49bd-b09f-62424b3b6427][Option for diff buffer looks]]. +[[#h:0b26cb47-9733-4cb1-87d9-50850cb0386e][Why are colors mostly variants of blue, magenta, cyan?]]. ** Option for more bold constructs :properties: @@ -521,7 +667,9 @@ configured to conform with deuteranopia. :end: #+vindex: modus-themes-bold-constructs -Symbol: ~modus-themes-bold-constructs~ +Brief: Use bold for code syntax highlighting and related. + +Symbol: ~modus-themes-bold-constructs~ (=boolean= type) Possible values: @@ -549,7 +697,9 @@ Advanced users may also want to configure the exact attributes of the :end: #+vindex: modus-themes-italic-constructs -Symbol: ~modus-themes-italic-constructs~ +Brief: Use italics for code syntax highlighting and related. + +Symbol: ~modus-themes-italic-constructs~ (=boolean= type) Possible values: @@ -575,7 +725,9 @@ Advanced users may also want to configure the exact attributes of the :end: #+vindex: modus-themes-syntax -Symbol: ~modus-themes-syntax~ +Brief: Set the overall style of code syntax highlighting. + +Symbol: ~modus-themes-syntax~ (=choice= type, list of properties) Possible values are expressed as a list of properties (default is ~nil~ or an empty list). The list can include any of the following symbols: @@ -629,45 +781,52 @@ weight or italic text: ~modus-themes-bold-constructs~ and [[#h:977c900d-0d6d-4dbb-82d9-c2aae69543d6][Option for more italic constructs]]. -** Option for no font mixing +** Option for font mixing :properties: -:alt_title: No mixed fonts +:alt_title: Mixed fonts :description: Toggle mixing of font families :custom_id: h:115e6c23-ee35-4a16-8cef-e2fcbb08e28b :end: -#+vindex: modus-themes-no-mixed-fonts +#+vindex: modus-themes-mixed-fonts + +Brief: Toggle the use of monospaced fonts for spacing-sensitive +constructs (affects font families). -Symbol: ~modus-themes-no-mixed-fonts~ +Symbol: ~modus-themes-mixed-fonts~ (=boolean= type) Possible values: 1. ~nil~ (default) 2. ~t~ -By default, the themes configure some spacing-sensitive faces like Org +When set to non-nil (~t~), configure some spacing-sensitive faces like Org tables and code blocks to always inherit from the ~fixed-pitch~ face. -This is to ensure that those constructs remain monospaced even when -users opt for a mode that remaps typeface families, such as the built-in -{{{kbd(M-x variable-pitch-mode)}}}. Otherwise the layout would appear -broken, due to how spacing is done. To disable this behavior, set the -option to ~t~. +This is to ensure that certain constructs like code blocks and tables +remain monospaced even when users opt for a mode that remaps typeface +families, such as the built-in {{{kbd(M-x variable-pitch-mode)}}}. Otherwise +the layout would appear broken, due to how spacing is done. -Users may prefer to use another package for handling mixed typeface -configurations, rather than letting the theme do it, perhaps because a -purpose-specific package has extra functionality. Two possible options -are ~org-variable-pitch~ and ~mixed-pitch~. +For a consistent experience, user may need to specify the font family of +the ~fixed-pitch~ face. [[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. +Furthermore, users may prefer to use another package for handling mixed +typeface configurations, rather than letting the theme do it, perhaps +because a purpose-specific package has extra functionality. Two +possible options are ~org-variable-pitch~ and ~mixed-pitch~. + ** Option for links :properties: :alt_title: Link styles :description: Choose among several styles, with or without underline -:custom_id: h:c119d7b2-fcd4-4e44-890e-5e25733d5e52 +:custom_id: h:5808be52-361a-4d18-88fd-90129d206f9b :end: #+vindex: modus-themes-links -Symbol: ~modus-themes-links~ +Brief: Control the style of links to web pages, files, buffers... + +Symbol: ~modus-themes-links~ (=choice= type, list of properties) Possible values are expressed as a list of properties (default is ~nil~ or an empty list). The list can include any of the following symbols: @@ -730,6 +889,101 @@ controlled by ~x-use-underline-position-properties~, ~x-underline-at-descent-line~, ~underline-minimum-offset~. Please refer to their documentation strings. +** Option for box buttons +:properties: +:alt_title: Box buttons +:description: Choose among several styles for buttons +:custom_id: h:8b85f711-ff40-45b0-b7fc-4727503cd2ec +:end: +#+vindex: modus-themes-box-buttons + +Brief: Control the style of buttons in the Custom UI and related. + +Symbol: ~modus-themes-box-buttons~ (=choice= type, list of properties) + +Possible values are expressed as a list of properties (default is ~nil~ or +an empty list). The list can include any of the following symbols: + ++ ~flat~ ++ ~accented~ ++ ~faint~ ++ ~variable-pitch~ ++ ~underline~ ++ A font weight, which must be supported by the underlying typeface: + - ~thin~ + - ~ultralight~ + - ~extralight~ + - ~light~ + - ~semilight~ + - ~regular~ + - ~medium~ + - ~semibold~ + - ~bold~ + - ~heavy~ + - ~extrabold~ + - ~ultrabold~ ++ A floating point as a height multiple of the default or a cons cell in + the form of =(height . FLOAT)= ++ ~all-buttons~ + +The default (a nil value or an empty list) is a gray background combined +with a pseudo three-dimensional effect. + +The ~flat~ property makes the button two dimensional. + +The ~accented~ property changes the background from gray to an accent +color. + +The ~faint~ property reduces the overall coloration. + +The ~variable-pitch~ property applies a proportionately spaced typeface +to the button~s text. + +[[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. + +The ~underline~ property draws a line below the affected text and +removes whatever box effect. This is optimal when Emacs runs inside a +terminal emulator ([[#h:fbb5e254-afd6-4313-bb05-93b3b4f67358][More accurate colors in terminal emulators]]). If +~flat~ and ~underline~ are defined together, the latter takes +precedence. + +The symbol of a weight attribute adjusts the font of the button +accordingly, such as ~light~, ~semibold~, etc. Valid symbols are +defined in the variable ~modus-themes-weights~. + +[[#h:2793a224-2109-4f61-a106-721c57c01375][Configure bold and italic faces]]. + +A number, expressed as a floating point (e.g. =0.9=), adjusts the height +of the button's text to that many times the base font size. The default +height is the same as =1.0=, though it need not be explicitly stated. +Instead of a floating point, an acceptable value can be in the form of a +cons cell like =(height . FLOAT)= or =(height FLOAT)=, where FLOAT is +the given number. + +The ~all-buttons~ property extends the box button effect (or the +aforementioned properties) to the faces of the generic widget library. +By default, those do not look like the buttons of the Custom UI as they +are ordinary text wrapped in square brackets. + +Combinations of any of those properties are expressed as a list, +like in these examples: + +#+begin_src emacs-lisp +(flat) +(variable-pitch flat) +(variable-pitch flat semibold 0.9) +(variable-pitch flat semibold (height 0.9)) ; same as above +(variable-pitch flat semibold (height . 0.9)) ; same as above +#+end_src + +The order in which the properties are set is not significant. + +In user configuration files the form may look like this: + +#+begin_src emacs-lisp +(setq modus-themes-box-buttons '(variable-pitch flat 0.9)) +#+end_src + ** Option for command prompt styles :properties: :alt_title: Command prompts @@ -738,7 +992,10 @@ their documentation strings. :end: #+vindex: modus-themes-prompts -Symbol: ~modus-themes-prompts~ +Brief: Control the style of command prompts (e.g. minibuffer, shell, IRC +clients). + +Symbol: ~modus-themes-prompts~ (=choice= type, list of properties) Possible values are expressed as a list of properties (default is ~nil~ or an empty list). The list can include any of the following symbols: @@ -794,7 +1051,9 @@ In user configuration files the form may look like this: :end: #+vindex: modus-themes-mode-line -Symbol: ~modus-themes-mode-line~ +Brief: Control the style of the mode lines. + +Symbol: ~modus-themes-mode-line~ (=choice= type, list of properties) Possible values, which can be expressed as a list of combinations of box effect, color, and border visibility: @@ -804,42 +1063,58 @@ effect, color, and border visibility: - ~moody~ + ~accented~ + ~borderless~ -+ ~padded~ ++ A natural number > 1 for extra padding or a cons cell in the form of + ~(padding . NATNUM)~. ++ A floating point to set the height of the mode line's text. It can + also be a cons cell in the form of ~(height . FLOAT)~. The default (a nil value or an empty list) is a two-dimensional -rectangle with a border around it. The active and the inactive -mode lines use different shades of grayscale values for the -background, foreground, border. - -The ~3d~ property applies a three-dimensional effect to the -active mode line. The inactive mode lines remain two-dimensional -and are toned down a bit, relative to the default style. - -The ~moody~ property optimizes the mode line for use with the -library of the same name (hereinafter referred to as 'Moody'). -In practice, it removes the box effect and replaces it with -underline and overline properties. It also tones down the -inactive mode lines. Despite its intended purpose, this option -can also be used without the Moody library (please consult the -themes' manual on this point for more details). If both ~3d~ and -~moody~ properties are set, the latter takes precedence. - -The ~borderless~ property removes the color of the borders. It -does not actually remove the borders, but only makes their color -the same as the background, effectively creating some padding. - -The ~accented~ property ensures that the active mode line uses a -colored background instead of the standard shade of gray. - -The ~padded~ property increases the apparent height of the mode line. -This is done by applying box effects and combining them with an -underline and overline. To ensure that the underline is placed at the -bottom, set ~x-underline-at-descent-line~ to non-nil. The ~padded~ property -has no effect when the ~moody~ property is also used, because Moody -already applies its own padding. +rectangle with a border around it. The active and the inactive mode +lines use different shades of grayscale values for the background, +foreground, border. + +The ~3d~ property applies a three-dimensional effect to the active mode +line. The inactive mode lines remain two-dimensional and are toned down +a bit, relative to the default style. + +The ~moody~ property optimizes the mode line for use with the library of +the same name (hereinafter referred to as 'Moody'). In practice, it +removes the box effect and replaces it with underline and overline +properties. It also tones down the inactive mode lines. Despite its +intended purpose, this option can also be used without the Moody library +(please consult the themes' manual on this point for more details). If +both ~3d~ and ~moody~ properties are set, the latter takes precedence. + +The ~borderless~ property removes the color of the borders. It does not +actually remove the borders, but only makes their color the same as the +background, effectively creating some padding. + +The ~accented~ property ensures that the active mode line uses a colored +background instead of the standard shade of gray. + +A positive integer (natural number or natnum) applies a padding effect +of NATNUM pixels at the boundaries of the mode lines. The default value +is 1 and does not need to be specified explicitly. The padding has no +effect when the ~moody~ property is also used, because Moody already +applies its own tweaks. To ensure that the underline is placed at the +bottom of the mode line, set ~x-underline-at-descent-line~ to non-nil +(this is not needed when the ~borderless~ property is also set). For +users on Emacs 29, the ~x-use-underline-position-properties~ variable must +also be set to nil. + +The padding can also be expressed as a cons cell in the form of +=(padding . NATNUM)= or =(padding NATNUM)= where the key is constant and +NATNUM is the desired natural number. + +A floating point applies an adjusted height to the mode line's text as a +multiple of the main font size. The default rate is 1.0 and does not +need to be specified. Apart from a floating point, the height may also +be expressed as a cons cell in the form of =(height . FLOAT)= or +=(height FLOAT)= where the key is constant and the FLOAT is the desired +number. -Combinations of any of those properties are expressed as a list, -like in these examples: +Combinations of any of those properties are expressed as a list, like in +these examples: #+begin_src emacs-lisp (accented) @@ -847,6 +1122,15 @@ like in these examples: (moody accented borderless) #+end_src +Same as above, using the padding and height as an example (these +all yield the same result): + +#+begin_src emacs-lisp +(accented borderless 4 0.9) +(accented borderless (padding . 4) (height . 0.9)) +(accented borderless (padding 4) (height 0.9)) +#+end_src + The order in which the properties are set is not significant. In user configuration files the form may look like this: @@ -874,8 +1158,12 @@ high, because it has the adverse effect of always overriding the default colors (which have been carefully designed to be highly accessible). Furthermore, because Moody expects an underline and overline instead of -a box style, it is advised to set ~x-underline-at-descent-line~ to a -non-nil value. +a box style, it is strongly advised to set ~x-underline-at-descent-line~ +to a non-nil value. + +Finally, note that various packages which heavily modify the mode line, +such as =doom-modeline=, =nano-modeline=, =powerline=, =spaceline= may not look +as intended with all possible combinations of this user option. ** Option for accented background in tab interfaces :properties: @@ -885,7 +1173,9 @@ non-nil value. :end: #+vindex: modus-themes-tabs-accented -Symbol: ~modus-themes-tabs-accented~ +Brief: Toggle accent colors for tabbed interfaces. + +Symbol: ~modus-themes-tabs-accented~ (=boolean= type) Possible values: @@ -901,47 +1191,106 @@ Centaur tabs package. ** Option for completion framework aesthetics :properties: :alt_title: Completion UIs -:description: Choose among standard, moderate, or opinionated looks +:description: Choose among several styles for completion UIs :custom_id: h:f1c20c02-7b34-4c35-9c65-99170efb2882 :end: #+vindex: modus-themes-completions -Symbol: ~modus-themes-completions~ +Brief: Set the overall style of completion framework interfaces. -Possible values: +Symbol: ~modus-themes-completions~ (=alist= type properties) -1. ~nil~ (default) -2. ~moderate~ -3. ~opinionated~ - -This is a special option that has different effects depending on the -completion UI. The interfaces can be grouped in two categories, based -on their default aesthetics: (i) those that only or mostly use -foreground colors for their interaction model, and (ii) those that -combine background and foreground values for some of their metaphors. -The former category encompasses Icomplete, Ido, Selectrum, Vertico, as -well as pattern matching styles like Orderless and Flx. The latter -covers Helm, Ivy, and Sallet. - -A value of ~nil~ (the default) will simply respect the metaphors of each -completion framework. - -Option ~moderate~ applies a combination of background and foreground that -is fairly subtle. For Icomplete and friends this constitutes a -departure from their default aesthetics, however the difference is -small. While Helm, Ivy et al appear slightly different than their -original looks, as they are toned down a bit. - -Option ~opinionated~ uses color combinations that refashion the completion -UI. For the Icomplete camp this means that intense background and -foreground combinations are used: in effect their looks emulate those of -Helm, Ivy and co. in their original style. Whereas the other group of -packages will revert to an even more nuanced aesthetic with some -additional changes to the choice of hues. - -To appreciate the scope of this customization option, you should spend -some time with every one of the ~nil~ (default), ~moderate~, and ~opinionated~ -possibilities. +This affects Company, Corfu, Flx, Helm, Icomplete/Fido, Ido, Ivy, +Orderless, Selectrum, Vertico. The value is an alist that takes the +form of a =(key . properties)= combination. Here is a sample, followed +by a description of the particularities: + +#+begin_src emacs-lisp +(setq modus-themes-completions + '((matches . (extrabold background intense)) + (selection . (semibold accented intense)) + (popup . (accented)))) +#+end_src + +The ~matches~ key refers to the highlighted characters that correspond +to the user's input. By default (nil or an empty list), they have a +bold weight and a colored foreground. The list of properties may +include any of the following symbols regardless of the order they may +appear in: + +- ~background~ to add a background color; + +- ~intense~ to increase the overall coloration (also amplifies + the ~background~, if present); + +- ~underline~ to draw a line below the characters; + +- ~italic~ to use a slanted font (italic or oblique forms); + +- The symbol of a font weight attribute such as ~light~, ~semibold~, et + cetera. Valid symbols are defined in the ~modus-themes-weights~ + variable. The absence of a weight means that bold will be used. + +The ~selection~ key applies to the current line or currently matched +candidate, depending on the specifics of the User Interface. By default +(nil or an empty list), it has a subtle gray background, a bold weight, +and the base foreground value for the text. The list of properties it +accepts is as follows (order is not significant): + +- ~accented~ to make the background colorful instead of gray; + +- ~text-also~ to apply extra color to the text of the selected line; + +- ~intense~ to increase the overall coloration; + +- ~underline~ to draw a line below the characters; + +- ~italic~ to use a slanted font (italic or oblique forms); + +- The symbol of a font weight attribute such as ~light~, ~semibold~, et + cetera. Valid symbols are defined in the ~modus-themes-weights~ + variable. The absence of a weight means that bold will be used. + +The ~popup~ key takes the same values as ~selection~. + +Apart from specifying each key separately, a fallback list is accepted. +This is only useful when the desired aesthetic is the same across all +keys that are not explicitly referenced. For example, this: + +#+begin_src emacs-lisp +(setq modus-themes-completions + '((t . (extrabold intense)))) +#+end_src + +Is the same as: + +#+begin_src emacs-lisp +(setq modus-themes-completions + '((matches . (extrabold intense)) + (selection . (extrabold intense)) + (popup . (extrabold intense)))) +#+end_src + +In the case of the fallback, any property that does not apply to the +corresponding key is simply ignored (~matches~ does not have ~accented~ +and ~text-also~, while ~selection~ and ~popup~ do not have +~background~). + +A concise expression of those associations can be written as follows, +where the ~car~ is always the key and the ~cdr~ is the list of +properties (whatever order they may appear in): + +#+begin_src emacs-lisp +(setq modus-themes-completions + '((matches extrabold background intense) + (selection semibold accented intense) + (popup accented))) +#+end_src + +[[#h:2793a224-2109-4f61-a106-721c57c01375][Configure bold and italic faces]]. + +Also refer to the Orderless documentation for its intersection with +Company (if you choose to use those in tandem). ** Option for mail citations :properties: @@ -951,22 +1300,29 @@ possibilities. :end: #+vindex: modus-themes-mail-citations -Symbol: ~modus-themes-mail-citations~ +Brief: Set the overall style of citations/quotes when composing +emails. + +Symbol: ~modus-themes-mail-citations~ (=choice= type) Possible values: 1. ~nil~ (default) -2. ~faint~ -3. ~monochrome~ +2. ~intense~ +3. ~faint~ +4. ~monochrome~ -By default, citations in email-related buffers apply contrasting hues to -different levels of depth in cited text. The colors are fairly easy to -tell apart. +By default (a nil value) citations are styled with contrasting hues to +denote their depth. Colors are easy to tell apart because they +complement each other, but they otherwise are not very prominent. -A value of ~faint~ makes all citation levels less intense, while retaining -the default style of contrasting hues (albeit very subtle ones). +Option ~intense~ is similar to the default in terms of using contrasting +and complementary hues, but applies more saturated colors. -Option ~monochrome~ turns all citations in to a uniform shade of gray. +Option ~faint~ maintains the same color-based distinction between citation +levels though the colors it uses have subtle differences between them. + +Option ~monochrome~ turns all quotes into a shade of gray. Whatever the value assigned to this variable, citations in emails are controlled by typographic elements or indentation, which the themes do @@ -980,7 +1336,9 @@ not touch. :end: #+vindex: modus-themes-fringes -Symbol: ~modus-themes-fringes~ +Brief: Control the overall coloration of the fringes. + +Symbol: ~modus-themes-fringes~ (=choice= type) Possible values: @@ -1004,7 +1362,10 @@ names imply. :end: #+vindex: modus-themes-lang-checkers -Symbol: ~modus-themes-lang-checkers~ +Brief: Control the style of in-buffer warnings and errors produced by +spell checkers, code linters, and the like. + +Symbol: ~modus-themes-lang-checkers~ (=choice= type, list of properties) Possible values are expressed as a list of properties (default is ~nil~ or an empty list). The list can include any of the following symbols: @@ -1012,7 +1373,9 @@ an empty list). The list can include any of the following symbols: + ~straight-underline~ + ~text-also~ + ~background~ -+ ~intense~ ++ Overall coloration: + - ~intense~ + - ~faint~ The default (a ~nil~ value or an empty list) applies a color-coded underline to the affected text, while it leaves the original foreground @@ -1028,15 +1391,15 @@ affected text. The property ~background~ adds a color-coded background. The property ~intense~ amplifies the applicable colors if ~background~ -and/or ~text-only~ are set. If ~intense~ is set on its own, then it implies -~text-only~. +and/or ~text-also~ are set. If ~intense~ is set on its own, then it implies +~text-also~. -To disable fringe indicators for Flymake or Flycheck, refer to variables -~flymake-fringe-indicator-position~ and ~flycheck-indication-mode~, -respectively. +The property ~faint~ uses nuanced colors for the underline and for the +foreground when ~text-also~ is included. If both ~faint~ and ~intense~ are +specified, the former takes precedence. -Combinations of any of those properties can be expressed in a -list, as in those examples: +Combinations of any of those properties can be expressed in a list, as +in those examples: #+begin_src emacs-lisp (background) @@ -1056,6 +1419,10 @@ NOTE: The placement of the straight underline, though not the wave style, is controlled by the built-in variables ~underline-minimum-offset~, ~x-underline-at-descent-line~, ~x-use-underline-position-properties~. +To disable fringe indicators for Flymake or Flycheck, refer to variables +~flymake-fringe-indicator-position~ and ~flycheck-indication-mode~, +respectively. + ** Option for line highlighting :properties: :alt_title: Line highlighting @@ -1064,7 +1431,9 @@ style, is controlled by the built-in variables ~underline-minimum-offset~, :end: #+vindex: modus-themes-hl-line -Symbol: ~modus-themes-hl-line~ +Brief: Control the style of the current line of ~hl-line-mode~. + +Symbol: ~modus-themes-hl-line~ (=choice= type, list of properties) Possible values are expressed as a list of properties (default is ~nil~ or an empty list). The list can include any of the following symbols: @@ -1108,6 +1477,9 @@ with underlines. This style affects several packages that enable ~hl-line-mode~, such as =elfeed=, =notmuch=, and =mu4e=. +[ Also check the =lin= package on GNU ELPA (by the author of the + modus-themes) for a stylistic enhancement to ~hl-line-mode~. ] + ** Option for line numbers :properties: :alt_title: Line numbers @@ -1116,7 +1488,9 @@ This style affects several packages that enable ~hl-line-mode~, such as :end: #+vindex: modus-themes-subtle-line-numbers -Symbol: ~modus-themes-subtle-line-numbers~ +Brief: Toggle subtle line numbers. + +Symbol: ~modus-themes-subtle-line-numbers~ (=boolean= type) Possible value: @@ -1137,6 +1511,84 @@ Instead they retain the primary background of the theme, blending with the rest of the buffer. Foreground values for all relevant faces are updated to accommodate this aesthetic. +** Option for mouseover effects +:properties: +:alt_title: Mouse hover effects +:description: Toggle intense style for mouseover highlights +:custom_id: h:9b869620-fcc5-4b5f-9ab8-225d73b7f22f +:end: +#+vindex: modus-themes-intense-mouseovers + +Brief: Toggle intense mouse hover effects. + +Symbol: ~modus-themes-intense-mouseovers~ (=boolean= type) + +Possible value: + +1. ~nil~ (default) +2. ~t~ + +By default all mouseover effects apply a highlight with a subtle colored +background. When non-nil, these have a more pronounced effect. + +Note that this affects the generic ~highlight~ which, strictly speaking, +is not limited to mouse usage. + +** Option for markup style in Org and others +:properties: +:alt_title: Markup +:description: Choose style for markup in Org and others +:custom_id: h:9d9a4e64-99ac-4018-8f66-3051b9c43fd7 +:end: +#+vindex: modus-themes-markup + +Brief: Choose style of markup in Org, Markdown, and others (affects +constructs such as Org's ==verbatim== and =~code~=). + +Symbol: ~modus-themes-markup~ (=boolean= type) + +Possible values are expressed as a list of properties (default is ~nil~ or +an empty list). The list can include any of the following symbols: + +1. ~bold~ +2. ~italic~ +3. ~background~ +4. ~intense~ + +The ~italic~ property applies a typographic slant (italics). + +The ~bold~ property applies a heavier typographic weight. + +[[#h:2793a224-2109-4f61-a106-721c57c01375][Configure bold and italic faces]]. + +The ~background~ property adds a background color. The background is a +shade of gray, unless the ~intense~ property is also set. + +The ~intense~ property amplifies the existing coloration. When +~background~ is used, the background color is enhanced as well and +becomes tinted instead of being gray. + +Combinations of any of those properties are expressed as a list, +like in these examples: + +#+begin_src emacs-lisp +(bold) +(bold italic) +(bold italic intense) +(bold italic intense background) +#+end_src + +The order in which the properties are set is not significant. + +In user configuration files the form may look like this: + +#+begin_src emacs-lisp +(setq modus-themes-markup '(bold italic)) +#+end_src + +Also check the variables ~org-hide-emphasis-markers~, +~org-hide-macro-markers~. + ** Option for parenthesis matching :properties: :alt_title: Matching parentheses @@ -1145,7 +1597,10 @@ updated to accommodate this aesthetic. :end: #+vindex: modus-themes-paren-match -Symbol: ~modus-themes-paren-match~ +Brief: Control the style of matching delimiters produced by +~show-paren-mode~. + +Symbol: ~modus-themes-paren-match~ (=choice= type, list of properties) Possible values are expressed as a list of properties (default is ~nil~ or an empty list). The list can include any of the following symbols: @@ -1192,7 +1647,9 @@ This customization variable affects the built-in ~show-paren-mode~ and the :end: #+vindex: modus-themes-region -Symbol: ~modus-themes-region~ +Brief: Control the style of the region. + +Symbol: ~modus-themes-region~ (=choice= type, list of properties) Possible values are expressed as a list of properties (default is ~nil~ or an empty list). The list can include any of the following symbols: @@ -1233,23 +1690,24 @@ In user configuration files the form may look like this: ** Option for diff buffer looks :properties: :alt_title: Diffs -:description: Choose among intense, desaturated, or text-only diffs +:description: Choose among intense, desaturated, or background-only diffs :custom_id: h:ea7ac54f-5827-49bd-b09f-62424b3b6427 :end: #+vindex: modus-themes-diffs -Symbol: ~modus-themes-diffs~ +Brief: Set the overall style of diffs. + +Symbol: ~modus-themes-diffs~ (=choice= type) Possible values: 1. ~nil~ (default) 2. ~desaturated~ 3. ~bg-only~ -4. ~deuteranopia~ -5. ~fg-only-deuteranopia~ The default (~nil~) uses fairly intense color combinations for diffs, by -applying prominently colored backgrounds, with appropriate foregrounds. +applying prominently colored backgrounds, with appropriately tinted +foregrounds. Option ~desaturated~ follows the same principles as with the default (~nil~), though it tones down all relevant colors. @@ -1257,24 +1715,24 @@ Option ~desaturated~ follows the same principles as with the default Option ~bg-only~ applies a background but does not override the text's foreground. This makes it suitable for a non-nil value passed to ~diff-font-lock-syntax~ (note: Magit does not support syntax highlighting -in diffs---last checked on 2021-04-21). - -Option ~deuteranopia~ is like the default (~nil~) in terms of using -prominently colored backgrounds, except that it also accounts for -red-green color defficiency by replacing all instances of green with -colors on the blue side of the spectrum. Other stylistic changes are -made in the interest of optimizing for such a use-case. - -Option ~fg-only-deuteranopia~ removes all colored backgrounds, except from -word-wise or refined changes. Instead, it only uses color-coded -foreground values to differentiate between added, removed, and changed -lines. If a background is necessary to denote context, a subtle -grayscale value is applied. The color used for added lines is a variant -of blue to account for red-green color defficiency but also because -green text alone is hard to discern in the diff's context (hard for our -accessibility purposes). The ~fg-only~ option that existed in older -versions of the themes is now an alias of ~fg-only-deuteranopia~, in the -interest of backward compatibility. +in diffs---last checked on 2021-12-02). + +When the user option ~modus-themes-deuteranopia~ is non-nil, all diffs +will use a red/blue color-coding system instead of the standard +red/green. Other stylistic changes are made in the interest of +optimizing for such a use-case. + +[[#h:3ed03a48-20d8-4ce7-b214-0eb7e4c79abe][Option for red-green color deficiency or deuteranopia]]. + +In versions before =2.0.0= there was an option for foreground-only diffs. +This is no longer supported at the theme level because there are cases +where the perceived contrast and overall contextuality were not good +enough although the applied colors were technically above the 7:1 +contrast threshold. + +[[#h:e2aed9eb-5e1e-45ec-bbd7-bc4faeab3236][Diffs with only the foreground]]. + +[[#h:b0b31802-0216-427e-b071-1a47adcfe608][Ediff without diff color-coding]]. ** Option for org-mode block styles :properties: @@ -1284,7 +1742,9 @@ interest of backward compatibility. :end: #+vindex: modus-themes-org-blocks -Symbol: ~modus-themes-org-blocks~ +Brief: Set the overall style of Org code blocks, quotes, and the like. + +Symbol: ~modus-themes-org-blocks~ (=choice= type) Possible values: @@ -1292,20 +1752,28 @@ Possible values: 2. ~gray-background~ (value ~grayscale~ exists for backward compatibility) 3. ~tinted-background~ (value ~rainbow~ exists for backward compatibility) -The default means that the block has no distinct background of its own -and uses the one that applies to the rest of the buffer. +Nil (the default) means that the block has no background of its own: it +uses the one that applies to the rest of the buffer. In this case, the +delimiter lines have a gray color for their text, making them look +exactly like all other Org properties. Option ~gray-background~ applies a subtle gray background to the block's -contents. It also affects the begin and end lines of the block: their -background extends to the edge of the window for Emacs version >= 27 -where the ~:extend~ keyword is recognized by ~set-face-attribute~ (this is -contingent on the variable ~org-fontify-whole-block-delimiter-line~). +contents. It also affects the begin and end lines of the block as they +get another shade of gray as their background, which differentiates them +from the contents of the block. All background colors extend to the +edge of the window, giving the area a rectangular, "blocky" +presentation. Option ~tinted-background~ uses a slightly colored background for the contents of the block. The exact color will depend on the programming language and is controlled by the variable ~org-src-block-faces~ (refer to the theme's source code for the current association list). For this to -take effect, Org must be restarted with {{{kbd(M-x org-mode-restart)}}}. +take effect, the Org buffer needs to be restarted with ~org-mode-restart~. +In this scenario, it may be better to inhibit the extension of the +delimiter lines' background to the edge of the window because Org does +not provide a mechanism to update their colors depending on the contents +of the block. Disable the extension of such backgrounds by setting +~org-fontify-whole-block-delimiter-line~ to nil. Code blocks use their major mode's colors only when the variable ~org-src-fontify-natively~ is non-nil. While quote/verse blocks require @@ -1325,7 +1793,10 @@ and ~rainbow~. Those will continue to work as they are aliases for :end: #+vindex: modus-themes-org-agenda -Symbol: ~modus-themes-org-agenda~ +Brief: Control the style of the Org agenda. Multiple parameters are +available, each with its own options. + +Symbol: ~modus-themes-org-agenda~ (=alist= type, multiple styles) This is an alist that accepts a =(key . value)= combination. Some values are specified as a list. Here is a sample, followed by a description of @@ -1333,9 +1804,9 @@ all possible combinations: #+begin_src emacs-lisp (setq modus-themes-org-agenda - '((header-block . (variable-pitch scale-title)) - (header-date . (grayscale workaholic bold-today)) - (event . (accented scale-small)) + '((header-block . (variable-pitch 1.5)) + (header-date . (grayscale workaholic bold-today 1.2)) + (event . (accented italic varied)) (scheduled . uniform) (habit . traffic-light))) #+end_src @@ -1348,20 +1819,37 @@ come in the form of a list that can include either or both of those properties: - ~variable-pitch~ to use a proportionately spaced typeface; -- ~scale-title~ to increase the size to the number assigned to - ~modus-themes-scale-title~ ([[#h:6868baa1-beba-45ed-baa5-5fd68322ccb3][Control the scale of headings]]) or ~no-scale~ - to make the font use the same height as the rest of the buffer. -In case both ~scale-title~ and ~no-scale~ are in the list, the latter takes -precedence. +- A number as a floating point (e.g. 1.5) to set the height of the text + to that many times the default font height. A float of 1.0 or the + symbol ~no-scale~ have the same effect of making the font the same + height as the rest of the buffer. When neither a number nor + `no-scale' are present, the default is a small increase in height (a + value of 1.15). + + Instead of a floating point, an acceptable value can be in the form of + a cons cell like =(height . FLOAT)= or =(height FLOAT)=, where FLOAT + is the given number. + +- The symbol of a weight attribute adjusts the font of the heading + accordingly, such as ~light~, ~semibold~, etc. Valid symbols are + defined in the variable ~modus-themes-weights~. The absence of a + weight means that bold will be used by virtue of inheriting the ~bold~ + face. + +[[#h:2793a224-2109-4f61-a106-721c57c01375][Configure bold and italic faces]]. + +In case both a number and ~no-scale~ are in the list, the latter takes +precedence. If two numbers are specified, the first one is applied. Example usage: #+begin_src emacs-lisp (header-block . nil) -(header-block . (scale-title)) +(header-block . (1.5)) (header-block . (no-scale)) -(header-block . (variable-pitch scale-title)) +(header-block . (variable-pitch 1.5)) +(header-block . (variable-pitch 1.5 semibold)) #+end_src A ~header-date~ key covers date headings. Dates use only a foreground @@ -1372,16 +1860,24 @@ the following properties: - ~grayscale~ to make weekdays use the main foreground color and weekends a more subtle gray; + - ~workaholic~ to make weekdays and weekends look the same in terms of color; + - ~bold-today~ to apply a bold typographic weight to the current date; -- ~bold-all~ to render all date headings in a bold weight. -- ~scale-heading~ increases the height of the date headings to the value - of ~modus-themes-scale-1~ (which is the first step in the scale for - regular headings). + +- ~bold-all~ to render all date headings in a bold weight; + - ~underline-today~ applies an underline to the current date while - removing the background it has by default. + removing the background it has by default; + +- A number as a floating point (e.g. 1.2) to set the height of the text + to that many times the default font height. The default is the same + as the base font height (the equivalent of 1.0). Instead of a + floating point, an acceptable value can be in the form of a cons cell + like =(height . FLOAT)= or =(height FLOAT)=, where FLOAT is the given + number. For example: @@ -1394,28 +1890,35 @@ For example: (header-date . (grayscale workaholic bold-today scale-heading)) #+end_src -An ~event~ key covers events from the diary and other entries that derive -from a symbolic expression or sexp (e.g. phases of the moon, holidays). -This key accepts a list of values. By default (a nil value or an empty -list) those have a gray foreground, while sexp events are additionally -presented using slanted text (italics). The properties that can form a -list of possible values are: +An ~event~ key covers (i) headings with a plain time stamp that are +shown on the agenda, also known as events, (ii) entries imported from +the diary, and (iii) other items that derive from a symbolic expression +or sexp (phases of the moon, holidays, etc.). By default all those look +the same and have a subtle foreground color (the default is a nil value +or an empty list). This key accepts a list of properties. Those are: -- ~scale-small~ reduces the height of the entries to the value of the user - option ~modus-themes-scale-small~ (0.9 the height of the main font size - by default). -- ~accented~ applies an accent value to the event's foreground, replacing - the original gray. +- ~accented~ applies an accent value to the event's foreground, + replacing the original gray. It makes all entries stand out more. - ~italic~ adds a slant to the font's forms (italic or oblique forms, depending on the typeface). +- ~varied~ differentiates between events with a plain time stamp and + entries that are generated from either the diary or a symbolic + expression. It generally puts more emphasis on events. When ~varied~ + is combined with ~accented~, it makes only events use an accent color, + while diary/sexp entries retain their original subtle foreground. + When ~varied~ is used in tandem with ~italic~, it applies a slant only + to diary and sexp entries, not events. And when ~varied~ is the sole + property passed to the ~event~ key, it has the same meaning as the + list (italic varied). The combination of ~varied~, ~accented~, + ~italic~ covers all of the aforementioned cases. For example: #+begin_src emacs-lisp (event . nil) -(event . (scale-small)) -(event . (scale-small accented)) -(event . (scale-small accented italic)) +(event . (italic)) +(event . (accented italic)) +(event . (accented italic varied)) #+end_src A ~scheduled~ key applies to tasks with a scheduled date. By default (a @@ -1460,9 +1963,12 @@ passed as a symbol. Those are: being too late. The difference between ready and clear states is attenuated by painting both of them using shades of green. This option thus highlights the alert and overdue states. -- ~traffic-light-deuteranopia~ is like the ~traffic-light~ except its three - colors are red, yellow, and blue to be suitable for users with - red-green color deficiency (deuteranopia). +- When ~modus-themes-deuteranopia~ is non-nil the exact style of the habit + graph adapts to the needs of users with red-green color deficiency by + substituting every instance of green with blue or cyan (depending on + the specifics). + +[[#h:3ed03a48-20d8-4ce7-b214-0eb7e4c79abe][Option for red-green color deficiency or deuteranopia]]. For example: @@ -1475,17 +1981,17 @@ For example: Putting it all together, the alist can look like this: #+begin_src emacs-lisp -'((header-block . (scale-title variable-pitch)) +'((header-block . (1.5 variable-pitch)) (header-date . (grayscale workaholic bold-today)) - (event . (accented scale-small)) + (event . (accented varied)) (scheduled . uniform) (habit . traffic-light)) ;; Or else: (setq modus-themes-org-agenda - '((header-block . (scale-title variable-pitch)) + '((header-block . (1.5 variable-pitch)) (header-date . (grayscale workaholic bold-today)) - (event . (accented scale-small)) + (event . (accented varied)) (scheduled . uniform) (habit . traffic-light))) #+end_src @@ -1498,18 +2004,27 @@ Putting it all together, the alist can look like this: :end: #+vindex: modus-themes-headings -Symbol: ~modus-themes-headings~ +Brief: Heading styles with optional list of values for levels 0-8. + +Symbol: ~modus-themes-headings~ (=alist= type, multiple properties) + +This is an alist that accepts a =(key . list-of-values)= combination. +The key is either a number, representing the heading's level (0-8) or t, +which pertains to the fallback style. -This is an alist that accepts a =(key . list-of-values)= combination. The -key is either a number, representing the heading's level or ~t~, which -pertains to the fallback style. The list of values covers symbols that -refer to properties, as described below. Here is a sample, followed by -a presentation of all available properties: +Level 0 is a special heading: it is used for what counts as a document +title or equivalent, such as the =#+title= construct we find in Org +files. Levels 1-8 are regular headings. + +The list of values covers symbols that refer to properties, as described +below. Here is a complete sample, followed by a presentation of all +available properties: #+begin_src emacs-lisp (setq modus-themes-headings - '((1 . (background overline)) - (2 . (overline rainbow)) + '((1 . (background overline variable-pitch 1.5)) + (2 . (overline rainbow 1.3)) + (3 . (overline 1.1)) (t . (monochrome)))) #+end_src @@ -1518,8 +2033,23 @@ Properties: + ~rainbow~ + ~overline~ + ~background~ -+ ~no-bold~ + ~monochrome~ ++ A font weight, which must be supported by the underlying typeface: + - ~thin~ + - ~ultralight~ + - ~extralight~ + - ~light~ + - ~semilight~ + - ~regular~ + - ~medium~ + - ~semibold~ + - ~bold~ + - ~heavy~ + - ~extrabold~ + - ~ultrabold~ ++ ~no-bold~ (deprecated alias of a ~regular~ weight) ++ A floating point as a height multiple of the default or a cons cell in + the form of =(height . FLOAT)=. By default (a ~nil~ value for this variable), all headings have a bold typographic weight and use a desaturated text color. @@ -1531,20 +2061,39 @@ An ~overline~ property draws a line above the area of the heading. A ~background~ property adds a subtle tinted color to the background of the heading. -A ~no-bold~ property removes the bold weight from the heading's text. +A ~monochrome~ property makes the heading the same as the base color, +which is that of the ~default~ face's foreground. When ~background~ is also +set, ~monochrome~ changes its color to gray. If both ~monochrome~ and +~rainbow~ are set, the former takes precedence. + +A ~variable-pitch~ property changes the font family of the heading to that +of the ~variable-pitch~ face (normally a proportionately spaced typeface). + +The symbol of a weight attribute adjusts the font of the heading +accordingly, such as ~light~, ~semibold~, etc. Valid symbols are +defined in the variable ~modus-themes-weights~. The absence of a weight +means that bold will be used by virtue of inheriting the ~bold~ face. +For backward compatibility, the ~no-bold~ value is accepted, though +users are encouraged to specify a ~regular~ weight instead. + +[[#h:2793a224-2109-4f61-a106-721c57c01375][Configure bold and italic faces]]. -A ~monochrome~ property makes all headings the same base color, which is -that of the default for the active theme (black/white). When ~background~ -is also set, ~monochrome~ changes its color to gray. If both ~monochrome~ -and ~rainbow~ are set, the former takes precedence. +A number, expressed as a floating point (e.g. 1.5), adjusts the height +of the heading to that many times the base font size. The default +height is the same as 1.0, though it need not be explicitly stated. +Instead of a floating point, an acceptable value can be in the form of a +cons cell like =(height . FLOAT)= or =(height FLOAT)=, where FLOAT is +the given number. Combinations of any of those properties are expressed as a list, like in these examples: #+begin_src emacs-lisp -(no-bold) +(semibold) (rainbow background) -(overline monochrome no-bold) +(overline monochrome semibold 1.3) +(overline monochrome semibold (height 1.3)) ; same as above +(overline monochrome semibold (height . 1.3)) ; same as above #+end_src The order in which the properties are set is not significant. @@ -1553,9 +2102,9 @@ In user configuration files the form may look like this: #+begin_src emacs-lisp (setq modus-themes-headings - '((1 . (background overline rainbow)) - (2 . (background overline)) - (t . (overline no-bold)))) + '((1 . (background overline rainbow 1.5)) + (2 . (background overline 1.3)) + (t . (overline semibold)))) #+end_src When defining the styles per heading level, it is possible to pass a @@ -1570,7 +2119,7 @@ original aesthetic for that level. For example: (setq modus-themes-headings '((1 . (background overline)) - (2 . (rainbow no-bold)) + (2 . (rainbow semibold)) (t . t))) ; default style for all other levels #+end_src @@ -1579,100 +2128,6 @@ For Org users, the extent of the heading depends on the variable ~background~ properties. Depending on the version of Org, there may be others, such as ~org-fontify-done-headline~. -[[#h:075eb022-37a6-41a4-a040-cc189f6bfa1f][Option for scaled headings]]. - -[[#h:97caca76-fa13-456c-aef1-a2aa165ea274][Option for variable-pitch font in headings]]. - -** Option for scaled headings -:properties: -:alt_title: Scaled headings -:description: Toggle scaling of headings -:custom_id: h:075eb022-37a6-41a4-a040-cc189f6bfa1f -:end: -#+vindex: modus-themes-scale-headings - -Symbol: ~modus-themes-scale-headings~ - -Possible values: - -1. ~nil~ (default) -2. ~t~ - -The default is to use the same size for headings and paragraph text. - -With a non-nil value (~t~) make headings larger in height relative to the -main text. This is noticeable in modes like Org, Markdown, and Info. - -*** Control the scale of headings -:properties: -:alt_title: Scaled heading sizes -:description: Specify rate of increase for scaled headings -:custom_id: h:6868baa1-beba-45ed-baa5-5fd68322ccb3 -:end: - -In addition to the toggle for enabling scaled headings, users can also -specify a number of their own. - -+ If it is a floating point, say, =1.5=, it is interpreted as a multiple - of the base font size. This is the recommended method, because it - will always adapt to changes in the base font size, such as while - using the ~text-scale-adjust~ command. - -+ If it is an integer, it is read as an absolute font height that is - 1/10 of the typographic point size. Thus a value of =18pt= must be - expressed as =180=. Setting an absolute value is discouraged, as it - will break the layout in cases where the base font size must change, - such as with the ~text-scale-adjust~ command ([[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations]]). - While we discourage using absolute values, we still provide for this - option for users who do not need to perform text-scaling operations or - who are content with whatever discrepancies in height. - -Below are the variables in their default values, using the floating -point paradigm. The numbers are very conservative, but one is free to -change them to their liking, such as =1.2=, =1.4=, =1.6=, =1.8=, =2.0=---or use a -resource for finding a consistent scale: - -#+begin_src emacs-lisp -(setq modus-themes-scale-1 1.05 - modus-themes-scale-2 1.1 - modus-themes-scale-3 1.15 - modus-themes-scale-4 1.2 - modus-themes-scale-title 1.3 - modus-themes-scale-small 0.9) -#+end_src - -As for the application of that scale, the variables that range from -~modus-themes-scale-1~ up to ~modus-themes-scale-4~ apply to regular -headings within the context of the given major mode. The former is the -smallest, while the latter is the largest. "Regular headings" are those -that have a standard syntax for their scale, such as Org mode's eight -levels of asterisks or Markdown's six columns. - -Whereas ~modus-themes-scale-title~ is applied to special headings that do -not conform with the aforementioned syntax, yet which are expected to be -larger than the largest value on that implied scale or at least have -some unique purpose in the buffer. Put concretely, Org's =#+title= meta -datum is not part of the eight levels of headings in an Org file, yet is -supposed to signify the primary header. Similarly, the Org Agenda's -structure headings are not part of a recognisable scale and so they also -get ~modus-themes-scale-title~ ([[#h:68f481bc-5904-4725-a3e6-d7ecfa7c3dbc][Option for Org agenda constructs]]). - -Similarly ~modus-themes-scale-small~ is not applied to regular headings, -but reserved for special contexts where the user is presented with an -option to use a smaller font height than the base size. It is only -implemented for the Org agenda. - -Users who wish to maintain scaled headings for the normal syntax while -preventing special headings from standing out, can assign a value of =1.0= -to ~modus-themes-scale-title~ to make it the same as body text (or -whatever value would render it indistinguishable from the desired point -of reference). - -Note that in earlier versions of Org, scaling would only increase the -size of the heading, but not of keywords that were added to it, like -"TODO". The issue has been fixed upstream: -<https://protesilaos.com/codelog/2020-09-24-org-headings-adapt/>. - ** Option for variable-pitch font in UI elements :properties: :alt_title: UI typeface @@ -1681,7 +2136,10 @@ size of the heading, but not of keywords that were added to it, like :end: #+vindex: modus-themes-variable-pitch-ui -Symbol: ~modus-themes-variable-pitch-ui~ +Brief: Toggle the use of proportionately spaced (~variable-pitch~) fonts +in the User Interface. + +Symbol: ~modus-themes-variable-pitch-ui~ (=boolean= type) Possible values: @@ -1700,29 +2158,6 @@ is done by assigning the ~variable-pitch~ face to the relevant items. [[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. -** Option for variable-pitch font in headings -:properties: -:alt_title: Headings' typeface -:description: Toggle the use of variable-pitch in headings -:custom_id: h:97caca76-fa13-456c-aef1-a2aa165ea274 -:end: -#+vindex: modus-themes-variable-pitch-headings - -Symbol: ~modus-themes-variable-pitch-headings~ - -Possible values: - -1. ~nil~ (default) -2. ~t~ - -The default is to use the main font family, which typically is -monospaced. - -With a non-nil value (~t~) apply a proportionately spaced typeface, else -"variable-pitch", to headings (such as in Org mode). - -[[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. - * Advanced customization :properties: :custom_id: h:f4651d55-8c07-46aa-b52b-bed1e53463bb @@ -1738,6 +2173,128 @@ their own local tweaks and who are willing to deal with any possible incompatibilities between versioned releases of the themes. As such, they are labeled as "do-it-yourself" or "DIY". +** More accurate colors in terminal emulators +:PROPERTIES: +:CUSTOM_ID: h:fbb5e254-afd6-4313-bb05-93b3b4f67358 +:END: +#+cindex: Color accuracy of terminal emulators + +[ This is based on partial information. Please help verify and/or + expand these findings. ] + +The graphical version of Emacs can reproduce color values accurately. +Whereas things get more tricky when Emacs is used in a terminal +emulator, because the terminals' own capabilities determine the number +of colors that may be displayed: the Modus themes don't look as good in +that case. + +There is, however, a way to instruct supported terminal emulators to use +more accurate colors. In a shell prompt type =toe -a | grep direct= to +get a list of relevant terminfo entries. There should be items such as +=xterm-direct=, =alacritty-direct=, =kitty-direct=. Once you find the one +that corresponds to your terminal, call Emacs with an environment +variable like =TERM=xterm-direct=. Example that can be adapted to shell +aliases: + +: TERM=xterm-direct emacsclient -nw + +Another example that can be bound to a key: + +: TERM=xterm-direct uxterm -e emacsclient -nw + +** Range of color with terminal emulators +:PROPERTIES: +:CUSTOM_ID: h:6b8211b0-d11b-4c00-9543-4685ec3b742f +:END: +#+cindex: Pure white and pure black in terminal emulators + +[ This is based on partial information. Please help verify and/or + expand these findings. ] + +When Emacs runs in a non-windowed session its color reproduction +capacity is framed or determined by the underlying terminal emulator +([[#h:fbb5e254-afd6-4313-bb05-93b3b4f67358][More accurate colors in terminal emulators]]). Emacs cannot produce a +color that lies outside the range of what the terminal's color palette +renders possible. + +This is immediately noticeable when the terminal's first 16 codes do not +include a pure black value for the =termcol0= entry and a pure white for +=termcol15=. Emacs cannot set the correct background (white for +~modus-operandi~; black for ~modus-vivendi~) or foreground (inverse of +the background). It thus falls back to the closest approximation, which +seldom is appropriate for the purposes of the Modus themes. + +In such a case, the user is expected to update their terminal's color +palette such as by adapting these resources: + +#+begin_src emacs-lisp +! Theme: modus-operandi +! Description: XTerm port of modus-operandi (Modus themes for GNU Emacs) +! Author: Protesilaos Stavrou, <https://protesilaos.com> +xterm*background: #ffffff +xterm*foreground: #000000 +xterm*color0: #000000 +xterm*color1: #a60000 +xterm*color2: #005e00 +xterm*color3: #813e00 +xterm*color4: #0031a9 +xterm*color5: #721045 +xterm*color6: #00538b +xterm*color7: #bfbfbf +xterm*color8: #595959 +xterm*color9: #972500 +xterm*color10: #315b00 +xterm*color11: #70480f +xterm*color12: #2544bb +xterm*color13: #5317ac +xterm*color14: #005a5f +xterm*color15: #ffffff + +! Theme: modus-vivendi +! Description: XTerm port of modus-vivendi (Modus themes for GNU Emacs) +! Author: Protesilaos Stavrou, <https://protesilaos.com> +xterm*background: #000000 +xterm*foreground: #ffffff +xterm*color0: #000000 +xterm*color1: #ff8059 +xterm*color2: #44bc44 +xterm*color3: #d0bc00 +xterm*color4: #2fafff +xterm*color5: #feacd0 +xterm*color6: #00d3d0 +xterm*color7: #bfbfbf +xterm*color8: #595959 +xterm*color9: #ef8b50 +xterm*color10: #70b900 +xterm*color11: #c0c530 +xterm*color12: #79a8ff +xterm*color13: #b6a0ff +xterm*color14: #6ae4b9 +xterm*color15: #ffffff +#+end_src + +** Visualize the active Modus theme's palette +:properties: +:custom_id: h:f4d4b71b-2ca5-4c3d-b0b4-9bfd7aa7fb4d +:end: +#+findex: modus-themes-list-colors +#+findex: modus-themes-list-colors-current +#+cindex: Preview color values + +The command ~modus-themes-list-colors~ prompts for a choice between +=modus-operandi= and =modus-vivendi= to produce a help buffer that shows a +preview of each variable in the given theme's color palette. The +command ~modus-themes-list-colors-current~ skips the prompt, using the +current Modus theme. + +Each row shows a foreground and background coloration using the +underlying value it references. For example a line with =#a60000= (a +shade of red) will show red text followed by a stripe with that same +color as a backdrop. + +The name of the buffer describes the given Modus theme. It is thus +called =*modus-operandi-list-colors*= or =*modus-vivendi-list-colors*=. + ** Per-theme customization settings :properties: :custom_id: h:a897b302-8e10-4a26-beab-3caaee1e1193 @@ -1813,7 +2370,11 @@ The function always extracts the color value of the active Modus theme. #+end_src Do {{{kbd(C-h v)}}} on the aforementioned variables to check all the available -symbols that can be passed to this function. +symbols that can be passed to this function. Or simply invoke the +command ~modus-themes-list-colors~ to produce a buffer with a preview of +each entry in the palette. + +[[#h:f4d4b71b-2ca5-4c3d-b0b4-9bfd7aa7fb4d][Visualize the active Modus theme's palette]]. With that granted, let us expand the example to actually change the ~cursor~ face's background property. We employ the built-in function of @@ -1892,7 +2453,10 @@ The ~modus-themes-with-colors~ macro lets you retrieve multiple color values by employing the backquote/backtick and comma notation. The values are stored in the alists ~modus-themes-operandi-colors~ and ~modus-themes-vivendi-colors~, while the macro always queries that of the -active Modus theme. +active Modus theme (preview the current palette with the command +~modus-themes-list-colors~). + +[[#h:f4d4b71b-2ca5-4c3d-b0b4-9bfd7aa7fb4d][Visualize the active Modus theme's palette]]. Here is an abstract example that just returns a list of color values while ~modus-operandi~ is enabled: @@ -2069,8 +2633,7 @@ contrast on an on-demand basis. One way to achieve this is to design a command that cycles through three distinct levels of intensity, though the following can be adapted to any -kind of cyclic behavior, such as to switch between red, green, and -blue. +kind of cyclic behavior, such as to switch between red, green, and blue. In the following example, we employ the ~modus-themes-color~ function which reads a symbol that represents an entry in the active theme's @@ -2230,9 +2793,11 @@ The themes provide a mechanism for overriding their color values. This is controlled by the variables ~modus-themes-operandi-color-overrides~ and ~modus-themes-vivendi-color-overrides~, which are alists that should mirror a subset of the associations in ~modus-themes-operandi-colors~ and -~modus-themes-vivendi-colors~ respectively. As with all customisations, +~modus-themes-vivendi-colors~ respectively. As with all customizations, overriding must be done before loading the affected theme. +[[#h:f4d4b71b-2ca5-4c3d-b0b4-9bfd7aa7fb4d][Visualize the active Modus theme's palette]]. + Let us approach the present topic one step at a time. Here is a simplified excerpt of the default palette for Modus Operandi with some basic background values that apply to buffers and the mode line @@ -2291,10 +2856,8 @@ both themes and expands to some more assosiations in the palette: (bg-inactive . "#f6ece5") (bg-region . "#c6bab1") (bg-header . "#ede3e0") - (bg-tab-bar . "#dcd3d3") (bg-tab-active . "#fdf6eb") - (bg-tab-inactive . "#c8bab8") - (fg-unfocused . "#55556f")) + (bg-tab-inactive . "#c8bab8")) modus-themes-vivendi-color-overrides '((bg-main . "#100b17") (bg-dim . "#161129") @@ -2304,19 +2867,34 @@ both themes and expands to some more assosiations in the palette: (bg-inactive . "#1a1e39") (bg-region . "#393a53") (bg-header . "#202037") - (bg-tab-bar . "#262b41") (bg-tab-active . "#120f18") - (bg-tab-inactive . "#3a3a5a") - (fg-unfocused . "#9a9aab"))) + (bg-tab-inactive . "#3a3a5a"))) (setq modus-themes-operandi-color-overrides nil modus-themes-vivendi-color-overrides nil))) #+end_src -With this in place, one can invoke {{{kbd(M-x my-modus-themes-tinted)}}} and -then load the Modus theme of their choice. The new palette subset will -come into effect: subtle ochre tints for Modus Operandi and night sky -shades for Modus Vivendi. Switching between the two themes, such as -with {{{kbd(M-x modus-themes-toggle)}}} will also use the overrides. +A more neutral style for ~modus-themes-operandi-color-overrides~ can +look like this: + +#+begin_src emacs-lisp +'((bg-main . "#f7f7f7") + (bg-dim . "#f2f2f2") + (bg-alt . "#e8e8e8") + (bg-hl-line . "#eaeaef") + (bg-active . "#e0e0e0") + (bg-inactive . "#e6e6e6") + (bg-region . "#b5b5b5") + (bg-header . "#e4e4e4") + (bg-tab-active . "#f5f5f5") + (bg-tab-inactive . "#c0c0c0")) +#+end_src + +With those in place, one can use {{{kbd(M-x my-modus-themes-tinted)}}} +and then load the Modus theme of their choice. The new palette subset +will come into effect: subtle ochre tints (or shades of gray) for Modus +Operandi and night sky blue shades for Modus Vivendi. Switching between +the two themes, such as with {{{kbd(M-x modus-themes-toggle)}}} will +also use the overrides. Given that this is a user-level customization, one is free to implement whatever color values they desire, even if the possible combinations @@ -2324,6 +2902,9 @@ fall below the minimum 7:1 contrast ratio that governs the design of the themes (the WCAG AAA legibility standard). Alternatively, this can also be done programmatically ([[#h:4589acdc-2505-41fc-9f5e-699cfc45ab00][Override color saturation]]). +The above are expanded into a fully fledged derivative elsewhere in this +document ([[#h:736c0ff5-8c9c-4565-82cf-989e57d07d4a][Override colors completely]]). + For manual interventions it is advised to inspect the source code of ~modus-themes-operandi-colors~ and ~modus-themes-vivendi-colors~ for the inline commentary: it explains what the intended use of each palette @@ -2454,23 +3035,367 @@ inspiration from the ~modus-themes-toggle~ we already provide: ('modus-vivendi (modus-themes-load-vivendi)))) #+end_src +** Override colors through blending +:properties: +:custom_id: h:80c326bf-fe32-47b2-8c59-58022256fd6e +:end: +#+cindex: Change theme colors through blending + +This is yet another method of overriding color values. + +[[#h:307d95dd-8dbd-4ece-a543-10ae86f155a6][Override colors]]. + +[[#h:4589acdc-2505-41fc-9f5e-699cfc45ab00][Override color saturation]]. + +Building on ideas and concepts from the previous sections, this method +blends the entire palette at once with the chosen colors. The function +~my-modus-themes-interpolate~ blends two colors, taking a value from the +themes and mixing it with a user-defined color to arrive at a midpoint. +This scales to all background and foreground colors with the help of the +~my-modus-themes-tint-palette~ function. + +#+begin_src emacs-lisp +(setq my-modus-operandi-bg-blend "#fbf1c7" + my-modus-operandi-fg-blend "#3a6084" + my-modus-vivendi-bg-blend "#3a4042" + my-modus-vivendi-fg-blend "#d7b765") + +;; Adapted from the `kurecolor-interpolate' function of kurecolor.el +(defun my-modus-themes-interpolate (color1 color2) + (cl-destructuring-bind (r g b) + (mapcar #'(lambda (n) (* (/ n 2) 255.0)) + (cl-mapcar '+ (color-name-to-rgb color1) (color-name-to-rgb color2))) + (format "#%02X%02X%02X" r g b))) + +(defun my-modus-themes-tint-palette (palette bg-blend fg-blend) + "Modify Modus PALETTE programmatically and return a new palette. +Blend background colors with BG-BLEND and foreground colors with FG-BLEND." + (let (name cons colors) + (dolist (cons palette) + (let ((blend (if (string-match "bg" (symbol-name (car cons))) + bg-blend + fg-blend))) + (setq name (my-modus-themes-interpolate (cdr cons) blend))) + (setq name (format "%s" name)) + (setq cons `(,(car cons) . ,name)) + (push cons colors)) + colors)) + +(define-minor-mode modus-themes-tinted-mode + "Tweak some Modus themes colors." + :init-value nil + :global t + (if modus-themes-tinted-mode + (setq modus-themes-operandi-color-overrides + (my-modus-themes-tint-palette modus-themes-operandi-colors + my-modus-operandi-bg-blend + my-modus-operandi-fg-blend) + modus-themes-vivendi-color-overrides + (my-modus-themes-tint-palette modus-themes-vivendi-colors + my-modus-vivendi-bg-blend + my-modus-vivendi-fg-blend)) + (setq modus-themes-operandi-color-overrides nil + modus-themes-vivendi-color-overrides nil))) + +(modus-themes-tinted-mode 1) +#+end_src + +** Override colors completely +:PROPERTIES: +:CUSTOM_ID: h:736c0ff5-8c9c-4565-82cf-989e57d07d4a +:END: + +Based on the ideas we have already covered in these sections, the +following code block provides a complete, bespoke pair of color palettes +which override the defaults. They are implemented as a minor mode, as +explained before ([[#h:307d95dd-8dbd-4ece-a543-10ae86f155a6][Override colors]]). We call them "Summertime" for +convenience. + +#+begin_src emacs-lisp +;; Read the relevant blog post: +;; <https://protesilaos.com/codelog/2022-07-26-modus-themes-color-override-demo/> +(define-minor-mode modus-themes-summertime + "Refashion the Modus themes by overriding their colors. + +This is a complete technology demonstration to show how to +manually override the colors of the Modus themes. I have taken +good care of those overrides to make them work as a fully fledged +color scheme that is compatible with all user options of the +Modus themes. + +These overrides are usable by those who (i) like something more +fancy than the comparatively austere looks of the Modus themes, +and (ii) can cope with a lower contrast ratio. + +The overrides are set up as a minor mode, so that the user can +activate the effect on demand. Those who want to load the +overrides at all times can either add them directly to their +configuration or enable `modus-themes-summertime' BEFORE loading +either of the Modus themes (if the overrides are evaluated after +the theme, the theme must be reloaded). + +Remember that all changes to theme-related variables require a +reload of the theme to take effect (the Modus themes have lots of +user options, apart from those overrides). + +The `modus-themes-summertime' IS NOT an official extension to the +Modus themes and DOES NOT comply with its lofty accessibility +standards. It is included in the official manual as guidance for +those who want to make use of the color overriding facility we +provide." + :init-value nil + :global t + (if modus-themes-summertime + (setq modus-themes-operandi-color-overrides + '((bg-main . "#fff0f2") + (bg-dim . "#fbe6ef") + (bg-alt . "#f5dae6") + (bg-hl-line . "#fad8e3") + (bg-active . "#efcadf") + (bg-inactive . "#f3ddef") + (bg-active-accent . "#ffbbef") + (bg-region . "#dfc5d1") + (bg-region-accent . "#efbfef") + (bg-region-accent-subtle . "#ffd6ef") + (bg-header . "#edd3e0") + (bg-tab-active . "#ffeff2") + (bg-tab-inactive . "#f8d3ef") + (bg-tab-inactive-accent . "#ffd9f5") + (bg-tab-inactive-alt . "#e5c0d5") + (bg-tab-inactive-alt-accent . "#f3cce0") + (fg-main . "#543f78") + (fg-dim . "#5f476f") + (fg-alt . "#7f6f99") + (fg-unfocused . "#8f6f9f") + (fg-active . "#563068") + (fg-inactive . "#8a5698") + (fg-docstring . "#5f5fa7") + (fg-comment-yellow . "#a9534f") + (fg-escape-char-construct . "#8b207f") + (fg-escape-char-backslash . "#a06d00") + (bg-special-cold . "#d3e0f4") + (bg-special-faint-cold . "#e0efff") + (bg-special-mild . "#c4ede0") + (bg-special-faint-mild . "#e0f0ea") + (bg-special-warm . "#efd0c4") + (bg-special-faint-warm . "#ffe4da") + (bg-special-calm . "#f0d3ea") + (bg-special-faint-calm . "#fadff9") + (fg-special-cold . "#405fb8") + (fg-special-mild . "#407f74") + (fg-special-warm . "#9d6f4f") + (fg-special-calm . "#af509f") + (bg-completion . "#ffc5e5") + (bg-completion-subtle . "#f7cfef") + (red . "#ed2f44") + (red-alt . "#e0403d") + (red-alt-other . "#e04059") + (red-faint . "#ed4f44") + (red-alt-faint . "#e0603d") + (red-alt-other-faint . "#e06059") + (green . "#217a3c") + (green-alt . "#417a1c") + (green-alt-other . "#006f3c") + (green-faint . "#318a4c") + (green-alt-faint . "#518a2c") + (green-alt-other-faint . "#20885c") + (yellow . "#b06202") + (yellow-alt . "#a95642") + (yellow-alt-other . "#a06f42") + (yellow-faint . "#b07232") + (yellow-alt-faint . "#a96642") + (yellow-alt-other-faint . "#a08042") + (blue . "#275ccf") + (blue-alt . "#475cc0") + (blue-alt-other . "#3340ef") + (blue-faint . "#476ce0") + (blue-alt-faint . "#575ccf") + (blue-alt-other-faint . "#3f60d7") + (magenta . "#bf317f") + (magenta-alt . "#d033c0") + (magenta-alt-other . "#844fe4") + (magenta-faint . "#bf517f") + (magenta-alt-faint . "#d053c0") + (magenta-alt-other-faint . "#846fe4") + (cyan . "#007a9f") + (cyan-alt . "#3f709f") + (cyan-alt-other . "#107f7f") + (cyan-faint . "#108aaf") + (cyan-alt-faint . "#3f80af") + (cyan-alt-other-faint . "#3088af") + (red-active . "#cd2f44") + (green-active . "#116a6c") + (yellow-active . "#993602") + (blue-active . "#475ccf") + (magenta-active . "#7f2ccf") + (cyan-active . "#007a8f") + (red-nuanced-bg . "#ffdbd0") + (red-nuanced-fg . "#ed6f74") + (green-nuanced-bg . "#dcf0dd") + (green-nuanced-fg . "#3f9a4c") + (yellow-nuanced-bg . "#fff3aa") + (yellow-nuanced-fg . "#b47232") + (blue-nuanced-bg . "#e3e3ff") + (blue-nuanced-fg . "#201f6f") + (magenta-nuanced-bg . "#fdd0ff") + (magenta-nuanced-fg . "#c0527f") + (cyan-nuanced-bg . "#dbefff") + (cyan-nuanced-fg . "#0f3f60") + (bg-diff-heading . "#b7cfe0") + (fg-diff-heading . "#041645") + (bg-diff-added . "#d6f0d6") + (fg-diff-added . "#004520") + (bg-diff-changed . "#fcefcf") + (fg-diff-changed . "#524200") + (bg-diff-removed . "#ffe0ef") + (fg-diff-removed . "#891626") + (bg-diff-refine-added . "#84cfa4") + (fg-diff-refine-added . "#002a00") + (bg-diff-refine-changed . "#cccf8f") + (fg-diff-refine-changed . "#302010") + (bg-diff-refine-removed . "#da92b0") + (fg-diff-refine-removed . "#500010") + (bg-diff-focus-added . "#a6e5c6") + (fg-diff-focus-added . "#002c00") + (bg-diff-focus-changed . "#ecdfbf") + (fg-diff-focus-changed . "#392900") + (bg-diff-focus-removed . "#efbbcf") + (fg-diff-focus-removed . "#5a0010")) + modus-themes-vivendi-color-overrides + '((bg-main . "#25152a") + (bg-dim . "#2a1930") + (bg-alt . "#382443") + (bg-hl-line . "#332650") + (bg-active . "#463358") + (bg-inactive . "#2d1f3a") + (bg-active-accent . "#50308f") + (bg-region . "#5d4a67") + (bg-region-accent . "#60509f") + (bg-region-accent-subtle . "#3f285f") + (bg-header . "#3a2543") + (bg-tab-active . "#26162f") + (bg-tab-inactive . "#362647") + (bg-tab-inactive-accent . "#36265a") + (bg-tab-inactive-alt . "#3e2f5a") + (bg-tab-inactive-alt-accent . "#3e2f6f") + (fg-main . "#debfe0") + (fg-dim . "#d0b0da") + (fg-alt . "#ae85af") + (fg-unfocused . "#8e7f9f") + (fg-active . "#cfbfef") + (fg-inactive . "#b0a0c0") + (fg-docstring . "#c8d9f7") + (fg-comment-yellow . "#cf9a70") + (fg-escape-char-construct . "#ff75aa") + (fg-escape-char-backslash . "#dbab40") + (bg-special-cold . "#2a3f58") + (bg-special-faint-cold . "#1e283f") + (bg-special-mild . "#0f3f31") + (bg-special-faint-mild . "#0f281f") + (bg-special-warm . "#44331f") + (bg-special-faint-warm . "#372213") + (bg-special-calm . "#4a314f") + (bg-special-faint-calm . "#3a223f") + (fg-special-cold . "#c0b0ff") + (fg-special-mild . "#bfe0cf") + (fg-special-warm . "#edc0a6") + (fg-special-calm . "#ff9fdf") + (bg-completion . "#502d70") + (bg-completion-subtle . "#451d65") + (red . "#ff5f6f") + (red-alt . "#ff8f6d") + (red-alt-other . "#ff6f9d") + (red-faint . "#ffa0a0") + (red-alt-faint . "#f5aa80") + (red-alt-other-faint . "#ff9fbf") + (green . "#51ca5c") + (green-alt . "#71ca3c") + (green-alt-other . "#51ca9c") + (green-faint . "#78bf78") + (green-alt-faint . "#99b56f") + (green-alt-other-faint . "#88bf99") + (yellow . "#f0b262") + (yellow-alt . "#f0e242") + (yellow-alt-other . "#d0a272") + (yellow-faint . "#d2b580") + (yellow-alt-faint . "#cabf77") + (yellow-alt-other-faint . "#d0ba95") + (blue . "#778cff") + (blue-alt . "#8f90ff") + (blue-alt-other . "#8380ff") + (blue-faint . "#82b0ec") + (blue-alt-faint . "#a0acef") + (blue-alt-other-faint . "#80b2f0") + (magenta . "#ff70cf") + (magenta-alt . "#ff77f0") + (magenta-alt-other . "#ca7fff") + (magenta-faint . "#e0b2d6") + (magenta-alt-faint . "#ef9fe4") + (magenta-alt-other-faint . "#cfa6ff") + (cyan . "#30cacf") + (cyan-alt . "#60caff") + (cyan-alt-other . "#40b79f") + (cyan-faint . "#90c4ed") + (cyan-alt-faint . "#a0bfdf") + (cyan-alt-other-faint . "#a4d0bb") + (red-active . "#ff6059") + (green-active . "#64dc64") + (yellow-active . "#ffac80") + (blue-active . "#4fafff") + (magenta-active . "#cf88ff") + (cyan-active . "#50d3d0") + (red-nuanced-bg . "#440a1f") + (red-nuanced-fg . "#ffcccc") + (green-nuanced-bg . "#002904") + (green-nuanced-fg . "#b8e2b8") + (yellow-nuanced-bg . "#422000") + (yellow-nuanced-fg . "#dfdfb0") + (blue-nuanced-bg . "#1f1f5f") + (blue-nuanced-fg . "#bfd9ff") + (magenta-nuanced-bg . "#431641") + (magenta-nuanced-fg . "#e5cfef") + (cyan-nuanced-bg . "#042f49") + (cyan-nuanced-fg . "#a8e5e5") + (bg-diff-heading . "#304466") + (fg-diff-heading . "#dae7ff") + (bg-diff-added . "#0a383a") + (fg-diff-added . "#94ba94") + (bg-diff-changed . "#2a2000") + (fg-diff-changed . "#b0ba9f") + (bg-diff-removed . "#50163f") + (fg-diff-removed . "#c6adaa") + (bg-diff-refine-added . "#006a46") + (fg-diff-refine-added . "#e0f6e0") + (bg-diff-refine-changed . "#585800") + (fg-diff-refine-changed . "#ffffcc") + (bg-diff-refine-removed . "#952838") + (fg-diff-refine-removed . "#ffd9eb") + (bg-diff-focus-added . "#1d4c3f") + (fg-diff-focus-added . "#b4dfb4") + (bg-diff-focus-changed . "#424200") + (fg-diff-focus-changed . "#d0daaf") + (bg-diff-focus-removed . "#6f0f39") + (fg-diff-focus-removed . "#eebdba"))) + (setq modus-themes-operandi-color-overrides nil + modus-themes-vivendi-color-overrides nil))) +#+end_src + ** Font configurations for Org and others :properties: :custom_id: h:defcf4fc-8fa8-4c29-b12e-7119582cc929 :end: #+cindex: Font configurations -The themes are designed to cope well with mixed font configurations. - -[[#h:115e6c23-ee35-4a16-8cef-e2fcbb08e28b][Option for no font mixing]]. +The themes are designed to optionally cope well with mixed font +configurations. This mostly concerns ~org-mode~ and ~markdown-mode~, though +expect to find it elsewhere like in ~Info-mode~. -This mostly concerns ~org-mode~ and ~markdown-mode~, though expect to find -it elsewhere like in ~Info-mode~. +[[#h:115e6c23-ee35-4a16-8cef-e2fcbb08e28b][Option for font mixing]]. In practice it means that the user can safely opt for a more prose-friendly proportionately spaced typeface as their default, while -letting spacing-sensitive elements like tables and inline code always -use a monospaced font, by inheriting from the ~fixed-pitch~ face. +spacing-sensitive elements like tables and inline code always use a +monospaced font, by inheriting from the ~fixed-pitch~ face. Users can try the built-in {{{kbd(M-x variable-pitch-mode)}}} to see the effect in action. @@ -2480,6 +3405,9 @@ the ~variable-pitch~ (proportional spacing) and ~fixed-pitch~ (monospaced) faces respectively. It may also be convenient to set your main typeface by configuring the ~default~ face the same way. +[ The =fontaine= package on GNU ELPA (by the author of the modus-themes) + is designed to handle this case. ] + Put something like this in your initialization file (also consider reading the doc string of ~set-face-attribute~): @@ -2491,7 +3419,14 @@ reading the doc string of ~set-face-attribute~): (set-face-attribute 'variable-pitch nil :family "DejaVu Serif" :height 1.0) ;; Monospaced typeface -(set-face-attribute 'fixed-pitch nil :family "DejaVu Sans Mono" :height 1.0) +(set-face-attribute 'fixed-pitch nil :family "DejaVu Sans Mono" :height 1.5) +#+end_src + +Or employ the ~face-attribute~ function to read an existing value, such as +if you want to make ~fixed-pitch~ use the font family of the ~default~ face: + +#+begin_src emacs-lisp +(set-face-attribute 'fixed-pitch nil :family (face-attribute 'default :family)) #+end_src The next section shows how to make those work in a more elaborate setup @@ -2504,12 +3439,13 @@ specify an absolute value, which is the point size × 10. So if you want to use a font at point size =11=, you set the height to =110=.[fn:: ~:height~ values do not need to be rounded to multiples of ten: the likes of =115= are perfectly valid—some typefaces will change to account for those -finer increments.] Whereas every other face must have a value that is -relative to the default, represented as a floating point (if you use an -integer, then that means an absolute height). This is of paramount -importance: it ensures that all fonts can scale gracefully when using -something like the ~text-scale-adjust~ command which only operates on the -base font size (i.e. the ~default~ face's absolute height). +finer increments.] Whereas every other face must either not specify a +height or have a value that is relative to the default, represented as a +floating point. If you use an integer, then that means an absolute +height. This is of paramount importance: it ensures that all fonts can +scale gracefully when using something like the ~text-scale-adjust~ command +which only operates on the base font size (i.e. the ~default~ face's +absolute height). [[#h:e6c5451f-6763-4be7-8fdb-b4706a422a4c][Note for EWW and Elfeed fonts]]. @@ -2545,7 +3481,7 @@ it means for a construct to be bold/italic, by tweaking the ~bold~ and To achieve those effects, one must first be sure that the fonts they use have support for those features. It then is a matter of following the -instructions for all face tweaks. +instructions for all typeface tweaks. [[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. @@ -2573,19 +3509,20 @@ To reset the font family, one can use this: To ensure that the effects persist after switching between the Modus themes (such as with {{{kbd(M-x modus-themes-toggle)}}}), the user needs to -write their configurations to a function and hook it up to the -~modus-themes-after-load-theme-hook~. This is necessary because the -themes set the default styles of faces (otherwise changing themes would -not be possible). +write their configurations to a function and pass it to the +~modus-themes-after-load-theme-hook~. This is necessary because themes +set the styles of faces upon activation, overriding prior values where +conflicts occur between the previous and the current states (otherwise +changing themes would not be possible). [[#h:86f6906b-f090-46cc-9816-1fe8aeb38776][A theme-agnostic hook for theme loading]]. This is a minimal setup to preserve font configurations across theme -load phases. For a more permanent setup, it is better to employ the +load phases. For a more permanent setup, it is better to rely on the ~custom-set-faces~ function: ~set-face-attribute~ works just fine, though it -is more convenient for quick previews or for smaller scale operations -(~custom-set-faces~ follows the format used in the source code of the -themes). +probably is better suited for quick previews or for smaller scale +operations (~custom-set-faces~ follows the format used in the source code +of the themes, which can make it easier to redefine faces in bulk). #+begin_src emacs-lisp ;; our generic function @@ -2605,11 +3542,13 @@ themes). (add-hook 'modus-themes-after-load-theme-hook #'my-modes-themes-bold-italic-faces) #+end_src -** Custom Org user faces +[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]. + +** Custom Org todo keyword and priority faces :properties: :custom_id: h:89f0678d-c5c3-4a57-a526-668b2bb2d7ad :end: -#+cindex: Org extra faces +#+cindex: Org custom todo faces Users of ~org-mode~ have the option to configure various keywords and priority cookies to better match their workflow. User options are @@ -2693,6 +3632,139 @@ it if you plan to control face attributes. [[#h:02e25930-e71a-493d-828a-8907fc80f874][Check color combinations]]. +** Custom Org emphasis faces +:properties: +:custom_id: h:26026302-47f4-4471-9004-9665470e7029 +:end: +#+cindex: Org custom emphasis faces + +Org provides the user option ~org-emphasis-alist~ which associates a +character with a face, list of faces, or face attributes. The default +specification of that variable looks like this: + +#+begin_src emacs-lisp +(setq org-emphasis-alist + '(("*" bold) + ("/" italic) + ("_" underline) + ("=" org-verbatim verbatim) + ("~" org-code verbatim) + ("+" (:strike-through t)))) +#+end_src + +With the exception of ~org-verbatim~ and ~org-code~ faces, everything else +uses the corresponding type of emphasis: a bold typographic weight, or +italicised, underlined, and struck through text. + +The best way for users to add some extra attributes, such as a +foreground color, is to define their own faces and assign them to the +given emphasis marker/character. + +This is a custom face that extends the standard ~bold~ face with a red +foreground value (so it colorises the text in addition to the bold +weight): + +#+begin_src emacs-lisp +(defface my-org-emphasis-bold + '((default :inherit bold) + (((class color) (min-colors 88) (background light)) + :foreground "#a60000") + (((class color) (min-colors 88) (background dark)) + :foreground "#ff8059")) + "My bold emphasis for Org.") +#+end_src + +This face definition reads as follows: + ++ Always inherit the ~bold~ face ([[#h:2793a224-2109-4f61-a106-721c57c01375][Configure bold and italic faces]]). ++ For versions of Emacs that support at least 88 colors (graphical + Emacs, for example) and use a light background, apply the =#a60000= + value. ++ For the same kind of Emacs that has a dark background use the =#ff8059= + color instead. + +Same principle for how to extend ~italic~ and ~underline~ with, for example, +green and yellow hues, respectively: + +#+begin_src emacs-lisp +(defface my-org-emphasis-italic + '((default :inherit italic) + (((class color) (min-colors 88) (background light)) + :foreground "#005e00") + (((class color) (min-colors 88) (background dark)) + :foreground "#44bc44")) + "My italic emphasis for Org.") + +(defface my-org-emphasis-underline + '((default :inherit underline) + (((class color) (min-colors 88) (background light)) + :foreground "#813e00") + (((class color) (min-colors 88) (background dark)) + :foreground "#d0bc00")) + "My underline emphasis for Org.") +#+end_src + +In the case of a strike-through effect, we have no generic face to +inherit from, so we can write it as follows to also change the +foreground to a more subtle gray: + +#+begin_src emacs-lisp +(defface my-org-emphasis-strike-through + '((default :strike-through t) + (((class color) (min-colors 88) (background light)) + :foreground "#505050") + (((class color) (min-colors 88) (background dark)) + :foreground "#a8a8a8")) + "My strike-through emphasis for Org.") +#+end_src + +Or we can just change the color of the line that strikes through the +text to, for example, a shade of red: + +#+begin_src emacs-lisp +(defface my-org-emphasis-strike-through + '((((class color) (min-colors 88) (background light)) + :strike-through "#972500") + (((class color) (min-colors 88) (background dark)) + :strike-through "#ef8b50")) + "My strike-through emphasis for Org.") +#+end_src + +It is possible to combine those effects: + +#+begin_src emacs-lisp +(defface my-org-emphasis-strike-through + '((((class color) (min-colors 88) (background light)) + :strike-through "#972500" :foreground "#505050") + (((class color) (min-colors 88) (background dark)) + :strike-through "#ef8b50" :foreground "#a8a8a8")) + "My strike-through emphasis for Org.") +#+end_src + +One may inspect the variables ~modus-themes-operandi-colors~ and +~modus-themes-vivendi-colors~ for possible color values. Or call the +command ~modus-themes-list-colors~ to show a buffer that previews each +entry in the palette. + +[[#h:f4d4b71b-2ca5-4c3d-b0b4-9bfd7aa7fb4d][Visualize the active Modus theme's palette]]. + +Once we have defined the faces we need, we must update the +~org-emphasis-alist~. Given that ~org-verbatim~ and ~org-code~ are already +styled by the themes, it probably is best not to edit them: + +#+begin_src emacs-lisp +(setq org-emphasis-alist + '(("*" my-org-emphasis-bold) + ("/" my-org-emphasis-italic) + ("_" my-org-emphasis-underline) + ("=" org-verbatim verbatim) + ("~" org-code verbatim) + ("+" my-org-emphasis-strike-through))) +#+end_src + +That's it! For changes to take effect in already visited Org files, +invoke {{{kbd(M-x org-mode-restart)}}}. + ** Update Org block delimiter fontification :properties: :custom_id: h:f44cc6e3-b0f1-4a5e-8a90-9e48fa557b50 @@ -2889,13 +3961,144 @@ at something like the following, which builds on the above example: (pdf-view-midnight-minor-mode -1)) (my-pdf-tools-backdrop))) +(defun my-pdf-tools-themes-toggle () + (mapc + (lambda (buf) + (with-current-buffer buf + (my-pdf-tools-midnight-mode-toggle))) + (buffer-list))) + (add-hook 'pdf-tools-enabled-hook #'my-pdf-tools-midnight-mode-toggle) -(add-hook 'modus-themes-after-load-theme-hook #'my-pdf-tools-midnight-mode-toggle) +(add-hook 'modus-themes-after-load-theme-hook #'my-pdf-tools-themes-toggle) #+end_src With those in place, PDFs have a distinct backdrop for their page, while -they automatically switch to their dark mode when ~modus-themes-toggle~ is -called from inside a buffer whose major-mode is ~pdf-view-mode~. +buffers with major-mode as ~pdf-view-mode~ automatically switches to dark +mode when ~modus-themes-toggle~ is called. + +** Decrease mode line height +:properties: +:custom_id: h:03be4438-dae1-4961-9596-60a307c070b5 +:end: +#+cindex: Decrease mode line height + +By default, the mode line of the Modus themes is set to 1 pixel width +for its =:box= attribute. In contrast, the mode line of stock Emacs is -1 +pixel. This small difference is considered necessary for the purposes +of accessibility as our out-of-the-box design has a prominent color +around the mode line (a border) to make its boundaries clear. With a +negative width the border and the text on the mode line can feel a bit +more difficult to read under certain scenaria. + +Furthermore, the user option ~modus-themes-mode-line~ ([[#h:27943af6-d950-42d0-bc23-106e43f50a24][Mode line]]) does not +allow for such a negative value because there are many edge cases that +simply make for a counter-intuitive set of possibilities, such as a =0= +value not being acceptable by the underlying face infrastructure, and +negative values greater than =-2= not being particularly usable. + +For these reasons, users who wish to decrease the overall height of the +mode line must handle things on their own by implementing the methods +for face customization documented herein. + +[[#h:1487c631-f4fe-490d-8d58-d72ffa3bd474][Basic face customization]]. + +One such method is to create a function that configures the desired +faces and hook it to ~modus-themes-after-load-theme-hook~ so that it +persists while switching between the Modus themes with the command +~modus-themes-toggle~. + +This one simply disables the box altogether, which will reduce the +height of the mode lines, but also remove their border: + +#+begin_src emacs-lisp +(defun my-modus-themes-custom-faces () + (set-face-attribute 'mode-line nil :box nil) + (set-face-attribute 'mode-line-inactive nil :box nil)) + +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) +#+end_src + +The above relies on the ~set-face-attribute~ function, though users who +plan to re-use colors from the theme and do so at scale are better off +with the more streamlined combination of the ~modus-themes-with-colors~ +macro and ~custom-set-faces~. + +[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face customization at scale]]. + +As explained before in this document, this approach has a syntax that is +consistent with the source code of the themes, so it probably is easier +to re-use parts of the design. + +The following emulates the stock Emacs style, while still using the +colors of the Modus themes (whichever attribute is not explicitly stated +is inherited from the underlying theme): + +#+begin_src emacs-lisp +(defun my-modus-themes-custom-faces () + (modus-themes-with-colors + (custom-set-faces + `(mode-line ((,class :box (:line-width -1 :style released-button)))) + `(mode-line-inactive ((,class :box (:line-width -1 :color ,bg-region))))))) + +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) +#+end_src + +And this one is like the out-of-the-box style of the Modus themes, but +with the -1 height instead of 1: + +#+begin_src emacs-lisp +(defun my-modus-themes-custom-faces () + (modus-themes-with-colors + (custom-set-faces + `(mode-line ((,class :box (:line-width -1 :color ,fg-alt)))) + `(mode-line-inactive ((,class :box (:line-width -1 :color ,bg-region))))))) + +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) +#+end_src + +Finally, to also change the background color of the active mode line, +such as that it looks like the "accented" variant which is possible via +the user option ~modus-themes-mode-line~, the =:background= attribute needs +to be specified as well: + +#+begin_src emacs-lisp +(defun my-modus-themes-custom-faces () + (modus-themes-with-colors + (custom-set-faces + `(mode-line ((,class :box (:line-width -1 :color ,fg-alt) :background ,bg-active-accent))) + `(mode-line-inactive ((,class :box (:line-width -1 :color ,bg-region))))))) + +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) +#+end_src + +** Toggle themes without reloading them +:properties: +:custom_id: h:b40aca50-a3b2-4c43-be58-2c26fcd14237 +:end: +#+cindex: Switch themes without load-theme + +Users who have a stable setup and who only ever need to toggle between +the themes without triggering a full reload, are better off defining +their own command which calls ~enable-theme~ instead of ~load-theme~: + +#+begin_src emacs-lisp +(defun my-modus-themes-toggle () + "Toggle between `modus-operandi' and `modus-vivendi' themes. +This uses `enable-theme' instead of the standard method of +`load-theme'. The technicalities are covered in the Modus themes +manual." + (interactive) + (pcase (modus-themes--current-theme) + ('modus-operandi (progn (enable-theme 'modus-vivendi) + (disable-theme 'modus-operandi))) + ('modus-vivendi (progn (enable-theme 'modus-operandi) + (disable-theme 'modus-vivendi))) + (_ (error "No Modus theme is loaded; evaluate `modus-themes-load-themes' first")))) +#+end_src + +[[#h:e68560b3-7fb0-42bc-a151-e015948f8a35][Differences between loading and enabling]]. + +Recall that ~modus-themes-toggle~ uses ~load-theme~. ** A theme-agnostic hook for theme loading :properties: @@ -2946,6 +4149,325 @@ user. Hence our hesitation to recommend it as part of the standard setup of the Modus themes (it is generally a good idea to understand what the implications are of advising a function). +** Diffs with only the foreground +:properties: +:custom_id: h:e2aed9eb-5e1e-45ec-bbd7-bc4faeab3236 +:end: +#+cindex: Foreground-only diffs + +Buffers that show differences between versions of a file or buffer, such +as in ~diff-mode~ and ~ediff~ always use color-coded background and +foreground combinations. + +[[#h:ea7ac54f-5827-49bd-b09f-62424b3b6427][Option for diff buffer looks]]. + +User may, however, prefer a style that removes the color-coded +backgrounds from regular changes while keeping them for word-wise (aka +"refined") changes---backgrounds for word-wise diffs are helpful in +context. To make this happen, one can use the ~modus-themes-with-colors~ +macro ([[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]): + +#+begin_src emacs-lisp +(defun my-modus-themes-custom-faces () + (modus-themes-with-colors + (custom-set-faces + `(modus-themes-diff-added ((,class :background unspecified :foreground ,green))) ; OR ,blue for deuteranopia + `(modus-themes-diff-changed ((,class :background unspecified :foreground ,yellow))) + `(modus-themes-diff-removed ((,class :background unspecified :foreground ,red))) + + `(modus-themes-diff-refine-added ((,class :background ,bg-diff-added :foreground ,fg-diff-added))) + ;; `(modus-themes-diff-refine-added ((,class :background ,bg-diff-added-deuteran :foreground ,fg-diff-added-deuteran))) + `(modus-themes-diff-refine-changed ((,class :background ,bg-diff-changed :foreground ,fg-diff-changed))) + `(modus-themes-diff-refine-removed ((,class :background ,bg-diff-removed :foreground ,fg-diff-removed))) + + `(modus-themes-diff-focus-added ((,class :background ,bg-dim :foreground ,green))) ; OR ,blue for deuteranopia + `(modus-themes-diff-focus-changed ((,class :background ,bg-dim :foreground ,yellow))) + `(modus-themes-diff-focus-removed ((,class :background ,bg-dim :foreground ,red))) + + `(modus-themes-diff-heading ((,class :background ,bg-alt :foreground ,fg-main))) + + `(diff-indicator-added ((,class :foreground ,green))) ; OR ,blue for deuteranopia + `(diff-indicator-changed ((,class :foreground ,yellow))) + `(diff-indicator-removed ((,class :foreground ,red))) + + `(magit-diff-added ((,class :background unspecified :foreground ,green-faint))) + `(magit-diff-changed ((,class :background unspecified :foreground ,yellow-faint))) + `(magit-diff-removed ((,class :background unspecified :foreground ,red-faint))) + `(magit-diff-context-highlight ((,class :background ,bg-dim :foreground ,fg-dim)))))) + +;; This is so that the changes persist when switching between +;; `modus-operandi' and `modus-vivendi'. +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) +#+end_src + +This used to be an optional style of ~modus-themes-diffs~, but has been +removed since version =2.0.0= to ensure that the accessibility standard +and aesthetic quality of the themes is not compromised. + +** Ediff without diff color-coding +:properties: +:custom_id: h:b0b31802-0216-427e-b071-1a47adcfe608 +:end: + +Ediff uses the same color-coding as ordinary diffs in ~diff-mode~, Magit, +etc. ([[#h:ea7ac54f-5827-49bd-b09f-62424b3b6427][Option for diff buffer looks]]). This is consistent with the +principle of least surprise. + +Users may, however, prefer to treat Ediff differently on the premise +that it does not need any particular color-coding to show added or +removed lines/words: it does not use the =+= or =-= markers, after all. + +This can be achieved by customizing the Ediff faces with color +combinations that do not carry the same connotations as those of diffs. +Consider this example, which leverages the ~modus-themes-with-colors~ +macro ([[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]): + +#+begin_src emacs-lisp +(defun my-modus-themes-custom-faces () + (modus-themes-with-colors + (custom-set-faces + `(ediff-current-diff-A ((,class :inherit unspecified :background ,bg-special-faint-cold :foreground ,fg-special-cold))) + `(ediff-current-diff-B ((,class :inherit unspecified :background ,bg-special-faint-warm :foreground ,fg-special-warm))) + `(ediff-current-diff-C ((,class :inherit unspecified :background ,bg-special-faint-calm :foreground ,fg-special-calm))) + `(ediff-fine-diff-A ((,class :inherit unspecified :background ,bg-special-cold :foreground ,fg-special-cold))) + `(ediff-fine-diff-B ((,class :inherit unspecified :background ,bg-special-warm :foreground ,fg-special-warm))) + `(ediff-fine-diff-C ((,class :inherit unspecified :background ,bg-special-calm :foreground ,fg-special-calm)))))) + +;; This is so that the changes persist when switching between +;; `modus-operandi' and `modus-vivendi'. +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) +#+end_src + +Remove the =:foreground= and its value to preserve the underlying +coloration. + +[[#h:f4d4b71b-2ca5-4c3d-b0b4-9bfd7aa7fb4d][Visualize the active Modus theme's palette]]. + +** Near-monochrome syntax highlighting +:properties: +:custom_id: h:c1f3fa8e-7a63-4a6f-baf3-a7febc0661f0 +:end: +#+cindex: Monochrome code syntax + +While the Modus themes do provide a user option to control the overall +style of syntax highlighting in programming major modes, they do not +cover the possibility of a monochromatic or near-monochromatic design +([[#h:c119d7b2-fcd4-4e44-890e-5e25733d5e52][Option for syntax highlighting]]). This is due to the multitude of +preferences involved: one may like comments to be styled with an accent +value, another may want certain constructs to be bold, a third may apply +italics to doc strings but not comments... The possibilities are +virtually endless. As such, this sort of design is best handled at the +user level in accordance with the information furnished elsewhere in +this manual. + +[[#h:1487c631-f4fe-490d-8d58-d72ffa3bd474][Case-by-case face specs using the themes' palette]]. + +[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]. + +The gist is that we want to override the font-lock faces. For our +changes to persist while switching between ~modus-operandi~ and +~modus-vivendi~ we wrap our face overrides in a function that we hook to +~modus-themes-after-load-theme-hook~. + +Users who want to replicate the structure of the themes' source code are +advised to use the examples with ~custom-set-faces~. Those who prefer a +different approach can use the snippets which call ~set-face-attribute~. +Below are the code blocks. + +The following uses a yellow accent value for comments and green hues for +strings. Regexp grouping constructs have color values that work in the +context of a green string. All other elements use the main foreground +color, except warnings such as the ~user-error~ function in Elisp +buffers which gets a subtle red tint (not to be confused with the +~warning~ face which is used for genuine warnings). Furthermore, notice +the ~modus-themes-bold~ and ~modus-themes-slant~ which apply the +preference set in the user options ~modus-themes-bold-constructs~ and +~modus-themes-italic-constructs~, respectively. Users who do not want +this conditionally must replace these faces with ~bold~ and ~italic~ +respectively (or ~unspecified~ to disable the effect altogether). + +#+begin_src emacs-lisp +;; This is the hook. It will not be replicated across all code samples. +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-subtle-syntax) + +(defun my-modus-themes-subtle-syntax () + (modus-themes-with-colors + (custom-set-faces + `(font-lock-builtin-face ((,class :inherit modus-themes-bold :foreground unspecified))) + `(font-lock-comment-delimiter-face ((,class :inherit font-lock-comment-face))) + `(font-lock-comment-face ((,class :inherit unspecified :foreground ,fg-comment-yellow))) + `(font-lock-constant-face ((,class :foreground unspecified))) + `(font-lock-doc-face ((,class :inherit modus-themes-slant :foreground ,fg-special-mild))) + `(font-lock-function-name-face ((,class :foreground unspecified))) + `(font-lock-keyword-face ((,class :inherit modus-themes-bold :foreground unspecified))) + `(font-lock-negation-char-face ((,class :inherit modus-themes-bold :foreground unspecified))) + `(font-lock-preprocessor-face ((,class :foreground unspecified))) + `(font-lock-regexp-grouping-backslash ((,class :inherit bold :foreground ,yellow))) + `(font-lock-regexp-grouping-construct ((,class :inherit bold :foreground ,blue-alt-other))) + `(font-lock-string-face ((,class :foreground ,green-alt-other))) + `(font-lock-type-face ((,class :inherit modus-themes-bold :foreground unspecified))) + `(font-lock-variable-name-face ((,class :foreground unspecified))) + `(font-lock-warning-face ((,class :inherit modus-themes-bold :foreground ,red-nuanced-fg)))))) + +;; Same as above with `set-face-attribute' instead of `custom-set-faces' +(defun my-modus-themes-subtle-syntax () + (modus-themes-with-colors + (set-face-attribute 'font-lock-builtin-face nil :inherit 'modus-themes-bold :foreground 'unspecified) + (set-face-attribute 'font-lock-comment-delimiter-face nil :inherit 'font-lock-comment-face) + (set-face-attribute 'font-lock-comment-face nil :inherit 'unspecified :foreground fg-comment-yellow) + (set-face-attribute 'font-lock-constant-face nil :foreground 'unspecified) + (set-face-attribute 'font-lock-doc-face nil :inherit 'modus-themes-slant :foreground fg-special-mild) + (set-face-attribute 'font-lock-function-name-face nil :foreground 'unspecified) + (set-face-attribute 'font-lock-keyword-face nil :inherit 'modus-themes-bold :foreground 'unspecified) + (set-face-attribute 'font-lock-negation-char-face nil :inherit 'modus-themes-bold :foreground 'unspecified) + (set-face-attribute 'font-lock-preprocessor-face nil :foreground 'unspecified) + (set-face-attribute 'font-lock-regexp-grouping-backslash nil :inherit 'bold :foreground yellow) + (set-face-attribute 'font-lock-regexp-grouping-construct nil :inherit 'bold :foreground blue-alt-other) + (set-face-attribute 'font-lock-string-face nil :foreground green-alt-other) + (set-face-attribute 'font-lock-type-face nil :inherit 'modus-themes-bold :foreground 'unspecified) + (set-face-attribute 'font-lock-variable-name-face nil :foreground 'unspecified) + (set-face-attribute 'font-lock-warning-face nil :inherit 'modus-themes-bold :foreground red-nuanced-fg))) +#+end_src + +The following sample is the same as above, except strings are blue and +comments are gray. Regexp constructs are adapted accordingly. + +#+begin_src emacs-lisp +(defun my-modus-themes-subtle-syntax () + (modus-themes-with-colors + (custom-set-faces + `(font-lock-builtin-face ((,class :inherit modus-themes-bold :foreground unspecified))) + `(font-lock-comment-delimiter-face ((,class :inherit font-lock-comment-face))) + `(font-lock-comment-face ((,class :inherit unspecified :foreground ,fg-alt))) + `(font-lock-constant-face ((,class :foreground unspecified))) + `(font-lock-doc-face ((,class :inherit modus-themes-slant :foreground ,fg-docstring))) + `(font-lock-function-name-face ((,class :foreground unspecified))) + `(font-lock-keyword-face ((,class :inherit modus-themes-bold :foreground unspecified))) + `(font-lock-negation-char-face ((,class :inherit modus-themes-bold :foreground unspecified))) + `(font-lock-preprocessor-face ((,class :foreground unspecified))) + `(font-lock-regexp-grouping-backslash ((,class :inherit bold :foreground ,fg-escape-char-backslash))) + `(font-lock-regexp-grouping-construct ((,class :inherit bold :foreground ,fg-escape-char-construct))) + `(font-lock-string-face ((,class :foreground ,blue-alt))) + `(font-lock-type-face ((,class :inherit modus-themes-bold :foreground unspecified))) + `(font-lock-variable-name-face ((,class :foreground unspecified))) + `(font-lock-warning-face ((,class :inherit modus-themes-bold :foreground ,red-nuanced-fg)))))) + +;; Same as above with `set-face-attribute' instead of `custom-set-faces' +(defun my-modus-themes-subtle-syntax () + (modus-themes-with-colors + (set-face-attribute 'font-lock-builtin-face nil :inherit 'modus-themes-bold :foreground 'unspecified) + (set-face-attribute 'font-lock-comment-delimiter-face nil :inherit 'font-lock-comment-face) + (set-face-attribute 'font-lock-comment-face nil :inherit 'unspecified :foreground fg-alt) + (set-face-attribute 'font-lock-constant-face nil :foreground 'unspecified) + (set-face-attribute 'font-lock-doc-face nil :inherit 'modus-themes-slant :foreground fg-docstring) + (set-face-attribute 'font-lock-function-name-face nil :foreground 'unspecified) + (set-face-attribute 'font-lock-keyword-face nil :inherit 'modus-themes-bold :foreground 'unspecified) + (set-face-attribute 'font-lock-negation-char-face nil :inherit 'modus-themes-bold :foreground 'unspecified) + (set-face-attribute 'font-lock-preprocessor-face nil :foreground 'unspecified) + (set-face-attribute 'font-lock-regexp-grouping-backslash nil :inherit 'bold :foreground fg-escape-char-backslash) + (set-face-attribute 'font-lock-regexp-grouping-construct nil :inherit 'bold :foreground fg-escape-char-construct) + (set-face-attribute 'font-lock-string-face nil :foreground blue-alt) + (set-face-attribute 'font-lock-type-face nil :inherit 'modus-themes-bold :foreground 'unspecified) + (set-face-attribute 'font-lock-variable-name-face nil :foreground 'unspecified) + (set-face-attribute 'font-lock-warning-face nil :inherit 'modus-themes-bold :foreground red-nuanced-fg))) +#+end_src + +** Custom hl-todo colors +:PROPERTIES: +:CUSTOM_ID: h:2ef83a21-2f0a-441e-9634-473feb940743 +:END: + +The =hl-todo= package provides the user option ~hl-todo-keyword-faces~: +it specifies a pair of keyword and corresponding color value. The Modus +themes configure that option in the interest of legibility. While this +works for our purposes, users may still prefer to apply their custom +values, in which case the following approach is necessary: + +#+begin_src emacs-lisp +(defun my-modus-themes-hl-todo-faces () + (setq hl-todo-keyword-faces '(("TODO" . "#ff0000") + ("HACK" . "#ffff00") + ("XXX" . "#00ffff") + ("NOTE" . "#ff00ff")))) + +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-hl-todo-faces) +#+end_src + +Or include a ~let~ form, if needed: + +#+begin_src emacs-lisp +(defun my-modus-themes-hl-todo-faces () + (let ((red "#ff0000") + (blue "#0000ff")) + (setq hl-todo-keyword-faces `(("TODO" . ,blue) + ("HACK" . ,red) + ("XXX" . ,red) + ("NOTE" . ,blue))))) + +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-hl-todo-faces) +#+end_src + +Normally, we do not touch user options, though this is an exception: +otherwise the defaults are not always legible. + +** Add support for solaire-mode +:PROPERTIES: +:CUSTOM_ID: h:439c9e46-52e2-46be-b1dc-85841dd99671 +:END: + +The =solaire-mode= package dims the background of what it considers +ancillary "UI" buffers, such as the minibuffer and Dired buffers. The +Modus themes used to support Solaire on the premise that the user was +(i) opting in to it, (ii) understood why certain buffers were more gray, +and (iii) knew what other adjustments had to be made to prevent broken +visuals (e.g. the default style of the ~modus-themes-completions~ uses a +subtle gray background for the selection, which with Solaire becomes +practically invisible). + +However, the assumption that users opt in to this feature does not +always hold true. There are cases where it is enabled by defaultsuch as +in the popular Doom Emacs configuration. Thus, the unsuspecting user +who loads ~modus-operandi~ or ~modus-vivendi~ without the requisite +customizations is getting a sub-par experience; an experience that we +did not intend and cannot genuinely fix. + +Because the Modus themes are meant to work everywhere, we cannot make an +exception for Doom Emacs and/or Solaire users. Furthermore, we shall +not introduce hacks, such as by adding a check in all relevant faces to +be adjusted based on Solaire or whatever other package. Hacks of this +sort are unsustainable and penalize the entire userbase. Besides, the +themes are built into Emacs and we must keep their standard high. + +The fundamental constraint with Solaire is that Emacs does not have a +real distinction between "content" and "UI" buffers. For themes to work +with Solaire, they need to be designed around that package. Such is an +arrangement that compromises on our accessibility standards and/or +hinders our efforts to provide the best possible experience while using +the Modus themes. + +As such, =solaire-mode= is not---and will not be---supported by the +Modus themes (or any other of my themes, for that matter). Users who +want it must style the faces manually. Below is some sample code, based +on what we cover at length elsewhere in this manual: + +[[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]. + +[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]. + +#+begin_src emacs-lisp +(defun my-modus-themes-custom-faces () + (modus-themes-with-colors + (custom-set-faces + `(solaire-default-face ((,class :inherit default :background ,bg-alt :foreground ,fg-dim))) + `(solaire-line-number-face ((,class :inherit solaire-default-face :foreground ,fg-unfocused))) + `(solaire-hl-line-face ((,class :background ,bg-active))) + `(solaire-org-hide-face ((,class :background ,bg-alt :foreground ,bg-alt)))))) + +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) +#+end_src + +As always, re-load the theme for changes to take effect. + * Face coverage :properties: :custom_id: h:a9c8f29d-7f72-4b54-b74b-ddefe15d6a19 @@ -2969,14 +4491,14 @@ affected face groups. The items with an appended asterisk =*= tend to have lots of extensions, so the "full support" may not be 100% true… + ace-window -+ ag + alert + all-the-icons ++ all-the-icons-dired ++ all-the-icons-ibuffer + annotate + ansi-color + anzu + apropos -+ apt-sources-list + artbollocks-mode + auctex and TeX + auto-dim-other-buffers @@ -2989,14 +4511,15 @@ have lots of extensions, so the "full support" may not be 100% true… + boon + bookmark + breakpoint (provided by the built-in {{{file(gdb-mi.el)}}} library) -+ buffer-expose + calendar and diary + calfw -+ centaur-tabs ++ calibredb + cfrs + change-log and log-view (such as ~vc-print-log~, ~vc-print-root-log~) ++ chart + cider + circe ++ citar + color-rg + column-enforce-mode + company-mode* @@ -3005,22 +4528,21 @@ have lots of extensions, so the "full support" may not be 100% true… + completions + consult + corfu ++ corfu-quick + counsel* + counsel-css -+ counsel-org-capture-string + cov + cperl-mode + css-mode + csv-mode + ctrlf -+ cursor-flash + custom (what you get with {{{kbd(M-x customize)}}}) + dap-mode -+ dashboard (emacs-dashboard) + deadgrep + debbugs -+ define-word + deft ++ denote ++ devdocs + dictionary + diff-hl + diff-mode @@ -3032,17 +4554,14 @@ have lots of extensions, so the "full support" may not be 100% true… + dired-git-info + dired-narrow + dired-subtree -+ diredc + diredfl + diredp (dired+) -+ disk-usage + display-fill-column-indicator-mode + doom-modeline -+ dynamic-ruler + easy-jekyll -+ easy-kill + ebdb + ediff ++ ein (Emacs IPython Notebook) + eglot + el-search + eldoc-box @@ -3050,6 +4569,7 @@ have lots of extensions, so the "full support" may not be 100% true… + elfeed-score + elpher + embark ++ ement + emms + enh-ruby-mode (enhanced-ruby-mode) + epa @@ -3076,10 +4596,8 @@ have lots of extensions, so the "full support" may not be 100% true… + flycheck-posframe + flymake + flyspell -+ flyspell-correct + flx + freeze-it -+ frog-menu + focus + fold-this + font-lock (generic syntax highlighting) @@ -3088,10 +4606,8 @@ have lots of extensions, so the "full support" may not be 100% true… + geiser + git-commit + git-gutter (and variants) -+ git-lens + git-rebase + git-timemachine -+ git-walktree + gnus + gotest + golden-ratio-scroll-screen @@ -3100,35 +4616,30 @@ have lots of extensions, so the "full support" may not be 100% true… + helm-switch-shell + helm-xref + helpful -+ highlight-blocks -+ highlight-defined -+ highlight-escape-sequences (~hes-mode~) + highlight-indentation + highlight-numbers + highlight-parentheses ([[#h:24bab397-dcb2-421d-aa6e-ec5bd622b913][Note on highlight-parentheses.el]]) -+ highlight-symbol -+ highlight-tail + highlight-thing + hl-defined + hl-fill-column + hl-line-mode + hl-todo + hydra -+ hyperlist + ibuffer + icomplete + icomplete-vertical + ido-mode + iedit + iflipb ++ image-dired + imenu-list + indium + info ++ info+ (info-plus) + info-colors + interaction-log + ioccur + isearch, occur, etc. -+ isl (isearch-light) + ivy* + ivy-posframe + jira (org-jira) @@ -3139,6 +4650,7 @@ have lots of extensions, so the "full support" may not be 100% true… + kaocha-runner + keycast + ledger-mode ++ leerzeichen + line numbers (~display-line-numbers-mode~ and global variant) + lsp-mode + lsp-ui @@ -3152,7 +4664,7 @@ have lots of extensions, so the "full support" may not be 100% true… + markup-faces (~adoc-mode~) + mentor + messages -+ minibuffer-line ++ mini-modeline + minimap + mmm-mode + mode-line @@ -3160,14 +4672,12 @@ have lots of extensions, so the "full support" may not be 100% true… + moody + mpdel + mu4e -+ mu4e-conversation + multiple-cursors ++ nano-modeline + neotree -+ no-emoji + notmuch + num3-mode + nxml-mode -+ objed + orderless + org* + org-journal @@ -3178,23 +4688,18 @@ have lots of extensions, so the "full support" may not be 100% true… + org-superstar + org-table-sticky-header + org-tree-slide -+ org-treescope + origami + outline-mode + outline-minor-faces + package (what you get with {{{kbd(M-x list-packages)}}}) + page-break-lines + pandoc-mode -+ paradox + paren-face -+ parrot + pass + pdf-tools + persp-mode + perspective + phi-grep -+ phi-search -+ pkgbuild-mode + pomidor + popup + powerline @@ -3203,10 +4708,10 @@ have lots of extensions, so the "full support" may not be 100% true… + proced + prodigy + pulse ++ pyim + quick-peek + racket-mode + rainbow-blocks -+ rainbow-identifiers + rainbow-delimiters + rcirc + recursion-indicator @@ -3215,7 +4720,6 @@ have lots of extensions, so the "full support" may not be 100% true… + ripgrep + rmail + ruler-mode -+ sallet + selectrum + selectrum-prescient + semantic @@ -3227,19 +4731,17 @@ have lots of extensions, so the "full support" may not be 100% true… + side-notes + sieve-mode + skewer-mode ++ slime (slbd) ++ sly + smart-mode-line + smartparens + smerge -+ solaire + spaceline + speedbar -+ spell-fu -+ spray + stripes + suggest + switch-window + swiper -+ swoop + sx + symbol-overlay + syslog-mode @@ -3251,23 +4753,24 @@ have lots of extensions, so the "full support" may not be 100% true… + telephone-line + terraform-mode + term ++ textsec + tomatinho + transient (pop-up windows such as Magit's) + trashed ++ tree-sitter + treemacs + tty-menu + tuareg + typescript + undo-tree + vc (vc-dir.el, vc-hooks.el) -+ vc-annotate (the output of {{{kbd(C-x v g)}}}) -+ vdiff + vertico ++ vertico-quick + vimish-fold + visible-mark + visual-regexp -+ volatile-highlights + vterm ++ vundo + wcheck-mode + web-mode + wgrep @@ -3298,23 +4801,45 @@ These do not require any extra styles because they are configured to inherit from some basic faces or their dependencies which are directly supported by the themes. ++ ag ++ apt-sources-list ++ buffer-expose + bufler + counsel-notmuch ++ counsel-org-capture-string ++ dashboard (emacs-dashboard) ++ define-word ++ disk-usage ++ dtache ++ dynamic-ruler ++ easy-kill + edit-indirect ++ egerrit ++ elfeed-summary + evil-owl ++ flyspell-correct + fortran-mode ++ git-walktree + goggles ++ highlight-defined ++ highlight-escape-sequences (~hes-mode~) + i3wm-config-mode ++ minibuffer-line ++ no-emoji ++ org-remark ++ parrot + perl-mode + php-mode + rjsx-mode + side-hustle ++ spell-fu + swift-mode + tab-bar-echo-area + tide ++ undo-hl ++ vdiff + vertico-indexed + vertico-mouse -+ vertico-quick * Notes on individual packages :properties: @@ -3324,40 +4849,6 @@ supported by the themes. This section covers information that may be of interest to users of individual packages. -** Note on avy hints -:properties: -:custom_id: h:2fdce705-6de7-44e6-ab7f-18f59af99e01 -:end: - -Hints can appear everywhere, in wildly varying contexts, hence, their -appearance, by necessity, is a compromise. However, there are various -options for making them stand out. First is dimming the surroundings: - -#+begin_src emacs-lisp -(setq avy-background t) -#+end_src - -Dimming works well when you find it difficult to spot hints, any hint. -Second is limiting the number of faces used by hints: - -#+begin_src emacs-lisp -(setq avy-lead-faces - '(avy-lead-face - avy-lead-face-1 - avy-lead-face-1 - avy-lead-face-1 - avy-lead-face-1)) -#+end_src - -Limiting the number of faces works well with longer hints when you find -it difficult to identify individual hints, especially with hints -touching each other. The first character of the hint will have an -intense color, the remaining ones the same neutral color. - -Third is preferring commands that produce fewer candidates. Fewer hints -is less noise: ~avy-goto-char-timer~ is an excellent alternative to -~avy-goto-char~. - ** Note on calendar.el weekday and weekend colors :properties: :custom_id: h:b2db46fb-32f4-44fd-8e11-d2b261cf51ae @@ -3387,6 +4878,76 @@ weekends uniformly. For changes to take effect, the Calendar buffer needs to be generated anew. +** Note on git-gutter in Doom Emacs +:PROPERTIES: +:CUSTOM_ID: h:a195e37c-e58c-4148-b254-8ba1ed8a731a +:END: + +The =git-gutter= and =git-gutter-fr= packages default to drawing bitmaps +for the indicators they display (e.g. bitmap of a plus sign for added +lines). In Doom Emacs, these bitmaps are replaced with contiguous lines +which may look nicer, but require a change to the foreground of the +relevant faces to yield the desired color combinations. + +Since this is Doom-specific, we urge users to apply changes in their +local setup. Below is some sample code, based on what we cover at +length elsewhere in this manual: + +[[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]. + +[[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]. + +#+begin_src emacs-lisp +(defun my-modus-themes-custom-faces () + (modus-themes-with-colors + (custom-set-faces + ;; Replace green with blue if you use `modus-themes-deuteranopia'. + `(git-gutter-fr:added ((,class :foreground ,green-fringe-bg))) + `(git-gutter-fr:deleted ((,class :foreground ,red-fringe-bg))) + `(git-gutter-fr:modified ((,class :foreground ,yellow-fringe-bg)))))) + +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-custom-faces) +#+end_src + +As always, re-load the theme for changes to take effect. + +If the above does not work, try this instead: + +#+begin_src emacs-lisp +(after! modus-themes + (modus-themes-with-colors + (custom-set-faces + ;; Replace green with blue if you use `modus-themes-deuteranopia'. + `(git-gutter-fr:added ((,class :foreground ,green-fringe-bg))) + `(git-gutter-fr:deleted ((,class :foreground ,red-fringe-bg))) + `(git-gutter-fr:modified ((,class :foreground ,yellow-fringe-bg)))))) +#+end_src + +Replace ~green-fringe-bg~ with ~blue-fringe-bg~ if you want to optimize +for red-green color deficiency. + +[[#h:3ed03a48-20d8-4ce7-b214-0eb7e4c79abe][Option for red-green color deficiency or deuteranopia]]. + +** Note on php-mode multiline comments +:PROPERTIES: +:CUSTOM_ID: h:d0a3157b-9c04-46e8-8742-5fb2a7ae8798 +:END: + +Depending on your build of Emacs and/or the environment it runs in, +multiline comments in PHP with the =php-mode= package use the +~font-lock-doc-face~ instead of ~font-lock-comment-face~. + +This seems to make all comments use the appropriate face: + +#+begin_src emacs-lisp +(defun my-multine-comments () + (setq-local c-doc-face-name 'font-lock-comment-face)) + +(add-hook 'php-mode-hook #'my-multine-comments) +#+end_src + +As always, re-load the theme for changes to take effect. + ** Note on underlines in compilation buffers :properties: :custom_id: h:420f5a33-c7a9-4112-9b04-eaf2cbad96bd @@ -3396,14 +4957,15 @@ Various buffers that produce compilation results or run tests on code apply an underline to the file names they reference or to relevant messages. Users may consider this unnecessary or excessive. -To outright disable the effect, use this: +To outright disable the effect, use this (buffers need to be generated +anew): #+begin_src emacs-lisp (setq compilation-message-face nil) #+end_src If some element of differentiation is still desired, a good option is to -render the affected text using the ~italic~ face: +render the affected text with the ~italic~ face: #+begin_src emacs-lisp (setq compilation-message-face 'italic) @@ -3467,33 +5029,35 @@ package: it draws too much attention to unfocused windows. :custom_id: h:2a602816-bc1b-45bf-9675-4cbbd7bf6cab :end: -While designing the style for ~display-fill-column-indicator-mode~, we -stayed close to the mode's defaults: to apply a subtle foreground color -to the ~fill-column-indicator~ face, which blends well with the rest of -theme and is consistent with the role of that mode. This is to not -upset the expectations of users. - -Nevertheless, ~display-fill-column-indicator-mode~ has some known -limitations pertaining to its choice of using typographic characters to -draw its indicator. What should be a continuous vertical line might -appear as a series of dashes in certain contexts or under specific -conditions: a non-default value for ~line-spacing~, scaled and/or -variable-pitch headings have been observed to cause this effect. +The ~display-fill-column-indicator-mode~ uses a typographic character to +draw its line. This has the downside of creating a dashed line. The +dashes are further apart depending on how tall the font's glyph height +is and what integer the ~line-spacing~ is set to. -Given that we cannot control such factors, it may be better for affected -users to deviate from the default style of the ~fill-column-indicator~ -face. Instead of setting a foreground color, one could use a background -and have the foreground be indistinguishable from it. For example: +At the theme level we eliminate this effect by making the character one +pixel tall: the line is contiguous. Users who prefer the dashed line +are advised to change the ~fill-column-indicator~ face, as explained +elsewhere in this document. For example: #+begin_src emacs-lisp (modus-themes-with-colors (custom-set-faces - `(fill-column-indicator ((,class :background ,bg-inactive - :foreground ,bg-inactive))))) + `(fill-column-indicator ((,class :foreground ,bg-active))))) #+end_src [[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]. +To make the line thicker, set the height to be equal to the base font +size instead of the one pixel we use. This is done by specifying a rate +instead of an absolute number, as in =:height 1.0= versus =:height 1=. +For example: + +#+begin_src emacs-lisp +(modus-themes-with-colors + (custom-set-faces + `(fill-column-indicator ((,class :height 1.0 :background ,bg-inactive :foreground ,bg-inactive))))) +#+end_src + ** Note on highlight-parentheses.el :PROPERTIES: :CUSTOM_ID: h:24bab397-dcb2-421d-aa6e-ec5bd622b913 @@ -3623,6 +5187,8 @@ implementation: (add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-highlight-parentheses) #+end_src +As always, re-load the theme for changes to take effect. + ** Note on mmm-mode.el background colors :properties: :custom_id: h:99cf0d6c-e478-4e26-9932-3bf3427d13f6 @@ -3684,7 +5250,7 @@ implements an alternative to the typical coloration of code. Instead of highlighting the syntactic constructs, it applies color to different levels of depth in the code structure. -As {{{file(prism.el)}}} offers a broad range of customisations, we cannot +As {{{file(prism.el)}}} offers a broad range of customizations, we cannot style it directly at the theme level: that would run contrary to the spirit of the package. Instead, we may offer preset color schemes. Those should offer a starting point for users to adapt to their needs. @@ -3775,11 +5341,11 @@ examples with the 4, 8, 16 colors): :custom_id: h:4da1d515-3e05-47ef-9e45-8251fc7e986a :end: -The ~god-mode~ library does not provide faces that could be configured -by the Modus themes. Users who would like to get some visual feedback -on the status of {{{kbd(M-x god-mode)}}} are instead encouraged by upstream -to set up their own configurations, such as by changing the ~mode-line~ -face ([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]). This is an adaptation of the approach +The ~god-mode~ library does not provide faces that could be configured by +the Modus themes. Users who would like to get some visual feedback on +the status of {{{kbd(M-x god-mode)}}} are instead encouraged by upstream to +set up their own configurations, such as by changing the ~mode-line~ face +([[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization]]). This is an adaptation of the approach followed in the upstream README: #+begin_src emacs-lisp @@ -3872,22 +5438,68 @@ Emacs' HTML rendering library ({{{file(shr.el)}}}) may need explicit configuration to respect the theme's colors instead of whatever specifications the webpage provides. -Consult {{{kbd(C-h v shr-use-colors)}}}. +Consult the doc string of ~shr-use-colors~. -** Note on EWW and Elfeed fonts +** Note on SHR fonts :properties: :custom_id: h:e6c5451f-6763-4be7-8fdb-b4706a422a4c :end: +#+cindex: Fonts in EWW, Elfeed, Ement, and SHR -EWW and Elfeed rely on the Simple HTML Renderer to display their -content. The {{{file(shr.el)}}} library contains the variable ~shr-use-fonts~ -that controls whether the text in the buffer is set to a ~variable-pitch~ -typeface (proportionately spaced) or if just retains whatever the -default font family is. Its default value is non-nil, which means that -~variable-pitch~ is applied. +By default, packages that build on top of the Simple HTML Remember (=shr=) +use proportionately spaced fonts. This is controlled by the user option +~shr-use-fonts~, which is set to non-nil by default. To use the standard +font instead, set that variable to nil. [[#h:defcf4fc-8fa8-4c29-b12e-7119582cc929][Font configurations for Org and others]]. +Packages affected by this are: + ++ elfeed ++ ement ++ eww + +This is a non-exhaustive list. + +** Note on Ement colors and fonts +:properties: +:custom_id: h:8e636056-356c-4ca7-bc78-ebe61031f585 +:end: + +The =ement.el= library by Adam Porter (also known as "alphapapa") defaults +to a method of colorizing usernames in a rainbow style. This is +controlled by the user option ~ement-room-prism~ and can be disabled with: + +#+begin_src emacs-lisp +(setq ement-room-prism nil) +#+end_src + +The contrast ratio of these colors is governed by another user option: +~ement-room-prism-minimum-contrast~. By default, it is set to 6 which is +slightly below our nominal target. Try this instead: + +#+begin_src emacs-lisp +(setq ement-room-prism-minimum-contrast 7) +#+end_src + +With regard to fonts, Ement depends on =shr= ([[#h:e6c5451f-6763-4be7-8fdb-b4706a422a4c][Note on SHR fonts]]). + +Since we are here, here is an excerpt from Ement's source code: + +#+begin_src emacs-lisp +(defcustom ement-room-prism-minimum-contrast 6 + "Attempt to enforce this minimum contrast ratio for user faces. +This should be a reasonable number from, e.g. 0-7 or so." + ;; Prot would almost approve of this default. :) I would go all the way + ;; to 7, but 6 already significantly dilutes the colors in some cases. + :type 'number) +#+end_src + +Yes, I do approve of that default. Even a 4.5 (the WCAG AA rating) +would be a good baseline for many themes and/or user configurations. +Our target is the highest of the sort, though we do not demand that +everyone conforms with it. + ** Note on Helm grep :properties: :custom_id: h:d28879a2-8e4b-4525-986e-14c0f873d229 @@ -3920,24 +5532,6 @@ candidates. That style still meets the contrast ratio target of >= 7:1 ANSI color number 1 (red) from the already-supported array of ~ansi-color-names-vector~. -** Note on vc-annotate-background-mode -:properties: -:custom_id: h:5095cbd1-e17a-419c-93e8-951c186362a3 -:end: - -Due to the unique way ~vc-annotate~ ({{{kbd(C-x v g)}}}) applies colors, support -for its background mode (~vc-annotate-background-mode~) is disabled at the -theme level. - -Normally, such a drastic measure should not belong in a theme: assuming -the user's preferences is bad practice. However, it has been deemed -necessary in the interest of preserving color contrast accessibility -while still supporting a useful built-in tool. - -If there actually is a way to avoid such a course of action, without -prejudice to the accessibility standard of this project, then please -report as much or send patches ([[#h:9c3cd842-14b7-44d7-84b2-a5c8bc3fc3b1][Contributing]]). - ** Note on pdf-tools link hints :properties: :custom_id: h:2659d13e-b1a5-416c-9a89-7c3ce3a76574 @@ -3988,11 +5582,25 @@ you've customized any faces. "-draw" "text %X,%Y '%c'")))) #+end_src +** Note on the Notmuch logo +:properties: +:custom_id: h:636af312-54a5-4918-84a6-0698e85a3c6d +:end: + +By default, the "hello" buffer of Notmuch includes a header with the +programs' logo and a couple of buttons. The logo has the effect of +enlarging the height of the line, which negatively impacts the shape of +those buttons. Disabling the logo fixes the problem: + +#+begin_src emacs-lisp +(setq notmuch-show-logo nil) +#+end_src + * Frequently Asked Questions :properties: :custom_id: h:b3384767-30d3-4484-ba7f-081729f03a47 :end: -#+cindex: Frequently Asked Questions (FAQ) +#+cindex: Frequently Asked Questions In this section we provide answers related to some aspects of the Modus themes' design and application. @@ -4111,8 +5719,8 @@ and hints of green give us suitable shades of purple. Due to the need of maintaining some difference in hueness between adjacent colors, it is not possible to make red, green, and yellow the -primary colors, because blue could not be used to control their -luminance and, thus the relevant space would shrink considerably. +main colors, because blue cannot be used to control their luminance and, +thus the relevant space will shrink considerably. [[#h:5ce7ae2e-9348-4e55-b4cf-9302345b1826][Is the contrast ratio about adjacent colors?]] @@ -4199,6 +5807,139 @@ The color combinations may have been optimized for accessibility, though the remaining contributing factors in each case need to be considered in full. +** Are these color schemes? +:properties: +:custom_id: h:a956dbd3-8fd2-4f5d-8b01-5f881268cf2b +:end: +#+cindex: Themes, not color schemes + +No, the Modus themes are not color schemes. + +A color scheme is a collection of colors. A good color scheme is a +combination of colors with an inner logic or abstract structure. + +A theme is a set of patterns that are applied across different contexts. +A good theme is one that does so with consistency, though not +uniformity. + +In practical terms, a color scheme is what one uses when, for example, +they edit the first sixteen escape sequences of a terminal emulator to +the hues of their preference. The terminal offers the option to choose, +say, the exact value of what counts as "red", but does not provide the +means to control where that is mapped to and whether it should also have +other qualities such as a bold weight for the underlying text or an +added background color. In contradistinction, Emacs uses constructs +known as "faces" which allow the user/developer to specify where a given +color will be used and whether it should be accompanied by other +typographic or stylistic attributes. + +By configuring the multitude of faces on offer we thus control both +which colors are applied and how they appear in their context. When a +package wants to render each instance of "foo" with the "bar" face, it +is not requesting a specific color, which makes things considerably more +flexible as we can treat "bar" in its own right without necessarily +having to use some color value that we hardcoded somewhere. + +Which brings us to the distinction between consistency and uniformity +where our goal is always the former: we want things to look similar +across all interfaces, but we must never force a visual identity where +that runs contrary to the functionality of the given interface. For +instance, all links are underlined by default yet there are cases such +as when viewing listings of emails in Gnus (and Mu4e, Notmuch) where (i) +it is already understood that one must follow the indicator or headline +to view its contents and (ii) underlining everything would make the +interface virtually unusable. + +[[#h:5808be52-361a-4d18-88fd-90129d206f9b][Option for links]]. + +Again, one must exercise judgement in order to avoid discrimination, +where "discrimination" refers to: + ++ The treatment of substantially different magnitudes as if they were of + the same class. ++ Or the treatment of the same class of magnitudes as if they were of a + different class. + +(To treat similar things differently; to treat dissimilar things alike.) + +If, in other words, one was to enforce uniformity without accounting for +the particular requirements of each case---the contextual demands for +usability beyond matters of color---they would be making a +not-so-obvious error of treating different cases as if they were the +same. + +The Modus themes prioritise "thematic consistency" over abstract harmony +or regularity among their applicable colors. In concrete terms, we do +not claim that, say, our yellows are the best complements for our blues +because we generally avoid using complementary colors side-by-side, so +it is wrong to optimise for a decontextualised blue+yellow combination. +Not to imply that our colors do not work well together because they do, +just to clarify that consistency of context is what themes must strive +for, and that requires widening the scope of the design beyond the +particularities of a color scheme. + +Long story short: color schemes and themes have different requirements. +Please do not conflate the two. + +** Port the Modus themes to other platforms? +:properties: +:custom_id: h:7156b949-917d-488e-9a72-59f70d80729c +:end: +#+cindex: Porting the themes to other editors + +There is no plan to port the themes to other platforms or text editors. +I (Protesilaos) only use GNU Emacs and thus cannot maintain code that +targets software I am either not familiar with or am not using on a +daily basis. + +While it is possible to produce a simulacrum based on a given template, +doing so would run contrary to how this project is maintained where +details matter greatly. + +Each program has its own requirements so it won't always be +possible---or indeed desirable---to have 1:1 correspondence between what +applies to Emacs and what should be done elsewhere. No port should ever +strive to be a faithful copy of the Emacs implementation, as no other +program is an Emacs equivalent, but instead try to follow the spirit of +the design. For example, some of the customization options accept a +list as their value, or an alist, which may not be possible to reproduce +on other platforms. + +[[#h:bf1c82f2-46c7-4eb2-ad00-dd11fdd8b53f][Customization options]]. + +In other words, if something must be done differently on a certain +editor then that is acceptable so long as (i) the accessibility +standards are not compromised and (ii) the overall character of the +themes remains consistent. + +The former criterion should be crystal clear as it pertains to the +scientific foundations of the themes: high legibility and taking care of +the needs of users with red-green color deficiency (deuteranopia) by +avoiding red+green color coding paradigms and/or by providing red+blue +variants. + +The latter criterion is the "je ne sais quoi" of the artistic aspect of +the themes, which is partially fleshed out in this manual. + +[[#h:b3384767-30d3-4484-ba7f-081729f03a47][Frequently Asked Questions]]. + +With regard to the artistic aspect (where "art" qua skill may amount to +an imprecise science), there is no hard-and-fast rule in effect as it +requires one to exercise discretion and make decisions based on +context-dependent information or constraints. As is true with most +things in life, when in doubt, do not cling on to the letter of the law +but try to understand its spirit. + +For a trivial example: the curly underline that Emacs draws for spelling +errors is thinner than, e.g., what a graphical web browser has, so if I +was to design for an editor than has a thicker curly underline I would +make the applicable colors less intense to counterbalance the +typographic intensity of the added thickness. + +With those granted, if anyone is willing to develop a port of the +themes, they are welcome to contact me and I will do my best to help +them in their efforts. + * Contributing :properties: :custom_id: h:9c3cd842-14b7-44d7-84b2-a5c8bc3fc3b1 @@ -4215,11 +5956,11 @@ in which you can contribute to their ongoing development. The ~modus-operandi~ and ~modus-vivendi~ themes are built into Emacs 28. -The source code of the themes is [[https://gitlab.com/protesilaos/modus-themes/][available on Gitlab]], for the time -being. A [[https://github.com/protesilaos/modus-themes/][mirror on Github]] is also on offer. +The source code of the themes is [[https://git.sr.ht/~protesilaos/modus-themes][available on SourceHut]]. Or check the +[[https://gitlab.com/protesilaos/modus-themes/][GitLab mirror (former main source)]] and the [[https://github.com/protesilaos/modus-themes/][GitHub mirror]]. An HTML version of this manual is provided as an extension of the -[[https://protesilaos.com/modus-themes/][author's personal website]] (does not rely on any non-free code). +[[https://protesilaos.com/emacs/modus-themes/][author's personal website]] (does not rely on any non-free code). ** Issues you can help with :properties: @@ -4227,7 +5968,10 @@ An HTML version of this manual is provided as an extension of the :end: #+cindex: Contributing -A few tasks you can help with: +#+findex: modus-themes-report-bug +A few tasks you can help with by sending an email to the general +[[https://lists.sr.ht/~protesilaos/modus-themes][modus-themes public mailing list]] (or use the command +~modus-themes-report-bug~). + Suggest refinements to packages that are covered. + Report packages not covered thus far. @@ -4235,7 +5979,8 @@ A few tasks you can help with: + Help expand the documentation of covered-but-not-styled packages. + Suggest refinements to the color palette. + Help expand this document or any other piece of documentation. -+ Merge requests for code refinements. ++ Send patches for code refinements (if you need, ask me for help with + Git---we all start out as beginners). [[#h:111773e2-f26f-4b68-8c4f-9794ca6b9633][Patches require copyright assignment to the FSF]]. @@ -4243,6 +5988,10 @@ It is preferable that your feedback includes some screenshots, GIFs, or short videos, as well as further instructions to reproduce a given setup. Though this is not a requirement. +#+findex: modus-themes-version +Also consider mentioning the version of the themes you are using, such +as by invoking the command ~modus-themes-version~. + Whatever you do, bear in mind the overarching objective of the Modus themes: to keep a contrast ratio that is greater or equal to 7:1 between background and foreground colors. If a compromise is ever necessary @@ -4274,7 +6023,7 @@ will send you the assignment form for your past and future changes. Please use your full legal name (in ASCII characters) as the subject line of the message. ----------------------------------------------------------------------- + REQUEST: SEND FORM FOR PAST AND FUTURE CHANGES [What is the name of the program or package you're contributing to?] @@ -4322,47 +6071,61 @@ The Modus themes are a collective effort. Every bit of work matters. + Author/maintainer :: Protesilaos Stavrou. -+ Contributions to code or documentation :: Anders Johansson, Basil - L.{{{space()}}} Contovounesios, Carlo Zancanaro, Eli Zaretskii, Fritz Grabo, - Kévin Le Gouguec, Kostadin Ninev, Madhavan Krishnan, Markus Beppler, - Matthew Stevenson, Mauro Aranda, Nicolas De Jaeghere, Philip - Kaludercic, Rudolf Adamkovič, Stephen Gildea, Shreyas Ragavan, Stefan - Kangas, Vincent Murphy, Xinglu Chen. ++ Contributions to code or documentation :: Alex Griffin, Anders + Johansson, Basil L.{{{space()}}} Contovounesios, Björn Lindström, + Carlo Zancanaro, Christian Tietze, Daniel Mendler, Eli Zaretskii, + Fritz Grabo, Illia Ostapyshyn, Kévin Le Gouguec, Kostadin Ninev, + Madhavan Krishnan, Manuel Giraud, Markus Beppler, Matthew Stevenson, + Mauro Aranda, Nicolas De Jaeghere, Paul David, Philip Kaludercic, + Pierre Téchoueyres, Rudolf Adamkovič, Stephen Gildea, Shreyas Ragavan, + Stefan Kangas, Utkarsh Singh, Vincent Murphy, Xinglu Chen, Yuanchen + Xie. + Ideas and user feedback :: Aaron Jensen, Adam Porter, Adam Spiers, - Adrian Manea, Alex Griffin, Alex Peitsinis, Alexey Shmalko, Alok - Singh, Anders Johansson, André Alexandre Gomes, Arif Rezai, Basil - L.{{{space()}}} Contovounesios, Burgess Chang, Christian Tietze, Christopher - Dimech, Damien Cassou, Daniel Mendler, Dario Gjorgjevski, David - Edmondson, Davor Rotim, Divan Santana, Eliraz Kedmi, Emanuele Michele - Alberto Monterosso, Farasha Euker, Feng Shu, Gautier Ponsinet, Gerry - Agbobada, Gianluca Recchia, Gustavo Barros, Hörmetjan Yiltiz, Ilja - Kocken, Iris Garcia, Jeremy Friesen, Jerry Zhang, John Haman, Joshua - O'Connor, Kevin Fleming, Kévin Le Gouguec, Kostadin Ninev, Len Trigg, - Manuel Uberti, Mark Burton, Markus Beppler, Mauro Aranda, Michael - Goldenberg, Morgan Smith, Murilo Pereira, Nicky van Foreest, Nicolas - De Jaeghere, Paul Poloskov, Pengji Zhang, Pete Kazmier, Peter Wu, - Philip Kaludercic, Pierre Téchoueyres, Roman Rudakov, Ryan Phillips, - Rudolf Adamkovič, Sam Kleinman, Shreyas Ragavan, Simon Pugnet, Tassilo - Horn, Thibaut Verron, Thomas Heartman, Trey Merkley, Togan Muftuoglu, - Toon Claes, Uri Sharf, Utkarsh Singh, Vincent Foley. As well as - users: Ben, CsBigDataHub1, Emacs Contrib, Eugene, Fourchaux, Fredrik, - Moesasji, Nick, TheBlob42, Trey, bepolymathe, doolio, fleimgruber, - iSeeU, jixiuf, okamsn, pRot0ta1p. - -+ Packaging :: Basil L.{{{space()}}} Contovounesios, Eli Zaretskii, Glenn - Morris, Mauro Aranda, Richard Stallman, Stefan Kangas (core Emacs), - Stefan Monnier (GNU Elpa), André Alexandre Gomes, Dimakakos Dimos, - Morgan Smith, Nicolas Goaziou (Guix), Dhavan Vaidya (Debian). + Adrian Manea, Alex Griffin, Alex Koen, Alex Peitsinis, Alexey Shmalko, + Alok Singh, Anders Johansson, André Alexandre Gomes, Andrew Tropin, + Antonio Hernández Blas, Arif Rezai, Augusto Stoffel, Basil + L.{{{space()}}} Contovounesios, Burgess Chang, Christian Tietze, + Christopher Dimech, Christopher League, Damien Cassou, Daniel Mendler, + Dario Gjorgjevski, David Edmondson, Davor Rotim, Divan Santana, Eliraz + Kedmi, Emanuele Michele Alberto Monterosso, Farasha Euker, Feng Shu, + Gautier Ponsinet, Gerry Agbobada, Gianluca Recchia, Gonçalo Marrafa, + Guilherme Semente, Gustavo Barros, Hörmetjan Yiltiz, Ilja Kocken, Iris + Garcia, Ivan Popovych, Jeremy Friesen, Jerry Zhang, Johannes Grødem, + John Haman, Jonas Collberg, Jorge Morais, Joshua O'Connor, Julio + C. Villasante, Kenta Usami, Kevin Fleming, Kévin Le Gouguec, Kostadin + Ninev, Len Trigg, Lennart C. Karssen, Magne Hov, Manuel Uberti, Mark + Bestley, Mark Burton, Markus Beppler, Matt Armstrong, Mauro Aranda, + Maxime Tréca, Michael Goldenberg, Morgan Smith, Morgan Willcock, + Murilo Pereira, Nicky van Foreest, Nicolas De Jaeghere, Paul Poloskov, + Pengji Zhang, Pete Kazmier, Peter Wu, Philip Kaludercic, Pierre + Téchoueyres, Przemysław Kryger, Robert Hepple, Roman Rudakov, Ryan + Phillips, Rytis Paškauskas, Rudolf Adamkovič, Sam Kleinman, Samuel + Culpepper, Saša Janiška, Shreyas Ragavan, Simon Pugnet, Tassilo Horn, + Thibaut Verron, Thomas Heartman, Togan Muftuoglu, Tony Zorman, Trey + Merkley, Tomasz Hołubowicz, Toon Claes, Uri Sharf, Utkarsh Singh, + Vincent Foley. As well as users: Ben, CsBigDataHub1, Emacs Contrib, + Eugene, Fourchaux, Fredrik, Moesasji, Nick, Summer Emacs, TheBlob42, + Trey, bepolymathe, bit9tream, derek-upham, doolio, fleimgruber, + gitrj95, iSeeU, jixiuf, okamsn, pRot0ta1p. + ++ Packaging :: Basil L.{{{space()}}} Contovounesios, Eli Zaretskii, + Glenn Morris, Mauro Aranda, Richard Stallman, Stefan Kangas (core + Emacs), Stefan Monnier (GNU Elpa), André Alexandre Gomes, Andrew + Tropin, Dimakakos Dimos, Morgan Smith, Nicolas Goaziou (Guix), Dhavan + Vaidya (Debian). + Inspiration for certain features :: Bozhidar Batsov (zenburn-theme), Fabrice Niessen (leuven-theme). -Special thanks, in no particular order, to Manuel Uberti, Gustavo -Barros, and Omar Antolín Camarena for their long time contributions and -insightful commentary. +Special thanks (from A-Z) to Daniel Mendler, Gustavo Barros, Manuel +Uberti, Nicolas De Jaeghere, and Omar Antolín Camarena for their long +time contributions and insightful commentary on key aspects of the +themes' design and/or aspects of their functionality. + +All errors are my own. -* Meta +* Other notes about the project :properties: :custom_id: h:13752581-4378-478c-af17-165b6e76bc1b :end: @@ -4385,12 +6148,18 @@ of this sort): + [[https://protesilaos.com/codelog/2021-01-11-modus-themes-review-select-faint-colours/][Modus themes: review of select "faint" colours]] (2021-01-11) + [[https://protesilaos.com/codelog/2021-02-25-modus-themes-diffs-deuteranopia/][The Modus themes now cover deuteranopia in diffs]] (2021-02-25) + [[https://protesilaos.com/codelog/2021-06-02-modus-themes-org-agenda/][Introducing the variable modus-themes-org-agenda]] (2021-06-02) - -And here are the canonical sources of this project's documentation: - -+ Manual :: <https://protesilaos.com/modus-themes> -+ Change Log :: <https://protesilaos.com/modus-themes-changelog> -+ Screenshots :: <https://protesilaos.com/modus-themes-pictures> ++ [[https://protesilaos.com/codelog/2022-01-02-review-modus-themes-org-habit-colours/][Modus themes: review of the org-habit graph colours]] (2022-01-02) ++ [[https://protesilaos.com/codelog/2022-01-03-modus-themes-port-faq/][Re: VSCode or Vim ports of the Emacs modus-themes?]] (2022-01-03) ++ [[https://protesilaos.com/codelog/2022-04-20-modus-themes-case-study-avy/][Modus themes: case study on Avy faces and colour combinations]] (2022-04-20) ++ [[https://protesilaos.com/codelog/2022-04-21-modus-themes-colour-theory/][Emacs: colour theory and techniques used in the Modus themes]] (2022-04-21) + +And here are the canonical sources of this project: + ++ Manual :: <https://protesilaos.com/emacs/modus-themes> ++ Change Log :: <https://protesilaos.com/emacs/modus-themes-changelog> ++ Screenshots :: <https://protesilaos.com/emacs/modus-themes-pictures> ++ Git repository :: https://git.sr.ht/~protesilaos/modus-themes ++ Mailing list :: https://lists.sr.ht/~protesilaos/modus-themes * GNU Free Documentation License :properties: diff --git a/doc/misc/octave-mode.texi b/doc/misc/octave-mode.texi index 58fb8a49b68..31d64c3d840 100644 --- a/doc/misc/octave-mode.texi +++ b/doc/misc/octave-mode.texi @@ -240,7 +240,7 @@ entering Octave commands at the prompt. The buffer is in Inferior Octave mode, which is derived from the standard Comint mode, a major mode for interacting with an inferior interpreter. See the documentation for @code{comint-mode} for more details, and use -@kbd{C-h b} to find out about available special keybindings. +@kbd{C-h b} to find out about available special key bindings. You can also communicate with an inferior Octave process from within files with Octave code (i.e., buffers in Octave mode), using the diff --git a/doc/misc/org.org b/doc/misc/org.org index 9f69c684318..7971c417a52 100644 --- a/doc/misc/org.org +++ b/doc/misc/org.org @@ -3352,7 +3352,7 @@ current buffer: ~org-link-email-description-format~. By default, it refers to the addressee and the subject. -- /Web browsers: W3, W3M and EWW/ :: +- /Web browsers: W3M and EWW/ :: Here the link is the current URL, with the page title as the description. diff --git a/doc/misc/pcl-cvs.texi b/doc/misc/pcl-cvs.texi index 87807b5bdab..80c130fb8e9 100644 --- a/doc/misc/pcl-cvs.texi +++ b/doc/misc/pcl-cvs.texi @@ -524,8 +524,8 @@ you can use in PCL-CVS@. They are grouped together by type. Most commands in PCL-CVS require that you have a @file{*cvs*} buffer. The commands that you use to get one are listed below. For each, a @samp{cvs} process will be run, the output will be parsed by -PCL-CVS, and the result will be printed in the @file{*cvs*} buffer (see -@ref{Buffer contents}, for a description of the buffer's contents). +PCL-CVS, and the result will be printed in the @file{*cvs*} buffer +(@pxref{Buffer contents}, for a description of the buffer's contents). @table @kbd @item M-x cvs-update diff --git a/doc/misc/rcirc.texi b/doc/misc/rcirc.texi index da214958d5c..8c798d6c33b 100644 --- a/doc/misc/rcirc.texi +++ b/doc/misc/rcirc.texi @@ -154,8 +154,11 @@ deego: fsbot rules! @cindex nick completion @cindex completion of nicks +@vindex rcirc-cycle-completion-flag @kindex TAB Since this is so common, you can use @key{TAB} to do nick completion. +By default rcirc will use the default completion system, but you can +enable @code{rcirc-cycle-completion-flag} to cycle nicks in place. @node Getting started with rcirc @section Getting started with rcirc @@ -609,12 +612,6 @@ Use this symbol if you need to identify yourself in the Bitlbee channel as follows: @code{identify secret}. The necessary arguments are the nickname you want to use this for, and the password to use. -@item sasl -@cindex sasl authentication -Use this symbol if you want to use @acronym{SASL} authentication. The -necessary arguments are the nickname you want to use this for, and the -password to use. - @cindex gateway to other IM services @cindex instant messaging, other services @cindex Jabber @@ -633,6 +630,19 @@ the other instant messaging services, and Bitlbee will log you in. All @code{rcirc} needs to know, is the login to your Bitlbee account. Don't confuse the Bitlbee account with all the other accounts. +@item sasl +@cindex sasl authentication +Use this symbol if you want to use @acronym{SASL} authentication. The +necessary arguments are the nickname you want to use this for, and the +password to use. + +@item certfp +@cindex certfp authentication +Use this symbol if you want to use CertFP authentication. The +necessary arguments are the path to the key and to the client +certificate associated with the account. The CertFP authentication +requires a @acronym{TLS} connection. + @end table @end table @@ -926,6 +936,11 @@ how to include the date in the time stamp: (setq rcirc-time-format "%Y-%m-%d %H:%M ") @end example +@findex rcirc-when +If you don't wish to use verbose time formatting all the time, you can +use the @code{rcirc-when} command to display a complete timestamp for +the message at point. + @node Defining a new command @section Defining a new command @cindex defining commands diff --git a/doc/misc/remember.texi b/doc/misc/remember.texi index a980c39616a..9d1fe545d47 100644 --- a/doc/misc/remember.texi +++ b/doc/misc/remember.texi @@ -313,7 +313,7 @@ Save (if it is modified) and bury the current buffer. @node Keystrokes @chapter Keystroke Reference -@file{remember.el} defines the following keybindings by default: +@file{remember.el} defines the following key bindings by default: @table @kbd diff --git a/doc/misc/sem-user.texi b/doc/misc/sem-user.texi index 70ccdf4a612..3141ab7c692 100644 --- a/doc/misc/sem-user.texi +++ b/doc/misc/sem-user.texi @@ -145,7 +145,7 @@ this means moving to the parent of the current tag. @item C-c , @key{SPC} Display a list of possible completions for the symbol at point (@code{semantic-complete-analyze-inline}). This also activates a -special set of keybindings for choosing a completion: @key{RET} +special set of key bindings for choosing a completion: @key{RET} accepts the current completion, @kbd{M-n} and @kbd{M-p} cycle through possible completions, @key{TAB} completes as far as possible and then cycles, and @kbd{C-g} or any other key aborts the completion. @@ -655,7 +655,7 @@ usual summary if the text at point has one of these faces. Semantic Idle Completions mode is a minor mode for performing @dfn{code completions} during idle time. The completions are -displayed inline, with keybindings that allow you to cycle through +displayed inline, with key bindings that allow you to cycle through different alternatives. Semantic Idle Completions mode performs completion based on the @@ -681,7 +681,7 @@ besselj [1 of 6 matches] @end example @noindent -While the completion is being displayed, the following keybindings +While the completion is being displayed, the following key bindings take effect: @table @kbd @@ -785,7 +785,7 @@ Most of the other commands documented in this section call This command is bound to @kbd{C-c , @key{SPC}} when Semantic mode is enabled (@pxref{Semantic mode user commands}). It displays a list of possible completions for the symbol at point, and activates a special -set of keybindings for choosing a completion. +set of key bindings for choosing a completion. You can type @key{RET} to accept the current completion, @kbd{M-n} and @kbd{M-p} to cycle through the possible completions, @key{TAB} to @@ -1122,7 +1122,7 @@ that @code{grep} is much slower than the others. The commands to display symbol references are @kbd{C-c , g} (@code{semantic-symref-symbol} and @kbd{C-c , G} -(@code{semantic-symref}). These keybindings are available whenever +(@code{semantic-symref}). These key bindings are available whenever Semantic mode is enabled (@pxref{Semantic mode user commands}). @deffn Command semantic-symref-symbol sym diff --git a/doc/misc/ses.texi b/doc/misc/ses.texi index 0acb7bf3f15..6d0415cdbbb 100644 --- a/doc/misc/ses.texi +++ b/doc/misc/ses.texi @@ -220,7 +220,14 @@ You move around with the regular Emacs movement commands. @table @kbd @item j -Moves point to cell, specified by identifier (@code{ses-jump}). +Moves point to cell, specified by identifier (@code{ses-jump}). Unless +the cell is a renamed cell, the identifier is case-insensitive. A +prefix argument @math{n} move to cell with coordinates @math{(n\div R, +n \% C)} for a spreadsheet of @math{R} rows and @math{C} columns, and +A1 being of coordinates @math{(0,0)}. The way the identifier or the +command prefix argument are interpreted can be customized through +variables @code{ses-jump-cell-name-function} and +@code{ses-jump-prefix-function}. @end table Point is always at the left edge of a cell, or at the empty endline. @@ -726,10 +733,6 @@ yank. This doesn't make any difference? @section Customizing @acronym{SES} @cindex customizing @vindex enable-local-eval -@vindex ses-mode-hook -@vindex safe-functions -@vindex enable-local-eval - By default, a newly-created spreadsheet has 1 row and 1 column. The column width is 7 and the default printer is @samp{"%.7g"}. Each of these @@ -740,9 +743,34 @@ cell. You can customize @code{ses-after-entry-functions} to move left or up or down. For diagonal movement, select two functions from the list. +@vindex ses-jump-cell-name-function +@code{ses-jump-cell-name-function} is a customizable variable by +default set to the @code{upcase} function. This function is called +when you pass a cell name to the @command{ses-jump} command (@kbd{j}), +it changes the entered cell name to that where to jump. The default +setting @code{upcase} allows you to enter the cell name in low +case. Another use of @code{ses-jump-cell-name-function} could be some +internationalisation to convert non latin characters into latin +equivalents to name the cell. Instead of a cell name, the function may +return cell coordinates in the form of a cons, for instance @code{(0 +. 0)} for cell @code{A1}, @code{(1 . 0)} for cell @code{A2}, etc. + +@vindex ses-jump-prefix-function +@code{ses-jump-prefix-function} is a customisable variable by default +set to the @code{ses-jump-prefix} function. This function is called +when you give a prefix argument to the @command{ses-jump} command +(@kbd{j}). It returns a cell name or cell coordinates corresponding to +the prefix argument. Cell coordinates are in the form of a cons, for +instance @code{(1 . 0)} for cell @code{A2}. The default setting +@code{ses-jump-prefix} will number cells left to right and then top +down, so assuming a 4x3 spreadsheet prefix argument 0 jumps to cell +A1, prefix argument 2 jumps to C1, prefix argument 3 jumps to A2, etc. + +@vindex ses-mode-hook @code{ses-mode-hook} is a normal mode hook (list of functions to execute when starting @acronym{SES} mode for a buffer). +@vindex safe-functions The variable @code{safe-functions} is a list of possibly-unsafe functions to be treated as safe when analyzing formulas and printers. @xref{Virus protection}. Before customizing @code{safe-functions}, diff --git a/doc/misc/speedbar.texi b/doc/misc/speedbar.texi index 8368f198a34..13b709bfc8b 100644 --- a/doc/misc/speedbar.texi +++ b/doc/misc/speedbar.texi @@ -1218,4 +1218,3 @@ Two good values are @code{nil} and @code{statictag}. @bye @c LocalWords: speedbar's xref slowbar kbd subsubsection -@c LocalWords: keybindings diff --git a/doc/misc/srecode.texi b/doc/misc/srecode.texi index 9b1578ec0e0..a0cbf7e33fb 100644 --- a/doc/misc/srecode.texi +++ b/doc/misc/srecode.texi @@ -293,14 +293,14 @@ If the variable @code{srecode-takeover-INS-key} is set, then the key The most important key is bound to @code{srecode-insert} which is @kbd{C-c / /}, or @kbd{@key{INSERT} @key{INSERT}}. @ref{Quick Start}. -Major keybindings are: +Major key bindings are: @table @kbd @item C-c / / Insert a template whose name is typed into the minibuffer. @item C-c / <lower case letter> Reserved for direct binding of simple templates to keys using a -keybinding command in the template file. +key binding command in the template file. @item C-c / <upper case letter> Reserved for template applications (Such as comment or get/set inserter.) @item C-c / E @@ -1070,9 +1070,9 @@ Here is an example of wrapping a semantic tag in a compound value: "Wrap up a collection of semantic tag information. This class will be used to derive dictionary values.") -(defmethod srecode-compound-toString((cp srecode-semantic-tag) - function - dictionary) +(cl-defmethod srecode-compound-toString ((cp srecode-semantic-tag) + function + dictionary) "Convert the compound dictionary value CP to a string. If FUNCTION is non-nil, then FUNCTION is somehow applied to an aspect of the compound value." diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex index 4e83986b8dd..f86af0db3e5 100644 --- a/doc/misc/texinfo.tex +++ b/doc/misc/texinfo.tex @@ -3,9 +3,9 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2021-04-25.21} +\def\texinfoversion{2022-08-20.19} % -% Copyright 1985--1986, 1988, 1990--2022 Free Software Foundation, Inc. +% Copyright 1985, 1986, 1988, 1990-2022 Free Software Foundation, Inc. % % This texinfo.tex file is free software: you can redistribute it and/or % modify it under the terms of the GNU General Public License as @@ -725,32 +725,22 @@ where each line of input produces a line of output.} \dimen2 = \ht\strutbox \advance\dimen2 by \dp\strutbox \ifdim\dimen0 > \dimen2 + % This is similar to the 'needspace' module in LaTeX. + % The first penalty allows a break if the end of the page is + % not too far away. Following penalties and skips are discarded. + % Otherwise, require at least \dimen0 of vertical space. % - % Do a \strut just to make the height of this box be normal, so the - % normal leading is inserted relative to the preceding line. - % And a page break here is fine. - \vtop to #1\mil{\strut\vfil}% - % - % TeX does not even consider page breaks if a penalty added to the - % main vertical list is 10000 or more. But in order to see if the - % empty box we just added fits on the page, we must make it consider - % page breaks. On the other hand, we don't want to actually break the - % page after the empty box. So we use a penalty of 9999. - % - % There is an extremely small chance that TeX will actually break the - % page at this \penalty, if there are no other feasible breakpoints in - % sight. (If the user is using lots of big @group commands, which - % almost-but-not-quite fill up a page, TeX will have a hard time doing - % good page breaking, for example.) However, I could not construct an - % example where a page broke at this \penalty; if it happens in a real - % document, then we can reconsider our strategy. + % (We used to use a \vtop to reserve space, but this had spacing issues + % when followed by a section heading, as it was not a "discardable item". + % This also has the benefit of providing glue before the page break if + % there isn't enough space.) + \vskip0pt plus \dimen0 + \penalty-100 + \vskip0pt plus -\dimen0 + \vskip \dimen0 \penalty9999 - % - % Back up by the size of the box, whether we did a page break or not. - \kern -#1\mil - % - % Do not allow a page break right after this kern. - \nobreak + \vskip -\dimen0 + \penalty0\relax % this hides the above glue from \safewhatsit and \dobreak \fi } @@ -1002,7 +992,7 @@ where each line of input produces a line of output.} \global\everypar = {}% } -% leave vertical mode without canceling any first paragraph indent +% leave vertical mode without cancelling any first paragraph indent \gdef\imageindent{% \toks0=\everypar \everypar={}% @@ -2558,7 +2548,7 @@ end \def\it{\fam=\itfam \setfontstyle{it}} \def\sl{\fam=\slfam \setfontstyle{sl}} \def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf} -\def\tt{\fam=\ttfam \setfontstyle{tt}}\def\ttstylename{tt} +\def\tt{\fam=\ttfam \setfontstyle{tt}} % Texinfo sort of supports the sans serif font style, which plain TeX does not. % So we set up a \sf. @@ -2691,6 +2681,14 @@ end % \def\ifmonospace{\ifdim\fontdimen3\font=0pt } +% Check if internal flag is clear, i.e. has not been @set. +\def\ifflagclear#1#2#3{% + \expandafter\ifx\csname SET#1\endcsname\relax + #2\else#3\fi +} + + + { \catcode`\'=\active \catcode`\`=\active @@ -2707,14 +2705,14 @@ end % \def\codequoteright{% \ifmonospace - \expandafter\ifx\csname SETtxicodequoteundirected\endcsname\relax - \expandafter\ifx\csname SETcodequoteundirected\endcsname\relax + \ifflagclear{txicodequoteundirected}{% + \ifflagclear{codequoteundirected}{% '% - \else \char'15 \fi - \else \char'15 \fi - \else - '% - \fi + }{\char'15 }% + }{\char'15 }% + \else + '% + \fi } % % and a similar option for the left quote char vs. a grave accent. @@ -2723,16 +2721,16 @@ end % \def\codequoteleft{% \ifmonospace - \expandafter\ifx\csname SETtxicodequotebacktick\endcsname\relax - \expandafter\ifx\csname SETcodequotebacktick\endcsname\relax + \ifflagclear{txicodequotebacktick}{% + \ifflagclear{codequotebacktick}{% % [Knuth] pp. 380,381,391 % \relax disables Spanish ligatures ?` and !` of \tt font. \relax`% - \else \char'22 \fi - \else \char'22 \fi - \else - \relax`% - \fi + }{\char'22 }% + }{\char'22 }% + \else + \relax`% + \fi } % Commands to set the quote options. @@ -2779,15 +2777,16 @@ end \def\dosmartslant#1#2{% \ifusingtt {{\ttsl #2}\let\next=\relax}% - {\def\next{{#1#2}\futurelet\next\smartitaliccorrection}}% + {\def\next{{#1#2}\smartitaliccorrection}}% \next } \def\smartslanted{\dosmartslant\sl} \def\smartitalic{\dosmartslant\it} -% Output an italic correction unless \next (presumed to be the following -% character) is such as not to need one. -\def\smartitaliccorrection{% +% Output an italic correction unless the following character is such as +% not to need one. +\def\smartitaliccorrection{\futurelet\next\smartitaliccorrectionx} +\def\smartitaliccorrectionx{% \ifx\next,% \else\ifx\next-% \else\ifx\next.% @@ -2798,18 +2797,18 @@ end \aftersmartic } -% Unconditional use \ttsl, and no ic. @var is set to this for defuns. -\def\ttslanted#1{{\ttsl #1}} - -% @cite is like \smartslanted except unconditionally use \sl. We never want -% ttsl for book titles, do we? -\def\cite#1{{\sl #1}\futurelet\next\smartitaliccorrection} +% @cite unconditionally uses \sl with \smartitaliccorrection. +\def\cite#1{{\sl #1}\smartitaliccorrection} +% @var unconditionally uses \sl. This gives consistency for +% parameter names whether they are in @def, @table @code or a +% regular paragraph. +% The \null is to reset \spacefactor. \def\aftersmartic{} \def\var#1{% \let\saveaftersmartic = \aftersmartic \def\aftersmartic{\null\let\aftersmartic=\saveaftersmartic}% - \smartslanted{#1}% + {\sl #1}\smartitaliccorrection } \let\i=\smartitalic @@ -2817,8 +2816,14 @@ end \let\dfn=\smartslanted \let\emph=\smartitalic -% Explicit font changes: @r, @sc, undocumented @ii. -\def\r#1{{\rm #1}} % roman font +% @r for roman font, used for code comment +\def\r#1{{% + \usenormaldash % get --, --- ligatures even if in @code + \defcharsdefault % in case on def line + \rm #1}} +{\catcode`-=\active \gdef\usenormaldash{\let-\normaldash}} + +% @sc, undocumented @ii. \def\sc#1{{\smallcaps#1}} % smallcaps font \def\ii#1{{\it #1}} % italic font @@ -2856,7 +2861,7 @@ end % @t, explicit typewriter. \def\t#1{% - {\tt \plainfrenchspacing #1}% + {\tt \defcharsdefault \plainfrenchspacing #1}% \null } @@ -3171,16 +3176,8 @@ end % Default is `distinct'. \kbdinputstyle distinct -% @kbd is like @code, except that if the argument is just one @key command, -% then @kbd has no effect. -\def\kbd#1{{\def\look{#1}\expandafter\kbdsub\look??\par}} - -\def\xkey{\key} -\def\kbdsub#1#2#3\par{% - \def\one{#1}\def\three{#3}\def\threex{??}% - \ifx\one\xkey\ifx\threex\three \key{#2}% - \else{\tclose{\kbdfont\setcodequotes\look}}\fi - \else{\tclose{\kbdfont\setcodequotes\look}}\fi +\def\kbd#1{% + \tclose{\kbdfont\setcodequotes#1}% } % definition of @key that produces a lozenge. Doesn't adjust to text size. @@ -3193,14 +3190,9 @@ end % \kern-0.4pt\hrule}% % \kern-.06em\raise0.4pt\hbox{\angleright}}}} -% definition of @key with no lozenge. If the current font is already -% monospace, don't change it; that way, we respect @kbdinputstyle. But -% if it isn't monospace, then use \tt. +% definition of @key with no lozenge. % -\def\key#1{{\setregularquotes - \nohyphenation - \ifmonospace\else\tt\fi - #1}\null} +\def\key#1{{\setregularquotes \nohyphenation \tt #1}\null} % @clicksequence{File @click{} Open ...} \def\clicksequence#1{\begingroup #1\endgroup} @@ -3614,6 +3606,9 @@ $$% \def\quotedblbase{{\ecfont \char"12}} \def\quotesinglbase{{\ecfont \char"0D}} % +\def\L{{\ecfont \char"8A}} % L with stroke +\def\l{{\ecfont \char"AA}} % l with stroke +% % This positioning is not perfect (see the ogonek LaTeX package), but % we have the precomposed glyphs for the most common cases. We put the % tests to use those glyphs in the single \ogonek macro so we have fewer @@ -4419,7 +4414,7 @@ $$% % Find the correct column width \hsize=\expandafter\csname col\the\colcount\endcsname % - \rightskip=0pt + \advance\rightskip by -1\rightskip % Zero leaving only any stretch \ifnum\colcount=1 \advance\hsize by\leftskip % Add indent of surrounding text \else @@ -4442,7 +4437,7 @@ $$% \message{conditionals,} -% @iftex, @ifnotdocbook, @ifnothtml, @ifnotinfo, @ifnotplaintext, +% @iftex, @ifnotdocbook, @ifnothtml, @ifnotinfo, @ifnotlatex, @ifnotplaintext, % @ifnotxml always succeed. They currently do nothing; we don't % attempt to check whether the conditionals are properly nested. But we % have to remember that they are conditionals, so that @end doesn't @@ -4456,6 +4451,7 @@ $$% \makecond{ifnotdocbook} \makecond{ifnothtml} \makecond{ifnotinfo} +\makecond{ifnotlatex} \makecond{ifnotplaintext} \makecond{ifnotxml} @@ -4468,10 +4464,12 @@ $$% \def\ifdocbook{\doignore{ifdocbook}} \def\ifhtml{\doignore{ifhtml}} \def\ifinfo{\doignore{ifinfo}} +\def\iflatex{\doignore{iflatex}} \def\ifnottex{\doignore{ifnottex}} \def\ifplaintext{\doignore{ifplaintext}} \def\ifxml{\doignore{ifxml}} \def\ignore{\doignore{ignore}} +\def\latex{\doignore{latex}} \def\menu{\doignore{menu}} \def\xml{\doignore{xml}} @@ -4995,25 +4993,24 @@ $$% \catcode`\-=13 \catcode`\`=13 \gdef\indexnonalnumdisappear{% - \expandafter\ifx\csname SETtxiindexlquoteignore\endcsname\relax\else + \ifflagclear{txiindexlquoteignore}{}{% % @set txiindexlquoteignore makes us ignore left quotes in the sort term. % (Introduced for FSFS 2nd ed.) \let`=\empty - \fi + }% % - \expandafter\ifx\csname SETtxiindexbackslashignore\endcsname\relax\else + \ifflagclear{txiindexbackslashignore}{}{% \backslashdisappear - \fi - % - \expandafter\ifx\csname SETtxiindexhyphenignore\endcsname\relax\else + }% + \ifflagclear{txiindexhyphenignore}{}{% \def-{}% - \fi - \expandafter\ifx\csname SETtxiindexlessthanignore\endcsname\relax\else + }% + \ifflagclear{txiindexlessthanignore}{}{% \def<{}% - \fi - \expandafter\ifx\csname SETtxiindexatsignignore\endcsname\relax\else + }% + \ifflagclear{txiindexatsignignore}{}{% \def\@{}% - \fi + }% } \gdef\indexnonalnumreappear{% @@ -5305,9 +5302,7 @@ $$% % \atdummies % - \expandafter\ifx\csname SETtxiindexescapeisbackslash\endcsname\relax\else - \escapeisbackslash - \fi + \ifflagclear{txiindexescapeisbackslash}{}{\escapeisbackslash}% % % For texindex which always views { and } as separators. \def\{{\lbracechar{}}% @@ -5491,9 +5486,9 @@ $$% % old index files using \ as the escape character. Reading this would % at best lead to typesetting garbage, at worst a TeX syntax error. \def\printindexzz#1#2\finish{% - \expandafter\ifx\csname SETtxiindexescapeisbackslash\endcsname\relax + \ifflagclear{txiindexescapeisbackslash}{% \uccode`\~=`\\ \uppercase{\if\noexpand~}\noexpand#1 - \expandafter\ifx\csname SETtxiskipindexfileswithbackslash\endcsname\relax + \ifflagclear{txiskipindexfileswithbackslash}{% \errmessage{% ERROR: A sorted index file in an obsolete format was skipped. To fix this problem, please upgrade your version of 'texi2dvi' @@ -5509,15 +5504,15 @@ this, Texinfo will try to use index files in the old format. If you continue to have problems, deleting the index files and starting again might help (with 'rm \jobname.?? \jobname.??s')% }% - \else + }{% (Skipped sorted index file in obsolete format) - \fi + }% \else \begindoublecolumns \input \jobname.\indexname s \enddoublecolumns \fi - \else + }{% \begindoublecolumns \catcode`\\=0\relax % @@ -5527,7 +5522,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% \catcode`\@=0\relax \input \jobname.\indexname s \enddoublecolumns - \fi + }% } % These macros are used by the sorted index file itself. @@ -5963,7 +5958,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% % Chapters, sections, etc. % Let's start with @part. -\outer\parseargdef\part{\partzzz{#1}} +\parseargdef\part{\partzzz{#1}} \def\partzzz#1{% \chapoddpage \null @@ -7287,22 +7282,6 @@ might help (with 'rm \jobname.?? \jobname.??s')% } \let\Eraggedright\par -\envdef\raggedleft{% - \parindent=0pt \leftskip0pt plus2em - \spaceskip.3333em \xspaceskip.5em \parfillskip=0pt - \hbadness=10000 % Last line will usually be underfull, so turn off - % badness reporting. -} -\let\Eraggedleft\par - -\envdef\raggedcenter{% - \parindent=0pt \rightskip0pt plus1em \leftskip0pt plus1em - \spaceskip.3333em \xspaceskip.5em \parfillskip=0pt - \hbadness=10000 % Last line will usually be underfull, so turn off - % badness reporting. -} -\let\Eraggedcenter\par - % @quotation does normal linebreaking (hence we can't use \nonfillstart) % and narrows the margins. We keep \parskip nonzero in general, since @@ -7525,9 +7504,11 @@ might help (with 'rm \jobname.?? \jobname.??s')% % file; b) letting users define the frontmatter in as flexible order as % possible is desirable. % -\def\copying{\checkenv{}\begingroup\scanargctxt\docopying} -\def\docopying#1@end copying{\endgroup\def\copyingtext{#1}} -% +\def\copying{\checkenv{}\begingroup\macrobodyctxt\docopying} +{\catcode`\ =\other +\gdef\docopying#1@end copying{\endgroup\def\copyingtext{#1}} +} + \def\insertcopying{% \begingroup \parindent = 0pt % paragraph indentation looks wrong on title page @@ -7592,6 +7573,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% % \def\printdefunline#1#2{% \begingroup + \plainfrenchspacing % call \deffnheader: #1#2 \endheader % common ending: @@ -7608,21 +7590,15 @@ might help (with 'rm \jobname.?? \jobname.??s')% \def\Edefun{\endgraf\medbreak} -% \makedefun{deffn} creates \deffn, \deffnx and \Edeffn; -% the only thing remaining is to define \deffnheader. +% \makedefun{deffoo}{ (definition of \deffooheader) } % +% Define \deffoo, \deffoox \Edeffoo and \deffooheader. \def\makedefun#1{% \expandafter\let\csname E#1\endcsname = \Edefun \edef\temp{\noexpand\domakedefun \makecsname{#1}\makecsname{#1x}\makecsname{#1header}}% \temp } - -% \domakedefun \deffn \deffnx \deffnheader { (defn. of \deffnheader) } -% -% Define \deffn and \deffnx, without parameters. -% \deffnheader has to be defined explicitly. -% \def\domakedefun#1#2#3{% \envdef#1{% \startdefun @@ -7655,74 +7631,51 @@ might help (with 'rm \jobname.?? \jobname.??s')% \fi\fi } -% \dosubind {index}{topic}{subtopic} -% -% If SUBTOPIC is present, precede it with a space, and call \doind. -% (At some time during the 20th century, this made a two-level entry in an -% index such as the operation index. Nobody seemed to notice the change in -% behavior though.) -\def\dosubind#1#2#3{% - \def\thirdarg{#3}% - \ifx\thirdarg\empty - \doind{#1}{#2}% - \else - \doind{#1}{#2\space#3}% - \fi -} - % Untyped functions: % @deffn category name args -\makedefun{deffn}{\deffngeneral{}} - -% @deffn category class name args -\makedefun{defop}#1 {\defopon{#1\ \putwordon}} - -% \defopon {category on}class name args -\def\defopon#1#2 {\deffngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} } +\makedefun{deffn}#1 #2 #3\endheader{% + \doind{fn}{\code{#2}}% + \defname{#1}{}{#2}\magicamp\defunargs{#3\unskip}% +} -% \deffngeneral {subind}category name args -% -\def\deffngeneral#1#2 #3 #4\endheader{% - \dosubind{fn}{\code{#3}}{#1}% - \defname{#2}{}{#3}\magicamp\defunargs{#4\unskip}% +% @defop category class name args +\makedefun{defop}#1 {\defopheaderx{#1\ \putwordon}} +\def\defopheaderx#1#2 #3 #4\endheader{% + \doind{fn}{\code{#3}\space\putwordon\ \code{#2}}% + \defname{#1\ \code{#2}}{}{#3}\magicamp\defunargs{#4\unskip}% } % Typed functions: % @deftypefn category type name args -\makedefun{deftypefn}{\deftypefngeneral{}} +\makedefun{deftypefn}#1 #2 #3 #4\endheader{% + \doind{fn}{\code{#3}}% + \doingtypefntrue + \defname{#1}{#2}{#3}\defunargs{#4\unskip}% +} % @deftypeop category class type name args -\makedefun{deftypeop}#1 {\deftypeopon{#1\ \putwordon}} - -% \deftypeopon {category on}class type name args -\def\deftypeopon#1#2 {\deftypefngeneral{\putwordon\ \code{#2}}{#1\ \code{#2}} } - -% \deftypefngeneral {subind}category type name args -% -\def\deftypefngeneral#1#2 #3 #4 #5\endheader{% - \dosubind{fn}{\code{#4}}{#1}% +\makedefun{deftypeop}#1 {\deftypeopheaderx{#1\ \putwordon}} +\def\deftypeopheaderx#1#2 #3 #4 #5\endheader{% + \doind{fn}{\code{#4}\space\putwordon\ \code{#1\ \code{#2}}}% \doingtypefntrue - \defname{#2}{#3}{#4}\defunargs{#5\unskip}% + \defname{#1\ \code{#2}}{#3}{#4}\defunargs{#5\unskip}% } % Typed variables: % @deftypevr category type var args -\makedefun{deftypevr}{\deftypecvgeneral{}} +\makedefun{deftypevr}#1 #2 #3 #4\endheader{% + \doind{vr}{\code{#3}}% + \defname{#1}{#2}{#3}\defunargs{#4\unskip}% +} % @deftypecv category class type var args -\makedefun{deftypecv}#1 {\deftypecvof{#1\ \putwordof}} - -% \deftypecvof {category of}class type var args -\def\deftypecvof#1#2 {\deftypecvgeneral{\putwordof\ \code{#2}}{#1\ \code{#2}} } - -% \deftypecvgeneral {subind}category type var args -% -\def\deftypecvgeneral#1#2 #3 #4 #5\endheader{% - \dosubind{vr}{\code{#4}}{#1}% - \defname{#2}{#3}{#4}\defunargs{#5\unskip}% +\makedefun{deftypecv}#1 {\deftypecvheaderx{#1\ \putwordof}} +\def\deftypecvheaderx#1#2 #3 #4 #5\endheader{% + \doind{vr}{\code{#4}\space\putwordof\ \code{#2}}% + \defname{#1\ \code{#2}}{#3}{#4}\defunargs{#5\unskip}% } % Untyped variables: @@ -7731,10 +7684,8 @@ might help (with 'rm \jobname.?? \jobname.??s')% \makedefun{defvr}#1 {\deftypevrheader{#1} {} } % @defcv category class var args -\makedefun{defcv}#1 {\defcvof{#1\ \putwordof}} - -% \defcvof {category of}class var args -\def\defcvof#1#2 {\deftypecvof{#1}#2 {} } +\makedefun{defcv}#1 {\defcvheaderx{#1\ \putwordof}} +\def\defcvheaderx#1#2 {\deftypecvheaderx{#1}#2 {} } % Types: @@ -7752,10 +7703,10 @@ might help (with 'rm \jobname.?? \jobname.??s')% \makedefun{defvar}{\defvrheader{\putwordDefvar} } \makedefun{defopt}{\defvrheader{\putwordDefopt} } \makedefun{deftypevar}{\deftypevrheader{\putwordDefvar} } -\makedefun{defmethod}{\defopon\putwordMethodon} -\makedefun{deftypemethod}{\deftypeopon\putwordMethodon} -\makedefun{defivar}{\defcvof\putwordInstanceVariableof} -\makedefun{deftypeivar}{\deftypecvof\putwordInstanceVariableof} +\makedefun{defmethod}{\defopheaderx\putwordMethodon} +\makedefun{deftypemethod}{\deftypeopheaderx\putwordMethodon} +\makedefun{defivar}{\defcvheaderx\putwordInstanceVariableof} +\makedefun{deftypeivar}{\deftypecvheaderx\putwordInstanceVariableof} % \defname, which formats the name of the @def (not the args). % #1 is the category, such as "Function". @@ -7774,9 +7725,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% \rettypeownlinefalse \ifdoingtypefn % doing a typed function specifically? % then check user option for putting return type on its own line: - \expandafter\ifx\csname SETtxideftypefnnl\endcsname\relax \else - \rettypeownlinetrue - \fi + \ifflagclear{txideftypefnnl}{}{\rettypeownlinetrue}% \fi % % How we'll format the category name. Putting it in brackets helps @@ -7841,30 +7790,18 @@ might help (with 'rm \jobname.?? \jobname.??s')% \fi % no return type #3% output function name }% - {\rm\enskip}% hskip 0.5 em of \rmfont + \ifflagclear{txidefnamenospace}{% + {\rm\enskip}% hskip 0.5 em of \rmfont + }{}% % \boldbrax % arguments will be output next, if any. } -% Print arguments in slanted roman (not ttsl), inconsistently with using -% tt for the name. This is because literal text is sometimes needed in -% the argument list (groff manual), and ttsl and tt are not very -% distinguishable. Prevent hyphenation at `-' chars. -% +% Print arguments. Use slanted for @def*, typewriter for @deftype*. \def\defunargs#1{% - % use sl by default (not ttsl), - % tt for the names. - \df \sl \hyphenchar\font=0 - % - % On the other hand, if an argument has two dashes (for instance), we - % want a way to get ttsl. We used to recommend @var for that, so - % leave the code in, but it's strange for @var to lead to typewriter. - % Nowadays we recommend @code, since the difference between a ttsl hyphen - % and a tt hyphen is pretty tiny. @code also disables ?` !`. - \def\var##1{{\setregularquotes\ttslanted{##1}}}% + \df \ifdoingtypefn \tt \else \sl \fi #1% - \sl\hyphenchar\font=45 } % We want ()&[] to print specially on the defun line. @@ -7883,9 +7820,12 @@ might help (with 'rm \jobname.?? \jobname.??s')% % so TeX would otherwise complain about undefined control sequence. { \activeparens - \global\let(=\lparen \global\let)=\rparen - \global\let[=\lbrack \global\let]=\rbrack - \global\let& = \& + \gdef\defcharsdefault{% + \let(=\lparen \let)=\rparen + \let[=\lbrack \let]=\rbrack + \let& = \&% + } + \globaldefs=1 \defcharsdefault \gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} \gdef\magicamp{\let&=\amprm} @@ -8069,24 +8009,17 @@ might help (with 'rm \jobname.?? \jobname.??s')% \catcode`\_=\other \catcode`\|=\other \catcode`\~=\other - \passthroughcharstrue -} - -\def\scanargctxt{% used for copying and captions, not macros. - \scanctxt \catcode`\@=\other - \catcode`\\=\other \catcode`\^^M=\other + \catcode`\\=\active + \passthroughcharstrue } -\def\macrobodyctxt{% used for @macro definitions +\def\macrobodyctxt{% used for @macro definitions and @copying \scanctxt \catcode`\ =\other - \catcode`\@=\other \catcode`\{=\other \catcode`\}=\other - \catcode`\^^M=\other - \usembodybackslash } % Used when scanning braced macro arguments. Note, however, that catcode @@ -8095,14 +8028,10 @@ might help (with 'rm \jobname.?? \jobname.??s')% \def\macroargctxt{% \scanctxt \catcode`\ =\active - \catcode`\@=\other - \catcode`\^^M=\other - \catcode`\\=\active } \def\macrolineargctxt{% used for whole-line arguments without braces \scanctxt - \catcode`\@=\other \catcode`\{=\other \catcode`\}=\other } @@ -8146,7 +8075,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% \global\expandafter\let\csname ismacro.\the\macname\endcsname=1% \addtomacrolist{\the\macname}% \fi - \begingroup \macrobodyctxt + \begingroup \macrobodyctxt \usembodybackslash \ifrecursive \expandafter\parsermacbody \else \expandafter\parsemacbody \fi} @@ -8681,9 +8610,11 @@ might help (with 'rm \jobname.?? \jobname.??s')% } \def\wordTop{Top} -% Until the next @node or @bye command, divert output to a box that is not -% output. -\def\ignorenode{\setbox\dummybox\vbox\bgroup\def\node{\egroup\node}% +% Until the next @node, @part or @bye command, divert output to a box that +% is not output. +\def\ignorenode{\setbox\dummybox\vbox\bgroup +\def\part{\egroup\part}% +\def\node{\egroup\node}% \ignorenodebye } @@ -8948,7 +8879,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% % output the `[mynode]' via the macro below so it can be overridden. \xrefprintnodename\printedrefname % - \expandafter\ifx\csname SETtxiomitxrefpg\endcsname\relax + \ifflagclear{txiomitxrefpg}{% % But we always want a comma and a space: ,\space % @@ -8963,7 +8894,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% \tokenafterxref ,% @NL \else\ifx\tie\tokenafterxref ,% @tie \fi\fi\fi\fi\fi\fi - \fi + }{}% \fi\fi \fi \endlink @@ -9392,25 +9323,27 @@ might help (with 'rm \jobname.?? \jobname.??s')% \catcode`\^^M = 5 % in case we're inside an example \normalturnoffactive % allow _ et al. in names \makevalueexpandable - % If the image is by itself, center it. \ifvmode \imagevmodetrue \else \ifx\centersub\centerV % for @center @image, we need a vbox so we can have our vertical space \imagevmodetrue - \vbox\bgroup % vbox has better behavior than vtop herev + \vbox\bgroup % vbox has better behavior than vtop here \fi\fi % \ifimagevmode - \nobreak\medskip + \medskip % Usually we'll have text after the image which will insert % \parskip glue, so insert it here too to equalize the space % above and below. - \nobreak\vskip\parskip - \nobreak + \vskip\parskip + % + % Place image in a \vtop for a top page margin that is (close to) correct, + % as \topskip glue is relative to the first baseline. + \vtop\bgroup\hrule height 0pt\vskip-\parskip \fi % - % Leave vertical mode so that indentation from an enclosing + % Enter horizontal mode so that indentation from an enclosing % environment such as @quotation is respected. % However, if we're at the top level, we don't want the % normal paragraph indentation. @@ -9439,6 +9372,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% \fi % \ifimagevmode + \egroup \medskip % space after a standalone image \fi \ifx\centersub\centerV \egroup \fi @@ -9608,7 +9542,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% % \def\caption{\docaption\thiscaption} \def\shortcaption{\docaption\thisshortcaption} -\def\docaption{\checkenv\float \bgroup\scanargctxt\defcaption} +\def\docaption{\checkenv\float \bgroup\scanctxt\defcaption} \def\defcaption#1#2{\egroup \def#1{#2}} % The parameter is the control sequence identifying the counter we are @@ -10328,9 +10262,9 @@ directory should work if nowhere else does.} % Given the value in \countUTFz as a Unicode code point, set \UTFviiiTmp % to the corresponding UTF-8 sequence. \gdef\parseXMLCharref{% - \ifnum\countUTFz < "A0\relax + \ifnum\countUTFz < "20\relax \errhelp = \EMsimple - \errmessage{Cannot define Unicode char value < 00A0}% + \errmessage{Cannot define Unicode char value < 0020}% \else\ifnum\countUTFz < "800\relax \parseUTFviiiA,% \parseUTFviiiB C\UTFviiiTwoOctetsName.,% @@ -10400,6 +10334,103 @@ directory should work if nowhere else does.} % least make most of the characters not bomb out. % \def\unicodechardefs{% + \DeclareUnicodeCharacter{0020}{ } % space + \DeclareUnicodeCharacter{0021}{\char"21 }% % space to terminate number + \DeclareUnicodeCharacter{0022}{\char"22 }% + \DeclareUnicodeCharacter{0023}{\char"23 }% + \DeclareUnicodeCharacter{0024}{\char"24 }% + \DeclareUnicodeCharacter{0025}{\char"25 }% + \DeclareUnicodeCharacter{0026}{\char"26 }% + \DeclareUnicodeCharacter{0027}{\char"27 }% + \DeclareUnicodeCharacter{0028}{\char"28 }% + \DeclareUnicodeCharacter{0029}{\char"29 }% + \DeclareUnicodeCharacter{002A}{\char"2A }% + \DeclareUnicodeCharacter{002B}{\char"2B }% + \DeclareUnicodeCharacter{002C}{\char"2C }% + \DeclareUnicodeCharacter{002D}{\char"2D }% + \DeclareUnicodeCharacter{002E}{\char"2E }% + \DeclareUnicodeCharacter{002F}{\char"2F }% + \DeclareUnicodeCharacter{0030}{0}% + \DeclareUnicodeCharacter{0031}{1}% + \DeclareUnicodeCharacter{0032}{2}% + \DeclareUnicodeCharacter{0033}{3}% + \DeclareUnicodeCharacter{0034}{4}% + \DeclareUnicodeCharacter{0035}{5}% + \DeclareUnicodeCharacter{0036}{6}% + \DeclareUnicodeCharacter{0037}{7}% + \DeclareUnicodeCharacter{0038}{8}% + \DeclareUnicodeCharacter{0039}{9}% + \DeclareUnicodeCharacter{003A}{\char"3A }% + \DeclareUnicodeCharacter{003B}{\char"3B }% + \DeclareUnicodeCharacter{003C}{\char"3C }% + \DeclareUnicodeCharacter{003D}{\char"3D }% + \DeclareUnicodeCharacter{003E}{\char"3E }% + \DeclareUnicodeCharacter{003F}{\char"3F }% + \DeclareUnicodeCharacter{0040}{\char"40 }% + \DeclareUnicodeCharacter{0041}{A}% + \DeclareUnicodeCharacter{0042}{B}% + \DeclareUnicodeCharacter{0043}{C}% + \DeclareUnicodeCharacter{0044}{D}% + \DeclareUnicodeCharacter{0045}{E}% + \DeclareUnicodeCharacter{0046}{F}% + \DeclareUnicodeCharacter{0047}{G}% + \DeclareUnicodeCharacter{0048}{H}% + \DeclareUnicodeCharacter{0049}{I}% + \DeclareUnicodeCharacter{004A}{J}% + \DeclareUnicodeCharacter{004B}{K}% + \DeclareUnicodeCharacter{004C}{L}% + \DeclareUnicodeCharacter{004D}{M}% + \DeclareUnicodeCharacter{004E}{N}% + \DeclareUnicodeCharacter{004F}{O}% + \DeclareUnicodeCharacter{0050}{P}% + \DeclareUnicodeCharacter{0051}{Q}% + \DeclareUnicodeCharacter{0052}{R}% + \DeclareUnicodeCharacter{0053}{S}% + \DeclareUnicodeCharacter{0054}{T}% + \DeclareUnicodeCharacter{0055}{U}% + \DeclareUnicodeCharacter{0056}{V}% + \DeclareUnicodeCharacter{0057}{W}% + \DeclareUnicodeCharacter{0058}{X}% + \DeclareUnicodeCharacter{0059}{Y}% + \DeclareUnicodeCharacter{005A}{Z}% + \DeclareUnicodeCharacter{005B}{\char"5B }% + \DeclareUnicodeCharacter{005C}{\char"5C }% + \DeclareUnicodeCharacter{005D}{\char"5D }% + \DeclareUnicodeCharacter{005E}{\char"5E }% + \DeclareUnicodeCharacter{005F}{\char"5F }% + \DeclareUnicodeCharacter{0060}{\char"60 }% + \DeclareUnicodeCharacter{0061}{a}% + \DeclareUnicodeCharacter{0062}{b}% + \DeclareUnicodeCharacter{0063}{c}% + \DeclareUnicodeCharacter{0064}{d}% + \DeclareUnicodeCharacter{0065}{e}% + \DeclareUnicodeCharacter{0066}{f}% + \DeclareUnicodeCharacter{0067}{g}% + \DeclareUnicodeCharacter{0068}{h}% + \DeclareUnicodeCharacter{0069}{i}% + \DeclareUnicodeCharacter{006A}{j}% + \DeclareUnicodeCharacter{006B}{k}% + \DeclareUnicodeCharacter{006C}{l}% + \DeclareUnicodeCharacter{006D}{m}% + \DeclareUnicodeCharacter{006E}{n}% + \DeclareUnicodeCharacter{006F}{o}% + \DeclareUnicodeCharacter{0070}{p}% + \DeclareUnicodeCharacter{0071}{q}% + \DeclareUnicodeCharacter{0072}{r}% + \DeclareUnicodeCharacter{0073}{s}% + \DeclareUnicodeCharacter{0074}{t}% + \DeclareUnicodeCharacter{0075}{u}% + \DeclareUnicodeCharacter{0076}{v}% + \DeclareUnicodeCharacter{0077}{w}% + \DeclareUnicodeCharacter{0078}{x}% + \DeclareUnicodeCharacter{0079}{y}% + \DeclareUnicodeCharacter{007A}{z}% + \DeclareUnicodeCharacter{007B}{\char"7B }% + \DeclareUnicodeCharacter{007C}{\char"7C }% + \DeclareUnicodeCharacter{007D}{\char"7D }% + \DeclareUnicodeCharacter{007E}{\char"7E }% + % \DeclareUnicodeCharacter{007F}{} % DEL + % \DeclareUnicodeCharacter{00A0}{\tie}% \DeclareUnicodeCharacter{00A1}{\exclamdown}% \DeclareUnicodeCharacter{00A2}{{\tcfont \char162}}% 0242=cent @@ -10899,6 +10930,9 @@ directory should work if nowhere else does.} \DeclareUnicodeCharacter{1EF8}{\~Y}% \DeclareUnicodeCharacter{1EF9}{\~y}% % + % Exotic spaces + \DeclareUnicodeCharacter{2007}{\hphantom{0}}% + % % Punctuation \DeclareUnicodeCharacter{2013}{--}% \DeclareUnicodeCharacter{2014}{---}% @@ -11081,24 +11115,26 @@ directory should work if nowhere else does.} % provide a definition macro to replace/pass-through a Unicode character % \def\DeclareUnicodeCharacterNative#1#2{% - \catcode"#1=\active - \def\dodeclareunicodecharacternative##1##2##3{% + \ifnum"#1>"7F % only make non-ASCII chars active + \catcode"#1=\active + \def\dodeclareunicodecharacternative##1##2##3{% + \begingroup + \uccode`\~="##2\relax + \uppercase{\gdef~}{% + \ifpassthroughchars + ##1% + \else + ##3% + \fi + } + \endgroup + } \begingroup - \uccode`\~="##2\relax - \uppercase{\gdef~}{% - \ifpassthroughchars - ##1% - \else - ##3% - \fi - } + \uccode`\.="#1\relax + \uppercase{\def\UTFNativeTmp{.}}% + \expandafter\dodeclareunicodecharacternative\UTFNativeTmp{#1}{#2}% \endgroup - } - \begingroup - \uccode`\.="#1\relax - \uppercase{\def\UTFNativeTmp{.}}% - \expandafter\dodeclareunicodecharacternative\UTFNativeTmp{#1}{#2}% - \endgroup + \fi } % Native Unicode handling (XeTeX and LuaTeX) character replacing definition. @@ -11244,23 +11280,6 @@ directory should work if nowhere else does.} \defbodyindent = .5cm }} -% Use @smallerbook to reset parameters for 6x9 trim size. -% (Just testing, parameters still in flux.) -\def\smallerbook{{\globaldefs = 1 - \parskip = 1.5pt plus 1pt - \textleading = 12pt - % - \internalpagesizes{7.4in}{4.8in}% - {-.2in}{-.4in}% - {0pt}{14pt}% - {9in}{6in}% - % - \lispnarrowing = 0.25in - \tolerance = 700 - \contentsrightmargin = 0pt - \defbodyindent = .4cm -}} - % Use @afourpaper to print on European A4 paper. \def\afourpaper{{\globaldefs = 1 \parskip = 3pt plus 2pt minus 1pt @@ -11294,7 +11313,7 @@ directory should work if nowhere else does.} \textleading = 12.5pt % \internalpagesizes{160mm}{120mm}% - {\voffset}{\hoffset}% + {\voffset}{-11.4mm}% {\bindingoffset}{8pt}% {210mm}{148mm}% % @@ -11376,6 +11395,7 @@ directory should work if nowhere else does.} \message{and turning on texinfo input format.} \def^^L{\par} % remove \outer, so ^L can appear in an @comment +\catcode`\^^K = 10 % treat vertical tab as whitespace % DEL is a comment character, in case @c does not suffice. \catcode`\^^? = 14 @@ -11599,11 +11619,9 @@ directory should work if nowhere else does.} @setregularquotes @c Local variables: -@c eval: (add-hook 'before-save-hook 'time-stamp) +@c eval: (add-hook 'before-save-hook 'time-stamp nil t) +@c time-stamp-pattern: "texinfoversion{%Y-%02m-%02d.%02H}" @c page-delimiter: "^\\\\message\\|emacs-page" -@c time-stamp-start: "def\\\\texinfoversion{" -@c time-stamp-format: "%:y-%02m-%02d.%02H" -@c time-stamp-end: "}" @c End: @c vim:sw=2: diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 3dc6da6e7d0..0e55b6c1d2a 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -50,13 +50,10 @@ This file documents @w{@value{tramp} @value{trampver}}, a remote file editing package for Emacs. @value{tramp} stands for ``Transparent Remote (file) Access, Multiple -Protocol''. This package provides remote file editing, similar to -Ange FTP@. - -The difference is that Ange FTP uses FTP to transfer files between the -local and the remote host, whereas @value{tramp} uses a combination of -@command{rsh} and @command{rcp} or other work-alike programs, such as -@command{ssh}/@command{scp}. +Protocol''. This package provides an easy, convenient, and consistent +interface to editing remote files transparently, just as if they are +local files. This extends to editing, version control, @code{dired}, +and more. You can find the latest version of this document on the web at @uref{@value{trampurl}}. @@ -133,19 +130,21 @@ Configuring @value{tramp} for use * Multi-hops:: Connecting to a remote host using multiple hops. * Firewalls:: Passing firewalls. * Customizing Methods:: Using Non-Standard Methods. -* Customizing Completion:: Selecting config files for user/host name completion. +* Customizing Completion:: Selecting config files for user/host name @c +completion. * Password handling:: Reusing passwords for several connections. * Connection caching:: Reusing connection related information. * Predefined connection information:: Setting own connection related information. -* Remote programs:: How @value{tramp} finds and uses programs on the remote host. +* Remote programs:: How @value{tramp} finds and uses programs @c +on the remote host. * Remote shell setup:: Remote shell setup hints. +* Ssh setup:: Ssh setup hints. * FUSE setup:: @acronym{FUSE} setup hints. * Android shell setup:: Android shell setup hints. * Auto-save File Lock and Backup:: Auto-save, File Lock and Backup. * Keeping files encrypted:: Protect remote files by encryption. -* Windows setup hints:: Issues with Cygwin ssh. Using @value{tramp} @@ -155,6 +154,7 @@ Using @value{tramp} @end ifset * File name completion:: File name completion. * Ad-hoc multi-hops:: Declaring multiple hops in the file name. +* Home directories:: Expanding @file{~} to home directory. * Remote processes:: Integration with other Emacs packages. * Cleanup remote connections:: Cleanup remote connections. * Renaming remote files:: Renaming remote files. @@ -179,10 +179,10 @@ interface to remote files as if they are local files. @value{tramp}'s transparency extends to editing, version control, and @code{dired}. @value{tramp} can access remote hosts using any number of access -methods, such as @command{rsh}, @command{rlogin}, @command{telnet}, -and related programs. If these programs can successfully pass -@acronym{ASCII} characters, @value{tramp} can use them. -@value{tramp} does not require or mandate 8-bit clean connections. +methods, such as @command{ssh}, @command{scp}, @command{telnet}, and +related programs. If these programs can successfully pass +@acronym{ASCII} characters, @value{tramp} can use them. @value{tramp} +does not require or mandate 8-bit clean connections. @value{tramp}'s most common access method is through @command{ssh}, a more secure alternative to @command{ftp} and other older access @@ -230,10 +230,10 @@ first time connecting to that host, here's what happens: @itemize @item -@value{tramp} invokes @samp{telnet @var{host}} or @samp{rsh @var{host} --l @var{user}} and establishes an external process to connect to the -remote host. @value{tramp} communicates with the process through an -Emacs buffer, which also shows output from the remote host. +@value{tramp} invokes @samp{telnet @var{host}} or @samp{ssh -l +@var{user} @var{host}} and establishes an external process to connect +to the remote host. @value{tramp} communicates with the process +through an Emacs buffer, which also shows output from the remote host. @item The remote host may prompt for a login name (for @command{telnet}, for @@ -243,7 +243,7 @@ followed by a newline. @item The remote host may then prompt for a password or passphrase (for -@command{rsh} or for @command{telnet}). @value{tramp} displays the +@command{ssh} or for @command{telnet}). @value{tramp} displays the password prompt in the minibuffer. @value{tramp} then sends whatever is entered to the remote host, followed by a newline. @@ -309,7 +309,7 @@ I hope this has provided you with a basic overview of what happens behind the scenes when you open a file with @value{tramp}. -@c For the end user +@c For the end user. @node Obtaining @value{tramp} @chapter Obtaining @value{tramp} @cindex obtaining @value{tramp} @@ -523,7 +523,7 @@ performed on another host, it can be comnbined with a leading connects first to the other host with non-administrative credentials, and changes to administrative credentials on that host afterwards. In a simple case, the syntax looks like -@file{@value{prefix}ssh@value{postfixhop}user@@host|sudo@value{postfixhop}@value{postfix}/path/to/file}. +@file{@trampfn{ssh@value{postfixhop}user@@host|sudo,,/path/to/file}}. @xref{Ad-hoc multi-hops}. @@ -688,19 +688,21 @@ to non-@code{nil}, @xref{Directory Variables, , , emacs}. * Multi-hops:: Connecting to a remote host using multiple hops. * Firewalls:: Passing firewalls. * Customizing Methods:: Using Non-Standard Methods. -* Customizing Completion:: Selecting config files for user/host name completion. +* Customizing Completion:: Selecting config files for user/host name @c +completion. * Password handling:: Reusing passwords for several connections. * Connection caching:: Reusing connection related information. * Predefined connection information:: Setting own connection related information. -* Remote programs:: How @value{tramp} finds and uses programs on the remote host. +* Remote programs:: How @value{tramp} finds and uses programs @c +on the remote host. * Remote shell setup:: Remote shell setup hints. +* Ssh setup:: Ssh setup hints. * FUSE setup:: @acronym{FUSE} setup hints. * Android shell setup:: Android shell setup hints. * Auto-save File Lock and Backup:: Auto-save, File Lock and Backup. * Keeping files encrypted:: Protect remote files by encryption. -* Windows setup hints:: Issues with Cygwin ssh. @end menu @@ -1239,7 +1241,8 @@ be populated in your @command{Online Accounts} application outside Emacs. Since Google Drive uses cryptic blob file names internally, @value{tramp} works with the @code{display-name} of the files. This could produce unexpected behavior in case two files in the same -directory have the same @code{display-name}, such a situation must be avoided. +directory have the same @code{display-name}, such a situation must be +avoided. @item @option{mtp} @cindex method @option{mtp} @@ -1453,7 +1456,7 @@ External methods might be more efficient for large files, but most @value{tramp} users edit small files more often than large files. Enable compression, @code{tramp-inline-compress-start-size}, for a -performance boost for large files. +performance boost for large files with inline methods. Since @command{ssh} has become the most common method of remote host access and it has the most reasonable security protocols, use @@ -1479,6 +1482,10 @@ For editing large files, @option{scp} is faster than @option{ssh}. @option{pscp} is faster than @option{plink}. But this speed improvement is not always true. +When copying large files between two different remote hosts via +@option{scp}, set @code{tramp-use-scp-direct-remote-copying} to +non-@code{nil}. + @node Default User @section Selecting a default user @@ -1659,7 +1666,7 @@ local one, first connect via @command{ssh}, and then apply (add-to-list 'tramp-default-proxies-alist '(nil "\\`root\\'" "@trampfn{ssh,%h,}")) (add-to-list 'tramp-default-proxies-alist - '((regexp-quote (system-name)) nil nil)) + `(,(regexp-quote (system-name)) nil nil)) @end group @end lisp @end defopt @@ -1694,8 +1701,8 @@ Sometimes, it is not possible to reach a remote host directly. A firewall might be in the way, which could be passed via a proxy server. -Both ssh and PuTTY support such proxy settings, using an HTTP tunnel -via the @command{CONNECT} command (conforming to RFC 2616, 2817 +Both OpenSSH and PuTTY support such proxy settings, using an HTTP +tunnel via the @command{CONNECT} command (conforming to RFC 2616, 2817 specifications). Proxy servers using HTTP 1.1 or later protocol support this command. @@ -1804,12 +1811,23 @@ Access of a hadoop/hdfs file system. A file is accessed via the user that you want to use, and @samp{node} is the name of the hadoop server. +@item tramp-nspawn +@cindex method @option{nspawn} +@cindex @option{nspawn} method +Access to environments provided by systemd-nspawn. A file is accessed +via @file{@trampfn{nspawn,user@@container,/path/to/file}}, where +@samp{user} is the (optional) user that you want to use, and +@samp{container} is the container to connect to. systemd-nspawn and +its container utilities often require super user access to run, use +multi-hop file names with @option{doas} or @option{sudo} to raise your +privileges. + @item vagrant-tramp @cindex method @option{vagrant} @cindex @option{vagrant} method Convenience method to access vagrant boxes. It is often used in multi-hop file names like -@file{@value{prefix}vagrant@value{postfixhop}box|sudo@value{postfixhop}box@value{postfix}/path/to/file}, +@file{@trampfn{vagrant@value{postfixhop}box|sudo,box,/path/to/file}}, where @samp{box} is the name of the vagrant box. @end table @@ -1865,29 +1883,25 @@ Example: The following predefined functions parsing configuration files exist: -@table @asis +@ftable @asis @item @code{tramp-parse-rhosts} -@findex tramp-parse-rhosts This function parses files which are syntactical equivalent to @file{~/.rhosts}. It returns both host names and user names, if specified. @item @code{tramp-parse-shosts} -@findex tramp-parse-shosts This function parses files which are syntactical equivalent to @file{~/.ssh/known_hosts}. Since there are no user names specified in such files, it can return host names only. @item @code{tramp-parse-sconfig} -@findex tramp-parse-sconfig This function returns the host nicknames defined by @option{Host} entries in @file{~/.ssh/config} style files. @item @code{tramp-parse-shostkeys} -@findex tramp-parse-shostkeys SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and @file{~/ssh2/hostkeys/*}. Hosts are coded in file names @@ -1895,7 +1909,6 @@ SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and are always @code{nil}. @item @code{tramp-parse-sknownhosts} -@findex tramp-parse-sknownhosts Another SSH2 style parsing of directories like @file{/etc/ssh2/knownhosts/*} and @file{~/ssh2/knownhosts/*}. This @@ -1903,26 +1916,22 @@ case, hosts names are coded in file names @file{@var{host-name}.@var{algorithm}.pub}. User names are always @code{nil}. @item @code{tramp-parse-hosts} -@findex tramp-parse-hosts A function dedicated to @file{/etc/hosts} for host names. @item @code{tramp-parse-passwd} -@findex tramp-parse-passwd A function which parses @file{/etc/passwd} for user names. @item @code{tramp-parse-etc-group} -@findex tramp-parse-etc-group A function which parses @file{/etc/group} for group names. @item @code{tramp-parse-netrc} -@findex tramp-parse-netrc A function which parses @file{~/.netrc} and @file{~/.authinfo}-style files. -@end table +@end ftable To keep a custom file with custom data in a custom structure, a custom function has to be provided. This function must meet the following @@ -1982,6 +1991,20 @@ file name syntax, must be appended to the machine and login items: machine melancholia#4711 port davs login daniel%BIZARRE password geheim @end example +For the methods @option{doas}, @option{sudo} and @option{sudoedit} the +password of the user requesting the connection is needed, and not the +password of the target user. If these connections happen on the local +host, an entry with the local user and local host is used: + +@example +machine @var{HOST} port sudo login @var{USER} password secret +@end example + +@var{USER} and @var{HOST} are the strings returned by +@code{(user-login-name)} and @code{(system-name)}. If one of these +methods is connected via a multi hop (@pxref{Multi-hops}), the +credentials of the previous hop are used. + @vindex auth-source-save-behavior If no proper entry exists, the password is read interactively. After successful login (verification of the password), @@ -2147,6 +2170,14 @@ reestablished. A value of @code{nil} disables this feature. Most of the methods do not set this property except the @option{sudo} and @option{doas} methods, which use predefined values. +@item @t{"~"}@* +@t{"~user"} + +This is the home directory on the remote host. Setting this +connection property helps especially for methods which cannot expand +to a remote home directory, like @option{adb}, @option{rclone} and +@option{sshfs}. @ref{Home directories} for an example. + @item @t{"tmpdir"} The temporary directory on the remote host. If not specified, the @@ -2243,8 +2274,7 @@ preserves the path value, which can be used to update shell supports the login argument @samp{-l}. @end defopt -Starting with @w{Emacs 26}, @code{tramp-remote-path} can be set per -host via connection-local +@code{tramp-remote-path} can also be set per host via connection-local @ifinfo variables, @xref{Connection Variables, , , emacs}. @end ifinfo @@ -2612,6 +2642,246 @@ where @samp{192.168.0.1} is the remote host IP address @end table +@node Ssh setup +@section Ssh setup hints + +The most common @value{tramp} connection family is based on either +@command{ssh} or @command{scp} of OpenSSH, or @command{plink} or +@command{pscp} of PuTTY on MS Windows. In the following, some +configuration recommendations are given. + + +@subsection Using ssh config include for host name completion + +@vindex Include@r{, ssh option} +@findex tramp-set-completion-function +@findex tramp-get-completion-function +OpenSSH configuration files can use an @option{Include} option for +further configuration files. Default @value{tramp} host name +completion ignores this option. However, you can configure this +yourself. + +Given, your @file{~/.ssh/config} file contains the following option: + +@example +Include ~/.ssh/conf.d/* +@end example + +The following code snippet in your @file{.emacs} uses all files in +that directory for host name completion: + +@lisp +@group +(tramp-set-completion-function + "ssh" (append (tramp-get-completion-function "ssh") + (mapcar (lambda (file) `(tramp-parse-sconfig ,file)) + (directory-files + "~/.ssh/conf.d/" + 'full directory-files-no-dot-files-regexp)))) +@end group +@end lisp + +This code snippet does it for the @option{ssh} method. If you replace +@t{"ssh"} by @t{"scp"}, it does it also for that method (or any other +method you like). + + +@subsection Detection of session hangouts + +@vindex ServerAliveInterval@r{, ssh option} +@vindex ServerAliveCountMax@r{, ssh option} +@command{ssh} sessions on the local host hang when the network is +down. @value{tramp} cannot safely detect such hangs. OpenSSH can be +configured to kill such hangs with the following settings in +@file{~/.ssh/config}: + +@example +@group +Host * + ServerAliveInterval 5 + ServerAliveCountMax 2 +@end group +@end example + +The corresponding PuTTY configuration is in the @option{Connection} +entry, @option{Seconds between keepalives} option. Set this to 5. +There is no counter which could be set. + + +@subsection Using ssh connection sharing + +@vindex ControlPath@r{, ssh option} +@vindex ControlPersist@r{, ssh option} +@value{tramp} uses the @option{ControlMaster=auto} OpenSSH option by +default, if possible. However, it overwrites @option{ControlPath} +settings when initiating @command{ssh} sessions. @value{tramp} does +this to fend off a stall if a master session opened outside the Emacs +session is no longer open. That is why @value{tramp} prompts for the +password again even if there is an @command{ssh} already open. + +@vindex tramp-ssh-controlmaster-options +Some OpenSSH versions support a @option{ControlPersist} option, which +allows you to set the @option{ControlPath} provided the variable +@code{tramp-ssh-controlmaster-options} is customized as follows: + +@lisp +@group +(customize-set-variable + 'tramp-ssh-controlmaster-options + (concat + "-o ControlPath=/tmp/ssh-ControlPath-%%r@@%%h:%%p " + "-o ControlMaster=auto -o ControlPersist=yes")) +@end group +@end lisp + +Note how @samp{%r}, @samp{%h} and @samp{%p} must be encoded as +@samp{%%r}, @samp{%%h} and @samp{%%p}. + +@vindex tramp-use-ssh-controlmaster-options +If the @file{~/.ssh/config} file is configured appropriately for the +above behavior, then any changes to @command{ssh} can be suppressed +with this @code{nil} setting: + +@lisp +(customize-set-variable 'tramp-use-ssh-controlmaster-options nil) +@end lisp + +@vindex ProxyCommand@r{, ssh option} +@vindex ProxyJump@r{, ssh option} +This should also be set to @code{nil} if you use the +@option{ProxyCommand} or @option{ProxyJump} options in your +@command{ssh} configuration. + +In order to use the @option{ControlMaster} option, @value{tramp} must +check whether the @command{ssh} client supports this option. This is +only possible on the local host, for the first hop. @value{tramp} +does not use this option on proxy hosts, therefore. + +If you want to use this option also for the other hops, you must +configure @file{~/.ssh/config} on the proxy host: + +@example +@group +Host * + ControlMaster auto + ControlPath tramp.%C + ControlPersist no +@end group +@end example + +Check the @samp{ssh_config(5)} man page whether these options are +supported on your proxy host. + +On MS Windows, @code{tramp-use-ssh-controlmaster-options} is set to +@code{nil} by default, because the MS Windows and MSYS2 +implementations of @command{OpenSSH} do not support this option properly. + +In PuTTY, you can achieve connection sharing in the @option{Connection/SSH} +entry, enabling the @option{Share SSH connections if possible} option. + + +@subsection Configure direct copying between two remote servers + +@vindex tramp-use-scp-direct-remote-copying +@value{tramp} uses a temporary local copy when copying two files +between different remote hosts via external methods. This behavior is +due to authentication problems @value{tramp} cannot handle +sufficiently. However, for @option{scp} connections this can be +changed. When a file shall be copied between two different remote +hosts @samp{source} and @samp{target}, and + +@itemize @minus +@item +Variable @code{tramp-use-scp-direct-remote-copying} is non-@code{nil}, + +@item +Remote host @samp{source} doesn't use the @option{RemoteCommand} +option in @file{~/.ssh/config}, + +@item +Remote host @samp{target} shows the same host key when seen from the +local host and from host @samp{source}, and + +@item +@command{scp} running on host @samp{source} can authenticate to host +@samp{target} without requiring a password, +@end itemize + +@noindent +@value{tramp} applies direct remote copying between hosts +@samp{source} and @samp{target} like + +@example +scp -p -T -R -q -r source:/path/to/file target:/path/to/another/file +@end example + +This protects also your local temporary directory from overrun when +copying large files. + +If these conditions do not apply, and +@code{tramp-use-scp-direct-remote-copying} is non-@code{nil}, the +option @samp{-3} is used instead of @samp{-R}. + +@c FIXME +When @value{tramp} uses direct remote copying, password caches are not +consulted. + + +@subsection Issues with Cygwin ssh +@cindex cygwin, issues + +This section is incomplete. Please share your solutions. + +@cindex method @option{sshx} with cygwin +@cindex @option{sshx} method with cygwin + +Cygwin's @command{ssh} works only with a Cygwin version of Emacs. To +check for compatibility: type @kbd{M-x eshell @key{RET}}, and start +@kbd{ssh test.host @key{RET}}. Incompatibilities trigger this +message: + +@example +Pseudo-terminal will not be allocated because stdin is not a terminal. +@end example + +Some older versions of Cygwin's @command{ssh} work with the +@option{sshx} access method. Consult Cygwin's FAQ at +@uref{https://cygwin.com/faq/} for details. + +@cindex cygwin and @command{fakecygpty} +@cindex @command{fakecygpty} and cygwin + +On @uref{https://www.emacswiki.org/emacs/SshWithNTEmacs, the Emacs +Wiki} it is explained how to use the helper program +@command{fakecygpty} to fix this problem. + +@cindex method @option{scpx} with cygwin +@cindex @option{scpx} method with cygwin + +When using the @option{scpx} access method, Emacs may call +@command{scp} with MS Windows file naming, such as @file{c:/foo}. But +the version of @command{scp} that is installed with Cygwin does not +know about MS Windows file naming, which causes it to incorrectly look +for a host named @samp{c}. + +A workaround: write a wrapper script for @option{scp} to convert +Windows file names to Cygwin file names. + +@cindex cygwin and @command{ssh-agent} +@cindex @env{SSH_AUTH_SOCK} and emacs on ms windows +@vindex SSH_AUTH_SOCK@r{, environment variable} + +When using the @command{ssh-agent} on MS Windows for password-less +interaction, @option{ssh} methods depend on the environment variable +@env{SSH_AUTH_SOCK}. But this variable is not set when Emacs is +started from a Desktop shortcut and authentication fails. + +One workaround is to use an MS Windows based SSH Agent, such as +@command{Pageant}. It is part of the PuTTY Suite of tools. + +The fallback is to start Emacs from a shell. + + @node FUSE setup @section @acronym{FUSE} setup hints @@ -2671,6 +2941,7 @@ Additionally, it declares also the arguments for running remote processes, using the @command{ssh} command. These don't need to be changed. + @node Android shell setup @section Android shell setup hints @cindex android shell setup for ssh @@ -2704,14 +2975,31 @@ where @samp{192.168.0.26} is the Android device's IP address. (@pxref{Predefined connection information}). @item -@value{tramp} requires preserving @env{PATH} environment variable from -user settings. Android devices prefer @file{/system/xbin} path over -@file{/system/bin}. Both of these are set as follows: +On the Android device the directory names are prefixed with an +application specific prefix, which is +@file{/data/data/com.termux/files/usr/bin} instead of @file{/usr/bin} +in the @code{Termux} case. You must adapt the file names in +@code{tramp-remote-path}, for example via connection-local +@ifinfo +settings (@pxref{Connection Variables, , , emacs}): +@end ifinfo +@ifnotinfo +settings: +@end ifnotinfo @lisp @group -(add-to-list 'tramp-remote-path 'tramp-own-remote-path) -(add-to-list 'tramp-remote-path "/system/xbin") +(connection-local-set-profile-variables + 'tramp-connection-local-termux-profile + `((tramp-remote-path + . ,(mapcar + (lambda (x) + (if (stringp x) (concat "/data/data/com.termux/files" x) x)) + (copy-tree tramp-remote-path))))) + +(connection-local-set-profiles + '(:application tramp :machine "192.168.0.26") + 'tramp-connection-local-termux-profile) @end group @end lisp @@ -2720,7 +3008,9 @@ When the Android device is not @samp{rooted}, specify a writable directory for temporary files: @lisp -(add-to-list 'tramp-remote-process-environment "TMPDIR=$HOME") +(add-to-list 'tramp-connection-properties + (list (regexp-quote "192.168.0.26") + "tmpdir" "/data/data/com.termux/files/home/tmp")) @end lisp @item @@ -2748,11 +3038,17 @@ the previous example, fix the connection properties as follows: @group (add-to-list 'tramp-connection-properties (list (regexp-quote "android") "remote-shell" "sh")) +(add-to-list 'tramp-connection-properties + (list (regexp-quote "android") + "tmpdir" "/data/data/com.termux/files/home/tmp")) +(connection-local-set-profiles + '(:application tramp :machine "android") + 'tramp-connection-local-termux-profile) @end group @end lisp @noindent -Open a remote connection with a more concise command @kbd{C-x C-f +Open a remote connection with the more concise command @kbd{C-x C-f @trampfn{ssh,android,} @key{RET}}. @end itemize @@ -2834,10 +3130,10 @@ Example: The backup file name of @file{@trampfn{su,root@@localhost,/etc/secretfile}} would be @ifset unified -@file{@trampfn{su,root@@localhost,~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}} +@file{@trampfn{su,root@@localhost,~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}}. @end ifset @ifset separate -@file{@trampfn{su,root@@localhost,~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}} +@file{@trampfn{su,root@@localhost,~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}}. @end ifset @vindex auto-save-file-name-transforms @@ -2855,6 +3151,14 @@ auto-saved files to the same directory as the original file. Alternatively, set the user option @code{tramp-auto-save-directory} to direct all auto saves to that location. +@c Since Emacs 29. +@vindex remote-file-name-inhibit-auto-save-visited +An alternative to @code{auto-save-mode} is +@code{auto-save-visited-mode}. In this mode, auto-saving is identical +to explicit saving. If you want to disable this behavior for remote +files, set user option +@code{remote-file-name-inhibit-auto-save-visited} to non-@code{nil}. + @vindex lock-file-name-transforms And still more issues to handle. Since @w{Emacs 28}, file locks use a similar user option as auto-save files, called @@ -2991,62 +3295,6 @@ subdirectories will remain encrypted. @end deffn -@node Windows setup hints -@section Issues with Cygwin ssh -@cindex cygwin, issues - -This section is incomplete. Please share your solutions. - -@cindex method @option{sshx} with cygwin -@cindex @option{sshx} method with cygwin - -Cygwin's @command{ssh} works only with a Cygwin version of Emacs. To -check for compatibility: type @kbd{M-x eshell @key{RET}}, and start -@kbd{ssh test.host @key{RET}}. Incompatibilities trigger this -message: - -@example -Pseudo-terminal will not be allocated because stdin is not a terminal. -@end example - -Some older versions of Cygwin's @command{ssh} work with the -@option{sshx} access method. Consult Cygwin's FAQ at -@uref{https://cygwin.com/faq/} for details. - -@cindex cygwin and @command{fakecygpty} -@cindex @command{fakecygpty} and cygwin - -On @uref{https://www.emacswiki.org/emacs/SshWithNTEmacs, the Emacs -Wiki} it is explained how to use the helper program -@command{fakecygpty} to fix this problem. - -@cindex method @option{scpx} with cygwin -@cindex @option{scpx} method with cygwin - -When using the @option{scpx} access method, Emacs may call -@command{scp} with MS Windows file naming, such as @file{c:/foo}. But -the version of @command{scp} that is installed with Cygwin does not -know about MS Windows file naming, which causes it to incorrectly look -for a host named @samp{c}. - -A workaround: write a wrapper script for @option{scp} to convert -Windows file names to Cygwin file names. - -@cindex cygwin and @command{ssh-agent} -@cindex @env{SSH_AUTH_SOCK} and emacs on ms windows -@vindex SSH_AUTH_SOCK@r{, environment variable} - -When using the @command{ssh-agent} on MS Windows for password-less -interaction, @option{ssh} methods depend on the environment variable -@env{SSH_AUTH_SOCK}. But this variable is not set when Emacs is -started from a Desktop shortcut and authentication fails. - -One workaround is to use an MS Windows based SSH Agent, such as -Pageant. It is part of the Putty Suite of tools. - -The fallback is to start Emacs from a shell. - - @node Usage @chapter Using @value{tramp} @cindex using @value{tramp} @@ -3075,6 +3323,7 @@ is a feature of Emacs that may cause missed prompts when using @end ifset * File name completion:: File name completion. * Ad-hoc multi-hops:: Declaring multiple hops in the file name. +* Home directories:: Expanding @file{~} to home directory. * Remote processes:: Integration with other Emacs packages. * Cleanup remote connections:: Cleanup remote connections. * Renaming remote files:: Renaming remote files. @@ -3090,6 +3339,7 @@ is a feature of Emacs that may cause missed prompts when using @file{@trampfn{method,host,/path/to/file}} opens file @var{/path/to/file} on the remote host @var{host}, using the method @var{method}. +@c We cannot use @trampfn{} in @item. @table @file @item @value{prefix}ssh@value{postfixhop}melancholia@value{postfix}.emacs For the file @file{.emacs} located in the home directory, on the host @@ -3121,12 +3371,9 @@ brackets @file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}. @end ifset By default, @value{tramp} will use the current local user name as the -remote user name for log in to the remote host. Specifying a different -name using the proper syntax will override this default behavior: - -@example -@trampfn{method,user@@host,path/to/file} -@end example +remote user name for log in to the remote host. Specifying a +different name using the proper syntax will override this default +behavior: @file{@trampfn{method,user@@host,path/to/file}}. @file{@trampfn{ssh,daniel@@melancholia,.emacs}} is for file @file{.emacs} in @code{daniel}'s home directory on the host, @@ -3322,8 +3569,9 @@ remote host name and file name. For example, hopping over a single proxy @samp{bird@@bastion} to a remote file on @samp{you@@remotehost}: @example -@c @kbd{C-x C-f @trampfn{ssh@value{postfixhop}bird@@bastion|ssh,you,remotehost,/path} @key{RET}} -@kbd{C-x C-f @value{prefix}ssh@value{postfixhop}bird@@bastion|ssh@value{postfixhop}you@@remotehost@value{postfix}/path @key{RET}} +@c @kbd{C-x C-f @trampfn{ssh@value{postfixhop}bird@@bastion|ssh,you@@remotehost,/path} @key{RET}} +@kbd{C-x C-f @value{prefix}ssh@value{postfixhop}bird@@bastion|@c +ssh@value{postfixhop}you@@remotehost@value{postfix}/path @key{RET}} @end example Each involved method must be an inline method (@pxref{Inline methods}). @@ -3351,12 +3599,72 @@ Ad-hoc proxies can take patterns @code{%h} or @code{%u} like in @code{tramp-default-proxies-alist}. The following file name expands to user @samp{root} on host @samp{remotehost}, starting with an @option{ssh} session on host @samp{remotehost}: -@samp{@value{prefix}ssh@value{postfixhop}%h|su@value{postfixhop}remotehost@value{postfix}}. +@samp{@trampfn{ssh@value{postfixhop}%h|su,remotehost,}}. -On the other hand, if a trailing hop does not specify a host name, -the host name of the previous hop is reused. Therefore, the following +On the other hand, if a trailing hop does not specify a host name, the +host name of the previous hop is reused. Therefore, the following file name is equivalent to the previous example: -@samp{@value{prefix}ssh@value{postfixhop}remotehost|su@value{postfixhop}@value{postfix}}. +@samp{@trampfn{ssh@value{postfixhop}remotehost|su,,}}. + + +@node Home directories +@section Expanding @file{~} to home directory + +Home directories on remote hosts can be typed as tilde @file{~}. If +possible, they are expanded to the remote user's home directory on the +remote host. Example: + +@example +@group +@trampfn{ssh,user@@host,~} +@result{} @trampfn{ssh,user@@host,/home/user} +@end group +@end example + +This works in general for @option{ssh}-like methods, and for +@option{sudoedit}. These methods allow also the home directory +expansion for another user, like + +@example +@group +@trampfn{sudoedit,,~otheruser} +@result{} @trampfn{sudoedit,root@@localhost,/home/otheruser} +@end group +@end example + +For other methods, a home directory can be expanded only if supported. +This happens for example for the @option{sftp} method. Methods, which +require a share directory in the remote file name (@option{afp}, +@option{smb}), use the value of this share directory as home +directory: + +@example +@group +@trampfn{smb,user@@host,~} +@result{} @trampfn{smb,user@@host,/share} +@end group +@end example + +Since Tramp cannot know in advance which share directory is intended +to use, this expansion can be applied only when a share directory has +been used already. + +The methods @option{adb}, @option{rclone} and @option{sshfs} do not +support home directory expansion at all. However, @value{tramp} keeps +the home directory in the cache. Therefore, those methods could be +configured to expand a home directory via a connection property, +@xref{Predefined connection information}. Example: + +@lisp +@group +(add-to-list 'tramp-connection-properties + (list (regexp-quote "@trampfn{sshfs,user@@randomhost.your.domain,}") + "~user" "/home/user")) +@end group +@end lisp + +When your remote file name does not contain a @samp{user} part, the +connection property @t{"~"} must be used instead. @node Remote processes @@ -3394,9 +3702,9 @@ returns the exit code for it. When the user option indication that the process has been interrupted, and returns a corresponding string. -This remote process handling does not apply to @acronym{GVFS} (see -@ref{GVFS-based methods}) because the remote file system is mounted on -the local host and @value{tramp} accesses it by changing the +This remote process handling does not apply to @acronym{GVFS} +(@pxref{GVFS-based methods}) because the remote file system is mounted +on the local host and @value{tramp} accesses it by changing the @code{default-directory}. @value{tramp} starts a remote process when a command is executed in a @@ -3416,7 +3724,7 @@ might also add their name to this environment variable, like For @value{tramp} to find the command on the remote, it must be accessible through the default search path as setup by @value{tramp} upon first connection. Alternatively, use an absolute path or extend -@code{tramp-remote-path} (see @ref{Remote programs}): +@code{tramp-remote-path} (@pxref{Remote programs}): @lisp @group @@ -3538,9 +3846,8 @@ ensures the correct name of the remote shell program. When @code{explicit-shell-file-name} is equal to @code{nil}, calling @code{shell} interactively will prompt for a shell name. -Starting with @w{Emacs 26}, you could use connection-local variables -for setting different values of @code{explicit-shell-file-name} for -different remote hosts. +You could use connection-local variables for setting different values +of @code{explicit-shell-file-name} for different remote hosts. @ifinfo @xref{Connection Variables, , , emacs}. @end ifinfo @@ -3774,6 +4081,127 @@ using the @code{:connection-type} keyword. If this keyword is not used, the value of @code{process-connection-type} is applied instead. +@subsection Process properties of asynchronous remote processes +@cindex Asynchronous remote processes + +When available, @value{tramp} adds process properties to process +objects of asynchronous properties. However, it is not guaranteed +that all these properties are set. + +@itemize +@item @code{remote-tty} + +This is the name of the terminal a @var{process} uses on the remote +host, i.e., it reads and writes on. + +@item @code{remote-pid} + +The process id of the command executed on the remote host. This is +used when sending signals remotely. + +@item @code{remote-command} + +The remote command which has been invoked via @code{make-process} or +@code{start-file-process}, a list of strings (program and its +arguments). This does not show the additional shell sugar +@value{tramp} makes around the commands, in order to see this you must +inspect @value{tramp} @ref{Traces and Profiles, traces}. +@end itemize + +@findex list-system-processes +@findex process-attributes +The functions @code{list-system-processes} and +@code{process-attributes} return information about system processes on +the respective remote host. In order to retrieve this information, +they use the command @command{ps}, driven by the following constants: + +@defvr Constant tramp-process-attributes-ps-args +This is a list of arguments (strings) @command{ps} is called with. +The default value is appropriate for GNU/Linux remote hosts. +@end defvr + +@defvr Constant tramp-process-attributes-ps-format +This is a list of cons cells @code{(@var{key} . @var{type})} for +interpretation of the @command{ps} output. @var{key} is a key used in +the @code{process-attributes} output plus the key @code{pid}, and +@var{type} is the respective value returned by @command{ps}. It can +be + + +@multitable {@bullet{} @code{numberp}} {--- a string of @var{number} width, could contain spaces} +@item @bullet{} @code{numberp} @tab --- a number +@item @bullet{} @code{stringp} @tab --- a string without spaces +@item @bullet{} @var{number} +@tab --- a string of @var{number} width, could contain spaces +@item @bullet{} @code{nil} @tab --- a string until end of line +@end multitable + +The default value is appropriate for GNU/Linux remote hosts. +@end defvr + +If, for example, @code{tramp-process-attributes-ps-args} is declared +as @code{("-eww" "-o" "pid,euid,euser,egid,egroup,comm:40,state")}, +the output of the respective @command{ps} command would look like + +@smallexample +@group + PID EUID EUSER EGID EGROUP COMMAND S + 1 0 root 0 root systemd S + 1610 0 root 0 root NFSv4 callback S + @dots{} +@end group +@end smallexample + +The corresponding @code{tramp-process-attributes-ps-format} has the value + +@smallexample +@group +@code{((pid . numberp) (euid . numberp) (user . stringp) + (egid . numberp) (group . stringp) (comm . 40) (state . stringp))} +@end group +@end smallexample + +@vindex tramp-adb-connection-local-default-ps-profile +@vindex tramp-adb-connection-local-default-ps-variables +@vindex tramp-connection-local-bsd-ps-profile +@vindex tramp-connection-local-bsd-ps-variables +@vindex tramp-connection-local-busybox-ps-profile +@vindex tramp-connection-local-busybox-ps-variables +@vindex tramp-connection-local-darwin-ps-profile +@vindex tramp-connection-local-darwin-ps-variables +The default values for @code{tramp-process-attributes-ps-args} and +@code{tramp-process-attributes-ps-format} can be overwritten by +connection-local variables. +@ifinfo +@xref{Connection Variables, , , emacs}. +@end ifinfo +This is already done by @value{tramp} for the @option{adb} method, see +@code{tramp-adb-connection-local-default-ps-profile} and +@code{tramp-adb-connection-local-default-ps-variables}. + +There are three further predefined sets of connection-local variables +for remote BSD systems, for remote macOS systems, and for a remote +@command{ps} command implemented with @command{busybox}. These are +called @code{tramp-connection-local-*-ps-profile} and +@code{tramp-connection-local-*-ps-variables}. Use them like + +@lisp +@group +(connection-local-set-profiles + '(:application tramp :machine "mybsdhost") + 'tramp-connection-local-bsd-ps-profile) +@end group +@end lisp + +@cindex proced +@vindex proced-show-remote-processes +If you want to see a listing of remote system processes when calling +@code{proced}, set user option @code{proced-show-remote-processes} to +non-@code{nil}, or invoke that command with a negative argument like +@kbd{C-u - M-x proced @key{RET}} when your buffer has a remote +@code{default-directory}. + + @anchor{Improving performance of asynchronous remote processes} @subsection Improving performance of asynchronous remote processes @cindex Asynchronous remote processes @@ -3811,8 +4239,8 @@ Furthermore, this approach has the following limitations: @itemize @item -It works only for connection methods defined in @file{tramp-sh.el} and -@file{tramp-adb.el}. +It works only for connection methods defined in @file{tramp-adb.el}, +@file{tramp-sh.el} and @file{tramp-sshfs.el}. @item It does not support interactive user authentication. With @@ -3978,7 +4406,9 @@ would trigger renaming of buffer file names on @samp{badhost} to @samp{goodhost}, including changing the directory name. @lisp -("@trampfn{ssh,.+\\\\.company\\\\.org,}" . "@value{prefix}ssh@value{postfixhop}multi.hop|ssh@value{postfixhop}%h@value{postfix}") +("@trampfn{ssh,.+\\\\.company\\\\.org,}" @c +. "@value{prefix}ssh@value{postfixhop}multi.hop|@c +ssh@value{postfixhop}%h@value{postfix}") @end lisp routes all connections to a host in @samp{company.org} via @@ -4068,6 +4498,11 @@ CPIO archives @cindex @file{cpio} file archive suffix @cindex file archive suffix @file{cpio} +@item @samp{.crate} --- +Cargo (Rust) packages +@cindex @file{crate} file archive suffix +@cindex file archive suffix @file{crate} + @item @samp{.deb} --- Debian packages @cindex @file{deb} file archive suffix @@ -4078,6 +4513,11 @@ HP-UX SD depots @cindex @file{depot} file archive suffix @cindex file archive suffix @file{depot} +@item @samp{.epub} --- +Electronic publications +@cindex @file{epub} file archive suffix +@cindex file archive suffix @file{epub} + @item @samp{.exe} --- Self extracting Microsoft Windows EXE files @cindex @file{exe} file archive suffix @@ -4235,7 +4675,8 @@ It is even possible to access file archives in file archives, as (progn (url-handler-mode 1) (find-file - "https://ftp.debian.org/debian/pool/main/c/coreutils/coreutils_8.28-1_amd64.deb/control.tar.gz/control")) + "https://ftp.debian.org/debian/pool/main/c/coreutils/\ +coreutils_8.28-1_amd64.deb/control.tar.gz/control")) @end group @end lisp @@ -4368,8 +4809,8 @@ Where is the latest @value{tramp}? @item Which systems does it work on? -The package works successfully on @w{Emacs 25}, @w{Emacs 26}, @w{Emacs -27}, and @w{Emacs 28}. +The package works successfully on @w{Emacs 26}, @w{Emacs 27}, @w{Emacs +28}, and @w{Emacs 29}. While Unix and Unix-like systems are the primary remote targets, @value{tramp} has equal success connecting to other platforms, such as @@ -4385,9 +4826,12 @@ authentication delays. During these operations, @value{tramp}'s responsiveness slows down. Some suggestions within the scope of @value{tramp}'s settings include: +@itemize @minus +@item Use an external method, such as @option{scp}, which are faster than -internal methods. +internal methods for large files. +@item Keep the file @code{tramp-persistency-file-name}, which is where @value{tramp} caches remote information about hosts and files. Caching is enabled by default. Don't disable it. @@ -4398,6 +4842,7 @@ files are not independently updated outside @value{tramp}'s control. That cache cleanup will be necessary if the remote directories or files are updated independent of @value{tramp}. +@item Disable version control to avoid delays: @lisp @@ -4417,9 +4862,17 @@ about, for example: (setq vc-handled-backends '(SVN Git)) @end lisp +@item +@vindex remote-file-name-inhibit-locks +Disable file locks. Set @code{remote-file-name-inhibit-locks} to +@code{t} if you know that different Emacs sessions are not modifying +the same remote file. + +@item Disable excessive traces. Set @code{tramp-verbose} to 3 or lower, default being 3. Increase trace levels temporarily when hunting for bugs. +@end itemize @item @@ -4556,97 +5009,6 @@ In order to disable those optimizations, set user option @item -@value{tramp} does not recognize if a @command{ssh} session hangs - -@vindex ServerAliveInterval@r{, ssh option} -@command{ssh} sessions on the local host hang when the network is -down. @value{tramp} cannot safely detect such hangs. The network -configuration for @command{ssh} can be configured to kill such hangs -with the following command in the @file{~/.ssh/config}: - -@example -@group -Host * - ServerAliveInterval 5 -@end group -@end example - - -@item -@value{tramp} does not use default @command{ssh} @option{ControlPath} - -@vindex ControlPath@r{, ssh option} -@vindex ControlPersist@r{, ssh option} -@value{tramp} overwrites @option{ControlPath} settings when initiating -@command{ssh} sessions. @value{tramp} does this to fend off a stall -if a master session opened outside the Emacs session is no longer -open. That is why @value{tramp} prompts for the password again even -if there is an @command{ssh} already open. - -@vindex tramp-ssh-controlmaster-options -Some @command{ssh} versions support a @option{ControlPersist} option, -which allows you to set the @option{ControlPath} provided the variable -@code{tramp-ssh-controlmaster-options} is customized as follows: - -@lisp -@group -(customize-set-variable - 'tramp-ssh-controlmaster-options - (concat - "-o ControlPath=/tmp/ssh-ControlPath-%%r@@%%h:%%p " - "-o ControlMaster=auto -o ControlPersist=yes")) -@end group -@end lisp - -Note how @samp{%r}, @samp{%h} and @samp{%p} must be encoded as -@samp{%%r}, @samp{%%h} and @samp{%%p}. - -@vindex tramp-use-ssh-controlmaster-options -If the @file{~/.ssh/config} file is configured appropriately for the -above behavior, then any changes to @command{ssh} can be suppressed -with this @code{nil} setting: - -@lisp -(customize-set-variable 'tramp-use-ssh-controlmaster-options nil) -@end lisp - -@vindex ProxyCommand@r{, ssh option} -@vindex ProxyJump@r{, ssh option} -This should also be set to @code{nil} if you use the -@option{ProxyCommand} or @option{ProxyJump} options in your -@command{ssh} configuration. - -On MS Windows, @code{tramp-use-ssh-controlmaster-options} is set to -@code{nil} by default, because the MS Windows and MSYS2 -implementations of @command{OpenSSH} do not support this option properly. - - -@item -On multi-hop connections, @value{tramp} does not use @command{ssh} -@option{ControlMaster} - -In order to use the @option{ControlMaster} option, @value{tramp} must -check whether the @command{ssh} client supports this option. This is -only possible on the local host, for the first hop. @value{tramp} -does not use this option on proxy hosts. - -If you want to use this option also for the other hops, you must -configure @file{~/.ssh/config} on the proxy host: - -@example -@group -Host * - ControlMaster auto - ControlPath tramp.%C - ControlPersist no -@end group -@end example - -Check the @samp{ssh_config(5)} man page whether these options are -supported on your proxy host. - - -@item Does @value{tramp} support @acronym{SSH} security keys? Yes. @command{OpenSSH} has added support for @acronym{FIDO} hardware @@ -4839,6 +5201,26 @@ be restored by moving them manually from @item +How to identify temporary files produced by @value{tramp}? + +@vindex tramp-temp-name-prefix +Temporary files are kept in your @code{temporary-file-directory} +directory, which is often @file{/tmp/}. By default, they have the +file name prefix @t{"tramp."}. If you want to change this prefix, for +example because you want to identify temporary files produced by +@code{file-local-copy} in your package, you can bind the variable +@code{tramp-temp-name-prefix} temporarily: + +@example +@group +(let ((tramp-temp-name-prefix "my-prefix.")) + (file-local-copy "@trampfn{ssh,,.emacs}")) +@result{} "/tmp/my-prefix.HDfgDZ" +@end group +@end example + + +@item How to shorten long file names when typing in @value{tramp}? Adapt several of these approaches to reduce typing. If the full name @@ -5086,7 +5468,8 @@ Why saved multi-hop file names do not work in a new Emacs session? When saving ad-hoc multi-hop @value{tramp} file names (@pxref{Ad-hoc multi-hops}) via bookmarks, recent files, filecache, bbdb, or another package, use the full ad-hoc file name including all hops, like -@file{@trampfn{ssh,bird@@bastion|ssh@value{postfixhop}news.my.domain,/opt/news/etc}}. +@file{@trampfn{ssh,bird@@bastion|ssh@value{postfixhop}@c +news.my.domain,/opt/news/etc}}. Alternatively, when saving abbreviated multi-hop file names @file{@trampfn{ssh,news@@news.my.domain,/opt/news/etc}}, the user @@ -5239,6 +5622,28 @@ time being you can suppress this error by the following code in your @item +I get an error @samp{Remote file error: Not a valid Tramp file name +function `tramp-FOO-file-name-p'} + +@value{tramp} has changed the signature of an internal function. +External packages implementing an own @value{tramp} backend must +follow this change. Please report this problem to the author of that +package. + +For the running session, @value{tramp} disables the external package, +and you can continue to work. If you don't want to see this error +while activating @value{tramp}, you can suppress it by the same code +as above in your @file{~/.emacs}: + +@lisp +@group +(setq debug-ignored-errors + (cons 'remote-file-error debug-ignored-errors)) +@end group +@end lisp + + +@item How to disable other packages from calling @value{tramp}? There are packages that call @value{tramp} without the user ever @@ -5256,6 +5661,7 @@ Disable @value{tramp} file name completion: (customize-set-variable 'ido-enable-tramp-completion nil) @end lisp +@c Obsolete since Emacs 29.1. @item @file{rlogin.el} @@ -5314,10 +5720,19 @@ local host's root directory as @file{/ssh:example.com:}. To unload @value{tramp}, type @kbd{M-x tramp-unload-tramp @key{RET}}. Unloading @value{tramp} resets Ange FTP plugins also. @end itemize + + +@item +What is the difference between Ange FTP and @value{tramp}? + +The difference is that Ange FTP uses @command{ftp} to transfer files +between the local and the remote host, whereas @value{tramp} uses a +combination of @command{ssh} and @command{scp} or other work-alike +programs. @end itemize -@c For the developer +@c For the developer. @node Files directories and localnames @chapter How file names, directories and localnames are mangled and managed @@ -5373,7 +5788,7 @@ bind it to non-@code{nil} value. Keeping a local cache of remote file attributes in sync with the remote host is a time-consuming operation. Flushing and re-querying these attributes can tax @value{tramp} to a grinding halt on busy -remote servers. +remote hosts. To get around these types of slow-downs in @value{tramp}'s responsiveness, set the @code{process-file-side-effects} to @code{nil} @@ -5528,6 +5943,8 @@ function call traces are written to the buffer @file{*trace-output*}. @c @c * Say something about the .login and .profile files of the remote @c shells. +@c @c * Explain how tramp.el works in principle: open a shell on a remote @c host and then send commands to it. +@c @c * Consistent small or capitalized words especially in menus. diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index 8352fed1b70..9e1be52cd38 100644 --- a/doc/misc/trampver.texi +++ b/doc/misc/trampver.texi @@ -8,10 +8,10 @@ @c In the Tramp GIT, the version numbers are auto-frobbed from @c tramp.el, and the bug report address is auto-frobbed from @c configure.ac. -@set trampver 2.5.3.28.2 +@set trampver 2.6.0-pre @set trampurl https://www.gnu.org/software/tramp/ @set tramp-bug-report-address tramp-devel@@gnu.org -@set emacsver 25.1 +@set emacsver 26.1 @c Other flags from configuration. @set instprefix /usr/local diff --git a/doc/misc/transient.texi b/doc/misc/transient.texi index d634ad5197a..24c3090ef7a 100644 --- a/doc/misc/transient.texi +++ b/doc/misc/transient.texi @@ -47,9 +47,9 @@ General Public License for more details. Taking inspiration from prefix keys and prefix arguments, Transient implements a similar abstraction involving a prefix command, infix arguments and suffix commands. We could call this abstraction a -``transient command'', but because it always involves at least two +“transient command”, but because it always involves at least two commands (a prefix and a suffix) we prefer to call it just a -``transient''. +“transient”. When the user calls a transient prefix command, a transient (temporary) keymap is activated, which binds the transient's infix @@ -97,7 +97,7 @@ Usage * Getting Help for Suffix Commands:: * Enabling and Disabling Suffixes:: * Other Commands:: -* Other Options:: +* Configuration:: Defining New Commands @@ -144,20 +144,20 @@ Related Abstractions and Packages Taking inspiration from prefix keys and prefix arguments, Transient implements a similar abstraction involving a prefix command, infix arguments and suffix commands. We could call this abstraction a -``transient command'', but because it always involves at least two +“transient command”, but because it always involves at least two commands (a prefix and a suffix) we prefer to call it just a -``transient''. +“transient”. +@cindex transient prefix command @quotation Transient keymaps are a feature provided by Emacs. Transients as implemented by this package involve the use of transient keymaps. -@cindex transient prefix command Emacs provides a feature that it calls @dfn{prefix commands}. When we -talk about ``prefix commands'' in this manual, then we mean our own kind -of ``prefix commands'', unless specified otherwise. To avoid ambiguity +talk about “prefix commands” in this manual, then we mean our own kind +of “prefix commands”, unless specified otherwise. To avoid ambiguity we sometimes use the terms @dfn{transient prefix command} for our kind and -``regular prefix command'' for the Emacs' kind. +“regular prefix command” for Emacs' kind. @end quotation @@ -208,7 +208,7 @@ looks a bit like this: @quotation This is a simplified version of @code{magit-tag}. Info manuals do not -support images or colored text, so the above ``screenshot'' lacks some +support images or colored text, so the above “screenshot” lacks some information; in practice you would be able to tell whether the arguments @code{--force} and @code{--annotate} are enabled or not based on their color. @@ -216,11 +216,11 @@ color. @end quotation @cindex command dispatchers -Transient can be used to implement simple ``command dispatchers''. The +Transient can be used to implement simple “command dispatchers”. The main benefit then is that the user can see all the available commands in a popup buffer. That is useful by itself because it frees the user from having to remember all the keys that are valid after a certain -prefix key or command. Magit's @code{magit-dispatch} (on @code{C-x M-g}) command is +prefix key or command. Magit's @code{magit-dispatch} (on @kbd{C-x M-g}) command is an example of using Transient to merely implement a command dispatcher. @@ -235,22 +235,22 @@ argument means to a certain command. Transient suffix commands, on the other hand, can accept dozens of different arguments without the user having to remember anything. -When using Transient, one can call a command with arguments that -are just as complex as when calling the same function non-interactively +When using Transient, one can call a command with arguments that are +just as complex as when calling the same function non-interactively from Lisp. Invoking a transient command with arguments is similar to invoking a command in a shell with command-line completion and history enabled. One benefit of the Transient interface is that it remembers history -not only on a global level (``this command was invoked using these -arguments, and previously it was invoked using those other arguments''), +not only on a global level (“this command was invoked using these +arguments, and previously it was invoked using those other arguments”), but also remembers the values of individual arguments independently. @xref{Using History}. -After a transient prefix command is invoked, @kbd{C-h @var{key}} can be used to -show the documentation for the infix or suffix command that @kbd{@var{key}} is +After a transient prefix command is invoked, @kbd{C-h @var{KEY}} can be used to +show the documentation for the infix or suffix command that @kbd{@var{KEY}} is bound to (@pxref{Getting Help for Suffix Commands}), and infixes and -suffixes can be removed from the transient using @kbd{C-x l @var{key}}. Infixes +suffixes can be removed from the transient using @kbd{C-x l @var{KEY}}. Infixes and suffixes that are disabled by default can be enabled the same way. @xref{Enabling and Disabling Suffixes}. @@ -273,11 +273,12 @@ to implementing yet). * Getting Help for Suffix Commands:: * Enabling and Disabling Suffixes:: * Other Commands:: -* Other Options:: +* Configuration:: @end menu @node Invoking Transients @section Invoking Transients + @cindex invoking transients A transient prefix command is invoked like any other command by @@ -290,9 +291,9 @@ disabled while the transient state is in effect. There are two kinds of commands that are available after invoking a transient prefix command; infix and suffix commands. Infix commands set some value (which is then shown in a popup buffer), without -leaving the transient. Suffix commands, on the other hand, usually quit -the transient and they may use the values set by the infix commands, -i.e.@: the infix @strong{arguments}. +leaving the transient. Suffix commands, on the other hand, usually +quit the transient and they may use the values set by the infix +commands, i.e., the infix @strong{arguments}. Instead of setting arguments to be used by a suffix command, infix commands may also set some value by side-effect, e.g., by setting the @@ -300,11 +301,12 @@ value of some variable. @node Aborting and Resuming Transients @section Aborting and Resuming Transients + @cindex aborting transients @cindex resuming transients @cindex quit transient -To quit the transient without invoking a suffix command press @code{C-g}. +To quit the transient without invoking a suffix command press @kbd{C-g}. Key bindings in transient keymaps may be longer than a single event. After pressing a valid prefix key, all commands whose bindings do not @@ -314,7 +316,7 @@ prefix key, but not the complete transient). A transient prefix command can be bound as a suffix of another transient. Invoking such a suffix replaces the current transient -state with a new transient state, i.e.@: the available bindings change +state with a new transient state, i.e., the available bindings change and the information displayed in the popup buffer is updated accordingly. Pressing @kbd{C-g} while a nested transient is active only quits the innermost transient, causing a return to the previous @@ -325,13 +327,12 @@ the latter, then you can later resume the stack of transients using @kbd{M-x transient-resume}. @table @asis +@item @kbd{C-g} (@code{transient-quit-seq}) +@itemx @kbd{C-g} (@code{transient-quit-one}) @kindex C-g -@findex transient-quit-seq -@item @kbd{C-g} @tie{}@tie{}@tie{}@tie{}(@code{transient-quit-seq}) @kindex C-g +@findex transient-quit-seq @findex transient-quit-one -@item @kbd{C-g} @tie{}@tie{}@tie{}@tie{}(@code{transient-quit-one}) - This key quits the currently active incomplete key sequence, if any, or else the current transient. When quitting the current transient, it returns to the previous transient, if any. @@ -342,22 +343,20 @@ To learn how to get that binding back see @code{transient-bind-q-to-quit}'s doc string. @table @asis +@item @kbd{C-q} (@code{transient-quit-all}) @kindex C-q @findex transient-quit-all -@item @kbd{C-q} @tie{}@tie{}@tie{}@tie{}(@code{transient-quit-all}) - This command quits the currently active incomplete key sequence, if any, and all transients, including the active transient and all suspended transients, if any. +@item @kbd{C-z} (@code{transient-suspend}) @kindex C-z @findex transient-suspend -@item @kbd{C-z} @tie{}@tie{}@tie{}@tie{}(@code{transient-suspend}) - Like @code{transient-quit-all}, this command quits an incomplete key sequence, if any, and all transients. Additionally, it saves the stack of transients so that it can easily be resumed (which is -particularly useful if you quickly need to do ``something else'', and +particularly useful if you quickly need to do “something else” and the stack is deeper than a single transient, and/or you have already changed the values of some infix arguments). @@ -365,43 +364,39 @@ Note that only a single stack of transients can be saved at a time. If another stack is already saved, then saving a new stack discards the previous stack. -@kindex M-x transient-resume +@item @kbd{M-x transient-resume} @findex transient-resume -@item @kbd{M-x transient-resume} @tie{}@tie{}@tie{}@tie{}(@code{transient-resume}) - This command resumes the previously suspended stack of transients, if any. @end table @node Common Suffix Commands @section Common Suffix Commands + @cindex common suffix commands A few shared suffix commands are available in all transients. These suffix commands are not shown in the popup buffer by default. -This includes the aborting commands mentioned in the previous section, as -well as some other commands that are all bound to @kbd{C-x @var{key}}. After +This includes the aborting commands mentioned in the previous section, +as well as some other commands that are all bound to @kbd{C-x @var{KEY}}. After @kbd{C-x} is pressed, a section featuring all these common commands is temporarily shown in the popup buffer. After invoking one of them, -the section disappears again. Note, however, that one of these commands -is described as ``Show common permanently''; invoke that if you want the -common commands to always be shown for all transients. +the section disappears again. Note, however, that one of these +commands is described as “Show common permanently”; invoke that if you +want the common commands to always be shown for all transients. @table @asis +@item @kbd{C-x t} (@code{transient-toggle-common}) @kindex C-x t @findex transient-toggle-common -@item @kbd{C-x t} @tie{}@tie{}@tie{}@tie{}(@code{transient-toggle-common}) - This command toggles whether the generic commands that are common to all transients are always displayed or only after typing the incomplete prefix key sequence @kbd{C-x}. This only affects the current Emacs session. - @end table @defopt transient-show-common-commands - This option controls whether shared suffix commands are shown alongside the transient-specific infix and suffix commands. By default, the shared commands are not shown to avoid overwhelming @@ -412,14 +407,15 @@ commands. The value of this option can be changed for the current Emacs session by typing @kbd{C-x t} while a transient is active. @end defopt -The other common commands are described in either the previous or -in one of the following sections. +The other common commands are described in either the previous or in +one of the following sections. Some of Transient's key bindings differ from the respective bindings of Magit-Popup; see @ref{FAQ} for more information. @node Saving Values @section Saving Values + @cindex saving values of arguments After setting the infix arguments in a transient, the user can save @@ -429,8 +425,7 @@ Most transients will start out with the saved arguments when they are invoked. There are a few exceptions, though. Some transients are designed so that the value that they use is stored externally as the buffer-local value of some variable. Invoking such a transient again -uses the buffer-local value.@footnote{ -@code{magit-diff} and @code{magit-log} are two prominent examples, and their +uses the buffer-local value. @footnote{@code{magit-diff} and @code{magit-log} are two prominent examples, and their handling of buffer-local values is actually a bit more complicated than outlined above and even customizable.} @@ -440,30 +435,32 @@ history. That value won't be used when the transient is next invoked, but it is easily accessible (@pxref{Using History}). @table @asis +@item @kbd{C-x s} (@code{transient-set}) @kindex C-x s @findex transient-set -@item @kbd{C-x s} @tie{}@tie{}@tie{}@tie{}(@code{transient-set}) - This command saves the value of the active transient for this Emacs session. +@item @kbd{C-x C-s} (@code{transient-save}) @kindex C-x C-s @findex transient-save -@item @kbd{C-x C-s} @tie{}@tie{}@tie{}@tie{}(@code{transient-save}) - Save the value of the active transient persistently across Emacs sessions. +@item @kbd{C-x C-k} (@code{transient-save}) +@kindex C-x C-k +@findex transient-save +Clear the set and saved value of the active transient. @end table @defopt transient-values-file - This option names the file that is used to persist the values of transients between Emacs sessions. @end defopt @node Using History @section Using History + @cindex value history Every time the user invokes a suffix command the transient's current @@ -472,32 +469,28 @@ same way one can cycle through the history of commands that read user-input in the minibuffer. @table @asis +@item @kbd{C-M-p} (@code{transient-history-prev}) +@itemx @kbd{C-x p} @kindex C-M-p -@findex transient-history-prev -@item @kbd{C-M-p} @tie{}@tie{}@tie{}@tie{}(@code{transient-history-prev}) @kindex C-x p @findex transient-history-prev -@item @kbd{C-x p} @tie{}@tie{}@tie{}@tie{}(@code{transient-history-prev}) - This command switches to the previous value used for the active transient. +@item @kbd{C-M-n} (@code{transient-history-next}) +@itemx @kbd{C-x n} @kindex C-M-n -@findex transient-history-next -@item @kbd{C-M-n} @tie{}@tie{}@tie{}@tie{}(@code{transient-history-next}) @kindex C-x n @findex transient-history-next -@item @kbd{C-x n} @tie{}@tie{}@tie{}@tie{}(@code{transient-history-next}) - This command switches to the next value used for the active transient. @end table In addition to the transient-wide history, Transient of course supports per-infix history. When an infix reads user-input using the -minibuffer, the user can use the regular minibuffer history -commands to cycle through previously used values. Usually the same -keys as those mentioned above are bound to those commands. +minibuffer, the user can use the regular minibuffer history commands +to cycle through previously used values. Usually the same keys as +those mentioned above are bound to those commands. Authors of transients should arrange for different infix commands that read the same kind of value to also use the same history key @@ -506,19 +499,18 @@ read the same kind of value to also use the same history key Both kinds of history are saved to a file when Emacs is exited. @defopt transient-history-file - This option names the file that is used to persist the history of transients and their infixes between Emacs sessions. @end defopt @defopt transient-history-limit - This option controls how many history elements are kept at the time the history is saved in @code{transient-history-file}. @end defopt @node Getting Help for Suffix Commands @section Getting Help for Suffix Commands + @cindex getting help Transients can have many suffixes and infixes that the user might not @@ -527,14 +519,13 @@ provides access to the documentation directly from the active transient. @table @asis +@item @kbd{C-h} (@code{transient-help}) @kindex C-h @findex transient-help -@item @kbd{C-h} @tie{}@tie{}@tie{}@tie{}(@code{transient-help}) - -This command enters help mode. When help mode is active, -typing a key shows information about the suffix command that the key -is normally bound to (instead of invoking it). Pressing @kbd{C-h} a -second time shows information about the @emph{prefix} command. +This command enters help mode. When help mode is active, typing a +key shows information about the suffix command that the key normally +is bound to (instead of invoking it). Pressing @kbd{C-h} a second time +shows information about the @emph{prefix} command. After typing a key, the stack of transient states is suspended and information about the suffix command is shown instead. Typing @kbd{q} in @@ -550,6 +541,7 @@ non-infix suffixes this is usually appropriate. @node Enabling and Disabling Suffixes @section Enabling and Disabling Suffixes + @cindex enabling suffixes @cindex disabling suffixes @@ -571,7 +563,7 @@ displayed at any level. The levels of individual transients and/or their individual suffixes can be changed interactively, by invoking the transient and then -pressing @kbd{C-x l} to enter the ``edit'' mode, see below. +pressing @kbd{C-x l} to enter the “edit” mode, see below. The default level for both transients and their suffixes is 4. The @code{transient-default-level} option only controls the default for @@ -582,23 +574,20 @@ very important suffixes on a lower level, so that they remain available even if the user lowers the transient level. @defopt transient-default-level - This option controls which suffix levels are made available by default. It sets the transient-level for transients for which the user has not set that individually. @end defopt @defopt transient-levels-file - This option names the file that is used to persist the levels of transients and their suffixes between Emacs sessions. @end defopt @table @asis +@item @kbd{C-x l} (@code{transient-set-level}) @kindex C-x l @findex transient-set-level -@item @kbd{C-x l} @tie{}@tie{}@tie{}@tie{}(@code{transient-set-level}) - This command enters edit mode. When edit mode is active, then all infixes and suffixes that are currently usable are displayed along with their levels. The colors of the levels indicate whether they @@ -616,9 +605,9 @@ To change the transient level press @kbd{C-x l} again. To exit edit mode press @kbd{C-g}. Note that edit mode does not display any suffixes that are not -currently usable. @code{magit-rebase}, for example, shows different suffixes -depending on whether a rebase is already in progress or not. The -predicates also apply in edit mode. +currently usable. @code{magit-rebase}, for example, shows different +suffixes depending on whether a rebase is already in progress or +not. The predicates also apply in edit mode. Therefore, to control which suffixes are available given a certain state, you have to make sure that that state is currently active. @@ -633,27 +622,29 @@ following commands. These commands are never shown in the transient window, and the key bindings are the same as for @code{scroll-up-command} and @code{scroll-down-command} in other buffers. -@findex transient-scroll-up arg @deffn Command transient-scroll-up arg - -This command scrolls text of transient popup window upward @var{arg} -lines. If @var{arg} is @code{nil}, then it scrolls near full screen. This +This command scrolls text of transient popup window upward @var{ARG} +lines. If @var{ARG} is @code{nil}, then it scrolls near full screen. This is a wrapper around @code{scroll-up-command} (which see). @end deffn -@findex transient-scroll-down arg @deffn Command transient-scroll-down arg - -This command scrolls text of transient popup window down @var{arg} -lines. If @var{arg} is @code{nil}, then it scrolls near full screen. This +This command scrolls text of transient popup window down @var{ARG} +lines. If @var{ARG} is @code{nil}, then it scrolls near full screen. This is a wrapper around @code{scroll-down-command} (which see). @end deffn -@node Other Options -@section Other Options +@node Configuration +@section Configuration -@defopt transient-show-popup +More options are described in @ref{Common Suffix Commands}, in @ref{Saving Values}, in @ref{Using History} and in @ref{Enabling and Disabling Suffixes}. + +@anchor{Essential Options} +@subheading Essential Options + +Also see @ref{Common Suffix Commands}. +@defopt transient-show-popup This option controls whether the current transient's infix and suffix commands are shown in the popup buffer. @@ -662,13 +653,11 @@ suffix commands are shown in the popup buffer. If @code{t} (the default) then the popup buffer is shown as soon as a transient prefix command is invoked. - @item If @code{nil}, then the popup buffer is not shown unless the user explicitly requests it, by pressing an incomplete prefix key sequence. - @item If a number, then the a brief one-line summary is shown instead of the popup buffer. If zero or negative, then not even that summary @@ -676,45 +665,43 @@ is shown; only the pressed key itself is shown. The popup is shown when the user explicitly requests it by pressing an incomplete prefix key sequence. Unless this is zero, -the popup is shown after that many seconds of inactivity -(using the absolute value). +the popup is shown after that many seconds of inactivity (using +the absolute value). @end itemize @end defopt @defopt transient-enable-popup-navigation - This option controls whether navigation commands are enabled in the transient popup buffer. While a transient is active the transient popup buffer is not the current buffer, making it necessary to use dedicated commands to act on that buffer itself. This is disabled by default. If this option -is non-nil, then the following features are available: +is non-@code{nil}, then the following features are available: @itemize @item -@key{UP} moves the cursor to the previous suffix. -@key{DOWN} moves the cursor to the next suffix. -@key{RET} invokes the suffix the cursor is on. - +@kbd{@key{UP}} moves the cursor to the previous suffix. @item -@key{mouse-1} invokes the clicked on suffix. - +@kbd{@key{DOWN}} moves the cursor to the next suffix. +@item +@kbd{@key{RET}} invokes the suffix the cursor is on. +@item +@kbd{mouse-1} invokes the clicked on suffix. @item @kbd{C-s} and @kbd{C-r} start isearch in the popup buffer. @end itemize @end defopt @defopt transient-display-buffer-action - This option specifies the action used to display the transient popup buffer. The transient popup buffer is displayed in a window using -@code{(display-buffer @var{buffer} transient-display-buffer-action)}. +@code{(display-buffer @var{BUFFER} transient-display-buffer-action)}. -The value of this option has the form @code{(@var{function} . @var{alist})}, -where @var{function} is a function or a list of functions. Each such +The value of this option has the form @code{(@var{FUNCTION} . @var{ALIST})}, +where @var{FUNCTION} is a function or a list of functions. Each such function should accept two arguments: a buffer to display and an -alist of the same form as @var{alist}. @xref{Choosing Window,,,elisp,}, +alist of the same form as @var{ALIST}. @xref{Choosing Window,,,elisp,}, for details. The default is: @@ -727,7 +714,7 @@ The default is: @end lisp This displays the window at the bottom of the selected frame. -Another useful @var{function} is @code{display-buffer-below-selected}, which +Another useful @var{FUNCTION} is @code{display-buffer-below-selected}, which is what @code{magit-popup} used by default. For more alternatives see @ref{Buffer Display Action Functions,,,elisp,}, and see @ref{Buffer Display Action Alists,,,elisp,}. @@ -748,8 +735,20 @@ If you change the value of this option, then you might also want to change the value of @code{transient-mode-line-format}. @end defopt -@defopt transient-mode-line-format +@anchor{Accessibility Options} +@subheading Accessibility Options + +@defopt transient-force-single-column +This option controls whether the use of a single column to display +suffixes is enforced. This might be useful for users with low +vision who use large text and might otherwise have to scroll in two +dimensions. +@end defopt + +@anchor{Auxiliary Options} +@subheading Auxiliary Options +@defopt transient-mode-line-format This option controls whether the transient popup buffer has a mode-line, separator line, or neither. @@ -759,23 +758,28 @@ good value. If @code{line} (the default), then the buffer also has no mode-line, but a thin line is drawn instead, using the background color of the face -@code{transient-separator}. Text-mode frames cannot display thin lines, and -therefore fall back to treating @code{line} like @code{nil}. +@code{transient-separator}. Text-mode frames cannot display thin lines, +and therefore fall back to treating @code{line} like @code{nil}. Otherwise this can be any mode-line format. @xref{Mode Line Format,,,elisp,}, for details. @end defopt -@defopt transient-read-with-initial-input +@defopt transient-semantic-coloring +This option controls whether prefixes and suffixes are colored in +a Hydra-like fashion. -This option controls whether the last history element is used as the -initial minibuffer input when reading the value of an infix argument -from the user. If @code{nil}, there is no initial input and the first -element has to be accessed the same way as the older elements. +If non-@code{nil}, then the key binding of each suffix is colorized to +indicate whether it exits the transient state or not. The color of +the prefix is indicated using the line that is drawn when the value +of @code{transient-mode-line-format} is @code{line}. + +For more information about how Hydra uses colors see +@uref{https://github.com/abo-abo/hydra#color} and +@uref{https://oremacs.com/2015/02/19/hydra-colors-reloaded}. @end defopt @defopt transient-highlight-mismatched-keys - This option controls whether key bindings of infix commands that do not match the respective command-line argument should be highlighted. For other infix commands this option has no effect. @@ -795,7 +799,6 @@ The highlighting is done using one of the faces @end defopt @defopt transient-substitute-key-function - This function is used to modify key bindings. If the value of this option is @code{nil} (the default), then no substitution is performed. @@ -819,14 +822,52 @@ optimized for lisp. @end lisp @end defopt -@defopt transient-detect-key-conflicts +@defopt transient-read-with-initial-input +This option controls whether the last history element is used as the +initial minibuffer input when reading the value of an infix argument +from the user. If @code{nil}, there is no initial input and the first +element has to be accessed the same way as the older elements. +@end defopt + +@defopt transient-hide-during-minibuffer-read +This option controls whether the transient buffer is hidden while +user input is being read in the minibuffer. +@end defopt + +@defopt transient-align-variable-pitch +This option controls whether columns are aligned pixel-wise in the +popup buffer. + +If this is non-@code{nil}, then columns are aligned pixel-wise to support +variable-pitch fonts. Keys are not aligned, so you should use a +fixed-pitch font for the @code{transient-key} face. Other key faces +inherit from that face unless a theme is used that breaks that +relationship. + +This option is intended for users who use a variable-pitch font for +the @code{default} face. +@end defopt + +@defopt transient-force-fixed-pitch +This option controls whether to force the use of a monospaced font +in popup buffer. Even if you use a proportional font for the +@code{default} face, you might still want to use a monospaced font in +transient's popup buffer. Setting this option to @code{t} causes @code{default} +to be remapped to @code{fixed-pitch} in that buffer. +@end defopt + +@anchor{Developer Options} +@subheading Developer Options +These options are mainly intended for developers. + +@defopt transient-detect-key-conflicts This option controls whether key binding conflicts should be -detected at the time the transient is invoked. If so, this -results in an error, which prevents the transient from being used. -Because of that, conflicts are ignored by default. +detected at the time the transient is invoked. If so, this results +in an error, which prevents the transient from being used. Because +of that, conflicts are ignored by default. -Conflicts cannot be determined earlier, i.e.@: when the transient is +Conflicts cannot be determined earlier, i.e., when the transient is being defined and when new suffixes are being added, because at that time there can be false-positives. It is actually valid for multiple suffixes to share a common key binding, provided the @@ -834,48 +875,51 @@ predicates of those suffixes prevent that more than one of them is enabled at a time. @end defopt -@defopt transient-force-fixed-pitch +@defopt transient-highlight-higher-levels +This option controls whether suffixes that would not be available by +default are highlighted. -This option controls whether to force the use of a monospaced font -in popup buffer. Even if you use a proportional font for the -@code{default} face, you might still want to use a monospaced font in -transient's popup buffer. Setting this option to @code{t} causes @code{default} -to be remapped to @code{fixed-pitch} in that buffer. +When non-@code{nil} then the descriptions of suffixes are highlighted if +their level is above 4, the default of @code{transient-default-level}. +Assuming you have set that variable to 7, this highlights all +suffixes that won't be available to users without them making the +same customization. @end defopt @node Modifying Existing Transients @chapter Modifying Existing Transients + @cindex modifying existing transients -To an extent, transients can be customized interactively, see @ref{Enabling and Disabling Suffixes}. This section explains how existing transients -can be further modified non-interactively. +To an extent, transients can be customized interactively, see +@ref{Enabling and Disabling Suffixes}. This section explains how existing +transients can be further modified non-interactively. The following functions share a few arguments: @itemize @item -@var{prefix} is a transient prefix command, a symbol. - +@var{PREFIX} is a transient prefix command, a symbol. @item -@var{suffix} is a transient infix or suffix specification in the same form +@var{SUFFIX} is a transient infix or suffix specification in the same form as expected by @code{transient-define-prefix}. Note that an infix is a -special kind of suffix. Depending on context ``suffixes'' means -``suffixes (including infixes)'' or ``non-infix suffixes''. Here it +special kind of suffix. Depending on context “suffixes” means +“suffixes (including infixes)” or “non-infix suffixes”. Here it means the former. @xref{Suffix Specifications}. -@var{suffix} may also be a group in the same form as expected by +@var{SUFFIX} may also be a group in the same form as expected by @code{transient-define-prefix}. @xref{Group Specifications}. @item -@var{loc} is a command, a key vector, a key description (a string as +@var{LOC} is a command, a key vector, a key description (a string as returned by @code{key-description}), or a list specifying coordinates (the last element may also be a command or key). For example @code{(1 0 -1)} identifies the last suffix (@code{-1}) of the first subgroup (@code{0}) of the second group (@code{1}). -If @var{loc} is a list of coordinates, then it can be used to identify a +If @var{LOC} is a list of coordinates, then it can be used to identify a group, not just an individual suffix command. The function @code{transient-get-suffix} can be useful to determine whether @@ -885,55 +929,53 @@ at the definition of the transient prefix command. @end itemize These functions operate on the information stored in the -@code{transient--layout} property of the @var{prefix} symbol. Suffix entries in -that tree are not objects but have the form @code{(@var{level} -@var{class} @var{plist})}, where -@var{plist} should set at least @code{:key}, @code{:description} and -@code{:command}. - -@defun transient-insert-suffix prefix loc suffix +@code{transient--layout} property of the @var{PREFIX} symbol. Suffix entries in +that tree are not objects but have the form @code{(@var{LEVEL} @var{CLASS} @var{PLIST})}, where +@var{PLIST} should set at least @code{:key}, @code{:description} and @code{:command}. -This function inserts suffix or group @var{suffix} into @var{prefix} -before @var{loc}. +@defun transient-insert-suffix prefix loc suffix &optional keep-other @end defun - -@defun transient-append-suffix prefix loc suffix - -This function inserts suffix or group @var{suffix} into @var{prefix} -after @var{loc}. +@defun transient-append-suffix prefix loc suffix &optional keep-other +These functions insert the suffix or group @var{SUFFIX} into @var{PREFIX} before +or after @var{LOC}. + +Conceptually adding a binding to a transient prefix is similar to +adding a binding to a keymap, but this is complicated by the fact +that multiple suffix commands can be bound to the same key, provided +they are never active at the same time, see @ref{Predicate Slots}. + +Unfortunately both false-positives and false-negatives are possible. +To deal with the former use non-nil @var{KEEP-OTHER@.} To deal with the +latter remove the conflicting binding explicitly. @end defun @defun transient-replace-suffix prefix loc suffix - -This function replaces the suffix or group at @var{loc} in @var{prefix} with -suffix or group @var{suffix}. +This function replaces the suffix or group at @var{LOC} in @var{PREFIX} with +suffix or group @var{SUFFIX}. @end defun @defun transient-remove-suffix prefix loc - -This function removes the suffix or group at @var{loc} in @var{prefix}. +This function removes the suffix or group at @var{LOC} in @var{PREFIX}. @end defun @defun transient-get-suffix prefix loc - -This function returns the suffix or group at @var{loc} in @var{prefix}. The +This function returns the suffix or group at @var{LOC} in @var{PREFIX}. The returned value has the form mentioned above. @end defun @defun transient-suffix-put prefix loc prop value - -This function edits the suffix or group at @var{loc} in @var{prefix}, -by setting the @var{prop} of its plist to @var{value}. +This function edits the suffix or group at @var{LOC} in @var{PREFIX}, by setting +the @var{PROP} of its plist to @var{VALUE}. @end defun Most of these functions do not signal an error if they cannot perform the requested modification. The functions that insert new suffixes -show a warning if @var{loc} cannot be found in @var{prefix}, without -signaling an error. The reason for doing it like this is that -establishing a key binding (and that is what we essentially are trying -to do here) should not prevent the rest of the configuration from -loading. Among these functions only @code{transient-get-suffix} and -@code{transient-suffix-put} may signal an error. +show a warning if @var{LOC} cannot be found in @var{PREFIX} without signaling an +error. The reason for doing it like this is that establishing a key +binding (and that is what we essentially are trying to do here) should +not prevent the rest of the configuration from loading. Among these +functions only @code{transient-get-suffix} and @code{transient-suffix-put} may +signal an error. @node Defining New Commands @chapter Defining New Commands @@ -957,12 +999,11 @@ defines the complete transient, not just the transient prefix command that is used to invoke that transient. @defmac transient-define-prefix name arglist [docstring] [keyword value]@dots{} group@dots{} [body@dots{}] - -This macro defines @var{name} as a transient prefix command and binds the +This macro defines @var{NAME} as a transient prefix command and binds the transient's infix and suffix commands. -@var{arglist} are the arguments that the prefix command takes. -@var{docstring} is the documentation string and is optional. +@var{ARGLIST} are the arguments that the prefix command takes. +@var{DOCSTRING} is the documentation string and is optional. These arguments can optionally be followed by keyword-value pairs. Each key has to be a keyword symbol, either @code{:class} or a keyword @@ -970,11 +1011,11 @@ argument supported by the constructor of that class. The @code{transient-prefix} class is used if the class is not specified explicitly. -@var{group}s add key bindings for infix and suffix commands and specify +@var{GROUP}s add key bindings for infix and suffix commands and specify how these bindings are presented in the popup buffer. At least one -@var{group} has to be specified. @xref{Binding Suffix and Infix Commands}. +@var{GROUP} has to be specified. @xref{Binding Suffix and Infix Commands}. -The @var{body} is optional. If it is omitted, then @var{arglist} is ignored and +The @var{BODY} is optional. If it is omitted, then @var{ARGLIST} is ignored and the function definition becomes: @lisp @@ -983,15 +1024,15 @@ the function definition becomes: (transient-setup 'NAME)) @end lisp -If @var{body} is specified, then it must begin with an @code{interactive} form -that matches @var{arglist}, and it must call @code{transient-setup}. It may, +If @var{BODY} is specified, then it must begin with an @code{interactive} form +that matches @var{ARGLIST}, and it must call @code{transient-setup}. It may, however, call that function only when some condition is satisfied. @cindex scope of a transient All transients have a (possibly @code{nil}) value, which is exported when suffix commands are called, so that they can consume that value. For some transients it might be necessary to have a sort of -secondary value, called a ``scope''. Such a scope would usually be +secondary value, called a “scope”. Such a scope would usually be set in the command's @code{interactive} form and has to be passed to the setup function: @@ -1013,8 +1054,8 @@ described below. Users and third-party packages can add additional bindings using functions such as @code{transient-insert-suffix} (@pxref{Modifying -Existing Transients}). These functions take a ``suffix -specification'' as one of their arguments, which has the same form as +Existing Transients}). These functions take a “suffix +specification” as one of their arguments, which has the same form as the specifications used in @code{transient-define-prefix}. @menu @@ -1024,6 +1065,7 @@ the specifications used in @code{transient-define-prefix}. @node Group Specifications @subsection Group Specifications + @cindex group specifications The suffix and infix commands of a transient are organized in groups. @@ -1043,39 +1085,39 @@ brackets to do the latter. Group specifications then have this form: @lisp -[@{@var{level}@} @{@var{description}@} - @{@var{keyword} @var{value}@}... - @var{element}...] +[@{@var{LEVEL}@} @{@var{DESCRIPTION}@} + @{@var{KEYWORD} @var{VALUE}@}... + @var{ELEMENT}...] @end lisp -The @var{level} is optional and defaults to 4. @xref{Enabling and +The @var{LEVEL} is optional and defaults to 4. @xref{Enabling and Disabling Suffixes}. -The @var{description} is optional. If present, it is used as the heading of +The @var{DESCRIPTION} is optional. If present, it is used as the heading of the group. -The @var{keyword}-@var{value} pairs are optional. Each keyword has to be a +The @var{KEYWORD}-@var{VALUE} pairs are optional. Each keyword has to be a keyword symbol, either @code{:class} or a keyword argument supported by the constructor of that class. @itemize @item One of these keywords, @code{:description}, is equivalent to specifying -@var{description} at the very beginning of the vector. The recommendation +@var{DESCRIPTION} at the very beginning of the vector. The recommendation is to use @code{:description} if some other keyword is also used, for -consistency, or @var{description} otherwise, because it looks better. +consistency, or @var{DESCRIPTION} otherwise, because it looks better. @item -Likewise @code{:level} is equivalent to @var{level}. +Likewise @code{:level} is equivalent to @var{LEVEL}. @item Other important keywords include the @code{:if...} keywords. These keywords control whether the group is available in a certain situation. -For example, one group of the @code{magit-rebase} transient uses -@code{:if magit-rebase-in-progress-p}, which contains the suffixes -that are useful while rebase is already in progress; and another that uses +For example, one group of the @code{magit-rebase} transient uses @code{:if + magit-rebase-in-progress-p}, which contains the suffixes that are +useful while rebase is already in progress; and another that uses @code{:if-not magit-rebase-in-progress-p}, which contains the suffixes that initiate a rebase. @@ -1096,9 +1138,9 @@ suffixes, which assumes that a predicate like this is used: @end lisp @item -The value of @code{:setup-children}, if non-@code{nil}, is a function -that takes two arguments the group object itself and a list of children. -The children are given as a, potentially empty, list consisting +The value of @code{:setup-children}, if non-@code{nil}, is a function that takes +two arguments the group object itself and a list of children. +The children are given as a (potentially empty) list consisting of either group or suffix specifications. It can make arbitrary changes to the children including constructing new children from scratch. Also see @code{transient-setup-children}. @@ -1109,21 +1151,21 @@ contained in a group are right padded, effectively aligning the descriptions. @end itemize -The @var{element}s are either all subgroups (vectors), or all suffixes +The @var{ELEMENT}s are either all subgroups (vectors), or all suffixes (lists) and strings. (At least currently no group type exists that would allow mixing subgroups with commands at the same level, though in principle there is nothing that prevents that.) -If the @var{element}s are not subgroups, then they can be a mixture of lists +If the @var{ELEMENT}s are not subgroups, then they can be a mixture of lists that specify commands and strings. Strings are inserted verbatim. The empty string can be used to insert gaps between suffixes, which is particularly useful if the suffixes are outlined as a table. Variables are supported inside group specifications. For example in place of a direct subgroup specification, a variable can be used whose -value is a vector that qualifies as a group specification. Likewise, a -variable can be used where a suffix specification is expected. Lists -of group or suffix specifications are also supported. Indirect +value is a vector that qualifies as a group specification. Likewise, +a variable can be used where a suffix specification is expected. +Lists of group or suffix specifications are also supported. Indirect specifications are resolved when the transient prefix is being defined. @@ -1131,6 +1173,7 @@ The form of suffix specifications is documented in the next node. @node Suffix Specifications @subsection Suffix Specifications + @cindex suffix specifications A transient's suffix and infix commands are bound when the transient @@ -1140,37 +1183,36 @@ prefix command is defined using @code{transient-define-prefix}, see individual suffix command. The same form is also used when later binding additional commands -using functions such as @code{transient-insert-suffix}, -see @ref{Modifying Existing Transients}. +using functions such as @code{transient-insert-suffix}, see @ref{Modifying Existing Transients}. -Note that an infix is a special kind of suffix. Depending on context -``suffixes'' means ``suffixes (including infixes)'' or ``non-infix -suffixes''. Here it means the former. +Note that an infix is a special kind of suffix. Depending on context +“suffixes” means “suffixes (including infixes)” or “non-infix +suffixes”. Here it means the former. Suffix specifications have this form: @lisp -([@var{level}] - [@var{key}] [@var{description}] - @var{command}|@var{argument} [@var{keyword} @var{value}]...) +([@var{LEVEL}] + [@var{KEY}] [@var{DESCRIPTION}] + @var{COMMAND}|@var{ARGUMENT} [@var{KEYWORD} @var{VALUE}]...) @end lisp -@var{level}, @var{key} and @var{description} can also be specified using the @var{keyword}s +@var{LEVEL}, @var{KEY} and @var{DESCRIPTION} can also be specified using the @var{KEYWORD}s @code{:level}, @code{:key} and @code{:description}. If the object that is associated with -@var{command} sets these properties, then they do not have to be specified +@var{COMMAND} sets these properties, then they do not have to be specified here. You can however specify them here anyway, possibly overriding the object's values just for the binding inside this transient. @itemize @item -@var{level} is the suffix level, an integer between 1 and 7. +@var{LEVEL} is the suffix level, an integer between 1 and 7. @xref{Enabling and Disabling Suffixes}. @item -@var{key} is the key binding, either a vector or key description string. +@var{KEY} is the key binding, either a vector or key description string. @item -@var{description} is the description, either a string or a function that +@var{DESCRIPTION} is the description, either a string or a function that returns a string. The function should be a lambda expression to avoid ambiguity. In some cases a symbol that is bound as a function would also work but to be safe you should use @code{:description} in that @@ -1182,7 +1224,7 @@ argument that is mandatory in all cases. @itemize @item -Usually @var{command} is a symbol that is bound as a function, which has +@var{COMMAND} should be a symbol that is bound as a function, which has to be defined or at least autoloaded as a command by the time the containing prefix command is invoked. @@ -1190,15 +1232,13 @@ Any command will do; it does not need to have an object associated with it (as would be the case if @code{transient-define-suffix} or @code{transient-define-infix} were used to define it). -The command can also be a closure or lambda expression, but that -should only be used for dynamic transients whose suffixes are -defined when the prefix command is invoked. See information about -the @code{:setup-children} function in @ref{Group Specifications}. +Anonymous, dynamically defined suffix commands are also support. +See information about the @code{:setup-children} function in @ref{Group Specifications}. As mentioned above, the object that is associated with a command can be used to set the default for certain values that otherwise have to be set in the suffix specification. Therefore if there is no object, -then you have to make sure to specify the @var{key} and the @var{description}. +then you have to make sure to specify the @var{KEY} and the @var{DESCRIPTION}. As a special case, if you want to add a command that might be neither defined nor autoloaded, you can use a workaround like: @@ -1209,8 +1249,8 @@ defined nor autoloaded, you can use a workaround like: :if (lambda () (featurep 'no-library)))) @end lisp -Instead of @code{featurep} you could also use @code{require} with a -non-nil value for @var{noerror}. +Instead of @code{featurep} you could also use @code{require} with a non-@code{nil} value +for @var{NOERROR}. @item The mandatory argument can also be a command-line argument, a @@ -1227,30 +1267,29 @@ used. Unless the class is specified explicitly, the appropriate class is guessed based on the long argument. If the argument ends with @samp{=} -(e.g. @samp{--format=}) then @code{transient-option} is used, otherwise +(e.g., @samp{--format=}) then @code{transient-option} is used, otherwise @code{transient-switch}. @end itemize -Finally, details can be specified using optional -@var{keyword}-@var{value} pairs. +Finally, details can be specified using optional @var{KEYWORD}-@var{VALUE} pairs. Each keyword has to be a keyword symbol, either @code{:class} or a keyword argument supported by the constructor of that class. See @ref{Suffix Slots}. @node Defining Suffix and Infix Commands @section Defining Suffix and Infix Commands + @cindex defining suffix commands @cindex defining infix commands -Note that an infix is a special kind of suffix. Depending on context -``suffixes'' means ``suffixes (including infixes)'' or ``non-infix -suffixes''. +Note that an infix is a special kind of suffix. Depending on context +“suffixes” means “suffixes (including infixes)” or “non-infix +suffixes”. @defmac transient-define-suffix name arglist [docstring] [keyword value]@dots{} body@dots{} +This macro defines @var{NAME} as a transient suffix command. -This macro defines @var{name} as a transient suffix command. - -@var{arglist} are the arguments that the command takes. -@var{docstring} is the documentation string and is optional. +@var{ARGLIST} are the arguments that the command takes. +@var{DOCSTRING} is the documentation string and is optional. These arguments can optionally be followed by keyword-value pairs. Each keyword has to be a keyword symbol, either @code{:class} or a keyword @@ -1258,17 +1297,16 @@ argument supported by the constructor of that class. The @code{transient-suffix} class is used if the class is not specified explicitly. -The @var{body} must begin with an @code{interactive} form that matches @var{arglist}. +The @var{BODY} must begin with an @code{interactive} form that matches @var{ARGLIST}. The infix arguments are usually accessed by using @code{transient-args} inside @code{interactive}. @end defmac @defmac transient-define-infix name arglist [docstring] [keyword value]@dots{} +This macro defines @var{NAME} as a transient infix command. -This macro defines @var{name} as a transient infix command. - -@var{arglist} is always ignored (but mandatory never-the-less) and -reserved for future use. @var{docstring} is the documentation string and +@var{ARGLIST} is always ignored (but mandatory never-the-less) and +reserved for future use. @var{DOCSTRING} is the documentation string and is optional. The keyword-value pairs are mandatory. All transient infix commands @@ -1297,13 +1335,12 @@ Different infix commands behave differently because the concrete methods are different for different infix command classes. In rare cases the above command function might not be suitable, even if you define your own infix command class. In that case you have to use -@code{transient-suffix-command} to define the infix command and use @code{t} as -the value of the @code{:transient} keyword. +@code{transient-define-suffix} to define the infix command and use @code{t} as the +value of the @code{:transient} keyword. @end defmac @defmac transient-define-argument name arglist [docstring] [keyword value]@dots{} - -This macro defines @var{name} as a transient infix command. +This macro defines @var{NAME} as a transient infix command. This is an alias for @code{transient-define-infix}. Only use this alias to define an infix command that actually sets an infix argument. @@ -1313,7 +1350,6 @@ To define an infix command that, for example, sets a variable, use @node Using Infix Arguments @section Using Infix Arguments -@cindex using infix arguments The functions and the variables described below allow suffix commands to access the value of the transient from which they were invoked; @@ -1332,61 +1368,56 @@ function, which for infix arguments serves about the same purpose as @code{prefix-arg} serves for prefix arguments. @defun transient-args prefix - This function returns the value of the transient prefix command -@var{prefix}. +@var{PREFIX}. If the current command was invoked from the transient prefix command -@var{prefix}, then it returns the active infix arguments. If the current -command was not invoked from @var{prefix}, then it returns the set, saved -or default value for @var{prefix}. +@var{PREFIX}, then it returns the active infix arguments. If the current +command was not invoked from @var{PREFIX}, then it returns the set, saved +or default value for @var{PREFIX}. @end defun @defun transient-arg-value arg args - -This function return the value of @var{arg} as it appears in @var{args}. +This function return the value of @var{ARG} as it appears in @var{ARGS}. For a switch a boolean is returned. For an option the value is returned as a string, using the empty string for the empty value, -or @code{nil} if the option does not appear in @var{args}. +or @code{nil} if the option does not appear in @var{ARGS}. @end defun @defun transient-suffixes prefix - This function returns the suffixes of the transient prefix command -@var{prefix}. This is a list of objects. This function should only be +@var{PREFIX}. This is a list of objects. This function should only be used if you need the objects (as opposed to just their values) and -if the current command is not being invoked from @var{prefix}. +if the current command is not being invoked from @var{PREFIX}. @end defun @defvar transient-current-suffixes - The suffixes of the transient from which this suffix command was invoked. This is a list of objects. Usually it is sufficient to instead use the function @code{transient-args}, which returns a list of values. In complex cases it might be necessary to use this variable -instead, i.e.@: if you need access to information beside the value. +instead, i.e., if you need access to information beside the value. @end defvar @defvar transient-current-prefix - The transient from which this suffix command was invoked. The returned value is a @code{transient-prefix} object, which holds information associated with the transient prefix command. @end defvar @defvar transient-current-command - The transient from which this suffix command was invoked. The returned value is a symbol, the transient prefix command. @end defvar @node Transient State @section Transient State + @cindex transient state -Invoking a transient prefix command ``activates'' the respective -transient, i.e.@: it puts a transient keymap into effect, which binds +Invoking a transient prefix command “activates” the respective +transient, i.e., it puts a transient keymap into effect, which binds the transient's infix and suffix commands. The default behavior while a transient is active is as follows: @@ -1397,20 +1428,20 @@ Invoking an infix command does not affect the transient state; the transient remains active. @item -Invoking a (non-infix) suffix command ``deactivates'' the transient +Invoking a (non-infix) suffix command “deactivates” the transient state by removing the transient keymap and performing some additional cleanup. @item Invoking a command that is bound in a keymap other than the transient keymap is disallowed and trying to do so results in a -warning. This does not ``deactivate'' the transient. +warning. This does not “deactivate” the transient. @end itemize But these are just the defaults. Whether a certain command -deactivates or ``exits'' the transient is configurable. There is more -than one way in which a command can be ``transient'' or ``non-transient''; -the exact behavior is implemented by calling a so-called ``pre-command'' +deactivates or “exits” the transient is configurable. There is more +than one way in which a command can be “transient” or “non-transient”; +the exact behavior is implemented by calling a so-called “pre-command” function. Whether non-suffix commands are allowed to be called is configurable per transient. @@ -1426,10 +1457,8 @@ Valid values are booleans and the pre-commands described below. @itemize @item @code{t} is equivalent to @code{transient--do-stay}. - @item @code{nil} is equivalent to @code{transient--do-exit}. - @item If @code{transient} is unbound (and that is actually the default for non-infix suffixes) then the value of the prefix's @@ -1439,18 +1468,18 @@ essentially equivalent to it being @code{nil}. @end itemize @item -A suffix command can be a prefix command itself, i.e. a -``sub-prefix''. While a sub-prefix is active we nearly always want -@kbd{C-g} to take the user back to the ``super-prefix''. However in rare +A suffix command can be a prefix command itself, i.e., a +“sub-prefix”. While a sub-prefix is active we nearly always want +@kbd{C-g} to take the user back to the “super-prefix”. However in rare cases this may not be desirable, and that makes the following complication necessary: For @code{transient-suffix} objects the @code{transient} slot is unbound. We can ignore that for the most part because, as stated above, @code{nil} and the -slot being unbound are equivalent, and mean ``do exit''. That isn't +slot being unbound are equivalent, and mean “do exit”. That isn't actually true for suffixes that are sub-prefixes though. For such -suffixes unbound means ``do exit but allow going back'', which is the -default, while @code{nil} means ``do exit permanently'', which requires that +suffixes unbound means “do exit but allow going back”, which is the +default, while @code{nil} means “do exit permanently”, which requires that slot to be explicitly set to that value. @item @@ -1465,7 +1494,7 @@ called by @code{transient--pre-command}, a function on @code{pre-command-hook} a the value that they return determines whether the transient is exited. To do so the value of one of the constants @code{transient--exit} or @code{transient--stay} is used (that way we don't have to remember if @code{t} means -``exit'' or ``stay''). +“exit” or “stay”). Additionally, these functions may change the value of @code{this-command} (which explains why they have to be called using @code{pre-command-hook}), @@ -1480,7 +1509,6 @@ The default for infixes is @code{transient--do-stay}. This is also the only function that makes sense for infixes. @defun transient--do-stay - Call the command without exporting variables and stay transient. @end defun @@ -1490,27 +1518,55 @@ Call the command without exporting variables and stay transient. The default for suffixes is @code{transient--do-exit}. @defun transient--do-exit - Call the command after exporting variables and exit the transient. @end defun -@defun transient--do-call +@defun transient--do-return +Call the command after exporting variables and return to parent +prefix. If there is no parent prefix, then call @code{transient--do-exit}. +@end defun +@defun transient--do-call Call the command after exporting variables and stay transient. @end defun -@defun transient--do-replace +The following pre-commands are suitable for sub-prefixes. Only the +first should ever explicitly be set as the value of the @code{transient} +slot. + +@defun transient--do-recurse +Call the transient prefix command, preparing for return to active +transient. + +Whether we actually return to the parent transient is ultimately +under the control of each invoked suffix. The difference between +this pre-command and @code{transient--do-replace} is that it changes the +value of the @code{transient-suffix} slot to @code{transient--do-return}. + +If there is no parent transient, then only call this command and +skip the second step. +@end defun +@defun transient--do-replace Call the transient prefix command, replacing the active transient. -This is used for suffixes that are prefixes themselves, i.e.@: for -sub-prefixes. +Unless @code{transient--do-recurse} is explicitly used, this pre-command +is automatically used for suffixes that are prefixes themselves, +i.e., for sub-prefixes. +@end defun + +@defun transient--do-suspend +Suspend the active transient, saving the transient stack. + +This is used by the command @code{transient-suspend} and optionally also by +“external events” such as @code{handle-switch-frame}. Such bindings should +be added to @code{transient-predicate-map}. @end defun @anchor{Pre-commands for Non-Suffixes} @subheading Pre-commands for Non-Suffixes -The default for non-suffixes, i.e@: commands that are bound in other +The default for non-suffixes, i.e., commands that are bound in other keymaps beside the transient keymap, is @code{transient--do-warn}. Silently ignoring the user-error is also an option, though probably not a good one. @@ -1520,12 +1576,10 @@ If you want to let the user invoke non-suffix commands, then use slot. @defun transient--do-warn - Call @code{transient-undefined} and stay transient. @end defun @defun transient--do-noop - Call @code{transient-noop} and stay transient. @end defun @@ -1533,21 +1587,18 @@ Call @code{transient-noop} and stay transient. @subheading Special Pre-Commands @defun transient--do-quit-one - If active, quit help or edit mode, else exit the active transient. This is used when the user pressed @kbd{C-g}. @end defun @defun transient--do-quit-all - Exit all transients without saving the transient stack. This is used when the user pressed @kbd{C-q}. @end defun @defun transient--do-suspend - Suspend the active transient, saving the transient stack. This is used when the user pressed @kbd{C-z}. @@ -1555,6 +1606,7 @@ This is used when the user pressed @kbd{C-z}. @node Classes and Methods @chapter Classes and Methods + @cindex classes and methods Transient uses classes and generic functions to make it possible to @@ -1591,7 +1643,7 @@ holds a function that is used to read a new value for an infix command. The values of such slots are regular functions. Generic functions are used when a function should do something -different based on the type of the command, i.e. when all commands +different based on the type of the command, i.e., when all commands of a certain type should behave the same way but different from the behavior for other types. Object slots that hold a regular function as value are used when the task that they perform is likely to @@ -1613,7 +1665,7 @@ differ even between different commands of the same type. @section Group Classes The type of a group can be specified using the @code{:class} property at the -beginning of the class specification, e.g. @code{[:class transient-columns +beginning of the class specification, e.g., @code{[:class transient-columns ...]} in a call to @code{transient-define-prefix}. @itemize @@ -1622,7 +1674,7 @@ The abstract @code{transient-child} class is the base class of both @code{transient-group} (and therefore all groups) as well as of @code{transient-suffix} (and therefore all suffix and infix commands). -This class exists because the elements (a.k.a.@: ``children'') of certain +This class exists because the elements (or “children”) of certain groups can be other groups instead of suffix and infix commands. @item @@ -1632,8 +1684,8 @@ group classes. @item The @code{transient-column} class is the simplest group. -This is the default ``flat'' group. If the class is not specified -explicitly and the first element is not a vector (i.e. not a group), +This is the default “flat” group. If the class is not specified +explicitly and the first element is not a vector (i.e., not a group), then this class is used. This class displays each element on a separate line. @@ -1648,8 +1700,8 @@ Direct elements have to be groups whose elements have to be commands or strings. Each subgroup represents a column. This class takes care of inserting the subgroups' elements. -This is the default ``nested'' group. If the class is not specified -explicitly and the first element is a vector (i.e.@: a group), then +This is the default “nested” group. If the class is not specified +explicitly and the first element is a vector (i.e., a group), then this class is used. @item @@ -1665,12 +1717,11 @@ elements. @section Group Methods @defun transient-setup-children group children - This generic function can be used to setup the children or a group. The default implementation usually just returns the children -unchanged, but if the @code{setup-children} slot of @var{group} is non-nil, then -it calls that function with @var{children} as the only argument and +unchanged, but if the @code{setup-children} slot of @var{GROUP} is non-@code{nil}, then +it calls that function with @var{CHILDREN} as the only argument and returns the value. The children are given as a (potentially empty) list consisting of @@ -1680,7 +1731,6 @@ children from scratch. @end defun @defun transient--insert-group group - This generic function formats the group and its elements and inserts the result into the current buffer, which is a temporary buffer. The contents of that buffer are later inserted into the popup buffer. @@ -1698,7 +1748,6 @@ commands and there is only a single generic function that can be specialized based on the class of a prefix command. @defun transient--history-init obj - This generic function is called while setting up the transient and is responsible for initializing the @code{history} slot. This is the transient-wide history; many individual infixes also have a history @@ -1784,8 +1833,7 @@ functions use @code{describe-function}. @subsection Suffix Value Methods @defun transient-init-value obj - -This generic function sets the initial value of the object @var{obj}. +This generic function sets the initial value of the object @var{OBJ}. This function is called for all suffix commands, but unless a concrete method is implemented this falls through to the default @@ -1797,9 +1845,8 @@ a method. @end defun @defun transient-infix-read obj - This generic function determines the new value of the infix object -@var{obj}. +@var{OBJ}. This function merely determines the value; @code{transient-infix-set} is used to actually store the new value in the object. @@ -1809,40 +1856,36 @@ user using the reader specified by the @code{reader} slot (using the @code{transient-infix-value} method described below). For some infix classes the value is changed without reading -anything in the minibuffer, i.e.@: the mere act of invoking the +anything in the minibuffer, i.e., the mere act of invoking the infix command determines what the new value should be, based on the previous value. @end defun @defun transient-prompt obj - This generic function returns the prompt to be used to read infix -object @var{obj}'s value. +object @var{OBJ}'s value. @end defun @defun transient-infix-set obj value - -This generic function sets the value of infix object @var{obj} to @var{value}. +This generic function sets the value of infix object @var{OBJ} to @var{VALUE}. @end defun @defun transient-infix-value obj - -This generic function returns the value of the suffix object @var{obj}. +This generic function returns the value of the suffix object @var{OBJ}. This function is called by @code{transient-args} (which see), meaning this function is how the value of a transient is determined so that the invoked suffix command can use it. Currently most values are strings, but that is not set in stone. -@code{nil} is not a value, it means ``no value''. +@code{nil} is not a value, it means “no value”. Usually only infixes have a value, but see the method for @code{transient-suffix}. @end defun @defun transient-init-scope obj - -This generic function sets the scope of the suffix object @var{obj}. +This generic function sets the scope of the suffix object @var{OBJ}. The scope is actually a property of the transient prefix, not of individual suffixes. However it is possible to invoke a suffix @@ -1859,8 +1902,7 @@ implementation, which is a noop. @subsection Suffix Format Methods @defun transient-format obj - -This generic function formats and returns @var{obj} for display. +This generic function formats and returns @var{OBJ} for display. When this function is called, then the current buffer is some temporary buffer. If you need the buffer from which the prefix @@ -1869,27 +1911,23 @@ making @code{transient--source-buffer} current. @end defun @defun transient-format-key obj - -This generic function formats @var{obj}'s @code{key} for display and returns the +This generic function formats @var{OBJ}'s @code{key} for display and returns the result. @end defun @defun transient-format-description obj - -This generic function formats @var{obj}'s @code{description} for display and +This generic function formats @var{OBJ}'s @code{description} for display and returns the result. @end defun @defun transient-format-value obj - -This generic function formats @var{obj}'s value for display and returns +This generic function formats @var{OBJ}'s value for display and returns the result. @end defun @defun transient-show-help obj - Show help for the prefix, infix or suffix command represented by -@var{obj}. +@var{OBJ}. For prefixes, show the info manual, if that is specified using the @code{info-manual} slot. Otherwise, show the manpage if that is specified @@ -1906,10 +1944,10 @@ the command's doc string. @itemize @item -@code{man-page} or @code{info-manual} can be used to specify the documentation for -the prefix and its suffixes. The command @code{transient-help} uses the -method @code{transient-show-help} (which see) to lookup and use these -values. +@code{show-help}, @code{man-page} or @code{info-manual} can be used to specify the +documentation for the prefix and its suffixes. The command +@code{transient-help} uses the method @code{transient-show-help} (which see) to +lookup and use these values. @item @code{history-key} If multiple prefix commands should share a single value, @@ -1930,7 +1968,7 @@ multiple sub-lists. @item @code{scope} For some transients it might be necessary to have a sort of -secondary value, called a ``scope''. See @code{transient-define-prefix}. +secondary value, called a “scope”. See @code{transient-define-prefix}. @end itemize @anchor{Internal Prefix Slots} @@ -1995,10 +2033,8 @@ It must contain the following %-placeholders: @itemize @item @code{%k} For the key. - @item @code{%d} For the description. - @item @code{%v} For the infix value. Non-infix suffixes don't have a value. @end itemize @@ -2006,6 +2042,11 @@ It must contain the following %-placeholders: @item @code{description} The description, either a string or a function that is called with no argument and returns a string. + +@item +@code{show-help} A function used to display help for the suffix. If +unspecified, the prefix controls how hlep is displayed for its +suffixes. @end itemize @anchor{Slots of @code{transient-infix}} @@ -2016,10 +2057,10 @@ They are defined here anyway to allow sharing certain methods. @itemize @item -@code{argument} The long argument, e.g. @code{--verbose}. +@code{argument} The long argument, e.g., @code{--verbose}. @item -@code{shortarg} The short argument, e.g. @code{-v}. +@code{shortarg} The short argument, e.g., @code{-v}. @item @code{value} The value. Should not be accessed directly. @@ -2036,7 +2077,34 @@ the prefixes. @item @code{multi-value} For options, whether the option can have multiple -values. If non-nil, then default to use @code{completing-read-multiple}. +values. If this is non-@code{nil}, then the values are read using +@code{completing-read-multiple} by default and if you specify your own +reader, then it should read the values using that function or +similar. + +Supported non-@code{nil} values are: + +@itemize +@item +Use @code{rest} for an option that can have multiple values. This is +useful e.g., for an @code{--} argument that indicates that all remaining +arguments are files (such as @code{git log -- file1 file2}). + +In the list returned by @code{transient-args} such an option and its +values are represented by a single list of the form @code{(ARGUMENT + . VALUES)}. + +@item +Use @code{repeat} for an option that can be specified multiple times. + +In the list returned by @code{transient-args} each instance of the option +and its value appears separately in the usual from, for example: +@code{("--another-argument" "--option=first" "--option=second")}. +@end itemize + +In both cases the option's values have to be specified in the +default value of a prefix using the same format as returned by +@code{transient-args}, e.g., @code{("--other" "--o=1" "--o=2" ("--" "f1" "f2"))}. @item @code{always-read} For options, whether to read a value on every invocation. @@ -2053,8 +2121,8 @@ same history because their values are of the same kind. @item @code{reader} The function used to read the value of an infix. Not used -for switches. The function takes three arguments, @var{prompt}, -@var{initial-input} and @var{history}, and must return a string. +for switches. The function takes three arguments, @var{PROMPT}, +@var{INITIAL-INPUT} and @var{HISTORY}, and must return a string. @item @code{prompt} The prompt used when reading the value, either a string or a @@ -2098,25 +2166,18 @@ what happens if you use more than one. @itemize @item @code{if} Enable if predicate returns non-@code{nil}. - @item @code{if-not} Enable if predicate returns @code{nil}. - @item @code{if-non-nil} Enable if variable's value is non-@code{nil}. - @item @code{if-nil} Enable if variable's value is @code{nil}. - @item @code{if-mode} Enable if major-mode matches value. - @item @code{if-not-mode} Enable if major-mode does not match value. - @item @code{if-derived} Enable if major-mode derives from value. - @item @code{if-not-derived} Enable if major-mode does not derive from value. @end itemize @@ -2146,16 +2207,13 @@ The following diagrams illustrate some of the differences. @itemize @item -@code{(c)} represents a return to the command loop. - +@samp{(c)} represents a return to the command loop. @item -@code{(+)} represents the user's choice to press one key or another. - +@samp{(+)} represents the user's choice to press one key or another. @item -@code{@{@var{word}@}} are possible behaviors. - +@samp{@{WORD@}} are possible behaviors. @item -@code{@{@var{number}@}} is a footnote. +@samp{@{NUMBER@}} is a footnote. @end itemize @anchor{Regular Prefix Commands} @@ -2331,7 +2389,7 @@ and also takes external state into account. @itemize @item -@code{@{1@}} Transients can be configured to be exited when a suffix command +@samp{@{1@}} Transients can be configured to be exited when a suffix command is invoked. The default is to do so for all suffixes except for those that are common to all transients and which are used to perform tasks such as providing help and saving the value of the @@ -2340,7 +2398,7 @@ specified for individual suffix commands and may even depend on state. @item -@code{@{2@}} Transients can be configured to allow the user to invoke +@samp{@{2@}} Transients can be configured to allow the user to invoke non-suffix commands. The default is to not allow that and instead warn the user. @end itemize @@ -2386,9 +2444,9 @@ Both packages use transient keymaps to make a set of commands temporarily available and show the available commands in a popup buffer. -A Hydra ``body'' is equivalent to a Transient ``prefix'' and a Hydra -``head'' is equivalent to a Transient ``suffix''. Hydra has no equivalent -of a Transient ``infix''. +A Hydra “body” is equivalent to a Transient “prefix” and a Hydra +“head” is equivalent to a Transient “suffix”. Hydra has no equivalent +of a Transient “infix”. Both hydras and transients can be used as simple command dispatchers. Used like this they are similar to regular prefix commands and prefix @@ -2406,7 +2464,7 @@ command dispatchers: @item Invoking a command from a hydra does not necessarily exit the hydra. That makes it possible to invoke the same command again, but using a -shorter key sequence (i.e. the key that was used to enter the hydra +shorter key sequence (i.e., the key that was used to enter the hydra does not have to be pressed again). Transient supports that too, but for now this feature is not a focus @@ -2421,7 +2479,6 @@ using the current interface: ("n" "next visible heading" outline-next-visible-heading)]) @end lisp - @item Transient supports infix arguments; values that are set by infix commands and then consumed by the invoked suffix command(s). @@ -2465,13 +2522,13 @@ currently exist. @anchor{Can I control how the popup buffer is displayed?} @appendixsec Can I control how the popup buffer is displayed? -Yes, see @code{transient-display-buffer-action} in @ref{Other Options}. +Yes, see @code{transient-display-buffer-action} in @ref{Configuration}. @anchor{Why did some of the key bindings change?} @appendixsec Why did some of the key bindings change? You may have noticed that the bindings for some of the common commands -do @strong{not} have the prefix @code{C-x} and that furthermore some of these commands +do @strong{not} have the prefix @kbd{C-x} and that furthermore some of these commands are grayed out while others are not. That unfortunately is a bit confusing if the section of common commands is not shown permanently, making the following explanation necessary. @@ -2486,42 +2543,41 @@ bindings. The bindings that do use a prefix do so to avoid wasting too many non-prefix bindings, keeping them available for use in individual transients. The bindings that do not use a prefix and that are @strong{not} grayed out are very important bindings that are @strong{always} -available, even when invoking the ``common command key prefix'' or @strong{any +available, even when invoking the “common command key prefix” or @strong{any other} transient-specific prefix. The non-prefix keys that @strong{are} grayed out however, are not available when any incomplete prefix key sequence -is active. They do not use the ``common command key prefix'' because it +is active. They do not use the “common command key prefix” because it is likely that users want to invoke them several times in a row and -e.g. @kbd{M-p M-p M-p} is much more convenient than -@kbd{C-x M-p C-x M-p C-x M-p}. +e.g., @kbd{M-p M-p M-p} is much more convenient than @kbd{C-x M-p C-x M-p C-x M-p}. -You may also have noticed that the "Set" command is bound to @kbd{C-x s}, +You may also have noticed that the “Set” command is bound to @kbd{C-x s}, while Magit-Popup used to bind @kbd{C-c C-c} instead. I have seen several users praise the latter binding (sic), so I did not change it willy-nilly. The reason that I changed it is that using different prefix keys for different common commands, would have made the -temporary display of the common commands even more confusing, -i.e. after pressing @kbd{C-c} all the @kbd{C-x ...} bindings would be grayed out. +temporary display of the common commands even more confusing, i.e., +after pressing @kbd{C-c} all the bindings that begin with the @kbd{C-x} prefix +would be grayed out. Using a single prefix for common commands key means that all other potential prefix keys can be used for transient-specific commands -@strong{without} the section of common commands also popping up. @code{C-c} in +@strong{without} the section of common commands also popping up. @kbd{C-c} in particular is a prefix that I want to (and already do) use for Magit, and also using that for a common command would prevent me from doing so. (Also see the next question.) -@anchor{Why does @code{q} not quit popups anymore?} -@appendixsec Why does @code{q} not quit popups anymore? +@anchor{Why does @kbd{q} not quit popups anymore?} +@appendixsec Why does @kbd{q} not quit popups anymore? I agree that @kbd{q} is a good binding for commands that quit something. This includes quitting whatever transient is currently active, but it also includes quitting whatever it is that some specific transient is -controlling. The transient @code{magit-blame} for example binds @code{q} to the +controlling. The transient @code{magit-blame} for example binds @kbd{q} to the command that turns @code{magit-blame-mode} off. So I had to decide if @kbd{q} should quit the active transient (like -Magit-Popup used to) or whether @kbd{C-g} should do that instead, so -that @kbd{q} +Magit-Popup used to) or whether @kbd{C-g} should do that instead, so that @kbd{q} could be bound in individual transient to whatever commands make sense for them. Because all other letters are already reserved for use by individual transients, I have decided to no longer make an exception @@ -2548,7 +2604,7 @@ necessary changes. See its doc string for more information. @printindex vr @node Concept Index -@appendix Concept and Feature Index +@appendix Concept Index @printindex cp diff --git a/doc/misc/url.texi b/doc/misc/url.texi index a9d06d7f5b9..5644027f952 100644 --- a/doc/misc/url.texi +++ b/doc/misc/url.texi @@ -950,7 +950,6 @@ containing the data cached for that URL. @node Proxies @section Proxies and Gatewaying -@c fixme: check/document url-ns stuff @cindex proxy servers @cindex proxies @cindex environment variables diff --git a/doc/misc/vhdl-mode.texi b/doc/misc/vhdl-mode.texi index 75e8747412a..7d451c71bd4 100644 --- a/doc/misc/vhdl-mode.texi +++ b/doc/misc/vhdl-mode.texi @@ -243,7 +243,7 @@ components. Also notice that the first component, @vindex vhdl-offsets-alist @vindex offsets-alist @r{(vhdl-)} Indentation for the current line is calculated using the syntactic -component list derived in step 1 above (see @ref{Syntactic +component list derived in step 1 above (@pxref{Syntactic Analysis}). Each component contributes to the final total indentation of the line in two ways. @@ -668,7 +668,7 @@ not handled by the mode directly. @cindex custom indentation functions One of the most common ways to customize VHDL Mode is by writing @dfn{custom indentation functions} and associating them with specific -syntactic symbols (see @ref{Syntactic Symbols}). VHDL Mode itself +syntactic symbols (@pxref{Syntactic Symbols}). VHDL Mode itself uses custom indentation functions to provide more sophisticated indentation, for example when lining up selected signal assignments: @example @@ -732,7 +732,7 @@ operator on the first line of the statement. Here is the lisp code @end example @noindent Custom indent functions take a single argument, which is a syntactic -component cons cell (see @ref{Syntactic Analysis}). The +component cons cell (@pxref{Syntactic Analysis}). The function returns an integer offset value that will be added to the running total indentation for the line. Note that what actually gets returned is the difference between the column that the signal assignment @@ -928,7 +928,7 @@ If you want to customize indentation, here you go: (setq tab-width 8 ;; this will make sure spaces are used instead of tabs indent-tabs-mode nil) - ;; keybindings for VHDL are put in vhdl-mode-map + ;; key bindings for VHDL are put in vhdl-mode-map (define-key vhdl-mode-map "\C-m" 'newline-and-indent) ) diff --git a/doc/misc/viper.texi b/doc/misc/viper.texi index 0e2473ddf3c..0703667ecce 100644 --- a/doc/misc/viper.texi +++ b/doc/misc/viper.texi @@ -2571,7 +2571,7 @@ The GNU Emacs Manual}, for more information on tags. The following two commands are normally bound to a mouse click and are part of Viper. They work only if Emacs runs as an application under X -Windows (or under some other window system for which a port of GNU Emacs 20 +Windows (or under some other window system for which a port of GNU Emacs is available). Clicking the mouse when Emacs is invoked in an Xterm window (using @code{emacs -nw}) will do no good. diff --git a/doc/misc/vtable.texi b/doc/misc/vtable.texi new file mode 100644 index 00000000000..59cd9d0f564 --- /dev/null +++ b/doc/misc/vtable.texi @@ -0,0 +1,577 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename ../../info/vtable.info +@settitle Variable Pitch Tables +@include docstyle.texi +@c Merge all indexes into a single Index node. +@syncodeindex fn cp +@syncodeindex vr cp +@syncodeindex ky cp +@c %**end of header + +@copying +This file documents the GNU vtable.el package. + +Copyright @copyright{} 2022 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. A copy of the license +is included in the section entitled ``GNU Free Documentation License.'' + +(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and +modify this GNU manual.'' +@end quotation +@end copying + +@dircategory Emacs misc features +@direntry +* vtable: (vtable). Variable Pitch Tables. +@end direntry + +@finalout + +@titlepage +@title Variable Pitch Tables +@subtitle Columnar Display of Data. + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top vtable + +@insertcopying +@end ifnottex + +@menu +* Introduction:: Introduction and examples. +* Concepts:: vtable concepts. +* Making A Table:: The main interface function. +* Commands:: vtable commands. +* Interface Functions:: Interface functions. + +Appendices +* GNU Free Documentation License:: The license for this documentation. + +Indices +* Index:: +@end menu + +@node Introduction +@chapter Introduction and Tutorial + +Most modes that display tabular data in Emacs use +@code{tabulated-list-mode}, but it has some limitations: It assumes +that the text it's displaying is monospaced, which makes it difficult +to mix fonts and images in a single list. The @dfn{vtable} (``variable +pitch tables'') package tackles this instead. + +@code{tabulated-list-mode} is a major mode, and assumes that it +controls the entire buffer. A vtable doesn't assume that---you can have +a vtable in the middle of other data, or have several vtables in the +same buffer. + +Here's just about the simplest vtable that can be created: + +@lisp +(make-vtable + :objects '(("Foo" 1034) + ("Gazonk" 45))) +@end lisp + +By default, vtable uses the @code{vtable} face (which inherits from +the @code{variable-pitch} face), and right-aligns columns that have +only numerical data (and left-aligns the rest). + +You'd normally want to name the columns: + +@lisp +(make-vtable + :columns '("Name" "ID") + :objects '(("Foo" 1034) + ("Gazonk" 45))) +@end lisp + +Clicking on the column names will sort the table based on the data in +each column (which, in this example, corresponds to an element in a +list). + +By default, the data is displayed ``as is'', that is, the way +@samp{(format "%s" ...)} would display it, but you can override that. + +@lisp +(make-vtable + :columns '("Name" "ID") + :objects '(("Foo" 1034) + ("Gazonk" 45)) + :formatter (lambda (value column &rest _) + (if (= column 1) + (file-size-human-readable value) + value))) +@end lisp + +In this case, that @samp{1034} will be displayed as @samp{1k}---but +will still sort after @samp{45}, because sorting is done on the actual +data, and not the displayed data. + +Alternatively, instead of having a general formatter for the table, +you can put the formatter in the column definition: + +@lisp +(make-vtable + :columns '("Name" + (:name "ID" :formatter file-size-human-readable)) + :objects '(("Foo" 1034) + ("Gazonk" 45))) +@end lisp + +The data doesn't have to be simple lists---you can give any type of +object to vtable, but then you also have to write a function that +returns the data for each column. For instance, here's a very simple +version of @kbd{M-x list-buffers}: + +@lisp +(make-vtable + :columns '("Name" "Size" "File") + :objects (buffer-list) + :actions '("k" kill-buffer + "RET" display-buffer) + :getter (lambda (object column vtable) + (pcase (vtable-column vtable column) + ("Name" (buffer-name object)) + ("Size" (buffer-size object)) + ("File" (or (buffer-file-name object) ""))))) +@end lisp + +@var{objects} in this case is a list of buffers. To get the data to +be displayed, vtable calls the @dfn{getter} function, which is called +for each column of every object, and which should return the data that +will eventually be displayed. + +Also note the @dfn{actions}: These are simple commands that will be +called with the object under point. So hitting @kbd{@key{RET}} on a line +will result in @code{display-buffer} being called with a buffer object +as the parameter. (You can also supply a keymap to be used, but then +you have to write commands that call @code{vtable-current-object} to +get at the object.) + +Note that the actions aren't called with the data displayed in the +buffer---they're called with the original objects. + +Finally, here's an example that uses just about all the features: + +@lisp +(make-vtable + :columns `(( :name "Thumb" :width "500px" + :displayer + ,(lambda (value max-width table) + (propertize "*" 'display + (create-image value nil nil + :max-width max-width)))) + (:name "Size" :width 10 + :formatter file-size-human-readable) + (:name "Time" :width 10 :primary ascend) + "Name") + :objects-function (lambda () + (directory-files "/tmp/" t "\\.jpg\\'")) + :actions '("RET" find-file) + :getter (lambda (object column table) + (pcase (vtable-column table column) + ("Name" (file-name-nondirectory object)) + ("Thumb" object) + ("Size" (file-attribute-size (file-attributes object))) + ("Time" (format-time-string + "%F" (file-attribute-modification-time + (file-attributes object)))))) + :separator-width 5 + :keymap (define-keymap + "q" #'kill-buffer)) +@end lisp + +This vtable implements a simple image browser that displays image +thumbnails (that change sizes dynamically depending on the width of +the column), human-readable file sizes, date and file name. The +separator width is 5 typical characters wide. Hitting @kbd{@key{RET}} on a +line will open the image in a new window, and hitting @kbd{q} will +kill a buffer. + +@node Concepts +@chapter Concepts + +@cindex vtable +A vtable lists data about a number of @dfn{objects}. Each object can +be a list or a vector, but it can also be anything else. + +@cindex getter of a vtable +To get the @dfn{value} for a particular column, the @dfn{getter} +function is called on the object. If no getter function is defined, +the default is to try to index the object as a sequence. In any case, +we end up with a value that is then used for sorting. + +@cindex formatter of a vtable +This value is then @dfn{formatted} via a @dfn{formatter} function, +which is called with the @dfn{value} as the argument. The formatter +commonly makes the value more reader friendly. + +@cindex displayer of a vtable +Finally, the formatted value is passed to the @dfn{displayer} +function, which is responsible for putting the table face on the +formatted value, and also ensuring that it's not wider than the column +width. The displayer will commonly truncate too-long strings and +scale image sizes. + +All these three transforms, the getter, the formatter and the display +functions, can be defined on a per-column basis, and also on a +per-table basis. (The per-column transform takes precedence over the +per-table transform.) + +User commands that are defined on a table does not work on the +displayed data. Instead they are called with the original object as +the argument. + +@node Making A Table +@chapter Making A Table + +@findex make-vtable +The interface function for making (and optionally inserting a table +into a buffer) is @code{make-vtable}. It returns a table object. + +The keyword parameters are described below. + +There are many callback interface functions possible in +@code{make-vtable}, and many of them take a @var{object} argument (an +object from the @code{:objects} list), a column index argument (an +integer starting at zero), and a table argument (the object returned +by @code{make-vtable}). + +@table @code +@item :objects +This is a list of objects to be displayed. It should either be a list +of strings (which will then be displayed as a single-column table), or +a list where each element is a sequence containing a mixture of +strings, numbers, and other objects that can be displayed ``simply''. + +In the latter case, if @code{:columns} is non-@code{nil} and there's +more elements in the sequence than there is in @code{:columns}, only +the @code{:columns} first elements are displayed. + +@item :objects-function +It's often convenient to generate the objects dynamically (for +instance, to make reversion work automatically). In that case, this +should be a function (which will be called with no arguments), and +should return a value as accepted as an @code{:objects} list. + +@item :columns +This is a list where each element is either a string (the column +name), a plist of keyword/values (to make a @code{vtable-column} +object), or a full @code{vtable-column} object. A +@code{vtable-column} object has the following slots: + +@table @code +@item name +The name of the column. + +@item width +The width of the column. This is either a number (the width of that +many @samp{x} characters in the table's face), or a string on the form +@samp{Xe@var{x}}, where @var{x} is a number of @samp{x} characters, or a +string on the form @samp{Xp@var{x}} (denoting a number of pixels), or a +string on the form @samp{X%} (a percentage of the window's width). + +@item min-width +This uses the same format as @code{width}, but specifies the minimum +width (and overrides @code{width} if @code{width} is smaller than this. + +@item max-width +This uses the same format as @code{width}, but specifies the maximum +width (and overrides @code{width} if @code{width} is larger than this. +@code{min-width}/@code{max-width} can be useful if @code{width} is +given as a percentage of the window width, and you want to ensure that +the column doesn't grow pointlessly large or unreadably narrow. + +@item primary +Whether this is the primary column---this will be used for initial +sorting. This should be either @code{ascend} or @code{descend} to say +in which order the table should be sorted. + +@item getter +If present, this function will be called to return the column value. + +@defun column-getter object table +It's called with two parameters: the object and the table. +@end defun + +@item formatter +If present, this function will be called to format the value. + +@defun column-formatter value +It's called with one parameter: the column value. +@end defun + +@item displayer +If present, this function will be called to prepare the formatted +value for display. This function should return a string with the +table face applied, and also limit the width of the string to the +display width. + +@defun column-displayer fvalue max-width table +@var{fvalue} is the formatted value; @var{max-width} is the maximum +width (in pixels), and @var{table} is the table. +@end defun + +@item align +Should be either @code{right} or @code{left}. +@end table + +@item :getter +If given, this is a function that should return the values to use in +the table, and will be called once for each element in the table +(unless overridden by a column getter function). + +@defun getter object index table +For a simple object (like a sequence), this function will typically +just return the element corresponding to the column index (zero-based), but the +function can do any computation it wants. If it's more convenient to +write the function based on column names rather than the column index, +the @code{vtable-column} function can be used to map from index to name. +@end defun + +@item :formatter +If present, this is a function that should format the value, and it +will be called on all values in the table (unless overridden by a +column formatter). + +@defun formatter value index table +This function is called with three parameters: the value (as returned +by the getter); the column index, and the table. It can return any +value. + +This can be used to (for instance) format numbers in a human-readable +form. +@end defun + +@item :displayer +Before displaying an element, it's passed to the displaying function +(if any). + +@defun displayer fvalue index max-width table +This is called with four arguments: the formatted value of the element +(as returned by the formatter function); the column index; the display +width (in pixels); and the table. + +This function should return a string with the table face applied, and +truncated to the display width. + +This can be used to (for instance) change the size of images that are +displayed in the table. +@end defun + +@item :use-header-line +If non-@code{nil} (which is the default), display the column names on +the header line. This is the most common use +case, but if there's other text in the buffer before the table, or +there are several tables in the same buffer, then this should be +@code{nil}. + +@item :face +The face to be used. This defaults to @code{vtable}. This face +doesn't override the faces in the data, or the faces supplied by the +getter and formatter functions. + +@item :row-colors +If present, this should be a list of color names to be used as the +background color on the rows. If there are fewer colors here than +there are rows, the rows will be repeated. The most common use +case here is to have alternating background colors on the rows, so +this would usually be a list of two colors. This can also be a list +of faces to be used. + +@item :column-colors +If present, this should be a list of color names to be used as the +background color on the columns. If there are fewer colors here than +there are columns, the colors will be repeated. The most common use +case here is to have alternating background colors on the columns, so +this would usually be a list of two colors. This can also be a list +of faces to be used. If both @code{:row-colors} and +@code{:column-colors} is present, the colors will be ``blended'' to +produce the final colors in the table. + +@item :actions +This uses the same syntax as @code{define-keymap}, but doesn't refer +to commands directly. Instead each key is bound to a command that +picks out the current object, and then calls the function specified +with that as the argument. + +@item :keymap +This is a keymap used on the table. The commands here are called as +usual, and if they're supposed to work on the object displayed on the +current line, they can use the @code{vtable-current-object} function +(@pxref{Interface Functions}) to determine what that object is. + +@item :separator-width +The width of the blank space between columns. + +@item :divider-width +@itemx :divider +You can have a divider inserted between the columns. This can either +be specified by using @code{:divider}, which should be a string to be +displayed between the columns, or @code{:divider-width}, which +specifies the width of the space to be used as the divider. + +@item :sort-by +This should be a list of tuples, and specifies how the table is to be +sorted. Each tuple should consist of an integer (the column index) +and either @code{ascend} or @code{descend}. + +The table is first sorted by the first element in this list, and then +the next, until the end is reached. + +@item :ellipsis +By default, when shortening displayed values, an ellipsis will be +shown. If this is @code{nil}, no ellipsis is shown. (The text to use +as the ellipsis is determined by the @code{truncate-string-ellipsis} +function.) + +@findex vtable-insert +@item :insert +By default, @code{make-vtable} will insert the table at point. If this +is @code{nil}, nothing is inserted, but the vtable object is returned, +and you can insert it later with the @code{vtable-insert} function. +@end table + +@code{make-table} returns a @code{vtable} object. You can access the +slots in that object by using accessor functions that have names based +on the keywords described above. For instance, to access the face, +use @code{vtable-face}. + +@node Commands +@chapter Commands +@cindex vtable commands + +When point is placed on a vtable, the following keys are bound: + +@table @kbd +@findex vtable-sort-by-current-column +@item S +Sort the table by the current column +(@code{vtable-sort-by-current-column}). Note that the table is sorted +according to the data returned by the getter function (@pxref{Making A +Table}), not by how it's displayed in the buffer. Columns that have +only numerical data are sorted as numbers, the rest are sorted as +strings. + +@findex vtable-narrow-current-column +@item @{ +Make the current column narrower +(@code{vtable-narrow-current-column}). + +@findex vtable-widen-current-column +@item @} +Make the current column wider +(@code{vtable-widen-current-column}). + +@findex vtable-previous-column +@item M-<left> +Move to the previous column (@code{vtable-previous-column}). + +@findex vtable-next-column +@item M-<right> +Move to the next column (@code{vtable-next-column}). + +@findex vtable-revert-command +@item g +Regenerate the table (@code{vtable-revert-command}). This command +mostly makes sense if the table has a @code{:objects-function} that +can fetch new data. +@end table + +@node Interface Functions +@chapter Interface Functions + +If you need to write a mode based on vtable, you will have to interact +with the table in +various ways---for instance, you'll need to write commands that +updates an object +and then displays the result. This chapter describes functions for +such interaction. + +@defun vtable-current-table +This function returns the table under point. +@end defun + +@defun vtable-current-object +This function returns the object on the current line. (Note that this +is the original object, not the characters displayed in the +buffer.) +@end defun + +@defun vtable-current-column +This function returns the column index of the column under point. +@end defun + +@defun vtable-goto-table table +Move point to the start of @var{table} and return the position. If +@var{table} can't be found in the current buffer, don't move point and +return @code{nil}. +@end defun + +@defun vtable-goto-object object +Move point to the start of the line where @var{object} is displayed in +the current table and return the position. If @var{object} can't be found, +don't move point and return @code{nil}. +@end defun + +@defun vtable-goto-column index +Move point to the start of the @var{index}th column. (The first +column is numbered zero.) +@end defun + +@defun vtable-beginning-of-table +Move to the beginning of the current table. +@end defun + +@defun vtable-end-of-table +Move to the end of the current table. +@end defun + +@defun vtable-remove-object table object +Remove @var{object} from @var{table}. This also updates the displayed +table. +@end defun + +@defun vtable-insert-object table object &optional after-object +Insert @var{object} into @var{table}. If @var{after-object}, insert +the object after this object; otherwise append to @var{table}. This +also updates the displayed table. +@end defun + +@defun vtable-update-object table object old-object +Change @var{old-object} into @var{object} in @var{table}. This also +updates the displayed table. + +This has the same effect as calling @code{vtable-remove-object} and +then @code{vtable-insert-object}, but is more efficient. +@end defun + +@defun vtable-column table index +Return the column name of the @var{index}th column in @var{table}. +@end defun + +@node GNU Free Documentation License +@chapter GNU Free Documentation License +@include doclicense.texi + +@node Index +@unnumbered Index +@printindex cp + +@bye |