diff options
Diffstat (limited to 'doc')
98 files changed, 4998 insertions, 2327 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. diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index fade4096e38..f5f79a543cb 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -238,7 +238,7 @@ supports it in developing GNU and promoting software freedom.'' @ifset WWW_GNU_ORG @html -<p>The homepage for GNU Emacs is at +<p>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/eintr.html">here</a>. @@ -1162,6 +1162,10 @@ computer. Often, people use the term @dfn{expression} indiscriminately. (Also, in many texts, the word @dfn{form} is used as a synonym for expression.) +@c This and the next paragraph say ``kinds of atom'', but that is not +@c a typo, just slightly ``old-fashioned wording which adds a fillip +@c of interest to it'', and ``is more elegant writing'', according to +@c RMS. Incidentally, the atoms that make up our universe were named such when they were thought to be indivisible; but it has been found that physical atoms are not indivisible. Parts can split off an atom or it can @@ -4201,7 +4205,7 @@ times. The part of the buffer between point and mark is called @dfn{the region}. Numerous commands work on the region, including -@code{center-region}, @code{count-lines-region}, @code{kill-region}, and +@code{center-region}, @code{count-words-region}, @code{kill-region}, and @code{print-region}. The @code{save-excursion} special form saves the location of point and @@ -4214,7 +4218,7 @@ evaluated. In Emacs, a function frequently moves point as part of its internal workings even though a user would not expect this. For example, -@code{count-lines-region} moves point. To prevent the user from being +@code{count-words-region} moves point. To prevent the user from being bothered by jumps that are both unexpected and (from the user's point of view) unnecessary, @code{save-excursion} is often used to keep point in the location expected by the user. The use of @@ -4893,6 +4897,23 @@ region. @c FIXME: the definition of append-to-buffer has been changed (in @c 2010-03-30). +@c In Bug#8275, Stefan Monner <monnier@iro.umontreal.ca> writes: +@c >> Do you want to fix this, or shall I try? The problem is that +@c >> append-to-buffer now uses let* and with-current-buffer, so this might +@c >> break the flow of the text. At this point in the book, let* and +@c >> with-current-buffer are not yet introduced. +@c > +@c > Here are some thoughts: +@c > - I don't think it's of any importance that the example code be +@c > identical to the currently used code. +@c > - append-to-buffer might not be the best example since AFAICT copying +@c > text from one buffer to another is not a common operation and in most +@c > cases this is done via buffer-substring + insert (often with some +@c > processing on the string between the two) rather than with +@c > insert-buffer-substring which is a rarely used function. +@c > - yes, I think the text would benefit from some rethink to try and present +@c > with-current-buffer in preference to set-buffer, but it's not +@c > a simple fix. @node append-to-buffer @section The Definition of @code{append-to-buffer} @findex append-to-buffer @@ -8767,7 +8788,7 @@ keeps the kill ring from growing too long. It looks like this: The code checks whether the length of the kill ring is greater than the maximum permitted length. This is the value of -@code{kill-ring-max} (which is 60, by default). If the length of the +@code{kill-ring-max} (which is 120, by default). If the length of the kill ring is too long, then this code sets the last element of the kill ring to @code{nil}. It does this by using two functions, @code{nthcdr} and @code{setcdr}. @@ -13473,10 +13494,9 @@ The template for an interactive function definition is, as always: What we need to do is fill in the slots. -The name of the function should be self-explanatory and similar to the -existing @code{count-lines-region} name. This makes the name easier +The name of the function should be self-explanatory and easy to remember. @code{count-words-region} is the obvious choice. Since -that name is now used for the standard Emacs command to count words, we +that name is used for the standard Emacs command to count words, we will name our implementation @code{@value{COUNT-WORDS}}. The function counts words within a region. This means that the @@ -14650,7 +14670,9 @@ Let's re-use @kbd{C-c =} as a convenient keybinding: Now we can try out @code{count-words-defun}: install both @code{count-words-in-defun} and @code{count-words-defun}, and set the -keybinding, and then place the cursor within the following definition: +keybinding. Then copy the following to an Emacs Lisp buffer (like, +for instance, @file{*scratch*}), place the cursor within the +definition, and use the @kbd{C-c =} command. @smallexample @group @@ -17455,9 +17477,9 @@ Manual}, for more information. @findex line-to-top-of-window @cindex Simple extension in @file{.emacs} file -Here is a simple extension to Emacs that moves the line point is on to -the top of the window. I use this all the time, to make text easier -to read. +Here is a simple extension to Emacs that moves the line that point is +on to the top of the window. I use this all the time, to make text +easier to read. You can put the following code into a separate file and then load it from your @file{.emacs} file, or you can include it within your @@ -17838,7 +17860,7 @@ xmodmap -e "keysym Alt_L = Meta_L Alt_L" Finally, a feature I really like: a modified mode line. When I work over a network, I forget which machine I am using. Also, -I tend to I lose track of where I am, and which line point is on. +I tend to lose track of where I am, and which line point is on. So I reset my mode line to look like this: diff --git a/doc/lispref/anti.texi b/doc/lispref/anti.texi index ced8082f6a4..118df05c791 100644 --- a/doc/lispref/anti.texi +++ b/doc/lispref/anti.texi @@ -6,186 +6,179 @@ @c This node must have no pointers. @node Antinews -@appendix Emacs 26 Antinews +@appendix Emacs 27 Antinews @c Update the elisp.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 greater +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 -Lisp objects are again implemented on the C level as integer types, -not as pointers. This might be a small step for Emacs Lisp users, but -it's a giant leap for the Emacs developers who work on the C level, -since it is now again easy to print Lisp object in the debugger in the -decimal format, which is so much easier for debugging. It also makes -calling Emacs functions from the debugger easier, and allows us to -freely mix integers and Lisp objects in the C code. +The annoying @code{lexical-binding} local variable now heeds the +value of @code{enable-local-variables}: if it's @code{nil}, the +@code{lexical-binding} cookie is ignored. We are working hard on +removing the lexical-binding support in some past Emacs version, and +this small step advances us back to that change. @item -The test suite was removed from the distribution tarball. We believe -that tests need seldom if ever be run, certainly not by the end -users. Removing the tests from the tarball makes it much smaller, -which is important since disk space becomes more and more at premium -as you move back in time. +The @code{load-dangerous-libraries} variable is not obsolete, as it +must be used to allow loading Lisp compiled by XEmacs, which will +become more and more important as you move back in time. @item -Dynamic module support is disabled by default. This both makes Emacs -smaller (a worthy goal by itself), and removes the complications and -additional complexity related with installing module support files and -letting random shared objects an opportunity to be loaded into Emacs -and mess with it. +The optional @var{modes} argument of @code{interactive} is not +supported, and every command is deemed applicable to any major mode. +We believe this makes the life of Lisp programmers much simpler, as +there's now no need to tag commands with the modes where they make +sense. @item -You now must activate any installed packages only after loading your -init files. That requires an explicit call to -@code{package-initialize} in your init file, which is a Good Thing, as -it makes you think seriously where and indeed whether you'd like your -packages to become available to your sessions. Simplicity should -tramp convenience! +Shorthands for Lisp symbols have been removed, which makes loading +Lisp files and handling Lisp symbols much simpler and more efficient. +This is important for decent performance on slower CPUs as you move +back in time. @item To reduce the amount of code in Emacs related to unimportant features, -we've removed native rotation and resizing of images. You will have -to build Emacs with ImageMagick if you want to resize or rotate images -inside Emacs. We don't expect anyone to miss that. +we've removed the variables @code{global-minor-modes} and +@code{local-minor-modes}. If your Lisp program needs to determine +whether some minor mode is in effect, it will have to test explicitly +for every mode. We don't expect anyone to miss those fancy variables. @item -We've re-enabled color fonts usage by the XFT font back-end. We -consider the availability of these fonts more important than a random -crash here and there, especially since the use of these fonts for -displaying Emoji will become less and less important as we travel back -in time, and will completely disappear in some past Emacs version. +The default preference for servicing sub-processes that produce output +at a high rate, and the associated variable +@code{process-prioritize-lower-fds}, have been removed. Moving back +in time means fewer and fewer programs can produce such high-rate +output, so this features becomes just useless crud. @item -The function @code{network-interface-list} can now return only IPv4 -addresses. We consider the complexity introduced by IPv6 to be too -much to be justified, and on the other hand its removal is the step in -the right direction, given that IPv6 is expected to be completely -removed as we move back in time. +The encodings that are variants of EBCDIC were removed. This includes +@code{ibm256}, @code{ibm273}, and others---variants of the EBCDIC +encoding tailored for some Japanese and European locales. You won't +need those where you are going. @item -The limit on repetitions in regular expressions was reduced to -@ifnottex -2**15 @minus{} 1. -@end ifnottex -@tex -@math{2^{15}-1}. -@end tex -We envision that regular expressions will become more and more simple -as we move towards the distant past. +The ``Bindat type expression'' description language has been removed, +as the existing data layout specifications are perfectly suited for +this job. @item To simplify code and reduce complexity, we removed the capability of -searching programs on remote hosts in @code{executable-find}. If you -really need this feature (why would you?), you can always write your -own shell script and run it on the remote. +specifying the success handler in @code{condition-case} via the +@code{:success} keyword. If you really need this feature (why would +you?), you can always write some simple Lisp that has the same effect. @item -The @code{:extend} face attribute is no longer available; all faces -have their background color extended by default past end of line. -This should significantly simplify face management and remove -unnecessary code bloat, as well as make faces significantly simpler to -understand and use. +Emacs modules can no longer provide interactive functions, or install +finalizers, nor open channels to existing pipe sub-processes. All +this is extra ballast, especially since we plan on removing modules in +some past Emacs version. The @code{make_unibyte_string} module API +was removed for the same reason. @item -The predicates @code{display-blink-cursor-p} and -@code{display-symbol-keys-p} were deleted. They are rarely if ever -needed, and can easily be substituted by appropriate calls to old and -proven APIs like @code{display-graphic-p}. As an additional bonus, -writing Lisp programs that depend on this functionality will make sure -the programmer understands better what exactly is the required -features of the display terminal. +To keep Emacs clean and elegant, we've removed the +@code{print-integers-as-characters} option. Recognizing characters by +their decimal codes is a basic requirement for Emacs Lisp programmers, +and with the expected decrease in use of Unicode characters, this will +be soon limited to ASCII only: surely something you all can master! @item -Relative directories in the value of the @env{HOME} environment -variable are once again interpreted relative to the -@code{default-directory} of the current buffer. This is much simpler, -and also allows @env{HOME} to resolve to a different place in -different buffers, which allows some interesting applications. +The optional @var{count} argument of the @code{directory-files} +function has been removed. Extracting the first @var{n} members from +the full list is trivial, so this is a significant simplification for +an insignificant cost. -For the same reasons, @code{file-name-absolute-p} now again considers -@file{~foo} an absolute file name, even if there's no known user -@samp{foo}. This means a Lisp program which uses such file names will -always work the same on any system, regardless of its known users. +@item +Functions that create sub-processes and network connections no longer +accept the @code{:coding} argument; use +@code{set-process-coding-system} or bind +@code{coding-system-for-read/write} instead: again, a significant +reduction in Emacs complexity for little or no cost. + +@item +We deleted from the macros @code{define-derived-mode} and +@code{define-minor-mode} the code which allowed using the +@code{:interactive} argument. The possibility of marking a mode +non-interactive makes very little sense, + +@item +The possibility of having links to man pages in doc strings has been +removed. Use plain text instead, if you need such references. + +@item +Temporary buffers are no longer exempt from running any buffer-related +hooks. Programs that don't want such hooks in some buffer can always +disable it locally, whereas making that simpler complicates Emacs for +no good reason. @item -File-related primitives like @code{file-attributes}, -@code{file-modes}, @code{file-newer-than-file-p}, and some others once -again return @code{nil} when the underlying low-level APIs fail, -instead of signaling an error. We decided that functions which signal -errors require more complex code from Lisp programs which use them, -and found this complexity unjustified when returning @code{nil} will -do. +Several features that complicated the byte compiler have been removed: +@itemize @minus @item -Similarly, old-style backquotes no longer signal errors; they generate -warnings instead. You can remove error handling from programs that -use backquotes. +The checks for missing declarations of dynamic variables. This will +continue making less and less sense as we move away of lexical-binding +support. @item -Formatting floating-point numbers has been sped up by letting the -underlying implementation produce unpredictable values, instead of -signaling errors when the number is too large to format correctly. We -believe the Emacs Lisp programmers should always know what they are -doing when they deal with floating-point values. +The ability of compiling symlinked @file{*.el} files, which is really +gross: copy the files instead. @item -The function @code{read-char-from-minibuffer} was deleted. We decided -that @code{read-char} should be enough for any Lisp program that needs -to ask the user for a single-character input, in recognition of the -fact that nothing makes Emacs Lisp hackers rejoice more than the need -to sit down and write yet another interactive question-and-answer -function, and make it optimal for each specific case. Consequently, -no history is provided for such responses (why would someone want -history of single-key strokes, anyway?). +The warnings about too-wide doc strings---that is just a nuisance, as +the programmers should be trusted to know what they are doing. +@end itemize + + +@item +We deleted several features of the @code{pcase} macro, in accordance +with our general plane to remove @code{pcase} from Emacs: +@itemize @minus @item -The function @code{ngettext} was deleted. Non-English languages will -become less and less widespread, let alone useful, as you move back in -time, so we took this small step in that direction, and simplified -Emacs as a nice bonus. +The @code{cl-type} pattern. @item -Focus-change notifications on text-mode frames are no longer -recognized or supported. You can now safely disregard the possibility -of receiving such notifications on TTY frames. This is one small step -on the long road of removing all non-character input events Emacs -supports on TTY frames. +the @code{pcase-setq} macro. + +@item +The @code{pcase-compile-patterns} function. +@end itemize @item -Face specifications in @code{face-remapping-alist} now have to be -buffer-specific, without any differences between windows showing the -same buffers. This allowed us to remove a lot of unneeded code bloat -from Emacs, and make the face handling much simpler. +Some of the keywords used in Edebug specification lists were deemed to +be of little use, and were therefore removed: @code{&interpose}, +@code{&error}, and @code{&name}. The long-term plane is for Emacs to +drop Edebug entirely, leaving only the trusted Lisp debugger, and we +continue working according to that plan. @item -The @samp{%o} and @samp{%x} formats now always produce unsigned -values, as you'd expect. This allows you to reveal the underlying -machine representation, which is different on each architecture, -something we consider a valuable feature. +The function @code{object-intervals} was dropped, as a Lisp program +can easily collect the intervals of a buffer or a string by iterating +through them one by one. @item -We no longer highlight in @code{font-lock-warning-face} symbols with -confusable quote characters, such as U+2018. Detecting them -needed non-trivial amount of code, and we firmly believe that Lisp -programmers always know what they are doing, and don't need to be -annoyed with typefaces that stand out and distract. +We decided that the @code{require-theme} function is an unnecessary +complication, so we deleted it. Lisp programs can easily search along +@code{custom-theme-load-path} instead. @item -The function @code{file-system-info} was dropped on Posix platforms, -since you can always invoke @command{df} instead and parse its -output. +The convenience functions @code{length<}, @code{length>}, and +@code{length=} were removed, as using @code{length} followed by a +comparison should be good enough for everyone, especially considering +that the typical length of a list keeps going down as you move back +through time. @item -The functions that implement the @samp{base64url} encoding were -removed, as they can always be emulated by suitable tweaking of the -normal base-64 encoding. No need to bloat Emacs and force Lisp -programmers learn more interfaces on this account. +The variable @code{current-minibuffer-command} is no longer available, +as we found little justification for keeping it. @item As part of the ongoing quest for simplicity, many other functions and -variables have been eliminated. +variables have been eliminated. Other functions and variables, that +were declared obsolete since Emacs 23, have been added back, in +preparation for releasing Emacs 23 in some distant past. @end itemize diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 55e9d00d8bf..6a0095dca97 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -89,11 +89,12 @@ in which most editing takes place. Most of the primitives for examining or changing text operate implicitly on the current buffer (@pxref{Text}). - Normally, the buffer displayed in the selected window is the current -buffer, but this is not always so: a Lisp program can temporarily -designate any buffer as current in order to operate on its contents, -without changing what is displayed on the screen. The most basic -function for designating a current buffer is @code{set-buffer}. + Normally, the buffer displayed in the selected window +(@pxref{Selecting Windows}) is the current buffer, but this is not +always so: a Lisp program can temporarily designate any buffer as +current in order to operate on its contents, without changing what is +displayed on the screen. The most basic function for designating a +current buffer is @code{set-buffer}. @defun current-buffer This function returns the current buffer. @@ -118,12 +119,12 @@ on it. When an editing command returns to the editor command loop, Emacs automatically calls @code{set-buffer} on the buffer shown in the -selected window. This is to prevent confusion: it ensures that the -buffer that the cursor is in, when Emacs reads a command, is the -buffer to which that command applies (@pxref{Command Loop}). Thus, -you should not use @code{set-buffer} to switch visibly to a different -buffer; for that, use the functions described in @ref{Switching -Buffers}. +selected window (@pxref{Selecting Windows}). This is to prevent +confusion: it ensures that the buffer that the cursor is in, when Emacs +reads a command, is the buffer to which that command applies +(@pxref{Command Loop}). Thus, you should not use @code{set-buffer} to +switch visibly to a different buffer; for that, use the functions +described in @ref{Switching Buffers}. When writing a Lisp function, do @emph{not} rely on this behavior of the command loop to restore the current buffer after an operation. @@ -912,16 +913,17 @@ History}) provided it is shown in that window. If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the current buffer. In addition, if the current buffer is displayed in the -selected window, this makes sure that the window is either deleted or -another buffer is shown in it. More precisely, if the selected window -is dedicated (@pxref{Dedicated Windows}) and there are other windows on -its frame, the window is deleted. If it is the only window on its frame -and that frame is not the only frame on its terminal, the frame is -dismissed by calling the function specified by -@code{frame-auto-hide-function} (@pxref{Quitting Windows}). Otherwise, -it calls @code{switch-to-prev-buffer} (@pxref{Window History}) to show -another buffer in that window. If @var{buffer-or-name} is displayed in -some other window, it remains displayed there. +selected window (@pxref{Selecting Windows}), this makes sure that the +window is either deleted or another buffer is shown in it. More +precisely, if the selected window is dedicated (@pxref{Dedicated +Windows}) and there are other windows on its frame, the window is +deleted. If it is the only window on its frame and that frame is not +the only frame on its terminal, the frame is dismissed by calling the +function specified by @code{frame-auto-hide-function} (@pxref{Quitting +Windows}). Otherwise, it calls @code{switch-to-prev-buffer} +(@pxref{Window History}) to show another buffer in that window. If +@var{buffer-or-name} is displayed in some other window, it remains +displayed there. To replace a buffer in all the windows that display it, use @code{replace-buffer-in-windows}, @xref{Buffers and Windows}. diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index b4a8b733a0b..6ed46fa6a27 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -601,6 +601,9 @@ Put them into three windows, selecting the last one." @node Command Modes @subsection Specifying Modes For Commands +@cindex commands, mode-specific +@cindex commands, specify as mode-specific +@cindex mode-specific commands Many commands in Emacs are general, and not tied to any specific mode. For instance, @kbd{M-x kill-region} can be used in pretty much any @@ -1173,6 +1176,7 @@ intended by Lisp code to be used as an event. * Repeat Events:: Double and triple click (or drag, or down). * Motion Events:: Just moving the mouse, not pushing a button. * Focus Events:: Moving the mouse between frames. +* Xwidget Events:: Events generated by xwidgets. * Misc Events:: Other events the system can generate. * Event Examples:: Examples of the lists for mouse events. * Classifying Events:: Finding the modifier keys in an event symbol. @@ -1421,9 +1425,12 @@ binding of the key sequence. @subsection Click Events @cindex click event @cindex mouse click event +@cindex mouse wheel event When the user presses a mouse button and releases it at the same -location, that generates a @dfn{click} event. All mouse click event +location, that generates a @dfn{click} event. Depending on how your +window-system reports mouse-wheel events, turning the mouse wheel can +generate either a mouse click or a mouse-wheel event. All mouse event share the same format: @example @@ -1434,7 +1441,8 @@ share the same format: @item @var{event-type} This is a symbol that indicates which mouse button was used. It is one of the symbols @code{mouse-1}, @code{mouse-2}, @dots{}, where the -buttons are numbered left to right. +buttons are numbered left to right. For mouse-wheel event, it can be +@code{wheel-up} or @code{wheel-down}. You can also use prefixes @samp{A-}, @samp{C-}, @samp{H-}, @samp{M-}, @samp{S-} and @samp{s-} for modifiers alt, control, hyper, meta, shift @@ -1447,19 +1455,20 @@ describe events by their types; thus, if there is a key binding for @item @var{position} @cindex mouse position list -This is a @dfn{mouse position list} specifying where the mouse click +This is a @dfn{mouse position list} specifying where the mouse event occurred; see below for details. @item @var{click-count} This is the number of rapid repeated presses so far of the same mouse -button. @xref{Repeat Events}. +button or the number of repeated turns of the wheel. @xref{Repeat +Events}. @end table To access the contents of a mouse position list in the -@var{position} slot of a click event, you should typically use the +@var{position} slot of a mouse event, you should typically use the functions documented in @ref{Accessing Mouse}. -The explicit format of the list depends on where the click occurred. +The explicit format of the list depends on where the event occurred. For clicks in the text area, mode line, header line, tab line, or in the fringe or marginal areas, the mouse position list has the form @@ -1474,11 +1483,11 @@ The meanings of these list elements are as follows: @table @asis @item @var{window} -The window in which the click occurred. +The window in which the mouse event occurred. @item @var{pos-or-area} The buffer position of the character clicked on in the text area; or, -if the click was outside the text area, the window area where it +if the event was outside the text area, the window area where it occurred. It is one of the symbols @code{mode-line}, @code{header-line}, @code{tab-line}, @code{vertical-line}, @code{left-margin}, @code{right-margin}, @code{left-fringe}, or @@ -1490,10 +1499,10 @@ happens after the imaginary prefix keys for the event are registered by Emacs. @xref{Key Sequence Input}. @item @var{x}, @var{y} -The relative pixel coordinates of the click. For clicks in the text +The relative pixel coordinates of the event. For events in the text area of a window, the coordinate origin @code{(0 . 0)} is taken to be the top left corner of the text area. @xref{Window Sizes}. For -clicks in a mode line, header line or tab line, the coordinate origin +events in a mode line, header line or tab line, the coordinate origin is the top left corner of the window itself. For fringes, margins, and the vertical border, @var{x} does not have meaningful data. For fringes and margins, @var{y} is relative to the bottom edge of the @@ -1505,9 +1514,9 @@ The time at which the event occurred, as an integer number of milliseconds since a system-dependent initial time. @item @var{object} -Either @code{nil}, which means the click occurred on buffer text, or a +Either @code{nil}, which means the event occurred on buffer text, or a cons cell of the form @w{(@var{string} . @var{string-pos})} if there -is a string from a text property or an overlay at the click position. +is a string from a text property or an overlay at the event position. @table @asis @item @var{string} @@ -1592,7 +1601,8 @@ handle), @code{up} (the up arrow at one end of the scroll bar), or @end table For clicks on the frame's internal border (@pxref{Frame Layout}), -@var{position} has this form: +the frame's tool bar (@pxref{Tool Bar}) or tab bar, @var{position} +has this form: @example (@var{frame} @var{part} (@var{X} . @var{Y}) @var{timestamp}) @@ -1600,19 +1610,20 @@ For clicks on the frame's internal border (@pxref{Frame Layout}), @table @asis @item @var{frame} -The frame whose internal border was clicked on. +The frame whose internal border or tool bar or tab bar was clicked on. @item @var{part} -The part of the internal border which was clicked on. This can be one +The part of the frame which was clicked on. This can be one of the following: @table @code -@item nil -The frame does not have an internal border. This usually happens on -text-mode frames. This can also happen on GUI frames with internal -border if the frame doesn't have its @code{drag-internal-border} -parameter (@pxref{Mouse Dragging Parameters}) set to a non-@code{nil} -value. +@cindex tool-bar mouse events +@item tool-bar +The frame has a tool bar, and the event was in the tool-bar area. + +@cindex tab-bar mouse events +@item tab-bar +The frame has a tab bar, and the event was in the tab-bar area. @item left-edge @itemx top-edge @@ -1626,6 +1637,13 @@ canonical character from the border's nearest corner. @itemx bottom-right-corner @itemx bottom-left-corner The click was on the corresponding corner of the internal border. + +@item nil +The frame does not have an internal border, and the event was not on +the tab bar or the tool bar. This usually happens on text-mode +frames. This can also happen on GUI frames with internal border if +the frame doesn't have its @code{drag-internal-border} parameter +(@pxref{Mouse Dragging Parameters}) set to a non-@code{nil} value. @end table @end table @@ -1854,6 +1872,85 @@ sequence---that is, after a prefix key---then Emacs reorders the events so that the focus event comes either before or after the multi-event key sequence, and not within it. +@node Xwidget Events +@subsection Xwidget events + +Xwidgets (@pxref{Xwidgets}) can send events to update Lisp programs on +their status. These events are dubbed @code{xwidget-events}, and +contain various data describing the nature of the change. + +@table @code +@cindex @code{xwidget-event} event +@item (xwidget-event @var{kind} @var{xwidget} @var{arg}) +This event is sent whenever some kind of update occurs in +@var{xwidget}. There are several types of updates, identified by +their @var{kind}. + +@table @code +@cindex @code{load-changed} xwidget event +@item load-changed +This xwidget event indicates that the @var{xwidget} has reached a +particular point of the page-loading process. When these events are +sent, @var{arg} will contain a string that futher describes the status +of the widget: + +@table @samp +@cindex @samp{load-started} in xwidgets +@item load-started +This means the widget has begun a page-loading operation. + +@cindex @samp{load-finished} in xwidgets +@item load-finished +This means the @var{xwidget} has finished processing whatever +page-loading operation that it was previously performing. + +@cindex @samp{load-redirected} in xwidgets +@item load-redirected +This means the @var{xwidget} has encountered and followed a redirect +during the page-loading operation. + +@cindex @samp{load-committed} in xwidgets +@item load-committed +This means the @var{xwidget} has committed to a given URL during the +page-loading operation, i.e.@: the URL is the final URL that will be +rendered by @var{xwidget} during the current page-loading operation. +@end table + +@cindex @code{download-callback} xwidget events +@item download-callback +This event indicates that a download of some kind has been completed. +@end table + +In the above events, there can be arguments after @var{arg}, which +itself indicates the URL from which the download file was retrieved: +the first argument after @var{arg} indicates the MIME type of the +download, as a string, while the second argument contains the full +file name of the downloaded file. + +@table @code +@cindex @code{download-started} xwidget events +@item download-started +This event indicates that a download has been started. In these +events, @var{arg} contains the URL of the file that is currently being +downloaded. + +@cindex @code{javascript-callback} xwidget events +@item javascript-callback +This event contains JavaScript callback data. These events are used +internally by @code{xwidget-webkit-execute-script}. +@end table + +@cindex @code{xwidget-display-event} event +@item (xwidget-display-event @var{xwidget}) +This event is sent whenever an xwidget requests that another xwidget +be displayed. @var{xwidget} is the xwidget that should be displayed. + +@var{xwidget}'s buffer will be set to a temporary buffer. When +displaying the widget, care should be taken to replace the buffer with +the buffer in which the xwidget will be displayed, using +@code{set-xwidget-buffer} (@pxref{Xwidgets}). +@end table + @node Misc Events @subsection Miscellaneous System Events @@ -2337,10 +2434,9 @@ This function returns position information corresponding to pixel coordinates @var{x} and @var{y} in a specified frame or window, @var{frame-or-window}, which defaults to the selected window. The coordinates @var{x} and @var{y} are relative to the -frame or window used. -If @var{whole} is @code{nil}, the coordinates are relative -to the window text area, otherwise they are relative to -the entire window area including scroll bars, margins and fringes. +text area of the selected window. +If @var{whole} is @code{non-nil}, the @var{x} coordinate is relative +to the entire window area including scroll bars, margins and fringes. @end defun @node Accessing Scroll @@ -2600,10 +2696,14 @@ returns the key sequence as a vector, never as a string. @cindex upper case key sequence @cindex downcasing in @code{lookup-key} @cindex shift-translation +@vindex translate-upper-case-key-bindings If an input character is upper-case (or has the shift modifier) and has no key binding, but its lower-case equivalent has one, then -@code{read-key-sequence} converts the character to lower case. Note -that @code{lookup-key} does not perform case conversion in this way. +@code{read-key-sequence} converts the character to lower case. (This +behaviour can be disabled by setting the +@code{translate-upper-case-key-bindings} user option to @code{nil}.) +Note that @code{lookup-key} does not perform case conversion in this +way. @vindex this-command-keys-shift-translated When reading input results in such a @dfn{shift-translation}, Emacs @@ -3568,17 +3668,19 @@ commands. @cindex exit recursive editing @cindex aborting To invoke a recursive editing level, call the function -@code{recursive-edit}. This function contains the command loop; it also -contains a call to @code{catch} with tag @code{exit}, which makes it -possible to exit the recursive editing level by throwing to @code{exit} -(@pxref{Catch and Throw}). If you throw a @code{nil} value, then -@code{recursive-edit} returns normally to the function that called it. -The command @kbd{C-M-c} (@code{exit-recursive-edit}) does this. -Throwing a @code{t} value causes @code{recursive-edit} to quit, so that -control returns to the command loop one level up. This is called -@dfn{aborting}, and is done by @kbd{C-]} (@code{abort-recursive-edit}). -You can also throw a function value. In that case, +@code{recursive-edit}. This function contains the command loop; it +also contains a call to @code{catch} with tag @code{exit}, which makes +it possible to exit the recursive editing level by throwing to +@code{exit} (@pxref{Catch and Throw}). Throwing a @code{t} value +causes @code{recursive-edit} to quit, so that control returns to the +command loop one level up. This is called @dfn{aborting}, and is done +by @kbd{C-]} (@code{abort-recursive-edit}). Similarly, you can throw +a string value to make @code{recursive-edit} signal an error, printing +this string as the message. If you throw a function, @code{recursive-edit} will call it without arguments before returning. +Throwing any other value, will make @code{recursive-edit} return +normally to the function that called it. The command @kbd{C-M-c} +(@code{exit-recursive-edit}) does this. Most applications should not use recursive editing, except as part of using the minibuffer. Usually it is more convenient for the user if you diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index f48f4f47e8b..523758c10f5 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -811,8 +811,7 @@ for you to be able to native-compile Lisp code. @vindex native-compile@r{, a Lisp feature} To determine whether the current Emacs process can produce and load -natively-compiled Lisp code, test whether the @code{native-compile} -feature is available (@pxref{Named Features}). Alternatively, call +natively-compiled Lisp code, call @code{native-comp-available-p} (@pxref{Native-Compilation Functions}). Unlike byte-compiled code, natively-compiled Lisp code is executed @@ -904,13 +903,20 @@ invokes the same Emacs executable as the process that called this function. @end defun -@defun batch-native-compile +@defun batch-native-compile &optional for-tarball This function runs native-compilation on files specified on the Emacs command line in batch mode. It must be used only in a batch execution of Emacs, as it kills Emacs upon completion of the compilation. If one or more of the files fail to compile, the Emacs process will attempt to compile all the other files, and will terminate with a -non-zero status code. +non-zero status code. The optional argument @var{for-tarball}, if +non-@code{nil}, tells the function to place the resulting @file{.eln} +files in the last directory mentioned in +@code{native-comp-eln-load-path} (@pxref{Library Search}); this is +meant to be used as part of building an Emacs source tarball for the +first time, when the natively-compiled files, which are absent from +the source tarball, should be generated in the build tree instead of +the user's cache directory. @end defun Native compilation can be run entirely asynchronously, in a subprocess diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 22b665bc931..06da1025186 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -555,6 +555,16 @@ Two symbols to avoid are @code{t}, which behaves like @code{_} Likewise, it makes no sense to bind keyword symbols (@pxref{Constant Variables}). +@item (cl-type @var{type}) +Matches if @var{expval} is of type @var{type}, which is a type +descriptor as accepted by @code{cl-typep} (@pxref{Type Predicates,,,cl,Common +Lisp Extensions}). Examples: + +@lisp +(cl-type integer) +(cl-type (integer 0 10)) +@end lisp + @item (pred @var{function}) Matches if the predicate @var{function} returns non-@code{nil} when called on @var{expval}. The test can be negated with the syntax @@ -1273,6 +1283,15 @@ bindings that can then be used inside @var{body}. The variable bindings are produced by destructuring binding of elements of @var{pattern} to the values of the corresponding elements of the evaluated @var{exp}. + +Here's a trivial example: + +@example +(pcase-let ((`(,major ,minor) + (split-string "image/png" "/"))) + minor) + @result{} "png" +@end example @end defmac @defmac pcase-let* bindings body@dots{} @@ -1302,6 +1321,10 @@ element of @var{list}. The bindings are performed as if by up being equivalent to @code{dolist} (@pxref{Iteration}). @end defmac +@defmac pcase-setq pattern value@dots{} +Assign values to variables in a @code{setq} form, destructuring each +@var{value} according to its respective @var{pattern}. +@end defmac @node Iteration @section Iteration diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index bc35982c172..b93b8bc015a 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -594,6 +594,9 @@ want to take the time to work out a more specific type to use. @item integer The value must be an integer. +@item natnum +The value must be a nonnegative integer. + @item number The value must be a number (floating point or integer). diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index e458d76d5d0..6548437817c 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -1043,9 +1043,9 @@ functions written in Lisp, it cannot profile Emacs primitives. @cindex benchmarking You can measure the time it takes to evaluate individual Emacs Lisp forms using the @file{benchmark} library. See the function -@code{benchmark-call} as well as the macros -@code{benchmark-run}, @code{benchmark-run-compiled} and -@code{benchmark-progn} in @file{benchmark.el}. You can also use the +@code{benchmark-call} as well as the macros @code{benchmark-run}, +@code{benchmark-run-compiled}, @code{benchmark-progn} and +@code{benchmark-call} in @file{benchmark.el}. You can also use the @code{benchmark} command for timing forms interactively. @c Not worth putting in the printed manual. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 13d0a1b458d..b6bd14f8874 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -152,6 +152,9 @@ truncation; a @samp{\} on the rightmost column indicates a line that wraps. (The display table can specify alternate characters to use for this; @pxref{Display Tables}). + Since wrapping and truncation of text contradict each other, Emacs +turns off line truncation when wrapping is requested, and vice versa. + @defopt truncate-lines If this buffer-local variable is non-@code{nil}, lines that extend beyond the right edge of the window are truncated; otherwise, they are @@ -558,6 +561,26 @@ You can rewrite the previous example with this macro as follows: @end example @end defmac +@defmac with-delayed-message (timeout message) body@dots{} +Sometimes it's unclear whether an operation will take a long time to +execute or not, or it can be inconvenient to implement a progress +reporter. This macro can be used in those situations. + +@lisp +(with-delayed-message (2 (format "Gathering data for %s" entry)) + (setq data (gather-data entry))) +@end lisp + +In this example, if the body takes more than two seconds to execute, +the message will be displayed. If it takes a shorter time than that, +the message won't be displayed. In either case, the body is evaluated +as normally, and the return value of the final element in the body is +the return value of the macro. + +The @var{message} element is evaluated before @var{body}, and is +always evaluated, whether the message is displayed or not. +@end defmac + @node Logging Messages @subsection Logging Messages in @file{*Messages*} @cindex logging echo-area messages @@ -646,9 +669,9 @@ If the value is zero, then command input is not echoed. @defvar message-truncate-lines Normally, displaying a long message resizes the echo area to display -the entire message. But if the variable @code{message-truncate-lines} -is non-@code{nil}, the echo area does not resize, and the message is -truncated to fit it. +the entire message, wrapping long line as needed. But if the variable +@code{message-truncate-lines} is non-@code{nil}, long lines of +echo-area message are instead truncated to fit the mini-window width. @end defvar The variable @code{max-mini-window-height}, which specifies the @@ -1331,6 +1354,11 @@ are not resized. By default, this mode uses @code{fit-window-to-buffer} (@pxref{Resizing Windows}) for resizing. You can specify a different function by customizing the options @code{temp-buffer-max-height} and @code{temp-buffer-max-width} below. + +The effect of this option can be overridden by providing a suitable +@code{window-height}, @code{window-width} or @code{window-size} action +alist entry for @code{display-buffer} (@pxref{Buffer Display Action +Alists}). @end defopt @defopt temp-buffer-max-height @@ -1917,7 +1945,8 @@ This function returns a list of the overlays that overlap the region contains one or more characters in the region; empty overlays (@pxref{Managing Overlays, empty overlay}) overlap if they are at @var{beg}, strictly between @var{beg} and @var{end}, or at @var{end} -when @var{end} denotes the position at the end of the buffer. +when @var{end} denotes the position at the end of the accessible part +of the buffer. @end defun @defun next-overlay-change pos @@ -1979,7 +2008,8 @@ The return value is an approximation: it only considers the values returned by @code{char-width} for the constituent characters, always takes a tab character as taking @code{tab-width} columns, ignores display properties and fonts, etc. For these reasons, we recommend -using @code{window-text-pixel-size}, described below, instead. +using @code{window-text-pixel-size} or @code{string-pixel-width}, +described below, instead. @end defun @defun truncate-string-to-width string width &optional start-column padding ellipsis ellipsis-text-property @@ -1993,11 +2023,11 @@ If a multi-column character in @var{string} exceeds the goal result can sometimes fall short of @var{width}, but cannot go beyond it. -The optional argument @var{start-column} specifies the starting column. -If this is non-@code{nil}, then the first @var{start-column} columns of -the string are omitted from the result. If one multi-column character in -@var{string} extends across the column @var{start-column}, that -character is omitted. +The optional argument @var{start-column} specifies the starting +column; it defaults to zero. If this is non-@code{nil}, then the +first @var{start-column} columns of the string are omitted from the +result. If one multi-column character in @var{string} extends across +the column @var{start-column}, that character is omitted. The optional argument @var{padding}, if non-@code{nil}, is a padding character added at the beginning and end of the result string, to @@ -2022,12 +2052,22 @@ means hide the excess parts of @var{string} with a @code{display} text property (@pxref{Display Property}) showing the ellipsis, instead of actually truncating the string. +@group @example (truncate-string-to-width "\tab\t" 12 4) @result{} "ab" (truncate-string-to-width "\tab\t" 12 4 ?\s) @result{} " ab " @end example +@end group + +This function uses @code{string-width} and @code{char-width} to find +the suitable truncation point when @var{string} is too wide, so it +suffers from the same basic issues as @code{string-width} does. In +particular, when character composition happens within @var{string}, +the display width of a string could be smaller than the sum of widths +of the constituent characters, and this function might return +inaccurate results. @end defun @defun truncate-string-ellipsis @@ -2046,7 +2086,7 @@ displayed in a given window. This function is used by (@pxref{Resizing Windows}) to make a window exactly as large as the text it contains. -@defun window-text-pixel-size &optional window from to x-limit y-limit mode-and-header-line +@defun window-text-pixel-size &optional window from to x-limit y-limit mode-lines This function returns the size of the text of @var{window}'s buffer in pixels. @var{window} must be a live window and defaults to the selected one. The return value is a cons of the maximum pixel-width @@ -2088,12 +2128,12 @@ calculating the pixel-height of a large buffer can take some time, it makes sense to specify this argument; in particular, if the caller does not know the size of the buffer. -The optional argument @var{mode-and-header-line} @code{nil} or omitted -means to not include the height of the mode- or header-line of -@var{window} in the return value. If it is either the symbol -@code{mode-line} or @code{header-line}, include only the height of that +The optional argument @var{mode-lines} @code{nil} or omitted means to +not include the height of the mode-, tab- or header-line of @var{window} +in the return value. If it is either the symbol @code{mode-line}, +@code{tab-line} or @code{header-line}, include only the height of that line, if present, in the return value. If it is @code{t}, include the -height of both, if present, in the return value. +height of all of these lines, if present, in the return value. @end defun @code{window-text-pixel-size} treats the text displayed in a window as a @@ -2161,12 +2201,42 @@ though when this function is run from an idle timer with a delay of zero seconds. @end defun +@defun string-pixel-width string +This is a convenience function that uses @code{window-text-pixel-size} +to compute the width of @var{string} (in pixels). +@end defun + @defun line-pixel-height This function returns the height in pixels of the line at point in the selected window. The value includes the line spacing of the line (@pxref{Line Height}). @end defun +@cindex grapheme cluster +@defun string-glyph-split string +When character compositions are in effect, sequence of characters can +be composed for display to form @dfn{grapheme clusters}, for example +to display accented characters, or ligatures, or Emoji, or when +complex text shaping requires that for some scripts. When that +happens, characters no longer map in a simple way to display columns, +and display layout decisions with such strings, such as truncating too +wide strings, can be a complex job. This function helps in performing +suvh jobs: it splits up its argument @var{string} into a list of +substrings, where each substring produces a single grapheme cluster +that should be displayed as a unit. Lisp programs can then use this +list to construct visually-valid substrings of @var{string} which will +look correctly on display, or compute the width of any substring of +@var{string} by adding the width of its constituents in the returned +list, etc. + +For instance, if you want to display a string without the first glyph, +you can say: + +@example +(apply #'insert (cdr (string-glyph-split string)))) +@end example +@end defun + When a buffer is displayed with line numbers (@pxref{Display Custom,,, emacs, The GNU Emacs Manual}), it is sometimes useful to know the width taken for displaying the line numbers. The following function @@ -2358,8 +2428,10 @@ value @code{unspecified}. This special value means that the face doesn't specify that attribute directly. An @code{unspecified} attribute tells Emacs to refer instead to a parent face (see the description @code{:inherit} attribute below); or, failing that, to an -underlying face (@pxref{Displaying Faces}). The @code{default} face -must specify all attributes. +underlying face (@pxref{Displaying Faces}). (However, +@code{unspecified} is not a valid value in @code{defface}.) + + The @code{default} face must specify all attributes. Some of these attributes are meaningful only on certain kinds of displays. If your display cannot handle a certain attribute, the @@ -2746,6 +2818,11 @@ terminal must match one of the @var{value}s specified for it in :group 'basic-faces) @end example +@kindex face-defface-spec @r{(face symbol property)} +@kindex saved-face @r{(face symbol property)} +@kindex customized-face @r{(face symbol property)} +@kindex theme-face @r{(face symbol property)} +@kindex face-documentation @r{(face symbol property)} Internally, Emacs stores each face's default spec in its @code{face-defface-spec} symbol property (@pxref{Symbol Properties}). The @code{saved-face} property stores any face spec saved by the user @@ -2802,9 +2879,12 @@ This function returns the value of the @var{attribute} attribute for If @var{frame} is omitted or @code{nil}, that means the selected frame (@pxref{Input Focus}). If @var{frame} is @code{t}, this function -returns the value of the specified attribute for newly-created frames -(this is normally @code{unspecified}, unless you have specified some -value using @code{set-face-attribute}; see below). +returns the value of the specified attribute for newly-created frames, +i.e.@: the value of the attribute before applying the face spec in the +face's @code{defface} definition (@pxref{Defining Faces}) or the spec +set by @code{face-spec-set}. This default value of @var{attribute} is +normally @code{unspecified}, unless you have specified some other +value using @code{set-face-attribute}; see below. If @var{inherit} is @code{nil}, only attributes directly defined by @var{face} are considered, so the return value may be @@ -2854,7 +2934,12 @@ elements of the result are name-value pairs of the form @w{@code{(@var{attr-name} . @var{attr-value})}}. Optional argument @var{frame} specifies the frame whose definition of @var{face} to return; if omitted or @code{nil}, the returned value describes the -default attributes of @var{face} for newly created frames. +default attributes of @var{face} for newly created frames, i.e.@: the +values these attributes have before applying the face spec in the +face's @code{defface} definition or the spec set by +@code{face-spec-set}. These default values of the attributes are +normally @code{unspecified}, unless you have specified some other +value using @code{set-face-attribute}; see below. @end defun @defun merge-face-attribute attribute value1 value2 @@ -2872,7 +2957,7 @@ for all frames. This function is mostly intended for internal usage. @defun set-face-attribute face frame &rest arguments This function sets one or more attributes of @var{face} for -@var{frame}. The attributes specifies in this way override the face +@var{frame}. The attributes specified in this way override the face spec(s) belonging to @var{face}. The extra arguments @var{arguments} specify the attributes to set, and @@ -2889,9 +2974,10 @@ sets the attribute @code{:weight} to @code{bold} and the attribute If @var{frame} is @code{t}, this function sets the default attributes -for newly created frames. If @var{frame} is @code{nil}, this function -sets the attributes for all existing frames, as well as for newly -created frames. +for newly created frames; they will effectively override the attribute +values specified by @code{defface}. If @var{frame} is @code{nil}, +this function sets the attributes for all existing frames, as well as +for newly created frames. @end defun The following commands and functions mostly provide compatibility @@ -5255,13 +5341,13 @@ to modify the set of known names for these dynamic libraries. Supported image formats (and the required support libraries) include PBM and XBM (which do not depend on support libraries and are always available), XPM (@code{libXpm}), GIF (@code{libgif} or -@code{libungif}), JPEG (@code{libjpeg}), TIFF -(@code{libtiff}), PNG (@code{libpng}), and SVG (@code{librsvg}). +@code{libungif}), JPEG (@code{libjpeg}), TIFF (@code{libtiff}), PNG +(@code{libpng}), SVG (@code{librsvg}), and WebP (@code{libwebp}). Each of these image formats is associated with an @dfn{image type symbol}. The symbols for the above formats are, respectively, -@code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, -@code{jpeg}, @code{tiff}, @code{png}, and @code{svg}. +@code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, @code{jpeg}, +@code{tiff}, @code{png}, @code{svg}, and @code{webp}. Furthermore, if you build Emacs with ImageMagick (@code{libMagickWand}) support, Emacs can display any image format @@ -5969,7 +6055,7 @@ To @var{svg} add an embedded (raster) image placed at @code{:base-uri} specifies a (possibly non-existing) file name of the svg image to be created, thus all the embedded files are searched relatively to the @code{:base-uri} filename's directory. If -@code{:base-uri} is ommited, then filename from where svg image is +@code{:base-uri} is omitted, then filename from where svg image is loaded is used. Using @code{:base-uri} improves the performance of embedding large images, comparing to @code{svg-embed}, because all the work is done directly by librsvg. @@ -6265,6 +6351,9 @@ Image type @code{png}. @item TIFF Image type @code{tiff}. Supports the @code{:index} property. @xref{Multi-Frame Images}. + +@item WebP +Image type @code{webp}. @end table @node Defining Images @@ -6416,7 +6505,7 @@ will compute a scaling factor based on the font pixel size. property yourself, but it is easier to use the functions in this section. -@defun insert-image image &optional string area slice +@defun insert-image image &optional string area slice inhibit-isearch This function inserts @var{image} in the current buffer at point. The value @var{image} should be an image descriptor; it could be a value returned by @code{create-image}, or the value of a symbol defined with @@ -6441,7 +6530,9 @@ image. Internally, this function inserts @var{string} in the buffer, and gives it a @code{display} property which specifies @var{image}. @xref{Display -Property}. +Property}. By default, doing interactive searches in the buffer will +consider @var{string} when searching. If @var{inhibit-isearch} is +non-@code{nil}, this is inhibited. @end defun @cindex slice, image @@ -6517,6 +6608,11 @@ cache, it can always be displayed, even if the value of @code{max-image-size} is subsequently changed (@pxref{Image Cache}). @end defvar +@defun image-at-point-p +This function returns @code{t} if point is on an image, and @code{nil} +otherwise. +@end defun + Images inserted with the insertion functions above also get a local keymap installed in the text properties (or overlays) that span the displayed image. This keymap defines the following commands: @@ -6688,7 +6784,10 @@ xwidget object, and then use that object as the display specifier in a @code{display} text or overlay property (@pxref{Display Property}). -@defun make-xwidget type title width height arguments &optional buffer + Embedded widgets can send events notifying Lisp code about changes +occurring within them. (@pxref{Xwidget Events}). + +@defun make-xwidget type title width height arguments &optional buffer related This creates and returns an xwidget object. If @var{buffer} is omitted or @code{nil}, it defaults to the current buffer. If @var{buffer} names a buffer that doesn't exist, it will be @@ -6701,7 +6800,10 @@ The WebKit component. @end table The @var{width} and @var{height} arguments specify the widget size in -pixels, and @var{title}, a string, specifies its title. +pixels, and @var{title}, a string, specifies its title. @var{related} +is used internally by the WebKit widget, and specifies another WebKit +widget that the newly created widget should share settings and +subprocesses with. @end defun @defun xwidgetp object @@ -6722,6 +6824,10 @@ property list given by @var{plist}. This function returns the buffer of @var{xwidget}. @end defun +@defun set-xwidget-buffer xwidget buffer +This function sets the buffer of @var{xwidget} to @var{buffer}. +@end defun + @defun get-buffer-xwidgets buffer This function returns a list of xwidget objects associated with the @var{buffer}, which can be specified as a buffer object or a name of @@ -6782,6 +6888,61 @@ This function returns the current setting of @var{xwidget}s query-on-exit flag, either @code{t} or @code{nil}. @end defun +@defun xwidget-perform-lispy-event xwidget event frame +Send an input event @var{event} to @var{xwidget}. The precise action +performed is platform-specific. @xref{Input Events}. + +You can optionally pass the frame on which the event was generated via +@var{frame}. On X11, modifier keys in key events will not be +considered if @var{frame} is @code{nil}, and the selected frame is not +an X-Windows frame. + +On GTK, only keyboard and function key events are supported. Mouse, +motion, and click events are dispatched to the xwidget without going +through Lisp code, and as such shouldn't require this function to be +called. +@end defun + +@defun xwidget-webkit-search query xwidget &optional case-insensitive backwards wrap-around +Start an incremental search on the WebKit widget @var{xwidget} with +the string @var{query} as the query. @var{case-insensitive} denotes +whether or not the search is case-insensitive, @var{backwards} +determines if the search is performed backwards towards the start of +the document, and @var{wrap-around} determines whether or not the +search terminates at the end of the document. + +If the function is called while a search query is already present, +then the query specified here will replace the existing query. + +To stop a search query, use @code{xwidget-webkit-finish-search}. +@end defun + +@defun xwidget-webkit-next-result xwidget +Display the next search result in @var{xwidget}. This function will +signal an error if a search query has not been already started in +@var{xwidget} through @code{xwidget-webkit-search}. + +If @code{wrap-around} was non-nil when @code{xwidget-webkit-search} +was called, then the search will restart from the beginning of the +document when its end is reached. +@end defun + +@defun xwidget-webkit-previous-result xwidget +Display the previous search result in @var{xwidget}. This function +signals an error if a search query has not been already started in +@var{xwidget} through @code{xwidget-webkit-search}. + +If @code{wrap-around} was non-nil when @code{xwidget-webkit-search} +was called, then the search will restart from the end of the +document when its beginning is reached. +@end defun + +@defun xwidget-webkit-finish-search xwidget +Finish a search operation started with @code{xwidget-webkit-search} in +@var{xwidget}. If there is no query currently ongoing, this function +signals an error. +@end defun + @node Buttons @section Buttons @cindex buttons in buffers @@ -6975,7 +7136,7 @@ This inserts a button with the label @var{label} at point, using text properties. @end defun -@defun button-buttonize string callback &optional data +@defun buttonize string callback &optional data Sometimes it's more convenient to make a string into a button without inserting it into a buffer immediately, for instance when creating data structures that may then, later, be inserted into a buffer. This @@ -7948,6 +8109,11 @@ Characters of Unicode General Category [Cf], such as U+200E @sc{left-to-right mark}, but excluding characters that have graphic images, such as U+00AD @sc{soft hyphen}. +@item variation-selectors +Unicode VS-1 through VS-16 (U+FE00 through U+FE0F), which are used to +select between different glyphs for the same codepoints (typically +emojis). + @item no-font Characters for which there is no suitable font, or which cannot be encoded by the terminal's coding system. diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index 323130f2378..7d67cc3af11 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -1216,9 +1216,7 @@ directs processing of arguments. @table @asis @item @code{t} All arguments are instrumented for evaluation. - -@item @code{0} -None of the arguments is instrumented. +This is short for @code{(body)}. @item a symbol The symbol must have an Edebug specification, which is used instead. @@ -1528,6 +1526,16 @@ example of the @code{let} specification. It may be easier to understand Edebug specifications by studying the examples provided here. +Consider a hypothetical macro @code{my-test-generator} that runs +tests on supplied lists of data. Although it is Edebug's default +behavior to not instrument arguments as code, as controlled by +@code{edebug-eval-macro-args} (@pxref{Instrumenting Macro Calls}), +it can be useful to explicitly document that the arguments are data: + +@example +(def-edebug-spec my-test-generator (&rest sexp)) +@end example + A @code{let} special form has a sequence of bindings and a body. Each of the bindings is either a symbol or a sublist with a symbol and optional expression. In the specification below, notice the @code{gate} diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 8b440c79774..1c0b0fa1b5a 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -161,7 +161,7 @@ Cover art by Etienne Suvasa. @ifset WWW_GNU_ORG @html -<p>The homepage for GNU Emacs is at +<p>The GNU Emacs website is at <a href="/software/emacs/">https://www.gnu.org/software/emacs/</a>.<br> For information on using Emacs, refer to the <a href="/software/emacs/manual/emacs.html">Emacs Manual</a>.<br> @@ -234,7 +234,7 @@ To view this manual in other formats, click Appendices -* Antinews:: Info for users downgrading to Emacs 26. +* Antinews:: Info for users downgrading to Emacs 27. * GNU Free Documentation License:: The license for this documentation. * GPL:: Conditions for copying and changing GNU Emacs. * Tips:: Advice and coding conventions for Emacs Lisp. @@ -365,6 +365,7 @@ Editing Types * Keymap Type:: What function a keystroke invokes. * Overlay Type:: How an overlay is represented. * Font Type:: Fonts for displaying text. +* Xwidget Type:: Embeddable widgets. Numbers @@ -788,6 +789,7 @@ Defining Commands * Interactive Codes:: The standard letter-codes for reading arguments in various ways. * Interactive Examples:: Examples of how to read interactive arguments. +* Command Modes:: Specifying that commands are for a specific mode. * Generic Commands:: Select among command alternatives. @@ -1047,6 +1049,7 @@ Windows * Basic Windows:: Basic information on using windows. * Windows and Frames:: Relating windows to the frame they appear on. +* Selecting Windows:: The selected window is the one that you edit in. * Window Sizes:: Accessing a window's size. * Resizing Windows:: Changing the sizes of windows. * Preserving Window Sizes:: Preserving the size of windows. @@ -1054,7 +1057,6 @@ Windows * Deleting Windows:: Deleting a window gives its space to other windows. * Recombining Windows:: Preserving the frame layout when splitting and deleting windows. -* Selecting Windows:: The selected window is the one that you edit in. * Cyclic Window Ordering:: Moving around the existing windows. * Buffers and Windows:: Each window displays the contents of a buffer. * Switching Buffers:: Higher-level functions for switching to a buffer. @@ -1122,6 +1124,7 @@ Frames * Dialog Boxes:: Displaying a box to ask yes or no. * Pointer Shape:: Specifying the shape of the mouse pointer. * Window System Selections::Transferring text to and from other X clients. +* Yanking Media:: Yanking things that aren't plain text. * Drag and Drop:: Internals of Drag-and-Drop implementation. * Color Names:: Getting the definitions of color names. * Text Terminal Colors:: Defining colors for text terminals. @@ -1315,6 +1318,7 @@ Regular Expressions * Rx Notation:: An alternative, structured regexp notation. @end ifnottex * Regexp Functions:: Functions for operating on regular expressions. +* Regexp Problems:: Some problems and how they may be avoided. Syntax of Regular Expressions diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index 7893895eee9..e1998842cf0 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -862,8 +862,13 @@ expressions that were read, evaluated, and printed from buffers (including the minibuffer) by the standard Emacs commands which do this. (Note that this does @emph{not} include evaluation in @file{*ielm*} buffers, nor evaluation using @kbd{C-j}, @kbd{C-x C-e}, -and similar evaluation commands in @code{lisp-interaction-mode}.) The -elements are ordered most recent first. +and similar evaluation commands in @code{lisp-interaction-mode}.) + +This variable is obsolete, and will be removed in a future version, +since it constantly enlarges the memory footprint of the Emacs +process. For that reason, we recommend against using it. + +The elements of @code{values} are ordered most recent first. @example @group @@ -880,8 +885,8 @@ values @end group @end example -This variable is useful for referring back to values of forms recently -evaluated. It is generally a bad idea to print the value of +This variable could be useful for referring back to values of forms +recently evaluated. It is generally a bad idea to print the value of @code{values} itself, since this may be very long. Instead, examine particular elements, like this: diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 266501d46d0..d93770a0d2f 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -563,7 +563,17 @@ In this case, @var{visit} must be @code{nil}. For example, @end example @noindent -inserts the first 500 characters of a file. +inserts the characters coded by the first 500 bytes of a file. + +If @var{beg} or @var{end} happens to be in the middle of a character's +multibyte sequence, Emacs's character code conversion will insert one +or more eight-bit characters (a.k.a.@: ``raw bytes'') +(@pxref{Character Sets}) into the buffer. If you want to read part of +a file this way, we recommend to bind @code{coding-system-for-read} to +a suitable value around the call to this function (@pxref{Specifying +Coding Systems}), and to write Lisp code which will check for raw +bytes at the boundaries, read the entire sequence of these bytes, and +convert them back to valid characters. If the argument @var{replace} is non-@code{nil}, it means to replace the contents of the buffer (actually, just the accessible portion) with the @@ -577,10 +587,11 @@ with @code{insert-file-contents}, as long as @var{replace} and @end defun @defun insert-file-contents-literally filename &optional visit beg end replace -This function works like @code{insert-file-contents} except that it -does not run @code{after-insert-file-functions}, and does not do -format decoding, character code conversion, automatic uncompression, -and so on. +This function works like @code{insert-file-contents} except that each +byte in the file is handled separately, being converted into an +eight-bit character if needed. It does not run +@code{after-insert-file-functions}, and does not do format decoding, +character code conversion, automatic uncompression, and so on. @end defun If you want to pass a file name to another process so that another @@ -936,6 +947,16 @@ file in @file{/foo/} will give an error: @end example @end defun +@defmac with-existing-directory body@dots{} +This macro ensures that @code{default-directory} is bound to an +existing directory before executing @var{body}. If +@code{default-directory} already exists, that's preferred, and +otherwise some other directory is used. This macro can be useful, for +instance, when calling an external command that requires that it's +running in a directory that exists. The chosen directory is not +guaranteed to be writable. +@end defmac + @defun access-file filename string If you can read @var{filename} this function returns @code{nil}; otherwise it signals an error @@ -1293,6 +1314,20 @@ on the 19th, @file{aug-20} was written on the 20th, and the file @end example @end defun +@defun file-has-changed-p filename tag +This function returns non-@code{nil} if the time stamp of +@var{filename} has changed since the last call. When called for the +first time for some @var{filename}, it records the last modification +time and size of the file, and returns non-@code{nil} when +@var{filename} exists. Thereafter, when called for the same +@var{filename}, it compares the current time stamp and size with the +recorded ones, and returns non-@code{nil} only if either the time +stamp or the size (or both) are different. This is useful when a Lisp +program wants to re-read a file whenever it changes. With an optional +argument @var{tag}, which must be a symbol, the size and modification +time comparisons are limited to calls with the same tag. +@end defun + @defun file-attributes filename &optional id-format @anchor{Definition of file-attributes} This function returns a list of attributes of file @var{filename}. If @@ -1864,7 +1899,7 @@ Interactively, @var{mode} is read from the minibuffer using @code{read-file-modes} (see below), which lets the user type in either an integer or a string representing the permissions symbolically. -@xref{File Attributes}, for the function @code{file-modes}, which +@xref{Testing Accessibility}, for the function @code{file-modes}, which returns the permissions of a file. @end deffn @@ -2062,6 +2097,9 @@ directory. Therefore, Emacs considers a file name as having two main parts: the @dfn{directory name} part, and the @dfn{nondirectory} part (or @dfn{file name within the directory}). Either part may be empty. Concatenating these two parts reproduces the original file name. +@footnote{Emacs follows the GNU convention to use the term @emph{file name} +instead of the term @emph{pathname}. We use the term @emph{path} only for +search paths, which are lists of directory names.} On most systems, the directory part is everything up to and including the last slash (backslash is also allowed in input on MS-DOS or @@ -2206,6 +2244,19 @@ and @code{file-name-nondirectory}. For example, @end example @end defun +@defun file-name-split filename +This function splits a file name into its components, and can be +thought of as the inverse of @code{string-join} with the appropriate +directory separator. For example, + +@example +(file-name-split "/tmp/foo.txt") + @result{} ("" "tmp" "foo.txt") +(string-join (file-name-split "/tmp/foo.txt") "/") + @result{} "/tmp/foo.txt" +@end example +@end defun + @node Relative File Names @subsection Absolute and Relative File Names @cindex absolute file name diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 25706befc8d..31ad82b7ada 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -105,6 +105,7 @@ window of another Emacs frame. @xref{Child Frames}. * Dialog Boxes:: Displaying a box to ask yes or no. * Pointer Shape:: Specifying the shape of the mouse pointer. * Window System Selections:: Transferring text to and from other X clients. +* Yanking Media:: Yanking things that aren't plain text. * Drag and Drop:: Internals of Drag-and-Drop implementation. * Color Names:: Getting the definitions of color names. * Text Terminal Colors:: Defining colors for text terminals. @@ -151,7 +152,7 @@ the window (a.k.a.@: the @dfn{dominating} monitor). This function itself does not make the new frame the selected frame. @xref{Input Focus}. The previously selected frame remains selected. -On graphical terminals, however, the windowing system may select the +On graphical terminals, however, the window system may select the new frame for its own reasons. @end deffn @@ -494,7 +495,8 @@ a graphical terminal: | | |_____________ Title Bar ______________| | | | (1)_____________ Menu Bar ______________| | ^ | | (2)_____________ Tool Bar ______________| | ^ - | | (3) _________ Internal Border ________ | | ^ + | | (3)_____________ Tab Bar _______________| | ^ + | | | _________ Internal Border ________ | | ^ | | | | ^ | | | | | | | | | | | | | Outer | | | Inner | | | Native @@ -640,6 +642,15 @@ GTK+, on the other hand, never wraps the tool bar but may automatically increase the outer width of a frame in order to accommodate an overlong tool bar. +@item Tab Bar +@cindex tab bar +The tab bar (@pxref{Tab Bars,,,emacs, The GNU Emacs Manual}) is always +drawn by Emacs itself. The tab bar appears above the tool bar in +Emacs built with an internal tool bar, and below the tool bar in +builds with an external tool bar. +Display of the tab bar can be suppressed by setting the +@code{tab-bar-lines} parameter (@pxref{Layout Parameters}) to zero. + @item Native Frame @cindex native frame @cindex native edges @@ -740,8 +751,8 @@ the internal border, one vertical scroll bar, and one left and one right fringe if they are specified for this frame, see @ref{Layout Parameters}. Its height can be obtained by removing from that of the native height the widths of the internal border and the heights of the -frame's internal menu and tool bars and one horizontal scroll bar if -specified for this frame. +frame's internal menu and tool bars, the tab bar and one horizontal +scroll bar if specified for this frame. @end table @cindex absolute position @@ -1208,10 +1219,10 @@ width of one scroll bar provided this option is @code{nil} and keep it unchanged if this option is @code{t} or a list containing @code{vertical-scroll-bars}. -The default value is @code{'(tab-bar-lines tool-bar-lines)} for Lucid, +The default value is @code{(tab-bar-lines tool-bar-lines)} for Lucid, Motif and MS-Windows (which means that adding/removing a tool or tab bar there does not change the outer frame height), -@code{'(tab-bar-lines)} on all other window systems including GTK+ +@code{(tab-bar-lines)} on all other window systems including GTK+ (which means that changing any of the parameters listed above with the exception of @code{tab-bar-lines} may change the size of the outer frame), and @code{t} otherwise (which means the outer frame size never @@ -1875,6 +1886,13 @@ The position of the tool bar when Emacs was built with GTK+. Its value can be one of @code{top}, @code{bottom} @code{left}, @code{right}. The default is @code{top}. +@vindex tab-bar-lines@r{, a frame parameter} +@item tab-bar-lines +The number of lines to use for the tab bar (@pxref{Tab Bars,,,emacs, The +GNU Emacs Manual}). The default is one if Tab Bar mode is enabled and +zero otherwise. This value may change whenever the tab bar wraps +(@pxref{Frame Layout}). + @vindex line-spacing@r{, a frame parameter} @item line-spacing Additional space to leave below each text line, in pixels (a positive @@ -2692,18 +2710,19 @@ frame and defaults to the selected frame. It never returns a frame whose @code{no-other-frame} parameter (@pxref{Frame Interaction Parameters}) is non-@code{nil}. -The second argument, @var{minibuf}, says which frames to consider: +The second argument, @var{minibuf}, says which frames to consider when +deciding what the next frame should be: @table @asis @item @code{nil} -Exclude minibuffer-only frames. +Consider all frames except minibuffer-only frames. @item @code{visible} -Consider all visible frames. +Consider only visible frames. @item 0 -Consider all visible or iconified frames. +Consider only visible or iconified frames. @item a window Consider only the frames using that particular window as their -minibuffer. +minibuffer window. @item anything else Consider all frames. @end table @@ -2757,7 +2776,8 @@ Terminals}. @cindex selected frame At any time, one frame in Emacs is the @dfn{selected frame}. The -selected window always resides on the selected frame. +selected window (@pxref{Selecting Windows}) always resides on the +selected frame. When Emacs displays its frames on several terminals (@pxref{Multiple Terminals}), each terminal has its own selected frame. But only one @@ -2991,12 +3011,11 @@ Auto-selection}). Note that this option does not distinguish ``sloppy'' focus (where the frame that previously had focus retains focus as long as the mouse -pointer does not move into another window manager window) from -``strict'' focus (where a frame immediately loses focus when it's left -by the mouse pointer). Neither does it recognize whether your window -manager supports delayed focusing or auto-raising where you can -explicitly specify the time until a new frame gets focus or is -auto-raised. +pointer does not move into another window-system window) from ``strict'' +focus (where a frame immediately loses focus when it's left by the mouse +pointer). Neither does it recognize whether your window manager +supports delayed focusing or auto-raising where you can explicitly +specify the time until a new frame gets focus or is auto-raised. You can supply a ``focus follows mouse'' policy for individual Emacs windows by customizing the variable @code{mouse-autoselect-window} @@ -3905,6 +3924,47 @@ For backward compatibility, there are obsolete aliases names of @code{gui-get-selection} and @code{gui-set-selection} before Emacs 25.1. +@node Yanking Media +@section Yanking Media + + If you choose, for instance, ``Copy Image'' in a web browser, that +image is put onto the clipboard, and Emacs can access it via +@code{gui-get-selection}. But in general, inserting image data into +an arbitrary buffer isn't very useful---you can't really do much with +it by default. + + So Emacs has a system to let modes register handlers for these +``complicated'' selections. + +@defun yank-media-handler types handler +@var{types} can be a @acronym{MIME} media type symbol, a regexp to +match these, or a list of these symbols and regexps. For instance: + +@example +(yank-media-handler 'text/html #'my-html-handler) +(yank-media-handler "image/.*" #'my-image-handler) +@end example + +A mode can register as many handlers as required. + + The @var{handler} function is called with two parameters: The +@acronym{MIME} media type symbol and the data (as a string). The +handler should then insert the object into the buffer, or save it, or +do whatever is appropriate for the mode. +@end defun + + The @code{yank-media} command will consult the registered handlers in +the current buffer, compare that with the available media types on the +clipboard, and then pass on the matching selection to the handler (if +any). If there's more than one matching selection, the user is +queried first. + + The @code{yank-media-types} command can be used to explore the +clipboard/primary selection. It lists all the media types that are +currently available, and can be handy when creating handlers---to see +what data is actually available. Some applications put a surprising +amount of different data types on the clipboard. + @node Drag and Drop @section Drag and Drop @cindex drag and drop diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 77d1465c876..9c1fde06b54 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -378,7 +378,7 @@ keyword @code{&rest} before one final argument. @group (@var{required-vars}@dots{} @r{[}&optional @r{[}@var{optional-vars}@dots{}@r{]}@r{]} - @r{[}&rest @r{[}@var{rest-var}@r{]}@r{]}) + @r{[}&rest @var{rest-var}@r{]}) @end group @end example @@ -826,12 +826,20 @@ This function returns a new function which, when called, will call @var{func} with the list of arguments composed from @var{args} and additional arguments specified at the time of the call. If @var{func} accepts @var{n} arguments, then a call to @code{apply-partially} with -@w{@code{@var{m} < @var{n}}} arguments will produce a new function of -@w{@code{@var{n} - @var{m}}} arguments. +@w{@code{@var{m} <= @var{n}}} arguments will produce a new function of +@w{@code{@var{n} - @var{m}}} arguments@footnote{ +If the number of arguments that @var{func} can accept is unlimited, +then the new function will also accept an unlimited number of +arguments, so in that case @code{apply-partially} doesn't reduce the +number of arguments that the new function could accept. +}. Here's how we could define the built-in function @code{1+}, if it didn't exist, using @code{apply-partially} and @code{+}, another -built-in function: +built-in function@footnote{ +Note that unlike the built-in function, this version accepts any +number of arguments. +}: @example @group @@ -902,11 +910,11 @@ length of @var{sequence}. For example: @example @group -(mapcar 'car '((a b) (c d) (e f))) +(mapcar #'car '((a b) (c d) (e f))) @result{} (a c e) -(mapcar '1+ [1 2 3]) +(mapcar #'1+ [1 2 3]) @result{} (2 3 4) -(mapcar 'string "abc") +(mapcar #'string "abc") @result{} ("a" "b" "c") @end group @@ -922,14 +930,14 @@ Return the list of results." ;; @r{If no list is exhausted,} (if (not (memq nil args)) ;; @r{apply function to @sc{car}s.} - (cons (apply function (mapcar 'car args)) - (apply 'mapcar* function + (cons (apply function (mapcar #'car args)) + (apply #'mapcar* function ;; @r{Recurse for rest of elements.} - (mapcar 'cdr args))))) + (mapcar #'cdr args))))) @end group @group -(mapcar* 'cons '(a b c) '(1 2 3 4)) +(mapcar* #'cons '(a b c) '(1 2 3 4)) @result{} ((a . 1) (b . 2) (c . 3)) @end group @end example @@ -946,10 +954,10 @@ the results (which must be lists), by altering the results (using @example @group ;; @r{Contrast this:} -(mapcar 'list '(a b c d)) +(mapcar #'list '(a b c d)) @result{} ((a) (b) (c) (d)) ;; @r{with this:} -(mapcan 'list '(a b c d)) +(mapcan #'list '(a b c d)) @result{} (a b c d) @end group @end example @@ -961,14 +969,14 @@ side-effects only---the values it returns are ignored, not collected into a list. @code{mapc} always returns @var{sequence}. @end defun -@defun mapconcat function sequence separator +@defun mapconcat function sequence &optional separator @code{mapconcat} applies @var{function} to each element of @var{sequence}; the results, which must be sequences of characters (strings, vectors, or lists), are concatenated into a single string return value. Between each pair of result sequences, @code{mapconcat} inserts the characters from @var{separator}, which also must be a -string, or a vector or list of characters. @xref{Sequences Arrays -Vectors}. +string, or a vector or list of characters; a @code{nil} value is +treated as the empty string. @xref{Sequences Arrays Vectors}. The argument @var{function} must be a function that can take one argument and returns a sequence of characters: a string, a vector, or @@ -978,7 +986,7 @@ string. @example @group -(mapconcat 'symbol-name +(mapconcat #'symbol-name '(The cat in the hat) " ") @result{} "The cat in the hat" @@ -986,8 +994,7 @@ string. @group (mapconcat (lambda (x) (format "%c" (1+ x))) - "HAL-8000" - "") + "HAL-8000") @result{} "IBM.9111" @end group @end example @@ -1443,7 +1450,7 @@ is not a function, e.g., a keyboard macro (@pxref{Keyboard Macros}): @result{} "\^u2\^k" @end example -It you wish to use @code{fset} to make an alternate name for a +If you wish to use @code{fset} to make an alternate name for a function, consider using @code{defalias} instead. @xref{Definition of defalias}. @end defun diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi index 394928454b0..e9d1e270d8e 100644 --- a/doc/lispref/hooks.texi +++ b/doc/lispref/hooks.texi @@ -18,11 +18,13 @@ arguments and their values are completely ignored. The recommended way to put a new function on such a hook is to call @code{add-hook}. @xref{Hooks}, for more information about using hooks. -The variables whose names end in @samp{-functions} are usually @dfn{abnormal -hooks} (some old code may also use the deprecated @samp{-hooks} suffix); their -values are lists of functions, but these functions are called in a special way -(they are passed arguments, or their return values are used). The variables -whose names end in @samp{-function} have single functions as their values. +The variables whose names end in @samp{-functions} are usually +@dfn{abnormal hooks} (some old code may also use the deprecated +@samp{-hooks} suffix). Their values are lists of functions, but these +functions are called in a special way: they are either passed +arguments, or their return values are used in some way. The variables +whose names end in @samp{-function} have single functions as their +values. This is not an exhaustive list, it only covers the more general hooks. For example, every major mode defines a hook named @@ -262,7 +264,6 @@ after-set-visited-file-name-hook auto-coding-functions choose-completion-string-functions completing-read-function -completion-annotate-function completion-at-point-functions completion-list-insert-choice-function deactivate-current-input-method-function diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 0e250d0f59b..7718712b9b8 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -218,6 +218,14 @@ the Emacs executable that dumped them. If you want to use this function in an Emacs that was already dumped, you must run Emacs with the @samp{-batch} option. + +@vindex after-pdump-load-hook +If you're including @samp{.el} files in the dumped Emacs and that +@samp{.el} file has code that is normally run at load time, that code +won't be run when Emacs starts after dumping. To help work around +that problem, you can put functions on the +@code{after-pdump-load-hook} hook. This hook is run when starting +Emacs. @end defun @defun dump-emacs to-file from-file @@ -337,18 +345,22 @@ by the vector allocation code while iterating over the vector blocks. It is quite common to use some storage for a while, then release it by (for example) killing a buffer or deleting the last pointer to an object. Emacs provides a @dfn{garbage collector} to reclaim this -abandoned storage. The garbage collector operates by finding and -marking all Lisp objects that are still accessible to Lisp programs. -To begin with, it assumes all the symbols, their values and associated -function definitions, and any data presently on the stack, are -accessible. Any objects that can be reached indirectly through other -accessible objects are also accessible. +abandoned storage. The garbage collector operates, in essence, by +finding and marking all Lisp objects that are still accessible to Lisp +programs. To begin with, it assumes all the symbols, their values and +associated function definitions, and any data presently on the stack, +are accessible. Any objects that can be reached indirectly through +other accessible objects are also accessible, but this calculation is +done ``conservatively'', so it may slightly overestimate how many +objects that are accessible. When marking is finished, all objects still unmarked are garbage. No matter what the Lisp program or the user does, it is impossible to refer to them, since there is no longer a way to reach them. Their space might as well be reused, since no one will miss them. The second -(sweep) phase of the garbage collector arranges to reuse them. +(sweep) phase of the garbage collector arranges to reuse them. (But +since the marking was done ``conservatively'', not all unused objects +are guaranteed to be garbage-collected by any one sweep.) @c ??? Maybe add something describing weak hash tables here? diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 4097c86f074..899499ed46e 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -94,8 +94,25 @@ Manual}. (kbd "<f1> SPC") @result{} [f1 32] (kbd "C-M-<down>") @result{} [C-M-down] @end example + +@findex kbd-valid-p +The @code{kbd} function is very permissive, and will try to return +something sensible even if the syntax used isn't completely +conforming. To check whether the syntax is actually valid, use the +@code{kbd-valid-p} function. + +@code{define-key} also supports using the shorthand syntax +@samp{["..."]} syntax to define a key. The string has to be a +strictly valid @code{kbd} sequence, and if it's not valid, an error +will be signalled. For instance, to bind @key{C-c f}, you can say: + +@lisp +(define-key global-map ["C-c f"] #'find-file-literally) +@end lisp + @end defun + @node Keymap Basics @section Keymap Basics @cindex key binding @@ -1278,24 +1295,46 @@ Binding Conventions}). @cindex meta character key constants @cindex control character key constants - In writing the key sequence to rebind, it is good to use the special -escape sequences for control and meta characters (@pxref{String Type}). -The syntax @samp{\C-} means that the following character is a control -character and @samp{\M-} means that the following character is a meta -character. Thus, the string @code{"\M-x"} is read as containing a -single @kbd{M-x}, @code{"\C-f"} is read as containing a single -@kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both read as -containing a single @kbd{C-M-x}. You can also use this escape syntax in -vectors, as well as others that aren't allowed in strings; one example -is @samp{[?\C-\H-x home]}. @xref{Character Type}. - - The key definition and lookup functions accept an alternate syntax for -event types in a key sequence that is a vector: you can use a list -containing modifier names plus one base event (a character or function -key name). For example, @code{(control ?a)} is equivalent to -@code{?\C-a} and @code{(hyper control left)} is equivalent to -@code{C-H-left}. One advantage of such lists is that the precise -numeric codes for the modifier bits don't appear in compiled files. + @code{define-key} (and other functions that are used to rebind keys) +understand a number of different syntaxes for the keys. + +@table @asis +@item A vector containing a single string. +This is the preferred way to represent a key sequence. Here's a +couple of examples: + +@example +["C-c M-f"] +["S-<home>"] +@end example + +The syntax is the same as the one used by Emacs when displaying key +bindings, for instance in @samp{*Help*} buffers and help texts. + +If the syntax isn't valid, an error will be raised when running +@code{define-key}, or when byte-compiling code that has these calls. + +@item A vector containing lists of keys. +You can use a list containing modifier names plus one base event (a +character or function key name). For example, @code{[(control ?a) +(meta b)]} is equivalent to @kbd{C-a M-b} and @code{[(hyper control +left)]} is equivalent to @kbd{C-H-left}. + +@item A string with control and meta characters. +Internally, key sequences are often represented as strings using the +special escape sequences for control and meta characters +(@pxref{String Type}), but this representation can also be used by +users when rebinding keys. A string like @code{"\M-x"} is read as +containing a single @kbd{M-x}, @code{"\C-f"} is read as containing a +single @kbd{C-f}, and @code{"\M-\C-x"} and @code{"\C-\M-x"} are both +read as containing a single @kbd{C-M-x}. + +@item a vector of characters. +This is the other internal representation of key sequences, and +supports a fuller range of modifiers than the string representation. +One example is @samp{[?\C-\H-x home]}, which represents the @kbd{C-H-x +home} key sequence. @xref{Character Type}. +@end table The functions below signal an error if @var{keymap} is not a keymap, or if @var{key} is not a string or vector representing a key sequence. @@ -1337,7 +1376,7 @@ bindings in it: @result{} (keymap) @end group @group -(define-key map "\C-f" 'forward-char) +(define-key map ["C-f"] 'forward-char) @result{} forward-char @end group @group @@ -1347,7 +1386,7 @@ map @group ;; @r{Build sparse submap for @kbd{C-x} and bind @kbd{f} in that.} -(define-key map (kbd "C-x f") 'forward-word) +(define-key map ["C-x f"] 'forward-word) @result{} forward-word @end group @group @@ -1360,14 +1399,14 @@ map @group ;; @r{Bind @kbd{C-p} to the @code{ctl-x-map}.} -(define-key map (kbd "C-p") ctl-x-map) +(define-key map ["C-p"] ctl-x-map) ;; @code{ctl-x-map} @result{} [nil @dots{} find-file @dots{} backward-kill-sentence] @end group @group ;; @r{Bind @kbd{C-f} to @code{foo} in the @code{ctl-x-map}.} -(define-key map (kbd "C-p C-f") 'foo) +(define-key map ["C-p C-f"] 'foo) @result{} 'foo @end group @group @@ -1386,6 +1425,99 @@ changing an entry in @code{ctl-x-map}, and this has the effect of changing the bindings of both @kbd{C-p C-f} and @kbd{C-x C-f} in the default global map. +@defun define-keymap &key options... &rest pairs... +@code{define-key} is the general work horse for defining a key in a +keymap. When writing modes, however, you frequently have to bind a +large number of keys at once, and using @code{define-key} on them all +can be tedious and error-prone. Instead you can use +@code{define-keymap}, which creates a keymaps and binds a number of +keys. Here's a very basic example: + +@lisp +(define-keymap + "n" #'forward-line + "f" #'previous-line + ["C-c C-c"] #'quit-window) +@end lisp + +This function creates a new sparse keymap, defines the two keystrokes +in @var{pairs}, and returns the new keymap. + +@var{pairs} is a list of alternating key bindings and key definitions, +as accepted by @code{define-key}. In addition the key can be the +special symbol @code{:menu}, in which case the definition should be a +menu definition as accepted by @code{easy-menu-define} (@pxref{Easy +Menu}). Here's a brief example: + +@lisp +(define-keymap :full t + "g" #'eww-reload + :menu '("Eww" + ["Exit" quit-window t] + ["Reload" eww-reload t])) +@end lisp + +A number of keywords can be used before the key/definition pairs to +changes features of the new keymap. If the keyword is missing, the +default value for the feature is @code{nil}. Here's a list of the +available keywords: + +@table @code +@item :full +If non-@code{nil}, create a chartable keymap (as from +@code{make-keymap}) instead of a sparse keymap (as from +@code{make-sparse-keymap} (@pxref{Creating Keymaps}). A sparse keymap +is the default. + +@item :parent +If non-@code{nil}, this should be a keymap to use as the parent +(@pxref{Inheritance and Keymaps}). + +@item :keymap +If non-@code{nil}, this should be a keymap. Instead of creating a new +keymap, this keymap is modified instead. + +@item :suppress +If non-@code{nil}, the keymap will be suppressed with +@code{suppress-keymap} (@pxref{Changing Key Bindings}). If +@code{nodigits}, treat digits like other chars. + +@item :name +If non-@code{nil}, this should be a string to use as the menu for the +keymap if you use it as a menu with @code{x-popup-menu} (@pxref{Pop-Up +Menus}). + +@item :prefix +If non-@code{nil}, this should be a symbol to be used as a prefix +command (@pxref{Prefix Keys}). If this is the case, this symbol is +returned by @code{define-keymap} instead of the map itself. +@end table + +@end defun + +@defmac defvar-keymap name &key options... &rest pairs... +By far, the most common thing to do with a keymap is to bind it to a +variable. This is what virtually all modes do---a mode called +@code{foo} almost always has a variable called @code{foo-mode-map}. + +This macro defines @var{name} as a variable, and passes @var{options} +and @var{pars} to @code{define-keymap}, and uses the result as the +default value for the variable. + +@var{options} is like the keywords in @code{define-keymap}, but adds a +@code{:doc} keyword that says what the doc string for the @var{name} +variable should be. + +Here's an example: + +@lisp +(defvar-keymap eww-textarea-map + :parent text-mode-map + "\r" #'forward-line + [?\t] #'shr-next-link) +@end lisp +@end defmac + The function @code{substitute-key-definition} scans a keymap for keys that have a certain binding and rebinds them with a different binding. Another feature which is cleaner and can often produce the @@ -2227,6 +2359,12 @@ This property specifies that @var{string} is the string to display as the keyboard equivalent for this menu item. You can use the @samp{\\[...]} documentation construct in @var{string}. +This property can also be a function (which will be called with no +arguments). This function should return a string. This function will +be called every time the menu is computed, so using a function that +takes a lot of time to compute is not a good idea, and it should +expect to be called from any context. + @item :filter @var{filter-fn} This property provides a way to compute the menu item dynamically. The property value @var{filter-fn} should be a function of one argument; diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index ac99835f7b3..f98ae76da9a 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -679,6 +679,20 @@ list are in the same order as in @var{tree}. @result{}(1 2 3 4 5 6 7) @end example +@defun ensure-list object +This function returns @var{object} as a list. If @var{object} is +already a list, the function returns it; otherwise, the function +returns a one-element list containing @var{object}. + +This is usually useful if you have a variable that may or may not be a +list, and you can then say, for instance: + +@lisp +(dolist (elem (ensure-list foo)) + (princ elem)) +@end lisp +@end defun + @defun number-sequence from &optional to separation This function returns a list of numbers starting with @var{from} and incrementing by @var{separation}, and ending at or just before @@ -1213,13 +1227,13 @@ this is not guaranteed to happen): @cindex lists as sets @cindex sets - A list can represent an unordered mathematical set---simply consider a -value an element of a set if it appears in the list, and ignore the -order of the list. To form the union of two sets, use @code{append} (as -long as you don't mind having duplicate elements). You can remove -@code{equal} duplicates using @code{delete-dups}. Other useful -functions for sets include @code{memq} and @code{delq}, and their -@code{equal} versions, @code{member} and @code{delete}. + A list can represent an unordered mathematical set---simply consider +a value an element of a set if it appears in the list, and ignore the +order of the list. To form the union of two sets, use @code{append} +(as long as you don't mind having duplicate elements). You can remove +@code{equal} duplicates using @code{delete-dups} or @code{seq-uniq}. +Other useful functions for sets include @code{memq} and @code{delq}, +and their @code{equal} versions, @code{member} and @code{delete}. @cindex CL note---lack @code{union}, @code{intersection} @quotation @@ -1475,7 +1489,8 @@ comparison. This function destructively removes all @code{equal} duplicates from @var{list}, stores the result in @var{list} and returns it. Of several @code{equal} occurrences of an element in @var{list}, -@code{delete-dups} keeps the first one. +@code{delete-dups} keeps the first one. See @code{seq-uniq} for +non-destructive operation (@pxref{Sequence Functions}). @end defun See also the function @code{add-to-list}, in @ref{List Variables}, @@ -1557,10 +1572,12 @@ of property lists and association lists. @defun assoc key alist &optional testfn This function returns the first association for @var{key} in @var{alist}, comparing @var{key} against the alist elements using -@var{testfn} if it is non-@code{nil} and @code{equal} otherwise -(@pxref{Equality Predicates}). It returns @code{nil} if no -association in @var{alist} has a @sc{car} equal to @var{key}. For -example: +@var{testfn} if it is a function, and @code{equal} otherwise +(@pxref{Equality Predicates}). If @var{testfn} is a function, it is +called with two arguments: the @sc{car} of an element from @var{alist} +and @var{key}. The function returns @code{nil} if no +association in @var{alist} has a @sc{car} equal to @var{key}, as +tested by @var{testfn}. For example: @smallexample (setq trees '((pine . cones) (oak . acorns) (maple . seeds))) diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 196dd990767..281e987e7f1 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -469,6 +469,18 @@ If @var{default} is a non-@code{nil} list, the first element of the list is used in the prompt. @end defun +@defvar read-minibuffer-restore-windows +If this option is non-@code{nil} (the default), getting input from the +minibuffer will restore, on exit, the window configurations of the frame +where the minibuffer was entered from and, if it is different, the frame +that owns the minibuffer window. This means that if, for example, a +user splits a window while getting input from the minibuffer on the same +frame, that split will be undone when exiting the minibuffer. + +If this option is @code{nil}, no such restorations are done. Hence, the +window split mentioned above will persist after exiting the minibuffer. +@end defvar + @node Object from Minibuffer @section Reading Lisp Objects with the Minibuffer @cindex minibuffer input, reading lisp objects @@ -2197,7 +2209,7 @@ Here is an example: @smallexample @group -(yes-or-no-p "Do you really want to remove everything? ") +(yes-or-no-p "Do you really want to remove everything?") ;; @r{After evaluation of the preceding expression,} ;; @r{the following prompt appears,} diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index b0dc0ff9166..bc5c08c687c 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -59,12 +59,13 @@ runs just before Emacs suspends itself (@pxref{Suspending Emacs}). @cindex abnormal hook If the hook variable's name does not end with @samp{-hook}, that -indicates it is probably an @dfn{abnormal hook}. That means the hook -functions are called with arguments, or their return values are used -in some way. The hook's documentation says how the functions are -called. Any functions added to an abnormal hook must follow the -hook's calling convention. By convention, abnormal hook names end in -@samp{-functions}. +indicates it is probably an @dfn{abnormal hook}. These differ from +normal hooks in two ways: they can be called with one or more +arguments, and their return values can be used in some way. The +hook's documentation says how the functions are called and how their +return values are used. Any functions added to an abnormal hook must +follow the hook's calling convention. By convention, abnormal hook +names end in @samp{-functions}. @cindex single-function hook If the name of the variable ends in @samp{-predicate} or @@ -268,6 +269,18 @@ normal-mode}), but tries to force it not to choose any modes in @var{avoided-modes}, if that argument is non-@code{nil}. @end defun +@defun clean-mode +Changing the major mode clears out most local variables, but it +doesn't remove all artefacts in the buffer (like text properties and +overlays). It's rare to change a buffer from one major mode to +another (except from @code{fundamental-mode} to everything else), so +this is usually not a concern. It can sometimes be convenient (mostly +when debugging a problem in a buffer) to do a ``full reset'' of the +buffer, and that's what the @code{clean-mode} major mode offers. It +will kill all local variables (even the permanently local ones), and +also removes all overlays and text properties. +@end defun + The easiest way to write a major mode is to use the macro @code{define-derived-mode}, which sets up the new mode as a variant of an existing major mode. @xref{Derived Modes}. We recommend using @@ -471,6 +484,22 @@ Each face that the mode defines should, if possible, inherit from an existing Emacs face. @xref{Basic Faces}, and @ref{Faces for Font Lock}. @item +Consider adding a mode-specific menu to the menu bar. This should +preferably include the most important menu-specific settings and +commands that will allow users discovering the main features quickly +and efficiently. + +@item +@cindex context menus, for a major mode +@vindex context-menu-functions +Consider adding mode-specific context menus for the mode, to be used +if and when users activate the @code{context-menu-mode} (@pxref{Menu +Mouse Clicks,,, emacs, The Emacs Manual}). To this end, define a +mode-specific function which builds one or more menus depending on the +location of the @kbd{mouse-3} click in the buffer, and then add that +function to the buffer-local value of @code{context-menu-functions}. + +@item The mode should specify how Imenu should find the definitions or sections of a buffer, by setting up a buffer-local value for the variable @code{imenu-generic-expression}, for the two variables @@ -1121,10 +1150,11 @@ re-sorting entries. Comparison is done with @code{equal}. @item @var{contents} is a vector with the same number of elements as @code{tabulated-list-format}. Each vector element is either a string, -which is inserted into the buffer as-is, or a list @code{(@var{label} -. @var{properties})}, which means to insert a text button by calling -@code{insert-text-button} with @var{label} and @var{properties} as -arguments (@pxref{Making Buttons}). +which is inserted into the buffer as-is; an image descriptor, which is +used to insert an image (@pxref{Image Descriptors}); or a list +@w{@code{(@var{label} . @var{properties})}}, which means to insert a +text button by calling @code{insert-text-button} with @var{label} and +@var{properties} as arguments (@pxref{Making Buttons}). There should be no newlines in any of these strings. @end itemize @@ -1728,7 +1758,8 @@ anything that can be used with the @code{setf} function (@pxref{Generalized Variables}). @var{place} can also be a cons @code{(@var{get} . @var{set})}, where @var{get} is an expression that returns the current state, -and @var{set} is a function of one argument (a state) that sets it. +and @var{set} is a function of one argument (a state) which should be +assigned to @var{place}. @item :after-hook @var{after-hook} This defines a single Lisp form which is evaluated after the mode hooks @@ -2251,16 +2282,15 @@ number. The format used to display column numbers when @code{column-number-mode} (@pxref{Optional Mode Line,,, emacs, The GNU Emacs Manual}) is switched on. @samp{%c} in the format will be -replaced with the column number, and this is zero-based if -@code{column-number-indicator-zero-based} is non-@code{nil}, and -one-based if @code{column-number-indicator-zero-based} is @code{nil}. +replaced with a zero-based column number, and @samp{%C} will be +replaced with a one-based column number. @end defvar @defvar mode-line-position-column-line-format The format used to display column numbers when both @code{line-number-mode} and @code{column-number-mode} are switched on. -See the previous two variables for the meaning of the @samp{%l} and -@samp{%c} format specs. +See the previous two variables for the meaning of the @samp{%l}, +@samp{%c} and @samp{%C} format specs. @end defvar @defvar minor-mode-alist @@ -3299,6 +3329,11 @@ This function tells Font Lock mode to run the Lisp function current buffer. It calls @var{function} before calling the default fontification functions, and gives it two arguments, @var{start} and @var{end}, which specify the region to be fontified or refontified. +If @var{function} performs fontifications, it can return a list of the +form @w{@code{(jit-lock-bounds @var{beg} . @var{end})}}, to indicate +the bounds of the region it actually fontified; JIT font-lock will use +this information to optimize subsequent redisplay cycles and regions +of buffer text it will pass to future calls to @var{function}. The optional argument @var{contextual}, if non-@code{nil}, forces Font Lock mode to always refontify a syntactically relevant part of the @@ -3445,9 +3480,17 @@ for string constants. @item font-lock-doc-face @vindex font-lock-doc-face -for documentation strings in the code. This inherits, by default, from +for documentation embedded in program code inside specially-formed +comments or strings. This face inherits, by default, from @code{font-lock-string-face}. +@item font-lock-doc-markup-face +@vindex font-lock-doc-markup-face +for mark-up elements in text using @code{font-lock-doc-face}. +It is typically used for the mark-up constructs in documentation embedded +in program code, following conventions such as Haddock, Javadoc or Doxygen. +This face inherits, by default, from @code{font-lock-constant-face}. + @item font-lock-negation-char-face @vindex font-lock-negation-char-face for easily-overlooked negation characters. diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index c22930d624e..6980920a7b9 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -459,7 +459,7 @@ of character properties. In particular, Emacs supports the @uref{https://www.unicode.org/reports/tr23/, Unicode Character Property Model}, and the Emacs character property database is derived from the Unicode Character Database (@acronym{UCD}). See the -@uref{https://www.unicode.org/versions/Unicode12.1.0/ch04.pdf, Character +@uref{https://www.unicode.org/versions/Unicode14.0.0/ch04.pdf, Character Properties chapter of the Unicode Standard}, for a detailed description of Unicode character properties and their meaning. This section assumes you are already familiar with that chapter of the @@ -1988,7 +1988,9 @@ for decoding keyboard input from @var{terminal}. If @var{coding-system} is @code{nil}, that means not to decode keyboard input. If @var{terminal} is a frame, it means that frame's terminal; if it is @code{nil}, that means the currently selected frame's -terminal. @xref{Multiple Terminals}. +terminal. @xref{Multiple Terminals}. Note that on modern MS-Windows +systems Emacs always uses Unicode input when decoding keyboard input, +so the encoding set by this command has no effect on Windows. @end deffn @defun terminal-coding-system &optional terminal diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 365d5ac8d61..bbd3973f61b 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -516,9 +516,9 @@ codes for these non-@acronym{ASCII} control characters include the 2**26 @end ifnottex bit as well as the code for the corresponding non-control character. -Ordinary text terminals have no way of generating non-@acronym{ASCII} -control characters, but you can generate them straightforwardly using -X and other window systems. +Not all text terminals can generate non-@acronym{ASCII} control +characters, but it is straightforward to generate them using X and +other window systems. For historical reasons, Emacs treats the @key{DEL} character as the control equivalent of @kbd{?}: @@ -588,8 +588,8 @@ character is upper case or lower case. Emacs uses the 2**25 @end ifnottex bit to indicate that the shift key was used in typing a control -character. This distinction is possible only when you use X terminals -or other special terminals; ordinary text terminals do not report the +character. This distinction is possible only on a graphical display +such as a GUI display on X; text terminals do not report the distinction. The Lisp syntax for the shift bit is @samp{\S-}; thus, @samp{?\C-\S-o} or @samp{?\C-\S-O} represents the shifted-control-o character. @@ -1535,6 +1535,7 @@ editing. * Keymap Type:: What function a keystroke invokes. * Overlay Type:: How an overlay is represented. * Font Type:: Fonts for displaying text. +* Xwidget Type:: Embeddable widgets. @end menu @node Buffer Type @@ -1625,19 +1626,18 @@ markers. @node Window Type @subsection Window Type - A @dfn{window} describes the portion of the terminal screen that Emacs -uses to display a buffer. Every window has one associated buffer, whose -contents appear in the window. By contrast, a given buffer may appear -in one window, no window, or several windows. + A @dfn{window} describes the portion of the screen that Emacs uses to +display buffers. Every live window (@pxref{Basic Windows}) has one +associated buffer, whose contents appear in that window. By contrast, a +given buffer may appear in one window, no window, or several windows. +Windows are grouped on the screen into frames; each window belongs to +one and only one frame. @xref{Frame Type}. Though many windows may exist simultaneously, at any time one window -is designated the @dfn{selected window}. This is the window where the -cursor is (usually) displayed when Emacs is ready for a command. The -selected window usually displays the current buffer (@pxref{Current -Buffer}), but this is not necessarily the case. - - Windows are grouped on the screen into frames; each window belongs to -one and only one frame. @xref{Frame Type}. +is designated the @dfn{selected window} (@pxref{Selecting Windows}). +This is the window where the cursor is (usually) displayed when Emacs is +ready for a command. The selected window usually displays the current +buffer (@pxref{Current Buffer}), but this is not necessarily the case. Windows have no read syntax. They print in hash notation, giving the window number and the name of the buffer being displayed. The window @@ -1861,6 +1861,20 @@ syntax looks like @samp{#<font-object>}, @samp{#<font-spec>}, and @samp{#<font-entity>} respectively. @xref{Low-Level Font}, for a description of these Lisp objects. +@node Xwidget Type +@subsection Xwidget Type +@cindex xwidget type +@cindex xwidget-view type + + An @dfn{xwidget} is a special display element, such as a web +browser, that can be embedded inside a buffer. Each window that +displays an xwidget will also have an @dfn{xwidget view}, which on +X-Windows corresponds to a single X window used to display the widget. + +Neither of these objects are readable; their print syntaxes look like +@samp{#<xwidget>} and @samp{#<xwidget-view>}, respectively. +@xref{Xwidgets}, for a more detailed description of xwidgets. + @node Circular Objects @section Read Syntax for Circular Objects @cindex circular structure, read syntax diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 12ddaf04b6a..1fbd66458a4 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -813,7 +813,7 @@ Here is an example of how you could use these hooks: @smallexample @group (add-hook 'suspend-hook - (lambda () (or (y-or-n-p "Really suspend? ") + (lambda () (or (y-or-n-p "Really suspend?") (error "Suspend canceled")))) @end group (add-hook 'suspend-resume-hook (lambda () (message "Resumed!") @@ -1042,6 +1042,21 @@ that variable with @code{let} is also reasonable practice. if it removed @var{variable} from the environment. @end deffn +@defmac with-environment-variables variables body@dots{} +This macro sets the environment variables according to @var{variables} +temporarily when executing @var{body}. The previous values are +restored when the form finishes. The argument @var{variables} should +be a list of pairs of strings of the form +@w{@code{(@var{var} @var{value})}}, where @var{var} is the name of the +environment variable and @var{value} is that variable's value. + +@lisp +(with-environment-variables (("LANG" "C") + ("LANGUAGE" "en_US:en")) + (call-process "ls" nil t)) +@end lisp +@end defmac + @defvar process-environment This variable is a list of strings, each describing one environment variable. The functions @code{getenv} and @code{setenv} work by means @@ -3109,8 +3124,9 @@ watch for file attribute changes, like permissions or modification time @end table -If @var{file} is a directory, changes for all files in that directory -will be notified. This does not work recursively. +If @var{file} is a directory, @code{change} watches for file creation +or deletion in that directory. Some of the file notification backends +report also file changes. This does not work recursively. When any event happens, Emacs will call the @var{callback} function passing it a single argument @var{event}, which is of the form @@ -3215,6 +3231,14 @@ Removes an existing file watch specified by its @var{descriptor}. @code{file-notify-add-watch}. @end defun +@deffn Command file-notify-rm-all-watches +Removes all existing file notification watches from Emacs. + +Use this command with caution, because it could have unexpected side +effects on packages relying on file watches. It is intended mainly +for debugging purposes, or when Emacs has been stalled. +@end deffn + @defun file-notify-valid-p descriptor Checks a watch specified by its @var{descriptor} for validity. @var{descriptor} should be an object returned by diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi index e8aaa3ae1d1..aeb455bb25f 100644 --- a/doc/lispref/package.texi +++ b/doc/lispref/package.texi @@ -17,6 +17,11 @@ put it in a @dfn{package archive} for others to download. @xref{Packages,,, emacs, The GNU Emacs Manual}, for a description of user-level features of the packaging system. + These sections are mostly directed towards package archive +maintainers---much of this information is not relevant for package +authors (i.e., people who write code that will be distributed via +these archives). + @menu * Packaging Basics:: The basic concepts of Emacs Lisp packages. * Simple Packages:: How to package a single .el file. @@ -283,11 +288,14 @@ variable @code{load-file-name} (@pxref{Loading}). Here is an example: @section Creating and Maintaining Package Archives @cindex package archive +@cindex GNU ELPA +@cindex non-GNU ELPA Via the Package Menu, users may download packages from @dfn{package archives}. Such archives are specified by the variable -@code{package-archives}, whose default value contains a single entry: -the archive hosted by the GNU project at @url{https://elpa.gnu.org}. This -section describes how to set up and maintain a package archive. +@code{package-archives}, whose default value lists the archives +hosted on @url{https://elpa.gnu.org, GNU ELPA} and +@url{https://elpa.nongnu.org, non-GNU ELPA}. This section describes +how to set up and maintain a package archive. @cindex base location, package archive @defopt package-archives diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 90c42156372..8a9cb2a8f88 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -1047,6 +1047,19 @@ This function returns a list of all processes that have not been deleted. @end smallexample @end defun +@defun num-processors &optional query +This function returns the number of processors, a positive integer. +Each usable thread execution unit counts as a processor. +By default, the count includes the number of available processors, +which you can override by setting the +@url{https://www.openmp.org/spec-html/5.1/openmpse59.html, +@env{OMP_NUM_THREADS} environment variable of OpenMP}. +If the optional argument @var{query} is @code{current}, +this function ignores @env{OMP_NUM_THREADS}; +if @var{query} is @code{all}, this function also counts processors +that are on the system but are not available to the current process. +@end defun + @defun get-process name This function returns the process named @var{name} (a string), or @code{nil} if there is none. The argument @var{name} can also be a @@ -1766,9 +1779,12 @@ or more batches of output; one way to do this is to insert the received text into a temporary buffer, which can then be searched. @defun set-process-filter process filter -This function gives @var{process} the filter function @var{filter}. If -@var{filter} is @code{nil}, it gives the process the default filter, -which inserts the process output into the process buffer. +This function gives @var{process} the filter function @var{filter}. +If @var{filter} is @code{nil}, it gives the process the default +filter, which inserts the process output into the process buffer. If +@var{filter} is @code{t}, Emacs stops accepting output from the +process, unless it's a network server process that listens for +incoming connections. @end defun @defun process-filter process diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index 1d3e2d986c5..296ce20169c 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -263,6 +263,7 @@ case-sensitive. * Rx Notation:: An alternative, structured regexp notation. @end ifnottex * Regexp Functions:: Functions for operating on regular expressions. +* Regexp Problems:: Some problems and how they may be avoided. @end menu @node Syntax of Regexps @@ -343,15 +344,6 @@ first tries to match all three @samp{a}s; but the rest of the pattern is The next alternative is for @samp{a*} to match only two @samp{a}s. With this choice, the rest of the regexp matches successfully. -@strong{Warning:} Nested repetition operators can run for a very -long time, if they lead to ambiguous matching. For -example, trying to match the regular expression @samp{\(x+y*\)*a} -against the string @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could -take hours before it ultimately fails. Emacs may try each way of -grouping the @samp{x}s before concluding that none of them can work. -In general, avoid expressions that can match the same string in -multiple ways. - @item @samp{+} @cindex @samp{+} in regexp is a postfix operator, similar to @samp{*} except that it must match @@ -1060,7 +1052,8 @@ customization. The various forms in @code{rx} regexps are described below. The shorthand @var{rx} represents any @code{rx} form, and @var{rx}@dots{} -means zero or more @code{rx} forms. Where the corresponding string +means zero or more @code{rx} forms. These are all valid arguments to +the @code{rx} macro. Where the corresponding string regexp syntax is given, @var{A}, @var{B}, @dots{} are string regexp subexpressions. @@ -1356,7 +1349,8 @@ names: For details, @pxref{Syntax Class Table}. Please note that @code{(syntax punctuation)} is @emph{not} equivalent to the character class @code{punctuation}.@* -Corresponding string regexp: @samp{\s@var{code}} +Corresponding string regexp: @samp{\s@var{char}} where @var{char} is the +syntax character. @item @code{(category @var{category})} @cindex @code{category} in rx @@ -1413,7 +1407,8 @@ the names below or its category character. For more information about currently defined categories, run the command @kbd{M-x describe-categories @key{RET}}. For how to define new categories, @pxref{Categories}.@* -Corresponding string regexp: @samp{\c@var{code}} +Corresponding string regexp: @samp{\c@var{char}} where @var{char} is the +category character. @end table @subsubheading Zero-width assertions @@ -1543,11 +1538,18 @@ in the current global environment. @node Rx Functions @subsubsection Functions and macros using @code{rx} regexps -@defmac rx rx-expr@dots{} -Translate the @var{rx-expr}s to a string regexp, as if they were the +@defmac rx rx-form@dots{} +Translate the @var{rx-form}s to a string regexp, as if they were the body of a @code{(seq @dots{})} form. The @code{rx} macro expands to a string constant, or, if @code{literal} or @code{regexp} forms are -used, a Lisp expression that evaluates to a string. +used, a Lisp expression that evaluates to a string. Example: + +@example +@group +(rx (+ alpha) "=" (+ digit)) + @result{} "[[:alpha:]]+=[[:digit:]]+" +@end group +@end example @end defmac @defun rx-to-string rx-expr &optional no-group @@ -1555,6 +1557,14 @@ Translate @var{rx-expr} to a string regexp which is returned. If @var{no-group} is absent or nil, bracket the result in a non-capturing group, @samp{\(?:@dots{}\)}, if necessary to ensure that a postfix operator appended to it will apply to the whole expression. +Example: + +@example +@group +(rx-to-string '(seq (+ alpha) "=" (+ digit)) t) + @result{} "[[:alpha:]]+=[[:digit:]]+" +@end group +@end example Arguments to @code{literal} and @code{regexp} forms in @var{rx-expr} must be string literals. @@ -1649,6 +1659,24 @@ extra actual argument values not matched by any other parameter in Since the definition is global, it is recommended to give @var{name} a package prefix to avoid name clashes with definitions elsewhere, as is usual when naming non-local variables and functions. + +Forms defined this way only perform simple template substitution. +For arbitrary computations, use them together with the @code{rx} +forms @code{eval}, @code{regexp} or @code{literal}. Example: + +@example +@group +(defun n-tuple-rx (n element) + `(seq "<" + (group-n 1 ,element) + ,@@(mapcar (lambda (i) `(seq ?, (group-n ,i ,element))) + (number-sequence 2 n)) + ">")) +(rx-define n-tuple (n element) (eval (n-tuple-rx n 'element))) +(rx (n-tuple 3 (+ (in "0-9")))) + @result{} "<\\(?1:[0-9]+\\),\\(?2:[0-9]+\\),\\(?3:[0-9]+\\)>" +@end group +@end example @end defmac @defmac rx-let (bindings@dots{}) body@dots{} @@ -1848,6 +1876,73 @@ variables that may be set to a pattern that actually matches something. @end defvar +@node Regexp Problems +@subsection Problems with Regular Expressions +@cindex regular expression problems +@cindex regexp stack overflow +@cindex stack overflow in regexp + +The Emacs regexp implementation, like many of its kind, is generally +robust but occasionally causes trouble in either of two ways: matching +may run out of internal stack space and signal an error, and it can +take a long time to complete. The advice below will make these +symptoms less likely and help alleviate problems that do arise. + +@itemize +@item +Anchor regexps at the beginning of a line, string or buffer using +zero-width assertions (@samp{^} and @code{\`}). This takes advantage +of fast paths in the implementation and can avoid futile matching +attempts. Other zero-width assertions may also bring benefits by +causing a match to fail early. + +@item +Avoid or-patterns in favour of character alternatives: write +@samp{[ab]} instead of @samp{a\|b}. Recall that @samp{\s-} and @samp{\sw} +are equivalent to @samp{[[:space:]]} and @samp{[[:word:]]}, respectively. + +@item +Since the last branch of an or-pattern does not add a backtrack point +on the stack, consider putting the most likely matched pattern last. +For example, @samp{^\(?:a\|.b\)*c} will run out of stack if trying to +match a very long string of @samp{a}s, but the equivalent +@samp{^\(?:.b\|a\)*c} will not. + +(It is a trade-off: successfully matched or-patterns run faster with +the most frequently matched pattern first.) + +@item +Try to ensure that any part of the text can only match in a single +way. For example, @samp{a*a*} will match the same set of strings as +@samp{a*}, but the former can do so in many ways and will therefore +cause slow backtracking if the match fails later on. Make or-pattern +branches mutually exclusive if possible, so that matching will not go +far into more than one branch before failing. + +Be especially careful with nested repetitions: they can easily result +in very slow matching in the presence of ambiguities. For example, +@samp{\(?:a*b*\)+c} will take a long time attempting to match even a +moderately long string of @samp{a}s before failing. The equivalent +@samp{\(?:a\|b\)*c} is much faster, and @samp{[ab]*c} better still. + +@item +Don't use capturing groups unless they are really needed; that is, use +@samp{\(?:@dots{}\)} instead of @samp{\(@dots{}\)} for bracketing +purposes. + +@ifnottex +@item +Consider using @code{rx} (@pxref{Rx Notation}); it can optimise some +or-patterns automatically and will never introduce capturing groups +unless explicitly requested. +@end ifnottex +@end itemize + +If you run into regexp stack overflow despite following the above +advice, don't be afraid of performing the matching in multiple +function calls, each using a simpler regexp where backtracking can +more easily be contained. + @node Regexp Search @section Regular Expression Searching @cindex regular expression searching @@ -1950,7 +2045,7 @@ feature for matching regular expressions from end to beginning. It's not worth the trouble of implementing that. @end deffn -@defun string-match regexp string &optional start +@defun string-match regexp string &optional start inhibit-modify This function returns the index of the start of the first match for the regular expression @var{regexp} in @var{string}, or @code{nil} if there is no match. If @var{start} is non-@code{nil}, the search starts @@ -1975,8 +2070,10 @@ For example, The index of the first character of the string is 0, the index of the second character is 1, and so on. -If this function finds a match, the index of the first character beyond -the match is available as @code{(match-end 0)}. @xref{Match Data}. +By default, if this function finds a match, the index of the first +character beyond the match is available as @code{(match-end 0)}. +@xref{Match Data}. If @var{inhibit-modify} is non-@code{nil}, the +match data isn't modified. @example @group @@ -1997,16 +2094,18 @@ This predicate function does what @code{string-match} does, but it avoids modifying the match data. @end defun -@defun looking-at regexp +@defun looking-at regexp &optional inhibit-modify This function determines whether the text in the current buffer directly following point matches the regular expression @var{regexp}. ``Directly following'' means precisely that: the search is ``anchored'' and it can succeed only starting with the first character following point. The result is @code{t} if so, @code{nil} otherwise. -This function does not move point, but it does update the match data. -@xref{Match Data}. If you need to test for a match without modifying -the match data, use @code{looking-at-p}, described below. +This function does not move point, but it does update the match data +(if @var{inhibit-modify} is @code{nil} or missing, which is the +default). @xref{Match Data}. As a convenience, instead of using the +@var{inhibit-modify} argument, you can use @code{looking-at-p}, +described below. In this example, point is located directly before the @samp{T}. If it were anywhere else, the result would be @code{nil}. @@ -2113,13 +2212,13 @@ backtracking specified by the POSIX standard for regular expression matching. @end deffn -@defun posix-looking-at regexp +@defun posix-looking-at regexp &optional inhibit-modify This is like @code{looking-at} except that it performs the full backtracking specified by the POSIX standard for regular expression matching. @end defun -@defun posix-string-match regexp string &optional start +@defun posix-string-match regexp string &optional start inhibit-modify This is like @code{string-match} except that it performs the full backtracking specified by the POSIX standard for regular expression matching. @@ -2540,9 +2639,9 @@ associated with it still exists. @cindex replacement after search @cindex searching and replacing - If you want to find all matches for a regexp in part of the buffer, -and replace them, the best way is to write an explicit loop using -@code{re-search-forward} and @code{replace-match}, like this: + If you want to find all matches for a regexp in part of the buffer +and replace them, the most flexible way is to write an explicit loop +using @code{re-search-forward} and @code{replace-match}, like this: @example (while (re-search-forward "foo[ \t]+bar" nil t) @@ -2553,9 +2652,33 @@ and replace them, the best way is to write an explicit loop using @xref{Replacing Match,, Replacing the Text that Matched}, for a description of @code{replace-match}. - However, replacing matches in a string is more complex, especially -if you want to do it efficiently. So Emacs provides two functions to do -this. + It may be more convenient to limit the replacements to a specific +region. The function @code{replace-regexp-in-region} does that. + +@defun replace-regexp-in-region regexp replacement &optional start end +This function replaces all the occurrences of @var{regexp} with +@var{replacement} in the region of buffer text between @var{start} and +@var{end}; @var{start} defaults to position of point, and @var{end} +defaults to the last accessible position of the buffer. The search +for @var{regexp} is case-sensitive, and @var{replacement} is inserted +without changing its letter-case. The @var{replacement} string can +use the same special elements starting with @samp{\} as +@code{replace-match} does. The function returns the number of +replaced occurrences, or @code{nil} if @var{regexp} is not found. The +function preserves the position of point. + +@example +(replace-regexp-in-region "foo[ \t]+bar" "foobar") +@end example +@end defun + +@defun replace-string-in-region string replacement &optional start end + This function works similarly to @code{replace-regexp-in-region}, +but searches for, and replaces, literal @var{string}s instead of +regular expressions. +@end defun + + Emacs also has special functions for replacing matches in a string. @defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start This function copies @var{string} and searches it for matches for @@ -2578,9 +2701,9 @@ replacement string. The match data at this point are the result of matching @var{regexp} against a substring of @var{string}. @end defun -@defun string-replace fromstring tostring instring -This function replaces all occurrences of @var{fromstring} with -@var{tostring} in @var{instring} and returns the result. It may +@defun string-replace from-string to-string in-string +This function replaces all occurrences of @var{from-string} with +@var{to-string} in @var{in-string} and returns the result. It may return one of its arguments unchanged, a constant string or a new string. Case is significant, and text properties are ignored. @end defun diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 545fd408f88..4a48d62f6db 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -953,6 +953,24 @@ contain less elements than @var{n}. @var{n} must be an integer. If @end example @end defun +@defun seq-union sequence1 sequence2 &optional function +@cindex sequences, union of +@cindex union of sequences + This function returns a list of the elements that appear either in +@var{sequence1} or @var{sequence2}. The elements of the returned list +are all unique, in the sense that no two elements there will compare +equal. If the optional argument @var{function} is non-@code{nil}, it +should be a function of two arguments to use to compare elements, +instead of the default @code{equal}. + +@example +@group +(seq-union [1 2 3] [3 5]) +@result{} (1 2 3 5) +@end group +@end example +@end defun + @defun seq-intersection sequence1 sequence2 &optional function @cindex sequences, intersection of @cindex intersection of sequences @@ -1111,6 +1129,23 @@ The @code{pcase} patterns provide an alternative facility for destructuring binding, see @ref{Destructuring with pcase Patterns}. @end defmac +@defmac seq-setq var-sequence val-sequence +@cindex sequence destructuring + This macro works similarly to @code{seq-let}, except that values are +assigned to variables as if by @code{setq} instead of as in a +@code{let} binding. + +@example +@group +(let ((a nil) + (b nil)) + (seq-setq (_ a _ b) '(1 2 3 4)) + (list a b)) +@result{} (2 4) +@end group +@end example +@end defmac + @defun seq-random-elt sequence This function returns an element of @var{sequence} taken at random. diff --git a/doc/lispref/spellfile b/doc/lispref/spellfile index 45a122d26ac..11a6ce813af 100644 --- a/doc/lispref/spellfile +++ b/doc/lispref/spellfile @@ -179,6 +179,8 @@ copyleft counterintuitive cr creatable +customization +customizations customize deactivate deactivated @@ -243,6 +245,8 @@ fmakunbound fo fol following' +fontification +fontified fooba foobaz foox @@ -257,6 +261,7 @@ garbles gc getenv gid +glyphs gp grep gtr @@ -270,6 +275,8 @@ hostname hpux hscroll ick +iconified +iconify id idiom ii @@ -314,6 +321,7 @@ mathsurround memq mh mini +minibuf minibuffer's minibuffers misalignment @@ -387,6 +395,7 @@ passwd ped perverse pid +pixelwise plist pointer' pointm @@ -417,6 +426,10 @@ reader' rebind rec rechecking +redisplay +redisplayed +redisplaying +redisplays redo redrawing redraws @@ -430,6 +443,7 @@ reinitialize reinitialized reinstall reinstalled +resizable resize resized resizes @@ -486,6 +500,8 @@ terpri text' tildes time's +tooltip +tooltips towards transportable txt @@ -494,6 +510,7 @@ unbind unbinding unbinds unclutters +uncustomized undefine undefines underfull @@ -520,6 +537,7 @@ vconcat vectorp vn voidness +whitespace window' windowing windowp diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index b4d7bc729f5..0914f204113 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -402,7 +402,7 @@ Remove the trailing text that matches @var{regexp} from @var{string}. @defun string-trim string &optional trim-left trim-right Remove the leading text that matches @var{trim-left} and trailing text -that matches @var{trim-right} from from @var{string}. Both regexps +that matches @var{trim-right} from @var{string}. Both regexps default to @samp{[ \t\n\r]+}. @end defun @@ -414,18 +414,24 @@ will not be shortened. @end defun @defun string-limit string length &optional end coding-system -If @var{string} is shorter than @var{length}, @var{string} is returned -as is. Otherwise, return a substring of @var{string} consisting of -the first @var{length} characters. If the optional @var{end} -parameter is given, return a string of the @var{length} last +If @var{string} is shorter than @var{length} characters, @var{string} +is returned as is. Otherwise, return a substring of @var{string} +consisting of the first @var{length} characters. If the optional +@var{end} parameter is given, return a string of the @var{length} last characters instead. If @var{coding-system} is non-@code{nil}, @var{string} will be encoded before limiting, and the result will be a unibyte string that's -shorter than @code{length}. If @var{string} contains characters that -are encoded into several bytes (for instance, when using +shorter than @code{length} bytes. If @var{string} contains characters +that are encoded into several bytes (for instance, when using @code{utf-8}), the resulting unibyte string is never truncated in the middle of a character representation. + +This function measures the string length in characters or bytes, and +thus is generally inappropriate if you need to shorten strings for +display purposes; use @code{truncate-string-to-width} or +@code{window-text-pixel-size} or @code{string-glyph-split} instead +(@pxref{Size of Displayed Text}). @end defun @defun string-lines string &optional omit-nulls diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index ed36f5139a8..b30a16927ec 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -29,6 +29,9 @@ otherwise. * Creating Symbols:: How symbols are kept unique. * Symbol Properties:: Each symbol has a property list for recording miscellaneous information. +* Shorthands:: Properly organize your symbol names but + type less of them. + @end menu @node Symbol Components @@ -67,7 +70,10 @@ important not to have two symbols with the same name. The Lisp reader ensures this: every time it reads a symbol, it looks for an existing symbol with the specified name before it creates a new one. To get a symbol's name, use the function @code{symbol-name} (@pxref{Creating -Symbols}). +Symbols}). However, although each symbol has only one unique +@emph{print name}, it is nevertheless possible to refer to that same +symbol via different alias names called ``shorthands'' +(@pxref{Shorthands}). The value cell holds a symbol's value as a variable, which is what you get if the symbol itself is evaluated as a Lisp expression. @@ -166,26 +172,39 @@ definitions. @xref{Name Help,,, emacs, The GNU Emacs Manual}. @section Creating and Interning Symbols @cindex reading symbols - To understand how symbols are created in GNU Emacs Lisp, you must know -how Lisp reads them. Lisp must ensure that it finds the same symbol -every time it reads the same set of characters. Failure to do so would -cause complete confusion. + To understand how symbols are created in GNU Emacs Lisp, you must +know how Lisp reads them. Lisp must ensure that it finds the same +symbol every time it reads the same sequence of characters in the same +context. Failure to do so would cause complete confusion. @cindex symbol name hashing @cindex hashing @cindex obarray @cindex bucket (in obarray) - When the Lisp reader encounters a symbol, it reads all the characters -of the name. Then it hashes those characters to find an index in a -table called an @dfn{obarray}. Hashing is an efficient method of -looking something up. For example, instead of searching a telephone -book cover to cover when looking up Jan Jones, you start with the J's -and go from there. That is a simple version of hashing. Each element -of the obarray is a @dfn{bucket} which holds all the symbols with a -given hash code; to look for a given name, it is sufficient to look -through all the symbols in the bucket for that name's hash code. (The -same idea is used for general Emacs hash tables, but they are a -different data type; see @ref{Hash Tables}.) + When the Lisp reader encounters a name that references a symbol in +the source code, it reads all the characters of that name. Then it +looks up that name in a table called an @dfn{obarray} to find the +symbol that the programmer meant. The technique used in this lookup +is called ``hashing'', an efficient method of looking something up by +converting a sequence of characters to a number, known as a ``hash +code''. For example, instead of searching a telephone book cover to +cover when looking up Jan Jones, you start with the J's and go from +there. That is a simple version of hashing. Each element of the +obarray is a @dfn{bucket} which holds all the symbols with a given +hash code; to look for a given name, it is sufficient to look through +all the symbols in the bucket for that name's hash code. (The same +idea is used for general Emacs hash tables, but they are a different +data type; see @ref{Hash Tables}.) + +When looking up names, the Lisp reader also considers ``shorthands''. +If the programmer supplied them, this allows the reader to find a +symbol even if its name isn't present in its full form in the source +code. Of course, the reader needs to be aware of some pre-established +context about such shorthands, much as one needs context to be to able +to refer uniquely to Jan Jones by just the name ``Jan'': it's probably +fine when amongst the Joneses, or when Jan has been mentioned +recently, but very ambiguous in any other situation. +@xref{Shorthands}. @cindex interning If a symbol with the desired name is found, the reader uses that @@ -200,9 +219,13 @@ same obarray. Thus, the reader gets the same symbols for the same names, as long as you keep reading with the same obarray. Interning usually happens automatically in the reader, but sometimes -other programs need to do it. For example, after the @kbd{M-x} command -obtains the command name as a string using the minibuffer, it then -interns the string, to get the interned symbol with that name. +other programs may want to do it. For example, after the @kbd{M-x} +command obtains the command name as a string using the minibuffer, it +then interns the string, to get the interned symbol with that name. +As another example, a hypothetical telephone book program could intern +the name of each looked up person's name as a symbol, even if the +obarray did not contain it, so that it could attach information to +that new symbol, such as the last time someone looked it up. @cindex symbol equality @cindex uninterned symbol @@ -210,11 +233,8 @@ interns the string, to get the interned symbol with that name. obarray. They are called @dfn{uninterned symbols}. An uninterned symbol has the same four cells as other symbols; however, the only way to gain access to it is by finding it in some other object or as the -value of a variable. - - Creating an uninterned symbol is useful in generating Lisp code, -because an uninterned symbol used as a variable in the code you generate -cannot clash with any variables used in other Lisp programs. +value of a variable. Uninterned symbols are sometimes useful in +generating Lisp code, see below. In Emacs Lisp, an obarray is actually a vector. Each element of the vector is a bucket; its value is either an interned symbol whose name @@ -236,7 +256,10 @@ not work---only @code{intern} can enter a symbol in an obarray properly. @cindex CL note---symbol in obarrays @quotation @b{Common Lisp note:} Unlike Common Lisp, Emacs Lisp does not provide -for interning a single symbol in several obarrays. +for interning the same name in several different ``packages'', thus +creating multiple symbols with the same name but different packages. +Emacs Lisp provides a different namespacing system called +``shorthands'' (@pxref{Shorthands}). @end quotation Most of the functions below take a name and sometimes an obarray as @@ -258,6 +281,11 @@ change the name of the symbol, but fails to update the obarray, so don't do it! @end defun +@cindex uninterned symbol, and generating Lisp code +Creating an uninterned symbol is useful in generating Lisp code, +because an uninterned symbol used as a variable in the code you +generate cannot clash with any variables used in other Lisp programs. + @defun make-symbol name This function returns a newly-allocated, uninterned symbol whose name is @var{name} (which must be a string). Its value and function definition @@ -275,10 +303,16 @@ distinct uninterned symbol whose name is also @samp{foo}. @defun gensym &optional prefix This function returns a symbol using @code{make-symbol}, whose name is -made by appending @code{gensym-counter} to @var{prefix}. The prefix -defaults to @code{"g"}. +made by appending @code{gensym-counter} to @var{prefix} and incrementing +that counter, guaranteeing that no two calls to this function will +generate a symbol with the same name. The prefix defaults to +@code{"g"}. @end defun +To avoid problems when accidentally interning printed representation +of generated code (@pxref{Printed Representation}), it is recommended +to use @code{gensym} instead of @code{make-symbol}. + @defun intern name &optional obarray This function returns the interned symbol whose name is @var{name}. If there is no such symbol in the obarray @var{obarray}, @code{intern} @@ -600,3 +634,120 @@ If non-@code{nil}, this specifies the named variable's documentation string. This is set automatically by @code{defvar} and related functions. @xref{Defining Faces}. @end table + +@node Shorthands +@section Shorthands +@cindex shorthands +@cindex symbolic shorthands +@cindex namespacing +@cindex namespaces + + The symbol @dfn{shorthands}, sometimes known as ``renamed symbols'', are +symbolic forms found in Lisp source. They're just like regular +symbolic forms, except that when the Lisp reader encounters them, it +produces symbols which have a different and usually longer @dfn{print +name} (@pxref{Symbol Components}). + +It is useful to think of shorthands as @emph{abbreviating} the full +names of intended symbols. Despite this, do not confuse shorthands with the +Abbrev system @pxref{Abbrevs}. + +@cindex namespace etiquette +Shorthands make Emacs Lisp's @dfn{namespacing etiquette} easier to work +with. Since all symbols are stored in a single obarray +(@pxref{Creating Symbols}), programmers commonly prefix each symbol +name with the name of the library where it originates. For example, +the functions @code{text-property-search-forward} and +@code{text-property-search-backward} both belong to the +@file{text-property-search.el} library (@pxref{Loading}). By properly +prefixing symbol names, one effectively prevents clashes between +similarly named symbols which belong to different libraries and thus do +different things. However, this practice commonly originates very +long symbols names, which are inconvenient to type and read after a +while. Shorthands solve these issues in a clean way. + +@defvar read-symbol-shorthands +This variable's value is an alist whose elements have the form +@code{(@var{shorthand-prefix} . @var{longhand-prefix})}. Each element +instructs the Lisp reader to read every symbol form which starts with +@var{shorthand-prefix} as if it started with @var{longhand-prefix} +instead. + +This variable may only be set in file-local variables (@pxref{File Variables, , +Local Variables in Files, emacs, The GNU Emacs Manual}). +@end defvar + +Here's an example of shorthands usage in a hypothetical string +manipulating library @file{some-nice-string-utils.el}. + +@smalllisp +(defun some-nice-string-utils-split (separator s &optional omit-nulls) + "A match-data saving variant of `split-string'." + (save-match-data (split-string s separator omit-nulls))) + +(defun some-nice-string-utils-lines (s) + "Split string S at newline characters into a list of strings." + (some-nice-string-utils-split "\\(\r\n\\|[\n\r]\\)" s)) +@end smalllisp + +As can be seen, it's quite tedious to read or develop this code since +the symbol names to type are so long. We can use shorthands to +alleviate that. + +@lisp +(defun snu-split (separator s &optional omit-nulls) + "A match-data saving variation on `split-string'." + (save-match-data (split-string s separator omit-nulls))) + +(defun snu-lines (s) + "Split string S into a list of strings on newline characters." + (snu-split "\\(\r\n\\|[\n\r]\\)" s)) + +;; Local Variables: +;; read-symbol-shorthands: (("snu-" . "some-nice-string-utils-")) +;; End: +@end lisp + +Even though the two excerpts look different, they are quite identical +after the Lisp reader processes them. Both will lead to the very same +symbols being interned (@pxref{Creating Symbols}). Thus loading or +byte-compiling any of the two files has equivalent results. The +shorthands @code{snu-split} and @code{snu-lines} used in the second +version are @emph{not} interned in the obarray. This is easily seen +by moving point to the location where the shorthands are used and +waiting for ElDoc (@pxref{Lisp Doc, , Local Variables in Files, emacs, +The GNU Emacs Manual}) to hint at the true full name of the symbol +under point in the echo area. + +Since @code{read-symbol-shorthands} is a file-local variable, it is +possible that multiple libraries depending on +@file{some-nice-string-utils-lines.el} refer to the same symbols under +@emph{different} shorthands, or not using shorthands at all. In the +next example, the @file{my-tricks.el} library refers to the symbol +@code{some-nice-string-utils-lines} using the @code{sns-} prefix +instead of @code{snu-}. + +@example +(defun t-reverse-lines (s) (string-join (reverse (sns-lines s)) "\n") + +;; Local Variables: +;; read-symbol-shorthands: (("t-" . "my-tricks-") +;; ("sns-" . "some-nice-string-utils-")) +;; End: +@end example + +@subsection Exceptions + +There are two exceptions to rules governing Shorthand transformations: + +@itemize @bullet +@item +Symbol forms comprised entirely of characters in the Emacs Lisp symbol +constituent class (@pxref{Syntax Class Table}) are not transformed. +For example, it's possible to use @code{-} or @code{/=} as shorthand +prefixes, but that won't shadow the arithmetic @emph{functions} of +those names. + +@item +Symbol forms whose names start with @samp{#_} are not transformed. +@end itemize diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi index deec3f44c08..87ade73c2ae 100644 --- a/doc/lispref/syntax.texi +++ b/doc/lispref/syntax.texi @@ -900,6 +900,7 @@ arrived at a top level position. @defun syntax-ppss-context state Return @code{string} if the end position of the scan returning @var{state} is in a string, and @code{comment} if it's in a comment. +Otherwise return @code{nil}. @end defun @node Low-Level Parsing diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index e18ba472822..937680c200d 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -315,10 +315,11 @@ word on the same line is acceptable. @defun thing-at-point thing &optional no-properties Return the @var{thing} around or next to point, as a string. -The argument @var{thing} is a symbol which specifies a kind of syntactic -entity. Possibilities include @code{symbol}, @code{list}, @code{sexp}, -@code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence}, -@code{whitespace}, @code{line}, @code{page}, and others. +The argument @var{thing} is a symbol which specifies a kind of +syntactic entity. Possibilities include @code{symbol}, @code{list}, +@code{sexp}, @code{defun}, @code{filename}, @code{existing-filename}, +@code{url}, @code{word}, @code{sentence}, @code{whitespace}, +@code{line}, @code{page}, @code{string}, and others. When the optional argument @var{no-properties} is non-@code{nil}, this function strips text properties from the return value. @@ -598,6 +599,19 @@ This command indents to the left margin if that is not zero. The value returned is @code{nil}. @end deffn +@deffn Command ensure-empty-lines &optional number-of-empty-lines +This command can be used to ensure that you have a specific number of +empty lines before point. (An ``empty line'' is here defined as a +line with no characters on it---a line with space characters isn't an +empty line.) It defaults to ensuring that there's a single empty line +before point. + +If point isn't at the beginning of a line, a newline character is +inserted first. If there's more empty lines before point than +specified, the number of empty lines is reduced. Otherwise it's +increased to the specified number. +@end deffn + @defvar overwrite-mode This variable controls whether overwrite mode is in effect. The value should be @code{overwrite-mode-textual}, @code{overwrite-mode-binary}, @@ -1328,7 +1342,7 @@ that @kbd{C-y} should yank. @defopt kill-ring-max The value of this variable is the maximum length to which the kill ring can grow, before elements are thrown away at the end. The default -value for @code{kill-ring-max} is 60. +value for @code{kill-ring-max} is 120. @end defopt @node Undo @@ -1492,6 +1506,11 @@ continuing to undo. This function does not bind @code{undo-in-progress}. @end defun +@defmac with-undo-amalgamate body@dots{} +This macro removes all the undo boundaries inserted during the +execution of @var{body} so that it can be undone as a single step. +@end defmac + Some commands leave the region active after execution in such a way that it interferes with selective undo of that command. To make @code{undo} ignore the active region when invoked immediately after such a command, @@ -1801,7 +1820,12 @@ read, you should set @code{fill-column} to no more than 70. Otherwise the line will be too long for people to read comfortably, and this can make the text seem clumsy. -The default value for @code{fill-column} is 70. +The default value for @code{fill-column} is 70. To disable Auto Fill +mode in a specific mode, you could say something like: + +@lisp +(add-hook 'foo-mode-hook (lambda () (auto-fill-mode -1)) +@end lisp @end defopt @deffn Command set-left-margin from to margin @@ -3596,6 +3620,11 @@ edited even in read-only buffers. @xref{Read Only Buffers}. A non-@code{nil} @code{invisible} property can make a character invisible on the screen. @xref{Invisible Text}, for details. +@kindex inhibit-isearch @r{(text property)} +@item inhibit-isearch +A non-@code{nil} @code{inhibit-isearch} property will make isearch +skip the text. + @item intangible @kindex intangible @r{(text property)} If a group of consecutive characters have equal and non-@code{nil} diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 8aa225a00c3..cbfcbd8d14f 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -252,6 +252,13 @@ themselves; Lisp programmers find this disconcerting. Please put a copyright notice and copying permission notice on the file if you distribute copies. @xref{Library Headers}. +@item +For variables holding (or functions returning) a file or directory name, +avoid using @code{path} in its name, preferring @code{file}, +@code{file-name}, or @code{directory} instead, since Emacs follows the +GNU convention to use the term @emph{path} only for search paths, +which are lists of directory names. + @end itemize @node Key Binding Conventions @@ -393,12 +400,18 @@ Don't use @code{message}, @code{throw}, @code{sleep-for}, or @item An error message should start with a capital letter but should not end -with a period. +with a period or other punctuation. + +It is occasionally useful to tell the user where an error originated, +even if @code{debug-on-error} is @code{nil}. In such cases, a +lower-case Lisp symbol can be prepended to the error message. For +example, the error message ``Invalid input'' could be extended to say +``some-function: Invalid input''. @item A question asked in the minibuffer with @code{yes-or-no-p} or @code{y-or-n-p} should start with a capital letter and end with -@samp{? }. +@samp{?}. @item When you mention a default value in a minibuffer prompt, @@ -755,11 +768,33 @@ anchor}. The Info file name defaults to @samp{emacs}. For example, See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'. @end smallexample +To make a hyperlink to a man page, write the single-quoted name of the +man page, preceded by @samp{Man page}, @samp{man page}, or @samp{man +page for}. For example, + +@smallexample +See the man page `chmod(1)' for details. +@end smallexample + +@noindent +The Info documentation is always preferable to man pages, so be sure +to link to an Info manual where available. For example, +@command{chmod} is documented in the GNU Coreutils manual, so it is +better to link to that instead of the man page. + +To link to a customization group, write the single-quoted name of the +group, preceded by @samp{customization group} (the first character in +each word is case-insensitive). For example, + +@smallexample +See the customization group `whitespace' for details. +@end smallexample + Finally, to create a hyperlink to URLs, write the single-quoted URL, preceded by @samp{URL}. For example, @smallexample -The home page for the GNU project has more information (see URL +The GNU project wesite has more information (see URL `https://www.gnu.org/'). @end smallexample @@ -781,10 +816,12 @@ the first use of @samp{\\[@dots{}]}. The text inside the @samp{\\<@dots{}>} should be the name of the variable containing the local keymap for the major mode. -It is not practical to use @samp{\\[@dots{}]} very many times, because -display of the documentation string will become slow. So use this to -describe the most important commands in your major mode, and then use -@samp{\\@{@dots{}@}} to display the rest of the mode's keymap. +Each use of @samp{\\[@dots{}]} slows the display of the documentation +string by a tiny amount. If you use a lot of them, these tiny +slowdowns will add up, and might become tangible, especially on slow +systems. So our recommendation is not to over-use them; e.g., try to +avoid using more than one reference to the same command in the same +doc string. @item For consistency, phrase the verb in the first sentence of a function's @@ -1090,9 +1127,9 @@ The name of this field is unfortunate, since people often assume it is the place to write arbitrary keywords that describe their package, rather than just the relevant Finder keywords. -@item Homepage -@itemx URL -These lines state the homepage of the library. +@item URL +@itemx Homepage +These lines state the website of the library. @item Package-Version If @samp{Version} is not suitable for use by the package manager, then diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 9356fb9f699..d2247004bcb 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -194,7 +194,7 @@ default scoping rule in Emacs Lisp is called @dfn{dynamic scoping}, which simply states that the current binding at any given point in the execution of a program is the most recently-created binding for that variable that still exists. For details about dynamic scoping, and an -alternative scoping rule called @dfn{lexical scoping}, @xref{Variable +alternative scoping rule called @dfn{lexical scoping}, @pxref{Variable Scoping}. The special forms @code{let} and @code{let*} exist to create local @@ -286,6 +286,57 @@ being run once: @end lisp @end defspec +@cindex dynamic binding, temporarily +@cindex dynamic let-binding +@defspec dlet (bindings@dots{}) forms@dots{} +This special form is like @code{let}, but it binds all variables +dynamically. This is rarely useful---you usually want to bind normal +variables lexically, and special variables (i.e., variables that are +defined with @code{defvar}) dynamically, and this is what @code{let} +does. + +@code{dlet} can be useful when interfacing with old code that assumes +that certain variables are dynamically bound (@pxref{Dynamic +Binding}), but it's impractical to @code{defvar} these variables. +@code{dlet} will temporarily make the bound variables special, execute +the forms, and then make the variables non-special again. +@end defspec + +@defspec named-let name bindings &rest body +This special form is a looping construct inspired from the +Scheme language. It is similar to @code{let}: It binds the variables in +@var{bindings}, and then evaluates @var{body}. However, +@code{named-let} also binds @var{name} to a +local function whose formal arguments are the variables in @var{bindings} +and whose body is @var{body}. This allows @var{body} to call itself +recursively by calling +@var{name}, where the arguments passed to @var{name} are used as the +new values of the bound variables in the recursive invocation. + +Example of a loop summing a list of numbers: + +@lisp +(named-let sum ((numbers '(1 2 3 4)) + (running-sum 0)) + (if numbers + (sum (cdr numbers) (+ running-sum (car numbers))) + running-sum)) +@result{} 10 +@end lisp + +@anchor{Tail recursion} +Recursive calls to @var{name} that occur in @emph{tail +positions} in @var{body} are guaranteed to be optimised as @emph{tail +calls}, which means that they will not consume any additional stack +space no matter how deeply the recursion runs. Such recursive calls +will effectively jump to the top of the loop with new values for the +variables. + +A function call is in the tail position if it's the very last thing +done so that the value returned by the call is the value of @var{body} +itself, as is the case in the recursive call to @code{sum} above. +@end defspec + Here is a complete list of the other facilities that create local bindings: @@ -1644,12 +1695,14 @@ buffer-local variables interactively. @end deffn @cindex local variables, killed by major mode -@defun kill-all-local-variables +@defun kill-all-local-variables &optional kill-permanent This function eliminates all the buffer-local variable bindings of the -current buffer except for variables marked as permanent and local -hook functions that have a non-@code{nil} @code{permanent-local-hook} -property (@pxref{Setting Hooks}). As a result, the buffer will see -the default values of most variables. +current buffer. As a result, the buffer will see the default values +of most variables. By default, for variables marked as permanent and +local hook functions that have a non-@code{nil} +@code{permanent-local-hook} property (@pxref{Setting Hooks}) won't be +killed, but if the optional @var{kill-permanent} argument is +non-@code{nil}, even these variables will be killed. This function also resets certain other information pertaining to the buffer: it sets the local keymap to @code{nil}, the syntax table to the diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 26f85df160e..d718ac59be6 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -14,6 +14,7 @@ is displayed in windows. @menu * Basic Windows:: Basic information on using windows. * Windows and Frames:: Relating windows to the frame they appear on. +* Selecting Windows:: The selected window is the one that you edit in. * Window Sizes:: Accessing a window's size. * Resizing Windows:: Changing the sizes of windows. * Preserving Window Sizes:: Preserving the size of windows. @@ -21,7 +22,6 @@ is displayed in windows. * Deleting Windows:: Removing a window from its frame. * Recombining Windows:: Preserving the frame layout when splitting and deleting windows. -* Selecting Windows:: The selected window is the one that you edit in. * Cyclic Window Ordering:: Moving around the existing windows. * Buffers and Windows:: Each window displays the contents of a buffer. * Switching Buffers:: Higher-level functions for switching to a buffer. @@ -53,32 +53,37 @@ is displayed in windows. @section Basic Concepts of Emacs Windows @cindex window -A @dfn{window} is an area of the screen that is used to display a buffer -(@pxref{Buffers}). In Emacs Lisp, windows are represented by a special -Lisp object type. - @cindex multiple windows - Windows are grouped into frames (@pxref{Frames}). Each frame -contains at least one window; the user can subdivide it into multiple, -non-overlapping windows to view several buffers at once. Lisp -programs can use multiple windows for a variety of purposes. In -Rmail, for example, you can view a summary of message titles in one -window, and the contents of the selected message in another window. +A @dfn{window} is an area of the screen that can be used to display a +buffer (@pxref{Buffers}). Windows are grouped into frames +(@pxref{Frames}). Each frame contains at least one window; the user can +subdivide a frame into multiple, non-overlapping windows to view several +buffers at once. Lisp programs can use multiple windows for a variety +of purposes. In Rmail, for example, you can view a summary of message +titles in one window, and the contents of the selected message in +another window. @cindex terminal screen @cindex screen of terminal - Emacs uses the word ``window'' with a different meaning than in -graphical desktop environments and window systems, such as the X -Window System. When Emacs is run on X, each of its graphical X -windows is an Emacs frame (containing one or more Emacs windows). -When Emacs is run on a text terminal, the frame fills the entire -terminal screen. +@cindex window-system window + Emacs uses the term ``window'' with a different meaning than in +graphical desktop environments and window systems, such as the X Window +System. When Emacs is run on X, each graphical X window owned by the +Emacs process corresponds to one Emacs frame. When Emacs is run on a +text terminal, each Emacs frame fills the entire terminal screen. In +either case, the frame may contain one or more Emacs windows. For +disambiguation, we use the term @dfn{window-system window} when we mean +the window-system window corresponding to an Emacs frame. @cindex tiled windows Unlike X windows, Emacs windows are @dfn{tiled}; they never overlap -within the area of the frame. When a window is created, resized, or -deleted, the change in window space is taken from or given to the -adjacent windows, so that the total area of the frame is unchanged. +within the area of their frame. When a window is created, resized, or +deleted, the change in window space is taken from or given to other +windows on the same frame, so that the total area of the frame is +unchanged. + +In Emacs Lisp, windows are represented by a special Lisp object type +(@pxref{Window Type}). @defun windowp object This function returns @code{t} if @var{object} is a window (whether or @@ -117,94 +122,145 @@ internal window in a window tree. Otherwise, it returns @code{nil}, including for the case where @var{object} is a deleted window. @end defun -@cindex selected window -@cindex window selected within a frame - In each frame, at any time, exactly one Emacs window is designated -as @dfn{selected within the frame}. For the selected frame, that -window is called the @dfn{selected window}---the one in which most -editing takes place, and in which the cursor for selected windows -appears (@pxref{Cursor Parameters}). Keyboard input that inserts or -deletes text is also normally directed to this window. The selected -window's buffer is usually also the current buffer, except when -@code{set-buffer} has been used (@pxref{Current Buffer}). As for -non-selected frames, the window selected within the frame becomes the -selected window if the frame is ever selected. @xref{Selecting -Windows}. + The following schematic shows the structure of a live window: -@defun selected-window -This function returns the selected window (which is always a live -window). -@end defun +@smallexample +@group + ____________________________________________ + |________________ Tab Line _______________|RD| ^ + |______________ Header Line ______________| | | + ^ |LS|LM|LF| |RF|RM|RS| | | + | | | | | | | | | | | +Window | | | | | | | | | Window +Body | | | | | Window Body | | | | | Total +Height | | | | | | | | | Height + | | | | |<- Window Body Width ->| | | | | | + v |__|__|__|_______________________|__|__|__| | | + |_________ Horizontal Scroll Bar _________| | | + |_______________ Mode Line _______________|__| | + |_____________ Bottom Divider _______________| v + <---------- Window Total Width ------------> -@anchor{Window Group}Sometimes several windows collectively and -cooperatively display a buffer, for example, under the management of -Follow Mode (@pxref{Follow Mode,,, emacs}), where the windows together -display a bigger portion of the buffer than one window could alone. -It is often useful to consider such a @dfn{window group} as a single -entity. Several functions such as @code{window-group-start} -(@pxref{Window Start and End}) allow you to do this by supplying, as -an argument, one of the windows as a stand in for the whole group. +@end group +@end smallexample -@defun selected-window-group -@vindex selected-window-group-function -When the selected window is a member of a group of windows, this -function returns a list of the windows in the group, ordered such that -the first window in the list is displaying the earliest part of the -buffer, and so on. Otherwise the function returns a list containing -just the selected window. +@cindex window body +@cindex body of a window +@cindex window decorations +@cindex left and right window decorations +@cindex top and bottom window decorations + At the center of that window is the @dfn{body}, where the buffer +text is displayed. The body can be surrounded by a series of optional +areas which we will call @dfn{window decorations}. On the left and +right, from innermost to outermost, these are the left and right +fringes, denoted by LF and RF (@pxref{Fringes}); the left and right +margins, denoted by LM and RM in the schematic (@pxref{Display +Margins}); the left or right vertical scroll bar, only one of which is +present at any time, denoted by LS and RS (@pxref{Scroll Bars}); and +the right divider, denoted by RD (@pxref{Window Dividers}). Together +these are the window's @dfn{left and right decorations}. + +@cindex text area of a window + At the top of the window are the tab line and the header line +(@pxref{Header Lines}). The @dfn{text area} of the window includes +the header line and the tab line, if they are present in the window. +At the bottom of the window are the horizontal scroll bar +(@pxref{Scroll Bars}); the mode line (@pxref{Mode Line Format}); and +the bottom divider (@pxref{Window Dividers}). Together these form the +window's @dfn{top and bottom decorations}. + + There are two special areas omitted in the schematic: + +@itemize @bullet +@item +When any of the fringes is missing, the display engine may use one +character cell in its place for showing a continuation or truncation +glyph provided a text line doesn't fit in a window. + +@item +When both, the vertical scroll bar and the right divider are missing, +the display engine usurps one pixel for drawing a vertical divider line +between this window and the window on its right, provided such a window +exists. On a text terminal, this divider always occupies an entire +character cell. +@end itemize + +In either case, the resulting artifact is considered part of the +window's body although its screen space cannot be used for displaying +buffer text. + + Note also, that line numbers (and their surrounding whitespace) as +displayed by @code{display-line-numbers-mode} (@pxref{Display Custom,,, +emacs, The GNU Emacs Manual}) do not count as decorations either; they +are part of the window's body too. + + Internal windows neither show any text nor do they have decorations. +Hence, the concept of ``body'' does not make sense for them. In fact, +most functions operating on the body of a window will yield an error +when applied to an internal window. + +@cindex minibuffer window +@cindex tooltip window + By default, an Emacs frame exhibits one special live window that is +used for displaying messages and accepting user input---the +@dfn{minibuffer window} (@pxref{Minibuffer Windows}). Since the +minibuffer window is used for displaying text, it has a body but it does +not have a tab or header line or any margins. Finally, a @dfn{tooltip +window} which is used for displaying a tooltip in a tooltip frame +(@pxref{Tooltips}) has a body too but no decorations at all. -The selected window is considered part of a group when the buffer -local variable @code{selected-window-group-function} is set to a -function. In this case, @code{selected-window-group} calls it with no -arguments and returns its result (which should be the list of windows -in the group). -@end defun @node Windows and Frames @section Windows and Frames -Each window belongs to exactly one frame (@pxref{Frames}). +Each window belongs to exactly one frame (@pxref{Frames}). For all +windows belonging to a specific frame, we sometimes also say that these +windows are @dfn{owned} by that frame or simply that they are on that +frame. @defun window-frame &optional window -This function returns the frame that the window @var{window} belongs -to. If @var{window} is @code{nil}, it defaults to the selected -window. +This function returns the specified @var{window}'s frame---the frame +that @var{window} belongs to. If @var{window} is omitted or @code{nil}, +it defaults to the selected window (@pxref{Selecting Windows}). @end defun @defun window-list &optional frame minibuffer window -This function returns a list of live windows belonging to the frame +This function returns a list of all live windows owned by the specified @var{frame}. If @var{frame} is omitted or @code{nil}, it defaults to -the selected frame. +the selected frame (@pxref{Input Focus}). -The optional argument @var{minibuffer} specifies whether to include -the minibuffer window in the returned list. If @var{minibuffer} is -@code{t}, the minibuffer window is included. If @var{minibuffer} is +The optional argument @var{minibuffer} specifies whether to include the +minibuffer window (@pxref{Minibuffer Windows}) in that list. If +@var{minibuffer} is @code{t}, the minibuffer window is included. If @code{nil} or omitted, the minibuffer window is included only if it is active. If @var{minibuffer} is neither @code{nil} nor @code{t}, the minibuffer window is never included. -The optional argument @var{window}, if non-@code{nil}, should be a live +The optional argument @var{window}, if non-@code{nil}, must be a live window on the specified frame; then @var{window} will be the first element in the returned list. If @var{window} is omitted or @code{nil}, -the window selected within the frame is the first element. +the window selected within @var{frame} (@pxref{Selecting Windows}) is +the first element. @end defun @cindex window tree @cindex root window - Windows in the same frame are organized into a @dfn{window tree}, + Windows on the same frame are organized into a @dfn{window tree}, whose leaf nodes are the live windows. The internal nodes of a window tree are not live; they exist for the purpose of organizing the relationships between live windows. The root node of a window tree is -called the @dfn{root window}. It can be either a live window (if the -frame has just one window), or an internal window. - - A minibuffer window (@pxref{Minibuffer Windows}) that is not alone -on its frame does not have a parent window, so it strictly speaking is -not part of its frame's window tree. Nonetheless, it is a sibling -window of the frame's root window, and thus can be reached via -@code{window-next-sibling}. Also, the function @code{window-tree} -described at the end of this section lists the minibuffer window -alongside the actual window tree. +called the @dfn{root window}. It is either a live window or an +internal window. If it is a live window, then the frame has just one +window besides the minibuffer window, or the frame is a +minibuffer-only frame, @pxref{Frame Layout}. + + A minibuffer window (@pxref{Minibuffer Windows}) that is not alone on +its frame does not have a parent window, so it strictly speaking is not +part of its frame's window tree. Nonetheless, it is a sibling window of +the frame's root window, and thus can be reached from the root window via +@code{window-next-sibling}, see below. Also, the function +@code{window-tree} described at the end of this section lists the +minibuffer window alongside the actual window tree. @defun frame-root-window &optional frame-or-window This function returns the root window for @var{frame-or-window}. The @@ -217,15 +273,15 @@ of that window's frame. @cindex parent window @cindex child window @cindex sibling window - When a window is split, there are two live windows where previously -there was one. One of these is represented by the same Lisp window -object as the original window, and the other is represented by a -newly-created Lisp window object. Both of these live windows become -leaf nodes of the window tree, as @dfn{child windows} of a single -internal window. If necessary, Emacs automatically creates this -internal window, which is also called the @dfn{parent window}, and -assigns it to the appropriate position in the window tree. A set of -windows that share the same parent are called @dfn{siblings}. + When a live window is split (@pxref{Splitting Windows}), there are two +live windows where previously there was one. One of these is +represented by the same Lisp window object as the original window, and +the other is represented by a newly-created Lisp window object. Both of +these live windows become leaf nodes of the window tree, as @dfn{child +windows} of a single internal window. If necessary, Emacs automatically +creates this internal window, which is also called the @dfn{parent +window}, and assigns it to the appropriate position in the window tree. +The set of windows that share the same parent are called @dfn{siblings}. @cindex parent window @defun window-parent &optional window @@ -235,16 +291,16 @@ window. The return value is @code{nil} if @var{window} has no parent (i.e., it is a minibuffer window or the root window of its frame). @end defun - Each internal window always has at least two child windows. If this -number falls to one as a result of window deletion, Emacs -automatically deletes the internal window, and its sole remaining -child window takes its place in the window tree. + A parent window always has at least two child windows. If this number +were to fall to one as a result of window deletion (@pxref{Deleting +Windows}), Emacs automatically deletes the parent window too, and its +sole remaining child window takes its place in the window tree. - Each child window can be either a live window, or an internal window + A child window can be either a live window, or an internal window (which in turn would have its own child windows). Therefore, each internal window can be thought of as occupying a certain rectangular -@dfn{screen area}---the union of the areas occupied by the live -windows that are ultimately descended from it. +@dfn{screen area}---the union of the areas occupied by the live windows +that are ultimately descended from it. @cindex window combination @cindex vertical combination @@ -284,7 +340,9 @@ windows @var{W4} and @var{W5}. Hence, the live windows in this window tree are @var{W2}, @var{W4}, and @var{W5}. The following functions can be used to retrieve a child window of an -internal window, and the siblings of a child window. +internal window, and the siblings of a child window. Their @var{window} +argument always defaults to the selected window (@pxref{Selecting +Windows}). @defun window-top-child &optional window This function returns the topmost child window of @var{window}, if @@ -309,8 +367,7 @@ the leftmost child window for a horizontal combination. If @defun window-combined-p &optional window horizontal This function returns a non-@code{nil} value if and only if -@var{window} is part of a vertical combination. If @var{window} is -omitted or @code{nil}, it defaults to the selected one. +@var{window} is part of a vertical combination. If the optional argument @var{horizontal} is non-@code{nil}, this means to return non-@code{nil} if and only if @var{window} is part of @@ -318,24 +375,21 @@ a horizontal combination. @end defun @defun window-next-sibling &optional window -This function returns the next sibling of the window @var{window}. If -omitted or @code{nil}, @var{window} defaults to the selected window. -The return value is @code{nil} if @var{window} is the last child of -its parent. +This function returns the next sibling of the specified @var{window}. The +return value is @code{nil} if @var{window} is the last child of its +parent. @end defun @defun window-prev-sibling &optional window -This function returns the previous sibling of the window @var{window}. -If omitted or @code{nil}, @var{window} defaults to the selected -window. The return value is @code{nil} if @var{window} is the first -child of its parent. +This function returns the previous sibling of the specified @var{window}. +The return value is @code{nil} if @var{window} is the first child of its +parent. @end defun -The functions @code{window-next-sibling} and -@code{window-prev-sibling} should not be confused with the functions -@code{next-window} and @code{previous-window}, which return the next -and previous window, respectively, in the cyclic ordering of windows -(@pxref{Cyclic Window Ordering}). +The functions @code{window-next-sibling} and @code{window-prev-sibling} +should not be confused with the functions @code{next-window} and +@code{previous-window}, which return the next and previous window in the +cyclic ordering of windows (@pxref{Cyclic Window Ordering}). The following functions can be useful to locate a window within its frame. @@ -408,8 +462,7 @@ Don't use this function to check whether there is @emph{no} window in much more efficient way to do that. @end defun -The following function allows the entire window tree of a frame to be -retrieved: +The following function retrieves the entire window tree of a frame: @defun window-tree &optional frame This function returns a list representing the window tree for frame @@ -433,54 +486,218 @@ internal window). The @var{edges} element is a list @code{(@var{left} @end defun +@node Selecting Windows +@section Selecting Windows +@cindex selecting a window + +@cindex selected window +@cindex window selected within a frame + In each frame, at any time, exactly one Emacs window is designated +as @dfn{selected within the frame}. For the selected frame, that +window is called the @dfn{selected window}---the one in which most +editing takes place, and in which the cursor for selected windows +appears (@pxref{Cursor Parameters}). Keyboard input that inserts or +deletes text is also normally directed to this window. The selected +window's buffer is usually also the current buffer, except when +@code{set-buffer} has been used (@pxref{Current Buffer}). As for +non-selected frames, the window selected within the frame becomes the +selected window if the frame is ever selected. + +@defun selected-window +This function returns the selected window (which is always a live +window). +@end defun + +The following function explicitly selects a window and its frame. + +@defun select-window window &optional norecord +This function makes @var{window} the selected window and the window +selected within its frame, and selects that frame. It also makes +@var{window}'s buffer (@pxref{Buffers and Windows}) current and sets +that buffer's value of @code{point} to the value of @code{window-point} +(@pxref{Window Point}) in @var{window}. @var{window} must be a live +window. The return value is @var{window}. + +By default, this function also moves @var{window}'s buffer to the front +of the buffer list (@pxref{Buffer List}) and makes @var{window} the most +recently selected window. If the optional argument @var{norecord} is +non-@code{nil}, these additional actions are omitted. + +In addition, this function by default also tells the display engine to +update the display of @var{window} when its frame gets redisplayed the +next time. If @var{norecord} is non-@code{nil}, such updates are +usually not performed. If, however, @var{norecord} equals the special +symbol @code{mark-for-redisplay}, the additional actions mentioned above +are omitted but @var{window}'s display will be nevertheless updated. + +Note that sometimes selecting a window is not enough to show it, or +make its frame the top-most frame on display: you may also need to +raise the frame or make sure input focus is directed to that frame. +@xref{Input Focus}. +@end defun + +@cindex select window hooks +@cindex running a hook when a window gets selected +For historical reasons, Emacs does not run a separate hook whenever a +window gets selected. Applications and internal routines often +temporarily select a window to perform a few actions on it. They do +that either to simplify coding---because many functions by default +operate on the selected window when no @var{window} argument is +specified---or because some functions did not (and still do not) take a +window as argument and always operate(d) on the selected window instead. +Running a hook every time a window gets selected for a short time and +once more when the previously selected window gets restored is not +useful. + + However, when its @var{norecord} argument is @code{nil}, +@code{select-window} updates the buffer list and thus indirectly runs +the normal hook @code{buffer-list-update-hook} (@pxref{Buffer List}). +Consequently, that hook provides one way to run a function whenever a +window gets selected more ``permanently''. + + Since @code{buffer-list-update-hook} is also run by functions that are +not related to window management, it will usually make sense to save the +value of the selected window somewhere and compare it with the value of +@code{selected-window} while running that hook. Also, to avoid false +positives when using @code{buffer-list-update-hook}, it is good practice +that every @code{select-window} call supposed to select a window only +temporarily passes a non-@code{nil} @var{norecord} argument. If +possible, the macro @code{with-selected-window} (see below) should be +used in such cases. + + Emacs also runs the hook @code{window-selection-change-functions} +whenever the redisplay routine detects that another window has been +selected since last redisplay. @xref{Window Hooks}, for a detailed +explanation. @code{window-state-change-functions} (described in the +same section) is another abnormal hook run after a different window +has been selected but is triggered by other window changes as well. + +@cindex most recently selected windows + The sequence of calls to @code{select-window} with a non-@code{nil} +@var{norecord} argument determines an ordering of windows by their +selection or use time, see below. The function @code{get-lru-window}, +for example, can then be used to retrieve the least recently selected +window (@pxref{Cyclic Window Ordering}). + +@defun frame-selected-window &optional frame +This function returns the window on @var{frame} that is selected +within that frame. @var{frame} should be a live frame; if omitted or +@code{nil}, it defaults to the selected frame. +@end defun + +@defun set-frame-selected-window frame window &optional norecord +This function makes @var{window} the window selected within the frame +@var{frame}. @var{frame} should be a live frame; if @code{nil}, it +defaults to the selected frame. @var{window} should be a live window; +if @code{nil}, it defaults to the selected window. + +If @var{frame} is the selected frame, this makes @var{window} the +selected window. + +If the optional argument @var{norecord} is non-@code{nil}, this function +does not alter the ordering of the most recently selected windows, nor +the buffer list. +@end defun + + The following macros are useful to temporarily select a window without +affecting the ordering of recently selected windows or the buffer list. + +@defmac save-selected-window forms@dots{} +This macro records the selected frame, as well as the selected window +of each frame, executes @var{forms} in sequence, then restores the +earlier selected frame and windows. It also saves and restores the +current buffer. It returns the value of the last form in @var{forms}. + +This macro does not save or restore anything about the sizes, +arrangement or contents of windows; therefore, if @var{forms} change +them, the change persists. If the previously selected window of some +frame is no longer live at the time of exit from @var{forms}, that +frame's selected window is left alone. If the previously selected +window is no longer live, then whatever window is selected at the end of +@var{forms} remains selected. The current buffer is restored if and +only if it is still live when exiting @var{forms}. + +This macro changes neither the ordering of recently selected windows nor +the buffer list. +@end defmac + +@defmac with-selected-window window forms@dots{} +This macro selects @var{window}, executes @var{forms} in sequence, then +restores the previously selected window and current buffer. The +ordering of recently selected windows and the buffer list remain +unchanged unless you deliberately change them within @var{forms}; for +example, by calling @code{select-window} with argument @var{norecord} +@code{nil}. Hence, this macro is the preferred way to temporarily work +with @var{window} as the selected window without needlessly running +@code{buffer-list-update-hook}. +@end defmac + +@defmac with-selected-frame frame forms@dots{} +This macro executes @var{forms} with @var{frame} as the selected +frame. The value returned is the value of the last form in +@var{forms}. This macro saves and restores the selected frame, and +changes the order of neither the recently selected windows nor the +buffers in the buffer list. +@end defmac + +@cindex window use time +@cindex use time of window +@cindex window order by time of last use +@defun window-use-time &optional window +This function returns the use time of window @var{window}. @var{window} +must be a live window and defaults to the selected one. + +The @dfn{use time} of a window is not really a time value, but an +integer that does increase monotonically with each call of +@code{select-window} with a @code{nil} @var{norecord} argument. The +window with the lowest use time is usually called the least recently +used window while the window with the highest use time is called the +most recently used one (@pxref{Cyclic Window Ordering}). +@end defun + +@defun window-bump-use-time &optional window +This function marks @var{window} as being the most recently used +one. This can be useful when writing certain @code{pop-to-buffer} +scenarios (@pxref{Switching Buffers}). @var{window} must be a live +window and defaults to the selected one. +@end defun + +@anchor{Window Group}Sometimes several windows collectively and +cooperatively display a buffer, for example, under the management of +Follow Mode (@pxref{Follow Mode,,, emacs}), where the windows together +display a bigger portion of the buffer than one window could alone. +It is often useful to consider such a @dfn{window group} as a single +entity. Several functions such as @code{window-group-start} +(@pxref{Window Start and End}) allow you to do this by supplying, as +an argument, one of the windows as a stand-in for the whole group. + +@defun selected-window-group +@vindex selected-window-group-function +When the selected window is a member of a group of windows, this +function returns a list of the windows in the group, ordered such that +the first window in the list is displaying the earliest part of the +buffer, and so on. Otherwise the function returns a list containing +just the selected window. + +The selected window is considered part of a group when the buffer +local variable @code{selected-window-group-function} is set to a +function. In this case, @code{selected-window-group} calls it with no +arguments and returns its result (which should be the list of windows +in the group). +@end defun + + @node Window Sizes @section Window Sizes @cindex window size @cindex size of window - The following schematic shows the structure of a live window: - -@smallexample -@group - ____________________________________________ - |______________ Header Line ______________|RD| ^ - ^ |LS|LM|LF| |RF|RM|RS| | | - | | | | | | | | | | | -Window | | | | Text Area | | | | | Window -Body | | | | | (Window Body) | | | | | Total -Height | | | | | | | | | Height - | | | | |<- Window Body Width ->| | | | | | - v |__|__|__|_______________________|__|__|__| | | - |_________ Horizontal Scroll Bar _________| | | - |_______________ Mode Line _______________|__| | - |_____________ Bottom Divider _______________| v - <---------- Window Total Width ------------> - -@end group -@end smallexample - -@cindex window body -@cindex text area of a window -@cindex body of a window - At the center of the window is the @dfn{text area}, or @dfn{body}, -where the buffer text is displayed. The text area can be surrounded by -a series of optional areas. On the left and right, from innermost to -outermost, these are the left and right fringes, denoted by LF and RF -(@pxref{Fringes}); the left and right margins, denoted by LM and RM in -the schematic (@pxref{Display Margins}); the left or right vertical -scroll bar, only one of which is present at any time, denoted by LS and -RS (@pxref{Scroll Bars}); and the right divider, denoted by RD -(@pxref{Window Dividers}). At the top of the window is the header line -(@pxref{Header Lines}). At the bottom of the window are the horizontal -scroll bar (@pxref{Scroll Bars}); the mode line (@pxref{Mode Line -Format}); and the bottom divider (@pxref{Window Dividers}). - - Emacs provides miscellaneous functions for finding the height and -width of a window. The return value of many of these functions can be +Emacs provides miscellaneous functions for finding the height and width +of a window. The return value of many of these functions can be specified either in units of pixels or in units of lines and columns. On a graphical display, the latter actually correspond to the height and -width of a default character specified by the frame's default font -as returned by @code{frame-char-height} and @code{frame-char-width} +width of a default character specified by the frame's default font as +returned by @code{frame-char-height} and @code{frame-char-width} (@pxref{Frame Font}). Thus, if a window is displaying text with a different font or size, the reported line height and column width for that window may differ from the actual number of text lines or columns @@ -490,8 +707,7 @@ displayed within it. @cindex height of a window @cindex total height of a window The @dfn{total height} of a window is the number of lines comprising -the window's body, the header line, the horizontal scroll bar, the mode -line and the bottom divider (if any). +its body and its top and bottom decorations (@pxref{Basic Windows}). @defun window-total-height &optional window round This function returns the total height, in lines, of the window @@ -521,9 +737,8 @@ with any other @var{round} it returns the internal value of @cindex window width @cindex width of a window @cindex total width of a window -The @dfn{total width} of a window is the number of lines comprising the -window's body, its margins, fringes, scroll bars and a right divider (if -any). +The @dfn{total width} of a window is the number of lines comprising its +body and its left and right decorations (@pxref{Basic Windows}). @defun window-total-width &optional window round This function returns the total width, in columns, of the window @@ -564,10 +779,9 @@ window in units of pixels. This function returns the total height of window @var{window} in pixels. @var{window} must be a valid window and defaults to the selected one. -The return value includes mode and header line, a horizontal scroll bar -and a bottom divider, if any. If @var{window} is an internal window, -its pixel height is the pixel height of the screen areas spanned by its -children. +The return value includes the heights of @var{window}'s top and bottom +decorations. If @var{window} is an internal window, its pixel height is +the pixel height of the screen areas spanned by its children. @end defun @cindex window pixel width @@ -578,10 +792,9 @@ children. This function returns the width of window @var{window} in pixels. @var{window} must be a valid window and defaults to the selected one. -The return value includes the fringes and margins of @var{window} as -well as any vertical dividers or scroll bars belonging to @var{window}. -If @var{window} is an internal window, its pixel width is the width of -the screen areas spanned by its children. +The return value includes the widths of @var{window}'s left and right +decorations. If @var{window} is an internal window, its pixel width is +the width of the screen areas spanned by its children. @end defun @cindex full-width window @@ -607,9 +820,9 @@ that of the root window on that frame. If @var{window} is omitted or @cindex window body height @cindex body height of a window -The @dfn{body height} of a window is the height of its text area, which -does not include a mode or header line, a horizontal scroll bar, or a -bottom divider. +The @dfn{body height} of a window is the height of its body, which +does not include any of its top or bottom decorations (@pxref{Basic +Windows}). @defun window-body-height &optional window pixelwise This function returns the height, in lines, of the body of window @@ -628,8 +841,10 @@ exceed its total height as returned by @code{window-total-height}. @cindex window body width @cindex body width of a window -The @dfn{body width} of a window is the width of its text area, which -does not include the scroll bar, fringes, margins or a right divider. +The @dfn{body width} of a window is the width of its body and of the +text area, which does not include any of its left or right decorations +(@pxref{Basic Windows}). + Note that when one or both fringes are removed (by setting their width to zero), the display engine reserves two character cells, one on each side of the window, for displaying the continuation and truncation @@ -662,16 +877,11 @@ to calling @code{window-body-width}. In either case, the optional argument @var{pixelwise} is passed to the function called. @end defun -For compatibility with previous versions of Emacs, -@code{window-height} is an alias for @code{window-total-height}, and -@code{window-width} is an alias for @code{window-body-width}. These -aliases are considered obsolete and will be removed in the future. - - The pixel heights of a window's mode and header line can be retrieved -with the functions given below. Their return value is usually accurate -unless the window has not been displayed before: In that case, the -return value is based on an estimate of the font used for the window's -frame. + The pixel heights of a window's mode, tab and header line can be +retrieved with the functions given below. Their return value is usually +accurate unless the window has not been displayed before: In that case, +the return value is based on an estimate of the font used for the +window's frame. @defun window-mode-line-height &optional window This function returns the height in pixels of @var{window}'s mode line. @@ -679,6 +889,12 @@ This function returns the height in pixels of @var{window}'s mode line. @var{window} has no mode line, the return value is zero. @end defun +@defun window-tab-line-height &optional window +This function returns the height in pixels of @var{window}'s tab line. +@var{window} must be a live window and defaults to the selected one. If +@var{window} has no tab line, the return value is zero. +@end defun + @defun window-header-line-height &optional window This function returns the height in pixels of @var{window}'s header line. @var{window} must be a live window and defaults to the selected @@ -720,15 +936,14 @@ size (@pxref{Preserving Window Sizes}). @defopt window-min-height This option specifies the minimum total height, in lines, of any window. -Its value has to accommodate at least one text line as well as a mode -and header line, a horizontal scroll bar and a bottom divider, if -present. +Its value has to accommodate at least one text line and any top or +bottom decorations. @end defopt @defopt window-min-width This option specifies the minimum total width, in columns, of any -window. Its value has to accommodate two text columns as well as -margins, fringes, a scroll bar and a right divider, if present. +window. Its value has to accommodate at least two text columns and any +left or right decorations. @end defopt The following function tells how small a specific window can get taking @@ -745,10 +960,9 @@ of @var{window}'s lines. The return value makes sure that all components of @var{window} remain fully visible if @var{window}'s size were actually set to it. With -@var{horizontal} @code{nil} it includes the mode and header line, the -horizontal scroll bar and the bottom divider, if present. With -@var{horizontal} non-@code{nil} it includes the margins and fringes, the -vertical scroll bar and the right divider, if present. +@var{horizontal} @code{nil} it includes any top or bottom decorations. +With @var{horizontal} non-@code{nil} it includes any left or right +decorations of @var{window}. The optional argument @var{ignore}, if non-@code{nil}, means ignore restrictions imposed by fixed size windows, @code{window-min-height} or @@ -770,10 +984,10 @@ minimum size of @var{window} counted in pixels. @cindex changing window size @cindex window size, changing - This section describes functions for resizing a window without -changing the size of its frame. Because live windows do not overlap, -these functions are meaningful only on frames that contain two or more -windows: resizing a window also changes the size of a neighboring +This section describes functions for resizing a window without changing +the size of its frame. Because live windows do not overlap, these +functions are meaningful only on frames that contain two or more +windows: resizing a window also changes the size of at least one other window. If there is just one window on a frame, its size cannot be changed except by resizing the frame (@pxref{Frame Size}). @@ -801,11 +1015,10 @@ Normally, the variables @code{window-min-height} and (@pxref{Window Sizes}). However, if the optional argument @var{ignore} is non-@code{nil}, this function ignores @code{window-min-height} and @code{window-min-width}, as well as @code{window-size-fixed}. Instead, -it considers the minimum-height window to be one consisting of a header -and a mode line, a horizontal scrollbar and a bottom divider (if any), -plus a text area one line tall; and a minimum-width window as one -consisting of fringes, margins, a scroll bar and a right divider (if -any), plus a text area two columns wide. +it considers the minimum height of a window as the sum of its top and +bottom decorations plus the text of one line; and its minimum width +as the sum of its left and right decorations plus text that takes two +columns. If the optional argument @var{pixelwise} is non-@code{nil}, @var{delta} is interpreted as pixels. @@ -889,7 +1102,7 @@ that this function can give @var{window}. The optional argument @var{min-height}, if non-@code{nil}, specifies the minimum total height that it can give, which overrides the variable @code{window-min-height}. Both @var{max-height} and @var{min-height} are specified in lines and -include mode and header line and a bottom divider, if any. +include any top or bottom decorations of @var{window}. If @var{window} is part of a horizontal combination and the value of the option @code{fit-window-to-buffer-horizontally} (see below) is @@ -900,8 +1113,8 @@ The optional argument @var{max-width} specifies a maximum width and defaults to the width of @var{window}'s frame. The optional argument @var{min-width} specifies a minimum width and defaults to @code{window-min-width}. Both @var{max-width} and @var{min-width} are -specified in columns and include fringes, margins and scrollbars, if -any. +specified in columns and include any left or right decorations of +@var{window}. The optional argument @var{preserve-size}, if non-@code{nil}, will install a parameter to preserve the size of @var{window} during future @@ -1144,19 +1357,18 @@ Sizes}). Thus, it signals an error if splitting would result in making a window smaller than those variables specify. However, a non-@code{nil} value for @var{size} causes those variables to be ignored; in that case, the smallest allowable window is considered to be -one that has space for a text area one line tall and/or two columns +one that has space for a text that is one line tall and/or two columns wide. Hence, if @var{size} is specified, it's the caller's responsibility to -check whether the emanating windows are large enough to encompass all -areas like a mode line or a scroll bar. The function +check whether the emanating windows are large enough to encompass all of +their decorations like a mode line or a scroll bar. The function @code{window-min-size} (@pxref{Window Sizes}) can be used to determine the minimum requirements of @var{window} in this regard. Since the new -window usually inherits areas like the mode line or the scroll bar -from @var{window}, that function is also a good guess for the minimum -size of the new window. The caller should specify a smaller size only -if it correspondingly removes an inherited area before the next -redisplay. +window usually inherits areas like the mode line or the scroll bar from +@var{window}, that function is also a good guess for the minimum size of +the new window. The caller should specify a smaller size only if it +correspondingly removes an inherited area before the next redisplay. The optional third argument @var{side} determines the position of the new window relative to @var{window}. If it is @code{nil} or @@ -1762,153 +1974,6 @@ distribute its space proportionally among the two remaining live windows. -@node Selecting Windows -@section Selecting Windows -@cindex selecting a window - -@defun select-window window &optional norecord -This function makes @var{window} the selected window and the window -selected within its frame (@pxref{Basic Windows}), and selects that -frame. It also makes @var{window}'s buffer (@pxref{Buffers and -Windows}) current and sets that buffer's value of @code{point} to the -value of @code{window-point} (@pxref{Window Point}) in @var{window}. -@var{window} must be a live window. The return value is @var{window}. - -By default, this function also moves @var{window}'s buffer to the front -of the buffer list (@pxref{Buffer List}) and makes @var{window} the most -recently selected window. If the optional argument @var{norecord} is -non-@code{nil}, these additional actions are omitted. - -In addition, this function by default also tells the display engine to -update the display of @var{window} when its frame gets redisplayed the -next time. If @var{norecord} is non-@code{nil}, such updates are -usually not performed. If, however, @var{norecord} equals the special -symbol @code{mark-for-redisplay}, the additional actions mentioned above -are omitted but @var{window} will be nevertheless updated. - -Note that sometimes selecting a window is not enough to show it, or -make its frame the top-most frame on display: you may also need to -raise the frame or make sure input focus is directed to that frame. -@xref{Input Focus}. -@end defun - -@cindex select window hooks -@cindex running a hook when a window gets selected -For historical reasons, Emacs does not run a separate hook whenever a -window gets selected. Applications and internal routines often -temporarily select a window to perform a few actions on it. They do -that either to simplify coding---because many functions by default -operate on the selected window when no @var{window} argument is -specified---or because some functions did not (and still do not) take a -window as argument and always operate(d) on the selected window instead. -Running a hook every time a window gets selected for a short time and -once more when the previously selected window gets restored is not -useful. - - However, when its @var{norecord} argument is @code{nil}, -@code{select-window} updates the buffer list and thus indirectly runs -the normal hook @code{buffer-list-update-hook} (@pxref{Buffer List}). -Consequently, that hook provides one way to run a function whenever a -window gets selected more ``permanently''. - - Since @code{buffer-list-update-hook} is also run by functions that are -not related to window management, it will usually make sense to save the -value of the selected window somewhere and compare it with the value of -@code{selected-window} while running that hook. Also, to avoid false -positives when using @code{buffer-list-update-hook}, it is good practice -that every @code{select-window} call supposed to select a window only -temporarily passes a non-@code{nil} @var{norecord} argument. If -possible, the macro @code{with-selected-window} (see below) should be -used in such cases. - - Emacs also runs the hook @code{window-selection-change-functions} -whenever the redisplay routine detects that another window has been -selected since last redisplay. @xref{Window Hooks}, for a detailed -explanation. @code{window-state-change-functions} (described in the -same section) is another abnormal hook run after a different window -has been selected but is triggered by other window changes as well. - -@cindex most recently selected windows - The sequence of calls to @code{select-window} with a non-@code{nil} -@var{norecord} argument determines an ordering of windows by their -selection time. The function @code{get-lru-window} can be used to -retrieve the least recently selected live window (@pxref{Cyclic Window -Ordering}). - -@defmac save-selected-window forms@dots{} -This macro records the selected frame, as well as the selected window -of each frame, executes @var{forms} in sequence, then restores the -earlier selected frame and windows. It also saves and restores the -current buffer. It returns the value of the last form in @var{forms}. - -This macro does not save or restore anything about the sizes, -arrangement or contents of windows; therefore, if @var{forms} change -them, the change persists. If the previously selected window of some -frame is no longer live at the time of exit from @var{forms}, that -frame's selected window is left alone. If the previously selected -window is no longer live, then whatever window is selected at the end of -@var{forms} remains selected. The current buffer is restored if and -only if it is still live when exiting @var{forms}. - -This macro changes neither the ordering of recently selected windows nor -the buffer list. -@end defmac - -@defmac with-selected-window window forms@dots{} -This macro selects @var{window}, executes @var{forms} in sequence, then -restores the previously selected window and current buffer. The -ordering of recently selected windows and the buffer list remain -unchanged unless you deliberately change them within @var{forms}; for -example, by calling @code{select-window} with argument @var{norecord} -@code{nil}. Hence, this macro is the preferred way to temporarily work -with @var{window} as the selected window without needlessly running -@code{buffer-list-update-hook}. -@end defmac - -@defmac with-selected-frame frame forms@dots{} -This macro executes @var{forms} with @var{frame} as the selected -frame. The value returned is the value of the last form in -@var{forms}. This macro saves and restores the selected frame, and -changes the order of neither the recently selected windows nor the -buffers in the buffer list. -@end defmac - -@defun frame-selected-window &optional frame -This function returns the window on @var{frame} that is selected -within that frame. @var{frame} should be a live frame; if omitted or -@code{nil}, it defaults to the selected frame. -@end defun - -@defun set-frame-selected-window frame window &optional norecord -This function makes @var{window} the window selected within the frame -@var{frame}. @var{frame} should be a live frame; if @code{nil}, it -defaults to the selected frame. @var{window} should be a live window; -if @code{nil}, it defaults to the selected window. - -If @var{frame} is the selected frame, this makes @var{window} the -selected window. - -If the optional argument @var{norecord} is non-@code{nil}, this -function does not alter the list of most recently selected windows, -nor the buffer list. -@end defun - -@cindex window use time -@cindex use time of window -@cindex window order by time of last use -@defun window-use-time &optional window -This functions returns the use time of window @var{window}. -@var{window} must be a live window and defaults to the selected one. - -The @dfn{use time} of a window is not really a time value, but an -integer that does increase monotonically with each call of -@code{select-window} with a @code{nil} @var{norecord} argument. The -window with the lowest use time is usually called the least recently -used window while the window with the highest use time is called the -most recently used one (@pxref{Cyclic Window Ordering}). -@end defun - - @node Cyclic Window Ordering @section Cyclic Ordering of Windows @cindex cyclic ordering of windows @@ -2036,8 +2101,11 @@ criterion, without selecting it: @cindex least recently used window @defun get-lru-window &optional all-frames dedicated not-selected no-other This function returns a live window which is heuristically the least -recently used. The optional argument @var{all-frames} has -the same meaning as in @code{next-window}. +recently used one. The @dfn{least recently used window} is the least +recently selected one---the window whose use time is less than the use +time of all other live windows (@pxref{Selecting Windows}). The +optional argument @var{all-frames} has the same meaning as in +@code{next-window}. If any full-width windows are present, only those windows are considered. A minibuffer window is never a candidate. A dedicated @@ -2053,8 +2121,14 @@ function returns @code{nil} in that case. The optional argument @cindex most recently used window @defun get-mru-window &optional all-frames dedicated not-selected no-other This function is like @code{get-lru-window}, but it returns the most -recently used window instead. The meaning of the arguments is the -same as for @code{get-lru-window}. +recently used window instead. The @dfn{most recently used window} is +the most recently selected one---the window whose use time exceeds the +use time of all other live windows (@pxref{Selecting Windows}). The +meaning of the arguments is the same as for @code{get-lru-window}. + +Since in practice the most recently used window is always the selected +one, it usually makes sense to call this function with a non-@code{nil} +@var{not-selected} argument only. @end defun @cindex largest window @@ -2919,9 +2993,9 @@ A non-@code{nil} value prevents another frame from being raised or selected, if the window chosen by @code{display-buffer} is displayed there. Primarily affected by this are @code{display-buffer-use-some-frame} and -@code{display-buffer-reuse-window}. -@code{display-buffer-pop-up-frame} should be affected as well, but -there is no guarantee that the window manager will comply. +@code{display-buffer-reuse-window}. Ideally, +@code{display-buffer-pop-up-frame} should be affected as well, but there +is no guarantee that the window manager will comply. @vindex window-parameters@r{, a buffer display action alist entry} @item window-parameters @@ -2964,11 +3038,16 @@ desired total height with respect to the total height of its frame's root window. @item +A cons cell whose @sc{car} is @code{body-lines} and whose @sc{cdr} is an +integer that specifies the height of the chosen window's body in frame +lines. + +@item If the value specifies a function, that function is called with one argument---the chosen window. The function is supposed to adjust the height of the window; its return value is ignored. Suitable functions -are @code{shrink-window-if-larger-than-buffer} and -@code{fit-window-to-buffer}, see @ref{Resizing Windows}. +are @code{fit-window-to-buffer} and +@code{shrink-window-if-larger-than-buffer}, see @ref{Resizing Windows}. @end itemize By convention, the height of the chosen window is adjusted only if the @@ -2997,16 +3076,47 @@ desired total width with respect to the total width of the frame's root window. @item +A cons cell whose @sc{car} is @code{body-columns} and whose @sc{cdr} is +an integer that specifies the width of the chosen window's body in frame +columns. + +@item If the value specifies a function, that function is called with one argument---the chosen window. The function is supposed to adjust the width of the window; its return value is ignored. @end itemize -By convention, the width of the chosen window is adjusted only if the -window is part of a horizontal combination (@pxref{Windows and -Frames}) to avoid changing the width of other, unrelated windows. -Also, this entry should be processed under only certain conditions -which are specified right below this list. +@vindex window-size@r{, a buffer display action alist entry} +@item window-size +This entry is a combination of the two preceding ones and can be used to +adjust the chosen window's height @emph{and} width. Since windows can +be resized in one direction only without affecting other windows, +@code{window-size} is effective only to set up the size of a window +appearing alone on a frame. The value can be one of the following: + +@itemize @bullet +@item +@code{nil} means to leave the size of the chosen window alone. + +@item +A cons cell of two integers specifies the desired total width and height +of the chosen window in lines and columns. It's effect is to adjust the +size of the frame accordingly. + +@item +A cons cell whose @sc{car} equals @code{body-chars} and whose @sc{cdr} +is a cons cell of two integers---the desired body width and height of +the chosen window in frame columns and lines. It's effect is to adjust +the size of the frame accordingly. + +@item +If the value specifies a function, that function is called with one +argument---the chosen window. The function is supposed to adjust the +size of the window's frame; its return value is ignored. +@end itemize + +This entry should be processed under only certain conditions which are +specified right below this list. @vindex dedicated@r{, a buffer display action alist entry} @item dedicated @@ -3107,6 +3217,14 @@ the window was created earlier by @code{display-buffer} to show the buffer and never was used to show another buffer until it was reused by the current invocation of @code{display-buffer}. +If no @code{window-height}, @code{window-width} or @code{window-size} +entry was specified, the window may still be resized automatically when +the buffer is temporary and @code{temp-buffer-resize-mode} has been +enabled, @ref{Temporary Displays}. In that case, the @sc{cdr} of a +@code{window-height}, @code{window-width} or @code{window-size} entry +can be used to inhibit or override the default behavior of +@code{temp-buffer-resize-mode} for specific buffers or invocations of +@code{display-buffer}. @node Choosing Window Options @subsection Additional Options for Displaying Buffers @@ -5085,7 +5203,7 @@ window. If @var{count} is negative, it scrolls backward instead. If @var{count} is @code{nil} (or omitted), the distance scrolled is @code{next-screen-context-lines} lines less than the height of the -window's text area. +window's body. If the selected window cannot be scrolled any further, this function signals an error. Otherwise, it returns @code{nil}. @@ -5578,16 +5696,15 @@ right of the rightmost column, and the Y coordinate one row down from the bottommost row. Note that these are the actual outer edges of the window, including any -header line, mode line, scroll bar, fringes, window divider and display -margins. On a text terminal, if the window has a neighbor on its right, -its right edge includes the separator line between the window and its -neighbor. +of its decorations. On a text terminal, if the window has a neighbor on +its right, its right edge includes the separator line between the window +and its neighbor. If the optional argument @var{body} is @code{nil}, this means to return the edges corresponding to the total size of @var{window}. @var{body} non-@code{nil} means to return the edges of @var{window}'s -body (aka text area). If @var{body} is non-@code{nil}, @var{window} -must specify a live window. +body. If @var{body} is non-@code{nil}, @var{window} must specify a +live window. If the optional argument @var{absolute} is @code{nil}, this means to return edges relative to the native position of @var{window}'s frame. @@ -5897,12 +6014,11 @@ all other child frames of that frame's parent frame. @cindex saving window information A @dfn{window configuration} records the entire layout of one -frame---all windows, their sizes, which buffers they contain, how those -buffers are scrolled, and their value of point; also their -fringes, margins, and scroll bar settings. It also includes the value -of @code{minibuffer-scroll-window}. As a special exception, the window -configuration does not record the value of point in the selected window -for the current buffer. +frame---all windows, their sizes, their decorations, which buffers they +contain, how those buffers are scrolled, and their value of point, It +also includes the value of @code{minibuffer-scroll-window}. As a +special exception, the window configuration does not record the value of +point in the selected window for the current buffer. You can bring back an entire frame layout by restoring a previously saved window configuration. If you want to record the layout of all diff --git a/doc/man/emacs.1.in b/doc/man/emacs.1.in index 290be604e3b..b2be8bb07b1 100644 --- a/doc/man/emacs.1.in +++ b/doc/man/emacs.1.in @@ -1,5 +1,5 @@ .\" See section COPYING for copyright and redistribution information. -.TH EMACS 1 "2020-04-05" "GNU Emacs @version@" "GNU" +.TH EMACS 1 "2021-09-28" "GNU Emacs @version@" "GNU" . . .SH NAME @@ -215,6 +215,9 @@ Specify the name which should be assigned to the initial window. This controls looking up X resources as well as the window title. .TP +.BR \-\-no\-x\-resources +Do not load X resources. +.TP .BI \-T " name\fR,\fP " \-\-title= "name" Specify the title for the initial X window. .TP diff --git a/doc/man/emacsclient.1 b/doc/man/emacsclient.1 index ba64efa282c..e5d1bbe09ae 100644 --- a/doc/man/emacsclient.1 +++ b/doc/man/emacsclient.1 @@ -1,5 +1,5 @@ .\" See section COPYING for conditions for redistribution. -.TH EMACSCLIENT 1 "2020-10-18" "GNU Emacs" "GNU" +.TH EMACSCLIENT 1 "2021-11-05" "GNU Emacs" "GNU" .\" NAME should be all caps, SECTION should be 1-8, maybe w/ subsection .\" other params are allowed: see man(7), man(1) .SH NAME @@ -69,6 +69,9 @@ start Emacs in daemon mode, and try to connect to it. .B -c, \-\-create-frame Create a new frame instead of trying to use the current Emacs frame. .TP +.B -r \-\-reuse-frame +Reuse an existing frame if one exists, otherwise create a new frame. +.TP .B \-F, \-\-frame-parameters=ALIST Set the parameters of a newly-created frame. .TP diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi index e11267e7a20..c77ccf766f2 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -2865,7 +2865,7 @@ that always equals one. Let's try to verify this identity. @smallexample @group 2: -64 2: -64 2: -64 2: 9.7192e54 2: 9.7192e54 -1: -64 1: -3.1175e27 1: 9.7192e54 1: -64 1: 9.7192e54 +1: -64 1: 3.1175e27 1: 9.7192e54 1: -64 1: 9.7192e54 . . . . . 64 n @key{RET} @key{RET} H C 2 ^ @key{TAB} H S 2 ^ diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index 98ded68e713..a2ff572a3f4 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -283,6 +283,8 @@ Font Locking * Font Locking Preliminaries:: * Faces:: * Doc Comments:: +* Wrong Comment Style:: +* Found Types:: * Misc Font Locking:: * AWK Mode Font Locking:: @@ -1855,6 +1857,7 @@ sections apply to the other languages. * Faces:: * Doc Comments:: * Wrong Comment Style:: +* Found Types:: * Misc Font Locking:: * AWK Mode Font Locking:: @end menu @@ -2162,6 +2165,60 @@ which aren't of the default style will be fontified with @end defvar @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Found Types +@comment node-name, next, previous, up +@section ``Found Type'' handling. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +In most languages handled by CC Mode, @dfn{found types} are recognized +as types by their context in the source code. These contrast with +types which are basic to a language or are declared as types (e.g. by +@code{typedef} in C). + +In earlier versions of @ccmode{}, when @code{jit-lock-mode} was +enabled in Emacs (which it is by default), found types would +frequently fail to get fontified properly. This happened when the +fontification functions scanned a use of the found type before +scanning the code which caused it to be recognized. + +From @ccmode{} version 5.36, a timer mechanism scans the entire buffer +for found types in the seconds immediately after starting the major +mode. When a found type gets recognized, all its occurrences in the +buffer get marked for (re)fontification. This scanning happens in +short time slices interleaved with other processing, such as keyboard +handling, so that the responsiveness of Emacs should be barely +affected. This mechanism can be disabled (see below). It is only +active when @code{jit-lock-mode} is also active. + +@defvar c-type-finder-time-slot +@vindex type-finder-time-slot (c-) +The approximate time in seconds that CC Mode spends in scanning source +code before relinquishing control to other Emacs activities. The +default value is 0.05. To disable the scanning mechanism, set this +variable to @code{nil}. +@end defvar + +@defvar c-type-finder-repeat-time +@vindex type-finder-repeat-time (c-) +The approximate frequency (in seconds) with which the scanning +mechanism is triggered. This time must be greater than +@code{c-type-finder-time-slot}. Its default value is 0.1. If a less +powerful machine becomes sluggish due to the scanning, increase the +value of @code{c-type-finder-repeat-time} to compensate. +@end defvar + +@defvar c-type-finder-chunk-size +@vindex type-finder-chunk-size (c-) +The approximate size (in characters) of the buffer chunk processed as +a unit before the scanning mechanism checks whether +@code{c-type-finder-time-slot} seconds have passed. The default value +is 1000. A too small value here will cause inefficiencies due to the +initialization which happens for each chunk, whereas a too large value +will cause the processing to consume an excessive proportion of the +@code{c-type-finder-repeat-time}. +@end defvar + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Misc Font Locking @comment node-name, next, previous, up @section Miscellaneous Font Locking diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index c89e0e75f85..55b112cb24a 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -1245,6 +1245,12 @@ blocks for other macros like @code{cl-incf}, and @code{cl-pushnew}. The @code{cl-letf} and @code{cl-letf*} macros are used in the processing of symbol macros; @pxref{Macro Bindings}. +@defmac with-memoization @var{place} @var{code}@dots{} +This macro provides a simple way to do memoization. @var{code} is +evaluated and then stashed in @var{place}. If @var{place}'s value is +non-@code{nil}, return that value instead of evaluating @var{code}. +@end defmac + @node Variable Bindings @section Variable Bindings @@ -3364,9 +3370,13 @@ true for all elements. @end defun @defun cl-reduce function seq @t{&key :from-end :start :end :initial-value :key} -This function combines the elements of @var{seq} using an associative -binary operation. Suppose @var{function} is @code{*} and @var{seq} is -the list @code{(2 3 4 5)}. The first two elements of the list are +This function returns the result of calling @var{function} on the +first and second element of @var{seq}, then calling @var{function} +with that result and the third element of @var{seq}, then with that +result and the third element of @var{seq}, etc. + +Here is an example. Suppose @var{function} is @code{*} and @var{seq} +is the list @code{(2 3 4 5)}. The first two elements of the list are combined with @code{(* 2 3) = 6}; this is combined with the next element, @code{(* 6 4) = 24}, and that is combined with the final element: @code{(* 24 5) = 120}. Note that the @code{*} function happens @@ -3962,22 +3972,22 @@ In the simplest case, @var{name} and each of the @var{slots} are symbols. For example, @example -(cl-defstruct person name age sex) +(cl-defstruct person first-name age sex) @end example @noindent -defines a struct type called @code{person} that contains three -slots. Given a @code{person} object @var{p}, you can access those -slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})}, -and @code{(person-sex @var{p})}. You can also change these slots by -using @code{setf} on any of these place forms, for example: +defines a struct type called @code{person} that contains three slots. +Given a @code{person} object @var{p}, you can access those slots by +calling @code{(person-first-name @var{p})}, @code{(person-age +@var{p})}, and @code{(person-sex @var{p})}. You can also change these +slots by using @code{setf} on any of these place forms, for example: @example (cl-incf (person-age birthday-boy)) @end example You can create a new @code{person} by calling @code{make-person}, -which takes keyword arguments @code{:name}, @code{:age}, and +which takes keyword arguments @code{:first-name}, @code{:age}, and @code{:sex} to specify the initial values of these slots in the new object. (Omitting any of these arguments leaves the corresponding slot ``undefined'', according to the Common Lisp standard; in Emacs @@ -3989,7 +3999,7 @@ object of the same type whose slots are @code{eq} to those of @var{p}. Given any Lisp object @var{x}, @code{(person-p @var{x})} returns true if @var{x} is a @code{person}, and false otherwise. -Accessors like @code{person-name} normally check their arguments +Accessors like @code{person-first-name} normally check their arguments (effectively using @code{person-p}) and signal an error if the argument is the wrong type. This check is affected by @code{(optimize (safety @dots{}))} declarations. Safety level 1, @@ -4002,13 +4012,13 @@ always print a descriptive error message for incorrect inputs. @xref{Declarations}. @example -(setq dave (make-person :name "Dave" :sex 'male)) +(setq dave (make-person :first-name "Dave" :sex 'male)) @result{} [cl-struct-person "Dave" nil male] (setq other (copy-person dave)) @result{} [cl-struct-person "Dave" nil male] (eq dave other) @result{} nil -(eq (person-name dave) (person-name other)) +(eq (person-first-name dave) (person-first-name other)) @result{} t (person-p dave) @result{} t @@ -4021,7 +4031,7 @@ always print a descriptive error message for incorrect inputs. @end example In general, @var{name} is either a name symbol or a list of a name -symbol followed by any number of @dfn{struct options}; each @var{slot} +symbol followed by any number of @dfn{structure options}; each @var{slot} is either a slot symbol or a list of the form @samp{(@var{slot-name} @var{default-value} @var{slot-options}@dots{})}. The @var{default-value} is a Lisp form that is evaluated any time an instance of the @@ -4029,7 +4039,7 @@ structure type is created without specifying that slot's value. @example (cl-defstruct person - (name nil :read-only t) + (first-name nil :read-only t) age (sex 'unknown)) @end example @@ -4062,7 +4072,7 @@ enclosed in lists.) (cl-defstruct (person (:constructor create-person) (:type list) :named) - name age sex) + first-name age sex) @end example The following structure options are recognized. @@ -4108,12 +4118,12 @@ option. (person (:constructor nil) ; no default constructor (:constructor new-person - (name sex &optional (age 0))) - (:constructor new-hound (&key (name "Rover") + (first-name sex &optional (age 0))) + (:constructor new-hound (&key (first-name "Rover") (dog-years 0) &aux (age (* 7 dog-years)) (sex 'canine)))) - name age sex) + first-name age sex) @end example The first constructor here takes its arguments positionally rather @@ -4165,16 +4175,16 @@ slot descriptors for slots in the included structure, possibly with modified default values. Borrowing an example from Steele: @example -(cl-defstruct person name (age 0) sex) +(cl-defstruct person first-name (age 0) sex) @result{} person (cl-defstruct (astronaut (:include person (age 45))) helmet-size (favorite-beverage 'tang)) @result{} astronaut -(setq joe (make-person :name "Joe")) +(setq joe (make-person :first-name "Joe")) @result{} [cl-struct-person "Joe" 0 nil] -(setq buzz (make-astronaut :name "Buzz")) +(setq buzz (make-astronaut :first-name "Buzz")) @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang] (list (person-p joe) (person-p buzz)) @@ -4182,17 +4192,17 @@ modified default values. Borrowing an example from Steele: (list (astronaut-p joe) (astronaut-p buzz)) @result{} (nil t) -(person-name buzz) +(person-first-name buzz) @result{} "Buzz" -(astronaut-name joe) - @result{} error: "astronaut-name accessing a non-astronaut" +(astronaut-first-name joe) + @result{} error: "astronaut-first-name accessing a non-astronaut" @end example Thus, if @code{astronaut} is a specialization of @code{person}, then every @code{astronaut} is also a @code{person} (but not the other way around). Every @code{astronaut} includes all the slots of a @code{person}, plus extra slots that are specific to -astronauts. Operations that work on people (like @code{person-name}) +astronauts. Operations that work on people (like @code{person-first-name}) work on astronauts just like other people. @item :noinline @@ -4230,10 +4240,10 @@ records, which are always tagged. Therefore, @code{:named} is only useful in conjunction with @code{:type}. @example -(cl-defstruct (person1) name age sex) -(cl-defstruct (person2 (:type list) :named) name age sex) -(cl-defstruct (person3 (:type list)) name age sex) -(cl-defstruct (person4 (:type vector)) name age sex) +(cl-defstruct (person1) first-name age sex) +(cl-defstruct (person2 (:type list) :named) first-name age sex) +(cl-defstruct (person3 (:type list)) first-name age sex) +(cl-defstruct (person4 (:type vector)) first-name age sex) (setq p1 (make-person1)) @result{} #s(person1 nil nil nil) @@ -4254,10 +4264,10 @@ useful in conjunction with @code{:type}. Since unnamed structures don't have tags, @code{cl-defstruct} is not able to make a useful predicate for recognizing them. Also, -accessors like @code{person3-name} will be generated but they -will not be able to do any type checking. The @code{person3-name} +accessors like @code{person3-first-name} will be generated but they +will not be able to do any type checking. The @code{person3-first-name} function, for example, will simply be a synonym for @code{car} in -this case. By contrast, @code{person2-name} is able to verify +this case. By contrast, @code{person2-first-name} is able to verify that its argument is indeed a @code{person2} object before proceeding. @@ -5024,7 +5034,7 @@ The above @code{incf} example could be written using @ignore (defmacro concatf (place &rest args) (gv-letplace (getter setter) place - (macroexp-let2 nil v (mapconcat 'identity args "") + (macroexp-let2 nil v (mapconcat 'identity args) (funcall setter `(concat ,getter ,v))))) @end ignore @end defmac diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi index a0f316f8480..5e9c3d7eef6 100644 --- a/doc/misc/ede.texi +++ b/doc/misc/ede.texi @@ -1556,7 +1556,7 @@ You can also use TRAMP for use with rcp & scp. @item :web-site-file @* -A file which contains the home page for this project. +A file which contains the website for this project. This file can be relative to slot @code{web-site-directory}. This can be a local file, use ange-ftp, EFS, or TRAMP. diff --git a/doc/misc/efaq-w32.texi b/doc/misc/efaq-w32.texi index 6eff88b76e3..ba1077d0acd 100644 --- a/doc/misc/efaq-w32.texi +++ b/doc/misc/efaq-w32.texi @@ -2278,7 +2278,7 @@ In Emacs, you can browse the manual using Info by typing @kbd{C-h r}, and you can view the FAQ by typing @kbd{C-h C-f}. Other resources include: @itemize -@item @uref{https://www.gnu.org/software/emacs/, The Emacs homepage} +@item @uref{https://www.gnu.org/software/emacs/, The Emacs website} @item @uref{https://www.gnu.org/software/emacs/manual/, Other Emacs manuals} @item @uref{https://www.emacswiki.org/, Emacs Wiki} @end itemize diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi index d66c12f9fc3..18342e65b0a 100644 --- a/doc/misc/efaq.texi +++ b/doc/misc/efaq.texi @@ -7,10 +7,6 @@ @include emacsver.texi -@c This file is maintained by Romain Francoise <rfrancoise@gnu.org>. -@c Feel free to install changes without prior permission (but I'd -@c appreciate a notice if you do). - @copying Copyright @copyright{} 2001--2021 Free Software Foundation, Inc.@* Copyright @copyright{} 1994, 1995, 1996, 1997, 1998, 1999, 2000 @@ -86,7 +82,7 @@ Emacs, the Emacs manual is often the best starting point. * FAQ notation:: * General questions:: * Getting help:: -* Status of Emacs:: +* History of Emacs:: * Common requests:: * Bugs and problems:: * Compiling and installing Emacs:: @@ -215,11 +211,6 @@ completion, @kbd{?} for a list of possibilities, and @kbd{M-p} and @kbd{M-n} (or up-arrow and down-arrow) to see previous commands entered. An Emacs @dfn{command} is an @dfn{interactive} Emacs function. -@cindex @key{Do} key -Your system administrator may have bound other key sequences to invoke -@code{execute-extended-command}. A function key labeled @kbd{Do} is a -good candidate for this, on keyboards that have such a key. - If you need to run non-interactive Emacs functions, see @ref{Evaluating Emacs Lisp code}. @@ -231,7 +222,7 @@ Emacs Lisp code}. @cindex Info, finding topics in When we refer you to some @var{topic} in the Emacs manual, you can -read this manual node inside Emacs (assuming nothing is broken) by +read this manual node inside Emacs by typing @kbd{C-h i m emacs @key{RET} m @var{topic} @key{RET}}. This invokes Info, the GNU hypertext documentation browser. If you don't @@ -240,9 +231,8 @@ already know how to use Info, type @kbd{?} from within Info. If we refer to @var{topic}:@var{subtopic}, type @kbd{C-h i m emacs @key{RET} m @var{topic} @key{RET} m @var{subtopic} @key{RET}}. -If these commands don't work as expected, your system administrator may -not have installed the Info files, or may have installed them -improperly. In this case you should complain. +(If these commands don't work as expected, your system may be missing +the Info files, or they may not be installed properly.) If you are reading this FAQ in Info, you can simply press @key{RET} on a reference to follow it. @@ -304,6 +294,9 @@ Richard Matthew Stallman @item GPL GNU General Public License +See @uref{https://gnu.org/licenses/, the GNU web site} for more +information about the GPL. + @end table The word ``free'' in the title of the Free Software Foundation refers to @@ -322,7 +315,6 @@ This chapter contains general questions having to do with Emacs, the Free Software Foundation, and related organizations. @menu -* Real meaning of copyleft:: * Guidelines for mailing list postings:: * Mailing list archives:: * Reporting bugs:: @@ -330,67 +322,31 @@ Free Software Foundation, and related organizations. * Contacting the FSF:: @end menu -@node Real meaning of copyleft -@section What is the real legal meaning of the GNU copyleft? -@cindex Copyleft, real meaning of -@cindex GPL, real meaning of -@cindex General Public License, real meaning of -@cindex Discussion of the GPL - -The real legal meaning of the GNU General Public License (copyleft) will -only be known if and when a judge rules on its validity and scope. -There has never been a copyright infringement case involving the GPL to -set any precedents. Although legal actions have been brought against -companies for violating the terms of the GPL, so far all have been -settled out of court (in favor of the plaintiffs). Please take any -discussion regarding this issue to -@uref{https://lists.gnu.org/mailman/listinfo/gnu-misc-discuss, the -gnu-misc-discuss mailing list}, which was created to hold the -extensive flame wars on the subject. - -RMS writes: - -@quotation -The legal meaning of the GNU copyleft is less important than the spirit, -which is that Emacs is a free software project and that work pertaining -to Emacs should also be free software. ``Free'' means that all users -have the freedom to study, share, change and improve Emacs. To make -sure everyone has this freedom, pass along source code when you -distribute any version of Emacs or a related program, and give the -recipients the same freedom that you enjoyed. -@end quotation - @node Guidelines for mailing list postings @section What are appropriate messages for the various Emacs mailing lists? -@cindex Newsgroups, appropriate messages for -@cindex GNU newsgroups, appropriate messages for -@cindex GNU mailing lists, appropriate messages for -@cindex Usenet groups, appropriate messages for @cindex Mailing lists, appropriate messages for @cindex Posting messages to mailing lists - @cindex GNU mailing lists -The Emacs mailing lists are described at + +There are various Emacs mailing lists, described at @uref{https://savannah.gnu.org/mail/?group=emacs, the Emacs Savannah page}. -Messages advocating ``non-free'' software are considered unacceptable -on any of the GNU mailing lists, except for -@url{https://lists.gnu.org/mailman/listinfo/gnu-misc-discuss, the -gnu-misc-discuss mailing list} which was created to hold the extensive -flame-wars on the subject. - -``Non-free'' software includes any software for which the end user -can't freely modify the source code and exchange enhancements. Be -careful to remove any GNU mailing lists from @samp{Cc:} when posting a -reply that recommends such software. - -@url{https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs, The -bug-gnu-emacs list} is a place where bug reports appear, but we -recommend using the commands @kbd{M-x report-emacs-bug} or @kbd{M-x -submit-emacs-patch} if at all possible (@pxref{Reporting bugs}). - -Some GNU mailing lists are gatewayed to (Usenet) newsgroups. +The main ones are: @code{help-gnu-emacs}, @code{bug-gnu-emacs}, +and @code{emacs-devel}. + +Messages advocating ``non-free'' software are considered unacceptable on +any of the GNU mailing lists, except for +@url{https://lists.gnu.org/mailman/listinfo/gnu-misc-discuss, +the gnu-misc-discuss mailing list}. +``Non-free'' software includes any software for which the end user can't +freely modify the source code and exchange enhancements. Please +remove GNU mailing lists from the recipients when +posting a reply that recommends such software. + +@cindex newsgroups +Some of the GNU mailing lists are gatewayed to newsgroups (although +the connection is occasionally unreliable). For example, sending an email to @url{https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs, The bug-gnu-emacs list} has the effect of posting on the newsgroup @@ -412,6 +368,8 @@ years, although there may be some unintentional gaps in coverage. The archive can be browsed over the web at @uref{https://lists.gnu.org/r/, the GNU mail archive}. +@cindex Usenet archives for GNU groups +@cindex Old Usenet postings for GNU groups Some web-based Usenet search services also archive the @code{gnu.*} newsgroups. @@ -422,15 +380,8 @@ newsgroups. @cindex How to submit a bug report @cindex Reporting bugs -The correct way to report Emacs bugs is to use the command -@kbd{M-x report-emacs-bug}. It sets up a mail buffer with the -essential information and the correct e-mail address, -@email{bug-gnu-emacs@@gnu.org}. - -Be sure to read the ``Bugs'' section of the Emacs manual before reporting -a bug! The manual describes in detail how to submit a useful bug -report (@pxref{Bugs, , Reporting Bugs, emacs, The GNU Emacs Manual}). -(@xref{Emacs manual}, if you don't know how to read the manual.) +Please see the Emacs manual for information on how to report bugs. +@xref{Checklist, , Checklist for Bug Reports, emacs, The GNU Emacs Manual}. Sending bug reports to @url{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs, the @@ -444,7 +395,7 @@ more messages about Emacs than the others. If you have reported a bug and you don't hear about a possible fix, then after a suitable delay (such as a week) it is okay to post on -@code{help-gnu-emacs@@gnu.org} asking if anyone can help you. +the help list asking if anyone can help you. If you are unsure whether you have found a bug, consider the following non-exhaustive list, courtesy of RMS: @@ -863,12 +814,9 @@ Emacs news, a history of recent user-visible changes @end table -More GNU information, including back issues of the @cite{GNU's -Bulletin}, are at - -@uref{https://www.gnu.org/bulletins/bulletins.html} and +More GNU and FSF information is available at -@uref{https://www.cs.pdx.edu/~trent/gnu/gnu.html} +@uref{https://www.gnu.org} and @uref{https://www.fsf.org} @node Help installing Emacs @section Where can I get help in installing Emacs? @@ -894,12 +842,9 @@ C-f} (@kbd{M-x view-emacs-FAQ}). The very latest version is available in the Emacs development repository (@pxref{Latest version of Emacs}). @c ------------------------------------------------------------ -@node Status of Emacs -@chapter Status of Emacs -@cindex Status of Emacs - -This chapter gives you basic information about Emacs, including the -status of its latest version. +@node History of Emacs +@chapter History of Emacs +@cindex History of Emacs @menu * Origin of the term Emacs:: @@ -912,6 +857,7 @@ status of its latest version. * New in Emacs 22:: * New in Emacs 21:: * New in Emacs 20:: +* What was XEmacs?:: @end menu @node Origin of the term Emacs @@ -950,7 +896,6 @@ conventions}). @cindex Latest version of Emacs @cindex Development, Emacs @cindex Repository, Emacs -@cindex Bazaar repository, Emacs Emacs @value{EMACSVER} is the current version as of this writing. A version number with two components (e.g., @samp{24.5}) indicates a released @@ -1475,6 +1420,29 @@ several languages in the same document; the ``Customize'' facility for modifying variables without having to use Lisp; and automatic conversion of files from Macintosh, Microsoft, and Unix platforms. +@node What was XEmacs? +@section What was XEmacs? +@cindex XEmacs + +XEmacs was a branch version of Emacs that is no longer actively +developed. Originally known as ``Lucid Emacs'', XEmacs was forked +from a prerelease version of Emacs 19. XEmacs last released a new +version on January 30, 2009, which lacks many important features that +exist in Emacs. Since its development has stopped, we do not expect +to see any new releases. + +In the past, it was not uncommon for Emacs packages to include code +for compatibility with XEmacs. Nowadays, most built-in and third party +packages have either stopped supporting XEmacs or were developed +exclusively for Emacs. + +If you want to talk about these two versions and distinguish them, +please call them ``Emacs'' and ``XEmacs.'' To contrast ``XEmacs'' +with ``GNU Emacs'' would be misleading, since XEmacs too has its +origin in the work of the GNU Project. Terms such as ``Emacsen'' and +``(X)Emacs'' are not wrong, but they are not very clear, so it +is better to write ``Emacs and XEmacs.'' + @c ------------------------------------------------------------ @node Common requests @chapter Common requests @@ -1598,7 +1566,7 @@ capabilities. The command @kbd{M-x list-colors-display} pops up a window which exhibits all the colors Emacs knows about on the current display. -Syntax highlighting is on by default since version 22.1. +Syntax highlighting is also on by default on text-only terminals. @cindex direct color in terminals Emacs 26.1 and later support direct color mode in terminals. If Emacs @@ -3380,6 +3348,7 @@ dired, @code{directory-listing-before-filename-regexp}. @menu * Installing Emacs:: +* Emacs for other operating systems:: * Problems building Emacs:: @end menu @@ -3392,9 +3361,7 @@ dired, @code{directory-listing-before-filename-regexp}. @cindex Source code, building Emacs from This answer is meant for users of Unix and Unix-like systems. Users of -other operating systems should see the series of questions beginning -with @ref{Emacs for MS-DOS}, which describe where to get non-Unix source -and binaries, and how to install Emacs on those systems. +other operating systems should see @xref{Emacs for other operating systems}. Most GNU/Linux distributions provide pre-built Emacs packages. If Emacs is not installed already, you can install it by running (as @@ -3413,20 +3380,20 @@ a list of sites that make them available. On @url{https://ftp.gnu.org}, the main GNU distribution site, sources are available as @c Don't include VER in the file name, because pretests are not there. -@uref{https://ftp.gnu.org/pub/gnu/emacs/emacs-VERSION.tar.gz} +@uref{https://ftp.gnu.org/pub/gnu/emacs/emacs-VERSION.tar.xz} (Replace @samp{VERSION} with the relevant version number, e.g., @samp{28.1}.) @item Next uncompress and extract the source files. This requires -the @code{gzip} and @code{tar} programs, which are standard utilities. +the @code{xz} and @code{tar} programs, which are standard utilities. If your system does not have them, these can also be downloaded from @url{https://ftp.gnu.org}. GNU @code{tar} can uncompress and extract in a single-step: @example -tar -zxvf emacs-VERSION.tar.gz +tar -axvf emacs-VERSION.tar.xz @end example @item @@ -3440,9 +3407,8 @@ cd emacs-VERSION make # use Makefile to build components, then Emacs @end example -If the @code{make} completes successfully, the odds are fairly good that -the build has gone well. (@xref{Problems building Emacs}, if you weren't -successful.) +If the @code{make} completes successfully, you can go on to install it. +(@xref{Problems building Emacs}, if you weren't successful.) @item By default, Emacs is installed in @file{/usr/local}. To actually @@ -3457,6 +3423,46 @@ and any Emacs Info files that might be in @file{/usr/local/share/info/}. @end itemize +@node Emacs for other operating systems +@section Where can I get Emacs for macOS, MS Windows, etc? + +@cindex Apple computers, Emacs for +@cindex Macintosh, Emacs for +@cindex macOS, Emacs for +Beginning with version 22.1, Emacs supports macOS natively. +See the file @file{nextstep/INSTALL} in the distribution. + +@cindex FAQ for Emacs on MS-Windows +@cindex Emacs for MS-Windows +@cindex Microsoft Windows, Emacs for +There is a separate FAQ for Emacs on MS-Windows, +@pxref{Top,,,efaq-w32,FAQ for Emacs on MS Windows}. + +@cindex GNUstep, Emacs for +Beginning with version 23.1, Emacs supports GNUstep natively. +See the file @file{nextstep/INSTALL} in the distribution. + +@cindex MS-DOS, Emacs for +@cindex DOS, Emacs for +@cindex Compiling Emacs for DOS +@cindex Emacs for MS-DOS +To build Emacs from source for MS-DOS, see the instructions in the file +@file{msdos/INSTALL} in the distribution. The DOS port builds and runs +on plain DOS, and also on all versions of MS-Windows from version 3.X +onwards, including Windows XP and Vista. Pre-built binaries may be +available at +@uref{http://www.delorie.com/pub/djgpp/current/v2gnu/emacs.README} + +For a list of other implementations of Emacs (and Emacs +look-alikes), consult the list of ``Emacs implementations and literature,'' +available at + +@uref{http://www.finseth.com/emacs.html} + +Note that while many of these programs look similar to Emacs, they often +lack certain features, such as the Emacs Lisp extension language. + + @node Problems building Emacs @section What should I do if I have trouble building Emacs? @cindex Problems building Emacs @@ -3480,26 +3486,20 @@ problem (@pxref{Reporting bugs}). @cindex Finding Emacs and related packages @menu -* Finding Emacs on the Internet:: +* Downloading Emacs:: * Finding a package with particular functionality:: * Packages that do not come with Emacs:: * Spell-checkers:: * Current GNU distributions:: -* What was XEmacs?:: * Emacs for minimalists:: -* Emacs for MS-DOS:: -* Emacs for MS-Windows:: -* Emacs for GNUstep:: -* Emacs for macOS:: @end menu -@node Finding Emacs on the Internet -@section Where can I get Emacs on the net? -@cindex Finding Emacs on the Internet +@node Downloading Emacs +@section Downloading Emacs @cindex Downloading Emacs Information on downloading Emacs is available at -@uref{https://www.gnu.org/software/emacs/, the Emacs home-page}. +@uref{https://www.gnu.org/software/emacs/, the Emacs website}. @xref{Installing Emacs}, for information on how to obtain and build the latest version of Emacs, and see @ref{Current GNU distributions}, for a list of @@ -3511,25 +3511,22 @@ archive sites that make GNU software available. @cindex Finding an Emacs Lisp package @cindex Functionality, finding a particular package -First of all, you should check to make sure that the package isn't -already available. For example, typing @kbd{M-x apropos @key{RET} -python @key{RET}} lists all functions and variables containing the -string @samp{python}. - -It is also possible that the package is on your system, but has not been -loaded. To see which packages are available for loading, look through -your computer's lisp directory (@pxref{File-name conventions}). The Lisp -source to most packages contains a short description of how they -should be loaded, invoked, and configured---so before you use or -modify a Lisp package, see if the author has provided any hints in the -source code. - The command @kbd{C-h p} (@code{finder-by-keyword}) allows you to browse -the constituent Emacs packages. +the packages that come with Emacs. For advice on how to find extra packages that are not part of Emacs, see @ref{Packages that do not come with Emacs}. +Other techniques that might be useful: + +Typing @kbd{M-x apropos @key{RET} python @key{RET}} lists all +functions and variables containing the string @samp{python}. + +You can look through your computer's lisp directory (@pxref{File-name +conventions}). The Lisp source to most packages contains a short +description of what they do and how they should be used. + + @c Note that M-x view-external-packages references this node. @node Packages that do not come with Emacs @section Where can I get Emacs Lisp packages that don't come with Emacs? @@ -3619,28 +3616,6 @@ A list of sites mirroring @samp{ftp.gnu.org} can be found at @uref{https://www.gnu.org/prep/ftp} -@node What was XEmacs? -@section What was XEmacs? -@cindex XEmacs - -XEmacs was a branch version of Emacs that is no longer actively -developed. XEmacs last released a new version on January 30, 2009, -and it lacks many important features that exist in Emacs. Since its -development has stopped, we do not expect to see any new releases. - -In the past, it was not uncommon for Emacs packages to include code -for compatibility with XEmacs. Nowadays, most built-in and third party -packages have either stopped supporting XEmacs or were developed -exclusively for Emacs. - -XEmacs was initially derived from a prerelease version of Emacs 19. -If you want to talk about these two versions and distinguish them, -please call them ``Emacs'' and ``XEmacs.'' To contrast ``XEmacs'' -with ``GNU Emacs'' would be misleading, since XEmacs too has its -origin in the work of the GNU Project. Terms such as ``Emacsen'' and -``(X)Emacs'' are not wrong, but they are not very clear, so it -is better to write ``Emacs and XEmacs.'' - @node Emacs for minimalists @section I don't have enough disk space to install Emacs @cindex Zile @@ -3654,63 +3629,6 @@ information is available from @uref{https://www.gnu.org/software/zile/} - -@node Emacs for MS-DOS -@section Where can I get Emacs for MS-DOS? -@cindex MS-DOS, Emacs for -@cindex DOS, Emacs for -@cindex Compiling Emacs for DOS -@cindex Emacs for MS-DOS - -To build Emacs from source for MS-DOS, see the instructions in the file -@file{msdos/INSTALL} in the distribution. The DOS port builds and runs -on plain DOS, and also on all versions of MS-Windows from version 3.X -onwards, including Windows XP and Vista. - -The file @file{etc/PROBLEMS} contains some additional information -regarding Emacs under MS-DOS. - -A pre-built binary distribution of the old Emacs 24 is available, as -described at - -@uref{http://www.delorie.com/pub/djgpp/current/v2gnu/emacs.README} - -For a list of other MS-DOS implementations of Emacs (and Emacs -look-alikes), consult the list of ``Emacs implementations and literature,'' -available at - -@uref{https://www.finseth.com/emacs.html} - -Note that while many of these programs look similar to Emacs, they often -lack certain features, such as the Emacs Lisp extension language. - -@node Emacs for MS-Windows -@section Where can I get Emacs for Microsoft Windows? -@cindex FAQ for Emacs on MS-Windows -@cindex Emacs for MS-Windows -@cindex Microsoft Windows, Emacs for - -There is a separate FAQ for Emacs on MS-Windows, -@pxref{Top,,,efaq-w32,FAQ for Emacs on MS Windows}. -For MS-DOS, @pxref{Emacs for MS-DOS}. - - -@node Emacs for GNUstep -@section Where can I get Emacs for GNUstep? -@cindex GNUstep, Emacs for - -Emacs supports GNUstep natively. See the file @file{nextstep/INSTALL} -in the distribution. - -@node Emacs for macOS -@section Where can I get Emacs for macOS? -@cindex Apple computers, Emacs for -@cindex Macintosh, Emacs for -@cindex macOS, Emacs for - -Emacs supports macOS natively. See the file @file{nextstep/INSTALL} -in the distribution. - @c ------------------------------------------------------------ @node Key bindings @chapter Key bindings @@ -4218,9 +4136,6 @@ You can get the old behavior by binding @kbd{SPC} to @lisp (define-key minibuffer-local-filename-completion-map (kbd "SPC") 'minibuffer-complete-word) - -(define-key minibuffer-local-filename-must-match-map (kbd "SPC") - 'minibuffer-complete-word) @end lisp @c ------------------------------------------------------------ diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi index 63b42827311..2b0b1f7fd67 100644 --- a/doc/misc/eieio.texi +++ b/doc/misc/eieio.texi @@ -700,18 +700,19 @@ slot values, and use the previously mentioned set/ref routines. @defun slot-value object slot @anchor{slot-value} This function retrieves the value of @var{slot} from @var{object}. +It can also be used on objects defined by @code{cl-defstruct}. This is a generalized variable that can be used with @code{setf} to -modify the value stored in @var{slot}. @xref{Generalized -Variables,,,elisp,GNU Emacs Lisp Reference Manual}. +modify the value stored in @var{slot}, tho not for objects defined by +@code{cl-defstruct}. +@xref{Generalized Variables,,,elisp,GNU Emacs Lisp Reference Manual}. @end defun @defun set-slot-value object slot value @anchor{set-slot-value} This function sets the value of @var{slot} from @var{object}. -This is not a CLOS function, but is the obsolete setter for -@code{slot-value} used by the @code{setf} macro. It is therefore +This is not a CLOS function. It is therefore recommended to use @w{@code{(setf (slot-value @var{object} @var{slot}) @var{value})}} instead. @end defun diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index 10ced678e1d..3b8e231d3a1 100644 --- a/doc/misc/erc.texi +++ b/doc/misc/erc.texi @@ -2,13 +2,15 @@ @c %**start of header @setfilename ../../info/erc.info @settitle ERC Manual +@set ERCVER 5.4.1 +@set ERCDIST as distributed with Emacs @value{EMACSVER} @include docstyle.texi @syncodeindex fn cp @include emacsver.texi @c %**end of header @copying -This manual is for ERC as distributed with Emacs @value{EMACSVER}. +This manual is for ERC @value{ERCVER} @value{ERCDIST}. Copyright @copyright{} 2005--2021 Free Software Foundation, Inc. diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi index fafdb8c4eb4..440c61add8e 100644 --- a/doc/misc/ert.texi +++ b/doc/misc/ert.texi @@ -260,36 +260,103 @@ unexpected result. In the example above, there are two failures, both due to failed @code{should} forms. @xref{Understanding Explanations}, for more details. +The following key bindings are available in the ERT results buffer: + +@table @kbd + +@item @key{RET} +@kindex RET@r{, in ert results buffer} +Each name of a function or macro in this buffer is a button; moving +point to it and typing @kbd{@key{RET}} jumps to its definition. + +@item @key{TAB} +@itemx S-@key{TAB} @kindex TAB@r{, in ert results buffer} @kindex S-TAB@r{, in ert results buffer} -In the ERT results buffer, @kbd{@key{TAB}} and @kbd{S-@key{TAB}} cycle between -buttons. Each name of a function or macro in this buffer is a button; -moving point to it and typing @kbd{@key{RET}} jumps to its definition. +Cycle between buttons forward (@code{forward-button}) and backward +(@code{backward-button}). +@item r @kindex r@r{, in ert results buffer} +@findex ert-results-rerun-test-at-point +Re-run the test near point on its own +(@code{ert-results-rerun-test-at-point}). + +@item d @kindex d@r{, in ert results buffer} +@findex ert-results-rerun-test-at-point-debugging-errors +Re-run the test near point on its own with the debugger enabled +(@code{ert-results-rerun-test-at-point-debugging-errors}). + +@item R +@kindex R@r{, in ert results buffer} +@findex ert-results-rerun-all-tests +Re-run all tests (@code{ert-results-rerun-all-tests}). + +@item . @kindex .@r{, in ert results buffer} +@findex ert-results-find-test-at-point-other-window +Jump to the definition of the test near point +(@code{ert-results-find-test-at-point-other-window}). This has the +same effect as @kbd{@key{RET}}, but does not require point to be on +the name of the test. + +@item b @kindex b@r{, in ert results buffer} +@findex ert-results-pop-to-backtrace-for-test-at-point @cindex backtrace of a failed test -Pressing @kbd{r} re-runs the test near point on its own. Pressing -@kbd{d} re-runs it with the debugger enabled. @kbd{.} jumps to the -definition of the test near point (@kbd{@key{RET}} has the same effect -if point is on the name of the test). On a failed test, @kbd{b} shows -the backtrace of the failure. @xref{Debugging,, Backtraces, elisp, -GNU Emacs Lisp Reference Manual}, for more information about -backtraces. +Show the backtrace of a failed test +(@code{ert-results-pop-to-backtrace-for-test-at-point}). +@xref{Debugging,, Backtraces, elisp, GNU Emacs Lisp Reference Manual}, +for more information about backtraces. +@item l @kindex l@r{, in ert results buffer} -@kbd{l} shows the list of @code{should} forms executed in the test. -If any messages were generated (with the Lisp function @code{message}) -in a test or any of the code that it invoked, @kbd{m} will show them. - +@findex ert-results-pop-to-should-forms-for-test-at-point +Show the list of @code{should} forms executed in the test +(@code{ert-results-pop-to-should-forms-for-test-at-point}). + +@item m +@kindex m@r{, in ert results buffer} +@findex ert-results-pop-to-messages-for-test-at-point +Show any messages that were generated (with the Lisp function +@code{message}) in in a test or any of the code that it invoked +(@code{ert-results-pop-to-messages-for-test-at-point}). + +@item L @kindex L@r{, in ert results buffer} +@findex ert-results-toggle-printer-limits-for-test-at-point By default, long expressions in the failure details are abbreviated -using @code{print-length} and @code{print-level}. Pressing @kbd{L} -while point is on a test failure will increase the limits to show more -of the expression. +using @code{print-length} and @code{print-level}. Increase the limits +to show more of the expression by moving point to a test failure with +this command (@code{ert-results-toggle-printer-limits-for-test-at-point}). + +@item D +@kindex D@r{, in ert results buffer} +@findex ert-delete-test +@cindex delete test +Delete a test from the running Emacs session (@code{ert-delete-test}). +@item h +@kindex h@r{, in ert results buffer} +@findex ert-describe-test +Show the documentation of a test (@code{ert-describe-test}). + +@item T +@kindex T@r{, in ert results buffer} +@findex ert-results-pop-to-timings +Display test timings for the last run (@code{ert-results-pop-to-timings}). + +@item M-x ert-delete-all-tests +@findex ert-delete-all-tests +@cindex delete all tests +Delete all tests from the running session. + +@item M-x ert-describe-test +@findex ert-results-describe-test-at-point +Prompt for a test and then show its documentation. + +@end table @node Running Tests in Batch Mode @section Running Tests in Batch Mode @@ -348,7 +415,7 @@ emacs -batch -l ert -l my-tests.el \ @end example By default, ERT test failure summaries are quite brief in batch -mode--only the names of the failed tests are listed. If the +mode---only the names of the failed tests are listed. If the EMACS_TEST_VERBOSE environment variable is set, the failure summaries will also include the data from the failing test. @@ -419,6 +486,7 @@ to find where a test was defined if the test was loaded from a file. * Expected Failures:: Tests for known bugs. * Tests and Their Environment:: Don't depend on customizations; no side effects. * Useful Techniques:: Some examples. +* erts files:: Files containing many buffer tests. @end menu @node The @code{should} Macro @@ -700,6 +768,119 @@ code is to restructure the code slightly to provide better interfaces for testing. Usually, this makes the interfaces easier to use as well. +@node erts files +@section erts files + +@findex ert-test-erts-file +Many relevant Emacs tests depend on comparing the contents of a buffer +before and after executing a particular function. These tests can be +written the normal way---making a temporary buffer, inserting the +``before'' text, running the function, and then comparing with the +expected ``after'' text. However, this often leads to test code +that's pretty difficult to read and write, especially when the text in +question is multi-line. + +So ert provides a function called @code{ert-test-erts-file} that takes +two parameters: The name of a specially-formatted @dfn{erts} file, and +(optionally) a function that performs the transform. + +@findex erts-mode +These erts files can be edited with the @code{erts-mode} major mode. + +An erts file is divided into sections by the (@samp{=-=}) separator. + +Here's an example file containing two tests: + +@example +Name: flet + +=-= +(cl-flet ((bla (x) +(* x x))) +(bla 42)) +=-= +(cl-flet ((bla (x) + (* x x))) + (bla 42)) +=-=-= + +Name: defun + +=-= +(defun x () + (print (quote ( thingy great + stuff)))) +=-=-= +@end example + +A test starts with a line containing just @samp{=-=} and ends with a +line containing just @samp{=-=-=}. The test may be preceded by +freeform text (for instance, comments), and also name/value pairs (see +below for a list of them). + +If there is a line with @samp{=-=} inside the test, that designates +the start of the ``after'' text. Otherwise, the ``before'' and +``after'' texts are assumed to be identical, which you typically see +when writing indentation tests. + +@code{ert-test-erts-file} puts the ``before'' section into a temporary +buffer, calls the transform function, and then compares with the +``after'' section. + +Here's an example usage: + +@lisp +(ert-test-erts-file "elisp.erts" + (lambda () + (emacs-lisp-mode) + (indent-region (point-min) (point-max)))) +@end lisp + +A list of the name/value specifications that can appear before a test +follows. The general syntax is @samp{Name: Value}, but continuation +lines can be used (along the same lines as in mail---subsequent lines +that start with a space are part of the value). + +@example +Name: foo +Code: (indent-region + (point-min) (point-max)) +@end example + +@table @samp +@item Name +All tests should have a name. This name will appear in ERT output if +the test fails, and helps to identify the failing test. + +@item Code +This is the code that will be run to do the transform. This can also +be passed in via the @code{ert-test-erts-file} call, but @samp{Code} +overrides that. It's used not only in the following test, but in all +subsequent tests in the file (until overridden by another @samp{Code} +specification). + +@item No-Before-Newline +@itemx No-After-Newline +These specifications say whether the ``before'' or ``after'' portions +have a newline at the end. (This would otherwise be impossible to +specify.) + +@item Point-Char +Sometimes it's useful to be able to put point at a specific place +before executing the transform function. @samp{Point-Char: |} will +make @code{ert-test-erts-file} place point where @samp{|} is in the +``before'' form (and remove that character), and will check that it's +where the @samp{|} character is in the ``after'' form (and issue a +test failure if that isn't the case). (This is used in all subsequent +tests, unless overridden by a new @samp{Point-Char} spec.) + +@item Skip +If this is present and value is a form that evaluates to a +non-@code{nil} value, the test will be skipped. +@end table + +If you need to use the literal line single line @samp{=-=} in a test +section, you can quote it with a @samp{\} character. @node How to Debug Tests @chapter How to Debug Tests diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index fc2e3f3b111..c01ceb5fb93 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -744,21 +744,33 @@ Eshell module.} You also need to load the following as shown: @node Writing a module @section Writing a module +This section is not yet written. + @node Module testing @section Module testing +This section is not yet written. + @node Directory handling @section Directory handling +This section is not yet written. + @node Key rebinding @section Key rebinding +This section is not yet written. + @node Smart scrolling @section Smart scrolling +This section is not yet written. + @node Terminal emulation @section Terminal emulation +This section is not yet written. + @node Bugs and ideas @chapter Bugs and ideas @cindex reporting bugs and ideas diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi index cc546a92d63..ebfdaf546e3 100644 --- a/doc/misc/eww.texi +++ b/doc/misc/eww.texi @@ -228,11 +228,12 @@ in an external browser by customizing @findex eww-retrieve-command EWW normally uses @code{url-retrieve} to fetch the @acronym{HTML} -before rendering it. It can sometimes be convenient to use an -external program to do this, and @code{eww-retrieve-command} should -then be a list that specifies a command and the parameters. For -instance, to use the Chromium browser, you could say something like -this: +before rendering it, and @code{url-retrieve-synchronously} when +the value of @code{eww-retrieve-command} is @code{sync}. It can +sometimes be convenient to use an external program to do this, and +@code{eww-retrieve-command} should then be a list that specifies +a command and the parameters. For instance, to use the Chromium +browser, you could say something like this: @lisp (setq eww-retrieve-command @@ -379,6 +380,32 @@ thus allowing for the use of the usual substitutions, such as @code{\[eww-reload]} for the current key binding of the @code{eww-reload} command. +@vindex eww-auto-rename-buffer + If the @code{eww-auto-rename-buffer} user option is non-@code{nil}, +EWW buffers will be renamed after rendering a document. If this is +@code{title}, rename based on the title of the document. If this is +@code{url}, rename based on the @acronym{URL} of the document. This +can also be a user-defined function, which is called with no +parameters in the EWW buffer, and should return a string. + +@cindex utm +@vindex eww-url-transformers + EWW runs the URLs through @code{eww-url-transformers} before using +them. This user option is a list of functions, where each function is +called with the URL as the parameter, and should return the (possibly) +transformed URL. By default, this variable contains +@code{eww-remove-tracking}, which removes the common @samp{utm_} +trackers from links. + +@cindex video +@vindex shr-use-xwidgets-for-media + If Emacs has been built with xwidget support, EWW can use that to +display @samp{<video>} elements. However, this support is still +experimental, and on some systems doesn't work (and even worse) may +crash your Emacs, so this feature is off by default. If you wish to +switch it on, set @code{shr-use-xwidgets-for-media} to a +non-@code{nil} value. + @node Command Line @chapter Command Line Usage diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi index 9c838a8341a..309bed77609 100644 --- a/doc/misc/flymake.texi +++ b/doc/misc/flymake.texi @@ -1,8 +1,8 @@ \input texinfo @c -*-texinfo; coding: utf-8 -*- @comment %**start of header @setfilename ../../info/flymake.info -@set VERSION 1.0 -@set UPDATED June 2018 +@set VERSION 1.2 +@set UPDATED September 2021 @settitle GNU Flymake @value{VERSION} @include docstyle.texi @syncodeindex pg cp @@ -11,8 +11,7 @@ @comment %**end of header @copying -This manual is for GNU Flymake (version @value{VERSION}, @value{UPDATED}), -which is a universal on-the-fly syntax checker for GNU Emacs. +This manual is for GNU Flymake (version @value{VERSION}, @value{UPDATED}). Copyright @copyright{} 2004--2021 Free Software Foundation, Inc. @@ -41,6 +40,7 @@ modify this GNU manual.'' @page @vskip 0pt plus 1filll @insertcopying + @end titlepage @contents @@ -48,6 +48,25 @@ modify this GNU manual.'' @ifnottex @node Top @top GNU Flymake +@end ifnottex + +Flymake is a universal on-the-fly syntax checker for Emacs. When +enabled, Flymake contacts one or more source @dfn{backends} to +collect information about problems in the buffer, called +@dfn{diagnostics}, and visually annotates them with a special face. +The mode line displays overall status including totals for different +types of diagnostics. + +To learn about using Flymake, @pxref{Using Flymake}. + +Flymake is designed to be easily extended to support new backends via +an Elisp interface. @xref{Extending Flymake}. + +Historically, Flymake used to accept diagnostics from a single +backend. Although obsolete, it is still functional. To learn how to +use and customize it, @pxref{The legacy Proc backend}. + +@ifnottex @insertcopying @end ifnottex @@ -64,19 +83,34 @@ modify this GNU manual.'' @cindex overview of flymake @cindex using flymake -Flymake is a universal on-the-fly buffer checker implemented as an -Emacs minor mode. To use Flymake, you must first activate -@code{flymake-mode} by using the command @kbd{flymake-mode}. +Flymake is only useful if at least one @dfn{backend} is configured to +provide the buffer-checking service. This is done via the hook +@code{flymake-diagnostic-functions}. @xref{Hooks,Hooks,, emacs, The +Emacs Editor}. + +It's possible that some major modes or a third-party package has +already setup this hook for you, by adding @dfn{backend functions} to +@code{flymake-diagnostic-functions}. If you know Elisp you may also +write your own Flymake backend functions. @xref{Backend functions}. -When enabled, Flymake collects information about problems in the -buffer, called @dfn{diagnostics}, from one or more different sources, -or @dfn{backends}, and then visually annotates the buffer by -highlighting problematic buffer regions with a special face. +@menu +* Starting Flymake:: +* Finding diagnostics:: +* Mode line status:: +* Troubleshooting:: +* Customizable variables:: +@end menu -It also displays an overall buffer status in the mode line containing -totals for different types of diagnostics. +@node Starting Flymake +@section Starting Flymake +@cindex starting Flymake -Syntax check is done ``on-the-fly''. It is started whenever +To use Flymake, activate the minor-mode @code{flymake-mode}. +Use the command @kbd{flymake-mode} to toggle it on and off. The +mode line should indicate its presence via an indicator (@pxref{Mode +line status}). + +Syntax checks happen ``on-the-fly''. Each check is started whenever: @itemize @bullet @item @@ -90,50 +124,56 @@ nil; @item some changes were made to the buffer more than @code{0.5} seconds ago (the delay is configurable in @code{flymake-no-changes-timeout}). -@end itemize -Syntax check can also be started manually by typing the @kbd{M-x -flymake-start @key{RET}} command. +@item +When the user invokes the command @code{flymake-start}. +@end itemize If the check detected errors or warnings, the respective buffer -regions are highlighted. You can place point on those regions and use -@kbd{C-h .} (@code{display-local-help}) to see what the specific -problem was. Alternatively, hovering the mouse on those regions -should also display a tool-tip with the same information. +regions are highlighted. @xref{Finding diagnostics}, for how to +learn what the problems are. + +@node Finding diagnostics +@section Finding diagnostics +@cindex read diagnostic message +If Flymake has highlighted the buffer, you may hover the mouse on the +highlighted regions to learn what the specific problem +is. Alternatively, place point on the highlighted regions and use the +commands @code{eldoc} or @code{display-local-help}. + +@cindex next and previous diagnostic +If the diagnostics are outside the visible region of the buffer, @code{flymake-goto-next-error} and @code{flymake-goto-prev-error} are -commands that allow easy navigation to the next/previous erroneous -regions, respectively. It might be a good idea to map them to @kbd{M-n} -and @kbd{M-p} in @code{flymake-mode}, by adding to your init file: +let you navigate to the next/previous erroneous regions, +respectively. It might be a good idea to map them to @kbd{M-n} and +@kbd{M-p} in @code{flymake-mode}, by adding to your init file: @lisp (define-key flymake-mode-map (kbd "M-n") 'flymake-goto-next-error) (define-key flymake-mode-map (kbd "M-p") 'flymake-goto-prev-error) @end lisp -Flymake is a universal syntax checker in the sense that it's easily -extended to support new backends (@pxref{Extending Flymake}). - -Historically, Flymake used to accept diagnostics from a single -backend, albeit a reasonably flexible one. - -This backend isn't (yet) obsolete, and so is still available as a -fallback and active by default (@pxref{The legacy Proc backend}). It works by -selecting a syntax check tool from a preconfigured list (compiler for -C@t{++} files, @command{perl} for Perl files, etc.), and executing it in the -background, passing it a temporary file which is a copy of the current -buffer, and parsing the output for known error/warning message -patterns. - -@menu -* Syntax check statuses:: -* Backend exceptions:: -* Customizable variables:: -@end menu - -@node Syntax check statuses -@section Syntax check statuses -@cindex Syntax check statuses +@cindex listing diagnostics +Sometimes it is useful to have a detailed overview of the diagnostics +in your files without having to jump to each one. The commands +@code{flymake-show-buffer-diagnostics} and +@code{flymake-show-project-diagnostics} are designed to handle this +situation. When invoked, they bring up a separate buffer containing a +detailed structured listing of multiple diagnostics in the current +buffer or for the current project, respectively (@pxref{Projects,,, +emacs, The Emacs Editor}). + +The listings is continuously updated as you edit source code, adding or +removing lines as you make or correct mistakes. Each line of this +listing includes the type of the diagnostic, its line and column in +the file, as well as the diagnostic message. You may sort the listing +by each of these columns. + +@node Mode line status +@section Mode line status +@cindex flymake mode line +@cindex syntax check status When enabled, Flymake displays its status in the mode line, which provides a visual summary of diagnostic collection. It may also hint @@ -157,7 +197,7 @@ delay and Flymake will resume normal operation soon. @item @code{!} @tab All the configured Flymake backends have disabled themselves: Flymake cannot annotate the buffer and action from the user is needed to -investigate and remedy the situation (@pxref{Backend exceptions}). +investigate and remedy the situation (@pxref{Troubleshooting}). @item @code{?} @tab There are no applicable Flymake backends for this buffer, thus Flymake @@ -166,17 +206,24 @@ and add a new backend (@pxref{Extending Flymake}). @end multitable -@node Backend exceptions -@section Backend exceptions +If you would like to customize the appearance of the mode-line, you +can use the variables @code{flymake-mode-line-format} and +@code{flymake-mode-line-counter-format} for that purpose. +@xref{Customizable variables}. + +@node Troubleshooting +@section Troubleshooting +@cindex troubleshooting @cindex backend exceptions @cindex disabled backends @cindex backends, disabled -Some backends may take longer than others to respond or complete, and -some may decide to @emph{disable} themselves if they are not suitable -for the current buffer or encounter some unavoidable problem. A -disabled backend is not tried again for future checks of the current -buffer. +As Flymake supports multiple simutaneously active external backends, +is becomes useful to monitor their status. For example, some backends +may take longer than others to respond or complete, and some may +decide to @emph{disable} themselves if they are not suitable for the +current buffer or encounter some unavoidable problem. A disabled +backend is not tried again for future checks of the current buffer. @findex flymake-reporting-backends @findex flymake-running-backends @@ -186,18 +233,23 @@ The commands @code{flymake-reporting-backends}, show the backends currently used and those which are disabled. @cindex reset disabled backends -Toggling @code{flymake-mode} off and on again, or invoking -@code{flymake-start} with a prefix argument is one way to reset the -disabled backend list, so that they will be tried again in the next check. +Sometimes, re-starting a backend that disabled itself is useful after +some external roadblock has been removed (for example after the user +installed a needed syntax-check program). Invoking +@code{flymake-start} with a prefix argument is a way to reset the +disabled backend list, so that they will be tried again in the next +check. Manually toggling @code{flymake-mode} off and on again also +works. @cindex logging @cindex flymake logging -Flymake also uses a simple logging facility for indicating important -points in the control flow. The logging facility sends logging -messages to the @file{*Flymake log*} buffer. The information logged -can be used for resolving various problems related to Flymake. For -convenience, a shortcut to this buffer can be found in Flymake's menu, -accessible from the top menu bar or just left of the status indicator. +Flymake uses a simple logging facility for indicating important points +in the control flow. The logging facility sends logging messages to +the @file{*Flymake log*} buffer. The logged information can be used +for resolving various problems related to Flymake. For convenience, a +shortcut to this buffer can be found in Flymake's menu, accessible +from the top menu bar or just left of the status indicator. The +command @code{flymake-switch-to-log-buffer} is another alternative. @vindex warning-minimum-log-level @vindex warning-minimum-level @@ -217,7 +269,7 @@ configuration of the Flymake user interface. Format to use for the Flymake mode line indicator. @item flymake-mode-line-counter-format -Mode-line construct for formatting Flymake diagnostic counters inside +mode line construct for formatting Flymake diagnostic counters inside the Flymake mode line indicator. @item flymake-no-changes-timeout @@ -270,10 +322,10 @@ Flymake can primarily be extended in one of two ways: @enumerate @item By changing the look and feel of the annotations produced by the -different backends. +different backends. @xref{Flymake error types}. @item -By adding a new buffer-checking backend. +By adding a new buffer-checking backend. @xref{Backend functions}. @end enumerate The following sections discuss each approach in detail. @@ -288,10 +340,12 @@ The following sections discuss each approach in detail. @cindex customizing error types @cindex error types, customization -To customize the appearance of error types, set properties on the -symbols associated with each diagnostic type. The standard diagnostic -symbols are @code{:error}, @code{:warning} and @code{:note} (though -the backend may define more, @pxref{Backend functions}). +To customize the appearance of error types, the user must set +properties on the symbols associated with each diagnostic type. + +The three standard diagnostic keyowrd symbols -- @code{:error}, +@code{:warning} and @code{:note} -- have pre-configured appearances. +However a backend may define more (@pxref{Backend functions}). The following properties can be set: @@ -489,7 +543,7 @@ manual}) or other asynchronous mechanisms. In any case, backend functions are expected to return quickly or signal an error, in which case the backend is disabled -(@pxref{Backend exceptions}). +(@pxref{Troubleshooting}). If the function returns, Flymake considers the backend to be @dfn{running}. If it has not done so already, the backend is expected @@ -540,6 +594,7 @@ reports targeting other parts of the buffer remain valid. @menu * Flymake utility functions:: +* Foreign and list-only diagnostics:: * An annotated example backend:: @end menu @@ -551,20 +606,26 @@ reports targeting other parts of the buffer remain valid. Before delivering them to Flymake, backends create diagnostic objects by calling the function @code{flymake-make-diagnostic}. -@deffn Function flymake-make-diagnostic buffer beg end type text -Make a Flymake diagnostic for @var{buffer}'s region from @var{beg} to -@var{end}. @var{type} is a diagnostic symbol (@pxref{Flymake error -types}), and @var{text} is a description of the problem detected in -this region. Currently, it is unspecified behavior to make -diagnostics for buffers other than the buffer that the Flymake backend -is responsible for. +@deffn Function flymake-make-diagnostic locus beg end type text &optional data +Make a Flymake diagnostic for the region of text in @var{locus}'s +delimited by @var{beg} and @var{end}. @var{type} is a diagnostic +symbol (@pxref{Flymake error types}), and @var{text} is a description +of the problem detected in this region. Most commonly @var{locus} is +the buffer object designating for the current buffer being +syntax-checked. However, it may be a string nameing a file relative +to the current working directory. @xref{Foreign and list-only +diagnostics}, for when this may be useful. Depending on the type of +@var{locus}, @var{beg} and @var{end} are both either buffer positions +or conses (@var{line} . @var{col}) which specify the line and column +of the diagnostic's start and end positions, respectively. @end deffn @cindex access diagnostic object These objects' properties can be accessed with the functions @code{flymake-diagnostic-backend}, @code{flymake-diagnostic-buffer}, @code{flymake-diagnostic-text}, @code{flymake-diagnostic-beg}, -@code{flymake-diagnostic-end} and @code{flymake-diagnostic-type}. +@code{flymake-diagnostic-end}, @code{flymake-diagnostic-type} and +@code{flymake-diagnostic-data}. Additionally, the function @code{flymake-diagnostics} will collect such objects in the region you specify. @@ -595,7 +656,7 @@ elisp, The Emacs Lisp Reference Manual}). @cindex add a log message For troubleshooting purposes, backends may record arbitrary exceptional or erroneous situations into the Flymake log -buffer (@pxref{Backend exceptions}): +buffer (@pxref{Troubleshooting}): @deffn Macro flymake-log level msg &optional args Log, at level @var{level}, the message @var{msg} formatted with @@ -604,6 +665,58 @@ Log, at level @var{level}, the message @var{msg} formatted with used to display the warning in Flymake's log buffer. @end deffn +@node Foreign and list-only diagnostics +@subsection Foreign and list-only diagnostics +@cindex create diagnostic object for other buffer + +It is possible for a given backend's implementation to use +@code{flymake-make-diagnostic} to create diagnostics for buffers or +files other than the ``source'' buffer where Flymake was enabled. For +instance, this is useful when a given backend has access to +information about the health of neighboring files that are not yet +visited or whose diagnostics depend on the current buffer's state. +There are two alternative ways to go about doing this: + +@enumerate + +@item +@cindex foreign diagnostics +@cindex domestic diagnostics +If the information about neighboring diagnostics is obtained +regularly, like when each syntax-checking iteration of a @code{.c} +file also reports a number of associated problems in an neighboring +@code{.h} file, it is better to create so-called ``foreign'' +diagnostics. + +This is done by passing a file name to @code{flymake-make-diagnostic} +(@pxref{Flymake utility functions}). Then, the resulting object is +simply reported along with the other ``domestic'' diagnostics for the +source buffer (@pxref{Backend functions}). When the neighboring file +is visited as a buffer and Flymake is active there, a number of +supplemental annotations will appear and automatically update whenever +as the ``source'' buffer is syntax-checked. + +@item +@cindex list-only diagnostics +@vindex flymake-list-only-diagnostics +If information about neighboring diagnostics is obtained infrequently, +like when running a time-consuming and sporadic check of a large +project, it is easier for the backend to modify the global variable +@code{flymake-list-only-diagnostics}. + +Flymake will look up this variable when asked to compile project-wide +lists of diagnostics. The backend should add one or more alist +entries that look like (@var{file-name} . @var{diags}). +@var{file-name} is the absolute name of the neighboring file presumed +not to be visited in Emacs already, as that would mean that that +buffer contains more up-to-date information on its diagnostics. +@var{diags} is a list of diagnostic objects. When the neighboring +file @var{file-name} is visited as a buffer and Flymake is activated +there, the ``list-only'' diagnostics will @emph{not} produce +annotations for @var{diags}, as Flymake assumes that the Flymake +activation in the new buffer will take care of that. +@end enumerate + @node An annotated example backend @subsection An annotated example backend @cindex example of backend @@ -661,7 +774,7 @@ Binding,,, elisp, The Emacs Lisp Reference Manual}) to be active. ;; Check that the process has indeed exited, as it might ;; be simply suspended. ;; - (when (eq 'exit (process-status proc)) + (when (memq (process-status proc) '(exit signal)) (unwind-protect ;; Only proceed if `proc' is the same as ;; `ruby--flymake-proc', which indicates that @@ -1038,7 +1151,7 @@ correct @file{file.h}. First matching master file found stops the search. The master file is then patched and saved to disk. In case no master file is found, syntax check is aborted, and corresponding status (@samp{!}) is reported in the mode line. -@xref{Syntax check statuses}. +@xref{Mode line status}. @node Getting the include directories @section Getting the include directories @@ -1064,7 +1177,7 @@ of every syntax check attempt. @section Locating the buildfile @cindex locating the buildfile @cindex buildfile, locating -@cindex Makefile, locating +@cindex makefile, locating The Proc backend can be configured to use different tools for performing syntax checks. For example, it can use direct compiler diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi index 28bee11d2bd..36c402ab35a 100644 --- a/doc/misc/gnus-faq.texi +++ b/doc/misc/gnus-faq.texi @@ -1443,7 +1443,7 @@ details. However, what you really want is the Insidious Big Brother Database bbdb. Get it from -@uref{http://bbdb.sourceforge.net/, bbdb's homepage}. +@uref{http://bbdb.sourceforge.net/, bbdb's website}. Now place the following in @file{~/.gnus.el}, to activate bbdb for Gnus: @example @@ -1559,7 +1559,7 @@ if you already use Gnus 5.10, if you still use 5.8.8 or "Request confirmation when replying to news." (interactive) (when (or (not (gnus-news-group-p gnus-newsgroup-name)) - (y-or-n-p "Really reply by mail to article author? ")) + (y-or-n-p "Really reply by mail to article author?")) ad-do-it)))) @end example @noindent diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index 9cdcf39ae10..796bb3bac84 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -2318,19 +2318,18 @@ commands listed in @ref{Browse Foreign Server} at hand. @itemx u @kindex S t @r{(Group)} @kindex u @r{(Group)} -@findex gnus-group-unsubscribe-current-group -@c @icon{gnus-group-unsubscribe} -Toggle subscription to the current group -(@code{gnus-group-unsubscribe-current-group}). +@findex gnus-group-toggle-subscription-at-point +@c @icon{gnus-group-toggle-subscription-at-point} +Toggle subscription to group under point +(@code{gnus-group-toggle-subscription-at-point}). @item S s @itemx U @kindex S s @r{(Group)} @kindex U @r{(Group)} -@findex gnus-group-unsubscribe-group -Prompt for a group to subscribe, and then subscribe it. If it was -subscribed already, unsubscribe it instead -(@code{gnus-group-unsubscribe-group}). +@findex gnus-group-toggle-subscription +Prompt for group, and toggle its subscription. +(@code{gnus-group-toggle-subscription}). @item S k @itemx C-k @@ -3736,10 +3735,10 @@ Enter the current group (@code{gnus-browse-select-group}). @item u @kindex u @r{(Browse)} -@findex gnus-browse-unsubscribe-current-group +@findex gnus-browse-toggle-subscription @vindex gnus-browse-subscribe-newsgroup-method -Unsubscribe to the current group, or, as will be the case here, -subscribe to it (@code{gnus-browse-unsubscribe-current-group}). You +Toggle subscription of the current group +(@code{gnus-browse-toggle-subscription}). You can affect the way the new group is entered into the Group buffer using the variable @code{gnus-browse-subscribe-newsgroup-method}. See @pxref{Subscription Methods} for available options. @@ -4146,6 +4145,25 @@ The default is 2. The @code{gnus-topic-display-empty-topics} says whether to display even topics that have no unread articles in them. The default is @code{t}. +@vindex gnus-topic-display-predicate +If @code{gnus-topic-display-predicate} is non-@code{nil}, it should be +a function that says whether the topic is to be displayed or not. +The function will be called with one parameter (the name of the topic) +and should return non-@code{nil} is the topic is to be displayed. + +For instance, if you don't even want to be reminded that work exists +outside of office hours, you can gather all the work-related groups +into a topic called @samp{"Work"}, and then say something like the +following: + +@lisp +(setq gnus-topic-display-predicate + (lambda (name) + (or (not (equal name "Work")) + (< 090000 + (string-to-number (format-time-string "%H%M%S")) + 170000)))) +@end lisp @node Topic Sorting @subsection Topic Sorting @@ -7112,20 +7130,15 @@ as 10, you might consider setting this variable to something sensible: (setq gnus-simplify-ignored-prefixes (concat "\\`\\[?\\(" - (mapconcat - 'identity - '("looking" - "wanted" "followup" "summary\\( of\\)?" - "help" "query" "problem" "question" - "answer" "reference" "announce" - "How can I" "How to" "Comparison of" - ;; ... - ) - "\\|") + (regexp-opt '("looking" + "wanted" "followup" "summary" "summary of" + "help" "query" "problem" "question" + "answer" "reference" "announce" + "How can I" "How to" "Comparison of" + ;; ... + )) "\\)\\s *\\(" - (mapconcat 'identity - '("for" "for reference" "with" "about") - "\\|") + (regexp-opt '("for" "for reference" "with" "about")) "\\)?\\]?:?[ \t]*")) @end lisp @@ -9356,6 +9369,12 @@ Use html2text---a simple @acronym{HTML} converter included with Gnus. @end table +@item W D F +@kindex W D F @r{(Summary)} +@findex gnus-article-toggle-fonts +Toggle proportional fonts for @acronym{HTML} articles. This temporarily +changes the @code{shr-use-fonts} variable in the current article buffer. + @item W b @kindex W b @r{(Summary)} @findex gnus-article-add-buttons @@ -9824,6 +9843,13 @@ Gravatarify the @code{From} header (@code{gnus-treat-from-gravatar}). Gravatarify all mail headers (i.e., @code{Cc}, @code{To}) (@code{gnus-treat-from-gravatar}). +@item W D e +@kindex W D e @r{(Summary)} +@findex gnus-article-emojize-symbols +Some symbols have both a non-emoji presentation and an emoji +presentation. This command will make Gnus choose the emoji presentation +(@code{gnus-article-emojize-symbols}). + @item W D D @kindex W D D @r{(Summary)} @findex gnus-article-remove-images @@ -12166,6 +12192,7 @@ controlling variable is a predicate list, as described above. @vindex gnus-treat-capitalize-sentences @vindex gnus-treat-overstrike @vindex gnus-treat-strip-cr +@vindex gnus-treat-emojize-symbols @vindex gnus-treat-strip-headers-in-body @vindex gnus-treat-strip-leading-blank-lines @vindex gnus-treat-strip-multiple-blank-lines @@ -12218,6 +12245,7 @@ possible but those listed are probably sufficient for most people. @item gnus-treat-capitalize-sentences (t, integer) @item gnus-treat-overstrike (t, integer) @item gnus-treat-strip-cr (t, integer) +@item gnus-treat-emojize-symbols (t, integer) @item gnus-treat-strip-headers-in-body (t, integer) @item gnus-treat-strip-leading-blank-lines (t, first, integer) @item gnus-treat-strip-multiple-blank-lines (t, integer) @@ -13851,11 +13879,9 @@ present in this hook. @item nntp-authinfo-function @vindex nntp-authinfo-function @findex nntp-send-authinfo -@vindex nntp-authinfo-file This function will be used to send @samp{AUTHINFO} to the @acronym{NNTP} server. The default function is @code{nntp-send-authinfo}, which looks -through your @file{~/.authinfo} (or whatever you've set the -@code{nntp-authinfo-file} variable to) for applicable entries. If none +through your @file{~/.authinfo} for applicable entries. If none are found, it will prompt you for a login name and a password. The format of the @file{~/.authinfo} file is (almost) the same as the @code{ftp} @file{~/.netrc} file, which is defined in the @code{ftp} @@ -14517,7 +14543,8 @@ this should be set to @code{anonymous}. If this variable isn't set, the normal login methods will be used. If you wish to specify a specific login method to be used, you can set this variable to either @code{login} (the traditional @acronym{IMAP} login method), -@code{plain} or @code{cram-md5}. +@code{plain}, @code{cram-md5} or @code{xoauth2}. (The latter method +requires using the @file{oauth2.el} library.) @item nnimap-expunge When to expunge deleted messages. If @code{never}, deleted articles @@ -21873,7 +21900,7 @@ bound to mairix searches and are automatically updated. Mairix is a tool for indexing and searching words in locally stored mail. It was written by Richard Curnow and is licensed under the GPL@. Mairix comes with most popular GNU/Linux distributions, but it also -runs under Windows (with cygwin), macOS and Solaris. The homepage can +runs under Windows (with cygwin), macOS and Solaris. The website can be found at @uref{http://www.rpcurnow.force9.co.uk/mairix/index.html} @@ -22702,6 +22729,13 @@ output lines in the various buffers. There's quite a lot of them. Fortunately, they all use the same syntax, so there's not that much to be annoyed by. +Gnus does not use the font locking machinery used by most modes in +Emacs, so switching @code{font-lock-mode} on in the Gnus +group/summary/article buffers usually doesn't do anything +useful---instead it'll just mess up the faces that Gnus has already +put in the buffer. (This is also the case for other minor modes that +use the font locking machinery, like @code{whitespace-mode}.) + Here's an example format spec (from the group buffer): @samp{%M%S%5y: %(%g%)\n}. We see that it is indeed extremely ugly, and that there are lots of percentages everywhere. @@ -26292,7 +26326,7 @@ Fortunately, setting up the Gnus registry is pretty easy: @end lisp This adds registry saves to Gnus newsrc saves (which happen on exit -and when you press @kbd{s} from the @file{*Group*} buffer. It also +and when you press @kbd{s} from the @file{*Group*} buffer). It also adds registry calls to article actions in Gnus (copy, move, etc.)@: so it's not easy to undo the initialization. See @code{gnus-registry-initialize} for the gory details. @@ -26861,9 +26895,10 @@ but at the common table.@* If you want to investigate the person responsible for this outrage, you can point your (feh!) web browser to -@uref{https://quimby.gnus.org/}. This is also the primary -distribution point for the new and spiffy versions of Gnus, and is -known as The Site That Destroys Newsrcs And Drives People Mad. +@uref{https://quimby.gnus.org/}. This used to be the primary +distribution point for the new and spiffy versions of Gnus, and was +known as The Site That Destroys Newsrcs And Drives People Mad, but +these days Gnus is developed in the Emacs repository. During the first extended alpha period of development, the new Gnus was called ``(ding) Gnus''. @dfn{(ding)} is, of course, short for diff --git a/doc/misc/mairix-el.texi b/doc/misc/mairix-el.texi index a571c744870..e57b5ed5422 100644 --- a/doc/misc/mairix-el.texi +++ b/doc/misc/mairix-el.texi @@ -60,6 +60,8 @@ database. * Using:: List of interactive functions * Extending:: Support your favorite mail reader! * GNU Free Documentation License:: The license for this documentation. +* Function Index: Function Index. +* Variable Index: Variable Index. @end menu @node About @@ -68,7 +70,7 @@ database. Mairix is a tool for indexing and searching words in locally stored mail. It was written by Richard Curnow and is licensed under the GPL@. Mairix comes with most popular GNU/Linux distributions, but it also -runs under Windows (with cygwin), macOS and Solaris. The homepage can +runs under Windows (with cygwin), macOS and Solaris. The website can be found at @uref{http://www.rpcurnow.force9.co.uk/mairix/index.html} @@ -339,4 +341,14 @@ And that's it! @appendix GNU Free Documentation License @include doclicense.texi +@node Function Index +@unnumbered Function Index + +@printindex fn + +@node Variable Index +@unnumbered Variable Index + +@printindex vr + @bye diff --git a/doc/misc/message.texi b/doc/misc/message.texi index d2353e6cec6..4136ad859f7 100644 --- a/doc/misc/message.texi +++ b/doc/misc/message.texi @@ -1699,14 +1699,15 @@ result is inserted. @cindex Sv @cindex Re Responses to messages have subjects that start with @samp{Re: }. This -is @emph{not} an abbreviation of the English word ``response'', but is -Latin, and means ``in response to''. Some illiterate nincompoops have -failed to grasp this fact, and have ``internationalized'' their software -to use abominations like @samp{Aw: } (``antwort'') or @samp{Sv: } -(``svar'') instead, which is meaningless and evil. However, you may -have to deal with users that use these evil tools, in which case you may -set this variable to a regexp that matches these prefixes. Myself, I -just throw away non-compliant mail. +is @emph{not} an abbreviation of the English word ``response'', but it +comes from the Latin ``res'', and means ``in the matter of''. Some +illiterate nincompoops have failed to grasp this fact, and have +``internationalized'' their software to use abominations like +@samp{Aw: } (``antwort'') or @samp{Sv: } (``svar'') instead, which is +meaningless and evil. However, you may have to deal with users that +use these evil tools, in which case you may set this variable to a +regexp that matches these prefixes. Myself, I just throw away +non-compliant mail. Here's an example of a value to deal with these headers when responding to a message: @@ -2084,7 +2085,7 @@ This optional header will be computed by Message. @vindex user-mail-address @findex system-name @cindex Sun -@cindex i-did-not-set--mail-host-address--so-tickle-me +@cindex mail-host-address-is-not-set This required header will be generated by Message. A unique ID will be created based on the date, time, user name (for the local part) and the domain part. For the domain part, message will look (in this order) at diff --git a/doc/misc/mh-e.texi b/doc/misc/mh-e.texi index 62540284312..bc788ebae09 100644 --- a/doc/misc/mh-e.texi +++ b/doc/misc/mh-e.texi @@ -7383,8 +7383,8 @@ The name of the MH sequence for ticked messages (default: @samp{'tick}). @item mh-update-sequences-after-mh-show-flag On means flush MH sequences to disk after message is shown (default: @samp{on}). -@item mh-whitelist-preserves-sequences-flag -On means that sequences are preserved when messages are whitelisted +@item mh-allowlist-preserves-sequences-flag +On means that sequences are preserved when messages are allowlisted (default: @samp{on}). @end vtable @@ -7540,17 +7540,17 @@ Marshall Rose once wrote a paper on MH entitled, @cite{How to process could be entitled, @cite{How to process 1000 spams a day and still get some real work done}. -@cindex blacklisting +@cindex blocklisting @cindex ham @cindex viruses -@cindex whitelisting +@cindex allowlisting @cindex worms We use the terms @dfn{junk mail} and @dfn{spam} interchangeably for any unwanted message which includes spam, @dfn{viruses}, and @dfn{worms}. The opposite of spam is @dfn{ham}. The act of classifying -a sender as one who sends junk mail is called @dfn{blacklisting}; the -opposite is called @dfn{whitelisting}. +a sender as one who sends junk mail is called @dfn{blocklisting}; the +opposite is called @dfn{allowlisting}. @table @kbd @kindex J ? @@ -7560,14 +7560,14 @@ Display cheat sheet for the commands of the current prefix in minibuffer (@code{mh-prefix-help}). @c ------------------------- @kindex J b -@findex mh-junk-blacklist +@findex mh-junk-blocklist @item J b -Blacklist range as spam (@code{mh-junk-blacklist}). +Blocklist range as spam (@code{mh-junk-blocklist}). @c ------------------------- -@kindex J w -@findex mh-junk-whitelist -@item J w -Whitelist range as ham (@code{mh-junk-whitelist}). +@kindex J a +@findex mh-junk-allowlist +@item J a +Allowlist range as ham (@code{mh-junk-allowlist}). @c ------------------------- @item @code{mh-spamassassin-identify-spammers} Identify spammers who are repeat offenders. @@ -7597,31 +7597,31 @@ The following option in the @samp{mh-sequences} customization group is also available. @vtable @code -@item mh-whitelist-preserves-sequences-flag -On means that sequences are preserved when messages are whitelisted +@item mh-allowlist-preserves-sequences-flag +On means that sequences are preserved when messages are allowlisted (default: @samp{on}). @end vtable The following hooks are available. @vtable @code -@item mh-blacklist-msg-hook -Hook run by @kbd{J b} (@code{mh-junk-blacklist}) after marking each -message for blacklisting (default: @code{nil}). +@item mh-blocklist-msg-hook +Hook run by @kbd{J b} (@code{mh-junk-blocklist}) after marking each +message for blocklisting (default: @code{nil}). @c ------------------------- -@item mh-whitelist-msg-hook -Hook run by @kbd{J w} (@code{mh-junk-whitelist}) after marking each -message for whitelisting (default @samp{nil}). +@item mh-allowlist-msg-hook +Hook run by @kbd{J a} (@code{mh-junk-allowlist}) after marking each +message for allowlisting (default @samp{nil}). @end vtable The following faces are available. @vtable @code -@item mh-folder-blacklisted -Blacklisted message face. +@item mh-folder-blocklisted +Blocklisted message face. @c ------------------------- -@item mh-folder-whitelisted -Whitelisted message face +@item mh-folder-allowlisted +Allowlisted message face @end vtable @cindex SpamProbe @@ -7647,21 +7647,21 @@ example, you have both SpamAssassin and bogofilter installed and you want to use bogofilter, then you can set this option to @samp{Bogofilter}. -@findex mh-junk-blacklist +@findex mh-junk-blocklist @kindex J b @vindex mh-junk-disposition -The command @kbd{J b} (@code{mh-junk-blacklist}) trains the spam +The command @kbd{J b} (@code{mh-junk-blocklist}) trains the spam program in use with the content of the range (@pxref{Ranges}) and then handles the message(s) as specified by the option @code{mh-junk-disposition}. By default, this option is set to @samp{Delete Spam} but you can also specify the name of the folder which is useful for building a corpus of spam for training purposes. -@findex mh-junk-whitelist -@kindex J w +@findex mh-junk-allowlist +@kindex J a -In contrast, the command @kbd{J w} (@code{mh-junk-whitelist}) +In contrast, the command @kbd{J a} (@code{mh-junk-allowlist}) reclassifies a range of messages (@pxref{Ranges}) as ham if it were incorrectly classified as spam. It then refiles the message into the @file{+inbox} folder. @@ -7671,12 +7671,12 @@ incorrectly classified as spam. It then refiles the message into the @cindex @samp{Previous-Sequence} MH profile component @cindex sequence, @samp{cur} @cindex sequence, @samp{Previous-Sequence} -@vindex mh-whitelist-preserves-sequences-flag +@vindex mh-allowlist-preserves-sequences-flag If a message is in any sequence (except @samp{Previous-Sequence:} and -@samp{cur}) when it is whitelisted, then it will still be in those +@samp{cur}) when it is allowlisted, then it will still be in those sequences in the destination folder. If this behavior is not desired, -then turn off the option @code{mh-whitelist-preserves-sequences-flag}. +then turn off the option @code{mh-allowlist-preserves-sequences-flag}. @cindex @file{*MH-E Log*} @cindex buffers, @file{*MH-E Log*} @@ -7687,7 +7687,7 @@ By default, the programs are run in the foreground, but this can be slow when junking large numbers of messages. If you have enough memory or don't junk that many messages at the same time, you might try turning on the option @code{mh-junk-background}. @footnote{Note that -the option @code{mh-junk-background} is used as the @code{display} +the option @code{mh-junk-background} is used as the @code{destination} argument in the call to @code{call-process}. Therefore, turning on this option means setting its value to @samp{0}. You can also set its value to @samp{t} to direct the programs' output to the @file{*MH-E @@ -7756,33 +7756,33 @@ the @samp{+spam} folder for later review. The major weakness of rules-based filters is a plethora of false positives so it is worthwhile to check. -@findex mh-junk-blacklist -@findex mh-junk-whitelist +@findex mh-junk-blocklist +@findex mh-junk-allowlist @kindex J b -@kindex J w +@kindex J a If SpamAssassin classifies a message incorrectly, or is unsure, you can -use the MH-E commands @kbd{J b} (@code{mh-junk-blacklist}) and -@kbd{J w} (@code{mh-junk-whitelist}). +use the MH-E commands @kbd{J b} (@code{mh-junk-blocklist}) and +@kbd{J a} (@code{mh-junk-allowlist}). @cindex @command{sa-learn} @cindex @file{.spamassassin/user_prefs} @cindex files, @file{.spamassassin/user_prefs} -The command @kbd{J b} (@code{mh-junk-blacklist}) adds a +The command @kbd{J b} (@code{mh-junk-blocklist}) adds a @samp{blacklist_from} entry to @file{~/spamassassin/user_prefs}, deletes the message, and sends the message to the Razor, so that others might not see this spam. If the @command{sa-learn} command is available, the message is also recategorized as spam. -The command@kbd{J w} (@code{mh-junk-whitelist}) adds a +The command@kbd{J a} (@code{mh-junk-allowlist}) adds a @samp{whitelist_from} rule to @samp{~/.spamassassin/user_prefs}. If the @command{sa-learn} command is available, the message is also recategorized as ham. Over time, you'll observe that the same host or domain occurs repeatedly in the @samp{blacklist_from} entries, so you might think -that you could avoid future spam by blacklisting all mail from a +that you could avoid future spam by blocklisting all mail from a particular domain. The utility function @code{mh-spamassassin-identify-spammers} helps you do precisely that. This function displays a frequency count of the hosts and domains in @@ -7796,7 +7796,7 @@ blacklist_from *@@*amazingoffersdirect2u.com @end smallexample In versions of SpamAssassin (2.50 and on) that support a Bayesian -classifier, @kbd{J b} @code{(mh-junk-blacklist}) uses the program +classifier, @kbd{J b} @code{(mh-junk-blocklist}) uses the program @command{sa-learn} to recategorize the message as spam. Neither MH-E, nor SpamAssassin, rebuilds the database after adding words, so you will need to run @samp{sa-learn --rebuild} periodically. This can be @@ -7856,14 +7856,14 @@ spam/. spam/unsure/. @end smallexample -@findex mh-junk-blacklist -@findex mh-junk-whitelist +@findex mh-junk-blocklist +@findex mh-junk-allowlist @kindex J b -@kindex J w +@kindex J a If bogofilter classifies a message incorrectly, or is unsure, you can -use the MH-E commands @kbd{J b} (@code{mh-junk-blacklist}) and @kbd{J -w} (@code{mh-junk-whitelist}) to update bogofilter's training. +use the MH-E commands @kbd{J b} (@code{mh-junk-blocklist}) and +@kbd{J a} (@code{mh-junk-allowlist}) to update bogofilter's training. The @cite{Bogofilter FAQ} suggests that you run the following occasionally to shrink the database: @@ -7908,14 +7908,14 @@ SCORE=| spamprobe receive spam/. @end smallexample -@findex mh-junk-blacklist -@findex mh-junk-whitelist +@findex mh-junk-blocklist +@findex mh-junk-allowlist @kindex J b -@kindex J w +@kindex J a If SpamProbe classifies a message incorrectly, you can use the MH-E -commands @kbd{J b} (@code{mh-junk-blacklist}) and @kbd{J w} -(@code{mh-junk-whitelist}) to update SpamProbe's training. +commands @kbd{J b} (@code{mh-junk-blocklist}) and @kbd{J a} +(@code{mh-junk-allowlist}) to update SpamProbe's training. @subheading Other Things You Can Do @@ -8114,7 +8114,7 @@ width is 4, so you would use @samp{(mh-set-cmd-note 4)}. @vindex mh-scan-format-nmh The default setting for @code{mh-scan-format-file} is @samp{Use MH-E -scan Format}. This means that the format string will be taken from the +scan Format}. This means that the format string will be taken from either @code{mh-scan-format-mh} or @code{mh-scan-format-nmh} depending on whether MH or nmh (or GNU mailutils MH) is in use. This setting also enables you to turn on the option @@ -8816,8 +8816,8 @@ hands several times since then. Jim Larus wanted to do something similar for GNU Emacs, and ended up completely rewriting it that same year. In 1989, Stephen Gildea picked it up and added many improvements. Bill Wohler then took over in 2000 and moved its -development to @uref{https://sourceforge.net/, SourceForge} where it -lives today. +development to @uref{https://sourceforge.net/, SourceForge}. +Since 2016, MH-E development occurs within the Emacs repository. @menu * From Brian Reid:: diff --git a/doc/misc/modus-themes.org b/doc/misc/modus-themes.org index 5bb230f892a..675144d5177 100644 --- a/doc/misc/modus-themes.org +++ b/doc/misc/modus-themes.org @@ -5,9 +5,9 @@ #+options: ':t toc:nil author:t email:t num:t #+startup: content -#+macro: stable-version 1.5.0 -#+macro: release-date 2021-07-15 -#+macro: development-version 1.6.0-dev +#+macro: stable-version 1.6.0 +#+macro: release-date 2021-09-29 +#+macro: development-version 1.7.0-dev #+macro: file @@texinfo:@file{@@$1@@texinfo:}@@ #+macro: space @@texinfo:@: @@ #+macro: kbd @@texinfo:@kbd{@@$1@@texinfo:}@@ @@ -383,6 +383,7 @@ this manual. modus-themes-no-mixed-fonts nil modus-themes-subtle-line-numbers nil modus-themes-success-deuteranopia t + modus-themes-tabs-accented t modus-themes-inhibit-reload t ; only applies to `customize-set-variable' and related modus-themes-fringes nil ; {nil,'subtle,'intense} @@ -395,9 +396,8 @@ this manual. ;; Options for `modus-themes-mode-line' are either nil, or a list ;; that can combine any of `3d' OR `moody', `borderless', - ;; `accented'. The variable's doc string shows all possible - ;; combinations. - modus-themes-mode-line '(3d accented) + ;; `accented', `padded'. + modus-themes-mode-line '(padded accented borderless) ;; Options for `modus-themes-syntax' are either nil (the default), ;; or a list of properties that may include any of those symbols: @@ -443,6 +443,7 @@ this manual. modus-themes-org-agenda ; this is an alist: read the manual or its doc string '((header-block . (variable-pitch scale-title)) (header-date . (grayscale workaholic bold-today)) + (event . (accented scale-small)) (scheduled . uniform) (habit . traffic-light-deuteranopia)) @@ -473,7 +474,7 @@ Symbol: ~modus-themes-inhibit-reload~ Possible values: -1. ~nil~ +1. ~nil~ 2. ~t~ (default) By default, customizing a theme-related user option through the Custom @@ -803,6 +804,7 @@ effect, color, and border visibility: - ~moody~ + ~accented~ + ~borderless~ ++ ~padded~ The default (a nil value or an empty list) is a two-dimensional rectangle with a border around it. The active and the inactive @@ -829,6 +831,13 @@ the same as the background, effectively creating some padding. The ~accented~ property ensures that the active mode line uses a colored background instead of the standard shade of gray. +The ~padded~ property increases the apparent height of the mode line. +This is done by applying box effects and combining them with an +underline and overline. To ensure that the underline is placed at the +bottom, set ~x-underline-at-descent-line~ to non-nil. The ~padded~ property +has no effect when the ~moody~ property is also used, because Moody +already applies its own padding. + Combinations of any of those properties are expressed as a list, like in these examples: @@ -843,7 +852,7 @@ The order in which the properties are set is not significant. In user configuration files the form may look like this: #+begin_src emacs-lisp -(setq modus-themes-prompts '(borderless accented)) +(setq modus-themes-mode-line '(borderless accented)) #+end_src Note that Moody does not expose any faces that the themes could style @@ -868,6 +877,27 @@ Furthermore, because Moody expects an underline and overline instead of a box style, it is advised to set ~x-underline-at-descent-line~ to a non-nil value. +** Option for accented background in tab interfaces +:properties: +:alt_title: Tab style +:description: Toggle accented background for tabs +:custom_id: h:27cef8f5-dc4e-4c93-ba41-b899e650d936 +:end: +#+vindex: modus-themes-tabs-accented + +Symbol: ~modus-themes-tabs-accented~ + +Possible values: + ++ ~nil~ (default) ++ ~t~ + +By default, all tab interfaces use backgrounds which are shades of gray. +When this option is set to non-nil, the backgrounds become colorful. + +This affects the built-in ~tab-bar-mode~ and ~tab-line-mode~, as well as the +Centaur tabs package. + ** Option for completion framework aesthetics :properties: :alt_title: Completion UIs @@ -1305,6 +1335,7 @@ all possible combinations: (setq modus-themes-org-agenda '((header-block . (variable-pitch scale-title)) (header-date . (grayscale workaholic bold-today)) + (event . (accented scale-small)) (scheduled . uniform) (habit . traffic-light))) #+end_src @@ -1346,6 +1377,11 @@ the following properties: - ~bold-today~ to apply a bold typographic weight to the current date; - ~bold-all~ to render all date headings in a bold weight. +- ~scale-heading~ increases the height of the date headings to the value + of ~modus-themes-scale-1~ (which is the first step in the scale for + regular headings). +- ~underline-today~ applies an underline to the current date while + removing the background it has by default. For example: @@ -1355,6 +1391,31 @@ For example: (header-date . (grayscale bold-all)) (header-date . (grayscale workaholic)) (header-date . (grayscale workaholic bold-today)) +(header-date . (grayscale workaholic bold-today scale-heading)) +#+end_src + +An ~event~ key covers events from the diary and other entries that derive +from a symbolic expression or sexp (e.g. phases of the moon, holidays). +This key accepts a list of values. By default (a nil value or an empty +list) those have a gray foreground, while sexp events are additionally +presented using slanted text (italics). The properties that can form a +list of possible values are: + +- ~scale-small~ reduces the height of the entries to the value of the user + option ~modus-themes-scale-small~ (0.9 the height of the main font size + by default). +- ~accented~ applies an accent value to the event's foreground, replacing + the original gray. +- ~italic~ adds a slant to the font's forms (italic or oblique forms, + depending on the typeface). + +For example: + +#+begin_src emacs-lisp +(event . nil) +(event . (scale-small)) +(event . (scale-small accented)) +(event . (scale-small accented italic)) #+end_src A ~scheduled~ key applies to tasks with a scheduled date. By default (a @@ -1416,6 +1477,7 @@ Putting it all together, the alist can look like this: #+begin_src emacs-lisp '((header-block . (scale-title variable-pitch)) (header-date . (grayscale workaholic bold-today)) + (event . (accented scale-small)) (scheduled . uniform) (habit . traffic-light)) @@ -1423,6 +1485,7 @@ Putting it all together, the alist can look like this: (setq modus-themes-org-agenda '((header-block . (scale-title variable-pitch)) (header-date . (grayscale workaholic bold-today)) + (event . (accented scale-small)) (scheduled . uniform) (habit . traffic-light))) #+end_src @@ -1574,7 +1637,8 @@ resource for finding a consistent scale: modus-themes-scale-2 1.1 modus-themes-scale-3 1.15 modus-themes-scale-4 1.2 - modus-themes-scale-title 1.3) + modus-themes-scale-title 1.3 + modus-themes-scale-small 0.9) #+end_src As for the application of that scale, the variables that range from @@ -1593,6 +1657,11 @@ supposed to signify the primary header. Similarly, the Org Agenda's structure headings are not part of a recognisable scale and so they also get ~modus-themes-scale-title~ ([[#h:68f481bc-5904-4725-a3e6-d7ecfa7c3dbc][Option for Org agenda constructs]]). +Similarly ~modus-themes-scale-small~ is not applied to regular headings, +but reserved for special contexts where the user is presented with an +option to use a smaller font height than the base size. It is only +implemented for the Org agenda. + Users who wish to maintain scaled headings for the normal syntax while preventing special headings from standing out, can assign a value of =1.0= to ~modus-themes-scale-title~ to make it the same as body text (or @@ -2321,8 +2390,8 @@ Using the above has an immediate effect, as it reloads the active Modus theme. The =my-modus-themes-saturate= function stores new color values in the -variables =modus-themes-operandi-color-overrides= and -=modus-themes-vivendi-color-overrides=, meaning that it undoes changes +variables ~modus-themes-operandi-color-overrides~ and +~modus-themes-vivendi-color-overrides~, meaning that it undoes changes implemented by the user on individual colors. To have both automatic saturation adjustment across the board and retain per-case edits to the palette, some tweaks to the above function are required. For example: @@ -2574,9 +2643,9 @@ two): #+begin_src emacs-lisp (setq org-todo-keyword-faces - '(("MEET" . '(font-lock-preprocessor-face org-todo)) - ("STUDY" . '(font-lock-variable-name-face org-todo)) - ("WRITE" . '(font-lock-type-face org-todo)))) + '(("MEET" . '(bold org-todo)) + ("STUDY" . '(warning org-todo)) + ("WRITE" . '(shadow org-todo)))) #+end_src This will refashion the keywords you specify, while letting the other @@ -2607,7 +2676,7 @@ configuration of the priority cookies: #+begin_src emacs-lisp (setq org-priority-faces - '((?A . '(org-scheduled-today org-priority)) + '((?A . '(bold org-priority)) (?B . org-priority) (?C . '(shadow org-priority)))) #+end_src @@ -2700,7 +2769,7 @@ A couple of examples (rounded numbers): ;; Pure black with pure green (modus-themes-contrast "#000000" "#00ff00") ;; => 15.3 -;; That is is a highly accessible combo +;; That is a highly accessible combo #+end_src It does not matter which color value comes first. The ratio is always @@ -2904,6 +2973,7 @@ have lots of extensions, so the "full support" may not be 100% true… + alert + all-the-icons + annotate ++ ansi-color + anzu + apropos + apt-sources-list @@ -2943,6 +3013,7 @@ have lots of extensions, so the "full support" may not be 100% true… + css-mode + csv-mode + ctrlf ++ cursor-flash + custom (what you get with {{{kbd(M-x customize)}}}) + dap-mode + dashboard (emacs-dashboard) @@ -2977,6 +3048,7 @@ have lots of extensions, so the "full support" may not be 100% true… + eldoc-box + elfeed + elfeed-score ++ elpher + embark + emms + enh-ruby-mode (enhanced-ruby-mode) @@ -3033,6 +3105,7 @@ have lots of extensions, so the "full support" may not be 100% true… + highlight-escape-sequences (~hes-mode~) + highlight-indentation + highlight-numbers ++ highlight-parentheses ([[#h:24bab397-dcb2-421d-aa6e-ec5bd622b913][Note on highlight-parentheses.el]]) + highlight-symbol + highlight-tail + highlight-thing @@ -3225,6 +3298,7 @@ These do not require any extra styles because they are configured to inherit from some basic faces or their dependencies which are directly supported by the themes. ++ bufler + counsel-notmuch + edit-indirect + evil-owl @@ -3234,8 +3308,13 @@ supported by the themes. + perl-mode + php-mode + rjsx-mode ++ side-hustle + swift-mode + tab-bar-echo-area ++ tide ++ vertico-indexed ++ vertico-mouse ++ vertico-quick * Notes on individual packages :properties: @@ -3415,6 +3494,135 @@ and have the foreground be indistinguishable from it. For example: [[#h:51ba3547-b8c8-40d6-ba5a-4586477fd4ae][Face specs at scale using the themes' palette]]. +** Note on highlight-parentheses.el +:PROPERTIES: +:CUSTOM_ID: h:24bab397-dcb2-421d-aa6e-ec5bd622b913 +:END: + +The =highlight-parentheses= package provides contextual coloration of +surrounding parentheses, highlighting only those which are around the +point. The package expects users to customize the applicable colors on +their own by configuring certain variables. + +To make the Modus themes work as expected with this, we need to use some +of the techniques that are discussed at length in the various +"Do-It-Yourself" (DIY) sections, which provide insight into the more +advanced customization options of the themes. + +[[#h:f4651d55-8c07-46aa-b52b-bed1e53463bb][Advanced customization (do-it-yourself)]]. + +In the following example, we are assuming that the user wants to (i) +re-use color variables provided by the themes, (ii) be able to retain +their tweaks while switching between ~modus-operandi~ and ~modus-vivendi~, +and (iii) have the option to highlight either the foreground of the +parentheses or the background as well. + +We start by defining our own variable, which will serve as a toggle +between foreground and background coloration styles: + +#+begin_src emacs-lisp +(defvar my-highlight-parentheses-use-background t + "Prefer `highlight-parentheses-background-colors'.") +#+end_src + +Then we can update our preference with this: + +#+begin_src emacs-lisp +;; Set to nil to disable backgrounds. +(setq my-highlight-parentheses-use-background nil) +#+end_src + +To re-use colors from the themes, we must wrap our code in the +~modus-themes-with-colors~ macro. Our implementation must interface with +the variables ~highlight-parentheses-background-colors~ and/or +~highlight-parentheses-colors~. + +So we can have something like this (the doc string of +~modus-themes-with-colors~ explains where the names of the colors can be +found): + +#+begin_src emacs-lisp +(modus-themes-with-colors + ;; Our preference for setting either background or foreground + ;; styles, depending on `my-highlight-parentheses-use-background'. + (if my-highlight-parentheses-use-background + + ;; Here we set color combinations that involve both a background + ;; and a foreground value. + (setq highlight-parentheses-background-colors (list cyan-refine-bg + magenta-refine-bg + green-refine-bg + yellow-refine-bg) + highlight-parentheses-colors (list cyan-refine-fg + magenta-refine-fg + green-refine-fg + yellow-refine-fg)) + + ;; And here we pass only foreground colors while disabling any + ;; backgrounds. + (setq highlight-parentheses-colors (list green-intense + magenta-intense + blue-intense + red-intense) + highlight-parentheses-background-colors nil))) + +;; Include this if you also want to make the parentheses bold: +(set-face-attribute 'highlight-parentheses-highlight nil :inherit 'bold) + +;; Our changes must be evaluated before enabling the relevant mode, so +;; this comes last. +(global-highlight-parentheses-mode 1) +#+end_src + +For our changes to persist while switching between the Modus themes, we +need to include them in a function which can then get passed to +~modus-themes-after-load-theme-hook~. This is the complete +implementation: + +#+begin_src emacs-lisp +;; Configurations for `highlight-parentheses': +(require 'highlight-parentheses) + +(defvar my-highlight-parentheses-use-background t + "Prefer `highlight-parentheses-background-colors'.") + +(setq my-highlight-parentheses-use-background nil) ; Set to nil to disable backgrounds + +(defun my-modus-themes-highlight-parentheses () + (modus-themes-with-colors + ;; Our preference for setting either background or foreground + ;; styles, depending on `my-highlight-parentheses-use-background'. + (if my-highlight-parentheses-use-background + + ;; Here we set color combinations that involve both a background + ;; and a foreground value. + (setq highlight-parentheses-background-colors (list cyan-refine-bg + magenta-refine-bg + green-refine-bg + yellow-refine-bg) + highlight-parentheses-colors (list cyan-refine-fg + magenta-refine-fg + green-refine-fg + yellow-refine-fg)) + + ;; And here we pass only foreground colors while disabling any + ;; backgrounds. + (setq highlight-parentheses-colors (list green-intense + magenta-intense + blue-intense + red-intense) + highlight-parentheses-background-colors nil))) + + ;; Include this if you also want to make the parentheses bold: + (set-face-attribute 'highlight-parentheses-highlight nil :inherit 'bold) + + ;; Our changes must be evaluated before enabling the relevant mode, so + ;; this comes last. + (global-highlight-parentheses-mode 1)) + +(add-hook 'modus-themes-after-load-theme-hook #'my-modus-themes-highlight-parentheses) +#+end_src + ** Note on mmm-mode.el background colors :properties: :custom_id: h:99cf0d6c-e478-4e26-9932-3bf3427d13f6 @@ -3520,7 +3728,7 @@ With 8 colors: :desaturations '(0) ; do not change---may lower the contrast ratio :lightens '(0) ; same :colors (modus-themes-with-colors - (list fg-special-cold + (list blue magenta magenta-alt-other cyan-alt-other @@ -3540,10 +3748,10 @@ to the themes' default aesthetic: :desaturations '(0) ; do not change---may lower the contrast ratio :lightens '(0) ; same :colors (modus-themes-with-colors - (list fg-main - cyan-alt-other + (list blue + magenta magenta-alt-other - magenta))) + green-alt))) #+end_src If you need to apply desaturation and lightening, you can use what the @@ -3958,7 +4166,7 @@ latter case. ~modus-operandi~ is best used outdoors or in a room that either gets direct sunlight or has plenty of light. Whereas ~modus-vivendi~ works better when there is not a lot of sunshine or the room has a source of -light, preferably a faint or warm one. It is possible to use +light that is preferably a faint and/or warm one. It is possible to use ~modus-operandi~ at night and ~modus-vivendi~ during the day, though that will depend on several variables, such as one's overall perception of color, the paint on the walls and how that contributes to the impression @@ -4005,9 +4213,7 @@ in which you can contribute to their ongoing development. :end: #+cindex: Sources of the themes -The ~modus-operandi~ and ~modus-vivendi~ themes are built into Emacs. -Currently they are in Emacs' git main branch (trunk), which is tracking -the next development release target. +The ~modus-operandi~ and ~modus-vivendi~ themes are built into Emacs 28. The source code of the themes is [[https://gitlab.com/protesilaos/modus-themes/][available on Gitlab]], for the time being. A [[https://github.com/protesilaos/modus-themes/][mirror on Github]] is also on offer. @@ -4118,31 +4324,31 @@ The Modus themes are a collective effort. Every bit of work matters. + Contributions to code or documentation :: Anders Johansson, Basil L.{{{space()}}} Contovounesios, Carlo Zancanaro, Eli Zaretskii, Fritz Grabo, - Kostadin Ninev, Madhavan Krishnan, Markus Beppler, Matthew Stevenson, - Mauro Aranda, Nicolas De Jaeghere, Philip Kaludercic, Rudolf - Adamkovič, Shreyas Ragavan, Stefan Kangas, Vincent Murphy, Xinglu - Chen. - -+ Ideas and user feedback :: Aaron Jensen, Adam Spiers, Adrian Manea, - Alex Griffin, Alex Peitsinis, Alexey Shmalko, Alok Singh, Anders - Johansson, André Alexandre Gomes, Arif Rezai, Basil L.{{{space()}}} - Contovounesios, Burgess Chang, Christian Tietze, Christopher Dimech, - Damien Cassou, Daniel Mendler, Dario Gjorgjevski, David Edmondson, - Davor Rotim, Divan Santana, Emanuele Michele Alberto Monterosso, - Farasha Euker, Gautier Ponsinet, Gerry Agbobada, Gianluca Recchia, - Gustavo Barros, Hörmetjan Yiltiz, Ilja Kocken, Iris Garcia, Jeremy - Friesen, Jerry Zhang, John Haman, Joshua O'Connor, Kevin Fleming, - Kévin Le Gouguec, Kostadin Ninev, Len Trigg, Manuel Uberti, Mark - Burton, Markus Beppler, Mauro Aranda, Michael Goldenberg, Morgan - Smith, Murilo Pereira, Nicky van Foreest, Nicolas De Jaeghere, Paul - Poloskov, Pengji Zhang, Pete Kazmier, Peter Wu, Philip Kaludercic, - Pierre Téchoueyres, Roman Rudakov, Ryan Phillips, Rudolf Adamkovič, - Sam Kleinman, Shreyas Ragavan, Simon Pugnet, Tassilo Horn, Thibaut - Verron, Thomas Heartman, Trey Merkley, Togan Muftuoglu, Toon Claes, - Uri Sharf, Utkarsh Singh, Vincent Foley. As well as users: Ben, - CsBigDataHub1, Emacs Contrib, Eugene, Fourchaux, Fredrik, Moesasji, - Nick, TheBlob42, Trey, bepolymathe, doolio, fleimgruber, iSeeU, - jixiuf, okamsn, pRot0ta1p. + Kévin Le Gouguec, Kostadin Ninev, Madhavan Krishnan, Markus Beppler, + Matthew Stevenson, Mauro Aranda, Nicolas De Jaeghere, Philip + Kaludercic, Rudolf Adamkovič, Stephen Gildea, Shreyas Ragavan, Stefan + Kangas, Vincent Murphy, Xinglu Chen. + ++ Ideas and user feedback :: Aaron Jensen, Adam Porter, Adam Spiers, + Adrian Manea, Alex Griffin, Alex Peitsinis, Alexey Shmalko, Alok + Singh, Anders Johansson, André Alexandre Gomes, Arif Rezai, Basil + L.{{{space()}}} Contovounesios, Burgess Chang, Christian Tietze, Christopher + Dimech, Damien Cassou, Daniel Mendler, Dario Gjorgjevski, David + Edmondson, Davor Rotim, Divan Santana, Eliraz Kedmi, Emanuele Michele + Alberto Monterosso, Farasha Euker, Feng Shu, Gautier Ponsinet, Gerry + Agbobada, Gianluca Recchia, Gustavo Barros, Hörmetjan Yiltiz, Ilja + Kocken, Iris Garcia, Jeremy Friesen, Jerry Zhang, John Haman, Joshua + O'Connor, Kevin Fleming, Kévin Le Gouguec, Kostadin Ninev, Len Trigg, + Manuel Uberti, Mark Burton, Markus Beppler, Mauro Aranda, Michael + Goldenberg, Morgan Smith, Murilo Pereira, Nicky van Foreest, Nicolas + De Jaeghere, Paul Poloskov, Pengji Zhang, Pete Kazmier, Peter Wu, + Philip Kaludercic, Pierre Téchoueyres, Roman Rudakov, Ryan Phillips, + Rudolf Adamkovič, Sam Kleinman, Shreyas Ragavan, Simon Pugnet, Tassilo + Horn, Thibaut Verron, Thomas Heartman, Trey Merkley, Togan Muftuoglu, + Toon Claes, Uri Sharf, Utkarsh Singh, Vincent Foley. As well as + users: Ben, CsBigDataHub1, Emacs Contrib, Eugene, Fourchaux, Fredrik, + Moesasji, Nick, TheBlob42, Trey, bepolymathe, doolio, fleimgruber, + iSeeU, jixiuf, okamsn, pRot0ta1p. + Packaging :: Basil L.{{{space()}}} Contovounesios, Eli Zaretskii, Glenn Morris, Mauro Aranda, Richard Stallman, Stefan Kangas (core Emacs), @@ -4178,6 +4384,7 @@ of this sort): + [[https://protesilaos.com/codelog/2020-12-27-modus-themes-review-rainbow-delimiters/][Modus themes: review rainbow-delimiters faces]] (2020-12-27) + [[https://protesilaos.com/codelog/2021-01-11-modus-themes-review-select-faint-colours/][Modus themes: review of select "faint" colours]] (2021-01-11) + [[https://protesilaos.com/codelog/2021-02-25-modus-themes-diffs-deuteranopia/][The Modus themes now cover deuteranopia in diffs]] (2021-02-25) ++ [[https://protesilaos.com/codelog/2021-06-02-modus-themes-org-agenda/][Introducing the variable modus-themes-org-agenda]] (2021-06-02) And here are the canonical sources of this project's documentation: diff --git a/doc/misc/org.org b/doc/misc/org.org index f072b5e00e0..17fd2dc39f7 100644 --- a/doc/misc/org.org +++ b/doc/misc/org.org @@ -82,11 +82,8 @@ probably do not need to install it. Most users will simply activate Org and begin exploring its many features. If, for one reason or another, you want to install Org on top of this -pre-packaged version, there are three ways to do it: - -- by using the Emacs package system; -- by downloading Org as an archive; or -- by using Org's git repository. +pre-packaged version, you can use the Emacs package system or clone +Org's git repository. We *strongly recommend* sticking to a single installation method. @@ -106,32 +103,6 @@ visited, i.e., where no Org built-in function have been loaded. Otherwise autoload Org functions will mess up the installation. #+end_quote -If you want to use Org's package repository, check out the [[https://orgmode.org/elpa.html][Org ELPA -page]]. - -*** Downloading Org as an archive -:PROPERTIES: -:UNNUMBERED: notoc -:END: - -You can download Org latest release from [[https://orgmode.org/][Org's website]]. In this case, -make sure you set the load path correctly in your Emacs init file: - -#+begin_src emacs-lisp -(add-to-list 'load-path "~/path/to/orgdir/lisp") -#+end_src - -The downloaded archive contains contributed libraries that are not -included in Emacs. If you want to use them, add the =contrib/= -directory to your load path: - -#+begin_src emacs-lisp -(add-to-list 'load-path "~/path/to/orgdir/contrib/lisp" t) -#+end_src - -Optionally, you can compile the files and/or install them in your -system. Run =make help= to list compilation and installation options. - *** Using Org's git repository :PROPERTIES: :UNNUMBERED: notoc @@ -141,7 +112,7 @@ You can clone Org's repository and install Org like this: #+begin_example $ cd ~/src/ -$ git clone https://code.orgmode.org/bzg/org-mode.git +$ git clone https://git.savannah.gnu.org/git/emacs/org-mode.git $ cd org-mode/ $ make autoloads #+end_example @@ -161,6 +132,16 @@ list of compilation/installation options. For more detailed explanations on Org's build system, please check the Org Build System page on [[https://orgmode.org/worg/dev/org-build-system.html][Worg]]. +*** Installing Org's contributed packages +:PROPERTIES: +:UNNUMBERED: notoc +:END: + +Org's repository used to contain =contrib/= directory for add-ons +contributed by others. As of Org 9.5, the directory has bee moved to +this new dedicated [[https://git.sr.ht/~bzg/org-contrib][org-contrib]] repository, which you can install +separately. + ** Activation :PROPERTIES: :DESCRIPTION: How to activate Org for certain buffers. @@ -189,9 +170,9 @@ to globally available keys, like the ones reserved for users (see please modify the keys to your own liking. #+begin_src emacs-lisp -(global-set-key (kbd "C-c l") 'org-store-link) -(global-set-key (kbd "C-c a") 'org-agenda) -(global-set-key (kbd "C-c c") 'org-capture) +(global-set-key (kbd "C-c l") #'org-store-link) +(global-set-key (kbd "C-c a") #'org-agenda) +(global-set-key (kbd "C-c c") #'org-capture) #+end_src #+cindex: Org mode, turning on @@ -273,7 +254,6 @@ shown below. ;; Add latest Org mode to load path. (add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp")) -(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t)) #+end_src If an error occurs, a "backtrace" can be very useful---see below on @@ -344,7 +324,7 @@ conventions: - =boss=, =ARCHIVE= :: - Tags are case-sensitive. User-defined tags are written in + Tags are case-sensitive. User-defined tags are usually written in lowercase; built-in tags with special meaning are written as they should appear in the document, usually with all capitals. @@ -577,6 +557,10 @@ buffer: ,#+STARTUP: overview ,#+STARTUP: content ,#+STARTUP: showall +,#+STARTUP: show2levels +,#+STARTUP: show3levels +,#+STARTUP: show4levels +,#+STARTUP: show5levels ,#+STARTUP: showeverything #+end_example @@ -656,10 +640,10 @@ The following commands jump to other headlines in the buffer. where you can use the following keys to find your destination: #+attr_texinfo: :columns 0.3 0.7 - | {{{kbd(TAB)}}} | Cycle visibility. | + | {{{kbd(TAB)}}} | Cycle visibility. | | {{{kbd(DOWN)}}} / {{{kbd(UP)}}} | Next/previous visible headline. | - | {{{kbd(RET)}}} | Select this location. | - | {{{kbd(/)}}} | Do a Sparse-tree search | + | {{{kbd(RET)}}} | Select this location. | + | {{{kbd(/)}}} | Do a Sparse-tree search | #+texinfo: @noindent The following keys work if you turn off ~org-goto-auto-isearch~ @@ -667,9 +651,9 @@ The following commands jump to other headlines in the buffer. #+attr_texinfo: :columns 0.3 0.7 | {{{kbd(n)}}} / {{{kbd(p)}}} | Next/previous visible headline. | | {{{kbd(f)}}} / {{{kbd(b)}}} | Next/previous headline same level. | - | {{{kbd(u)}}} | One level up. | + | {{{kbd(u)}}} | One level up. | | {{{kbd(0)}}} ... {{{kbd(9)}}} | Digit argument. | - | {{{kbd(q)}}} | Quit. | + | {{{kbd(q)}}} | Quit. | #+vindex: org-goto-interface #+texinfo: @noindent @@ -932,16 +916,16 @@ commands can be accessed through a dispatcher: #+kindex: C-c / / #+findex: org-occur #+vindex: org-remove-highlights-with-change - Prompts for a regexp and shows a sparse tree with all matches. If - the match is in a headline, the headline is made visible. If the - match is in the body of an entry, headline and body are made - visible. In order to provide minimal context, also the full - hierarchy of headlines above the match is shown, as well as the - headline following the match. Each match is also highlighted; the - highlights disappear when the buffer is changed by an editing - command, or by pressing {{{kbd(C-c C-c)}}}[fn:8]. When called with - a {{{kbd(C-u)}}} prefix argument, previous highlights are kept, so - several calls to this command can be stacked. + Prompts for a regexp (see [[*Regular Expressions]]) and shows a sparse + tree with all matches. If the match is in a headline, the headline + is made visible. If the match is in the body of an entry, headline + and body are made visible. In order to provide minimal context, + also the full hierarchy of headlines above the match is shown, as + well as the headline following the match. Each match is also + highlighted; the highlights disappear when the buffer is changed by + an editing command, or by pressing {{{kbd(C-c C-c)}}}[fn:8]. When + called with a {{{kbd(C-u)}}} prefix argument, previous highlights + are kept, so several calls to this command can be stacked. - {{{kbd(M-g n)}}} or {{{kbd(M-g M-n)}}} (~next-error~) :: @@ -1371,9 +1355,8 @@ you, configure the option ~org-table-auto-blank-field~. Re-align the table, move to the next field. Creates a new row if necessary. -- {{{kbd(C-c SPC)}}} (~org-table-blank-field~) :: +- {{{kbd(M-x org-table-blank-field)}}} :: - #+kindex: C-c SPC #+findex: org-table-blank-field Blank the field at point. @@ -1805,7 +1788,7 @@ mode with {{{kbd(M-x orgtbl-mode)}}}. To turn it on by default, for example in Message mode, use #+begin_src emacs-lisp -(add-hook 'message-mode-hook 'turn-on-orgtbl) +(add-hook 'message-mode-hook #'turn-on-orgtbl) #+end_src Furthermore, with some special setup, it is possible to maintain @@ -2074,6 +2057,14 @@ variable ~org-calc-default-modes~. Fraction and symbolic modes of Calc. +- =u= :: + + Units simplification mode of Calc. Calc is also a symbolic + calculator and is capable of working with values having a unit, + represented with numerals followed by a unit string in Org table + cells. This mode instructs Calc to simplify the units in the + computed expression before returning the result. + - =T=, =t=, =U= :: Duration computations in Calc or Lisp, [[*Durations and time values]]. @@ -2169,38 +2160,54 @@ It is also possible to write a formula in Emacs Lisp. This can be useful for string manipulation and control structures, if Calc's functionality is not enough. -If a formula starts with a single-quote followed by an opening -parenthesis, then it is evaluated as a Lisp form. The evaluation -should return either a string or a number. Just as with Calc -formulas, you can specify modes and a ~printf~ format after -a semicolon. +A formula is evaluated as a Lisp form when it starts with a +single-quote followed by an opening parenthesis. Cell table +references are interpolated into the Lisp form before execution. The +evaluation should return either a string or a number. Evaluation +modes and a ~printf~ format used to render the returned values can be +specified after a semicolon. + +By default, references are interpolated as literal Lisp strings: the +field content is replaced in the Lisp form stripped of leading and +trailing white space and surrounded in double-quotes. For example: -With Emacs Lisp forms, you need to be conscious about the way field -references are interpolated into the form. By default, a reference is -interpolated as a Lisp string (in double-quotes) containing the field. -If you provide the =N= mode switch, all referenced elements are -numbers---non-number fields will be zero---and interpolated as Lisp -numbers, without quotes. If you provide the =L= flag, all fields are -interpolated literally, without quotes. For example, if you want a -reference to be interpreted as a string by the Lisp form, enclose the -reference operator itself in double-quotes, like ="$3"=. Ranges are -inserted as space-separated fields, so you can embed them in list or -vector syntax. +: '(concat $1 $2) -Here are a few examples---note how the =N= mode is used when we do -computations in Lisp: +#+texinfo: @noindent +concatenates the content of columns 1 and column 2. -- ='(concat (substring $1 1 2) (substring $1 0 1) (substring $1 2))= :: +When the =N= flag is used, all referenced elements are parsed as +numbers and interpolated as Lisp numbers, without quotes. Fields that +cannot be parsed as numbers are interpolated as zeros. For example: - Swap the first two characters of the content of column 1. +: '(+ $1 $2);N -- ='(+ $1 $2);N= :: +#+texinfo: @noindent +adds columns 1 and 2, equivalent to Calc's =$1+$2=. Ranges are +inserted as space-separated fields, so they can be embedded in list or +vector syntax. For example: - Add columns 1 and 2, equivalent to Calc's =$1+$2=. +: '(apply '+ '($1..$4));N -- ='(apply '+ '($1..$4));N= :: +#+texinfo: @noindent +computes the sum of columns 1 to 4, like Calc's =vsum($1..$4)=. + +When the =L= flag is used, all fields are interpolated literally: the +cell content is replaced in the Lisp form stripped of leading and +trailing white space and without quotes. If a reference is intended +to be interpreted as a string by the Lisp form, the reference operator +itself should be enclosed in double-quotes, like ="$3"=. The =L= flag +is useful when strings and numbers are used in the same Lisp form. For +example: - Compute the sum of columns 1 to 4, like Calc's =vsum($1..$4)=. +: '(substring "$1" $2 $3);L + +#+texinfo: @noindent +extracts the part of the string in column 1 between the character +positions specified in the integers in column 2 and 3 and it is easier +to read than the equivalent: + +: '(substring $1 (string-to-number $2) (string-to-number $3)) *** Durations and time values :PROPERTIES: @@ -2797,7 +2804,7 @@ either graphically or in ASCII art. #+cindex: @samp{PLOT}, keyword Org Plot can produce 2D and 3D graphs of information stored in Org -tables using [[http://www.gnuplot.info/][Gnuplot]] and [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][Gnuplot mode]]. To see this in action, ensure +tables using [[https://www.gnuplot.info/][Gnuplot]] and [[http://cars9.uchicago.edu/~ravel/software/gnuplot-mode.html][Gnuplot mode]]. To see this in action, ensure that you have both Gnuplot and Gnuplot mode installed on your system, then call {{{kbd(C-c \quot g)}}} or {{{kbd(M-x org-plot/gnuplot)}}} on the following table. @@ -2813,6 +2820,19 @@ following table. | Morelia | 257.56 | 17.67 | #+end_example +Org Plot supports a range of plot types, and provides the ability to add more. +For example, a radar plot can be generated like so: +#+begin_example +,#+PLOT: title:"An evaluation of plaintext document formats" transpose:yes type:radar min:0 max:4 +| Format | Fine-grained-control | Initial Effort | Syntax simplicity | Editor Support | Integrations | Ease-of-referencing | Versatility | +|-------------------+----------------------+----------------+-------------------+----------------+--------------+---------------------+-------------| +| Word | 2 | 4 | 4 | 2 | 3 | 2 | 2 | +| LaTeX | 4 | 1 | 1 | 3 | 2 | 4 | 3 | +| Org Mode | 4 | 2 | 3.5 | 1 | 4 | 4 | 4 | +| Markdown | 1 | 3 | 3 | 4 | 3 | 3 | 1 | +| Markdown + Pandoc | 2.5 | 2.5 | 2.5 | 3 | 3 | 3 | 2 | +#+end_example + Notice that Org Plot is smart enough to apply the table's headers as labels. Further control over the labels, type, content, and appearance of plots can be exercised through the =PLOT= keyword @@ -2843,9 +2863,15 @@ For more information and examples see the [[https://orgmode.org/worg/org-tutoria the third and fourth columns. Defaults to graphing all other columns aside from the =ind= column. +- transpose :: + + When =y=, =yes=, or =t= attempt to transpose the table data before + plotting. Also recognises the shorthand option =trans=. + - =type= :: - Specify whether the plot is =2d=, =3d=, or =grid=. + Specify the type of the plot, by default one of =2d=, =3d=, =radar=, or =grid=. + Available types can be customised with ~org-plot/preset-plot-types~. - =with= :: @@ -2872,6 +2898,27 @@ For more information and examples see the [[https://orgmode.org/worg/org-tutoria When plotting =3d= or =grid= types, set this to =t= to graph a flat mapping rather than a =3d= slope. +- min :: + + Provides a minimum axis value that may be used by a plot type. + Implicitly assumes the =y= axis is being referred to. Can + explicitly provide a value for a either the =x= or =y= axis with + =xmin= and =ymin=. + +- max :: + + Provides a maximum axis value that may be used by a plot type. + Implicitly assumes the =y= axis is being referred to. Can + explicitly provide a value for a either the =x= or =y= axis with + =xmax= and =ymax=. + +- ticks :: + + Provides a desired number of axis ticks to display, that may be used + by a plot type. If none is given a plot type that requires ticks + will use ~org--plot/sensible-tick-num~ to try to determine a good + value. + - =timefmt= :: Specify format of Org mode timestamps as they will be parsed by @@ -3113,14 +3160,14 @@ Here is the full set of built-in link types: - =file= :: - File links. File name may be remote, absolute, or relative. + File links. File name may be remote, absolute, or relative. - Additionally, you can specify a line number, or a text search. - In Org files, you may link to a headline name, a custom ID, or a - code reference instead. + Additionally, you can specify a line number, or a text search. + In Org files, you may link to a headline name, a custom ID, or a + code reference instead. - As a special case, "file" prefix may be omitted if the file name - is complete, e.g., it starts with =./=, or =/=. + As a special case, "file" prefix may be omitted if the file name + is complete, e.g., it starts with =./=, or =/=. - =attachment= :: @@ -3224,9 +3271,10 @@ options: #+cindex: VM links #+cindex: Wanderlust links On top of these built-in link types, additional ones are available -through the =contrib/= directory (see [[*Installation]]). For example, -these links to VM or Wanderlust messages are available when you load -the corresponding libraries from the =contrib/= directory: +through the =org-contrib= repository (see [[*Installation]]). For +example, these links to VM or Wanderlust messages are available when +you load the corresponding libraries from the =org-contrib= +repository: | =vm:folder= | VM folder link | | =vm:folder#id= | VM message link | @@ -3291,8 +3339,9 @@ current buffer: =ID= property for the link[fn:29]. So using this command in Org buffers potentially creates two links: a human-readable link from the custom ID, and one that is globally unique and works even if the - entry is moved from file to file. Later, when inserting the link, - you need to decide which one to use. + entry is moved from file to file. The =ID= property can be either a + UUID (default) or a timestamp, depending on ~org-id-method~. Later, + when inserting the link, you need to decide which one to use. - /Email/News clients: VM, Rmail, Wanderlust, MH-E, Gnus/ :: @@ -3474,8 +3523,8 @@ generally, act on links. #+begin_src emacs-lisp (with-eval-after-load 'org - (define-key org-mode-map (kbd "M-n") 'org-next-link) - (define-key org-mode-map (kbd "M-p") 'org-previous-link)) + (define-key org-mode-map (kbd "M-n") #'org-next-link) + (define-key org-mode-map (kbd "M-p") #'org-previous-link)) #+end_src ** Using Links Outside Org @@ -3516,7 +3565,7 @@ replacement text. Here is an example: #+begin_src emacs-lisp (setq org-link-abbrev-alist '(("bugzilla" . "http://10.1.2.9/bugzilla/show_bug.cgi?id=") - ("Nu Html Checker" . "https://validator.w3.org/nu/?doc=%h") + ("Nu Html Checker" . "https://validator.w3.org/nu/?doc=%h") ("duckduckgo" . "https://duckduckgo.com/?q=%s") ("omap" . "http://nominatim.openstreetmap.org/search?q=%s&polygon=1") ("ads" . "https://ui.adsabs.harvard.edu/search/q=%20author%3A\"%s\""))) @@ -3616,10 +3665,10 @@ link, together with explanations for each: - =/REGEXP/= :: - Do a regular expression search for {{{var(REGEXP)}}}. This uses the - Emacs command ~occur~ to list all matches in a separate window. If - the target file is in Org mode, ~org-occur~ is used to create - a sparse tree with the matches. + Do a regular expression search for {{{var(REGEXP)}}} (see [[*Regular + Expressions]]). This uses the Emacs command ~occur~ to list all + matches in a separate window. If the target file is in Org mode, + ~org-occur~ is used to create a sparse tree with the matches. As a degenerate case, a file link with an empty file name can be used to search the current file. For example, =[[file:::find me]]= does @@ -3944,9 +3993,9 @@ interpretation, but it means the same as =#+TODO=, or A setup for using several sets in parallel would be: #+begin_example -,#+TODO: TODO | DONE -,#+TODO: REPORT BUG KNOWNCAUSE | FIXED -,#+TODO: | CANCELED +,#+TODO: TODO(t) | DONE(d) +,#+TODO: REPORT(r) BUG(b) KNOWNCAUSE(k) | FIXED(f) +,#+TODO: | CANCELED(c) #+end_example #+cindex: completion, of option keywords @@ -4070,7 +4119,7 @@ checkboxes is blocked from switching to DONE. If you need more complex dependency structures, for example dependencies between entries in different trees or files, check out -the contributed module =org-depend.el=. +the module =org-depend.el= in the =org-contrib= repository. ** Progress Logging :PROPERTIES: @@ -4158,10 +4207,6 @@ example, with the setting '((sequence "TODO(t)" "WAIT(w@/!)" "|" "DONE(d!)" "CANCELED(c@)"))) #+end_src -#+texinfo: @noindent -To record a timestamp without a note for TODO keywords configured with -=@=, just type {{{kbd(C-c C-c)}}} to enter a blank note when prompted. - #+vindex: org-log-done You not only define global TODO keywords and fast access keys, but also request that a time is recorded when the entry is set to =DONE=, @@ -4181,6 +4226,9 @@ to a buffer: : #+TODO: TODO(t) WAIT(w@/!) | DONE(d!) CANCELED(c@) +To record a timestamp without a note for TODO keywords configured with +=@=, just type {{{kbd(C-c C-c)}}} to enter a blank note when prompted. + #+cindex: @samp{LOGGING}, property In order to define logging settings that are local to a subtree or a single item, define a =LOGGING= property in this entry. Any @@ -4443,7 +4491,7 @@ all children are done, you can use the following setup: (let (org-log-done org-log-states) ; turn off logging (org-todo (if (= n-not-done 0) "DONE" "TODO")))) -(add-hook 'org-after-todo-statistics-hook 'org-summary-todo) +(add-hook 'org-after-todo-statistics-hook #'org-summary-todo) #+end_src Another possibility is the use of checkboxes to identify (a hierarchy @@ -4794,9 +4842,10 @@ In this interface, you can also use the following special keys: #+kindex: TAB Enter a tag in the minibuffer, even if the tag is not in the - predefined list. You can complete on all tags present in the - buffer. You can also add several tags: just separate them with - a comma. + predefined list. You can complete on all tags present in the buffer + and globally pre-defined tags from ~org-tag-alist~ and + ~org-tag-persistent-alist~. You can also add several tags: just + separate them with a comma. - {{{kbd(SPC)}}} :: @@ -4931,8 +4980,9 @@ mutually exclusive. Furthermore, the members of a group tag can also be regular expressions, creating the possibility of a more dynamic and rule-based -tag structure. The regular expressions in the group must be specified -within curly brackets. Here is an expanded example: +tag structure (see [[*Regular Expressions]]). The regular expressions in +the group must be specified within curly brackets. Here is an +expanded example: #+begin_example ,#+TAGS: [ Vision : {V@.+} ] @@ -5274,7 +5324,7 @@ single property: tree is created with all entries that define this property with the given value. If you enclose the value in curly braces, it is interpreted as a regular expression and matched against the property - values. + values (see [[*Regular Expressions]]). ** Property Inheritance :PROPERTIES: @@ -5737,8 +5787,8 @@ block. If there is a =TBLFM= keyword after the table, the table is recalculated automatically after an update. An alternative way to capture and process property values into a table -is provided by Eric Schulte's =org-collector.el=, which is -a contributed package[fn:58]. It provides a general API to collect +is provided by Eric Schulte's =org-collector.el=, which is a package +in =org-contrib=[fn:58]. It provides a general API to collect properties from entries in a certain scope, and arbitrary Lisp expressions to process these values before inserting them into a table or a dynamic block. @@ -6022,6 +6072,7 @@ dash(es) as the separator in the former case and use =+= as the separator in the latter case, e.g.: | =11am-1:15pm= | \rArr{} 11:00-13:15 | +| =11h-13h15= | \rArr{} same as above | | =11am--1:15pm= | \rArr{} same as above | | =11am+2:15= | \rArr{} same as above | @@ -7197,6 +7248,16 @@ special command: Copying works like refiling, except that the original note is not deleted. +- {{{kbd(C-c C-M-w)}}} (~org-refile-reverse~) :: + + #+kindex: C-c C-M-w + #+findex: org-refile-reverse + Works like refiling, except that it temporarily toggles how the + value of ~org-reverse-note-order~ applies to the current buffer. So + if ~org-refile~ would append the entry as the last entry under the + target header, ~org-refile-reverse~ will prepend it as the first + entry, and vice-versa. + ** Archiving :PROPERTIES: :DESCRIPTION: What to do with finished products. @@ -7746,6 +7807,9 @@ Now lets look at the elements of a template definition. Each entry in Do not save the target file after finishing the capture. + - ~:refile-targets :: Temporarily set ~org-refile-targets~ to the + value of this property. + **** Template expansion :PROPERTIES: :DESCRIPTION: Filling in information about time and context. @@ -7804,6 +7868,10 @@ here: Like =%a=, but only insert the literal link. +- =%L= :: + + Like =%l=, but without brackets (the link content itself). + - =%c= :: Current kill ring head. @@ -7859,7 +7927,8 @@ here: - =%^{PROP}p= :: - Prompt the user for a value for property {{{var(PROP)}}}. + Prompt the user for a value for property {{{var(PROP)}}}. You may + specify a default value with =%^{PROP|default}=. - =%^{PROMPT}= :: @@ -7912,7 +7981,7 @@ patches. Then you would configure this option like this: #+begin_src emacs-lisp (setq org-capture-templates-contexts - '(("p" (in-mode . "message-mode")))) + '(("p" ((in-mode . "message-mode"))))) #+end_src You can also tell that the command key {{{kbd(p)}}} should refer to @@ -7920,7 +7989,7 @@ another template. In that case, add this command key like this: #+begin_src emacs-lisp (setq org-capture-templates-contexts - '(("p" "q" (in-mode . "message-mode")))) + '(("p" "q" ((in-mode . "message-mode"))))) #+end_src See the docstring of the variable for more information. @@ -8199,7 +8268,7 @@ To make Org mode take care of versioning of attachments for you, add the following to your Emacs config: #+begin_src emacs-lisp - (require 'org-attach-git) +(require 'org-attach-git) #+end_src *** Attach from Dired @@ -8259,7 +8328,7 @@ variable has detailed information. With the following #+begin_src emacs-lisp (setq org-feed-alist '(("Slashdot" - "http://rss.slashdot.org/Slashdot/slashdot" + "https://rss.slashdot.org/Slashdot/slashdot" "~/txt/org/feeds.org" "Slashdot Entries"))) #+end_src @@ -8847,8 +8916,9 @@ only tags. #+cindex: regular expressions, with tags search Instead of a tag, you may also specify a regular expression enclosed -in curly braces. For example, =work+{^boss.*}= matches headlines that -contain the tag =:work:= and any tag /starting/ with =boss=. +in curly braces (see [[*Regular Expressions]]). For example, +=work+{^boss.*}= matches headlines that contain the tag =:work:= and +any tag /starting/ with =boss=. #+cindex: group tags, as regular expressions Group tags (see [[*Tag Hierarchy]]) are expanded as regular expressions. @@ -8888,7 +8958,7 @@ to test the value of a property. Here is a complex example: #+begin_example +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2 - +With={Sarah|Denny}+SCHEDULED>="<2008-10-11>" + +With={Sarah\|Denny}+SCHEDULED>="<2008-10-11>" #+end_example #+texinfo: @noindent @@ -8918,7 +8988,7 @@ So the search string in the example finds entries tagged =work= but not =boss=, which also have a priority value =A=, a =Coffee= property with the value =unlimited=, an =EFFORT= property that is numerically smaller than 2, a =With= property that is matched by the regular -expression =Sarah|Denny=, and that are scheduled on or after October +expression =Sarah\|Denny=, and that are scheduled on or after October 11, 2008. You can configure Org mode to use property inheritance during @@ -9296,16 +9366,16 @@ filter elements are accumulated. selects entries with category =work= and effort estimates below 10 minutes, and deselects entries with tag =John= or matching the - regexp =plot=. You can leave =+= out if that does not lead to - ambiguities. The sequence of elements is arbitrary. The filter - syntax assumes that there is no overlap between categories and tags. - Otherwise, tags take priority. If you reply to the prompt with the - empty string, all filtering is removed. If a filter is specified, - it replaces all current filters. But if you call the command with - a double prefix argument, or if you add an additional =+= (e.g., - =++work=) to the front of the string, the new filter elements are - added to the active ones. A single prefix argument applies the - entire filter in a negative sense. + regexp =plot= (see [[*Regular Expressions]]). You can leave =+= out if + that does not lead to ambiguities. The sequence of elements is + arbitrary. The filter syntax assumes that there is no overlap + between categories and tags. Otherwise, tags take priority. If you + reply to the prompt with the empty string, all filtering is removed. + If a filter is specified, it replaces all current filters. But if + you call the command with a double prefix argument, or if you add an + additional =+= (e.g., =++work=) to the front of the string, the new + filter elements are added to the active ones. A single prefix + argument applies the entire filter in a negative sense. - {{{kbd(|)}}} (~org-agenda-filter-remove-all~) :: @@ -10863,7 +10933,7 @@ pretty output for a number of export back-ends. Org mode can contain LaTeX math fragments, and it supports ways to process these for several export back-ends. When exporting to LaTeX, the code is left as it is. When exporting to HTML, Org can use either -[[http://www.mathjax.org][MathJax]] (see [[*Math formatting in HTML export]]) or transcode the math +[[https://www.mathjax.org][MathJax]] (see [[*Math formatting in HTML export]]) or transcode the math into images (see [[*Previewing LaTeX fragments]]). LaTeX fragments do not need any special marking at all. The following @@ -10968,7 +11038,7 @@ current buffer with {{{kbd(M-x org-cdlatex-mode)}}}, or for all Org files with #+begin_src emacs-lisp -(add-hook 'org-mode-hook 'turn-on-org-cdlatex) +(add-hook 'org-mode-hook #'turn-on-org-cdlatex) #+end_src When this mode is enabled, the following features are present (for @@ -11304,7 +11374,7 @@ The following command handles footnotes: #+attr_texinfo: :columns 0.1 0.9 | {{{kbd(s)}}} | Sort the footnote definitions by reference sequence. | | {{{kbd(r)}}} | Renumber the simple =fn:N= footnotes. | - | {{{kbd(S)}}} | Short for first {{{kbd(r)}}}, then {{{kbd(s)}}} action. | + | {{{kbd(S)}}} | Short for first {{{kbd(r)}}}, then {{{kbd(s)}}} action. | | {{{kbd(n)}}} | Rename all footnotes into a =fn:1= ... =fn:n= sequence. | | {{{kbd(d)}}} | Delete the footnote at point, including definition and references. | @@ -11361,7 +11431,7 @@ Users can install libraries for additional formats from the Emacs packaging system. For easy discovery, these packages have a common naming scheme: ~ox-NAME~, where {{{var(NAME)}}} is a format. For example, ~ox-koma-letter~ for /koma-letter/ back-end. More libraries -can be found in the =contrib/= directory (see [[*Installation]]). +can be found in the =org-contrib= repository (see [[*Installation]]). #+vindex: org-export-backends Org only loads back-ends for the following formats by default: ASCII, @@ -11452,7 +11522,7 @@ further alter what is exported, and how. Toggle visible-only export. This is useful for exporting only certain parts of an Org document by adjusting the visibility of - particular headings. + particular headings. See also [[*Sparse Trees]]. ** Export Settings :PROPERTIES: @@ -11961,7 +12031,7 @@ example #+texinfo: @noindent becomes -: Rose is red, violet's blue. Life's ordered: Org assists you. +: Rose is red, violet's blue. Life's ordered: Org assists you. As a special case, Org parses any replacement text starting with =(eval= as an Emacs Lisp expression and evaluates it accordingly. @@ -12527,7 +12597,7 @@ compatible with XHTML 1.0 strict standard. #+findex: org-html-export-to-html Export as HTML file with a =.html= extension. For =myfile.org=, Org - exports to =myfile.html=, overwriting without warning. {{{kbd{C-c + exports to =myfile.html=, overwriting without warning. {{{kbd(C-c C-e h o)}}} exports to HTML and opens it in a web browser. - {{{kbd(C-c C-e h H)}}} (~org-html-export-as-html~) :: @@ -12552,6 +12622,9 @@ settings described in [[*Export Settings]]. multiple =DESCRIPTION= lines. The exporter takes care of wrapping the lines properly. + The exporter includes a number of other meta tags, which can be customized + by modifying ~org-html-meta-tags~. + - =HTML_DOCTYPE= :: #+cindex: @samp{HTML_DOCTYPE}, keyword @@ -12693,8 +12766,8 @@ exports to: #+begin_src html <video controls="controls" width="350"> <source src="movie.mp4" type="video/mp4"> - <source src="movie.ogg" type="video/ogg"> - <p>Your browser does not support the video tag.</p> + <source src="movie.ogg" type="video/ogg"> + <p>Your browser does not support the video tag.</p> </video> #+end_src @@ -12925,7 +12998,7 @@ as-is. #+vindex: org-html-mathjax-options~ LaTeX math snippets (see [[*LaTeX fragments]]) can be displayed in two -different ways on HTML pages. The default is to use the [[http://www.mathjax.org][MathJax]], +different ways on HTML pages. The default is to use the [[https://www.mathjax.org][MathJax]], which should work out of the box with Org[fn:129][fn:130]. Some MathJax display options can be configured via ~org-html-mathjax-options~, or in the buffer. For example, with the following settings, @@ -13621,7 +13694,7 @@ placement. #+cindex: image, centering in LaTeX export The LaTeX export back-end centers all images by default. Setting =:center= to =nil= disables centering. To disable centering globally, -set ~org-latex-images-centered~ to =t=. +set ~org-latex-images-centered~ to =nil=. Set the =:comment-include= attribute to non-~nil~ value for the LaTeX export back-end to comment out the =\includegraphics= macro. @@ -13698,7 +13771,7 @@ objects through the attributes =:float= and =:options=. For =:float=: The LaTeX export back-end passes string values in =:options= to LaTeX packages for customization of that specific source block. In the example below, the =:options= are set for Minted. Minted is a source -code highlighting LaTeX package with many configurable options. +code highlighting LaTeX package with many configurable options[fn:134]. #+begin_example ,#+ATTR_LATEX: :options commentstyle=\bfseries @@ -13801,6 +13874,95 @@ The LaTeX export back-end converts horizontal rules by the specified ----- #+end_example +*** Verse blocks in LaTeX export +:PROPERTIES: +:DESCRIPTION: Attributes specific to special blocks. +:END: + +#+cindex: verse blocks, in @LaTeX{} export +#+cindex: @samp{ATTR_LATEX}, keyword + +The LaTeX export back-end accepts four attributes for verse blocks: +=:lines=, =:center=, =:versewidth= and =:latexcode=. The three first +require the external LaTeX package =verse.sty=, which is an extension +of the standard LaTeX environment. + +- =:lines= :: To add marginal verse numbering. Its value is an + integer, the sequence in which the verses should be numbered. +- =:center= :: With value =t= all the verses on the page are optically + centered (a typographic convention for poetry), taking as a + reference the longest verse, which must be indicated by the + attribute =:versewidth=. +- =:versewidth= :: Its value is a literal text string with the longest + verse. +- =:latexcode= :: It accepts any arbitrary LaTeX code that can be + included within a LaTeX =verse= environment. + +A complete example with Shakespeare's first sonnet: + +#+begin_src org +,#+ATTR_LATEX: :center t :latexcode \color{red} :lines 5 +,#+ATTR_LATEX: :versewidth Feed’st thy light’s flame with self-substantial fuel, +,#+BEGIN_VERSE +From fairest creatures we desire increase, +That thereby beauty’s rose might never die, +But as the riper should by time decease +His tender heir might bear his memory +But thou, contracted to thine own bright eyes, +Feed’st thy light’s flame with self-substantial fuel, +Making a famine where abundance lies, +Thyself thy foe, to thy sweet self too cruel. +Thou that art now the world’s fresh ornament, +And only herald to the gaudy spring, +Within thine own bud buriest thy content, +And, tender churl, mak’st waste in niggardly. +Pity the world, or else this glutton be, +To eat the world’s due, by the grave and thee. +,#+END_VERSE +#+end_src + +*** Quote blocks in LaTeX export +:PROPERTIES: +:DESCRIPTION: Attributes specific to quote blocks. +:END: + +#+cindex: quote blocks, in @LaTeX{} export +#+cindex: @samp{ATTR_LATEX}, keyword +#+cindex: org-latex-default-quote-environment + +The LaTeX export back-end accepts two attributes for quote blocks: +=:environment=, for an arbitrary quoting environment (the default +value is that of ~org-latex-default-quote-environment~: ~"quote"~) and +=:options=. For example, to choose the environment =quotation=, +included as an alternative to =quote= in standard LaTeX classes: + +#+begin_example +,#+ATTR_LATEX: :environment quotation +,#+BEGIN_QUOTE +some text... +,#+END_QUOTE +#+end_example + +To choose the =foreigndisplayquote= environment, included in the LaTeX +package =csquotes=, with the =german= option, use this syntax: + +#+begin_example +,#+LATEX_HEADER:\usepackage[autostyle=true]{csquotes} +,#+ATTR_LATEX: :environment foreigndisplayquote :options {german} +,#+BEGIN_QUOTE +some text in German... +,#+END_QUOTE +#+end_example + +#+texinfo: @noindent +which is exported to LaTeX as + +#+begin_example +\begin{foreigndisplayquote}{german} +some text in German... +\end{foreigndisplayquote} +#+end_example + ** Markdown Export :PROPERTIES: :DESCRIPTION: Exporting to Markdown. @@ -13860,7 +14022,7 @@ a limit to a level before the absolute limit (see [[*Export Settings]]). The ODT export back-end handles creating of OpenDocument Text (ODT) format. Documents created by this exporter use the -{{{cite(OpenDocument-v1.2 specification)}}}[fn:134] and are compatible +{{{cite(OpenDocument-v1.2 specification)}}}[fn:135] and are compatible with LibreOffice 3.4. *** Pre-requisites for ODT export @@ -14261,7 +14423,7 @@ document in one of the following ways: variables ~org-latex-to-mathml-convert-command~ and ~org-latex-to-mathml-jar-file~. - If you prefer to use MathToWeb[fn:135] as your converter, you can + If you prefer to use MathToWeb[fn:136] as your converter, you can configure the above variables as shown below. #+begin_src emacs-lisp @@ -14272,7 +14434,7 @@ document in one of the following ways: #+end_src #+texinfo: @noindent - or, to use LaTeXML[fn:136] instead, + or, to use LaTeXML[fn:137] instead, #+begin_src emacs-lisp (setq org-latex-to-mathml-convert-command @@ -14591,7 +14753,7 @@ with the =#+ATTR_ODT= line. For a discussion on default formatting of tables, see [[*Tables in ODT export]]. This feature closely mimics the way table templates are defined in the -OpenDocument-v1.2 specification[fn:137]. +OpenDocument-v1.2 specification[fn:138]. #+vindex: org-odt-table-styles For quick preview of this feature, install the settings below and export the @@ -14625,7 +14787,7 @@ templates, define new styles there. To use this feature proceed as follows: -1. Create a table template[fn:138]. +1. Create a table template[fn:139]. A table template is set of =table-cell= and =paragraph= styles for each of the following table cell categories: @@ -14664,7 +14826,7 @@ To use this feature proceed as follows: =</office:automatic-styles>= element of the content template file (see [[x-orgodtcontenttemplate-xml][Factory styles]]). -2. Define a table style[fn:139]. +2. Define a table style[fn:140]. #+vindex: org-odt-table-styles To define a table style, create an entry for the style in the @@ -15159,7 +15321,7 @@ To specify the author of the quotation, use the =:author= attribute. ,#+BEGIN_QUOTE The Lady of the Lake, her arm clad in the purest shimmering samite, held aloft Excalibur from the bosom of the water, signifying by divine -providence that I, Arthur, was to carry Excalibur. That is why I am +providence that I, Arthur, was to carry Excalibur. That is why I am your king. ,#+END_QUOTE #+end_example @@ -15422,7 +15584,7 @@ BACKEND is the export back-end being used, as a symbol." (org-map-entries (lambda () (delete-region (point) (line-beginning-position 2))))) -(add-hook 'org-export-before-parsing-hook 'my-headline-removal) +(add-hook 'org-export-before-parsing-hook #'my-headline-removal) #+end_src *** Filters @@ -15768,17 +15930,17 @@ following properties Publishing means that a file is copied to the destination directory and possibly transformed in the process. The default transformation is to export Org files as HTML files, and this is done by the function -~org-publish-org-to-html~ which calls the HTML exporter (see [[*HTML +~org-html-publish-to-html~ which calls the HTML exporter (see [[*HTML Export]]). But you can also publish your content as PDF files using -~org-publish-org-to-pdf~, or as ASCII, Texinfo, etc., using the +~org-latex-publish-to-pdf~, or as ASCII, Texinfo, etc., using the corresponding functions. If you want to publish the Org file as an =.org= file but with /archived/, /commented/, and /tag-excluded/ trees removed, use -~org-publish-org-to-org~. This produces =file.org= and put it in the +~org-org-publish-to-org~. This produces =file.org= and puts it in the publishing directory. If you want a htmlized version of this file, set the parameter ~:htmlized-source~ to ~t~. It produces -=file.org.html= in the publishing directory[fn:140]. +=file.org.html= in the publishing directory[fn:141]. Other files like images only need to be copied to the publishing destination; for this you can use ~org-publish-attachment~. For @@ -16247,12 +16409,13 @@ directory on the local machine. (setq org-publish-project-alist '(("org" :base-directory "~/org/" + :publishing-function org-html-publish-to-html :publishing-directory "~/public_html" :section-numbers nil - :table-of-contents nil - :style "<link rel=\"stylesheet\" - href=\"../other/mystyle.css\" - type=\"text/css\"/>"))) + :with-toc nil + :html-head "<link rel=\"stylesheet\" + href=\"../other/mystyle.css\" + type=\"text/css\"/>"))) #+end_src *** Example: complex publishing configuration @@ -16347,6 +16510,127 @@ of the commands above, or by customizing the variable particular if files include other files via =SETUPFILE= or =INCLUDE= keywords. +* Citation handling +:PROPERTIES: +:DESCRIPTION: create, follow and export citations. +:END: +#+cindex: citation + +The =oc.el= library provides tooling to handle citations in Org via +"citation processors" that offer some or all of the following +capabilities: + +- activate :: Fontification, tooltip preview, etc. +- follow :: At-point actions on citations via ~org-open-at-point~. +- insert :: Add and edit citations via ~org-cite-insert~. +- export :: Via different libraries for different target formats. + +The user can configure these with ~org-cite-activate-processor~, +~org-cite-follow-processor~, ~org-cite-insert-processor~, and +~org-cite-export-processors~ respectively. + +The included "basic" processor provides all four capabilities. + +** Citations + +Before adding citations, first set one-or-more bibliographies, either +globally with ~org-cite-global-bibliography~, or locally using one or +more "bibliography" keywords. + +#+begin_example +#+bibliography: SomeFile.bib +#+bibliography: /some/other/file.json +#+bibliography: "/some/file/with spaces/in its name.bib" +#+end_example + +#+kindex: C-c C-x @@ +#+findex: org-cite-insert +One can then insert and edit citations using ~org-cite-insert~, called +with {{{kbd(C-c C-x @)}}}. + +A /citation/ requires one or more citation /key(s)/, elements +identifying a reference in the bibliography. + +- Each citation is surrounded by brackets and uses the =cite= type. + +- Each key starts with the character =@=. + +- Each key can be qualified by a /prefix/ (e.g.\nbsp{}"see ") and/or + a /suffix/ (e.g.\nbsp{}"p.\nbsp{}123"), giving informations useful or necessary + fo the comprehension of the citation but not included in the + reference. + +- A single citation can cite more than one reference ; the keys are + separated by semicolons ; the formatting of such citation groups is + specified by the style. + +- One can also specify a stylistic variation for the citations by + inserting a =/= and a style name between the =cite= keyword and the + colon; this usually makes sense only for the author-year styles. + +: [cite/style:common prefix ;prefix @key suffix; ... ; common suffix] + +The only mandatory elements are: + +- The =cite= keyword and the colon. +- The =@= character immediately preceding each key. +- The brackets surrounding the citation(s) (group). + +** Citation export processors + +Org currently includes the following export processors: + +- Two processors can export to a variety of formats, including =latex= + (and therefore =pdf=), =html=, =odt= and plain (UTF8) text: + + - basic :: a basic export processor, well adapted to situations + where backward compatibility is not a requirement and formatting + needs are minimal; + + - csl :: this export processor uses format files written in [[https://en.wikipedia.org/wiki/Citation_Style_Language][Citation + Style Language]] via [[https://github.com/andras-simonyi/citeproc-el][citeproc-el]]; + +- In contrast, two other processors target LaTeX and LaTeX-derived + formats exclusively: + + - natbib :: this export processor uses BibTeX, the historical + bibliographic processor used with LaTeX, thus allowing the use of + data and style files compatible with this processor (including + a large number of publishers' styles). It uses citation commands + implemented in the LaTeX package =natbib=, allowing more stylistic + variants that LaTeX's =\cite= command. + + - biblatex :: this backend allows the use of data and formats + prepared for BibLaTeX, an alternate bibliographic processor used + with LaTeX, which overcomes some serious BibTeX limitations, but + has not (yet?)\nbsp{}been widely adopted by publishers. + +The =CITE_EXPORT= keyword specifies the export processor and the +citation (and possibly reference) style(s); for example (all arguments +are optional) + +: #+cite_export: basic author author-year + +#+texinfo: @noindent +specifies the "basic" export processor with citations inserted as +author's name and references indexed by author's names and year; + +: #+cite_export: csl /some/path/to/vancouver-brackets.csl + +#+texinfo: @noindent +specifies the "csl" processor and CSL style, which in this case +defines numeric citations and numeric references according to the +=Vancouver= specification (as style used in many medical journals), +following a typesetting variation putting citations between brackets; + +: #+cite_export: natbib kluwer + +#+texinfo: @noindent +specifies the =natbib= export processor with a label citation style +conformant to the Harvard style and the specification of the +Wolkers-Kluwer publisher; since it relies on the ~bibtex~ processor of +your LaTeX installation, it won't export to anything but PDF. + * Working with Source Code :PROPERTIES: :DESCRIPTION: Export, evaluate, and tangle code blocks. @@ -16393,7 +16677,7 @@ extract, export, and publish source code blocks. Org can also compile and execute a source code block, then capture the results. The Org mode literature sometimes refers to source code blocks as /live code/ blocks because they can alter the content of the Org document or the -material that it exports. Users can control how live they want each +material that it exports. Users can control the "liveliness" of each source code block by tweaking the header arguments (see [[*Using Header Arguments]]) for compiling, execution, extraction, and exporting. @@ -16736,7 +17020,11 @@ the =var= header argument. body. {{{var(ASSIGN)}}} is a literal value, such as a string, a number, a reference to a table, a list, a literal example, another code block---with or without arguments---or the results of evaluating -a code block. +a code block. {{{var(ASSIGN)}}} may specify a filename for references +to elements in a different file, using a =:= to separate the filename +from the reference. + +: :var NAME=FILE:REFERENCE Here are examples of passing values by reference: @@ -16815,6 +17103,9 @@ Here are examples of passing values by reference: | two | 16 | 17 | 18 | 19 | 20 | #+end_example +To refer to a table in another file, join the filename and table name with +a colon, for example: =:var table=other-file.org:example-table=. + - list :: A simple named list. @@ -17156,13 +17447,13 @@ See [[*Languages]] to enable other languages. #+kindex: C-c C-v e #+findex: org-babel-execute-src-block Org provides many ways to execute code blocks. {{{kbd(C-c C-c)}}} or -{{{kbd(C-c C-v e)}}} with the point on a code block[fn:141] calls the +{{{kbd(C-c C-v e)}}} with the point on a code block[fn:142] calls the ~org-babel-execute-src-block~ function, which executes the code in the block, collects the results, and inserts them in the buffer. #+cindex: @samp{CALL}, keyword #+vindex: org-babel-inline-result-wrap -By calling a named code block[fn:142] from an Org mode buffer or +By calling a named code block[fn:143] from an Org mode buffer or a table. Org can call the named code blocks from the current Org mode buffer or from the "Library of Babel" (see [[*Library of Babel]]). @@ -17363,7 +17654,7 @@ they are mutually exclusive. - =value= :: - Default for most Babel libraries[fn:142]. Functional mode. Org + Default for most Babel libraries[fn:143]. Functional mode. Org gets the value by wrapping the code in a function definition in the language of the source block. That is why when using =:results value=, code should execute like a function and return a value. For @@ -17488,10 +17779,12 @@ default behavior is to automatically determine the result type. #+end_example #+cindex: @samp{file-desc}, header argument - The =file-desc= header argument defines the description (see - [[*Link Format]]) for the link. If =file-desc= is present but has no value, + The =file-desc= header argument defines the description (see [[*Link + Format]]) for the link. If =file-desc= is present but has no value, the =file= value is used as the link description. When this - argument is not present, the description is omitted. + argument is not present, the description is omitted. If you want to + provide the =file-desc= argument but omit the description, you can + provide it with an empty vector (i.e., :file-desc []). #+cindex: @samp{sep}, header argument By default, Org assumes that a table written to a file has @@ -17549,7 +17842,7 @@ follows from the type specified above. #+begin_example ,#+begin_src shell :results file link :file "download.tar.gz" - wget -c "http://example.com/download.tar.gz" + wget -c "https://example.com/download.tar.gz" ,#+end_src #+end_example @@ -17595,15 +17888,20 @@ value listed above. E.g., Handling options after collecting the results. +- =replace= :: + + Default. Insert results in the Org buffer. Remove previous + results. Usage example: =:results output replace=. + - =silent= :: Do not insert results in the Org mode buffer, but echo them in the minibuffer. Usage example: =:results output silent=. -- =replace= :: +- =none= :: - Default. Insert results in the Org buffer. Remove previous - results. Usage example: =:results output replace=. + Do not process results at all. No inserting in the Org mode buffer + nor echo them in the minibuffer. Usage example: =:results none=. - =append= :: @@ -17929,35 +18227,8 @@ code block header arguments: #+cindex: source code, languages #+cindex: code block, languages -Code blocks in the following languages are supported. - -#+attr_texinfo: :columns 0.25 0.25 0.25 0.20 -| Language | Identifier | Language | Identifier | -|------------+---------------+----------------+--------------| -| Asymptote | =asymptote= | Lisp | =lisp= | -| Awk | =awk= | Lua | =lua= | -| C | =C= | MATLAB | =matlab= | -| C++ | =C++=[fn:143] | Mscgen | =mscgen= | -| Clojure | =clojure= | Objective Caml | =ocaml= | -| CSS | =css= | Octave | =octave= | -| D | =D=[fn:144] | Org mode | =org= | -| ditaa | =ditaa= | Oz | =oz= | -| Emacs Calc | =calc= | Perl | =perl= | -| Emacs Lisp | =emacs-lisp= | Plantuml | =plantuml= | -| Eshell | =eshell= | Processing.js | =processing= | -| Fortran | =fortran= | Python | =python= | -| Gnuplot | =gnuplot= | R | =R= | -| GNU Screen | =screen= | Ruby | =ruby= | -| Graphviz | =dot= | Sass | =sass= | -| Haskell | =haskell= | Scheme | =scheme= | -| Java | =java= | Sed | =sed= | -| Javascript | =js= | shell | =sh= | -| LaTeX | =latex= | SQL | =sql= | -| Ledger | =ledger= | SQLite | =sqlite= | -| Lilypond | =lilypond= | Vala | =vala= | - -Additional documentation for some languages is at -https://orgmode.org/worg/org-contrib/babel/languages.html. +Code blocks in dozens of languages are supported. See Worg for +[[https://orgmode.org/worg/org-contrib/babel/languages/index.html][language specific documentation]]. #+vindex: org-babel-load-languages By default, only Emacs Lisp is enabled for evaluation. To enable or @@ -18071,7 +18342,7 @@ for Python and Emacs Lisp languages. #+cindex: @samp{noweb-ref}, header argument Source code blocks can include references to other source code blocks, -using a noweb[fn:145] style syntax: +using a noweb[fn:144] style syntax: : <<CODE-BLOCK-ID>> @@ -18582,14 +18853,14 @@ Org Tempo expands snippets to structures defined in ~org-structure-template-alist~ and ~org-tempo-keywords-alist~. For example, {{{kbd(< s TAB)}}} creates a code block. Enable it by customizing ~org-modules~ or add =(require 'org-tempo)= to your Emacs -init file[fn:146]. +init file[fn:145]. #+attr_texinfo: :columns 0.1 0.9 | {{{kbd(a)}}} | =#+BEGIN_EXPORT ascii= ... =#+END_EXPORT= | | {{{kbd(c)}}} | =#+BEGIN_CENTER= ... =#+END_CENTER= | | {{{kbd(C)}}} | =#+BEGIN_COMMENT= ... =#+END_COMMENT= | | {{{kbd(e)}}} | =#+BEGIN_EXAMPLE= ... =#+END_EXAMPLE= | -| {{{kbd(E)}}} | =#+BEGIN_EXPORT= ... =#+END_EXPORT= | +| {{{kbd(E)}}} | =#+BEGIN_EXPORT= ... =#+END_EXPORT= | | {{{kbd(h)}}} | =#+BEGIN_EXPORT html= ... =#+END_EXPORT= | | {{{kbd(l)}}} | =#+BEGIN_EXPORT latex= ... =#+END_EXPORT= | | {{{kbd(q)}}} | =#+BEGIN_QUOTE= ... =#+END_QUOTE= | @@ -18616,14 +18887,14 @@ the variable ~org-use-speed-commands~ to a non-~nil~ value. To trigger a Speed Key, point must be at the beginning of an Org headline, before any of the stars. -#+vindex: org-speed-commands-user +#+vindex: org-speed-commands #+findex: org-speed-command-help Org comes with a pre-defined list of Speed Keys. To add or modify -Speed Keys, customize the variable, ~org-speed-commands-user~. For -more details, see the variable's docstring. With Speed Keys -activated, {{{kbd(M-x org-speed-command-help)}}}, or {{{kbd(?)}}} when -point is at the beginning of an Org headline, shows currently active -Speed Keys, including the user-defined ones. +Speed Keys, customize the option ~org-speed-commands~. For more +details, see the variable's docstring. With Speed Keys activated, +{{{kbd(M-x org-speed-command-help)}}}, or {{{kbd(?)}}} when point is at the +beginning of an Org headline, shows currently active Speed Keys, +including the user-defined ones. ** A Cleaner Outline View :PROPERTIES: @@ -18662,7 +18933,7 @@ in the desired amount with hard spaces and hiding leading stars. To display the buffer in the indented view, activate Org Indent minor mode, using {{{kbd(M-x org-indent-mode)}}}. Text lines that are not headlines are prefixed with virtual spaces to vertically align with -the headline text[fn:147]. +the headline text[fn:146]. #+vindex: org-indent-indentation-per-level To make more horizontal space, the headlines are shifted by two @@ -18690,15 +18961,15 @@ use =STARTUP= keyword as follows: It is possible to use hard spaces to achieve the indentation instead, if the bare ASCII file should have the indented look also outside -Emacs[fn:148]. With Org's support, you have to indent all lines to +Emacs[fn:147]. With Org's support, you have to indent all lines to line up with the outline headers. You would use these -settings[fn:149]: +settings[fn:148]: - #+begin_src emacs-lisp - (setq org-adapt-indentation t - org-hide-leading-stars t - org-odd-levels-only t) - #+end_src +#+begin_src emacs-lisp +(setq org-adapt-indentation t + org-hide-leading-stars t + org-odd-levels-only t) +#+end_src - /Indentation of text below headlines/ (~org-adapt-indentation~) :: @@ -18955,11 +19226,15 @@ changes. | =overview= | Top-level headlines only. | | =content= | All headlines. | | =showall= | No folding on any entry. | + | =show2levels= | Headline levels 1-2. | + | =show3levels= | Headline levels 1-3. | + | =show4levels= | Headline levels 1-4. | + | =show5levels= | Headline levels 1-5. | | =showeverything= | Show even drawer contents. | #+vindex: org-startup-indented Dynamic virtual indentation is controlled by the variable - ~org-startup-indented~[fn:150]. + ~org-startup-indented~[fn:149]. | =indent= | Start with Org Indent mode turned on. | | =noindent= | Start with Org Indent mode turned off. | @@ -19095,6 +19370,22 @@ changes. These lines set the TODO keywords and their interpretation in the current file. The corresponding variable is ~org-todo-keywords~. +** Regular Expressions +:PROPERTIES: +:DESCRIPTION: Elisp regular expressions. +:END: +#+cindex: regular expressions syntax +#+cindex: regular expressions, in searches + +Org, as an Emacs mode, makes use of Elisp regular expressions for +searching, matching and filtering. Elisp regular expressions have a +somewhat different syntax then some common standards. Most notably, +alternation is indicated using =\|= and matching groups are denoted by +=\(...\)=. For example the string =home\|work= matches either =home= +or =work=. + +For more information, see [[info:emacs::Regexps][Regular Expressions in Emacs]]. + ** Org Syntax :PROPERTIES: :DESCRIPTION: Formal description of Org's syntax. @@ -19533,7 +19824,7 @@ passed to Emacs through the =emacsclient= command, so you also need to ensure an Emacs server is running. More precisely, when the application calls -: emacsclient org-protocol://PROTOCOL?key1=val1&key2=val2 +: emacsclient "org-protocol://PROTOCOL?key1=val1&key2=val2" #+texinfo: @noindent Emacs calls the handler associated to {{{var(PROTOCOL)}}} with @@ -19556,7 +19847,7 @@ Using the ~store-link~ handler, you can copy links, to that they can be inserted using {{{kbd(M-x org-insert-link)}}} or yanking. More precisely, the command -: emacsclient org-protocol://store-link?url=URL&title=TITLE +: emacsclient "org-protocol://store-link?url=URL&title=TITLE" #+texinfo: @noindent stores the following link: @@ -19571,10 +19862,19 @@ To use this feature from a browser, add a bookmark with an arbitrary name, e.g., =Org: store-link= and enter this as /Location/: #+begin_example +javascript:location.href='org-protocol://store-link?' + + new URLSearchParams({url:location.href, title:document.title}); +#+end_example + +Title is an optional parameter. Another expression was recommended earlier: + +#+begin_example javascript:location.href='org-protocol://store-link?url='+ encodeURIComponent(location.href); #+end_example +The latter form is compatible with older Org versions from 9.0 to 9.4. + *** The ~capture~ protocol :PROPERTIES: :DESCRIPTION: Fill a buffer with external information. @@ -19585,18 +19885,31 @@ javascript:location.href='org-protocol://store-link?url='+ Activating the "capture" handler pops up a =Capture= buffer in Emacs, using acapture template. -: emacsclient org-protocol://capture?template=X?url=URL?title=TITLE?body=BODY +: emacsclient "org-protocol://capture?template=X&url=URL&title=TITLE&body=BODY" To use this feature, add a bookmark with an arbitrary name, e.g., =Org: capture=, and enter this as =Location=: #+begin_example +javascript:location.href='org-protocol://capture?' + + new URLSearchParams({ + template: 'x', url: window.location.href, + title: document.title, body: window.getSelection()}); +#+end_example + +You might have seen another expression: + +#+begin_example javascript:location.href='org-protocol://capture?template=x'+ '&url='+encodeURIComponent(window.location.href)+ '&title='+encodeURIComponent(document.title)+ '&body='+encodeURIComponent(window.getSelection()); #+end_example +It is a bit more cluttered than the former one, but it is compatible +with previous Org versions 9.0-9.4. In these versions encoding of +space as "+" character was not supported by URI decoder. + #+vindex: org-protocol-default-template-key The capture template to be used can be specified in the bookmark (like =X= above). If unspecified, the template key is set in the variable @@ -19652,13 +19965,13 @@ click the bookmark and start editing. #+cindex: rewritten URL in open-source protocol #+cindex: protocol, open-source rewritten URL However, such mapping may not always yield the desired results. -Suppose you maintain an online store located at =http://example.com/=. +Suppose you maintain an online store located at =https://example.com/=. The local sources reside in =/home/user/example/=. It is common practice to serve all products in such a store through one file and rewrite URLs that do not match an existing file on the server. That -way, a request to =http://example.com/print/posters.html= might be +way, a request to =https://example.com/print/posters.html= might be rewritten on the server to something like -=http://example.com/shop/products.php/posters.html.php=. The +=https://example.com/shop/products.php/posters.html.php=. The ~open-source~ handler probably cannot find a file named =/home/user/example/print/posters.html.php= and fails. @@ -19673,7 +19986,7 @@ adding ~:rewrites~ rules like this: #+begin_src emacs-lisp (setq org-protocol-project-alist '(("example.com" - :base-url "http://example.com/" + :base-url "https://example.com/" :working-directory "/home/user/example/" :online-suffix ".php" :working-suffix ".php" @@ -19704,8 +20017,8 @@ an Org file that is part of a publishing project. :END: Org Crypt encrypts the text of an entry, but not the headline, or -properties. Behind the scene, it uses the Emacs EasyPG library to -encrypt and decrypt files. +properties. Behind the scene, it uses the [[info:epa][Emacs EasyPG Library]] to +encrypt and decrypt files, and EasyPG needs a correct [[info:gnupg][GnuPG]] setup. #+vindex: org-crypt-tag-matcher Any text below a headline that has a =crypt= tag is automatically @@ -19778,7 +20091,7 @@ Tags]]) only for those set in these variables. #+vindex: org-mobile-directory The mobile application needs access to a file directory on -a server[fn:151] to interact with Emacs. Pass its location through +a server[fn:150] to interact with Emacs. Pass its location through the ~org-mobile-directory~ variable. If you can mount that directory locally just set the variable to point to that directory: @@ -19799,7 +20112,7 @@ With a public server, consider encrypting the files. Org also requires OpenSSL installed on the local computer. To turn on encryption, set the same password in the mobile application and in Emacs. Set the password in the variable -~org-mobile-use-encryption~[fn:152]. Note that even after the mobile +~org-mobile-use-encryption~[fn:151]. Note that even after the mobile application encrypts the file contents, the file name remains visible on the file systems of the local computer, the server, and the mobile device. @@ -19815,15 +20128,15 @@ The command ~org-mobile-push~ copies files listed in ~org-mobile-files~ into the staging area. Files include agenda files (as listed in ~org-agenda-files~). Customize ~org-mobile-files~ to add other files. File names are staged with paths relative to -~org-directory~, so all files should be inside this directory[fn:153]. +~org-directory~, so all files should be inside this directory[fn:152]. Push creates a special Org file =agendas.org= with custom agenda views -defined by the user[fn:154]. +defined by the user[fn:153]. Finally, Org writes the file =index.org=, containing links to other files. The mobile application reads this file first from the server to determine what other files to download for agendas. For faster -downloads, it is expected to only read files whose checksums[fn:155] +downloads, it is expected to only read files whose checksums[fn:154] have changed. *** Pulling from the mobile application @@ -19840,7 +20153,7 @@ data in an inbox file format, through the following steps: 1. #+vindex: org-mobile-inbox-for-pull - Org moves all entries found in =mobileorg.org=[fn:156] and appends + Org moves all entries found in =mobileorg.org=[fn:155] and appends them to the file pointed to by the variable ~org-mobile-inbox-for-pull~. It should reside neither in the staging area nor on the server. Each captured entry and each @@ -19904,12 +20217,10 @@ https://orgmode.org/worg/doc.html#hooks. :END: #+cindex: add-on packages -Various authors wrote a large number of add-on packages for Org. - -These packages are not part of Emacs, but they are distributed as -contributed packages with the separate release available at -https://orgmode.org. See the =contrib/README= file in the source code -directory for a list of contributed files. Worg page with more +Various authors wrote a large number of add-on packages for Org. Some +of these packages used to be part of the =org-mode= repository but are +now hosted in a separate =org-contrib= repository +[[https://git.sr.ht/~bzg/org-contrib][here]]. A Worg page with more information is at: https://orgmode.org/worg/org-contrib/. ** Adding Hyperlink Types @@ -20136,9 +20447,9 @@ of these strategies: #+cindex: @LaTeX{}, and Orgtbl mode To wrap a source table in LaTeX, use the =comment= environment -provided by =comment.sty=[fn:157]. To activate it, put +provided by =comment.sty=[fn:156]. To activate it, put ~\usepackage{comment}~ in the document header. Orgtbl mode inserts -a radio table skeleton[fn:158] with the command {{{kbd(M-x +a radio table skeleton[fn:157] with the command {{{kbd(M-x orgtbl-insert-radio-table)}}}, which prompts for a table name. For example, if =salesfigures= is the name, the template inserts: @@ -20157,7 +20468,7 @@ The line =#+ORGTBL: SEND= tells Orgtbl mode to use the function ~orgtbl-to-latex~ to convert the table to LaTeX format, then insert the table at the target (receive) location named =salesfigures=. Now the table is ready for data entry. It can even use spreadsheet -features[fn:159]: +features[fn:158]: #+begin_example % BEGIN RECEIVE ORGTBL salesfigures @@ -20373,7 +20684,7 @@ Dynamic blocks, like any other block, can be narrowed with #+vindex: org-agenda-skip-function #+vindex: org-agenda-skip-function-global Org provides a special hook to further limit items in agenda views: -~agenda~, ~agenda*~[fn:160], ~todo~, ~alltodo~, ~tags~, ~tags-todo~, +~agenda~, ~agenda*~[fn:159], ~todo~, ~alltodo~, ~tags~, ~tags-todo~, ~tags-tree~. Specify a custom function that tests inclusion of every matched item in the view. This function can also skip as much as is needed. @@ -20416,7 +20727,7 @@ meaningful string suitable for the agenda view. #+vindex: org-agenda-skip-function Search for entries with a limit set on levels for the custom search. This is a general approach to creating custom searches in Org. To -include all levels, use =LEVEL>0=[fn:161]. Then to selectively pick +include all levels, use =LEVEL>0=[fn:160]. Then to selectively pick the matched entries, use ~org-agenda-skip-function~, which also accepts Lisp forms, such as ~org-agenda-skip-entry-if~ and ~org-agenda-skip-subtree-if~. For example: @@ -21017,6 +21328,9 @@ be complete if the ones above were not mentioned in this manual. - Charles Cave's suggestion sparked the implementation of templates for Remember, which are now templates for capture. +- Timothy E Chapman worked on a complete overhaul of the orgmode.org + website in 2020 and helped fixing various bugs. + - Pavel Chalmoviansky influenced the agenda treatment of items with specified time. @@ -21106,6 +21420,9 @@ be complete if the ones above were not mentioned in this manual. - Jason\nbsp{}F.\nbsp{}McBrayer suggested agenda export to CSV format. +- Kyle Meyer helped setting up the [[https://public-inbox.org/][public-inbox]] archive of the [[https://orgmode.org/list/][Org + mailing list]] and has been fixing many bugs. + - Max Mikhanosha came up with the idea of refiling. - Dmitri Minaev sent a patch to set priority limits on a per-file @@ -21143,6 +21460,9 @@ be complete if the ones above were not mentioned in this manual. - Martin Pohlack provided the code snippet to bundle character insertion into bundles of 20 for undo. +- Ihor Radchenko helped with fixing bugs and improving the user + experience regarding Org's speed. + - T.\nbsp{}V.\nbsp{}Raman reported bugs and suggested improvements. - Matthias Rempe (Oelde) provided ideas, Windows support, and quality @@ -21173,7 +21493,7 @@ be complete if the ones above were not mentioned in this manual. literal examples, and remote highlighting for referenced code lines. - Stathis Sideris wrote the =ditaa.jar= ASCII to PNG converter that is - now packaged into Org's =contrib/= directory. + now packaged into the [[https://git.sr.ht/~bzg/org-contrib][org-contrib]] repository. - Daniel Sinder came up with the idea of internal archiving by locking subtrees. @@ -21296,7 +21616,7 @@ modify this GNU manual." * Footnotes [fn:1] If you do not use Font Lock globally turn it on in Org buffer -with =(add-hook 'org-mode-hook 'turn-on-font-lock)=. +with =(add-hook 'org-mode-hook #'turn-on-font-lock)=. [fn:2] Please consider subscribing to the mailing list in order to minimize the work the mailing list moderators have to do. @@ -21597,12 +21917,12 @@ lognoteclock-out=. line---the line is broken here only to fit it into the manual. [fn:81] On computers using macOS, idleness is based on actual user -idleness, not just Emacs' idle time. For X11, you can install -a utility program =x11idle.c=, available in the =contrib/scripts/= -directory of the Org Git distribution, or install the xprintidle -package and set it to the variable ~org-clock-x11idle-program-name~ if -you are running Debian, to get the same general treatment of idleness. -On other systems, idle time refers to Emacs idle time only. +idleness, not just Emacs' idle time. For X11, you can install a +utility program =x11idle.c=, available in the =org-contrib/= +repository, or install the xprintidle package and set it to the +variable ~org-clock-x11idle-program-name~ if you are running Debian, +to get the same general treatment of idleness. On other systems, idle +time refers to Emacs idle time only. [fn:82] Please note the pitfalls of summing hierarchical data in a flat list (see [[*Using Column View in the Agenda]]). @@ -21733,7 +22053,7 @@ a fragment, see the documentation of the function version 1.34 of the =htmlize.el= package, which you need to install). Fontified code chunks in LaTeX can be achieved using either the [[https://www.ctan.org/pkg/listings][listings]] package or the [[https://www.ctan.org/pkg/minted][minted]] package. Refer to -~org-export-latex-listings~ for details. +~org-latex-listings~ for details. [fn:115] Source code in code blocks may also be evaluated either interactively or on export. See [[*Working with Source Code]] for more @@ -21762,7 +22082,9 @@ and =#+STARTUP: nofnadjust=. [fn:122] The variable ~org-export-date-timestamp-format~ defines how this timestamp are exported. -[fn:123] DEFINITION NOT FOUND. +[fn:123] For export to LaTeX format---or LaTeX-related formats such as +Beamer---, the =org-latex-package-alist= variable needs further +configuration. See [[LaTeX specific export settings]]. [fn:124] At the moment, some export back-ends do not obey this specification. For example, LaTeX export excludes every unnumbered @@ -21785,7 +22107,7 @@ to make it visible. The tag serves as a visual aid and has no semantic relevance. [fn:129] By default Org loads MathJax from [[https://cdnjs.com][cdnjs.com]] as recommended by -[[http://www.mathjax.org][MathJax]]. +[[https://www.mathjax.org][MathJax]]. [fn:130] Please note that exported formulas are part of an HTML document, and that signs such as =<=, =>=, or =&= have special @@ -21802,93 +22124,89 @@ use the variables ~org-html-todo-kwd-class-prefix~ and for different files. However, "smart" LaTeX compilation systems, such as latexmk, can select the correct bibliography compiler. -[fn:134] See [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][Open Document Format for Office Applications +[fn:134] Minted uses an external Python package for code highlighting, +which requires the flag =-shell-escape= to be added to +~org-latex-pdf-process~. + +[fn:135] See [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][Open Document Format for Office Applications (OpenDocument) Version 1.2]]. -[fn:135] See [[http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl][MathToWeb]]. +[fn:136] See [[http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl][MathToWeb]]. -[fn:136] See [[http://dlmf.nist.gov/LaTeXML/]]. +[fn:137] See [[http://dlmf.nist.gov/LaTeXML/]]. -[fn:137] [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][OpenDocument-v1.2 Specification]] +[fn:138] [[http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html][OpenDocument-v1.2 Specification]] -[fn:138] See the =<table:table-template>= element of the +[fn:139] See the =<table:table-template>= element of the OpenDocument-v1.2 specification. -[fn:139] See the attributes =table:template-name=, +[fn:140] See the attributes =table:template-name=, =table:use-first-row-styles=, =table:use-last-row-styles=, =table:use-first-column-styles=, =table:use-last-column-styles=, =table:use-banding-rows-styles=, and =table:use-banding-column-styles= of the =<table:table>= element in the OpenDocument-v1.2 specification. -[fn:140] If the publishing directory is the same as the source +[fn:141] If the publishing directory is the same as the source directory, =file.org= is exported as =file.org.org=, so you probably do not want to do this. -[fn:141] The option ~org-babel-no-eval-on-ctrl-c-ctrl-c~ can be used +[fn:142] The option ~org-babel-no-eval-on-ctrl-c-ctrl-c~ can be used to remove code evaluation from the {{{kbd(C-c C-c)}}} key binding. -[fn:142] Actually, the constructs =call_<name>()= and =src_<lang>{}= +[fn:143] Actually, the constructs =call_<name>()= and =src_<lang>{}= are not evaluated when they appear in a keyword (see [[*Summary of In-Buffer Settings]]). -[fn:143] C++ language is handled in =ob-C.el=. Even though the -identifier for such source blocks is =C++=, you activate it by loading -the C language. - -[fn:144] D language is handled in =ob-C.el=. Even though the -identifier for such source blocks is =D=, you activate it by loading -the C language. - -[fn:145] For noweb literate programming details, see +[fn:144] For noweb literate programming details, see http://www.cs.tufts.edu/~nr/noweb/. -[fn:146] For more information, please refer to the commentary section +[fn:145] For more information, please refer to the commentary section in =org-tempo.el=. -[fn:147] Org Indent mode also sets ~wrap-prefix~ correctly for +[fn:146] Org Indent mode also sets ~wrap-prefix~ correctly for indenting and wrapping long lines of headlines or text. This minor mode also handles Visual Line mode and directly applied settings through ~word-wrap~. -[fn:148] This works, but requires extra effort. Org Indent mode is +[fn:147] This works, but requires extra effort. Org Indent mode is more convenient for most applications. -[fn:149] ~org-adapt-indentation~ can also be set to ='headline-data=, +[fn:148] ~org-adapt-indentation~ can also be set to ='headline-data=, in which case only data lines below the headline will be indented. -[fn:150] Note that Org Indent mode also sets the ~wrap-prefix~ +[fn:149] Note that Org Indent mode also sets the ~wrap-prefix~ property, such that Visual Line mode (or purely setting ~word-wrap~) wraps long lines, including headlines, correctly indented. -[fn:151] For a server to host files, consider using a WebDAV server, +[fn:150] For a server to host files, consider using a WebDAV server, such as [[https://nextcloud.com][Nextcloud]]. Additional help is at this [[https://orgmode.org/worg/org-faq.html#mobileorg_webdav][FAQ entry]]. -[fn:152] If Emacs is configured for safe storing of passwords, then +[fn:151] If Emacs is configured for safe storing of passwords, then configure the variable ~org-mobile-encryption-password~; please read the docstring of that variable. -[fn:153] Symbolic links in ~org-directory~ need to have the same name +[fn:152] Symbolic links in ~org-directory~ need to have the same name as their targets. -[fn:154] While creating the agendas, Org mode forces =ID= properties +[fn:153] While creating the agendas, Org mode forces =ID= properties on all referenced entries, so that these entries can be uniquely identified if Org Mobile flags them for further action. To avoid setting properties configure the variable ~org-mobile-force-id-on-agenda-items~ to ~nil~. Org mode then relies on outline paths, assuming they are unique. -[fn:155] Checksums are stored automatically in the file +[fn:154] Checksums are stored automatically in the file =checksums.dat=. -[fn:156] The file will be empty after this operation. +[fn:155] The file will be empty after this operation. -[fn:157] https://www.ctan.org/pkg/comment +[fn:156] https://www.ctan.org/pkg/comment -[fn:158] By default this works only for LaTeX, HTML, and Texinfo. +[fn:157] By default this works only for LaTeX, HTML, and Texinfo. Configure the variable ~orgtbl-radio-table-templates~ to install templates for other modes. -[fn:159] If the =TBLFM= keyword contains an odd number of dollar +[fn:158] If the =TBLFM= keyword contains an odd number of dollar characters, this may cause problems with Font Lock in LaTeX mode. As shown in the example you can fix this by adding an extra line inside the =comment= environment that is used to balance the dollar @@ -21896,9 +22214,9 @@ expressions. If you are using AUCTeX with the font-latex library, a much better solution is to add the =comment= environment to the variable ~LaTeX-verbatim-environments~. -[fn:160] The ~agenda*~ view is the same as ~agenda~ except that it +[fn:159] The ~agenda*~ view is the same as ~agenda~ except that it only considers /appointments/, i.e., scheduled and deadline items that have a time specification =[h]h:mm= in their time-stamps. -[fn:161] Note that, for ~org-odd-levels-only~, a level number +[fn:160] Note that, for ~org-odd-levels-only~, a level number corresponds to order in the hierarchy, not to the number of stars. diff --git a/doc/misc/pgg.texi b/doc/misc/pgg.texi index 82495275fca..e796da6da37 100644 --- a/doc/misc/pgg.texi +++ b/doc/misc/pgg.texi @@ -27,7 +27,8 @@ modify this GNU manual.'' @dircategory Emacs network features @direntry -* PGG: (pgg). Emacs interface to various PGP implementations. +* PGG: (pgg). An obsolete Emacs interface to various + PGP implementations. @end direntry @titlepage diff --git a/doc/misc/rcirc.texi b/doc/misc/rcirc.texi index ae3a3b13e62..a4ca54a8b01 100644 --- a/doc/misc/rcirc.texi +++ b/doc/misc/rcirc.texi @@ -254,6 +254,10 @@ To make this permanent, add the following to your init file: Use @kbd{C-c C-@key{SPC}} to switch to these buffers. +@vindex rcirc-track-ignore-server-buffer-flag +If the user wishes to ignore events in the server buffer, set +@code{rcirc-track-ignore-server-buffer-flag} to a non-nil value. + @node Reference @chapter Reference @cindex reference @@ -426,7 +430,13 @@ lost. The simple solution is to use @kbd{M-x rcirc}. The problem is that this opens an @emph{additional} connection, so you'll have two copies of every channel buffer, one dead and one live. -The real answer, therefore, is the @code{/reconnect} command. +One option therefore, is the @code{/reconnect} command. + +An other approach is to set @code{rcirc-reconnect-delay} to a value +greater than 0, and allow rcirc to reconnect when it detects that the +connection has been closed. By default it will try to do this three +times (as specified by @code{rcirc-reconnect-attempts}), before giving +up. @end table @node Useful IRC commands @@ -671,6 +681,12 @@ window is showing them), the mode line will now show you the abbreviated channel or nick name. Use @kbd{C-c C-@key{SPC}} to switch to these buffers. +@cindex rcirc-track-abbrevate-flag +By default the channel names are abbreviated, set +@code{rcirc-track-abbrevate-flag} to a non-nil value. This might be +interesting if the IRC activities are not tracked in the mode line, +but somewhere else. + @vindex rcirc-mode-hook If you prefer not to load @code{rcirc} immediately, you can delay the activation of this mode: @@ -807,6 +823,19 @@ active and only omits a message if the nick has not been active. The window @code{rcirc} considers is controlled by the @code{rcirc-omit-threshold} variable. +@vindex rcirc-omit-unless-requested +Certain messages can be omitted by default, unless the user manual +requests them. For example, if you don't want to display @code{TOPIC} +and @code{NAMES} messages, after reconnecting, you can configure +@code{rcirc-omit-unless-requested} to hide: + +@example +(setq rcirc-omit-unless-requested '("TOPIC" "NAMES")) +@end example + +Now NAMES will only be displayed, after it has been requested via the +@code{rcirc-cmd-name} command. + @node Hacking and Tweaking @chapter Hacking and Tweaking @cindex hacking and tweaking @@ -819,6 +848,7 @@ Here are some examples of stuff you can do to configure @code{rcirc}. * Scrolling conservatively:: * Changing the time stamp format:: * Defining a new command:: +* Using rcirc with bouncers:: @end menu @node Skipping /away messages using handlers @@ -903,20 +933,48 @@ how to include the date in the time stamp: @cindex new commands, defining Here's a simple new command, @code{/sv}. With it, you can boast about -your IRC client. It shows how you can use @code{defun-rcirc-command} to +your IRC client. It shows how you can use @code{rcirc-define-command} to define new commands. +@findex rcirc-define-command We're waiting for the definition of this command until @code{rcirc} is loaded -because @code{defun-rcirc-command} is not yet available, and without +because @code{rcirc-define-command} is not yet available, and without @code{rcirc} loaded, the command wouldn't do us much good anyway. @smallexample (with-eval-after-load 'rcirc - (defun-rcirc-command sv (arg) + (rcirc-define-command sv () "Boast about rcirc." (interactive "i") - (rcirc-send-message process target - (concat "I use " rcirc-id-string)))) + (rcirc-send-message process target "I use " rcirc-id-string))) +@end smallexample + +@node Using rcirc with bouncers +@section Using rcirc with bouncers +@cindex bouncer + +Some bouncers multiplex connections to various servers, but have to +modify nicks and channel names to make this work. The channel +@code{#emacs} on @code{irc.libera.chat} becomes +@code{#emacs/irc.libera.chat}. + +@vindex rcirc-nick-filter +@vindex rcirc-channel-filter +The options @code{rcirc-nick-filter} and @code{rcirc-channel-filter} +can be used to make this feel more natural. When set to functions, +these will be used to change how nicks and channel names are +displayed. A simple configuration to fix the above example might be: + +@smallexample +(defun my/rcirc-remove-suffix (STR) + "Remove suffixes from STR." + (save-match-data + (if (string-match "/[[:alpha:]]+?\\'" str) + (substring str 0 (match-beginning 0)) + str))) + +(setq rcirc-nick-filter #'my/rcirc-remove-suffix + rcirc-channel-filter #'local/rcirc-soju-suffix) @end smallexample @node GNU Free Documentation License diff --git a/doc/misc/reftex.texi b/doc/misc/reftex.texi index 88ca4450d59..8bde241e18f 100644 --- a/doc/misc/reftex.texi +++ b/doc/misc/reftex.texi @@ -658,9 +658,9 @@ variable @code{reftex-auto-recenter-toc}. @end table -@vindex reftex-toc-map +@vindex reftex-toc-mode-map In order to define additional commands for the @file{*toc*} buffer, the -keymap @code{reftex-toc-map} may be used. +keymap @code{reftex-toc-mode-map} may be used. @findex reftex-toc-recenter @vindex reftex-auto-recenter-toc @@ -1021,9 +1021,9 @@ document and let you select a label from there (@pxref{LaTeX xr Package,,xr}). @end table -@vindex reftex-select-label-map +@vindex reftex-select-label-mode-map In order to define additional commands for the selection process, the -keymap @code{reftex-select-label-map} may be used. +keymap @code{reftex-select-label-mode-map} may be used. @node Builtin Label Environments @section Builtin Label Environments @@ -1871,9 +1871,9 @@ entries. @end table -@vindex reftex-select-bib-map +@vindex reftex-select-bib-mode-map In order to define additional commands for this selection process, the -keymap @code{reftex-select-bib-map} may be used. +keymap @code{reftex-select-bib-mode-map} may be used. Note that if you do not use Emacs to edit the @BibTeX{} database files, @RefTeX{} will ask if the related buffers should be updated once it @@ -3192,7 +3192,7 @@ with the @kbd{g} key. To get this behavior, use instead @AUCTeX{} is without doubt the best major mode for editing @TeX{} and @LaTeX{} files with Emacs (@pxref{Top,AUCTeX,,auctex, The AUCTeX User Manual}). -You can get it from its home page at @value{AUCTEXSITE}, but since +You can get it from its website at @value{AUCTEXSITE}, but since it is available from GNU ELPA, you can simply install it from @kbd{M-x list-packages}. @@ -3565,7 +3565,7 @@ With @i{Viper} mode prior to Vipers version 3.01, you need to protect @cindex Acknowledgments @cindex Thanks @cindex Bug reports -@cindex @code{http}, @RefTeX{} home page +@cindex @code{http}, @RefTeX{} website @cindex @code{ftp}, @RefTeX{} site @c dominik@@science.uva.nl @@ -3960,7 +3960,7 @@ Normal hook which is run when a @file{*toc*} buffer is created. @end deffn -@deffn Keymap reftex-toc-map +@deffn Keymap reftex-toc-mode-map The keymap which is active in the @file{*toc*} buffer. (@pxref{Table of Contents}). @end deffn @@ -4425,7 +4425,7 @@ Normal hook which is run when a selection buffer enters @code{reftex-select-label-mode}. @end deffn -@deffn Keymap reftex-select-label-map +@deffn Keymap reftex-select-label-mode-map The keymap which is active in the labels selection process (@pxref{Referencing Labels}). @end deffn @@ -4586,7 +4586,7 @@ Normal hook which is run when a selection buffer enters @code{reftex-select-bib-mode}. @end deffn -@deffn Keymap reftex-select-bib-map +@deffn Keymap reftex-select-bib-mode-map The keymap which is active in the citation-key selection process (@pxref{Creating Citations}). @end deffn @@ -4792,7 +4792,7 @@ into blocks. Sorting will then preserve blocks, so that lines are re-arranged only within blocks. @end defopt -@defopt reftex-index-phrases-map +@defopt reftex-index-phrases-mode-map Keymap for the Index Phrases buffer. @end defopt @@ -4824,7 +4824,7 @@ the document. This flag can be toggled from within the @file{*Index*} buffer with the @kbd{f} key. @end defopt -@deffn Keymap reftex-index-map +@deffn Keymap reftex-index-mode-map The keymap which is active in the @file{*Index*} buffer (@pxref{Index Support}). @end deffn @@ -5813,8 +5813,8 @@ buffer). @noindent @b{Version 3.12} @itemize @bullet @item -There are 3 new keymaps for customization: @code{reftex-toc-map}, -@code{reftex-select-label-map}, @code{reftex-select-bib-map}. +There are 3 new keymaps for customization: @code{reftex-toc-mode-map}, +@code{reftex-select-label-mode-map}, @code{reftex-select-bib-mode-map}. @item Refontification uses more standard font-lock stuff. @item diff --git a/doc/misc/smtpmail.texi b/doc/misc/smtpmail.texi index ca7dabe6545..f5d567533b6 100644 --- a/doc/misc/smtpmail.texi +++ b/doc/misc/smtpmail.texi @@ -264,12 +264,14 @@ file, @pxref{Top,,auth-source, auth, Emacs auth-source Library}. @cindex CRAM-MD5 @cindex PLAIN @cindex LOGIN -The process by which the SMTP library authenticates you to the server -is known as ``Simple Authentication and Security Layer'' (SASL). -There are various SASL mechanisms, and this library supports three of -them: CRAM-MD5, PLAIN, and LOGIN, where the first uses a form of +The process by which the @acronym{SMTP} library authenticates you to +the server is known as ``Simple Authentication and Security Layer'' +(@acronym{SASL}). There are various @acronym{SASL} mechanisms, and +this library supports three of them: @code{cram-md5}, @code{plain}, +@code{login} and @code{xoauth2}, where the first uses a form of encryption to obscure your password, while the other two do not. It -tries each of them, in that order, until one succeeds. You can +tries each of them, in that order, until one succeeds. +(@code{xoauth2} requires using the @file{oauth2.el} library. You can override this by assigning a specific authentication mechanism to a server by including a key @code{smtp-auth} with the value of your preferred mechanism in the appropriate @file{~/.authinfo} entry. diff --git a/doc/misc/speedbar.texi b/doc/misc/speedbar.texi index 9991917b3fd..70d4b054166 100644 --- a/doc/misc/speedbar.texi +++ b/doc/misc/speedbar.texi @@ -896,7 +896,7 @@ augmented with speedbar. @enumerate @item -Create the keymap variable @code{@var{name}-speedbar-key-map}. +Create the keymap variable @code{@var{name}-speedbar-mode-map}. @item Create a function, named whatever you like, which assigns values into your @@ -904,7 +904,7 @@ keymap. Use this command to create the keymap before assigning bindings: @smallexample - (setq @var{name}-speedbar-key-map (speedbar-make-specialized-keymap)) + (setq @var{name}-speedbar-mode-map (speedbar-make-specialized-keymap)) @end smallexample This function creates a special keymap for use in speedbar. @@ -977,7 +977,7 @@ Next, register your extension like this; @example (speedbar-add-expansion-list '("MyExtension" MyExtension-speedbar-menu-items - MyExtension-speedbar-key-map + MyExtension-speedbar-mode-map MyExtension-speedbar-buttons)) @end example diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex index a91181b116e..e48383defc4 100644 --- a/doc/misc/texinfo.tex +++ b/doc/misc/texinfo.tex @@ -3,9 +3,9 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2020-11-25.18} +\def\texinfoversion{2021-04-25.21} % -% Copyright 1985, 1986, 1988, 1990-2020 Free Software Foundation, Inc. +% Copyright 1985, 1986, 1988, 1990-2021 Free Software Foundation, Inc. % % This texinfo.tex file is free software: you can redistribute it and/or % modify it under the terms of the GNU General Public License as @@ -574,7 +574,7 @@ % @end foo calls \checkenv and executes the definition of \Efoo. -\parseargdef\end{ +\parseargdef\end{% \if 1\csname iscond.#1\endcsname \else % The general wording of \badenverr may not be ideal. @@ -1002,6 +1002,14 @@ where each line of input produces a line of output.} \global\everypar = {}% } +% leave vertical mode without cancelling any first paragraph indent +\gdef\imageindent{% + \toks0=\everypar + \everypar={}% + \ptexnoindent + \global\everypar=\toks0 +} + % @refill is a no-op. \let\refill=\relax @@ -1181,7 +1189,7 @@ where each line of input produces a line of output.} % double any backslashes. Otherwise, a name like "\node" will be % interpreted as a newline (\n), followed by o, d, e. Not good. % -% See https://mailman.ntg.nl/pipermail/ntg-pdftex/2004-July/000654.html and +% See http://www.ntg.nl/pipermail/ntg-pdftex/2004-July/000654.html and % related messages. The final outcome is that it is up to the TeX user % to double the backslashes and otherwise make the string valid, so % that's what we do. pdftex 1.30.0 (ca.2005) introduced a primitive to @@ -1862,19 +1870,23 @@ output) for that.)} \closein 1 \endgroup % - \def\xetexpdfext{pdf}% - \ifx\xeteximgext\xetexpdfext - \XeTeXpdffile "#1".\xeteximgext "" - \else - \def\xetexpdfext{PDF}% + % Putting an \hbox around the image can prevent an over-long line + % after the image. + \hbox\bgroup + \def\xetexpdfext{pdf}% \ifx\xeteximgext\xetexpdfext \XeTeXpdffile "#1".\xeteximgext "" \else - \XeTeXpicfile "#1".\xeteximgext "" + \def\xetexpdfext{PDF}% + \ifx\xeteximgext\xetexpdfext + \XeTeXpdffile "#1".\xeteximgext "" + \else + \XeTeXpicfile "#1".\xeteximgext "" + \fi \fi - \fi - \ifdim \wd0 >0pt width \xeteximagewidth \fi - \ifdim \wd2 >0pt height \xeteximageheight \fi \relax + \ifdim \wd0 >0pt width \xeteximagewidth \fi + \ifdim \wd2 >0pt height \xeteximageheight \fi \relax + \egroup } \fi @@ -3539,7 +3551,7 @@ $$% % We use the free feym* fonts from the eurosym package by Henrik % Theiling, which support regular, slanted, bold and bold slanted (and % "outlined" (blackboard board, sort of) versions, which we don't need). -% It is available from https://www.ctan.org/tex-archive/fonts/eurosym. +% It is available from http://www.ctan.org/tex-archive/fonts/eurosym. % % Although only regular is the truly official Euro symbol, we ignore % that. The Euro is designed to be slightly taller than the regular @@ -4289,82 +4301,8 @@ $$% \doitemize{#1.}\flushcr } -% @alphaenumerate and @capsenumerate are abbreviations for giving an arg -% to @enumerate. -% -\def\alphaenumerate{\enumerate{a}} -\def\capsenumerate{\enumerate{A}} -\def\Ealphaenumerate{\Eenumerate} -\def\Ecapsenumerate{\Eenumerate} - % @multitable macros -% Amy Hendrickson, 8/18/94, 3/6/96 -% -% @multitable ... @end multitable will make as many columns as desired. -% Contents of each column will wrap at width given in preamble. Width -% can be specified either with sample text given in a template line, -% or in percent of \hsize, the current width of text on page. - -% Table can continue over pages but will only break between lines. - -% To make preamble: -% -% Either define widths of columns in terms of percent of \hsize: -% @multitable @columnfractions .25 .3 .45 -% @item ... -% -% Numbers following @columnfractions are the percent of the total -% current hsize to be used for each column. You may use as many -% columns as desired. - - -% Or use a template: -% @multitable {Column 1 template} {Column 2 template} {Column 3 template} -% @item ... -% using the widest term desired in each column. - -% Each new table line starts with @item, each subsequent new column -% starts with @tab. Empty columns may be produced by supplying @tab's -% with nothing between them for as many times as empty columns are needed, -% ie, @tab@tab@tab will produce two empty columns. - -% @item, @tab do not need to be on their own lines, but it will not hurt -% if they are. - -% Sample multitable: - -% @multitable {Column 1 template} {Column 2 template} {Column 3 template} -% @item first col stuff @tab second col stuff @tab third col -% @item -% first col stuff -% @tab -% second col stuff -% @tab -% third col -% @item first col stuff @tab second col stuff -% @tab Many paragraphs of text may be used in any column. -% -% They will wrap at the width determined by the template. -% @item@tab@tab This will be in third column. -% @end multitable - -% Default dimensions may be reset by user. -% @multitableparskip is vertical space between paragraphs in table. -% @multitableparindent is paragraph indent in table. -% @multitablecolmargin is horizontal space to be left between columns. -% @multitablelinespace is space to leave between table items, baseline -% to baseline. -% 0pt means it depends on current normal line spacing. -% -\newskip\multitableparskip -\newskip\multitableparindent -\newdimen\multitablecolspace -\newskip\multitablelinespace -\multitableparskip=0pt -\multitableparindent=6pt -\multitablecolspace=12pt -\multitablelinespace=0pt % Macros used to set up halign preamble: % @@ -4412,8 +4350,6 @@ $$% \go } -% multitable-only commands. -% % @headitem starts a heading row, which we typeset in bold. Assignments % have to be global since we are inside the implicit group of an % alignment entry. \everycr below resets \everytab so we don't have to @@ -4430,14 +4366,8 @@ $$% % default for tables with no headings. \let\headitemcrhook=\relax % -% A \tab used to include \hskip1sp. But then the space in a template -% line is not enough. That is bad. So let's go back to just `&' until -% we again encounter the problem the 1sp was intended to solve. -% --karl, nathan@acm.org, 20apr99. \def\tab{\checkenv\multitable &\the\everytab}% -% @multitable ... @end multitable definitions: -% \newtoks\everytab % insert after every tab. % \envdef\multitable{% @@ -4452,9 +4382,8 @@ $$% % \tolerance=9500 \hbadness=9500 - \setmultitablespacing - \parskip=\multitableparskip - \parindent=\multitableparindent + \parskip=0pt + \parindent=6pt \overfullrule=0pt \global\colcount=0 % @@ -4484,47 +4413,24 @@ $$% % continue for many paragraphs if desired. \halign\bgroup &% \global\advance\colcount by 1 - \multistrut + \strut \vtop{% - % Use the current \colcount to find the correct column width: + \advance\hsize by -1\leftskip + % Find the correct column width \hsize=\expandafter\csname col\the\colcount\endcsname % - % In order to keep entries from bumping into each other - % we will add a \leftskip of \multitablecolspace to all columns after - % the first one. - % - % If a template has been used, we will add \multitablecolspace - % to the width of each template entry. - % - % If the user has set preamble in terms of percent of \hsize we will - % use that dimension as the width of the column, and the \leftskip - % will keep entries from bumping into each other. Table will start at - % left margin and final column will justify at right margin. - % - % Make sure we don't inherit \rightskip from the outer environment. \rightskip=0pt \ifnum\colcount=1 - % The first column will be indented with the surrounding text. - \advance\hsize by\leftskip + \advance\hsize by\leftskip % Add indent of surrounding text \else - \ifsetpercent \else - % If user has not set preamble in terms of percent of \hsize - % we will advance \hsize by \multitablecolspace. - \advance\hsize by \multitablecolspace - \fi - % In either case we will make \leftskip=\multitablecolspace: - \leftskip=\multitablecolspace + % In order to keep entries from bumping into each other. + \leftskip=12pt + \ifsetpercent \else + % If a template has been used + \advance\hsize by \leftskip + \fi \fi - % Ignoring space at the beginning and end avoids an occasional spurious - % blank line, when TeX decides to break the line at the space before the - % box from the multistrut, so the strut ends up on a line by itself. - % For example: - % @multitable @columnfractions .11 .89 - % @item @code{#} - % @tab Legal holiday which is valid in major parts of the whole country. - % Is automatically provided with highlighting sequences respectively - % marking characters. - \noindent\ignorespaces##\unskip\multistrut + \noindent\ignorespaces##\unskip\strut }\cr } \def\Emultitable{% @@ -4533,31 +4439,6 @@ $$% \global\setpercentfalse } -\def\setmultitablespacing{% - \def\multistrut{\strut}% just use the standard line spacing - % - % Compute \multitablelinespace (if not defined by user) for use in - % \multitableparskip calculation. We used define \multistrut based on - % this, but (ironically) that caused the spacing to be off. - % See bug-texinfo report from Werner Lemberg, 31 Oct 2004 12:52:20 +0100. -\ifdim\multitablelinespace=0pt -\setbox0=\vbox{X}\global\multitablelinespace=\the\baselineskip -\global\advance\multitablelinespace by-\ht0 -\fi -% Test to see if parskip is larger than space between lines of -% table. If not, do nothing. -% If so, set to same dimension as multitablelinespace. -\ifdim\multitableparskip>\multitablelinespace -\global\multitableparskip=\multitablelinespace -\global\advance\multitableparskip-7pt % to keep parskip somewhat smaller - % than skip between lines in the table. -\fi% -\ifdim\multitableparskip=0pt -\global\multitableparskip=\multitablelinespace -\global\advance\multitableparskip-7pt % to keep parskip somewhat smaller - % than skip between lines in the table. -\fi} - \message{conditionals,} @@ -5171,30 +5052,29 @@ $$% \let\lbracechar\{% \let\rbracechar\}% % + % Non-English letters. + \def\AA{AA}% + \def\AE{AE}% + \def\DH{DZZ}% + \def\L{L}% + \def\OE{OE}% + \def\O{O}% + \def\TH{TH}% + \def\aa{aa}% + \def\ae{ae}% + \def\dh{dzz}% + \def\exclamdown{!}% + \def\l{l}% + \def\oe{oe}% + \def\ordf{a}% + \def\ordm{o}% + \def\o{o}% + \def\questiondown{?}% + \def\ss{ss}% + \def\th{th}% % \let\do\indexnofontsdef % - % Non-English letters. - \do\AA{AA}% - \do\AE{AE}% - \do\DH{DZZ}% - \do\L{L}% - \do\OE{OE}% - \do\O{O}% - \do\TH{TH}% - \do\aa{aa}% - \do\ae{ae}% - \do\dh{dzz}% - \do\exclamdown{!}% - \do\l{l}% - \do\oe{oe}% - \do\ordf{a}% - \do\ordm{o}% - \do\o{o}% - \do\questiondown{?}% - \do\ss{ss}% - \do\th{th}% - % \do\LaTeX{LaTeX}% \do\TeX{TeX}% % @@ -8931,7 +8811,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% \else \ifhavexrefs % We (should) know the real title if we have the xref values. - \def\printedrefname{\refx{#1-title}{}}% + \def\printedrefname{\refx{#1-title}}% \else % Otherwise just copy the Info node name. \def\printedrefname{\ignorespaces #1}% @@ -9025,7 +8905,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% % If the user specified the print name (third arg) to the ref, % print it instead of our usual "Figure 1.2". \ifdim\wd\printedrefnamebox = 0pt - \refx{#1-snt}{}% + \refx{#1-snt}% \else \printedrefname \fi @@ -9060,9 +8940,9 @@ might help (with 'rm \jobname.?? \jobname.??s')% \else % Reference within this manual. % - % Only output a following space if the -snt ref is nonempty; for - % @unnumbered and @anchor, it won't be. - \setbox2 = \hbox{\ignorespaces \refx{#1-snt}{}}% + % Only output a following space if the -snt ref is nonempty, as the ref + % will be empty for @unnumbered and @anchor. + \setbox2 = \hbox{\ignorespaces \refx{#1-snt}}% \ifdim \wd2 > 0pt \refx{#1-snt}\space\fi % % output the `[mynode]' via the macro below so it can be overridden. @@ -9073,7 +8953,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% ,\space % % output the `page 3'. - \turnoffactive \putwordpage\tie\refx{#1-pg}{}% + \turnoffactive \putwordpage\tie\refx{#1-pg}% % Add a , if xref followed by a space \if\space\noexpand\tokenafterxref ,% \else\ifx\ \tokenafterxref ,% @TAB @@ -9150,9 +9030,8 @@ might help (with 'rm \jobname.?? \jobname.??s')% \fi\fi\fi } -% \refx{NAME}{SUFFIX} - reference a cross-reference string named NAME. SUFFIX -% is output afterwards if non-empty. -\def\refx#1#2{% +% \refx{NAME} - reference a cross-reference string named NAME. +\def\refx#1{% \requireauxfile {% \indexnofonts @@ -9179,7 +9058,6 @@ might help (with 'rm \jobname.?? \jobname.??s')% % It's defined, so just use it. \thisrefX \fi - #2% Output the suffix in any case. } % This is the macro invoked by entries in the aux file. Define a control @@ -9289,10 +9167,10 @@ might help (with 'rm \jobname.?? \jobname.??s')% \catcode`\[=\other \catcode`\]=\other \catcode`\"=\other - \catcode`\_=\other - \catcode`\|=\other - \catcode`\<=\other - \catcode`\>=\other + \catcode`\_=\active + \catcode`\|=\active + \catcode`\<=\active + \catcode`\>=\active \catcode`\$=\other \catcode`\#=\other \catcode`\&=\other @@ -9539,7 +9417,7 @@ might help (with 'rm \jobname.?? \jobname.??s')% % On the other hand, if we are in the case of @center @image, we don't % want to start a paragraph, which will create a hsize-width box and % eradicate the centering. - \ifx\centersub\centerV\else \noindent \fi + \ifx\centersub\centerV \else \imageindent \fi % % Output the image. \ifpdf @@ -11731,3 +11609,4 @@ directory should work if nowhere else does.} @c vim:sw=2: @enablebackslashhack + diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 088352e8a8a..a17a8d67e5b 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -290,7 +290,7 @@ file's contents. For external transfers, @value{tramp} sends a command as follows: @example -rcp user@@host:/path/to/remote/file /tmp/tramp.4711 +$ rcp user@@host:/path/to/remote/file /tmp/tramp.4711 @end example @value{tramp} reads the local temporary file @file{/tmp/tramp.4711} into a buffer, and then deletes the temporary file. @@ -1071,7 +1071,7 @@ capable of servicing requests from @value{tramp}. This non-native @value{tramp} method connects via the Server Message Block (SMB) networking protocol to hosts running file servers that are -typically based on @url{https://www.samba.org/,,Samba} or MS Windows. +typically based on @uref{https://www.samba.org/,,Samba} or MS Windows. Using @command{smbclient} requires a few tweaks when working with @value{tramp}: @@ -1290,7 +1290,7 @@ they are added here for the benefit of @ref{Archive file names}. If you want to use @acronym{GVFS}-based @option{ftp} or @option{smb} methods, you must add them to @code{tramp-gvfs-methods}, and you must -disable the corresponding Tramp package by setting +disable the corresponding @value{tramp} package by setting @code{tramp-ftp-method} or @code{tramp-smb-method} to @code{nil}, respectively: @@ -1323,7 +1323,7 @@ possible, @value{tramp} emulates those operations otherwise. @vindex tramp-rclone-program The program @command{rclone} allows to access different system -storages in the cloud, see @url{https://rclone.org/} for a list of +storages in the cloud, see @uref{https://rclone.org/} for a list of supported systems. If the @command{rclone} program isn't found in your @env{PATH} environment variable, you can tell @value{tramp} its absolute path via the user option @code{tramp-rclone-program}. @@ -1362,7 +1362,7 @@ for accessing the system storage, you should use it. On local hosts which have installed the @command{sshfs} client for mounting a file system based on @command{sftp}, this method can be used, see -@url{https://github.com/libfuse/sshfs/blob/master/README.rst/}. If +@uref{https://github.com/libfuse/sshfs/blob/master/README.rst/}. If the @command{sshfs} program isn't found in your @env{PATH} environment variable, you can tell @value{tramp} its absolute path via the user option @code{tramp-sshfs-program}. @@ -2122,9 +2122,9 @@ to construct these lists. @item @t{"remote-shell"} -This property tells Tramp which remote shell to apply on the remote -host. It is used in all connection methods of @file{tramp-sh.el}. -The default value is @t{"/bin/sh"}. +This property tells @value{tramp} which remote shell to apply on the +remote host. It is used in all connection methods of +@file{tramp-sh.el}. The default value is @t{"/bin/sh"}. @item @t{"remote-shell-login"} @@ -2310,9 +2310,9 @@ trouble with the shell prompt due to set zle options will be avoided. For @command{bash}, loading @file{~/.editrc} or @file{~/.inputrc} is suppressed. -Similar problems can happen with the local shell Tramp uses to create -a process. By default, it uses the command @command{/bin/sh} for -this, which could also be a link to another shell. In order to +Similar problems can happen with the local shell @value{tramp} uses to +create a process. By default, it uses the command @command{/bin/sh} +for this, which could also be a link to another shell. In order to overwrite this, you might apply @vindex tramp-encoding-shell @@ -2610,7 +2610,7 @@ where @samp{192.168.0.1} is the remote host IP address @node FUSE setup @section @acronym{FUSE} setup hints -The @acronym{FUSE} file systems are mounted per default at +The @acronym{FUSE} file systems are mounted by default at @file{/tmp/tramp.method.user@@host#port}. The user name and port number are optional. If the file system is already mounted, it will be used as it is. If the mount point does not exist yet, @@ -2629,6 +2629,11 @@ Example: @end group @end lisp +@vindex tramp-fuse-unmount-on-cleanup +The user option @code{tramp-fuse-unmount-on-cleanup}, when set to +non-@code{nil}, controls, whether a mount point is unmounted on +connection cleanup or on Emacs exiting. + @anchor{Setup of rclone method} @subsection @option{rclone} setup @@ -3231,7 +3236,10 @@ directory @file{/sbin} on your local host. Type @kbd{s h @value{postfixhop}} for the minibuffer completion to @samp{@value{prefix}ssh@value{postfixhop}}. Typing @kbd{@key{TAB}} shows host names @value{tramp} extracts from @file{~/.ssh/config} -file, for example. +@c bug#50387 +file, for example@footnote{Some completion styles, like +@code{substring} or @code{flex}, require to type at least one +character after the trailing @samp{@value{postfixhop}}.}. @example @group @@ -3734,6 +3742,33 @@ To open @command{powershell} as a remote shell, use this: @end lisp +@subsection Remote process connection type +@vindex process-connection-type +@cindex tramp-process-connection-type + +Asynchronous processes behave differently based on whether they use a +pseudo tty or not. This is controlled by the variable +@code{process-connection-type}, which can be @code{t} or @code{pty} +(use a pseudo tty), or @code{nil} or @code{pipe} (don't use one). +@value{tramp} is based on running shells on the remote host, which +requires a pseudo tty. Therefore, it declares the variable +@code{tramp-process-connection-type}, which carries this information +for remote processes. Its default value is @code{t}, and there is no +need to change it. The name of the remote pseudo tty is returned by +the function @code{process-tty-name}. + +If a remote process, started by @code{start-file-process}, should +@emph{not} use a pseudo tty, this can be requested by setting +@code{process-connection-type} to @code{nil} or @code{pipe}. There is +still a pseudo tty for the started process, but some terminal +properties are changed, like suppressing translation of carriage +return characters into newline. + +The function @code{make-process} allows controlling this explicitly by +using the @code{:connection-type} keyword. If this keyword is not +used, the value of @code{process-connection-type} is applied instead. + + @anchor{Improving performance of asynchronous remote processes} @subsection Improving performance of asynchronous remote processes @cindex Asynchronous remote processes @@ -4255,7 +4290,17 @@ test, @ref{Cleanup remote connections}. Alternatively, and often better for analysis, reproduce the problem in a clean Emacs session started with @command{emacs -Q}. Then, @value{tramp} does not load the persistency file (@pxref{Connection caching}), and it does not use -passwords from @file{auth-source.el} (@pxref{Password handling}). +passwords from @file{auth-source.el} (@pxref{Password handling}). The +latter does not happen for the @option{sudoedit} method, otherwise it +would be unusable. + +If you use the GNU ELPA version of @value{tramp}, you must load it +explicitly, because @command{emacs -Q} ignores installed ELPA +packages. Call (version number adapted) + +@example +$ emacs -Q -l ~/.emacs.d/elpa/tramp-2.4.5.1/tramp-autoloads +@end example When including @value{tramp}'s messages in the bug report, increase the verbosity level to 6 (@pxref{Traces and Profiles, Traces}) in the @@ -4266,6 +4311,11 @@ non-@acronym{ASCII} characters which are relevant for analysis, append the buffers as attachments to the bug report. This is also needed in order to avoid line breaks during mail transfer. +If you send the message from Emacs, you are asked about to append +these buffers to the bug report. If you use an external mail program, +you must save these buffers to files, and append them with that mail +program. + @strong{Note} that a verbosity level greater than 6 is not necessary at this stage. Also note that a verbosity level of 6 or greater, the contents of files and directories will be included in the debug @@ -4576,6 +4626,16 @@ supported on your proxy host. @item +Does @value{tramp} support @acronym{SSH} security keys? + +Yes. @command{OpenSSH} has added support for @acronym{FIDO} hardware +devices via special key types @option{*-sk}. @value{tramp} supports +the additional handshaking messages for them. This requires at least +@command{OpenSSH} 8.2, and a @acronym{FIDO} @acronym{U2F} compatible +security key, like yubikey, solokey, or nitrokey. + + +@item @value{tramp} does not connect to Samba or MS Windows hosts running SMB1 connection protocol @@ -5049,7 +5109,7 @@ location. Then start Emacs Client from the command line: @example -emacsclient @trampfn{ssh,user@@host,/file/to/edit} +$ emacsclient @trampfn{ssh,user@@host,/file/to/edit} @end example @code{user} and @code{host} refer to the local host. @@ -5069,7 +5129,7 @@ Then change the environment variable @env{EDITOR} to point to the wrapper script: @example -export EDITOR=/path/to/emacsclient.sh +$ export EDITOR=/path/to/emacsclient.sh @end example @@ -5132,12 +5192,15 @@ tramp-compat-with-mutex} @value{tramp} comes with compatibility code for different Emacs versions. When you see such a message (the text might differ), you -don't use the Emacs built-in version of @value{tramp}. In case you -have installed @value{tramp} from GNU ELPA, see the package README -file for instructions how to recompile it. +don't use the Emacs built-in version of @value{tramp}, and you must +recompile it. In case you have installed @value{tramp} from GNU ELPA, @ifset installchapter -@xref{Recompilation}. +@xref{ELPA Installation}. Otherwise, @xref{Recompilation}. @end ifset +@ifclear installchapter +see @uref{@value{trampurl}#ELPA-Installation}. Otherwise, see +@uref{@value{trampurl}#Recompilation}. +@end ifclear @item @@ -5266,6 +5329,12 @@ handlers. @node External packages @section Integrating with external Lisp packages + +In general, it is not recommended to use @value{tramp} functions and +variables not described in this manual. They might change their +signature and/or semantics without any announcement. + + @subsection File name completion @vindex non-essential diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index 10c951d3ccf..b11ee39f884 100644 --- a/doc/misc/trampver.texi +++ b/doc/misc/trampver.texi @@ -8,7 +8,7 @@ @c In the Tramp GIT, the version numbers are auto-frobbed from @c tramp.el, and the bug report address is auto-frobbed from @c configure.ac. -@set trampver 2.5.1 +@set trampver 2.5.2-pre @set trampurl https://www.gnu.org/software/tramp/ @set tramp-bug-report-address tramp-devel@@gnu.org @set emacsver 25.1 |