diff options
Diffstat (limited to 'doc/emacs')
33 files changed, 882 insertions, 425 deletions
diff --git a/doc/emacs/anti.texi b/doc/emacs/anti.texi index 49da473fa51..3b02187b5cb 100644 --- a/doc/emacs/anti.texi +++ b/doc/emacs/anti.texi @@ -4,156 +4,138 @@ @c See file emacs.texi for copying conditions. @node Antinews -@appendix Emacs 26 Antinews +@appendix Emacs 27 Antinews @c Update the emacs.texi Antinews menu entry with the above version number. For those users who live backwards in time, here is information -about downgrading to Emacs version 26.3. We hope you will enjoy the +about downgrading to Emacs version 27.2. We hope you will enjoy the greater simplicity that results from the absence of many @w{Emacs @value{EMACSVER}} features. @itemize @bullet @item -Emacs no longer uses @acronym{GMP}, the GNU Multiple Precision -library, and doesn't support Lisp integers greater than -@code{most-positive-fixnum} or smaller than -@code{most-negative-fixnum}. We now have only one kind of a Lisp -integer. This simplifies many Lisp programs that use integers, and -makes integer calculations always fast. If you want larger values, -use Lisp floats, as Emacs has done since day one. +Emacs can no longer be built with support of native compilation of +Lisp programs. This means Emacs builds much faster, and the problems +that came with native compilation: the need to have GCC and Binutils +installed, the complications of managing your @file{eln-cache} +directories---all of that is now future history. The simplicity and +elegance of the Emacs byte-compiled code is now restored in all of its +pristine beauty. @item -Emacs no longer supports HarfBuzz as the engine for shaping complex -text. As you move back in time, we will gradually shed off all traces -of support for complex text shaping, and this is one step in that -direction. +Emacs no longer builds by default with Cairo, even if it's present. +The warnings about not using HarfBuzz are also gone, in preparation +for complete removal of HarfBuzz support in previous Emacs versions. +Fancy text shaping and display is becoming less important as you move +back in time. The @code{ftx} font backend is again part of Emacs, for +the same reasons. @item -We have removed support for building with the Jansson library, and -consequently the native support for JSON parsing is gone. The -importance of JSON decreases as we go back in time, so for now using -the Lisp code for handling it should be good enough; in one of the -past Emacs versions, we intend to remove even that, as useless bloat. - -The library for supporting JSONRPC applications was removed for the -same reason. +As Motif becomes more and more important with moving farther into the +past, we've reinstated the code which supports Motif in Emacs. @item -The ``portable dumper'' feature is gone. We are once again using the -field-proven ``unexec'' way of dumping Emacs. With that, the hope for -being able to re-dump your customized Emacs session is also gone: why -would anyone want to record their random customization experiments on -disk, and restore them the next time they start Emacs? And true -Emacsers don't restart their Emacs sessions anyway. +Emacs once again supports versions 5.3 and older OpenBSD systems, +which will be needed as you move back in time. @item -We dropped the support for @acronym{XDG}-style configuration -directories and the @env{XDG_CONFIG_HOME} environment variable. -There's once again only one place where Emacs looks for its init -files: the @file{~/.emacs.d} directory, with the @file{~/.emacs} file -as fallback. We think this will go a long way towards preventing -confusion among users who for some reason have @env{XDG_CONFIG_HOME} -set, thus risking to have their init files randomly spread between two -places. In one of the past Emacs versions, we intend to further -simplify this, removing the @file{~/.emacs.d} place and leaving only -@file{~/.emacs}; stay tuned. - -For similar reasons, we've removed the ``early init'' file. You can -now again use all the tricks you want to initialize variables like -@code{package-user-dir} and @code{package-load-list} just in time for -the packages to load. +We've dropped support for Secure Computing filter on GNU/Linux. The +past world is much more secure than the present, so the complexities +related with this stuff, which can only be explained by severe +paranoia, are no longer justified. -@command{emacsclient} no longer supports @acronym{XDG}-style directory -trees, either. +@item +Emacs reverted back to supporting Unicode 13.x, since the following +versions of the standards are not yet published where you are going. +The @samp{emoji} script and the support for displaying Emoji sequences +were removed for the same reasons: no one will produce them in the +past. @item -TLS connections are back to their lenient security settings. We -decided that too tight security settings are an annoyance for users, -and make little sense considering the world-wide tendency to have -fewer and fewer network security problems as we move back in time -(those issues will be completely gone when networks disappear in some -distant past). +Mode-specific commands and the @kbd{M-S-x} command that invokes them +were removed. As you move back in time, the command set in Emacs +becomes smaller, so any such filtering of applicable commands just +gets in the way. @item -The @code{server-after-make-frame-hook} hook was deleted, in -preparation for removing the entire daemon business in some past Emacs -version. You will be glad to learn that setting up the GUI -customizations of your sessions is now once again as easy as it ever -was, with just the @code{after-make-frame-functions} to use. +We have removed the system for displaying documentation of groups of +related functions, the @kbd{shortdoc-display-group} command to go with +it, and the corresponding ``See also'' button in the @file{*Help*} +buffer. That should make searching for certain functions simpler: +just use the venerable @samp{apropos} commands. @item -The @code{flex} completion style was removed. We feel that it -unnecessarily complicates the Emacs user experience, and therefore -will continue to remove other tricky completion styles, until in some -past Emacs version we get to a single original style Emacs pioneered -decades ago. Long live simplicity; down with complications! +The @code{context-menu-mode} was removed, and with it the context +menus popped by pressing the right mouse button. This is one small +step towards freeing Emacs (and eventually, the whole world of +computing) from the tyranny of the GUI pointing devices in general, +and moving back to the simplicity of text-mode user interfaces. +Down with mice and other rodents! @item -The optional display of the fill-column indicator is no longer -supported. With the display sizes becoming smaller and smaller as you -move back in time, we feel that the display itself will always show -you where to fill or wrap your text, and do this much more easily and -reliably than any such display indicator. +The commands @kbd{C-x 4 4} and @kbd{C-x 5 5} for displaying the +results in a new window/frame re gone. We are quite certain that +creating a new window/frame before running a command is much simpler, +and doesn't require a complication of a new prefix. @item -We removed the features that made visiting large files easier. Thus, -Emacs will no longer suggest visiting a large file literally, nor -offer the @code{so-long} mode to deal with overly-long lines. We -decided that this simplification is worthwhile, given that the general -tendency of having very large files is becoming a rarity as we move -back in time. +The behavior of active minibuffers when switching frames is now the +perfect mess it should be: sometimes the minibuffer moves to the new +selected frame, sometimes it doesn't, and sometimes you get an error. +This makes Emacs usage much more fun, as you get to guess the result, +instead of having it boringly consistent. @item -We have removed the feature that displayed echo-area messages without -hiding content of the active minibuffer. This should prevent user -confusion from having two unrelated pieces of text staring at them, -with no clear separation between them. Users with good memories (and -Emacs users are all expected to be of that kind) will have no trouble -keeping the minibuffer text in their minds, and typing the responses -without actually seeing the prompts. +Compact mode-line display mode has been removed. The items displayed +on the mode line are now always in the same place, and if there's not +enough space for them, they are not displayed at all, instead of being +confusingly displayed in a different position. You no longer need to +think twice where to find a particular mode-line element on display. @item -Horizontal scrolling using the mouse or touchpad has been removed. In -the past, wide monitors will become less popular, so horizontal -scrolling will no longer be needed. Removal of the mouse support for -horizontal scrolling is the first step towards its complete removal in -prior Emacs versions. +Many commands and options related to tab bars were removed, including +(but not limited to) frame-specific appearance of tab bars, the +@code{tab-bar-format} option, the @kbd{C-x t n}, @kbd{C-x t N}, +@kbd{C-x t M}, and @kbd{C-x t G} commands, and many mouse gestures on +the tab bar. We are going to delete the tab bar support from Emacs in +one of the past versions, and this is a step in that direction. @item -The @code{main-thread} variable and @code{list-threads} were removed, -and @code{thread-join} no longer returns the result of the finished -thread. We intend to remove the support for Lisp threads in some past -Emacs version, so we continue removing the associated complexities and -features as we go back in time. +The ``transient'' input methods have been removed; use @kbd{C-\} to +turn input methods on and off instead. This is in preparation for +complete removal of input methods from Emacs in version 19, and +consistent with the fact that the number of input methods we support +becomes smaller as you move back in time. @item -Tab bar and window tab-lines were removed. This should make the Emacs -display simpler and less cluttered, and help those users who disable -menu bar and tool bar in their GUI sessions. The fashion to provide -tabs in every GUI application out there is gaining less and less -popularity as we move back in time, and will completely disappear at -some past point; removing the tabs from Emacs is the step in that -direction. +We disabled @code{show-paren-mode} by default, since we think the +venerable @code{blink-matching-paren} feature is more than enough, and +better fits the simplicity of past Emacs versions. It will definitely +be better when colors are removed from Emacs in the distant past. + +For the same reason, sub-groups in interactive regexp searches are no +longer highlighted in distinct colors. @item -Displaying line numbers for a buffer is only possibly using add-on -features, such as @code{linum-mode}, which can only display the -numbers in the display margins. Line-number display using these -features is also slow, as we firmly believe such a feature is -un-Emacsy and should not have been included in Emacs to begin with. -Consequently, @code{display-line-numbers-mode} was removed. +On our permanent quest for simplifying Emacs, we've removed the Ispell +command @code{ispell-comment-or-string-at-point}; the old-time friend +@code{ispell-comments-and-strings} should suffice. @item -On our permanent quest for simplifying Emacs, we've removed the -support for changing the font size by turning the mouse wheel. +Many Gnus commands and options were deemed to unnecessarily complicate +the use of Gnus (which is too complex to begin with), and thus were +removed. This includes @code{gnus-topic-display-predicate}, +@code{gnus-process-mark-toggle}, @code{gnus-registry-register-all}, +@code{gnus-paging-select-next}, and many others. The @code{nnselect} +backend was deleted for the same reason. @item -Several commands, deemed to be unnecessary complications, have been -removed. Examples include @code{make-empty-file}, -@code{font-lock-refontify}, @code{xref-find-definitions-at-mouse}, -@code{make-frame-on-monitor}, and @code{diff-buffers}. +The @file{project.el} package have been redesigned to remove many +unnecessary features, so that just the bare essentials remain. We +plan on removing this package from Emacs in a previous version, but +decided to begin with removing some extra features first. @item To keep up with decreasing computer memory capacity and disk space, many -other functions and files have been eliminated in Emacs 26.3. +other functions and files have been eliminated in Emacs 27.2. @end itemize diff --git a/doc/emacs/back.texi b/doc/emacs/back.texi index ae0121e1a88..dc4e218d378 100644 --- a/doc/emacs/back.texi +++ b/doc/emacs/back.texi @@ -48,6 +48,7 @@ The ability to: Create @strong{PostScript output} from plain-text files (special editing modes for @LaTeX{} and @TeX{} are included). + @item @strong{Compile} and @strong{debug} from inside Emacs. @@ -67,7 +68,7 @@ Enjoy the use of extensive @strong{merge} and @strong{diff} functions. @item Take advantage of built-in support for many @strong{version control -systems}, including Git, Mercurial, Bazaar, Subversion, and CVS. +systems,} including Git, Mercurial, Bazaar, Subversion, and CVS. @item And much more! @@ -82,8 +83,8 @@ useful to expert users. It also includes appendices with specific material about X and GTK resources, and with details for users of macOS and Microsoft Windows. -And when you tire of all the work you can accomplish with it, Emacs -contains games to play. +And when you tire of all the work you can accomplish with Emacs, enjoy +the games that come with it. @strong{About the original and principal author:} @@ -92,8 +93,10 @@ Emacs in 1984/85. He has received the ACM Grace Hopper Award, a MacArthur Foundation fellowship, the Electronic Frontier Foundation's Pioneer award, the Takeda Award for Social/Economic Betterment, and the ACM Software and System Award, as well as several doctorates -honoris causa. +@emph{honoris causa.} @end quotation @hfil @bye + ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi index ba8d822b18e..c4fa0d64ed7 100644 --- a/doc/emacs/basic.texi +++ b/doc/emacs/basic.texi @@ -887,15 +887,19 @@ z z z}. The first @kbd{C-x z} repeats the command once, and each subsequent @kbd{z} repeats it once again. @findex repeat-mode - Also you can activate @code{repeat-mode} that temporarily enables -a transient mode with short keys after a limited number of commands. +@vindex repeat-exit-key +@vindex repeat-exit-timeout + Also you can activate @code{repeat-mode} that temporarily enables a +transient mode with short keys after a limited number of commands. Currently supported shorter key sequences are @kbd{C-x u u} instead of @kbd{C-x u C-x u} to undo many changes, @kbd{C-x o o} instead of @kbd{C-x o C-x o} to switch several windows, @kbd{C-x @{ @{ @} @} ^ ^ v v} to resize the selected window interactively, @kbd{M-g n n p p} to -navigate @code{next-error} matches. Any other key exits transient mode -and then is executed normally. The user option @code{repeat-exit-key} -defines an additional key to exit this transient mode. Also it's -possible to break the repetition chain automatically after idle time -by customizing the user option @code{repeat-exit-timeout} to a number -of seconds. +navigate @code{next-error} matches, and @kbd{C-x ] ] [ [} to navigate +through pages. Any other key exits transient mode and then is +executed normally. The user option @code{repeat-exit-key} defines an +additional key to exit this transient mode. Also it's possible to +break the repetition chain automatically after some idle time by +customizing the user option @code{repeat-exit-timeout} to specify the +idle time in seconds after which this transient mode will be turned +off. diff --git a/doc/emacs/book-spine.texi b/doc/emacs/book-spine.texi index 20e23ca2bf8..9634cceedaf 100644 --- a/doc/emacs/book-spine.texi +++ b/doc/emacs/book-spine.texi @@ -13,7 +13,7 @@ @center @titlefont{GNU Emacs Manual} @sp 5 -@center @value{EDITION} edition, for Emacs Version @value{EMACSVER} +@center @value{EDITION} edition, for Emacs version @value{EMACSVER} @sp 5 @center by Richard M.@: Stallman et al. diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index 8de93867baa..f9ea1b390f7 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -213,7 +213,6 @@ Select a buffer to be used by next invocation of @code{next-error} and @kindex M-g n @kindex C-x ` @findex next-error -@findex next-error-message @vindex next-error-message-highlight @vindex next-error-highlight @vindex next-error-highlight-no-select @@ -263,7 +262,9 @@ to skip any messages. highlights the relevant source line. The duration of this highlight is determined by the variable @code{next-error-highlight} for the locus in the selected buffer, and @code{next-error-highlight-no-select} for -the locus in non-selected buffers. +the locus in non-selected buffers. Also you can customize the variable +@code{next-error-message-highlight} that defines how to highlight the +current error message in the buffer that contains messages. @vindex compilation-context-lines If the @file{*compilation*} buffer is shown in a window with a left @@ -1491,7 +1492,7 @@ Emacs Lisp Reference Manual}. code not unlike the one produced by a C or Fortran compiler. Native code runs even faster than byte-code. Natively-compiled Emacs Lisp code is stored in files whose names end in @samp{.eln}. @xref{Native -Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual}. +Compilation,, Native Compilation, elisp, the Emacs Lisp Reference Manual}. @findex load-file To @dfn{load} an Emacs Lisp file, type @kbd{M-x load-file}. This diff --git a/doc/emacs/calendar.texi b/doc/emacs/calendar.texi index 3750e78e709..18de721e288 100644 --- a/doc/emacs/calendar.texi +++ b/doc/emacs/calendar.texi @@ -1363,6 +1363,20 @@ the 11 above to @samp{'(1 2 3)} and have the entry apply to the last Thursday of January, February, and March. If the month is @code{t}, the entry applies to all months of the year. +@findex diary-offset +@example +%%(diary-offset '(diary-float t 3 4) 2) Monthly committee meeting +@end example + +@noindent +This entry applies to the Saturday after the third Thursday of each +month. The 2 specifies number of days after when the sexp +@w{@code{'(diary-float t 3 4)}} would evaluate to @code{t}. This is +useful when for example your organization has a committee meeting two +days after every monthly meeting which takes place on the third +Thursday, or if you would like to attend a virtual meeting scheduled +in a different timezone causing a difference in the date. + Each of the standard sexp diary entries takes an optional parameter specifying the name of a face or a single-character string to use when marking the entry in the calendar. Most generally, sexp diary entries diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi index b7f0bda7851..86c04c84a2a 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 @@ -266,6 +271,11 @@ disables auto-saving except in buffers for which auto-saving is explicitly requested, and when saving files it omits the @code{fsync} system call unless otherwise requested. +@vindex backtrace-on-error-noninteractive +Errors that occur when running a @samp{--batch} Emacs will result in +an Emacs Lisp backtrace being printed. To disable this behavior, set +@code{backtrace-on-error-noninteractive} to @code{nil}. + @item --script @var{file} @opindex --script @cindex script mode diff --git a/doc/emacs/commands.texi b/doc/emacs/commands.texi index 82a917ce7d1..f56f820b399 100644 --- a/doc/emacs/commands.texi +++ b/doc/emacs/commands.texi @@ -121,7 +121,7 @@ C-k} is two key sequences, not one. By default, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-h}, @kbd{C-x}, @kbd{C-x @key{RET}}, @kbd{C-x @@}, @kbd{C-x a}, @kbd{C-x n}, @kbd{C-x r}, @kbd{C-x t}, @kbd{C-x v}, @kbd{C-x 4}, @kbd{C-x 5}, -@kbd{C-x 6}, @key{ESC}, @kbd{M-g}, and @kbd{M-o}. (@key{F1} and +@kbd{C-x 6}, @key{ESC}, and @kbd{M-g}. (@key{F1} and @key{F2} are aliases for @kbd{C-h} and @kbd{C-x 6}.) This list is not cast in stone; if you customize Emacs, you can make new prefix keys. You could even eliminate some of the standard ones, though this is not diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 999234e6d33..d9d6a680057 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 @@ -1084,8 +1084,9 @@ first line: @noindent You can specify any number of variable/value pairs in this way, each pair with a colon and semicolon. The special variable/value pair -@code{mode: @var{modename};}, if present, specifies a major mode. The -@var{value}s are used literally, and not evaluated. +@code{mode: @var{modename};}, if present, specifies a major mode +(without the ``-mode'' suffix). The @var{value}s are used literally, +and not evaluated. @findex add-file-local-variable-prop-line @findex delete-file-local-variable-prop-line @@ -1473,9 +1474,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 @@ -1491,6 +1493,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"))) @@ -1500,13 +1506,15 @@ 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 +@code{"remotemachine"} as host name. Such a criteria can also discriminate for the properties @code{:protocol} (this is the Tramp method) or @code{:user} (a remote user name). The @code{nil} criteria matches all buffers with a remote default directory. @@ -1721,6 +1729,17 @@ previous ones, but they are specifically for file name completion. They do not bind @key{SPC}. @end itemize +By default, @key{TAB}, @key{SPC} and @key{?} do completion in +@code{minibuffer-local-completion-map}. If you commonly complete over +collections that have elements with space or question mark characters in +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) +@end lisp + @node Rebinding @subsection Changing Key Bindings Interactively @cindex key rebinding, this session @@ -2355,14 +2374,19 @@ function @code{setq} to set the variable @code{fill-column} (@pxref{Filling}) to 60. You can set any Lisp variable with @code{setq}, but with certain -variables @code{setq} won't do what you probably want in the -init file. Some variables automatically become buffer-local -when set with @code{setq}; what you want in the init file is to set -the default value, using @code{setq-default}. Some customizable minor -mode variables do special things to enable the 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. The -following section has examples of both of these methods. +variables @code{setq} won't do what you probably want in the init +file. Some variables automatically become buffer-local when set with +@code{setq}; what you want in the init file is to set the default +value, using @code{setq-default}. (The following section has examples +of both of these methods.) + +Some customizable minor mode variables do special things to enable the +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}). 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 @@ -2511,6 +2535,14 @@ Turn on Auto Fill mode automatically in Text mode and related modes @end example @item +Change the coding system used when using the clipboard +(@pxref{Communication Coding}). + +@example +(customize-set-variable 'selection-coding-system 'utf-8) +@end example + +@item Load the installed Lisp library named @file{foo} (actually a file @file{foo.elc} or @file{foo.el} in a standard Emacs directory). @@ -2783,12 +2815,12 @@ Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}. @cindex early init file Most customizations for Emacs should be put in the normal init file. -@xref{Init File}. However, it is sometimes desirable -to have customizations that take effect during Emacs startup earlier than the +@xref{Init File}. However, it is sometimes necessary +to have customizations take effect during Emacs startup earlier than the normal init file is processed. Such customizations can be put in the early init file, @file{~/.config/emacs/early-init.el} or @file{~/.emacs.d/early-init.el}. This file is loaded before the package system and GUI is initialized, so in it you can customize variables -that affect frame appearance as well as the package initialization process, +that affect the package initialization process, such as @code{package-enable-at-startup}, @code{package-load-list}, and @code{package-user-dir}. Note that variables like @code{package-archives} which only affect the installation of new packages, and not the process of diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi index 3fbaf8bab7a..704850e584c 100644 --- a/doc/emacs/dired.texi +++ b/doc/emacs/dired.texi @@ -823,7 +823,9 @@ link. Change the mode (also called @dfn{permission bits}) of the specified files (@code{dired-do-chmod}). @var{modespec} can be in octal or symbolic notation, like arguments handled by the @command{chmod} -program. +program. This command does not follow symbolic links, so it reports +an error if you try to change the mode of a symbolic link on a +platform where such modes are immutable. @findex dired-do-chgrp @kindex G @r{(Dired)} @@ -850,8 +852,8 @@ different systems put @command{chown} in different places). @cindex changing file time (in Dired) @item T @var{timestamp} @key{RET} Touch the specified files (@code{dired-do-touch}). This means -updating their modification times to the present time. This is like -the shell command @code{touch}. +updating their modification times to @var{timestamp}, which defaults +to the present time. This is like the shell command @command{touch}. @findex dired-do-print @kindex P @r{(Dired)} @@ -1505,16 +1507,14 @@ buffer containing image-dired, corresponding to the marked files. You can also enter Image-Dired directly by typing @kbd{M-x 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. This -takes a long time if the directory contains many image files, and it -asks for confirmation if the number of image files exceeds -@code{image-dired-show-all-from-dir-max-files}. +directory, and displays them all in the thumbnail buffer. The +thumbnails are generated in the background and are loaded as they +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 @@ -1553,6 +1553,11 @@ image. You comment a file from the thumbnail buffer by typing @kbd{c}. You will be prompted for a comment. Type @kbd{C-t c} to add a comment from Dired (@code{image-dired-dired-comment-files}). +@vindex image-dired-thumb-visible-marks + Files that are marked in Dired will also be marked in Image-Dired if +@code{image-dired-thumb-visible-marks} is non-@code{nil} (which is the +default). + Image-Dired also provides simple image manipulation. In the thumbnail buffer, type @kbd{L} to rotate the original image 90 degrees anti clockwise, and @kbd{R} to rotate it 90 degrees clockwise. This diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index ae345c11df5..7ea754612ee 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -150,6 +150,14 @@ gives you less jerky scrolling when you hold down @kbd{C-v}, but the window contents after any action which scrolls into a fresh portion of the buffer will be momentarily unfontified. +@vindex redisplay-skip-fontification-on-input +Finally, a third alternative to these variables is +@code{redisplay-skip-fontification-on-input}. If this variable is +non-@code{nil}, skip some fontifications is there's input pending. +This usually does not affect the display because redisplay is +completely skipped anyway if input was pending, but it can make +scrolling smoother by avoiding unnecessary fontification. + @vindex scroll-up @vindex scroll-down @findex scroll-up-line @@ -1767,6 +1775,10 @@ multiple screen lines. Setting the variable @code{truncate-lines} in any way makes it local to the current buffer; until that time, the default value, which is normally @code{nil}, is in effect. + Since line truncation and word wrap (described in the next section) +are contradictory, @code{toggle-truncate-lines} disables word wrap +when it turns on line truncation. + If a split window becomes too narrow, Emacs may automatically enable line truncation. @xref{Split Window}, for the variable @code{truncate-partial-width-windows} which controls this. @@ -1797,6 +1809,10 @@ mode is enabled, the mode line shows the string @samp{wrap} in the mode display. The command @kbd{M-x global-visual-line-mode} toggles Visual Line mode in all buffers. + Since word wrap and line truncation (described in the previous +section) are contradictory, turning on @code{visual-line-mode} +disables line truncation. + @findex beginning-of-visual-line @findex end-of-visual-line @findex next-logical-line diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index d2011ebf974..83847fb8f12 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -116,7 +116,7 @@ ways to customize it; it corresponds to GNU Emacs version @value{EMACSVER}. @c See 'manual-html-mono' and 'manual-html-node' in admin/admin.el. @ifset WWW_GNU_ORG @html -The homepage for GNU Emacs is at +The GNU Emacs website is at <a href="/software/emacs/">https://www.gnu.org/software/emacs/</a>.<br> To view this manual in other formats, click <a href="/software/emacs/manual/emacs.html">here</a>.<br> @@ -219,7 +219,7 @@ Appendices * GNU Free Documentation License:: The license for this documentation. * Emacs Invocation:: Hairy startup options. * X Resources:: X resources for customizing Emacs. -* Antinews:: Information about Emacs version 26. +* Antinews:: Information about Emacs version 27. * Mac OS / GNUstep:: Using Emacs under macOS and GNUstep. * Microsoft Windows:: Using Emacs on Microsoft Windows and MS-DOS. * Manifesto:: What's GNU? Gnu's Not Unix! diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 7edf4d2bbbf..3e0788307a5 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -742,6 +742,17 @@ always supposed to end in newlines. Such major modes set the variable setting the latter variable, you can control how these modes handle final newlines. +@vindex file-preserve-symlinks-on-save +If this option is non-@code{nil} and you're visiting a file via a +symbolic link, Emacs will break the symbolic link upon saving the +buffer, and will write the buffer to a file with the same name as the +symbolic link, if the value of @code{file-precious-flag} is +non-@code{nil} (@pxref{Saving Buffers, file-precious-flag,, elisp, The +Emacs Lisp Reference Manual}). If you want Emacs to save the buffer +to the file the symbolic link points to (thereby preserving the link) +in these cases, customize the variable +@code{file-preserve-symlinks-on-save} to @code{t}. + @vindex write-region-inhibit-fsync Normally, when a program writes a file, the operating system briefly caches the file's data in main memory before committing the data to @@ -948,7 +959,7 @@ Manual}). For customizations, see the Custom group @code{time-stamp}. then change your mind, you can @dfn{revert} the changes and go back to the saved version of the file. To do this, type @kbd{C-x x g}. Since reverting unintentionally could lose a lot of work, Emacs asks for -confirmation first. +confirmation first if the buffer is modified. The @code{revert-buffer} command tries to position point in such a way that, if the file was edited only slightly, you will be at @@ -991,6 +1002,17 @@ revert it automatically if it has changed---provided the buffer itself is not modified. (If you have edited the text, it would be wrong to discard your changes.) +@vindex revert-buffer-quick-short-answers +@findex revert-buffer-quick + The @kbd{C-x x g} keystroke is bound to the +@code{revert-buffer-quick} command. This is like the +@code{revert-buffer} command, but prompts less. Unlike +@code{revert-buffer}, it will not prompt if the current buffer visits +a file, and the buffer is not modified. It also respects the +@code{revert-buffer-quick-short-answers} user option. If this option +is non-@code{nil}, use a shorter @kbd{y/n} query instead of a longer +@kbd{yes/no} query. + You can also tell Emacs to revert buffers automatically when their visited files change on disk; @pxref{Auto Revert}. @@ -1169,6 +1191,13 @@ visited file. (You can inhibit this by setting the variable file name with @kbd{C-x C-w} or @code{set-visited-file-name} renames any auto-save file to go with the new visited name. +@vindex kill-buffer-delete-auto-save-files + Killing a buffer, by default, doesn't remove the buffer's auto-save +file. If @code{kill-buffer-delete-auto-save-files} is non-@code{nil}, +killing a buffer that has an auto-save file will make Emacs prompt the +user for whether the auto-save file should be deleted. (This is +inhibited if @code{delete-auto-save-files} is @code{nil}.) + @node Auto Save Control @subsection Controlling Auto-Saving @@ -1717,12 +1746,16 @@ exists. @kbd{M-x copy-file} copies the contents of the file @var{old} to the file @var{new}. +@vindex copy-directory-create-symlink @findex copy-directory @kbd{M-x copy-directory} copies directories, similar to the @command{cp -r} shell command. If @var{new} is a directory name, it creates a copy of the @var{old} directory and puts it in @var{new}. Otherwise it copies all the contents of @var{old} into a new directory -named @var{new}. +named @var{new}. If @code{copy-directory-create-symlink} is +non-@code{nil} and @var{old} is a symbolic link, this command will +copy the symbolic link. If @code{nil}, this command will follow the +link and copy the contents instead. (This is the default.) @cindex renaming files @findex rename-file @@ -2172,11 +2205,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}. diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi index b558ebc3fdc..7feebddee8c 100644 --- a/doc/emacs/fixit.texi +++ b/doc/emacs/fixit.texi @@ -462,10 +462,9 @@ use @code{flyspell-region} or @code{flyspell-buffer} for that. When Flyspell mode highlights a word as misspelled, you can click on it with @kbd{mouse-2} (@code{flyspell-correct-word}) to display a menu of possible corrections and actions. If you want this menu on -@kbd{mouse-3} instead, customize the variable -@code{flyspell-use-mouse-3-for-menu}. In addition, @kbd{C-.} or -@kbd{@key{ESC}-@key{TAB}} (@code{flyspell-auto-correct-word}) will -propose various successive corrections for the word at point, and +@kbd{mouse-3} instead, enable @code{context-menu-mode}. In addition, +@kbd{C-.} or @kbd{@key{ESC} @key{TAB}} (@code{flyspell-auto-correct-word}) +will propose various successive corrections for the word at point, and @w{@kbd{C-c $}} (@code{flyspell-correct-word-before-point}) will pop up a menu of possible corrections. Of course, you can always correct the misspelled word by editing it manually in any way you like. diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index 70615f68ed8..c14ada29576 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -366,20 +366,24 @@ This menu is for changing the default face within the window's buffer. @xref{Text Scale}. @end table - Some graphical applications use @kbd{mouse-3} for a mode-specific -menu. If you prefer @kbd{mouse-3} in Emacs to bring up such a menu -instead of running the @code{mouse-save-then-kill} command, rebind -@kbd{mouse-3} by adding the following line to your init file -(@pxref{Init Rebinding}): - -@smallexample -(global-set-key [mouse-3] - '(menu-item "Menu Bar" ignore - :filter (lambda (_) - (if (zerop (or (frame-parameter nil 'menu-bar-lines) 0)) - (mouse-menu-bar-map) - (mouse-menu-major-mode-map))))) -@end smallexample +@cindex context menu +@findex context-menu-mode +@vindex context-menu-functions +@kindex Down-mouse-3 +@kindex S-F10 + Many GUI applications use @kbd{mouse-3} to display @dfn{context +menus}: menus that provide access to various pertinent settings and +actions for the location and context of the mouse click. If you +prefer this in Emacs over the default function of @kbd{mouse-3}, which +is bound to the @code{mouse-save-then-kill} command (@pxref{Mouse +Commands}), you can enable the minor mode @code{context-menu-mode}. +Then Emacs will show context menus when you click @kbd{mouse-3}. The +exact contents of these context menus depends on the current major +mode and the buffer contents around the place where you click the +mouse. To customize the contents of the context menu, you can use the +variable @code{context-menu-functions} (@pxref{Major Mode +Conventions,,, elisp, The Emacs Lisp Reference Manual}). +You can also invoke the context menu by pressing @kbd{S-@key{F10}}. @node Mode Line Mouse @section Mode Line Mouse Commands @@ -448,7 +452,14 @@ buffer to select: @item C-x 5 2 @kindex C-x 5 2 @findex make-frame-command -Create a new frame (@code{make-frame-command}). +Create a new frame using the default frame parameters +(@code{make-frame-command}). + +@item C-x 5 c +@kindex C-x 5 c +@findex clone-frame +Create a new frame using the window configuration and frame parameters +of the current frame (@code{clone-frame}). @item C-x 5 b @var{bufname} @key{RET} Select buffer @var{bufname} in another frame. This runs @@ -480,9 +491,10 @@ frame. This runs @code{find-file-read-only-other-frame}. @xref{Visiting}. @item C-x 5 5 -A more general prefix command affects the buffer displayed by the next -command invoked immediately after this prefix command. It requests -the buffer of the next command to be displayed in another frame. +A more general prefix command that affects the buffer displayed by the +next command invoked immediately after this prefix command +(@code{other-frame-prefix}). It requests the buffer of the next +command to be displayed in another frame. @end table You can control the appearance and behavior of the newly-created @@ -1217,7 +1229,9 @@ the use of menu bars at startup, customize the variable terminals, where this makes one additional line available for text. If the menu bar is off, you can still pop up a menu of its contents with @kbd{C-mouse-3} on a display which supports pop-up menus. -@xref{Menu Mouse Clicks}. +Or you can enable @code{context-menu-mode} and customize the variable +@code{context-menu-functions} to pop up a context menu with +@kbd{mouse-3}. @xref{Menu Mouse Clicks}. @xref{Menu Bar}, for information on how to invoke commands with the menu bar. @xref{X Resources}, for how to customize the menu bar @@ -1267,19 +1281,23 @@ displayed by moving the mouse pointer to the top of the screen. @section Tab Bars @cindex tab bar mode @cindex mode, Tab Bar -@cindex tabs, tabbar +@cindex tabs, on the Tab Bar On graphical displays and on text terminals, Emacs can optionally display a @dfn{Tab Bar} at the top of each frame, just below the menu -bar. The Tab Bar is a row of @dfn{tabs}---buttons that you can click -to switch between window configurations on that frame. +bar (@pxref{Menu Bars}) and above or below the tool bar (@pxref{Tool +Bars}) depending on the variable @code{tab-bar-position}. +The Tab Bar is a row of @dfn{tabs}---buttons that you can click to +switch between window configurations. Each tab on the Tab Bar represents a named persistent window -configuration. Its name is composed from the list of names of buffers -visible in windows of that window configuration. Clicking on the tab -switches to the window configuration recorded by the tab; it is a -configuration of windows and buffers which was previously used in the -frame when that tab was the current tab. +configuration of its frame, i.e., how that frame is partitioned into +windows and which buffer is displayed in each window. The tab's name +is composed from the list of names of buffers shown in windows of that +window configuration. Clicking on the tab switches to the window +configuration recorded by the tab; it is a configuration of windows +and buffers which was previously used in the frame when that tab was +the current tab. If you are using the desktop library to save and restore your sessions (@pxref{Saving Emacs Sessions}), the tabs from the Tab Bar are @@ -1288,28 +1306,40 @@ configurations, and will be available after restoring the session. Note that the Tab Bar is different from the Tab Line (@pxref{Tab Line}). Whereas tabs on the Tab Line at the top of each window are used to -switch between buffers, tabs on the Tab Bar at the top of each frame -are used to switch between window configurations containing several -windows with buffers. +switch between buffers in the window, tabs on the Tab Bar at the top +of each frame are used to switch between window configurations +containing several windows showing one or more buffers. @findex tab-bar-mode - To toggle the use of tab bars, type @kbd{M-x tab-bar-mode}. This + To toggle the use of Tab Bars, type @kbd{M-x tab-bar-mode}. This command applies to all frames, including frames yet to be created. To control the use of tab bars at startup, customize the variable -@code{tab-bar-mode}. +@code{tab-bar-mode} and save your customization. @vindex tab-bar-show The variable @code{tab-bar-show} controls whether the Tab Bar mode is turned on automatically. If the value is @code{t}, then @code{tab-bar-mode} is enabled when using the commands that create new tabs. The value @code{1} hides the tab bar when it has only one tab, -and shows it again when more tabs are created. The value @code{nil} -always keeps the tab bar hidden; in this case it's still possible to -switch between named window configurations without the tab bar by -using @kbd{M-x tab-next}, @kbd{M-x tab-switcher}, and other commands -that provide completion on tab names. Also it's possible to create -and close tabs without the tab bar by using commands @kbd{M-x -tab-new}, @kbd{M-x tab-close}, etc. +and shows it again when more tabs are created. More generally, a +value that is a non-negative integer causes the Tab Bar to be +displayed only if the number of tabs is greater than that integer. +The value @code{nil} always keeps the Tab Bar hidden; in this case +it's still possible to switch between named window configurations +without displaying the Tab Bar by using @kbd{M-x tab-next}, @kbd{M-x +tab-switcher}, and other commands that provide completion on tab +names. Also it's possible to create and close tabs without the Tab +Bar by using commands @kbd{M-x tab-new}, @kbd{M-x tab-close}, etc. + + Note that a numerical value of @code{tab-bar-show} can cause the Tab +Bar to be displayed on some frames, but not on others, depending on +the number of tabs created on each frame. + +@findex toggle-frame-tab-bar + To toggle the use of the Tab Bar only on the selected frame, type +@kbd{M-x toggle-frame-tab-bar}. This command allows to enable the +display of the Tab Bar on some frames and disable it on others, +regardless of the values of @code{tab-bar-mode} and @code{tab-bar-show}. @kindex C-x t The prefix key @kbd{C-x t} is analogous to @kbd{C-x 5}. @@ -1322,29 +1352,41 @@ buffer to select. The following commands can be used to select a buffer in a new tab: @table @kbd -@item C-x t 2 @kindex C-x t 2 @findex tab-new +@vindex tab-bar-tab-name-function +@item C-x t 2 Add a new tab (@code{tab-new}). You can control the choice of the buffer displayed in a new tab by customizing the variable -@code{tab-bar-new-tab-choice}. +@code{tab-bar-new-tab-choice}. You can control the names given by +default to new tabs by customizing the variable +@code{tab-bar-tab-name-function}. +@kindex C-x t b +@findex switch-to-buffer-other-tab @item C-x t b @var{bufname} @key{RET} Select buffer @var{bufname} in another tab. This runs @code{switch-to-buffer-other-tab}. +@kindex C-x t f +@findex find-file-other-tab @item C-x t f @var{filename} @key{RET} -Visit file @var{filename} and select its buffer in another tab. This -runs @code{find-file-other-tab}. @xref{Visiting}. +Visit the file @var{filename} (@pxref{Visiting}) and select its buffer +in another tab. This runs @code{find-file-other-tab}. +@kindex C-x t d +@findex dired-other-tab @item C-x t d @var{directory} @key{RET} -Select a Dired buffer for directory @var{directory} in another tab. -This runs @code{dired-other-tab}. @xref{Dired}. +Edit the specified @var{directory} (@pxref{Dired}) in another tab. +This runs @code{dired-other-tab}. +@kindex C-x t t +@findex other-tab-prefix @item C-x t t -A more general prefix command affects the buffer displayed by the next -command invoked immediately after this prefix command. It requests -the buffer of the next command to be displayed in another tab. +This is a prefix command (@code{other-tab-prefix}) that affects the +next command invoked immediately after this prefix command. It +requests the buffer displayed by the next command to be shown in +another tab. @end table @vindex tab-bar-new-tab-choice @@ -1360,17 +1402,18 @@ By default, a new tab is added on the right side of the current tab. The following commands can be used to delete tabs: @table @kbd -@item C-x t 0 @kindex C-x t 0 @findex tab-close -Close the selected tab (@code{tab-close}). It has no effect if there +@vindex tab-bar-close-last-tab-choice +@item C-x t 0 +Close the selected tab (@code{tab-close}). This has no effect if there is only one tab, unless the variable @code{tab-bar-close-last-tab-choice} is customized to a non-default value. -@item C-x t 1 @kindex C-x t 1 @findex tab-close-other -Close all tabs on the selected frame, except the selected one. +@item C-x t 1 +Close all tabs, except the selected tab, on the selected frame. @end table @vindex tab-bar-close-tab-select @@ -1384,77 +1427,113 @@ a recently used tab. The following commands can be used to switch between tabs: @table @kbd -@item C-x t o -@itemx C-@key{TAB} @kindex C-x t o @kindex C-TAB @findex tab-next -Switch to the next tab. If you repeat this command, it cycles through -all the tabs on the selected frame. With a positive numeric argument -@var{n}, it switches to the next @var{n}th tab; with a negative -argument @minus{}@var{n}, it switches back to the previous @var{n}th -tab. +@item C-x t o +@itemx C-@key{TAB} +Switch to the next tab (@code{tab-next}). If you repeat this command, +it cycles through all the tabs on the selected frame. With a positive +numeric argument @var{n}, it switches to the @var{n}th next tab; with +a negative argument @minus{}@var{n}, it switches back to the @var{n}th +previous tab. -@item S-C-@key{TAB} @kindex S-C-TAB @findex tab-previous -Switch to the previous tab. With a positive numeric argument @var{n}, -it switches to the previous @var{n}th tab; with a negative argument -@minus{}@var{n}, it switches back to the next @var{n}th tab. +@item S-C-@key{TAB} +Switch to the previous tab (@code{tab-previous}). With a positive +numeric argument @var{n}, it switches to the @var{n}th previous tab; +with a negative argument @minus{}@var{n}, it switches to the +@var{n}th next tab. +@kindex C-x t @key{RET} +@findex tab-switch @item C-x t @key{RET} @var{tabname} @key{RET} -Switch to the tab by its name, with completion on all tab names. -Default values are tab names sorted by recency, so you can use -@kbd{M-n} (@code{next-history-element}) to get the name of the last -visited tab, the second last, and so on. - -@item @var{modifier}-@var{tabnumber} +Switch to the tab by its name (@code{tab-switch}), with completion on +all tab names. The default value and the ``future history'' of tab +names is sorted by recency, so you can use @kbd{M-n} +(@code{next-history-element}) to get the name of the last visited tab, +the second last, and so on. + +@kindex C-1, tab bar +@kindex M-1, tab bar @findex tab-select -Switch to the tab by its number. After customizing the variable -@code{tab-bar-select-tab-modifiers} to specify a @var{modifier} key, you -can select a tab by its ordinal number using the specified modifier in -combination with the tab number to select. To display the tab number -alongside the tab name, you can customize another variable -@code{tab-bar-tab-hints}. This will help you to decide what key to press -to select the tab by its number. - -@item @var{modifier}-@kbd{0} +@vindex tab-bar-select-tab-modifiers +@vindex tab-bar-tab-hints +@item @var{modifier}-@var{tab-number} +Switch to the tab by its number @var{tab-number} (@code{tab-select}). +After customizing the variable @code{tab-bar-select-tab-modifiers} to +specify one or more @var{modifier} keys, you can select a tab by its +ordinal number using one of the specified modifiers in combination +with the tab number to select. The number 9 can be used to select the +last tab. You can select any modifiers supported by Emacs, +@pxref{Modifier Keys}. To display the tab number alongside the tab +name, you can customize another variable @code{tab-bar-tab-hints}. +This will help you decide which numerical key to press to select the +tab by its number. + +@kindex C-9, tab bar +@kindex M-9, tab bar +@findex tab-last +@item @var{modifier}-@kbd{9} +Switch to the last tab (@code{tab-last}). The key combination is +the modifier key defined by @code{tab-bar-select-tab-modifiers} and +the key @kbd{9}. With a numeric argument @var{n}, switch to the +@var{n}th last tab. + +@kindex C-0, tab bar +@kindex M-0, tab bar @findex tab-recent -Switch to the recent tab. The key combination is the modifier key -defined by @code{tab-bar-select-tab-modifiers} and the key @kbd{0}. -With a numeric argument @var{n}, switch to the @var{n}th recent tab. +@item @var{modifier}-@kbd{0} +Switch to the recent tab (@code{tab-recent}). The key combination is +the modifier key defined by @code{tab-bar-select-tab-modifiers} and +the key @kbd{0}. With a numeric argument @var{n}, switch to the +@var{n}th recent tab. @end table The following commands can be used to operate on tabs: @table @kbd -@item C-x t r @var{tabname} @key{RET} +@kindex C-x t r @findex tab-rename -Rename the current tab to @var{tabname}. You can control the -programmatic name given to a tab by default by customizing the -variable @code{tab-bar-tab-name-function}. +@item C-x t r @var{tabname} @key{RET} +Rename the current tab to @var{tabname} (@code{tab-rename}). -@item C-x t m +@kindex C-x t m @findex tab-move -Move the current tab @var{n} positions to the right with a positive -numeric argument @var{n}. With a negative argument @minus{}@var{n}, -move the current tab @var{n} positions to the left. +@item C-x t m +Move the current tab one position to the right (@code{tab-move}). +With a positive numeric argument @var{n}, move it that many positions +to the right; with a negative argument @minus{}@var{n}, move it +@var{n} positions to the left. @end table + You can use the mouse to operate on tabs. Clicking @kbd{mouse-2} +closes the tab. Clicking @kbd{mouse-3} pops up the context menu with +the items that operate on the clicked tab. Dragging the tab with +@kbd{mouse-1} moves it to another position on the tab bar. Mouse +wheel scrolling switches to the next or previous tab. Holding down +the @key{SHIFT} key during scrolling moves the tab to the left or right. + @findex tab-bar-history-mode You can enable @code{tab-bar-history-mode} to remember window -configurations used in every tab, and restore them. +configurations used in every tab, and later restore them. @table @kbd -@item tab-bar-history-back +@findex tab-bar-history-back +@item M-x tab-bar-history-back Restore a previous window configuration used in the current tab. This navigates back in the history of window configurations. -@item tab-bar-history-forward +@findex tab-bar-history-forward +@item M-x tab-bar-history-forward Cancel restoration of the previous window configuration. -This navigates forward in the history of window configurations. +This moves forward in the history of window configurations. @end table + It's possible to customize the items displayed on the tab bar +by the user option @code{tab-bar-format}. + @node Dialog Boxes @section Using Dialog Boxes @cindex dialog boxes diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi index 4f971eb1e01..9c06bcc4af1 100644 --- a/doc/emacs/glossary.texi +++ b/doc/emacs/glossary.texi @@ -86,8 +86,8 @@ delimiter for you (@pxref{Matching,,Matching Parens}). @anchor{Glossary---Balanced Expression} @item Balanced Expressions A balanced expression is a syntactically recognizable expression, such -as a symbol, number, string constant, block, or parenthesized expression -in C@. @xref{Expressions,Balanced Expressions}. +as a symbol (q.v.@:), number, string constant, block, or parenthesized +expression in C@. @xref{Expressions,Balanced Expressions}. @item Balloon Help @xref{Glossary---Tooltips}. @@ -238,7 +238,7 @@ a key binding in Emacs or to be invoked by its name @anchor{Glossary---Command Name} @item Command Name -A command name is the name of a Lisp symbol that is a command +A command name is the name of a Lisp symbol (q.v.@:) that is a command (@pxref{Commands}). You can invoke any command by its name using @kbd{M-x} (@pxref{M-x,M-x,Running Commands by Name}). @@ -1113,7 +1113,7 @@ Emacs. @xref{Query Replace}. @anchor{Glossary---Quitting} @item Quitting Quitting means canceling a partially typed command or a running -command, using @kbd{C-g} (or @kbd{C-@key{BREAK}} on MS-DOS). @xref{Quitting}. +command, using @kbd{C-g} (or @kbd{C-@key{Break}} on MS-DOS). @xref{Quitting}. @item Quoting Quoting means depriving a character of its usual special significance. @@ -1334,6 +1334,13 @@ allowed as well. @item String Substitution @xref{Glossary---Global Substitution}. +@item Symbol +A symbol in Emacs Lisp is an object with a name. The object can be a +variable (q.v.@:), a function or command (q.v.@:), or a face (q.v.@:). +The symbol's name serves as the printed representation of the symbol. +@xref{Symbol Type,, Symbol Type, elisp, The Emacs Lisp Reference +Manual}. + @item Syntax Highlighting @xref{Glossary---Font Lock}. diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index 0caab681d34..20a9d8be13b 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -278,6 +278,15 @@ name is defined as a Lisp function. Type @kbd{C-g} to cancel the @kbd{C-h f} command if you don't really want to view the documentation. +@vindex help-enable-symbol-autoload + If you request help for an autoloaded function whose @code{autoload} +form (@pxref{Autoload,,, elisp, The Emacs Lisp Reference Manual}) +doesn't provide a doc string, the @file{*Help*} buffer won't have any +doc string to display. In that case, if +@code{help-enable-symbol-autoload} is non-@code{nil}, Emacs will try +to load the file in which the function is defined to see whether +there's a doc string there. + @findex shortdoc-display-group You can get an overview of functions relevant for a particular topic by using the @kbd{M-x shortdoc-display-group} command. This will @@ -310,6 +319,14 @@ variable, or a face. If the symbol has more than one definition, like it has both definition as a function and as a variable, this command will show the documentation of all of them, one after the other. +@vindex completions-detailed + If the @code{completions-detailed} user option is non-@code{nil}, +some commands provide details about the possible values when +displaying completions. For instance, @kbd{C-h o TAB} will then +include the first line of the doc string, and will also say whether +each symbol is a function or a variable (and so on). Which details +are included varies depending on the command used. + @node Apropos @section Apropos @cindex apropos @@ -426,11 +443,13 @@ alphabetical order, change the variable @node Help Mode @section Help Mode Commands +@findex help-mode +@cindex help mode - Help buffers provide the same commands as View mode (@pxref{View -Mode}); for instance, @key{SPC} scrolls forward, and @key{DEL} or -@kbd{S-@key{SPC}} scrolls backward. A few special commands are also -provided: + Help buffers have Help mode as their major mode. Help mode provides +the same commands as View mode (@pxref{View Mode}); for instance, +@key{SPC} scrolls forward, and @key{DEL} or @kbd{S-@key{SPC}} scrolls +backward. It also provides a few special commands: @table @kbd @item @key{RET} @@ -442,15 +461,18 @@ 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}). @@ -479,6 +501,30 @@ 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. + +@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 @@ -488,16 +534,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 @@ -629,14 +665,14 @@ Emacs Lisp Reference Manual}). @findex describe-prefix-bindings You can get a list of subcommands for a particular prefix key by -typing @kbd{C-h}, @kbd{?}, or @key{f1} +typing @kbd{C-h}, @kbd{?}, or @key{F1} (@code{describe-prefix-bindings}) after the prefix key. (There are a few prefix keys for which not all of these keys work---those that provide their own bindings for that key. One of these prefix keys is @key{ESC}, because @kbd{@key{ESC} C-h} and @kbd{@key{ESC} ?} are actually @kbd{C-M-h} (@code{mark-defun}) and @kbd{M-?} (@code{xref-find-references}), respectively. However, -@w{@kbd{@key{ESC} @key{f1}}} works fine.) +@w{@kbd{@key{ESC} @key{F1}}} works fine.) @findex describe-keymap Finally, @kbd{M-x describe-keymap} prompts for the name of a keymap, diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi index 6e4fd77e8b9..375ac970d78 100644 --- a/doc/emacs/killing.texi +++ b/doc/emacs/killing.texi @@ -353,7 +353,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. @@ -562,6 +562,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 (@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 diff --git a/doc/emacs/kmacro.texi b/doc/emacs/kmacro.texi index e713c6ef8c0..78964bb903f 100644 --- a/doc/emacs/kmacro.texi +++ b/doc/emacs/kmacro.texi @@ -102,7 +102,7 @@ are in the process of defining one, or calls the last macro otherwise.) You can also supply @key{F4} with a numeric prefix argument @samp{n}, which means to invoke the macro @samp{n} times. An argument of zero repeats the macro indefinitely, until it gets an -error or you type @kbd{C-g} (or, on MS-DOS, @kbd{C-@key{BREAK}}). +error or you type @kbd{C-g} (or, on MS-DOS, @kbd{C-@key{Break}}). The above example demonstrates a handy trick that you can employ with keyboard macros: if you wish to repeat an operation at regularly @@ -180,11 +180,11 @@ define it, so @kbd{C-u 4 C-x )} executes the macro immediately 3 additional times. @findex kdb-macro-redisplay -@kindex C-x C-k Q +@kindex C-x C-k d While executing a long-running keyboard macro, it can sometimes be useful to trigger a redisplay (to show how far we've gotten). The -@kbd{C-x C-k Q} can be used for this. As a not very useful example, -@kbd{C-x ( M-f C-x C-k Q C-x )} will create a macro that will +@kbd{C-x C-k d} command can be used for this. As a not very useful +example, @kbd{C-x ( M-f C-x C-k d C-x )} will create a macro that will redisplay once per iteration when saying @kbd{C-u 42 C-x e}. @node Keyboard Macro Ring diff --git a/doc/emacs/m-x.texi b/doc/emacs/m-x.texi index d35a8351541..7b9b40388c2 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 cd1db1a7bab..99c67ed09e5 100644 --- a/doc/emacs/macos.texi +++ b/doc/emacs/macos.texi @@ -290,7 +290,7 @@ The default behavior is to save all file-visiting buffers. @cindex using Nextstep services (macOS) Emacs also allows users to make use of Nextstep services, via a set of commands whose names begin with @samp{ns-service-} and end with the -name of the service. Type @kbd{M-x ns-service-@key{TAB}} to +name of the service. Type @kbd{M-x ns-service- @key{TAB}} to see a list of these commands. These functions either operate on marked text (replacing it with the result) or take a string argument and return the result as a string. You can also use the Lisp function diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index 3205e6dbdf7..ebd72fa2a00 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -493,7 +493,7 @@ action on the current VC fileset: either registering it with a version control system, or committing it, or unlocking it, or merging changes into it. The precise actions are described in detail in the following subsections. You can use @kbd{C-x v v} either in a file-visiting -buffer or in a VC Directory buffer. +buffer, in a Dired buffer, or in a VC Directory buffer. Note that VC filesets are distinct from the named filesets used for viewing and visiting files in functional groups @@ -945,7 +945,7 @@ the author's description of the changes in the revision on the current line. @item w -Annotate the working revision--the one you are editing. If you used +Annotate the working revision---the one you are editing. If you used @kbd{p} and @kbd{n} to browse to other revisions, use this key to return to your working revision. @@ -1136,13 +1136,17 @@ Revert the work file(s) in the current VC fileset to the last revision @findex vc-revert @vindex vc-revert-show-diff If you want to discard all the changes you have made to the current -VC fileset, type @kbd{C-x v u} (@code{vc-revert}). This shows -you a diff between the work file(s) and the revision from which you -started editing, and asks for confirmation for discarding the changes. -If you agree, the fileset is reverted. If you don't want @kbd{C-x v -u} to show a diff, set the variable @code{vc-revert-show-diff} to -@code{nil} (you can still view the diff directly with @kbd{C-x v =}; -@pxref{Old Revisions}). +VC fileset, type @kbd{C-x v u} (@code{vc-revert}). This will ask you +for confirmation before discarding the changes. If you agree, the +fileset is reverted. + + If @code{vc-revert-show-diff} is non-@code{nil}, this command will +show you a diff between the work file(s) and the revision from which +you started editing. Afterwards, the diff buffer will either be +killed (if this variable is @code{kill}), or the buffer will be buried +(any other non-@code{nil} value). If you don't want @kbd{C-x v u} to +show a diff, set this variable to @code{nil} (you can still view the +diff directly with @kbd{C-x v =}; @pxref{Old Revisions}). On locking-based version control systems, @kbd{C-x v u} leaves files unlocked; you must lock again to resume editing. You can also use @@ -1731,7 +1735,8 @@ the full file name of the file to visit, you can type only the file's 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 default to visit. +name at point, this command offers that file as the first element of +the ``future history''. @findex project-find-regexp The command @kbd{C-x p g} (@code{project-find-regexp}) is similar to @@ -1743,10 +1748,12 @@ commands (@pxref{Xref Commands}). When invoked with a prefix argument, this command additionally prompts for the base directory from which to start the search; this allows, for example, to limit the search only to project files under a certain subdirectory of the -project root. +project root. The way this command displays the matches is affected +by the value of @code{xref-auto-jump-to-first-xref} (@pxref{Identifier +Search}). @findex project-search - @kbd{M-x project-search} is an interactive variant of + @kbd{M-x project-search} is a sequential variant of @code{project-find-regexp}. It prompts for a regular expression to search in the current project's files, but instead of finding all the matches and displaying them, it stops when it finds a match and visits @@ -1762,8 +1769,13 @@ Replace}), and continues to the next match after you respond. If your response causes Emacs to exit the query-replace loop, you can later continue with @w{@kbd{M-x fileloop-continue @key{RET}}}. +@findex project-find-dir + The command @kbd{C-x p d} (@code{project-find-dir}) prompts you to +choose a directory inside the current project, with completion. +And opens a Dired buffer (@pxref{Dired}) listing the files in it. + @findex project-dired - The command @kbd{C-x p d} (@code{project-dired}) opens a Dired + The command @kbd{C-x p D} (@code{project-dired}) opens a Dired buffer (@pxref{Dired}) listing the files in the current project's root directory. @@ -1854,14 +1866,14 @@ records the list of known projects. It defaults to the file @subsection Managing the Project List File @table @kbd -@item M-x project-remove-known-project +@item M-x project-forget-project Remove a known project from the @code{project-list-file}. @end table -@findex project-remove-known-project +@findex project-forget-project Normally Emacs automatically adds and removes projects to and from the @code{project-list-file}, but sometimes you may want to manually edit -the available projects. @kbd{M-x project-remove-known-project} +the available projects. @kbd{M-x project-forget-project} prompts you to choose one of the available projects, and then removes it from the file. @@ -2127,7 +2139,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 @@ -2135,24 +2150,15 @@ Switch @code{xref} to use the @code{etags} backend. @kindex M-. @findex xref-find-definitions @vindex xref-prompt-for-identifier - @kbd{M-.}@: (@code{xref-find-definitions}) shows the definitions of + @kbd{M-.}@: (@code{xref-find-definitions}) shows the definition of the identifier at point. With a prefix argument, or if there's no identifier at point, it prompts for the identifier. (If you want it to always prompt, customize @code{xref-prompt-for-identifier} to @code{t}.) -If the specified identifier has only one definition, the command jumps -to it. If the identifier has more than one possible definition (e.g., -in an object-oriented language, or if there's a function and a -variable by the same name), the command shows the candidate -definitions in the @file{*xref*} buffer, together with the files in -which these definitions are found. Selecting one of these candidates -by typing @kbd{@key{RET}} or clicking @kbd{mouse-2} will pop a buffer -showing the corresponding definition. - - When entering the identifier argument to @kbd{M-.}, the usual -minibuffer completion commands can be used (@pxref{Completion}), with -the known identifier names as completion candidates. + When entering the identifier argument to @kbd{M-.}, you can use the +usual minibuffer completion commands (@pxref{Completion}), with the +known identifier names being the completion candidates. @kindex C-x 4 . @findex xref-find-definitions-other-window @@ -2170,29 +2176,48 @@ former is @w{@kbd{C-x 4 .}} or around the place of a mouse event. This command is intended to be bound to a mouse event, such as @kbd{C-M-mouse-1}, for example. -@findex xref-find-apropos @kindex C-M-. - The command @kbd{C-M-.} (@code{xref-find-apropos}) finds the -definitions of one or more identifiers that match a specified regular -expression. It is just like @kbd{M-.} except that it does regexp +@findex xref-find-apropos +@vindex tags-apropos-additional-actions + The command @kbd{C-M-.}@: (@code{xref-find-apropos}) is like +@code{apropos} for tags (@pxref{Apropos}). It displays a list of +identifiers in the selected tags table whose names match the specified +@var{regexp}. This is just like @kbd{M-.}, except that it does regexp matching of identifiers instead of matching symbol names as fixed -strings. - - When any of the above commands finds more than one definition, it -presents the @file{*xref*} buffer showing the definition candidates. -In that buffer, you have several specialized commands, described in -@ref{Xref Commands}. +strings. By default, the command pops up the @file{*xref*} buffer, +like @kbd{M-.}, but you can display additional output by customizing +the variable @code{tags-apropos-additional-actions}; see its +documentation for details. + +@vindex xref-auto-jump-to-first-definition + If any of the above commands finds more than one matching +definition, it by default pops up the @file{*xref*} buffer showing the +matching candidates. (@kbd{C-M-.}@: @emph{always} pops up the +@file{*xref*} buffer if it finds at least one match.) The candidates +are normally shown in that buffer as the name of a file and the +matching identifier(s) in that file. In that buffer, you can select +any of the candidates for display, and you have several additional +commands, described in @ref{Xref Commands}. However, if the value of +the variable @code{xref-auto-jump-to-first-definition} is @code{move}, +the first of these candidates is automatically selected in the +@file{*xref*} buffer, and if it's @code{t} or @code{show}, the first +candidate is automatically shown in its own window; @code{t} also +selects the window showing the first candidate. The default value is +@code{nil}, which just shows the candidates in the @file{*xref*} +buffer, but doesn't select any of them. @kindex M-, -@findex xref-pop-marker-stack -@vindex xref-marker-ring-length - To go back to places @emph{from where} you found the definition, -use @kbd{M-,} (@code{xref-pop-marker-stack}). It jumps back to the +@findex xref-go-back + To go back to places @emph{from where} you've displayed the definition, +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 + Go forward to a place from where you previously went back using @kbd{M-,}. +This is useful if you find that you went back too far. @findex xref-etags-mode Some major modes install @code{xref} support facilities that might @@ -2218,10 +2243,16 @@ the special XREF mode: @table @kbd @item @key{RET} -@itemx mouse-2 +@itemx mouse-1 Display the reference on the current line (@code{xref-goto-xref}). With prefix argument, also bury the @file{*xref*} buffer. +@item mouse-2 +@findex xref-select-and-show-xref +The same as @code{mouse-1}, but make the window displaying the +@file{*xref*} buffer the selected window +(@code{xref-select-and-show-xref}). + @item n @itemx . @findex xref-next-line @@ -2257,10 +2288,15 @@ the match with @var{replacement}. @xref{Identifier Search}. @item g @findex xref-revert-buffer Refresh the contents of the @file{*xref*} buffer -(@code{xref-revert-buffer}. +(@code{xref-revert-buffer}). + +@item M-, +@findex xref-quit-and-pop-marker-stack +Quit the window showing the @file{*xref*} buffer, and then jump to the +previous Xref stack location (@code{xref-quit-and-pop-marker-stack}). -@findex xref-quit @item q +@findex xref-quit Quit the window showing the @file{*xref*} buffer (@code{xref-quit}). @end table @@ -2311,6 +2347,16 @@ identifier, showing the file name and the line where the identifier is referenced. The XREF mode commands are available in this buffer, see @ref{Xref Commands}. +@vindex xref-auto-jump-to-first-xref + If the value of the variable @code{xref-auto-jump-to-first-xref} is +@code{t}, @code{xref-find-references} automatically jumps to the first +result and selects the window where it is displayed. If the value is +@code{show}, the first result is shown, but the window showing the +@file{*xref*} buffer is left selected. If the value is @code{move}, +the first result is selected in the @file{*xref*} buffer, but is not +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 @@ -2381,13 +2427,14 @@ Searching}. Perform completion on the text around point, possibly using the selected tags table if one is loaded (@code{completion-at-point}). -@item M-x xref-find-apropos @key{RET} @var{regexp} @key{RET} -Display a list of all known identifiers matching @var{regexp}. - @item M-x list-tags @key{RET} @var{file} @key{RET} Display a list of the identifiers defined in the program file @var{file}. +@item C-M-. @var{regexp} @key{RET} +Display a list of all identifiers matching @var{regexp} +(@code{xref-find-apropos}). @xref{Looking Up Identifiers}. + @item M-x tags-next-file Visit files recorded in the selected tags table. @end table @@ -2409,26 +2456,6 @@ for the project to be available. @xref{Tags Tables}. If used interactively, the default tag is file name of the current buffer if used interactively. -@c Sadly, the new-and-improved Xref feature doesn't provide anything -@c close to the described below features of the now-obsoleted -@c tags-apropos. I'm leaving this here to encourage enhancements to -@c xref.el. -@ignore -@findex tags-apropos -@vindex tags-apropos-verbose -@vindex tags-tag-face -@vindex tags-apropos-additional-actions - @kbd{M-x tags-apropos} is like @code{apropos} for tags -(@pxref{Apropos}). It displays a list of tags in the selected tags -table whose entries match @var{regexp}. If the variable -@code{tags-apropos-verbose} is non-@code{nil}, it displays the names -of the tags files together with the tag names. You can customize the -appearance of the output by setting the variable @code{tags-tag-face} -to a face. You can display additional output by customizing the -variable @code{tags-apropos-additional-actions}; see its documentation -for details. -@end ignore - @findex tags-next-file @kbd{M-x tags-next-file} visits files covered by the selected tags table. The first time it is called, it visits the first file covered by the @@ -3097,19 +3124,23 @@ these local variables section would do. @smallexample ;; Local Variables: -;; bug-reference-bug-regexp: "\\([Bb]ug[#-]\\)\\([0-9]+\\)" +;; bug-reference-bug-regexp: "\\([Bb]ug[#-]\\([0-9]+\\)\\)" ;; bug-reference-url-format: "https://project.org/issues/%s" ;; End: @end smallexample +The string captured by the first regexp group defines the bounds of +the overlay bug-reference creates, i.e., the part which is highlighted +and made clickable. + The string captured by the second regexp group in @code{bug-reference-bug-regexp} is used to replace the @code{%s} template in the @code{bug-reference-url-format}. Note that @code{bug-reference-url-format} may also be a function in -order to cater for more complex scenarios, e.g., when the part before -the actual bug number has to be used to distinguish between issues and -merge requests where each of them has a different URL. +order to cater for more complex scenarios, e.g., when different parts +of the bug reference have to be used to distinguish between issues and +merge requests resulting in different URLs. @heading Automatic Setup @@ -3124,20 +3155,22 @@ variables itself by calling the functions in one is able to set the variables. @vindex bug-reference-setup-from-vc-alist +@vindex bug-reference-forge-alist @vindex bug-reference-setup-from-mail-alist @vindex bug-reference-setup-from-irc-alist Right now, there are three types of setup functions. @enumerate @item -Setup for version-controlled files configurable by the variable -@code{bug-reference-setup-from-vc-alist}. The default is able to +Setup for version-controlled files configurable by the variables +@code{bug-reference-forge-alist}, and +@code{bug-reference-setup-from-vc-alist}. The defaults are able to setup GNU projects where @url{https://debbugs.gnu.org} is used as issue tracker and issues are usually referenced as @code{bug#13} (but -many different notations are considered, too), Sourcehut projects -where issues are referenced using the notation @code{#17}, Codeberg -and Github projects where both bugs and pull requests are referenced -using the same notation, and GitLab projects where bugs are referenced -with @code{#17}, too, but merge requests use the @code{!18} notation. +many different notations are considered, too), and several kinds of +modern software forges such as GitLab, Gitea, SourceHut, or GitHub. +If you deploy a self-hosted instance of such a forge, the easiest way +to tell bug-reference about it is through +@code{bug-reference-forge-alist}. @item Setup for email guessing from mail folder/mbox names, and mail header diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi index 20cb8ee2c65..2461cb0f6af 100644 --- a/doc/emacs/mark.texi +++ b/doc/emacs/mark.texi @@ -409,9 +409,14 @@ region by dragging the mouse, you can continue to extend the region using shifted cursor motion commands. In either case, any unshifted cursor motion command deactivates the mark. +@vindex shift-select-mode To turn off shift-selection, set @code{shift-select-mode} to @code{nil}. Doing so does not disable setting the mark via mouse -commands. +commands. If you set @code{shift-select-mode} to the value +@code{permanent}, cursor motion keys that were not shift-translated +will not deactivate the mark, so, for example, the region set by prior +commands can be extended by shift-selection, and unshifted cursor +motion keys will extend the region set by shift-selection. @node Disabled Transient Mark @section Disabling Transient Mark Mode diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi index 6dcee3fa824..b0f6e424a7f 100644 --- a/doc/emacs/mini.texi +++ b/doc/emacs/mini.texi @@ -41,11 +41,14 @@ Alternatively, you can type @kbd{C-g} to exit the minibuffer by canceling the command asking for the argument (@pxref{Quitting}). @cindex default argument +@vindex minibuffer-default-prompt-format Sometimes, the prompt shows a @dfn{default argument}, inside parentheses before the colon. This default will be used as the argument if you just type @key{RET}. For example, commands that read buffer names usually show a buffer name as the default; you can type -@key{RET} to operate on that default buffer. +@key{RET} to operate on that default buffer. You can customize how +the default argument is shown with the user option +@code{minibuffer-default-prompt-format}. @cindex Minibuffer Electric Default mode @cindex mode, Minibuffer Electric Default diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index aba98cf21e1..4b3c2ea4bd2 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -163,14 +163,13 @@ List killed groups (@code{gnus-group-list-killed}). List zombie groups (@code{gnus-group-list-zombies}). @kindex u @r{(Gnus Group mode)} -@findex gnus-group-unsubscribe-current-group +@findex gnus-group-toggle-subscription @cindex subscribe groups @cindex unsubscribe groups @item u Toggle the subscription status of the group -(@code{gnus-group-unsubscribe-current-group}) on the current line -(i.e., turn a subscribed group into an unsubscribed group, or vice -versa). Invoking this on a killed or zombie group turns it into an +(@code{gnus-group-toggle-subscription}) on the current line. +Invoking this on a killed or zombie group turns it into an unsubscribed group. @kindex C-k @r{(Gnus Group mode)} @@ -1114,6 +1113,19 @@ subshell: @end example @end table +By default, Shell mode handles common @acronym{ANSI} escape codes (for +instance, for changing the color of text). Emacs also optionally +supports some extend escape codes, like some of the @acronym{OSC} +(Operating System Codes) if you put the following in your init file: + +@lisp +(add-hook 'comint-output-filter-functions 'comint-osc-process-output) +@end lisp + +With this enabled, the output from, for instance, @code{ls +--hyperlink} will be made into clickable buttons in the Shell mode +buffer. + @cindex Comint mode @cindex mode, Comint Shell mode is a derivative of Comint mode, a general-purpose mode for @@ -1485,14 +1497,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 @@ -1974,6 +1992,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 @@ -2590,7 +2613,7 @@ invoked @code{hexl-mode}. @noindent Other Hexl commands let you insert strings (sequences) of binary bytes, move by @code{short}s or @code{int}s, etc.; type @kbd{C-h a -hexl-@key{RET}} for details. +hexl- @key{TAB}} for details. Hexl mode can also be used for editing text files. This could come in handy if the text file includes unusual characters or uses unusual @@ -2930,6 +2953,33 @@ 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}. + @node Browse-URL @subsection Following URLs @cindex World Wide Web @@ -2974,6 +3024,15 @@ URLs. For more information, view the package commentary by typing @kbd{C-h P browse-url @key{RET}}. +@findex url-handler-mode + Emacs also has a minor mode that has some support for handling +@acronym{URL}s as if they were files. @code{url-handler-mode} is a +global minor mode that affects most of the Emacs commands and +primitives that deal with file names. After switching on this mode, +you can say, for instance, @kbd{C-x C-f https://www.gnu.org/ RET} to +see the @acronym{HTML} for that web page, and you can then edit it and +save it to a local file, for instance. + @node Goto Address mode @subsection Activating URLs @findex goto-address-mode diff --git a/doc/emacs/msdos.texi b/doc/emacs/msdos.texi index 33d389acd50..20eaa0bcb6f 100644 --- a/doc/emacs/msdos.texi +++ b/doc/emacs/msdos.texi @@ -543,7 +543,7 @@ keyboard input in Emacs. conventional uses in MS-Windows programs conflict with traditional Emacs key bindings. (These Emacs key bindings were established years before Microsoft was founded.) Examples of conflicts include -@kbd{C-c}, @kbd{C-x}, @kbd{C-z}, @kbd{C-a}, and @kbd{W-@key{SPC}}. +@kbd{C-c}, @kbd{C-x}, @kbd{C-z}, and @kbd{C-a}. You can redefine some of them with meanings more like the MS-Windows meanings by enabling CUA Mode (@pxref{CUA Bindings}). Another optional feature which will make Emacs behave like other Windows @@ -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 22b3677b5b0..83c775df0e1 100644 --- a/doc/emacs/mule.texi +++ b/doc/emacs/mule.texi @@ -473,6 +473,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 +502,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 +576,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 @@ -1330,6 +1361,12 @@ You can do this by putting @noindent in your init file. +@findex w32-set-console-codepage + Setting @code{keyboard-coding-system} has no effect on MS-Windows, +except on old Windows 9X systems, in which case the encoding must +match the current codepage of the MS-Windows console, which can be +changed by calling @code{w32-set-console-codepage}. + There is a similarity between using a coding system translation for keyboard input, and using an input method: both define sequences of keyboard input that translate into single characters. However, input diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi index d419a4e24b5..570afd5be2b 100644 --- a/doc/emacs/package.texi +++ b/doc/emacs/package.texi @@ -129,7 +129,7 @@ entails. @item w @kindex w @r{(Package Menu)} @findex package-browse-url -Open the home page of the package on the current line in a browser +Open the package website on the current line in a browser (@code{package-browse-url}). @code{browse-url} is used to open the browser. diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index fe3ee57ac0a..0056906e1f7 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -275,8 +275,10 @@ a non-@code{nil} value. There is no need to rescan because of small changes in the text. @vindex imenu-auto-rescan-maxout +@vindex imenu-max-index-time @code{imenu-auto-rescan} will be disabled in buffers that are larger -than @code{imenu-auto-rescan-maxout} in bytes. +than @code{imenu-auto-rescan-maxout} in bytes, and scanning is +stopped if it takes more than @code{imenu-max-index-time} seconds. @vindex imenu-sort-function You can customize the way the menus are sorted by setting the @@ -469,6 +471,23 @@ the function name. This is normally done for macro definitions, using the @code{declare} construct. @xref{Defining Macros,,, elisp, The Emacs Lisp Reference Manual}. + In Emacs Lisp, lists are usually indented as if they are +function-like forms: + +@lisp +(setq foo '(bar zot + gazonk)) +@end lisp + + However, if you add a space after the opening parenthesis, this tells +Emacs that it's a data list instead of a piece of code, and Emacs will +then indent it like this: + +@lisp +(setq foo '( bar zot + gazonk)) +@end lisp + @node C Indent @subsection Commands for C Indentation @@ -809,41 +828,55 @@ displayed. The default is 102400. @cindex Show Paren mode @cindex highlighting matching parentheses @findex show-paren-mode - Show Paren mode, a global minor mode, provides a more powerful kind +@findex show-paren-local-mode + Show Paren mode is a minor mode that provides a more powerful kind of automatic matching. Whenever point is before an opening delimiter or after a closing delimiter, the delimiter, its matching delimiter, and optionally the text between them are highlighted. To toggle Show -Paren mode, type @kbd{M-x show-paren-mode}. To customize it, type -@kbd{M-x customize-group @key{RET} paren-showing}. The customizable -options which control the operation of this mode include: +Paren mode globally, type @kbd{M-x show-paren-mode}. To toggle it +only in the current buffer, type @kbd{M-x show-paren-local-mode}. To +customize it, type @w{@kbd{M-x customize-group @key{RET} paren-showing}}. +The customizable options which control the operation of this mode +include: @itemize @bullet @item @vindex show-paren-highlight-openparen @code{show-paren-highlight-openparen} controls whether to highlight -an open paren when point stands just before it, and hence its position +an open paren when point is just before it, and hence its position is marked by the cursor anyway. The default is non-@code{nil} (yes). @item @vindex show-paren-style @code{show-paren-style} controls whether just the two parens, or also -the space between them get highlighted. The valid options here are +the text between them get highlighted. The valid options here are @code{parenthesis} (show the matching paren), @code{expression} (highlight the entire expression enclosed by the parens), and -@code{mixed} (highlight the matching paren if it is visible, the -expression otherwise). +@code{mixed} (highlight the matching paren if it is visible in the +window, the expression otherwise). @item @vindex show-paren-when-point-inside-paren @code{show-paren-when-point-inside-paren}, when non-@code{nil}, causes -highlighting also when point is on the inside of a parenthesis. +highlighting also when point is inside of the parentheses. The +default is @code{nil}. @item @vindex show-paren-when-point-in-periphery @code{show-paren-when-point-in-periphery}, when non-@code{nil}, causes -highlighting also when point is in whitespace at the beginning or end -of a line, and there is a paren at, respectively, the first or last, -or the last, non-whitespace position on the line. +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 @@ -1098,13 +1131,13 @@ match the last comment before point in the buffer, and then does a expression that is the value of the variable @code{comment-start-skip}. Make sure this regexp does not match the null string. It may match more than the comment starting delimiter in the strictest sense of the word; -for example, in C mode the value of the variable is +for example, in C mode the value of the variable could be @c This stops M-q from breaking the line inside that @code. -@code{@w{"\\(//+\\|/\\*+\\)\\s *"}}, which matches extra stars and -spaces after the @samp{/*} itself, and accepts C++ style comments -also. (Note that @samp{\\} is needed in Lisp syntax to include a -@samp{\} in the string, which is needed to deny the first star its -special meaning in regexp syntax. @xref{Regexp Backslash}.) +@code{@w{"/\\*+[ \t]*\\|//+[ \t]*"}}, which matches extra stars and +spaces after the @samp{/*} itself, and accepts C++ style (@samp{//}) +comments also. (Note that @samp{\\} is needed in Lisp syntax to +include a @samp{\} in the string, which is needed to deny the first +star its special meaning in regexp syntax. @xref{Regexp Backslash}.) @vindex comment-start @vindex comment-end diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi index a1760ad66ff..fbbb1f6e682 100644 --- a/doc/emacs/search.texi +++ b/doc/emacs/search.texi @@ -222,6 +222,15 @@ going past the original starting point of the search, it changes to @samp{Overwrapped}, which means that you are revisiting matches that you have already seen. +@vindex isearch-wrap-pause + You can control what happens when there are no more matches by +customizing the @code{isearch-wrap-pause} user option. If it is +@code{t} (the default), signal an error. (Repeating the search will +wrap around.) If @code{no}, issue a @code{ding} and wrap immediately +after reaching the last match. If @code{no-ding}, wrap immediately, +but don't @code{ding}. Finally, if @code{nil}, never wrap, but just +stop at the last match. + @cindex search ring @findex isearch-ring-advance @findex isearch-ring-retreat @@ -328,6 +337,16 @@ value of the variable @code{search-upper-case} (@pxref{Lax Search, search-upper-case}) is other than @code{not-yanks}, that disables this down-casing. +@kindex M-s M-. +@findex isearch-forward-thing-at-point + To begin a new incremental search with the text near point yanked +into the initial search string, type @kbd{M-s M-.} that runs the +command @code{isearch-forward-thing-at-point}. If the region was +active, then it yanks the text from the region into the search string. +Otherwise, it tries to yank a URL, a symbol or an expression found +near point. What to yank is defined by the user option +@code{isearch-forward-thing-at-point}. + @node Error in Isearch @subsection Errors in Incremental Search @@ -593,6 +612,19 @@ or the selected window and frame. The command must not itself attempt an incremental search. This feature is disabled if @code{isearch-allow-scroll} is @code{nil} (which it is by default). +@vindex isearch-allow-motion +@vindex isearch-motion-changes-direction + Likewise, if you change the variable @code{isearch-allow-motion} +to a non-@code{nil} value, this enables the use of the keyboard motion +commands @kbd{M-<}, @kbd{M->}, @kbd{C-v} and @kbd{M-v}, to move +respectively to the first occurrence of the current search string in +the buffer, the last one, the first one after the current window, +and the last one before the current window. The search direction +does not change when these motion commands are used, unless you change +the variable @code{isearch-motion-changes-direction} to a non-@code{nil} +value, in which case the search direction is forward after @kbd{M-<} and +@kbd{C-v}, and backward after @kbd{M->} and @kbd{M-v}. + @item Motion Commands @cindex motion commands, during incremental search When @code{isearch-yank-on-move} is customized to @code{shift}, @@ -1309,10 +1341,9 @@ matches @w{@samp{foo bar}}, @w{@samp{foo@ @ bar}}, precisely, Emacs matches each sequence of space characters in the search string to a regular expression specified by the variable @code{search-whitespace-regexp}. For example, to make spaces match -sequences of newlines as well as spaces, set it to -@samp{"[[:space:]\n]+"}. The default value of this variable depends -on the buffer's major mode; most major modes classify spaces, tabs, -and formfeed characters as whitespace. +sequences of newlines as well as spaces, set it to the regular expression +@samp{[[:space:]\n]+}. The default value of this variable considers +any sequence of spaces and tab characters as whitespace. If you want whitespace characters to match exactly, you can turn lax space matching off by typing @kbd{M-s @key{SPC}} diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi index c9c4be3c61d..ead0f699bb3 100644 --- a/doc/emacs/text.texi +++ b/doc/emacs/text.texi @@ -572,7 +572,7 @@ Set the fill column (@code{set-fill-column}). Fill each paragraph in the region (@code{fill-region}). @item M-x fill-region-as-paragraph Fill the region, considering it as one paragraph. -@item M-o M-s +@item M-x center-line Center a line. @end table @@ -621,10 +621,9 @@ numeric argument, it uses that as the new fill column. With just @kbd{C-u} as argument, it sets @code{fill-column} to the current horizontal position of point. -@kindex M-o M-s @r{(Text mode)} @cindex centering @findex center-line - The command @kbd{M-o M-s} (@code{center-line}) centers the current line + The command @kbd{M-x center-line} centers the current line within the current fill column. With an argument @var{n}, it centers @var{n} lines individually and moves past them. This binding is made by Text mode and is available only in that and related modes @@ -997,6 +996,20 @@ 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 +outline heading lines. @kbd{TAB} cycles hiding, showing the +sub-heading, and showing all for the current section. @kbd{S-@key{TAB}} +does the same for the entire buffer. + @menu * Outline Format:: What the text of an outline looks like. * Outline Motion:: Special commands for moving through outlines. diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi index 9a638818c91..027086cab50 100644 --- a/doc/emacs/trouble.texi +++ b/doc/emacs/trouble.texi @@ -393,7 +393,7 @@ this---saving them---updates the files themselves. associated with any files, or if the autosave was not recent enough to have recorded important changes, you can use the @file{etc/emacs-buffer.gdb} script with GDB (the GNU Debugger) to -retrieve them from a core dump--provided that a core dump was saved, +retrieve them from a core dump---provided that a core dump was saved, and that the Emacs executable was not stripped of its debugging symbols. @@ -1352,8 +1352,13 @@ downloaded the repository source, you should read the file from a normal build). If you would like to make more extensive contributions, see the -@file{CONTRIBUTE} file in the Emacs distribution for information on -how to be an Emacs developer. +@file{CONTRIBUTE} file in the Emacs source tree for information on how +to be an Emacs developer. That file is distributed as part of the source +tarball of every released Emacs version, and can also be found on-line +in the @url{https://git.savannah.gnu.org/cgit/emacs.git/tree/CONTRIBUTE, +Emacs on-line source repository}. If you cloned the Emacs repository, +per the instructions in @url{https://savannah.gnu.org/projects/emacs/}, +you will find this file in the top directory of the source Emacs tree. For documentation on Emacs (to understand how to implement your desired change), refer to: diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi index facbc7f3ed8..27c754133f7 100644 --- a/doc/emacs/windows.texi +++ b/doc/emacs/windows.texi @@ -444,7 +444,7 @@ selected window write: @group (customize-set-variable 'display-buffer-alist - '("\\*scratch\\*" (display-buffer-same-window))) + '(("\\*scratch\\*" (display-buffer-same-window)))) @end group @end example @@ -603,16 +603,16 @@ buffer. @xref{Follow Mode}. between neighboring windows in a frame. @kbd{M-x windmove-right} selects the window immediately to the right of the currently selected one, and similarly for the left, up, and down counterparts. -@w{@kbd{M-x windmove-default-keybindings}} binds these commands to +@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 defined for commands that select windows directionally, you can use -@w{@kbd{M-x windmove-display-default-keybindings}} to define -keybindings for commands that specify in what direction to display the -window for the buffer that the next command is going to display. -Also there is @w{@kbd{M-x windmove-delete-default-keybindings}} to -define keybindings for commands that delete windows directionally, and -@w{@kbd{M-x windmove-swap-states-default-keybindings}} that defines +@code{windmove-display-default-keybindings} to define keybindings for +commands that specify in what direction to display the window for the +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 window with the window in the specified direction. |