diff options
Diffstat (limited to 'doc/emacs')
35 files changed, 1590 insertions, 514 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 094b8b11f6a..6ed43bcb790 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 @@ -2376,8 +2394,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 @@ -2530,7 +2548,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 @@ -2580,13 +2598,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 @@ -2596,24 +2614,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. @@ -2789,18 +2806,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..292c986c1c6 100644 --- a/doc/emacs/dired.texi +++ b/doc/emacs/dired.texi @@ -122,7 +122,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 +748,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 +776,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 +804,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 +844,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 +983,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 +1044,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 +1081,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 @@ -1114,9 +1170,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 +1333,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 +1580,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 +1638,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 +1743,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..b87ca81faea 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -24,6 +24,7 @@ the text is displayed. * Faces:: How to change the display style using faces. * Colors:: Specifying colors for faces. * Standard Faces:: The main predefined faces. +* Icons:: How to change how icons look. * Text Scale:: Increasing or decreasing text size in a buffer. * Font Lock:: Minor mode for syntactic highlighting using faces. * Highlight Interactively:: Tell Emacs what text to highlight. @@ -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,43 @@ This face is used to display on text-mode terminals the menu item that would be selected if you click a mouse or press @key{RET}. @end table +@node Icons +@section Icons + +Emacs sometimes displays clickable buttons (or other informative +icons), and the look of these can be customized by the user. + +@vindex icon-preference +The main customization point here is the @code{icon-preference} user +option. By using this, you can tell Emacs your overall preferences +for icons. This is a list of icon types, and the first icon type +that's supported will be used. The supported types are: + +@table @code +@item image +Use an image for the icon. + +@item emoji +Use a colorful emoji for the icon. + +@item symbol +Use a monochrome symbol for the icon. + +@item text +Use a simple text for the icon. +@end table + +In addition, each individual icon can be customized with @kbd{M-x +customize-icon}, and themes can further alter the looks of the icons. + +To get a quick description of an icon, use the @kbd{M-x describe-icon} +command. + @node Text Scale @section Text Scale -@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 +896,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 +926,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 +1071,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 +1654,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 +1771,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 +1961,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 +2159,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..404978b315d 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,11 +2269,11 @@ 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} +@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 specifying a scale factor, use the command @code{image-transform-set-scale} bound to @kbd{s s}. @@ -2291,6 +2355,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/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 979be34fac7..4e71793b66e 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..841a285520a 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -455,20 +455,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 +856,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 +896,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 +1520,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 +1643,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 +1726,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 +1797,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 +2046,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 +2783,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, @@ -2942,6 +3012,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..e30d623a77c 100644 --- a/doc/emacs/msdos.texi +++ b/doc/emacs/msdos.texi @@ -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..27d4db85412 100644 --- a/doc/emacs/search.texi +++ b/doc/emacs/search.texi @@ -422,7 +422,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 +436,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 +463,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 +899,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 +1027,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 +1048,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 +1119,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 +1190,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 +1211,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 +1465,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 +1829,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..8915d2025ba 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,49 @@ 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. + @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 +447,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 +466,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 +615,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 +625,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. |