diff options
Diffstat (limited to 'doc')
108 files changed, 6216 insertions, 3476 deletions
diff --git a/doc/emacs/ChangeLog.1 b/doc/emacs/ChangeLog.1 index 99faff1623c..b9f7e49fc91 100644 --- a/doc/emacs/ChangeLog.1 +++ b/doc/emacs/ChangeLog.1 @@ -4398,7 +4398,7 @@ mail-header-separator. (Mail Headers): Put info about initialization and changing in one place at the start. Update FCC section for mbox Rmail. Clarify From - section, mention mail-setup-with-from. Clarify Reply-to section. + section, mention mail-setup-with-from. Clarify Reply-To section. Add Mail-followup-to and mail-mailing-lists. Clarify References section. (Mail Aliases): Update example, make less contentious. diff --git a/doc/emacs/Makefile.in b/doc/emacs/Makefile.in index fa451b1f927..01c6700197c 100644 --- a/doc/emacs/Makefile.in +++ b/doc/emacs/Makefile.in @@ -206,8 +206,8 @@ doc-emacsver: ## Temp files. mostlyclean: - rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \ - *.op *.ops *.pg *.pgs *.tp *.tps *.vr *.vrs + rm -f ./*.aux ./*.log ./*.toc ./*.cp ./*.cps ./*.fn ./*.fns ./*.ky ./*.kys \ + ./*.op ./*.ops ./*.pg ./*.pgs ./*.tp ./*.tps ./*.vr ./*.vrs ## Products not in the release tarfiles. clean: mostlyclean diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi index 0e4a982da40..06e75f30773 100644 --- a/doc/emacs/ack.texi +++ b/doc/emacs/ack.texi @@ -503,10 +503,6 @@ Tassilo Horn wrote DocView mode, allowing viewing of PDF, PostScript and DVI documents. @item -Tom Houlder wrote @file{mantemp.el}, which generates manual C@t{++} -template instantiations. - -@item Joakim Hove wrote @file{html2text.el}, a html to plain text converter. @item diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi index cd7c1ff895e..37e2f9e5818 100644 --- a/doc/emacs/arevert-xtra.texi +++ b/doc/emacs/arevert-xtra.texi @@ -4,8 +4,9 @@ @c @c This file is included either in emacs-xtra.texi (when producing the @c printed version) or in the main Emacs manual (for the on-line version). -@node Autorevert -@section Auto Reverting Non-File Buffers + +@node Non-File Buffers +@subsection Auto Reverting Non-File Buffers Global Auto Revert Mode normally only reverts file buffers. There are two ways to auto-revert certain non-file buffers: by enabling Auto @@ -34,6 +35,14 @@ the Buffer Menu.) In this case, Auto Revert does not print any messages while reverting, even when @code{auto-revert-verbose} is non-@code{nil}. +@vindex buffer-auto-revert-by-notification +Some non-file buffers can be updated reliably by file notification on +their default directory; Dired buffers is an example. The major mode +can indicate this by setting @code{buffer-auto-revert-by-notification} +to a non-@code{nil} value in that buffer, allowing Auto Revert to +avoid periodic polling. Such notification does not include changes to +files in that directory, only to the directory itself. + The details depend on the particular types of buffers and are explained in the corresponding sections. @@ -43,7 +52,7 @@ explained in the corresponding sections. @end menu @node Auto Reverting the Buffer Menu -@subsection Auto Reverting the Buffer Menu +@subsubsection Auto Reverting the Buffer Menu If auto-reverting of non-file buffers is enabled, the Buffer Menu @iftex @@ -65,7 +74,7 @@ adding marks sets the buffer's modified flag prevents Auto Revert from automatically erasing the marks. @node Auto Reverting Dired -@subsection Auto Reverting Dired buffers +@subsubsection Auto Reverting Dired buffers Dired buffers only auto-revert when the file list of the buffer's main directory changes (e.g., when a new file is added or deleted). They diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi index 27fcb7369a9..269f9f7d6fe 100644 --- a/doc/emacs/buffers.texi +++ b/doc/emacs/buffers.texi @@ -550,6 +550,18 @@ Sort the Buffer Menu entries according to their values in the column at point. With a numeric prefix argument @var{n}, sort according to the @var{n}-th column (@code{tabulated-list-sort}). +@item @} +@kindex @} @r{(Buffer Menu)} +@findex tabulated-list-widen-current-column +Widen the current column width by @var{n} (the prefix numeric +argument) characters. + +@item @{ +@kindex @{ @r{(Buffer Menu)} +@findex tabulated-list-narrow-current-column +Narrow the current column width by @var{n} (the prefix numeric +argument) characters. + @item T @findex Buffer-menu-toggle-files-only @kindex T @r{(Buffer Menu)} @@ -568,10 +580,10 @@ mode in this buffer, as long as it is not marked modified. Global Auto Revert mode applies to the @file{*Buffer List*} buffer only if @code{global-auto-revert-non-file-buffers} is non-@code{nil}. @iftex -@inforef{Autorevert,, emacs-xtra}, for details. +@inforef{Auto Reverting the Buffer Menu,, emacs-xtra}, for details. @end iftex @ifnottex -@xref{Autorevert, global-auto-revert-non-file-buffers}, for details. +@xref{Auto Reverting the Buffer Menu, global-auto-revert-non-file-buffers}, for details. @end ifnottex @node Indirect Buffers diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index 246a04c2824..6e16588861e 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -204,6 +204,9 @@ compilation buffer produce automatic source display. @item g Re-run the last command whose output is shown in the @file{*compilation*} buffer. +@item M-x next-error-select-buffer +Select a buffer to be used by next invocation of @code{next-error} and +@code{previous-error}. @end table @kindex M-g M-n @@ -216,16 +219,18 @@ Re-run the last command whose output is shown in the This command can be invoked from any buffer, not just a Compilation mode buffer. The first time you invoke it after a compilation, it visits the locus of the first error message. Each subsequent -@w{@kbd{C-x `}} visits the next error, in a similar fashion. If you +@w{@kbd{M-g M-n}} visits the next error, in a similar fashion. If you visit a specific error with @key{RET} or a mouse click in the -@file{*compilation*} buffer, subsequent @w{@kbd{C-x `}} commands -advance from there. When @w{@kbd{C-x `}} finds no more error messages -to visit, it signals an error. @w{@kbd{C-u C-x `}} starts again from +@file{*compilation*} buffer, subsequent @w{@kbd{M-g M-n}} commands +advance from there. When @w{@kbd{M-g M-n}} finds no more error messages +to visit, it signals an error. @w{@kbd{C-u M-g M-n}} starts again from the beginning of the compilation buffer, and visits the first locus. @kbd{M-g M-p} or @kbd{M-g p} (@code{previous-error}) iterates through errors in the opposite direction. +@vindex next-error-find-buffer-function +@findex next-error-select-buffer The @code{next-error} and @code{previous-error} commands don't just act on the errors or matches listed in @file{*compilation*} and @file{*grep*} buffers; they also know how to iterate through error or @@ -233,10 +238,15 @@ match lists produced by other commands, such as @kbd{M-x occur} (@pxref{Other Repeating Search}). If the current buffer contains error messages or matches, these commands will iterate through them; otherwise, Emacs looks for a buffer containing error messages or -matches amongst the windows of the selected frame, then for any buffer -that @code{next-error} or @code{previous-error} previously visited, -and finally all other buffers. Any buffer these commands iterate -through that is not currently displayed in a window will be displayed. +matches amongst the windows of the selected frame (if the variable +@code{next-error-find-buffer-function} is customized to the value +@code{next-error-buffer-on-selected-frame}), then for a buffer used +previously by @code{next-error} or @code{previous-error}, and finally +all other buffers. Any buffer these commands iterate through that is +not currently displayed in a window will be displayed. You can use +the @command{next-error-select-buffer} command to switch to +a different buffer to be used by the subsequent invocation of +@code{next-error}. @vindex compilation-skip-threshold By default, the @code{next-error} and @code{previous-error} commands @@ -408,8 +418,8 @@ grep -nH -e foo *.el | grep bar | grep toto @end example The output from @command{grep} goes in the @file{*grep*} buffer. You -can find the corresponding lines in the original files using @w{@kbd{C-x -`}}, @key{RET}, and so forth, just like compilation errors. +can find the corresponding lines in the original files using @w{@kbd{M-g +M-n}}, @key{RET}, and so forth, just like compilation errors. @xref{Compilation Mode}, for detailed description of commands and key bindings available in the @file{*grep*} buffer. @@ -463,6 +473,18 @@ the variable @code{grep-files-aliases}. @kbd{M-x rgrep}. The default value includes the data directories used by various version control systems. +@vindex grep-find-abbreviate +@findex grep-find-toggle-abbreviation + By default, the shell commands constructed for @code{lgrep}, +@code{rgrep}, and @code{zgrep} are abbreviated for display by +concealing the part that contains a long list of files and directories +to ignore. You can reveal the concealed part by clicking on the +button with ellipsis, which represents them. You can also +interactively toggle viewing the concealed part by typing @kbd{M-x +grep-find-toggle-abbreviation}. To disable this abbreviation of the +shell commands, customize the option @code{grep-find-abbreviate} to a +@code{nil} value. + @node Flymake @section Finding Syntax Errors On The Fly @cindex checking syntax diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi index 9b60c2c3e33..34a5ff5f2c1 100644 --- a/doc/emacs/cmdargs.texi +++ b/doc/emacs/cmdargs.texi @@ -385,6 +385,21 @@ verify that their module conforms to the module API requirements. The option makes Emacs abort if a module-related assertion triggers. @xref{Writing Dynamic Modules,, Writing Dynamically-Loaded Modules, elisp, The GNU Emacs Lisp Reference Manual}. + +@item --dump-file=@var{file} +@opindex --dump-file +@cindex specify dump file +Load the dumped Emacs state from the named @var{file}. By default, an +installed Emacs will look for its dump state in a file named +@file{@var{emacs}.pdmp} in the directory where the Emacs installation +puts the architecture-dependent files; the variable +@code{exec-directory} holds the name of that directory. @var{emacs} +is the name of the Emacs executable file, normally just @file{emacs}. +(When you invoke Emacs from the @file{src} directory where it was +built without installing it, it will look for the dump file in the +directory of the executable.) If you rename or move the dump file to +a different place, you can use this option to tell Emacs where to find +that file. @end table @node Command Example @@ -530,12 +545,17 @@ This variable defaults to @file{~/.bash_history} if you use Bash, to otherwise. @item HOME @vindex HOME@r{, environment variable} -The location of your files in the directory tree; used for -expansion of file names starting with a tilde (@file{~}). On MS-DOS, -it defaults to the directory from which Emacs was started, with -@samp{/bin} removed from the end if it was present. On Windows, the -default value of @env{HOME} is the @file{Application Data} -subdirectory of the user profile directory (normally, this is +The location of your files in the directory tree; used for expansion +of file names starting with a tilde (@file{~}). If set, it should be +set to an absolute file name. (If set to a relative file name, Emacs +interprets it relative to the directory where Emacs was started, but +we don't recommend to use this feature.) If unset, @env{HOME} +normally defaults to the home directory of the user given by +@env{LOGNAME}, @env{USER} or your user ID, or to @file{/} if all else +fails. On MS-DOS, it defaults to the directory from which Emacs was +started, with @samp{/bin} removed from the end if it was present. On +Windows, the default value of @env{HOME} is the @file{Application +Data} subdirectory of the user profile directory (normally, this is @file{C:/Documents and Settings/@var{username}/Application Data}, where @var{username} is your user name), though for backwards compatibility @file{C:/} will be used instead if a @file{.emacs} file diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 3fd655048b4..fae5433f877 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -380,7 +380,7 @@ lines of code to your initialization file, to set the variable file. For example: @example -(setq custom-file "~/.emacs-custom.el") +(setq custom-file "~/.config/emacs-custom.el") (load custom-file) @end example @@ -390,14 +390,14 @@ Emacs versions, like this: @example (cond ((< emacs-major-version 22) ;; @r{Emacs 21 customization.} - (setq custom-file "~/.custom-21.el")) + (setq custom-file "~/.config/custom-21.el")) ((and (= emacs-major-version 22) (< emacs-minor-version 3)) ;; @r{Emacs 22 customization, before version 22.3.} - (setq custom-file "~/.custom-22.el")) + (setq custom-file "~/.config/custom-22.el")) (t ;; @r{Emacs version 22.3 or later.} - (setq custom-file "~/.emacs-custom.el"))) + (setq custom-file "~/.config/emacs-custom.el"))) (load custom-file) @end example @@ -765,6 +765,8 @@ expects (@pxref{Examining}). * Locals:: Per-buffer values of variables. * File Variables:: How files can specify variable values. * Directory Variables:: How variable values can be specified by directory. +* Connection Variables:: Variables which are valid for buffers with a + remote default directory. @end menu @node Examining @@ -799,6 +801,7 @@ Its value is 70 Automatically becomes buffer-local when set. This variable is safe as a file local variable if its value satisfies the predicate ‘integerp’. + Probably introduced at or before Emacs version 18. Documentation: Column beyond which automatic line-wrapping should happen. @@ -1358,7 +1361,8 @@ files in that subdirectory. @example ((nil . ((indent-tabs-mode . t) - (fill-column . 80))) + (fill-column . 80) + (mode . auto-fill))) (c-mode . ((c-file-style . "BSD") (subdirs . nil))) ("src/imported" @@ -1367,13 +1371,16 @@ files in that subdirectory. @end example @noindent -This sets @samp{indent-tabs-mode} and @code{fill-column} for any file -in the directory tree, and the indentation style for any C source -file. The special @code{subdirs} element is not a variable, but a -special keyword which indicates that the C mode settings are only to -be applied in the current directory, not in any subdirectories. -Finally, it specifies a different @file{ChangeLog} file name for any -file in the @file{src/imported} subdirectory. +This sets the variables @samp{indent-tabs-mode} and @code{fill-column} +for any file in the directory tree, and the indentation style for any +C source file. The special @code{mode} element specifies the minor +mode to be enabled. So @code{(mode . auto-fill)} specifies that the +minor mode @code{auto-fill-mode} needs to be enabled. The special +@code{subdirs} element is not a variable, but a special keyword which +indicates that the C mode settings are only to be applied in the +current directory, not in any subdirectories. Finally, it specifies a +different @file{ChangeLog} file name for any file in the +@file{src/imported} subdirectory. If the @file{.dir-locals.el} file contains multiple different values for a variable using different mode names or directories, the values @@ -1443,6 +1450,52 @@ variables are handled in the same way as unsafe file-local variables do not visit a file directly but perform work within a directory, such as Dired buffers (@pxref{Dired}). +@node Connection Variables +@subsection Per-Connection Local Variables +@cindex local variables, for all remote connections +@cindex connection-local variables +@cindex per-connection local variables + + 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. + + This can be accomplished with @dfn{connection-local variables}. +Directory and file local variables override connection-local +variables. Unsafe connection-local variables are handled in the same +way as unsafe file-local variables (@pxref{Safe File Variables}). + +@findex connection-local-set-profile-variables +@findex connection-local-set-profiles + Connection-local variables are declared as a group of +variables/value pairs in a @dfn{profile}, using the +@code{connection-local-set-profile-variables} function. The function +@code{connection-local-set-profiles} activates profiles for a given +criteria, identifying a remote machine: + +@example +(connection-local-set-profile-variables 'remote-ksh + '((shell-file-name . "/bin/ksh") + (shell-command-switch . "-c"))) + +(connection-local-set-profile-variables 'remote-bash + '((shell-file-name . "/bin/bash") + (shell-command-switch . "-c"))) + +(connection-local-set-profiles + '(:application tramp :machine "remotemachine") '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 +buffers which have a remote default directory matching the regexp +@code{"remotemachine} as host name. Such a criteria can also +discriminate for the properties @code{:protocol} (this is the Tramp +method) or @code{:user} (a remote user name). The @code{nil} criteria +matches all buffers with a remote default directory. + @node Key Bindings @section Customizing Key Bindings @cindex key bindings @@ -2166,16 +2219,28 @@ as a function from Lisp programs. @cindex init file @cindex .emacs file @cindex ~/.emacs file +@cindex ~/.config/emacs file @cindex Emacs initialization file @cindex startup (init file) When Emacs is started, it normally tries to load a Lisp program from an @dfn{initialization file}, or @dfn{init file} for short. This file, if it exists, specifies how to initialize Emacs for you. Emacs -looks for your init file using the filenames @file{~/.emacs}, -@file{~/.emacs.el}, or @file{~/.emacs.d/init.el}; you can choose to -use any one of these three names (@pxref{Find Init}). Here, @file{~/} -stands for your home directory. +looks for your init file using the filenames +@file{~/.config/emacs},. @file{~/.emacs}, @file{~/.config/emacs.el}, +@file{~/.emacs.el}, @file{~/.config/emacs.d/init.el} or +@file{~/.emacs.d/init.el}; you can choose to use any one of these +names (@pxref{Find Init}). Here, @file{~/} stands for your home +directory. + + While the @file{~/.emacs} and @file{~/.emacs.d/init.el} locations +are backward-compatible to older Emacs versions, and the rest of this +chapter will use them to name your initialization file, it is better practice +to group all of your dotfiles under @file{.config} so that if you have +to troubleshoot a problem that might be due to a bad init file, or +archive a collection of them, it can be done by renaming or +copying that directory. Note that the @file{.config} versions +don't have a leading dot on the basename part of the file. You can use the command line switch @samp{-q} to prevent loading your init file, and @samp{-u} (or @samp{--user}) to specify a @@ -2233,6 +2298,7 @@ Manual}. * Terminal Init:: Each terminal type can have an init file. * Find Init:: How Emacs finds the init file. * Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file. +* Early Init File:: Another init file, which is read early on. @end menu @node Init Syntax @@ -2580,15 +2646,16 @@ library. @xref{Hooks}. @node Find Init @subsection How Emacs Finds Your Init File - Normally Emacs uses the environment variable @env{HOME} -(@pxref{General Variables, HOME}) to find @file{.emacs}; that's what -@samp{~} means in a file name. If @file{.emacs} is not found inside -@file{~/} (nor @file{.emacs.el}), Emacs looks for -@file{~/.emacs.d/init.el} (which, like @file{~/.emacs.el}, can be -byte-compiled). + Normally Emacs uses your home directory to find +@file{~/.config/emacs} or @file{~/.emacs}; that's what @samp{~} means +in a file name. @xref{General Variables, HOME}. If none of +@file{~/.config/emacs}, @file{~/.emacs}, @file{~/.config/emacs.el} nor +@file{~/.emacs.el} is found, Emacs looks for +@file{~/.config/emacs.d/init.el} or @file{~/.emacs.d/init.el} (these, +like @file{~/.emacs.el}, can be byte-compiled). However, if you run Emacs from a shell started by @code{su}, Emacs -tries to find your own @file{.emacs}, not that of the user you are +tries to find your own initialization files, not that of the user you are currently pretending to be. The idea is that you should get your own editor customizations even if you are running as the super user. @@ -2634,6 +2701,36 @@ instance: @noindent Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}. +@node Early Init File +@subsection The Early Init File +@cindex early init file + + Most customizations for Emacs should be put in the normal init file, +@file{.config/emacs} or @file{~/.config/emacs.d/init.el}. However, it is sometimes desirable +to have customizations that 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.d/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, +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 +making already-installed packages available, may be customized in the regular +init file. @xref{Package Installation}. + + We do not recommend that you move into @file{early-init.el} +customizations that can be left in the normal init files. That is +because the early init file is read before the GUI is initialized, so +customizations related to GUI features will not work reliably in +@file{early-init.el}. By contrast, the normal init files are read +after the GUI is initialized. If you must have customizations in the +early init file that rely on GUI features, make them run off hooks +provided by the Emacs startup, such as @code{window-setup-hook} or +@code{tty-setup-hook}. @xref{Hooks}. + + For more information on the early init file, @pxref{Init File,,, +elisp, The Emacs Lisp Reference Manual}. + @node Authentication @section Keeping Persistent Authentication Information diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi index cf9665ac5b4..4ada2a8df4f 100644 --- a/doc/emacs/dired.texi +++ b/doc/emacs/dired.texi @@ -435,6 +435,12 @@ the previous @minus{}@var{n} files). If invoked on a subdirectory header line (@pxref{Subdirectories in Dired}), this command marks all the files in that subdirectory. +@item * N +@kindex * N @r{(Dired)} +@findex dired-number-of-marked-files +Report what the number and size of the marked files are +(@code{dired-number-of-marked-files}). + @item * * @kindex * * @r{(Dired)} @findex dired-mark-executables @@ -663,6 +669,14 @@ Copy the specified files (@code{dired-do-copy}). The argument @var{new} is the directory to copy into, or (if copying a single file) the new name. This is like the shell command @code{cp}. +@vindex dired-create-destination-dirs +The option @code{dired-create-destination-dirs} controls whether Dired +should create non-existent directories in the destination while +copying/renaming files. The default value @code{nil} means Dired +never creates such missing directories; the value @code{always}, +means Dired automatically creates them; the value @code{ask} +means Dired asks you for confirmation before creating them. + @vindex dired-copy-preserve-time If @code{dired-copy-preserve-time} is non-@code{nil}, then copying with this command preserves the modification time of the old file in @@ -694,6 +708,9 @@ single file, the argument @var{new} is the new name of the file. If you rename several files, the argument @var{new} is the directory into which to move the files (this is like the shell command @command{mv}). +The option @code{dired-create-destination-dirs} controls whether Dired +should create non-existent directories in @var{new}. + Dired automatically changes the visited file name of buffers associated with renamed files so that they refer to the new names. @@ -1463,6 +1480,11 @@ rotation is lossless, and uses an external utility called directory's name, and creates that directory. It signals an error if the directory already exists. +@findex dired-create-empty-file + The command (@code{dired-create-empty-file}) reads a +file name, and creates that file. It signals an error if +the file already exists. + @cindex searching multiple files via Dired @kindex M-s a C-s @r{(Dired)} @kindex M-s a M-C-s @r{(Dired)} diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index 435c21fe738..f92f7529ea9 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -975,8 +975,10 @@ the buffer is loaded. For example, to highlight all occurrences of the word ``whim'' using the default face (a yellow background), type @kbd{M-s h r whim @key{RET} @key{RET}}. Any face can be used for highlighting, Hi Lock provides several of its own and these are -pre-loaded into a list of default values. While being prompted -for a face use @kbd{M-n} and @kbd{M-p} to cycle through them. +pre-loaded into a list of default values. While being prompted for a +face use @kbd{M-n} and @kbd{M-p} to cycle through them. A prefix +numeric argument limits the highlighting to the corresponding +subexpression. @vindex hi-lock-auto-select-face Setting the option @code{hi-lock-auto-select-face} to a non-@code{nil} @@ -1140,6 +1142,55 @@ right-to-left paragraphs. @node Displaying Boundaries @section Displaying Boundaries +@cindex mode, display-fill-column-indicator +@findex display-fill-column-indicator-mode +@findex global-display-fill-column-indicator-mode + Emacs can add an indicator to display a fill column position. The +fill column indicator is a useful functionality specially in +prog-mode to indicate the position of an specific column. + + You can set the buffer-local variables @code{display-fill-column-indicator} +and @code{display-fill-column-indicator-character} to activate the +indicator and controls how the indicator looks. + +Alternatively you can type @w{@kbd{M-x display-fill-column-indicator-mode}} +or @w{@kbd{M-x global-display-fill-column-indicator-mode}} which enables the +indicator locally and globally respectively and also chooses the +character to use if none is set already. It is possible to use the +first one to activate the indicator in a hook or the second one to +enable it globally. + +There are 2 buffer local variables and 1 face to customize this mode: + +@table @code +@item display-fill-column-indicator-column +@vindex display-fill-column-indicator-column +Specifies the column number where the indicator should be set. It can +take positive numerical values for the column or the special value +@code{t} which means that the variable @code{fill-column} will be +used. + +Any other value disables the indicator. The default value is @code{t}. + +@item display-fill-column-indicator-char +@vindex display-fill-column-indicator-char +Specifies the character used for the indicator. This character can be +any valid char including unicode ones if the actual font supports +them. + +When the mode is enabled through the functions +@code{display-fill-column-indicator-mode} or +@code{global-display-fill-column-indicator-mode}, the initialization +functions check if this variable is @code{non-nil}, otherwise the +initialization tries to set it to U+2502 or @samp{|}. + +@item fill-column-indicator +@vindex fill-column-indicator +Specifies the face used to display the indicator. It inherits its +default values from shadow but without background color. To change +the indicator color you need to set only the foreground color of this face. +@end table + @vindex indicate-buffer-boundaries On graphical displays, Emacs can indicate the buffer boundaries in the fringes. If you enable this feature, the first line and the last diff --git a/doc/emacs/emacs-xtra.texi b/doc/emacs/emacs-xtra.texi index dcd8fae1b61..e9231b4e3a9 100644 --- a/doc/emacs/emacs-xtra.texi +++ b/doc/emacs/emacs-xtra.texi @@ -59,7 +59,7 @@ modify this GNU manual.'' * Picture Mode:: Editing pictures made up of characters using the quarter-plane screen model. -* Autorevert:: Auto Reverting non-file buffers. +* Non-File Buffers:: Auto Reverting non-file buffers. * Subdir Switches:: Subdirectory switches in Dired. * Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. * Emerge:: A convenient way of merging two versions of a program. diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 5b16d5034f1..a34cef221e1 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -443,9 +443,7 @@ File Handling * Visiting:: Visiting a file prepares Emacs to edit the file. * Saving:: Saving makes your changes permanent. * Reverting:: Reverting cancels all the changes not saved. -@ifnottex -* Autorevert:: Auto Reverting non-file buffers. -@end ifnottex +* Auto Revert:: Keeping buffers automatically up-to-date. * Auto Save:: Auto Save periodically protects against loss of data. * File Aliases:: Handling multiple names for one file. * Directories:: Creating, deleting, and listing file directories. @@ -1135,6 +1133,8 @@ Variables * Locals:: Per-buffer values of variables. * File Variables:: How files can specify variable values. * Directory Variables:: How variable values can be specified by directory. +* Connection Variables:: Variables which are valid for buffers with a + remote default directory. Local Variables in Files @@ -1164,6 +1164,7 @@ The Emacs Initialization File * Terminal Init:: Each terminal type can have an init file. * Find Init:: How Emacs finds the init file. * Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file. +* Early Init File:: Another init file, which is read early on. Dealing with Emacs Trouble @@ -1481,7 +1482,7 @@ Stevens, Andy Stewart, Jonathan Stigelman, Martin Stjernholm, Kim F. Storm, Steve Strassmann, Christopher Suckling, Olaf Sylvester, Naoto Takahashi, Steven Tamm, Jan Tatarik, Luc Teirlinck, Jean-Philippe Theberge, Jens T. Berger Thielemann, Spencer Thomas, Jim Thompson, Toru Tomabechi, -David O'Toole, Markus Triska, Tom Tromey, Enami Tsugutomo, Eli +David O'Toole, Markus Triska, Tom Tromey, Eli Tziperman, Daiki Ueno, Masanobu Umeda, Rajesh Vaidheeswarran, Neil W. Van Dyke, Didier Verna, Joakim Verona, Ulrik Vieth, Geoffrey Voelker, Johan Vromans, Inge Wallin, John Paul Wallington, Colin diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index cd64fb109ea..36ef1dcea21 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -25,9 +25,7 @@ on file directories. * Visiting:: Visiting a file prepares Emacs to edit the file. * Saving:: Saving makes your changes permanent. * Reverting:: Reverting cancels all the changes not saved. -@ifnottex -* Autorevert:: Auto Reverting non-file buffers. -@end ifnottex +* Auto Revert:: Keeping buffers automatically up-to-date. * Auto Save:: Auto Save periodically protects against loss of data. * File Aliases:: Handling multiple names for one file. * Directories:: Creating, deleting, and listing file directories. @@ -206,7 +204,10 @@ saved it. If the file has changed, Emacs offers to reread it. If you try to visit a file larger than @code{large-file-warning-threshold} (the default is 10000000, which is about 10 megabytes), Emacs asks you for confirmation first. You can -answer @kbd{y} to proceed with visiting the file. Note, however, that +answer @kbd{y} to proceed with visiting the file or @kbd{l} to visit +the file literally (see below). Visiting large files literally speeds +up navigation and editing of such files, because various +potentially-expensive features are turned off. Note, however, that Emacs cannot visit files that are larger than the maximum Emacs buffer size, which is limited by the amount of memory Emacs can allocate and by the integers that Emacs can represent (@pxref{Buffers}). If you @@ -400,11 +401,14 @@ possible responses are analogous to those of @code{query-replace}: @table @kbd @item y +@item @key{SPC} Save this buffer and ask about the rest of the buffers. @item n +@item @key{DEL} Don't save this buffer, but ask about the rest of the buffers. @item ! Save this buffer and all the rest with no more questions. +@item q @c following generates acceptable underfull hbox @item @key{RET} Terminate @code{save-some-buffers} without any more saving. @@ -949,6 +953,11 @@ 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.) + You can also tell Emacs to revert buffers automatically when their +visited files change on disk; @pxref{Auto Revert}. + +@node Auto Revert +@section Auto Revert: Keeping buffers automatically up-to-date @cindex Global Auto Revert mode @cindex mode, Global Auto Revert @cindex Auto Revert mode @@ -956,22 +965,39 @@ discard your changes.) @findex global-auto-revert-mode @findex auto-revert-mode @findex auto-revert-tail-mode -@vindex auto-revert-interval -@vindex auto-revert-remote-files + + A buffer can get out of sync with respect to its visited file on +disk if that file is changed by another program. To keep it up to +date, you can enable Auto Revert mode by typing @kbd{M-x auto-revert-mode}. +This automatically reverts the buffer when its visited file changes on +disk. To do the same for all file buffers, type +@kbd{M-x global-auto-revert-mode} to enable Global Auto Revert mode. + + Auto Revert will not revert a buffer if it has unsaved changes, or if +its file on disk is deleted or renamed. + + One use of Auto Revert mode is to ``tail'' a file such as a system +log, so that changes made to that file by other programs are +continuously displayed. To do this, just move the point to the end of +the buffer, and it will stay there as the file contents change. +However, if you are sure that the file will only change by growing at +the end, use Auto Revert Tail mode instead +(@code{auto-revert-tail-mode}). It is more efficient for this. +Auto Revert Tail mode also works for remote files. + @vindex auto-revert-verbose - You can also tell Emacs to revert buffers periodically. To do this -for a specific buffer, enable the minor mode Auto-Revert mode by -typing @kbd{M-x auto-revert-mode}. This automatically reverts the -current buffer when its visited file changes on disk. To do the same -for all file buffers, type @kbd{M-x global-auto-revert-mode} to enable -Global Auto-Revert mode. These minor modes do not check or revert -remote files, because that is usually too slow. This behavior can be -changed by setting the variable @code{auto-revert-remote-files} to -non-@code{nil}. + When a buffer is auto-reverted, a message is generated. This can be +suppressed by setting @code{auto-revert-verbose} to @code{nil}. + +@vindex auto-revert-remote-files + The Auto Revert modes do not check or revert remote files, because +that is usually too slow. This behavior can be changed by setting the +variable @code{auto-revert-remote-files} to non-@code{nil}. @cindex file notifications @vindex auto-revert-use-notify - By default, Auto-Revert mode works using @dfn{file notifications}, +@vindex auto-revert-interval + By default, Auto Revert mode works using @dfn{file notifications}, whereby changes in the filesystem are reported to Emacs by the OS. You can disable use of file notifications by customizing the variable @code{auto-revert-use-notify} to a @code{nil} value, then Emacs will @@ -982,19 +1008,22 @@ the polling interval through the variable @code{auto-revert-interval}. supported, @code{auto-revert-use-notify} will be @code{nil} by default. - One use of Auto-Revert mode is to ``tail'' a file such as a system -log, so that changes made to that file by other programs are -continuously displayed. To do this, just move the point to the end of -the buffer, and it will stay there as the file contents change. -However, if you are sure that the file will only change by growing at -the end, use Auto-Revert Tail mode instead -(@code{auto-revert-tail-mode}). It is more efficient for this. -Auto-Revert Tail mode works also for remote files. - - When a buffer is auto-reverted, a message is generated. This can be -suppressed by setting @code{auto-revert-verbose} to @code{nil}. - - In Dired buffers (@pxref{Dired}), Auto-Revert mode refreshes the +@vindex auto-revert-avoid-polling +@vindex auto-revert-notify-exclude-dir-regexp + By default, Auto Revert mode will poll files for changes +periodically even when file notifications are used. Polling is +unnecessary in many cases, and turning it off may save power by +relying on notifications only. To do so, set the variable +@code{auto-revert-avoid-polling} to non-@code{nil}. However, +notification is ineffective on certain file systems; mainly network +file system on Unix-like machines, where files can be altered from +other machines. For such file systems, polling may be necessary. +To force polling when +@code{auto-revert-avoid-polling} is non-@code{nil}, set +@code{auto-revert-notify-exclude-dir-regexp} to match files that +should be excluded from using notification. + + In Dired buffers (@pxref{Dired}), Auto Revert mode refreshes the buffer when a file is created or deleted in the buffer's directory. @xref{VC Undo}, for commands to revert to earlier versions of files @@ -1002,6 +1031,9 @@ under version control. @xref{VC Mode Line}, for Auto Revert peculiarities when visiting files under version control. @ifnottex +@menu +* Non-File Buffers:: Auto Reverting Non-File Buffers. +@end menu @include arevert-xtra.texi @end ifnottex @@ -1016,13 +1048,16 @@ separate file, without altering the file you actually use. This is called @dfn{auto-saving}. It prevents you from losing more than a limited amount of work if the system crashes. +@vindex auto-save-no-message When Emacs determines that it is time for auto-saving, it considers each buffer, and each is auto-saved if auto-saving is enabled for it -and it has been changed since the last time it was auto-saved. The -message @samp{Auto-saving...} is displayed in the echo area during -auto-saving, if any files are actually auto-saved. Errors occurring -during auto-saving are caught so that they do not interfere with the -execution of commands you have been typing. +and it has been changed since the last time it was auto-saved. When +the @code{auto-save-no-message} variable is set to @code{nil} (the +default), the message @samp{Auto-saving...} is displayed in the echo +area during auto-saving, if any files are actually auto-saved; to +disable these messages, customize the variable to a non-@code{nil} +value. Errors occurring during auto-saving are caught so that they do +not interfere with the execution of commands you have been typing. @menu * Files: Auto Save Files. The file where auto-saved changes are @@ -1309,17 +1344,8 @@ default), and @code{list-directory-verbose-switches} is a string giving the switches to use in a verbose listing (@code{"-l"} by default). -@vindex directory-free-space-program -@vindex directory-free-space-args In verbose directory listings, Emacs adds information about the -amount of free space on the disk that contains the directory. You can -customize how this is done for local filesystems via the variables -@code{directory-free-space-program} and -@code{directory-free-space-args}: the former specifies what program to -run (default: @command{df}), the latter which arguments to pass to -that program (default is system-dependent). (On MS-Windows and -MS-DOS, these two variables are ignored, and an internal Emacs -implementation of the same functionality is used instead.) +amount of free space on the disk that contains the directory. The command @kbd{M-x delete-directory} prompts for a directory's name using the minibuffer, and deletes the directory if it is empty. If @@ -1448,7 +1474,7 @@ automatic line number correction, change the variable @code{diff-update-on-the-fly} to @code{nil}. Diff mode arranges for hunks to be treated as compiler error -messages by @kbd{C-x `} and other commands that handle error messages +messages by @kbd{M-g M-n} and other commands that handle error messages (@pxref{Compilation Mode}). Thus, you can use the compilation-mode commands to visit the corresponding source locations. @@ -1461,26 +1487,19 @@ manipulate and apply parts of patches: Move to the next hunk-start (@code{diff-hunk-next}). With prefix argument @var{n}, move forward to the @var{n}th next hunk. -@findex diff-auto-refine-mode -@cindex mode, Diff Auto-Refine -@cindex Diff Auto-Refine mode -This command has a side effect: it @dfn{refines} the hunk you move to, -highlighting its changes with better granularity. To disable this -feature, type @kbd{M-x diff-auto-refine-mode} to toggle off the minor -mode Diff Auto-Refine mode. To disable Diff Auto-Refine mode by -default, add this to your init file (@pxref{Hooks}): - -@example -(add-hook 'diff-mode-hook - (lambda () (diff-auto-refine-mode -1))) -@end example +@vindex diff-refine +By default, Diff mode @dfn{refines} hunks as Emacs displays them, +highlighting their changes with better granularity. Alternatively, if +you set @code{diff-refine} to the symbol @code{navigation}, Diff mode +only refines the hunk you move to with this command or with +@code{diff-hunk-prev}. @item M-p @findex diff-hunk-prev Move to the previous hunk-start (@code{diff-hunk-prev}). With prefix argument @var{n}, move back to the @var{n}th previous hunk. Like -@kbd{M-n}, this has the side-effect of refining the hunk you move to, -unless you disable Diff Auto-Refine mode. +@kbd{M-n}, this command refines the hunk you move to if you set +@code{diff-refine} to the symbol @code{navigation}. @item M-@} @findex diff-file-next @@ -1518,6 +1537,11 @@ Highlight the changes of the hunk at point with a finer granularity (@code{diff-refine-hunk}). This allows you to see exactly which parts of each changed line were actually changed. +@vindex diff-refine +By default, Diff mode refines hunks as Emacs displays them, so you may +find this command useful if you customize @code{diff-refine} to a +non-default value. + @item C-c C-c @findex diff-goto-source @vindex diff-jump-to-old-file @@ -1530,6 +1554,10 @@ default jumps to the ``old'' file, and the meaning of the prefix argument is reversed. If the prefix argument is a number greater than 8 (e.g., if you type @kbd{C-u C-u C-c C-c}), then this command also sets @code{diff-jump-to-old-file} for the next invocation. +If the source file is under version control (@pxref{Version Control}), +this jumps to the work file by default. With a prefix argument, jump +to the ``old'' revision of the file (@pxref{Old Revisions}), when +point is on the old line, or otherwise jump to the ``new'' revision. @item C-c C-e @findex diff-ediff-patch @@ -1613,6 +1641,10 @@ displayed in the echo area). With a prefix argument, it tries to modify the original (``old'') source files rather than the patched (``new'') source files. +@vindex diff-font-lock-syntax + If non-@code{nil}, fragments of source in hunks are highlighted +according to the appropriate major mode. + @node Copying and Naming @section Copying, Naming and Renaming Files diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi index bb1b4c87137..fc610583c87 100644 --- a/doc/emacs/fixit.texi +++ b/doc/emacs/fixit.texi @@ -149,6 +149,12 @@ Transpose two words (@code{transpose-words}). Transpose two balanced expressions (@code{transpose-sexps}). @item C-x C-t Transpose two lines (@code{transpose-lines}). +@item M-x transpose-sentences +Transpose two sentences (@code{transpose-sentences}). +@item M-x transpose-paragraphs +Transpose two paragraphs (@code{transpose-paragraphs}). +@item M-x transpose-regions +Transpose two regions. @end table @kindex C-t @@ -183,10 +189,14 @@ punctuation characters between the words do not move. For example, @w{@samp{BAR FOO,}}. When point is at the end of the line, it will transpose the word before point with the first word on the next line. +@findex transpose-sentences +@findex transpose-paragraphs @kbd{C-M-t} (@code{transpose-sexps}) is a similar command for transposing two expressions (@pxref{Expressions}), and @kbd{C-x C-t} -(@code{transpose-lines}) exchanges lines. They work like @kbd{M-t} -except as regards the units of text they transpose. +(@code{transpose-lines}) exchanges lines. @kbd{M-x +transpose-sentences} and @kbd{M-x transpose-paragraphs} transpose +sentences and paragraphs, respectively. These commands work like +@kbd{M-t} except as regards the units of text they transpose. A numeric argument to a transpose command serves as a repeat count: it tells the transpose command to move the character (or word or @@ -204,6 +214,15 @@ otherwise a command with a repeat count of zero would do nothing): to transpose the character (or word or expression or line) ending after point with the one ending after the mark. +@findex transpose-regions + @kbd{M-x transpose-regions} transposes the text between point and +mark with the text between the last two marks pushed to the mark ring +(@pxref{Setting Mark}). With a numeric prefix argument, it transposes +the text between point and mark with the text between two successive +marks that many entries back in the mark ring. This command is best +used for transposing multiple characters (or words or sentences or +paragraphs) in one go. + @node Fixing Case @section Case Conversion diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index 05aabd0e15b..6001096f35b 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -899,6 +899,16 @@ input stream for each server. Each server also has its own selected frame. The commands you enter with a particular X server apply to that server's selected frame. + On multi-monitor displays it is possible to use the command +@code{make-frame-on-monitor}: + +@findex make-frame-on-monitor +@table @kbd +@item M-x make-frame-on-monitor @key{RET} @var{monitor} @key{RET} +Create a new frame on monitor @var{monitor} whose screen area is +a part of the current display. +@end table + @node Frame Parameters @section Frame Parameters @vindex default-frame-alist diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index 9ffea416827..4851659b8b7 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -523,13 +523,17 @@ currently in use. @xref{Coding Systems}. @section Other Help Commands @kindex C-h i +@kindex C-h 4 i @findex info +@findex info-other-window @cindex Info @cindex manuals, included @kbd{C-h i} (@code{info}) runs the Info program, which browses -structured documentation files. The entire Emacs manual is available -within Info, along with many other manuals for the GNU system. Type -@kbd{h} after entering Info to run a tutorial on using Info. +structured documentation files. @kbd{C-h 4 i} +(@code{info-other-window}) does the same, but shows the Info buffer in +another window. The entire Emacs manual is available within Info, +along with many other manuals for the GNU system. Type @kbd{h} after +entering Info to run a tutorial on using Info. @cindex find Info manual by its file name With a numeric argument @var{n}, @kbd{C-h i} selects the Info buffer diff --git a/doc/emacs/indent.texi b/doc/emacs/indent.texi index a6aa75bbb42..5f40acba151 100644 --- a/doc/emacs/indent.texi +++ b/doc/emacs/indent.texi @@ -110,6 +110,10 @@ parentheses, or if the junction follows another newline. If there is a fill prefix, @kbd{M-^} deletes the fill prefix if it appears after the newline that is deleted. @xref{Fill Prefix}. +With a prefix argument, join the current line line to the following +line. If the region is active, and no prefix argument is given, join +all lines in the region instead. + @item C-M-\ @kindex C-M-\ @findex indent-region diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi index 6d27e978217..d9920957ad7 100644 --- a/doc/emacs/macos.texi +++ b/doc/emacs/macos.texi @@ -170,8 +170,25 @@ the requested line (@code{ns-open-file-select-line}). This event occurs when a user drags an object from another application into an Emacs frame. The default behavior is to open a file in the window under the mouse, or to insert text at point of the window under -the mouse. It may sometimes be necessary to use the @key{Meta} key in -conjunction with dragging to force text insertion. +the mouse. + +The sending application has some limited ability to decide how Emacs +handles the sent object, but the user may override the default +behaviour by holding one or more modifier key. + +@table @kbd +@item control +Insert as text in the current buffer. If the object is a file, this +will insert the filename. +@item alt/option +Attempt to open the object as though it is a file or URL. +@item super/command +Perform the default action for the type. This can be useful when an +application is overriding the default behaviour. +@end table + +The modifier keys listed above are defined by macOS and are unaffected +by user changes to the modifiers in Emacs. @item ns-change-font This event occurs when the user selects a font in a Nextstep font diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index 93dbce47595..4986c111030 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -831,6 +831,14 @@ working tree containing the current VC fileset). If you invoke this command from a Dired buffer, it applies to the working tree containing the directory. +@findex vc-root-version-diff +@kindex C-u C-x v D + To compare two arbitrary revisions of the whole trees, call +@code{vc-root-diff} with a prefix argument: @kbd{C-u C-x v D}. This +prompts for two revision IDs (@pxref{VCS Concepts}), and displays a +diff between those versions of the entire version-controlled directory +trees (RCS, SCCS, CVS, and SRC do not support this feature). + @vindex vc-diff-switches You can customize the @command{diff} options that @kbd{C-x v =} and @kbd{C-x v D} use for generating diffs. The options used are taken @@ -963,6 +971,7 @@ and the maximum number of revisions to display. Directory Mode}) or a Dired buffer (@pxref{Dired}), it applies to the file listed on the current line. +@kindex C-x v L @findex vc-print-root-log @findex log-view-toggle-entry-display @kbd{C-x v L} (@code{vc-print-root-log}) displays a @@ -1639,21 +1648,35 @@ entry is considered a page. This facilitates editing the entries. @kbd{C-j} and auto-fill indent each new line like the previous line; this is convenient for entering the contents of an entry. -You can use the @code{next-error} command (by default bound to -@kbd{C-x `}) to move between entries in the Change Log, when Change -Log mode is on. You will jump to the actual site in the file that was -changed, not just to the next Change Log entry. You can also use -@code{previous-error} to move back in the same list. +@findex change-log-goto-source + You can use the command @code{change-log-goto-source} (by default +bound to @kbd{C-c C-c}) to go to the source location of the change log +entry near point, when Change Log mode is on. Then subsequent +invocations of the @code{next-error} command (by default bound to +@kbd{M-g M-n} and @kbd{C-x `}) will move between entries in the change +log. You will jump to the actual site in the file that was changed, +not just to the next change log entry. You can also use +@code{previous-error} to move back through the change log entries. @findex change-log-merge You can use the command @kbd{M-x change-log-merge} to merge other log files into a buffer in Change Log Mode, preserving the date ordering of entries. +@vindex add-log-dont-create-changelog-file Version control systems are another way to keep track of changes in -your program and keep a change log. In the VC log buffer, typing -@kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant -Change Log entry, if one exists. @xref{Log Buffer}. +your program and keep a change log. Many projects that use a VCS don't +keep a separate versioned change log file nowadays, so you may wish to +avoid having such a file in the repository. If the value of +@code{add-log-dont-create-changelog-file} is non-@code{nil}, commands +like @kbd{C-x 4 a} (@code{add-change-log-entry-other-window}) will +record changes in a suitably named temporary buffer instead of a file, +if such a file does not already exist. + +Whether you have a change log file or use a temporary buffer for +change logs, you can type @kbd{C-c C-a} +(@code{log-edit-insert-changelog}) in the VC Log buffer to insert the +relevant change log entries, if they exist. @xref{Log Buffer}. @node Format of ChangeLog @subsection Format of ChangeLog @@ -1808,6 +1831,8 @@ Find definitions of identifier, but display it in another window @item C-x 5 .@: @key{RET} Find definition of identifier, and display it in a new frame (@code{xref-find-definitions-other-frame}). +@item M-x xref-find-definitions-at-mouse +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}). @@ -1848,6 +1873,11 @@ former is @w{@kbd{C-x 4 .}} (@code{xref-find-definitions-other-window}), and the latter is @w{@kbd{C-x 5 .}} (@code{xref-find-definitions-other-frame}). + The command @code{xref-find-definitions-at-mouse} works like +@code{xref-find-definitions}, but it looks for the identifier name at +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 @@ -1959,7 +1989,7 @@ table. @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET} Perform a @code{query-replace-regexp} on each file in the selected tags table. -@item M-x tags-loop-continue +@item M-x fileloop-continue Restart one of the last 2 commands above, from the current location of point. @end table @@ -1995,9 +2025,9 @@ you can follow its progress. As soon as it finds an occurrence, @code{tags-search} returns. This command requires tags tables to be available (@pxref{Tags Tables}). -@findex tags-loop-continue +@findex fileloop-continue Having found one match with @code{tags-search}, you probably want to -find all the rest. @kbd{M-x tags-loop-continue} resumes the +find all the rest. @kbd{M-x fileloop-continue} resumes the @code{tags-search}, finding one more match. This searches the rest of the current buffer, followed by the remaining files of the tags table. @@ -2020,10 +2050,10 @@ default is to use the same setting as the value of single invocation of @kbd{M-x tags-query-replace}. But often it is useful to exit temporarily, which you can do with any input event that has no special query replace meaning. You can resume the query -replace subsequently by typing @kbd{M-x tags-loop-continue}; this +replace subsequently by typing @kbd{M-x fileloop-continue}; this command resumes the last tags search or replace command that you did. For instance, to skip the rest of the current file, you can type -@w{@kbd{M-> M-x tags-loop-continue}}. +@w{@kbd{M-> M-x fileloop-continue}}. Note that the commands described above carry out much broader searches than the @code{xref-find-definitions} family. The @@ -2055,7 +2085,7 @@ Display a list of all known identifiers matching @var{regexp}. Display a list of the identifiers defined in the program file @var{file}. -@item M-x next-file +@item M-x tags-next-file Visit files recorded in the selected tags table. @end table @@ -2094,8 +2124,8 @@ variable @code{tags-apropos-additional-actions}; see its documentation for details. @end ignore -@findex next-file - @kbd{M-x next-file} visits files covered by the selected tags table. +@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 table. Each subsequent call visits the next covered file, unless a prefix argument is supplied, in which case it returns to the first diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi index d17ef2dad63..820d3baad13 100644 --- a/doc/emacs/mini.texi +++ b/doc/emacs/mini.texi @@ -362,14 +362,26 @@ While in the completion list buffer, this chooses the completion at point (@code{choose-completion}). @findex next-completion +@item @key{TAB} @item @key{RIGHT} -While in the completion list buffer, this moves point to the following -completion alternative (@code{next-completion}). +While in the completion list buffer, these keys move point to the +following completion alternative (@code{next-completion}). @findex previous-completion +@item @key{S-TAB} @item @key{LEFT} -While in the completion list buffer, this moves point to the previous -completion alternative (@code{previous-completion}). +While in the completion list buffer, these keys move point to the +previous completion alternative (@code{previous-completion}). + +@findex quit-window +@item @kbd{q} +While in the completion list buffer, this quits the window showing it +and selects the window showing the minibuffer (@code{quit-window}). + +@findex kill-current-buffer +@item @kbd{z} +While in the completion list buffer, kill it and delete the window +showing it (@code{kill-current-buffer}). @end table @node Completion Exit diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index 75cca721900..cfc50d33b5f 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -314,7 +314,28 @@ You can decide to register a permanent security exception for an unverified connection, a temporary exception, or refuse the connection entirely. -Below is a list of the checks done on the @code{medium} level. +@vindex network-security-protocol-checks +In addition to the basic certificate correctness checks, several +@acronym{TLS} algorithm checks are available. Some encryption +technologies that were previously thought to be secure have shown +themselves to be fragile, so Emacs (by default) warns you about some +of these problems. + +The protocol network checks is controlled via the +@code{network-security-protocol-checks} variable. + +It's an alist where the first element of each association is the name +of the check, the second element is the security level where the check +should be used, and the optional third element is a parameter supplied +to the check. + +An element like @code{(rc4 medium)} will result in the function +@code{nsm-protocol-check--rc4} being called like thus: +@w{@code{(nsm-protocol-check--rc4 host port status optional-parameter)}}. +The function should return non-@code{nil} if the connection should +proceed and @code{nil} otherwise. + +Below is a list of the checks done on the default @code{medium} level. @table @asis @@ -352,12 +373,44 @@ over these connections. Similarly, if you're sending email via connection to be encrypted. If the connection isn't encrypted, @acronym{NSM} will warn you. +@item Diffie-Hellman low prime bits +When doing the public key exchange, the number of prime bits should be +high enough to ensure that the channel can't be eavesdropped on by third +parties. If this number is too low, Emacs will warn you. (This is the +@code{diffie-hellman-prime-bits} check in +@code{network-security-protocol-checks}). + +@item @acronym{RC4} stream cipher +The @acronym{RC4} stream cipher is believed to be of low quality and +may allow eavesdropping by third parties. (This is the @code{rc4} +check in @code{network-security-protocol-checks}). + +@item @acronym{SHA1} in the host certificate or in intermediate certificates +It is believed that if an intermediate certificate uses the +@acronym{SHA1} hashing algorithm, then third parties can issue +certificates pretending to be that issuing instance. These +connections are therefore vulnerable to man-in-the-middle attacks. +(These are the @code{signature-sha1} and @code{intermediate-sha1} +checks in @code{network-security-protocol-checks}). + +@item @acronym{SSL1}, @acronym{SSL2} and @acronym{SSL3} +The protocols older than @acronym{TLS1.0} are believed to be +vulnerable to a variety of attacks, and you may want to avoid using +these if what you're doing requires higher security. (This is the +@code{ssl} check in @code{network-security-protocol-checks}). + @end table If @code{network-security-level} is @code{high}, the following checks will be made, in addition to the above: @table @asis +@item @acronym{3DES} cipher +The @acronym{3DES} stream cipher provides at most 112 bits of +effective security, which is considered to be towards the low end. +(This is the @code{3des} check in +@code{network-security-protocol-checks}). + @item a validated certificate changes the public key Servers change their keys occasionally, and that is normally nothing to be concerned about. However, if you are worried that your network @@ -365,19 +418,6 @@ connections are being hijacked by agencies who have access to pliable Certificate Authorities which issue new certificates for third-party services, you may want to keep track of these changes. -@item Diffie-Hellman low prime bits -When doing the public key exchange, the number of prime bits -should be high to ensure that the channel can't be eavesdropped on by -third parties. If this number is too low, you will be warned. - -@item @acronym{RC4} stream cipher -The @acronym{RC4} stream cipher is believed to be of low quality and -may allow eavesdropping by third parties. - -@item @acronym{SSL1}, @acronym{SSL2} and @acronym{SSL3} -The protocols older than @acronym{TLS1.0} are believed to be -vulnerable to a variety of attacks, and you may want to avoid using -these if what you're doing requires higher security. @end table Finally, if @code{network-security-level} is @code{paranoid}, you will @@ -402,6 +442,7 @@ This means that one can't casually read the settings file to see what servers the user has connected to. If this variable is @code{t}, @acronym{NSM} will also save host names in the @code{nsm-settings-file}. + @end table @@ -734,6 +775,13 @@ documentation for more possibilities. displayed only when the command generates output, set @code{async-shell-command-display-buffer} to @code{nil}. +@vindex async-shell-command-width + The option @code{async-shell-command-width} defines the number of display +columns available for output of asynchronous shell commands. +A positive integer tells the shell to use that number of columns for +command output. The default value is @code{nil} that means to use +the same number of columns as provided by the shell. + @kindex M-| @findex shell-command-on-region @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!}, but @@ -754,6 +802,10 @@ to @command{gpg}. This will output the list of keys to the name is relative, Emacs searches the directories listed in @code{exec-path} (@pxref{Shell}). + If the default directory is remote (@pxref{Remote Files}), the +default value is @file{/bin/sh}. This can be changed by declaring +@code{shell-file-name} connection-local (@pxref{Connection Variables}). + To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command @kbd{C-x @key{RET} c} immediately beforehand. @xref{Communication Coding}. @@ -985,8 +1037,8 @@ Move backward across one shell command, but not beyond the current line Ask the shell for its working directory, and update the Shell buffer's default directory. @xref{Directory Tracking}. -@item M-x send-invisible @key{RET} @var{text} @key{RET} -@findex send-invisible +@item M-x comint-send-invisible @key{RET} @var{text} @key{RET} +@findex comint-send-invisible Send @var{text} as input to the shell, after reading it without echoing. This is useful when a shell command runs a program that asks for a password. @@ -1133,7 +1185,7 @@ Fetch the next subsequent command from the history @item C-c . @kindex C-c . @r{(Shell mode)} -@findex comint-input-previous-argument +@findex comint-insert-previous-argument Fetch one argument from an old shell command (@code{comint-input-previous-argument}). @@ -1180,14 +1232,20 @@ you just repeated. Then type @key{RET} to reexecute this command. You can reexecute several successive commands by typing @kbd{C-c C-x @key{RET}} over and over. - The command @kbd{C-c .}@: (@code{comint-input-previous-argument}) + The command @kbd{C-c .}@: (@code{comint-insert-previous-argument}) copies an individual argument from a previous command, like -@kbd{@key{ESC} .} in Bash. The simplest use copies the last argument from the -previous shell command. With a prefix argument @var{n}, it copies the -@var{n}th argument instead. Repeating @kbd{C-c .} copies from an -earlier shell command instead, always using the same value of @var{n} -(don't give a prefix argument when you repeat the @kbd{C-c .} -command). +@kbd{@key{ESC} .}@: in Bash and @command{zsh}. The simplest use +copies the last argument from the previous shell command. With a +prefix argument @var{n}, it copies the @var{n}th argument instead. +Repeating @kbd{C-c .} copies from an earlier shell commands, always +using the same value of @var{n} (don't give a prefix argument when +you repeat the @kbd{C-c .} command). + +@vindex comint-insert-previous-argument-from-end + If you set @code{comint-insert-previous-argument-from-end} to a +non-@code{nil} value, @kbd{C-c .}@: will instead copy the @var{n}th +argument counting from the last one; this emulates @kbd{@key{ESC} .}@: +in @command{zsh}. These commands get the text of previous shell commands from a special history list, not from the shell buffer itself. Thus, editing the shell @@ -1726,10 +1784,10 @@ a specific server file, use the @samp{-f} or @samp{--server-file} option, or set the @env{EMACS_SERVER_FILE} environment variable (@pxref{emacsclient Options}). If @code{server-auth-dir} is set to a non-standard value, or if @code{server-name} is set to an absolute -file name, @command{emacsclient} needs an absolute file name -to the server file, as the default @code{server-auth-dir} is -hard-coded in @command{emacsclient} to be used as the directory for -resolving relative filenames. +file name, @command{emacsclient} needs an absolute file name to the +server file, as the default @code{server-auth-dir} is hard-coded in +@command{emacsclient} to be used as the directory for resolving +relative filenames. @node Invoking emacsclient @subsection Invoking @code{emacsclient} @@ -1929,6 +1987,10 @@ You need to use this option if you started Emacs as daemon (@pxref{Initial Options}) and specified the name for the server started by the daemon. +Alternatively, you can set the @env{EMACS_SOCKET_NAME} environment +variable to point to the server socket. (The command-line option +overrides the environment variable.) + @item -t @itemx --tty @itemx -nw @@ -2584,7 +2646,7 @@ e.g., the daemon cannot use GUI features, so parameters such as frame position, size, and decorations cannot be restored. For that reason, you may wish to delay restoring the desktop in daemon mode until the first client connects, by calling @code{desktop-read} in a hook -function that you add to @code{after-make-frame-functions} +function that you add to @code{server-after-make-frame-hook} (@pxref{Creating Frames,,, elisp, The Emacs Lisp Reference Manual}). @node Recursive Edit diff --git a/doc/emacs/msdos.texi b/doc/emacs/msdos.texi index fb876340b41..6933130d5bd 100644 --- a/doc/emacs/msdos.texi +++ b/doc/emacs/msdos.texi @@ -808,6 +808,13 @@ communications with subprocesses to programs that exhibit unusual behavior with respect to buffering pipe I/O. @ifnottex +@vindex w32-pipe-read-delay + If you need to invoke MS-DOS programs as Emacs subprocesses, you may +see low rate of reading data from such programs. Setting the variable +@code{w32-pipe-read-delay} to a non-zero value may improve throughput +in these cases; we suggest the value of 50 for such situations. The +default is zero. + @findex w32-shell-execute The function @code{w32-shell-execute} can be useful for writing customized commands that run MS-Windows applications registered to @@ -978,21 +985,43 @@ fontconfig library used in modern Free desktops: The old XLFD based format is also supported for backwards compatibility. @cindex font backend selection (MS-Windows) - Emacs 23 and later supports a number of font backends. Currently, -the @code{gdi} and @code{uniscribe} backends are supported on Windows. -The @code{gdi} font backend is available on all versions of Windows, -and supports all fonts that are natively supported by Windows. The -@code{uniscribe} font backend is available on Windows 2000 and later, -and supports TrueType and OpenType fonts. Some languages requiring -complex layout can only be properly supported by the Uniscribe -backend. By default, both backends are enabled if supported, with -@code{uniscribe} taking priority over @code{gdi}. To override that -and use the GDI backend even if Uniscribe is available, invoke Emacs -with the @kbd{-xrm Emacs.fontBackend:gdi} command-line argument, or -add a @code{Emacs.fontBackend} resource with the value @code{gdi} in -the Registry under either the + Emacs on MS-Windows supports a number of font backends. Currently, +the @code{gdi}, @code{uniscribe}, and @code{harfbuzz} backends are +available. The @code{gdi} font backend is available on all versions +of Windows, and supports all fonts that are natively supported by +Windows. The @code{uniscribe} font backend is available on Windows +2000 and later, and supports TrueType and OpenType fonts. The +@code{harfbuzz} font backend is available if Emacs was built with +HarfBuzz support, and if the HarfBuzz DLL is installed on your system; +like @code{uniscribe}, this backend supports only TrueType and +OpenType fonts. Some languages requiring complex layout can only be +properly supported by the Uniscribe or HarfBuzz backends. By default, +two backends are enabled for each frame: @code{gdi} and either +@code{harfbuzz} or @code{uniscribe}, depending on which one is +available (if both are available, only @code{harfbuzz} is enabled by +default). The @code{harfbuzz} and @code{uniscribe} backends take +priority over @code{gdi} when Emacs looks for a suitable font. To +override that and use the GDI backend even if Uniscribe is available, +invoke Emacs with the @kbd{-xrm Emacs.fontBackend:gdi} command-line +argument, or add a @code{Emacs.fontBackend} resource with the value +@code{gdi} in the Registry under either the @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} or the @samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs} key (@pxref{Resources}). +Similarly, to use the Uniscribe backend even if HarfBuzz is available, +use @kbd{-xrm Emacs.fontBackend:uniscribe} on the command line that +invokes Emacs. You can also request all the 3 backends via the +@code{font-backend} frame parameter, but be warned that in that case +font searches for characters for which no fonts are available on the +system will take longer. + +Alternatively, you could specify a font backend for a frame via the +@code{font-backend} frame parameter, using +@code{modify-frame-parameters} (@pxref{Parameter Access,,, elisp, The +Emacs Lisp Reference Manual}). You can also request specific font +backend(s) for all your frames via @code{default-frame-alist} and +@code{initial-frame-alist} (@pxref{Frame Parameters}). Note that the +value of the @code{font-backend} parameter should be a list of +symbols, as in @code{(uniscribe)} or @w{@code{(harfbuzz uniscribe gdi)}}. @cindex font properties (MS Windows) @noindent diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi index b3e7d218c62..6a26667510a 100644 --- a/doc/emacs/mule.texi +++ b/doc/emacs/mule.texi @@ -397,7 +397,7 @@ messages. But if your locale matches an entry in the variable coding system instead. For example, if the locale @samp{ja_JP.PCK} matches @code{japanese-shift-jis} in @code{locale-preferred-coding-systems}, Emacs uses that encoding even -though it might normally use @code{japanese-iso-8bit}. +though it might normally use @code{utf-8}. You can override the language environment chosen at startup with explicit use of the command @code{set-language-environment}, or with diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi index 99e04740d3c..26e64243301 100644 --- a/doc/emacs/package.texi +++ b/doc/emacs/package.texi @@ -241,57 +241,53 @@ lower-priority archives will not be shown in the menu, if the same package is available from a higher-priority archive. (This is controlled by the value of @code{package-menu-hide-low-priority}.) - Once a package is downloaded and installed, it is @dfn{loaded} into -the current Emacs session. Loading a package is not quite the same as -loading a Lisp library (@pxref{Lisp Libraries}); loading a package -adds its directory to @code{load-path} and loads its autoloads. The -effect of a package's autoloads varies from package to package. Most -packages just make some new commands available, while others have more + Once a package is downloaded and installed, it is made available to +the current Emacs session. Making a package available adds its +directory to @code{load-path} and loads its autoloads. The effect of +a package's autoloads varies from package to package. Most packages +just make some new commands available, while others have more wide-ranging effects on the Emacs session. For such information, consult the package's help buffer. - By default, Emacs also automatically loads all installed packages in -subsequent Emacs sessions. This happens at startup, after processing -the init file (@pxref{Init File}). As an exception, Emacs does not -load packages at startup if invoked with the @samp{-q} or + After a package is installed, it is automatically made available by +Emacs in all subsequent sessions. This happens at startup, before +processing the init file but after processing the early init file +(@pxref{Early Init File}). As an exception, Emacs does not make +packages available at startup if invoked with the @samp{-q} or @samp{--no-init-file} options (@pxref{Initial Options}). @vindex package-enable-at-startup - To disable automatic package loading, change the variable -@code{package-enable-at-startup} to @code{nil}. - -@findex package-initialize - The reason automatic package loading occurs after loading the init -file is that user options only receive their customized values after -loading the init file, including user options which affect the -packaging system. In some circumstances, you may want to load -packages explicitly in your init file (usually because some other code -in your init file depends on a package). In that case, your init file -should call the function @code{package-initialize}. It is up to you -to ensure that relevant user options, such as @code{package-load-list} -(see below), are set up prior to the @code{package-initialize} call. -This will automatically set @code{package-enable-at-startup} to @code{nil}, to -avoid loading the packages again after processing the init file. -Alternatively, you may choose to completely inhibit package loading at -startup, and invoke the command @kbd{M-x package-initialize} to load -your packages manually. + To keep Emacs from automatically making packages available at +startup, change the variable @code{package-enable-at-startup} to +@code{nil}. You must do this in the early init file, as the variable +is read before loading the regular init file. Currently this variable +cannot be set via Customize. + +@findex package-activate-all + If you have set @code{package-enable-at-startup} to @code{nil}, you +can still make packages available either during or after startup. To +make installed packages available during startup, call the function +@code{package-activate-all} in your init file. To make installed +packages available after startup, invoke the command @kbd{M-: +(package-activate-all) RET}. @vindex package-load-list - For finer control over package loading, you can use the variable -@code{package-load-list}. Its value should be a list. A list element -of the form @code{(@var{name} @var{version})} tells Emacs to load -version @var{version} of the package named @var{name}. Here, -@var{version} should be a version string (corresponding to a specific -version of the package), or @code{t} (which means to load any -installed version), or @code{nil} (which means no version; this -disables the package, preventing it from being loaded). A list -element can also be the symbol @code{all}, which means to load the -latest installed version of any package not named by the other list -elements. The default value is just @code{'(all)}. - - For example, if you set @code{package-load-list} to @code{'((muse -"3.20") all)}, then Emacs only loads version 3.20 of the @samp{muse} -package, plus any installed version of packages other than + For finer control over which packages are made available at startup, +you can use the variable @code{package-load-list}. Its value should +be a list. A list element of the form @w{@code{(@var{name} +@var{version})}} tells Emacs to make available version @var{version} of +the package named @var{name}. Here, @var{version} should be a version +string (corresponding to a specific version of the package), or +@code{t} (which means to make available any installed version), or +@code{nil} (which means no version; this disables the package, +preventing it from being made available). A list element can also be +the symbol @code{all}, which means to make available the latest +installed version of any package not named by the other list elements. +The default value is just @code{'(all)}. + + For example, if you set @code{package-load-list} to @w{@code{'((muse +"3.20") all)}}, then Emacs only makes available version 3.20 of the +@samp{muse} package, plus any installed version of packages other than @samp{muse}. Any other version of @samp{muse} that happens to be installed will be ignored. The @samp{muse} package will be listed in the package menu with the @samp{held} status. diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index 1d6f3e0459a..fe5093147b0 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -156,56 +156,22 @@ Emacs we use it for all languages. @cindex open-parenthesis in leftmost column @cindex ( in leftmost column - Many programming-language modes assume by default that any opening -delimiter found at the left margin is the start of a top-level -definition, or defun. Therefore, @strong{don't put an opening -delimiter at the left margin unless it should have that significance}. -For instance, never put an open-parenthesis at the left margin in a -Lisp file unless it is the start of a top-level list. - - The convention speeds up many Emacs operations, which would -otherwise have to scan back to the beginning of the buffer to analyze -the syntax of the code. - - If you don't follow this convention, not only will you have trouble -when you explicitly use the commands for motion by defuns; other -features that use them will also give you trouble. This includes the -indentation commands (@pxref{Program Indent}) and Font Lock mode -(@pxref{Font Lock}). - - The most likely problem case is when you want an opening delimiter -at the start of a line inside a string. To avoid trouble, put an -escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some -other Lisp dialects) before the opening delimiter. This will not -affect the contents of the string, but will prevent that opening -delimiter from starting a defun. Here's an example: - -@example - (insert "Foo: -\(bar) -") -@end example - - To help you catch violations of this convention, Font Lock mode -highlights confusing opening delimiters (those that ought to be -quoted) in bold red. + Many programming-language modes have traditionally assumed that any +opening parenthesis or brace found at the left margin is the start of +a top-level definition, or defun. So, by default, commands which seek +the beginning of a defun accept such a delimiter as signifying that +position. @vindex open-paren-in-column-0-is-defun-start - If you need to override this convention, you can do so by setting -the variable @code{open-paren-in-column-0-is-defun-start}. -If this user option is set to @code{t} (the default), opening -parentheses or braces at column zero always start defuns. When it is + If you want to override this convention, you can do so by setting +the user option @code{open-paren-in-column-0-is-defun-start} to +@code{nil}. If this option is set to @code{t} (the default), commands +seeking the start of a defun will stop at opening parentheses or +braces at column zero which aren't in a comment or string. When it is @code{nil}, defuns are found by searching for parens or braces at the -outermost level. - - Usually, you should leave this option at its default value of -@code{t}. If your buffer contains parentheses or braces in column -zero which don't start defuns, and it is somehow impractical to remove -these parentheses or braces, it might be helpful to set the option to -@code{nil}. Be aware that this might make scrolling and display in -large buffers quite sluggish. Furthermore, the parentheses and braces -must be correctly matched throughout the buffer for it to work -properly. +outermost level. Since low-level Emacs routines no longer depend on +this convention, you usually won't need to change +@code{open-paren-in-column-0-is-defun-start} from its default. @node Moving by Defuns @subsection Moving by Defuns diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi index b47e5d30b2d..37026946477 100644 --- a/doc/emacs/regs.texi +++ b/doc/emacs/regs.texi @@ -80,7 +80,9 @@ information until you store something else in it. @kindex C-x r j @findex jump-to-register The command @kbd{C-x r j @var{r}} switches to the buffer recorded in -register @var{r}, and moves point to the recorded position. The +register @var{r}, pushes a mark, and moves point to the recorded +position. (The mark is not pushed if point was already at the +recorded position, or in successive calls to the command.) The contents of the register are not changed, so you can jump to the saved position any number of times. diff --git a/doc/emacs/rmail.texi b/doc/emacs/rmail.texi index 94e1e63d44e..4901ca9709e 100644 --- a/doc/emacs/rmail.texi +++ b/doc/emacs/rmail.texi @@ -529,13 +529,18 @@ file name from the message @samp{Subject} header. @kindex C-o @r{(Rmail)} @findex rmail-output-as-seen The commands @kbd{o} and @kbd{C-o} copy the current message into a -specified file, adding it at the end. The two commands differ mainly -in how much to copy: @kbd{o} copies the full message headers, even if -they are not all visible, while @kbd{C-o} copies exactly the headers -currently displayed and no more. @xref{Rmail Display}. In addition, -@kbd{o} converts the message to Babyl format (used by Rmail in Emacs -version 22 and before) if the file is in Babyl format; @kbd{C-o} -cannot output to Babyl files at all. +specified file, adding it at the end. A positive prefix argument +serves as a repeat count: that many consecutive messages will be +copied to the specified file, starting with the current one and +ignoring deleted messages. + +The two commands differ mainly in how much to copy: @kbd{o} copies the +full message headers, even if they are not all visible, while +@kbd{C-o} copies exactly the headers currently displayed and no more. +@xref{Rmail Display}. In addition, @kbd{o} converts the message to +Babyl format (used by Rmail in Emacs version 22 and before) if the +file is in Babyl format; @kbd{C-o} cannot output to Babyl files at +all. @c FIXME remove BABYL mention in some future version? If the output file is currently visited in an Emacs buffer, the @@ -565,17 +570,29 @@ second says which files in that directory to offer (all those that match the regular expression). If no files match, you cannot select this menu item. -@vindex rmail-delete-after-output Copying a message with @kbd{o} or @kbd{C-o} gives the original copy of the message the @samp{filed} attribute, so that @samp{filed} appears in the mode line when such a message is current. +@vindex rmail-delete-after-output If you like to keep just a single copy of every mail message, set the variable @code{rmail-delete-after-output} to @code{t}; then the @kbd{o}, @kbd{C-o} and @kbd{w} commands delete the original message after copying it. (You can undelete it afterward if you wish, see @ref{Rmail Deletion}.) +@vindex rmail-output-reset-deleted-flag + By default, @kbd{o} will leave the deleted status of a message it +outputs as it was on the original message; thus, a message deleted +before it was output will appear as deleted in the output file. +Setting the variable @code{rmail-output-reset-deleted-flag} to a +non-@code{nil} value countermands that: the copy of the message will +have its deleted status reset, so the message will appear as undeleted +in the output file. In addition, when this variable is +non-@code{nil}, specifying a positive argument to @kbd{o} will not +ignore deleted messages when looking for consecutive messages to +output. + @vindex rmail-output-file-alist The variable @code{rmail-output-file-alist} lets you specify intelligent defaults for the output file, based on the contents of the @@ -753,7 +770,7 @@ Try sending a bounced message a second time (@code{rmail-retry-failure}). to the message you are reading. To do this, type @kbd{r} (@code{rmail-reply}). This displays a mail composition buffer in another window, much like @kbd{C-x 4 m}, but preinitializes the -@samp{Subject}, @samp{To}, @samp{CC}, @samp{In-reply-to} and +@samp{Subject}, @samp{To}, @samp{CC}, @samp{In-Reply-To} and @samp{References} header fields based on the message you are replying to. The @samp{To} field starts out as the address of the person who sent the message you received, and the @samp{CC} field starts out with diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi index 0da037330d4..c61578bab76 100644 --- a/doc/emacs/search.texi +++ b/doc/emacs/search.texi @@ -253,6 +253,13 @@ character or word at point to the search string. This is an easy way to search for another occurrence of the text at point. (The decision of whether to copy a character or a word is heuristic.) +@kindex C-M-w @r{(Incremental search)} +@findex isearch-yank-symbol-or-char + @kbd{C-M-w} (@code{isearch-yank-symbol-or-char}) appends the next +character or symbol at point to the search string. This is an easy way +to search for another occurrence of the symbol at point. (The decision +of whether to copy a character or a symbol is heuristic.) + @kindex M-s C-e @r{(Incremental search)} @findex isearch-yank-line Similarly, @kbd{M-s C-e} (@code{isearch-yank-line}) appends the rest @@ -274,11 +281,11 @@ appended text with an earlier kill, similar to the usual @kbd{M-y} in the echo area appends the current X selection (@pxref{Primary Selection}) to the search string (@code{isearch-yank-x-selection}). -@kindex C-M-w @r{(Incremental search)} +@kindex C-M-d @r{(Incremental search)} @kindex C-M-y @r{(Incremental search)} @findex isearch-del-char @findex isearch-yank-char - @kbd{C-M-w} (@code{isearch-del-char}) deletes the last character + @kbd{C-M-d} (@code{isearch-del-char}) deletes the last character from the search string, and @kbd{C-M-y} (@code{isearch-yank-char}) appends the character after point to the search string. An alternative method to add the character after point is to enter the @@ -308,7 +315,7 @@ string that failed to match is highlighted using the face At this point, there are several things you can do. If your string was mistyped, use @key{DEL} to cancel a previous input item -(@pxref{Basic Isearch}), @kbd{C-M-w} to erase one character at a time, +(@pxref{Basic Isearch}), @kbd{C-M-d} to erase one character at a time, or @kbd{M-e} to edit it. If you like the place you have found, you can type @key{RET} to remain there. Or you can type @kbd{C-g}, which removes from the search string the characters that could not be found @@ -468,7 +475,7 @@ of the keymap @code{isearch-mode-map} (@pxref{Keymaps}). This subsection describes how to control whether typing a command not specifically meaningful in searches exits the search before executing -the command. It also describes two categories of commands which you +the command. It also describes three categories of commands which you can type without exiting the current incremental search, even though they are not themselves part of incremental search. @@ -477,7 +484,7 @@ they are not themselves part of incremental search. search exits the search before executing the command. Thus, the command operates on the buffer from which you invoked the search. However, if you customize the variable @code{search-exit-option} to -@code{nil}, the characters which you type that are not interpreted by +@code{append}, the characters which you type that are not interpreted by the incremental search are simply appended to the search string. This is so you could include in the search string control characters, such as @kbd{C-a}, that would normally exit the search and invoke the @@ -538,6 +545,18 @@ change point, the buffer contents, the match data, the current buffer, 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). + +@item Motion Commands +@cindex motion commands, during incremental search +When @code{isearch-yank-on-move} is customized to @code{shift}, +you can extend the search string by holding down the shift key while +typing cursor motion commands. It will yank text that ends at the new +position after moving point in the current buffer. + +When @code{isearch-yank-on-move} is @code{t}, you can extend the +search string without using the shift key for cursor motion commands, +but it applies only for certain motion command that have the +@code{isearch-move} property on their symbols. @end table @node Isearch Minibuffer @@ -955,11 +974,10 @@ character class inside a character alternative. For instance, elisp, The Emacs Lisp Reference Manual}, for a list of character classes. -To include a @samp{]} in a character set, you must make it the first -character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To -include a @samp{-}, write @samp{-} as the first or last character of the -set, or put it after a range. Thus, @samp{[]-]} matches both @samp{]} -and @samp{-}. +To include a @samp{]} in a character set, you must make it the first character. +For example, @samp{[]a]} matches @samp{]} or @samp{a}. To include a @samp{-}, +write @samp{-} as the last character of the set, tho you can also put it first +or after a range. Thus, @samp{[]-]} matches both @samp{]} and @samp{-}. To include @samp{^} in a set, put it anywhere but at the beginning of the set. (At the beginning, it complements the set---see below.) @@ -1819,7 +1837,7 @@ In the @file{*Occur*} buffer, you can click on each entry, or move point there and type @key{RET}, to visit the corresponding position in the buffer that was searched. @kbd{o} and @kbd{C-o} display the match in another window; @kbd{C-o} does not select it. Alternatively, you -can use the @kbd{C-x `} (@code{next-error}) command to visit the +can use the @kbd{M-g M-n} (@code{next-error}) command to visit the occurrences one by one (@pxref{Compilation Mode}). @cindex Occur Edit mode @@ -1855,11 +1873,13 @@ region instead. @findex flush-lines @item M-x flush-lines Prompt for a regexp, and delete each line that contains a match for -it, operating on the text after point. This command deletes the -current line if it contains a match starting after point. If the -region is active, it operates on the region instead; if a line -partially contained in the region contains a match entirely contained -in the region, it is deleted. +it, operating on the text after point. When the command finishes, +it prints the number of deleted matching lines. + +This command deletes the current line if it contains a match starting +after point. If the region is active, it operates on the region +instead; if a line partially contained in the region contains a match +entirely contained in the region, it is deleted. If a match is split across lines, @code{flush-lines} deletes all those lines. It deletes the lines before starting to look for the next diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi index f5d69abf279..c6b8912e2e3 100644 --- a/doc/emacs/sending.texi +++ b/doc/emacs/sending.texi @@ -70,7 +70,7 @@ or using some other method. @xref{Mail Sending}, for details. @example To: subotai@@example.org -Cc: mongol.soldier@@example.net, rms@@gnu.org +CC: mongol.soldier@@example.net, rms@@gnu.org Subject: Re: What is best in life? From: conan@@example.org --text follows this line-- @@ -170,14 +170,14 @@ writes in Babyl format. If an Rmail buffer is visiting the file, Emacs updates it accordingly. To specify more than one file, use several @samp{FCC} fields, with one file name in each field. -@item Reply-to +@item Reply-To An address to which replies should be sent, instead of @samp{From}. This is used if, for some reason, your @samp{From} address cannot receive replies. -@item Mail-reply-to -This field takes precedence over @samp{Reply-to}. It is used because -some mailing lists set the @samp{Reply-to} field for their own +@item Mail-Reply-To +This field takes precedence over @samp{Reply-To}. It is used because +some mailing lists set the @samp{Reply-To} field for their own purposes (a somewhat controversial practice). @item Mail-Followup-To @@ -186,14 +186,14 @@ messages. This is typically used when you reply to a message from a mailing list that you are subscribed to, and want replies to go to the list without sending an extra copy to you. -@item In-reply-to +@item In-Reply-To An identifier for the message you are replying to. Most mail readers use this information to group related messages together. Normally, this header is filled in automatically when you reply to a message in any mail program built into Emacs. @item References -Identifiers for previous related messages. Like @samp{In-reply-to}, +Identifiers for previous related messages. Like @samp{In-Reply-To}, this is normally filled in automatically for you. @end table @@ -220,12 +220,12 @@ To: foo@@example.net, this@@example.net, You can direct Emacs to insert certain default headers into the mail buffer by setting the variable @code{mail-default-headers} to a string. Then @kbd{C-x m} inserts this string into the message -headers. For example, here is how to add a @samp{Reply-to} and +headers. For example, here is how to add a @samp{Reply-To} and @samp{FCC} header to each message: @smallexample (setq mail-default-headers - "Reply-to: foo@@example.com\nFCC: ~/Mail/sent") + "Reply-To: foo@@example.com\nFCC: ~/Mail/sent") @end smallexample @noindent @@ -293,7 +293,7 @@ alias definitions and include commands. Mail aliases expand as abbrevs---that is to say, as soon as you type a word-separator character after an alias (@pxref{Abbrevs}). This expansion takes place only within the @samp{To}, @samp{From}, -@samp{CC}, @samp{BCC}, and @samp{Reply-to} header fields (plus their +@samp{CC}, @samp{BCC}, and @samp{Reply-To} header fields (plus their @samp{Resent-} variants); it does not take place in other header fields, such as @samp{Subject}. @@ -422,7 +422,7 @@ Move to the @samp{CC} header (@code{message-goto-cc}). @item C-c C-f C-b Move to the @samp{BCC} header (@code{message-goto-bcc}). @item C-c C-f C-r -Move to the @samp{Reply-to} header (@code{message-goto-reply-to}). +Move to the @samp{Reply-To} header (@code{message-goto-reply-to}). @item C-c C-f C-f Move to the @samp{Mail-Followup-To} header field (@code{message-goto-followup-to}). diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi index 900f743ea9e..59423feeeae 100644 --- a/doc/emacs/text.texi +++ b/doc/emacs/text.texi @@ -459,6 +459,13 @@ non-@code{nil}, and in programming-language strings if @code{nil} for @code{electric-quote-string} and @code{t} for the other variables. +@vindex electric-quote-replace-double + You can also set the option @code{electric-quote-replace-double} to +a non-@code{nil} value. Then, typing @t{"} insert an appropriate +curved double quote depending on context: @t{“} at the beginning of +the buffer or after a line break, whitespace, opening parenthesis, or +quote character, and @t{”} otherwise. + Electric Quote mode is disabled by default. To toggle it in a single buffer, use @kbd{M-x electric-quote-local-mode}. To toggle it globally, type @@ -631,8 +638,15 @@ line. If a function returns a non-@code{nil} value, Emacs will not break the line there. Functions you can use there include: @code{fill-single-word-nobreak-p} (don't break after the first word of a sentence or before the last); @code{fill-single-char-nobreak-p} -(don't break after a one-letter word); and @code{fill-french-nobreak-p} -(don't break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}). +(don't break after a one-letter word preceded by a whitespace +character); @code{fill-french-nobreak-p} (don't break after @samp{(} +or before @samp{)}, @samp{:} or @samp{?}); and +@code{fill-polish-nobreak-p} (don't break after a one letter word, +even if preceded by a non-whitespace character). + + Emacs can display an indicator in the @code{fill-column} position +using the Display fill column indicator mode +(@pxref{Displaying Boundaries, display-fill-column-indicator}). @node Fill Prefix @subsection The Fill Prefix @@ -2406,11 +2420,13 @@ to the commands above. @subsection Setting Other Text Properties The Special Properties submenu of Text Properties has entries for -adding or removing three other text properties: @code{read-only}, +adding or removing four other text properties: @code{read-only}, (which disallows alteration of the text), @code{invisible} (which -hides text), and @code{intangible} (which disallows moving point -within the text). The @samp{Remove Special} menu item removes all of -these special properties from the text in the region. +hides text), @code{intangible} (which disallows moving point within +the text), and @code{charset} (which is important for selecting a +proper font to display a character). The @samp{Remove Special} menu +item removes all of these special properties from the text in the +region. The @code{invisible} and @code{intangible} properties are not saved. diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi index c4c724e6bc2..4b39e8bfe10 100644 --- a/doc/emacs/windows.texi +++ b/doc/emacs/windows.texi @@ -157,7 +157,9 @@ this option is @code{nil}. @item C-x o Select another window (@code{other-window}). @item C-M-v -Scroll the next window (@code{scroll-other-window}). +Scroll the next window upward (@code{scroll-other-window}). +@item C-M-S-v +Scroll the next window downward (@code{scroll-other-window-down}). @item mouse-1 @kbd{mouse-1}, in the text area of a window, selects the window and moves point to the position clicked. Clicking in the mode line @@ -181,13 +183,18 @@ back and finish supplying the minibuffer argument that is requested. @kindex C-M-v @findex scroll-other-window +@kindex C-M-S-v +@findex scroll-other-window-down The usual scrolling commands (@pxref{Display}) apply to the selected -window only, but there is one command to scroll the next window. +window only, but there are also commands to scroll the next window. @kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that -@kbd{C-x o} would select. It takes arguments, positive and negative, -like @kbd{C-v}. (In the minibuffer, @kbd{C-M-v} scrolls the help -window associated with the minibuffer, if any, rather than the next -window in the standard cyclic order; @pxref{Minibuffer Edit}.) +@kbd{C-x o} would select. In other respects, the command behaves like +@kbd{C-v}; both move the buffer text upward relative to the window, and +take positive and negative arguments. (In the minibuffer, @kbd{C-M-v} +scrolls the help window associated with the minibuffer, if any, rather +than the next window in the standard cyclic order; @pxref{Minibuffer +Edit}.) @kbd{C-M-S-v} (@code{scroll-other-window-down}) scrolls the +next window downward in a similar way. @vindex mouse-autoselect-window If you set @code{mouse-autoselect-window} to a non-@code{nil} value, @@ -359,7 +366,7 @@ various help commands (@pxref{Help}), work by calling Other commands do the same as @code{display-buffer}, and additionally select the displaying window so that you can begin -editing its buffer. The command @kbd{C-x `} (@code{next-error}) is +editing its buffer. The command @kbd{M-g M-n} (@code{next-error}) is one example (@pxref{Compilation Mode}). Such commands work by calling the function @code{pop-to-buffer} internally. @xref{Switching Buffers,,Switching to a Buffer in a Window, elisp, The Emacs Lisp @@ -528,6 +535,9 @@ Reference Manual}), and cannot exceed the size of the containing frame. @section Convenience Features for Window Handling @findex winner-mode +@vindex winner-dont-bind-my-keys +@vindex winner-ring-size +@vindex winner-boring-buffers @cindex Winner mode @cindex mode, Winner @cindex undoing window configuration changes @@ -539,7 +549,14 @@ with @kbd{M-x winner-mode}, or by customizing the variable @code{winner-mode}. When the mode is enabled, @kbd{C-c left} (@code{winner-undo}) undoes the last window configuration change. If you change your mind while undoing, you can redo the changes you had -undone using @kbd{C-c right} (@code{M-x winner-redo}). +undone using @kbd{C-c right} (@code{M-x winner-redo}). To prevent +Winner mode from binding @kbd{C-c left} and @kbd{C-c right}, you can +customize the variable @code{winner-dont-bind-my-keys} to a +non-@code{nil} value. By default, Winner mode stores a maximum of 200 +window configurations per frame, but you can change that by modifying +the variable @code{winner-ring-size}. If there are some buffers whose +windows you wouldn't want Winner mode to restore, add their names to +the list variable @code{winner-boring-buffers}. Follow mode (@kbd{M-x follow-mode}) synchronizes several windows on the same buffer so that they always display adjacent sections of that diff --git a/doc/lispintro/Makefile.in b/doc/lispintro/Makefile.in index efe5a1e0046..37fffb8a0f2 100644 --- a/doc/lispintro/Makefile.in +++ b/doc/lispintro/Makefile.in @@ -109,8 +109,8 @@ emacs-lisp-intro.ps: emacs-lisp-intro.dvi .PHONY: mostlyclean clean distclean bootstrap-clean maintainer-clean infoclean mostlyclean: - rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \ - *.op *.ops *.pg *.pgs *.tp *.tps *.vr *.vrs + rm -f ./*.aux ./*.log ./*.toc ./*.cp ./*.cps ./*.fn ./*.fns ./*.ky ./*.kys \ + ./*.op ./*.ops ./*.pg ./*.pgs ./*.tp ./*.tps ./*.vr ./*.vrs clean: mostlyclean rm -f $(DVI_TARGETS) $(HTML_TARGETS) $(PDF_TARGETS) $(PS_TARGETS) diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index c4b19a4e50a..c03fbfc47b2 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -9014,26 +9014,24 @@ Lisp; it is written in C and is one of the primitives of the GNU Emacs system. Since it is very simple, I will digress briefly from Lisp and describe it here. -@c GNU Emacs 24 in src/editfns.c -@c the DEFUN for delete-and-extract-region - @need 1500 Like many of the other Emacs primitives, @code{delete-and-extract-region} is written as an instance of a C macro, a macro being a template for code. The complete macro looks like this: +@c This is a copy of editfns.c's DEFUN for delete-and-extract-region. @smallexample @group DEFUN ("delete-and-extract-region", Fdelete_and_extract_region, Sdelete_and_extract_region, 2, 2, 0, doc: /* Delete the text between START and END and return it. */) - (Lisp_Object start, Lisp_Object end) + (Lisp_Object start, Lisp_Object end) @{ validate_region (&start, &end); - if (XINT (start) == XINT (end)) + if (XFIXNUM (start) == XFIXNUM (end)) return empty_unibyte_string; - return del_range_1 (XINT (start), XINT (end), 1, 1); + return del_range_1 (XFIXNUM (start), XFIXNUM (end), 1, 1); @} @end group @end smallexample @@ -9097,9 +9095,9 @@ consists of the following four lines: @smallexample @group validate_region (&start, &end); -if (XINT (start) == XINT (end)) +if (XFIXNUM (start) == XFIXNUM (end)) return empty_unibyte_string; -return del_range_1 (XINT (start), XINT (end), 1, 1); +return del_range_1 (XFIXNUM (start), XFIXNUM (end), 1, 1); @end group @end smallexample @@ -9111,27 +9109,28 @@ then return an empty string. The @code{del_range_1} function actually deletes the text. It is a complex function we will not look into. It updates the buffer and does other things. However, it is worth looking at the two arguments -passed to @code{del_range_1}. These are @w{@code{XINT (start)}} and -@w{@code{XINT (end)}}. +passed to @code{del_range_1}. These are @w{@code{XFIXNUM (start)}} and +@w{@code{XFIXNUM (end)}}. As far as the C language is concerned, @code{start} and @code{end} are -two integers that mark the beginning and end of the region to be -deleted@footnote{More precisely, and requiring more expert knowledge -to understand, the two integers are of type @code{Lisp_Object}, which can -also be a C union instead of an integer type.}. +two opaque values that mark the beginning and end of the region to be +deleted. More precisely, and requiring more expert knowledge +to understand, the two values are of type @code{Lisp_Object}, which +might be a C pointer, a C integer, or a C @code{struct}; C code +ordinarily should not care how @code{Lisp_Object} is implemented. -Integer widths depend on the machine, and are typically 32 or 64 bits. -A few of the bits are used to specify the type of information; the -remaining bits are used as content. +@code{Lisp_Object} widths depend on the machine, and are typically 32 +or 64 bits. A few of the bits are used to specify the type of +information; the remaining bits are used as content. -@samp{XINT} is a C macro that extracts the relevant number from the +@samp{XFIXNUM} is a C macro that extracts the relevant integer from the longer collection of bits; the type bits are discarded. @need 800 The command in @code{delete-and-extract-region} looks like this: @smallexample -del_range_1 (XINT (start), XINT (end), 1, 1); +del_range_1 (XFIXNUM (start), XFIXNUM (end), 1, 1); @end smallexample @noindent @@ -11070,9 +11069,8 @@ The @code{dotimes} macro is similar to @code{dolist}, except that it loops a specific number of times. The first argument to @code{dotimes} is assigned the numbers 0, 1, 2 -and so forth each time around the loop, and the value of the third -argument is returned. You need to provide the value of the second -argument, which is how many times the macro loops. +and so forth each time around the loop. You need to provide the value +of the second argument, which is how many times the macro loops. @need 1250 For example, the following binds the numbers from 0 up to, but not @@ -11084,17 +11082,18 @@ three numbers in all, starting with zero as the first number.) @smallexample @group (let (value) ; otherwise a value is a void variable - (dotimes (number 3 value) - (setq value (cons number value)))) + (dotimes (number 3) + (setq value (cons number value))) + value) @result{} (2 1 0) @end group @end smallexample @noindent -@code{dotimes} returns @code{value}, so the way to use -@code{dotimes} is to operate on some expression @var{number} number of -times and then return the result, either as a list or an atom. +The way to use @code{dotimes} is to operate on some expression +@var{number} number of times and then return the result, either as +a list or an atom. @need 1250 Here is an example of a @code{defun} that uses @code{dotimes} to add @@ -11105,8 +11104,9 @@ up the number of pebbles in a triangle. (defun triangle-using-dotimes (number-of-rows) "Using `dotimes', add up the number of pebbles in a triangle." (let ((total 0)) ; otherwise a total is a void variable - (dotimes (number number-of-rows total) - (setq total (+ total (1+ number)))))) + (dotimes (number number-of-rows) + (setq total (+ total (1+ number)))) + total)) (triangle-using-dotimes 4) @end group @@ -15598,7 +15598,7 @@ like this: (recursive-lengths-list-many-files (files-in-below-directory "/usr/local/src/emacs/lisp/")) '<) - (insert (format "%s" (current-time-string)))) + (insert (current-time-string))) @end ignore @node Counting function definitions @@ -16798,7 +16798,7 @@ It will look like this: ;; If you edit it by hand, you could mess it up, so be careful. ;; Your init file should contain only one such instance. ;; If there is more than one, they won't work right. - '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify)))) + '(text-mode-hook '(turn-on-auto-fill text-mode-hook-identify))) @end group @end smallexample @@ -21857,14 +21857,17 @@ MENU ENTRY: NODE NAME. @end ifnottex @quotation -Robert J. Chassell has worked with GNU Emacs since 1985. He writes -and edits, teaches Emacs and Emacs Lisp, and speaks throughout the +Robert J. Chassell (1946--2017) started working with GNU Emacs in 1985. He wrote +and edited, taught Emacs and Emacs Lisp, and spoke throughout the world on software freedom. Chassell was a founding Director and -Treasurer of the Free Software Foundation, Inc. He is co-author of -the @cite{Texinfo} manual, and has edited more than a dozen other -books. He graduated from Cambridge University, in England. He has an -abiding interest in social and economic history and flies his own +Treasurer of the Free Software Foundation, Inc. He was co-author of +the @cite{Texinfo} manual, and edited more than a dozen other +books. He graduated from Cambridge University, in England. He had an +abiding interest in social and economic history and flew his own airplane. + +@uref{https://www.fsf.org/blogs/community/goodbye-to-bob-chassell, +"Goodbye to Bob Chassell"} @end quotation @c @page diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in index 74e3878a37e..5de04a7784c 100644 --- a/doc/lispref/Makefile.in +++ b/doc/lispref/Makefile.in @@ -167,8 +167,8 @@ elisp.ps: elisp.dvi ## [12] stuff is from two-volume.make. mostlyclean: - rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \ - *.op *.ops *.pg *.pgs *.tp *.tps *.vr *.vrs + rm -f ./*.aux ./*.log ./*.toc ./*.cp ./*.cps ./*.fn ./*.fns ./*.ky ./*.kys \ + ./*.op ./*.ops ./*.pg ./*.pgs ./*.tp ./*.tps ./*.vr ./*.vrs rm -f elisp[12]* vol[12].tmp clean: mostlyclean diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi index 558040ebf67..b67c014a83d 100644 --- a/doc/lispref/abbrevs.texi +++ b/doc/lispref/abbrevs.texi @@ -232,7 +232,8 @@ Emacs commands to offer to save your abbrevs. Save all abbrev definitions (except system abbrevs), for all abbrev tables listed in @code{abbrev-table-name-list}, in the file @var{filename}, in the form of a Lisp program that when loaded will -define the same abbrevs. If @var{filename} is @code{nil} or omitted, +define the same abbrevs. Tables that do not have any abbrevs to save +are omitted. If @var{filename} is @code{nil} or omitted, @code{abbrev-file-name} is used. This function returns @code{nil}. @end deffn diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 6ad1fb1824a..260f159851b 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -573,7 +573,6 @@ echo area; use @code{set-buffer-modified-p} (above) instead. This function returns @var{buffer}'s modification-count. This is a counter that increments every time the buffer is modified. If @var{buffer} is @code{nil} (or omitted), the current buffer is used. -The counter can wrap around occasionally. @end defun @defun buffer-chars-modified-tick &optional buffer @@ -648,16 +647,13 @@ file should not be done. @defun visited-file-modtime This function returns the current buffer's recorded last file -modification time, as a list of the form @code{(@var{high} @var{low} -@var{microsec} @var{picosec})}. (This is the same format that -@code{file-attributes} uses to return time values; @pxref{File -Attributes}.) +modification time, as a Lisp timestamp (@pxref{Time of Day}). If the buffer has no recorded last modification time, this function returns zero. This case occurs, for instance, if the buffer is not visiting a file or if the time has been explicitly cleared by @code{clear-visited-file-modtime}. Note, however, that -@code{visited-file-modtime} returns a list for some non-file buffers +@code{visited-file-modtime} returns a timestamp for some non-file buffers too. For instance, in a Dired buffer listing a directory, it returns the last modification time of that directory, as recorded by Dired. @@ -672,9 +668,8 @@ is not @code{nil}, and otherwise to the last modification time of the visited file. If @var{time} is neither @code{nil} nor an integer flag returned -by @code{visited-file-modtime}, it should have the form -@code{(@var{high} @var{low} @var{microsec} @var{picosec})}, -the format used by @code{current-time} (@pxref{Time of Day}). +by @code{visited-file-modtime}, it should be a Lisp time value +(@pxref{Time of Day}). This function is useful if the buffer was not read from the file normally, or if the file itself has been changed for some known benign @@ -831,7 +826,7 @@ regardless of which frames they were displayed on. @group ;; @r{Note that the name of the minibuffer} ;; @r{begins with a space!} -(mapcar (function buffer-name) (buffer-list)) +(mapcar #'buffer-name (buffer-list)) @result{} ("buffers.texi" " *Minibuf-1*" "buffer.c" "*Help*" "TAGS") @end group diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index ad31240beff..c0df944f9ce 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -1047,12 +1047,9 @@ and meaning of input events in detail. This function returns non-@code{nil} if @var{object} is an input event or event type. -Note that any symbol might be used as an event or an event type. -@code{eventp} cannot distinguish whether a symbol is intended by Lisp -code to be used as an event. Instead, it distinguishes whether the -symbol has actually been used in an event that has been read as input in -the current Emacs session. If a symbol has not yet been so used, -@code{eventp} returns @code{nil}. +Note that any non-@code{nil} symbol might be used as an event or an +event type; @code{eventp} cannot distinguish whether a symbol is +intended by Lisp code to be used as an event. @end defun @menu @@ -2884,6 +2881,14 @@ command's key sequence (as returned by, e.g., @code{this-command-keys}), as the events will already have been added once as they were read for the first time. An element of the form @w{@code{(t . @var{event})}} forces @var{event} to be added to the current command's key sequence. + +@cindex not recording input events +@cindex input events, prevent recording +Elements read from this list are normally recorded by the +record-keeping features (@pxref{Recording Input}) and while defining a +keyboard macro (@pxref{Keyboard Macros}). However, an element of the +form @w{@code{(no-record . @var{event})}} causes @var{event} to be +processed normally without recording it. @end defvar @defun listify-key-sequence key diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index d9db55e22cd..4ff0e1c91e4 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -505,8 +505,25 @@ current lexical scope, or file if at top-level.) @xref{Defining Variables}. @end itemize - You can also suppress any and all compiler warnings within a certain -expression using the construct @code{with-no-warnings}: + You can also suppress compiler warnings within a certain expression +using the @code{with-suppressed-warnings} macro: + +@defspec with-suppressed-warnings warnings body@dots{} +In execution, this is equivalent to @code{(progn @var{body}...)}, but +the compiler does not issue warnings for the specified conditions in +@var{body}. @var{warnings} is an associative list of warning symbols +and function/variable symbols they apply to. For instance, if you +wish to call an obsolete function called @code{foo}, but want to +suppress the compilation warning, say: + +@lisp +(with-suppressed-warnings ((obsolete foo)) + (foo ...)) +@end lisp +@end defspec + +For more coarse-grained suppression of compiler warnings, you can use +the @code{with-no-warnings} construct: @c This is implemented with a defun, but conceptually it is @c a special form. @@ -516,8 +533,9 @@ In execution, this is equivalent to @code{(progn @var{body}...)}, but the compiler does not issue warnings for anything that occurs inside @var{body}. -We recommend that you use this construct around the smallest -possible piece of code, to avoid missing possible warnings other than +We recommend that you use @code{with-suppressed-warnings} instead, but +if you do use this construct, that you use it around the smallest +possible piece of code to avoid missing possible warnings other than one you intend to suppress. @end defspec diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 9e27e1a751a..e308d68b75d 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -1095,12 +1095,10 @@ Matches if @var{expval} is a vector of length @var{m} whose @item @var{symbol} @itemx @var{keyword} -@itemx @var{integer} +@itemx @var{number} @itemx @var{string} Matches if the corresponding element of @var{expval} is @code{equal} to the specified literal object. -Note that, aside from @var{symbol}, this is the same set of -self-quoting literal objects that are acceptable as a core pattern. @item ,@var{pattern} Matches if the corresponding element of @var{expval} @@ -1355,7 +1353,8 @@ This construct executes @var{body} once for each integer from 0 (inclusive) to @var{count} (exclusive), binding the variable @var{var} to the integer for the current iteration. Then it returns the value of evaluating @var{result}, or @code{nil} if @var{result} is omitted. -Here is an example of using @code{dotimes} to do something 100 times: +Use of @var{result} is deprecated. Here is an example of using +@code{dotimes} to do something 100 times: @example (dotimes (i 100) @@ -1986,9 +1985,10 @@ error occurs during @var{protected-form}. Each of the @var{handlers} is a list of the form @code{(@var{conditions} @var{body}@dots{})}. Here @var{conditions} is an error condition name to be handled, or a list of condition names (which can include @code{debug} -to allow the debugger to run before the handler); @var{body} is one or more -Lisp expressions to be executed when this handler handles an error. -Here are examples of handlers: +to allow the debugger to run before the handler). A condition name of +@code{t} matches any condition. @var{body} is one or more Lisp +expressions to be executed when this handler handles an error. Here +are examples of handlers: @example @group diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 2576fbe39d7..9e433433107 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -81,7 +81,8 @@ debugger recursively. @xref{Recursive Editing}. * Function Debugging:: Entering it when a certain function is called. * Variable Debugging:: Entering it when a variable is modified. * Explicit Debug:: Entering it at a certain point in the program. -* Using Debugger:: What the debugger does; what you see while in it. +* Using Debugger:: What the debugger does. +* Backtraces:: What you see while in the debugger. * Debugger Commands:: Commands used while in the debugger. * Invoking the Debugger:: How to call the function @code{debug}. * Internals of Debugger:: Subroutines of the debugger, and global variables. @@ -392,32 +393,82 @@ this is not what you want, you can either set @code{eval-expression-debug-on-error} to @code{nil}, or set @code{debug-on-error} to @code{nil} in @code{debugger-mode-hook}. + The debugger itself must be run byte-compiled, since it makes +assumptions about the state of the Lisp interpreter. These +assumptions are false if the debugger is running interpreted. + +@node Backtraces +@subsection Backtraces +@cindex backtrace buffer + +Debugger mode is derived from Backtrace mode, which is also used to +show backtraces by Edebug and ERT. (@pxref{Edebug}, and @ref{Top,the +ERT manual,, ert, ERT: Emacs Lisp Regression Testing}.) + +@cindex stack frame +The backtrace buffer shows you the functions that are executing and +their argument values. When a backtrace buffer is created, it shows +each stack frame on one, possibly very long, line. (A stack frame is +the place where the Lisp interpreter records information about a +particular invocation of a function.) The most recently called +function will be at the top. + @cindex current stack frame - The backtrace buffer shows you the functions that are executing and -their argument values. It also allows you to specify a stack frame by -moving point to the line describing that frame. (A stack frame is the -place where the Lisp interpreter records information about a particular -invocation of a function.) The frame whose line point is on is -considered the @dfn{current frame}. Some of the debugger commands -operate on the current frame. If a line starts with a star, that means -that exiting that frame will call the debugger again. This is useful -for examining the return value of a function. - - If a function name is underlined, that means the debugger knows -where its source code is located. You can click with the mouse on -that name, or move to it and type @key{RET}, to visit the source code. +In a backtrace you can specify a stack frame by moving point to a line +describing that frame. The frame whose line point is on is considered +the @dfn{current frame}. + +If a function name is underlined, that means Emacs knows where its +source code is located. You can click with the mouse on that name, or +move to it and type @key{RET}, to visit the source code. You can also +type @key{RET} while point is on any name of a function or variable +which is not underlined, to see help information for that symbol in a +help buffer, if any exists. The @code{xref-find-definitions} command, +bound to @key{M-.}, can also be used on any identifier in a backtrace +(@pxref{Looking Up Identifiers,,,emacs, The GNU Emacs Manual}). + +In backtraces, the tails of long lists and the ends of long strings, +vectors or structures, as well as objects which are deeply nested, +will be printed as underlined ``...''. You can click with the mouse +on a ``...'', or type @key{RET} while point is on it, to show the part +of the object that was hidden. To control how much abbreviation is +done, customize @code{backtrace-line-length}. + +Here is a list of commands for navigating and viewing backtraces: - The debugger itself must be run byte-compiled, since it makes -assumptions about how many stack frames are used for the debugger -itself. These assumptions are false if the debugger is running -interpreted. +@table @kbd +@item v +Toggle the display of local variables of the current stack frame. + +@item p +Move to the beginning of the frame, or to the beginning +of the previous frame. + +@item n +Move to the beginning of the next frame. + +@item + +Add line breaks and indentation to the top-level Lisp form at point to +make it more readable. + +@item - +Collapse the top-level Lisp form at point back to a single line. + +@item # +Toggle @code{print-circle} for the frame at point. + +@item . +Expand all the forms abbreviated with ``...'' in the frame at point. + +@end table @node Debugger Commands @subsection Debugger Commands @cindex debugger command list The debugger buffer (in Debugger mode) provides special commands in -addition to the usual Emacs commands. The most important use of +addition to the usual Emacs commands and to the Backtrace mode commands +described in the previous section. The most important use of debugger commands is for stepping through code, so that you can see how control flows. The debugger can step through the control structures of an interpreted function, but cannot do so in a @@ -427,6 +478,11 @@ the same function. (To do this, visit the source for the function and type @kbd{C-M-x} on its definition.) You cannot use the Lisp debugger to step through a primitive function. +Some of the debugger commands operate on the current frame. If a +frame starts with a star, that means that exiting that frame will call the +debugger again. This is useful for examining the return value of a +function. + @c FIXME: Add @findex for the following commands? --xfq Here is a list of Debugger mode commands: @@ -502,8 +558,6 @@ Display a list of functions that will invoke the debugger when called. This is a list of functions that are set to break on entry by means of @code{debug-on-entry}. -@item v -Toggle the display of local variables of the current stack frame. @end table @node Invoking the Debugger @@ -624,20 +678,19 @@ of @code{debug} (@pxref{Invoking the Debugger}). @cindex run time stack @cindex call stack This function prints a trace of Lisp function calls currently active. -This is the function used by @code{debug} to fill up the -@file{*Backtrace*} buffer. It is written in C, since it must have access -to the stack to determine which function calls are active. The return -value is always @code{nil}. +The trace is identical to the one that @code{debug} would show in the +@file{*Backtrace*} buffer. The return value is always nil. In the following example, a Lisp expression calls @code{backtrace} explicitly. This prints the backtrace to the stream @code{standard-output}, which, in this case, is the buffer @samp{backtrace-output}. -Each line of the backtrace represents one function call. The line shows -the values of the function's arguments if they are all known; if they -are still being computed, the line says so. The arguments of special -forms are elided. +Each line of the backtrace represents one function call. The line +shows the function followed by a list of the values of the function's +arguments if they are all known; if they are still being computed, the +line consists of a list containing the function and its unevaluated +arguments. Long lists or deeply nested structures may be elided. @smallexample @group @@ -654,10 +707,10 @@ forms are elided. @group ----------- Buffer: backtrace-output ------------ backtrace() - (list ...computing arguments...) + (list 'testing (backtrace)) @end group (progn ...) - eval((progn (1+ var) (list (quote testing) (backtrace)))) + eval((progn (1+ var) (list 'testing (backtrace)))) (setq ...) (save-excursion ...) (let ...) @@ -685,10 +738,10 @@ example would look as follows: @group ----------- Buffer: backtrace-output ------------ (backtrace) - (list ...computing arguments...) + (list 'testing (backtrace)) @end group (progn ...) - (eval (progn (1+ var) (list (quote testing) (backtrace)))) + (eval (progn (1+ var) (list 'testing (backtrace)))) (setq ...) (save-excursion ...) (let ...) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index b6fda1cd807..217df3b2cc2 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -426,7 +426,7 @@ This function calls @code{progress-reporter-update}, so the first message is printed immediately. @end defun -@defun progress-reporter-update reporter &optional value +@defun progress-reporter-update reporter &optional value suffix This function does the main work of reporting progress of your operation. It displays the message of @var{reporter}, followed by progress percentage determined by @var{value}. If percentage is zero, @@ -440,6 +440,11 @@ state of your operation and must be between @var{min-value} and @code{make-progress-reporter}. For instance, if you scan a buffer, then @var{value} should be the result of a call to @code{point}. +Optional argument @var{suffix} is a string to be displayed after +@var{reporter}'s main message and progress text. If @var{reporter} is +a non-numerical reporter, then @var{value} should be @code{nil}, or a +string to use instead of @var{suffix}. + This function respects @var{min-change} and @var{min-time} as passed to @code{make-progress-reporter} and so does not output new messages on every invocation. It is thus very fast and normally you should not @@ -447,11 +452,11 @@ try to reduce the number of calls to it: resulting overhead will most likely negate your effort. @end defun -@defun progress-reporter-force-update reporter &optional value new-message +@defun progress-reporter-force-update reporter &optional value new-message suffix This function is similar to @code{progress-reporter-update} except that it prints a message in the echo area unconditionally. -The first two arguments have the same meaning as for +@var{reporter}, @var{value}, and @var{suffix} have the same meaning as for @code{progress-reporter-update}. Optional @var{new-message} allows you to change the message of the @var{reporter}. Since this function always updates the echo area, such a change will be immediately @@ -469,19 +474,54 @@ never print it, there are many good reasons for this not to happen. Secondly, @samp{done} is more explicit. @end defun -@defmac dotimes-with-progress-reporter (var count [result]) message body@dots{} +@defmac dotimes-with-progress-reporter (var count [result]) reporter-or-message body@dots{} This is a convenience macro that works the same way as @code{dotimes} does, but also reports loop progress using the functions described -above. It allows you to save some typing. +above. It allows you to save some typing. The argument +@var{reporter-or-message} can be either a string or a progress +reporter object. + +You can rewrite the example in the beginning of this subsection using +this macro as follows: + +@example +@group +(dotimes-with-progress-reporter + (k 500) + "Collecting some mana for Emacs..." + (sit-for 0.01)) +@end group +@end example -You can rewrite the example in the beginning of this node using -this macro this way: +Using a reporter object as the @var{reporter-or-message} argument is +useful if you want to specify the optional arguments in +@var{make-progress-reporter}. For instance, you can write the +previous example as follows: @example +@group (dotimes-with-progress-reporter (k 500) + (make-progress-reporter "Collecting some mana for Emacs..." 0 500 0 1 1.5) + (sit-for 0.01)) +@end group +@end example +@end defmac + +@defmac dolist-with-progress-reporter (var count [result]) reporter-or-message body@dots{} +This is another convenience macro that works the same way as @code{dolist} +does, but also reports loop progress using the functions described +above. As in @code{dotimes-with-progress-reporter}, +@code{reporter-or-message} can be a progress reporter or a string. +You can rewrite the previous example with this macro as follows: + +@example +@group +(dolist-with-progress-reporter + (k (number-sequence 0 500)) "Collecting some mana for Emacs..." (sit-for 0.01)) +@end group @end example @end defmac @@ -735,6 +775,10 @@ When this variable is non-@code{nil}, it specifies a fill prefix to use for filling each warning's text. @end defvar +@defvar warning-fill-column +The column at which to fill warnings. +@end defvar + @defvar warning-type-format This variable specifies the format for displaying the warning type in the warning message. The result of formatting the type this way @@ -999,8 +1043,8 @@ hiding certain lines on the screen. @cindex explicit selective display The first variant, explicit selective display, was designed for use in a Lisp program: it controls which lines are hidden by altering the text. This kind of -hiding is now obsolete; instead you can get the same effect with the -@code{invisible} property (@pxref{Invisible Text}). +hiding is now obsolete and deprecated; instead you should use the +@code{invisible} property (@pxref{Invisible Text}) to get the same effect. In the second variant, the choice of lines to hide is made automatically based on indentation. This variant is designed to be a @@ -1708,9 +1752,12 @@ modified, and the length of the pre-change text replaced by that range. length is the number of characters deleted, and the post-change beginning and end are equal.) -If these functions modify the buffer, they should bind -@code{inhibit-modification-hooks} to @code{t} around doing so, to -avoid confusing the internal mechanism that calls these hooks. +When these functions are called, @code{inhibit-modification-hooks} is +bound to non-@code{nil}. If the functions modify the buffer, you +might want to bind @code{inhibit-modification-hooks} to @code{nil}, so +as to cause the change hooks to run for these modifications. However, +doing this may call your own change hook recursively, so be sure to +prepare for that. @xref{Change Hooks}. Text properties also support the @code{modification-hooks} property, but the details are somewhat different (@pxref{Special Properties}). @@ -2939,7 +2986,13 @@ the remapped face---it replaces the normal definition of @var{face}, instead of modifying it. If @code{face-remapping-alist} is buffer-local, its local value takes -effect only within that buffer. +effect only within that buffer. If @code{face-remapping-alist} +includes faces applicable only to certain windows, by using the +@w{@code{(:filtered (:window @var{param} @var{val}) @var{spec})}}, +that face takes effect only in windows that match the filter +conditions (@pxref{Special Properties}). To turn off face filtering +temporarily, bind @code{face-filters-always-match} to a non-@code{nil} +value, then all face filters will match any window. Note: face remapping is non-recursive. If @var{remapping} references the same face name @var{face}, either directly or via the @@ -4139,10 +4192,10 @@ Used to indicate continued lines. @item @code{right-triangle}, @code{left-triangle} The former is used by overlay arrows. The latter is unused. -@item @code{up-arrow}, @code{down-arrow}, @code{top-left-angle} @code{top-right-angle} +@item @code{up-arrow}, @code{down-arrow} @itemx @code{bottom-left-angle}, @code{bottom-right-angle} -@itemx @code{top-right-angle}, @code{top-left-angle} -@itemx @code{left-bracket}, @code{right-bracket}, @code{top-right-angle}, @code{top-left-angle} +@itemx @code{top-left-angle}, @code{top-right-angle} +@itemx @code{left-bracket}, @code{right-bracket} Used to indicate buffer boundaries. @item @code{filled-rectangle}, @code{hollow-rectangle} @@ -4150,7 +4203,7 @@ Used to indicate buffer boundaries. @itemx @code{vertical-bar}, @code{horizontal-bar} Used for different types of fringe cursors. -@item @code{empty-line}, @code{exclamation-mark}, @code{question-mark}, @code{exclamation-mark} +@item @code{empty-line}, @code{exclamation-mark}, @code{question-mark} Not used by core Emacs features. @end table @@ -5097,6 +5150,71 @@ This adds a shadow rectangle around the image. The value, @var{relief} is negative, shadows are drawn so that the image appears as a pressed button; otherwise, it appears as an unpressed button. +@item :width @var{width}, :height @var{height} +The @code{:width} and @code{:height} keywords are used for scaling the +image. If only one of them is specified, the other one will be +calculated so as to preserve the aspect ratio. If both are specified, +aspect ratio may not be preserved. + +@item :max-width @var{max-width}, :max-height @var{max-height} +The @code{:max-width} and @code{:max-height} keywords are used for +scaling if the size of the image exceeds these values. If +@code{:width} is set, it will have precedence over @code{max-width}, +and if @code{:height} is set, it will have precedence over +@code{max-height}, but you can otherwise mix these keywords as you +wish. + +If both @code{:max-width} and @code{:height} are specified, but +@code{:width} is not, preserving the aspect ratio might require that +width exceeds @code{:max-width}. If this happens, scaling will use a +smaller value for the height so as to preserve the aspect ratio while +not exceeding @code{:max-width}. Similarly when both +@code{:max-height} and @code{:width} are specified, but @code{:height} +is not. For example, if you have a 200x100 image and specify that +@code{:width} should be 400 and @code{:max-height} should be 150, +you'll end up with an image that is 300x150: Preserving the aspect +ratio and not exceeding the ``max'' setting. This combination of +parameters is a useful way of saying ``display this image as large as +possible, but no larger than the available display area''. + +@item :scale @var{scale} +This should be a number, where values higher than 1 means to increase +the size, and lower means to decrease the size, by multiplying both +the width and height. For instance, a value of 0.25 will make the +image a quarter size of what it originally was. If the scaling makes +the image larger than specified by @code{:max-width} or +@code{:max-height}, the resulting size will not exceed those two +values. If both @code{:scale} and @code{:height}/@code{:width} are +specified, the height/width will be adjusted by the specified scaling +factor. + +@item :crop @var{geometry} +This should be a list of the form @code{(@var{width} @var{height} +@var{x} @var{y})}. @var{width} and @var{height} specify the width +and height of the cropped image. If @var{x} is a positive number it +specifies the offset of the cropped area from the left of the original +image, and if negative the offset from the right. If @var{y} is a +positive number it specifies the offset from the top of the original +image, and if negative from the bottom. If @var{x} or @var{y} are +@code{nil} or unspecified the crop area will be centred on the +original image. + +If the crop area is outside or overlaps the edge of the image it will +be reduced to exclude any areas outside of the image. This means it +is not possible to use @code{:crop} to increase the size of the image +by entering large @var{width} or @var{height} values. + +Cropping is performed after scaling but before rotation. + +@item :rotation @var{angle} +Specifies a rotation angle in degrees. Only multiples of 90 degrees +are supported, unless the image type is @code{imagemagick}. Positive +values rotate clockwise, negative values counter-clockwise. Rotation +is performed after scaling and cropping. + +@item :index @var{frame} +@xref{Multi-Frame Images}. + @item :conversion @var{algorithm} This specifies a conversion algorithm that should be applied to the image before it is displayed; the value, @var{algorithm}, specifies @@ -5236,6 +5354,17 @@ This function returns @code{t} if image @var{spec} has a mask bitmap. (@pxref{Input Focus}). @end defun +@defun image-transforms-p &optional frame +This function returns @code{t} if @var{frame} supports image scaling +and rotation. @var{frame} @code{nil} or omitted means to use the +selected frame (@pxref{Input Focus}). + +If image transforms are not supported, @code{:rotation}, +@code{:width}, @code{:height}, @code{:scale}, @code{:max-width} and +@code{:max-height} will only be usable through ImageMagick, if +available (@pxref{ImageMagick Images}). +@end defun + @node XBM Images @subsection XBM Images @cindex XBM @@ -5372,53 +5501,11 @@ color, which is used as the image's background color if the image supports transparency. If the value is @code{nil}, it defaults to the frame's background color. -@item :width @var{width}, :height @var{height} -The @code{:width} and @code{:height} keywords are used for scaling the -image. If only one of them is specified, the other one will be -calculated so as to preserve the aspect ratio. If both are specified, -aspect ratio may not be preserved. - -@item :max-width @var{max-width}, :max-height @var{max-height} -The @code{:max-width} and @code{:max-height} keywords are used for -scaling if the size of the image of the image exceeds these values. -If @code{:width} is set it will have precedence over @code{max-width}, -and if @code{:height} is set it will have precedence over -@code{max-height}, but you can otherwise mix these keywords as you -wish. @code{:max-width} and @code{:max-height} will always preserve -the aspect ratio. - -If both @code{:width} and @code{:max-height} has been set (but -@code{:height} has not been set), then @code{:max-height} will have -precedence. The same is the case for the opposite combination: The -``max'' keyword has precedence. That is, if you have a 200x100 image -and specify that @code{:width} should be 400 and @code{:max-height} -should be 150, you'll end up with an image that is 300x150: Preserving -the aspect ratio and not exceeding the ``max'' setting. This -combination of parameters is a useful way of saying ``display this -image as large as possible, but no larger than the available display -area''. - -@item :scale @var{scale} -This should be a number, where values higher than 1 means to increase -the size, and lower means to decrease the size. For instance, a value -of 0.25 will make the image a quarter size of what it originally was. -If the scaling makes the image larger than specified by -@code{:max-width} or @code{:max-height}, the resulting size will not -exceed those two values. If both @code{:scale} and -@code{:height}/@code{:width} are specified, the height/width will be -adjusted by the specified scaling factor. - @item :format @var{type} The value, @var{type}, should be a symbol specifying the type of the image data, as found in @code{image-format-suffixes}. This is used when the image does not have an associated file name, to provide a hint to ImageMagick to help it detect the image type. - -@item :rotation @var{angle} -Specifies a rotation angle in degrees. - -@item :index @var{frame} -@xref{Multi-Frame Images}. @end table @node SVG Images diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index e674280a83d..2c0ee3969b9 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -442,8 +442,18 @@ Redisplay the most recently known expression result in the echo area Display a backtrace, excluding Edebug's own functions for clarity (@code{edebug-backtrace}). -You cannot use debugger commands in the backtrace buffer in Edebug as -you would in the standard debugger. +@xref{Backtraces}, for a description of backtraces +and the commands which work on them. + +@findex edebug-backtrace-show-instrumentation +@findex edebug-backtrace-hide-instrumentation +If you would like to see Edebug's functions in the backtrace, +use @kbd{M-x edebug-backtrace-show-instrumentation}. To hide them +again use @kbd{M-x edebug-backtrace-hide-instrumentation}. + +If a backtrace frame starts with @samp{>} that means that Edebug knows +where the source code for the frame is located. Use @kbd{s} to jump +to the source code for the current frame. The backtrace buffer is killed automatically when you continue execution. @@ -1711,3 +1721,33 @@ Whether or not to pause for @code{edebug-sit-for-seconds} on reaching a breakpoint. Set to @code{nil} to prevent the pause, non-@code{nil} to allow it. @end defopt + +@defopt edebug-behavior-alist +By default, this alist contains one entry with the key @code{edebug} +and a list of three functions, which are the default implementations +of the functions inserted in instrumented code: @code{edebug-enter}, +@code{edebug-before} and @code{edebug-after}. To change Edebug's +behavior globally, modify the default entry. + +Edebug's behavior may also be changed on a per-definition basis by +adding an entry to this alist, with a key of your choice and three +functions. Then set the @code{edebug-behavior} symbol property of an +instrumented definition to the key of the new entry, and Edebug will +call the new functions in place of its own for that definition. +@end defopt + +@defopt edebug-new-definition-function +A function run by Edebug after it wraps the body of a definition +or closure. After Edebug has initialized its own data, this function +is called with one argument, the symbol associated with the +definition, which may be the actual symbol defined or one generated by +Edebug. This function may be used to set the @code{edebug-behavior} +symbol property of each definition instrumented by Edebug. +@end defopt + +@defopt edebug-after-instrumentation-function +To inspect or modify Edebug's instrumentation before it is used, set +this variable to a function which takes one argument, an instrumented +top-level form, and returns either the same or a replacement form, +which Edebug will then use as the final result of instrumentation. +@end defopt diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index a2b03da5abc..e18759654d9 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -455,6 +455,7 @@ Evaluation the program). * Backquote:: Easier construction of list structure. * Eval:: How to invoke the Lisp interpreter explicitly. +* Deferred Eval:: Deferred and lazy evaluation of forms. Kinds of Forms @@ -654,7 +655,8 @@ The Lisp Debugger * Function Debugging:: Entering it when a certain function is called. * Variable Debugging:: Entering it when a variable is modified. * Explicit Debug:: Entering it at a certain point in the program. -* Using Debugger:: What the debugger does; what you see while in it. +* Using Debugger:: What the debugger does. +* Backtraces:: What you see while in the debugger. * Debugger Commands:: Commands used while in the debugger. * Invoking the Debugger:: How to call the function @code{debug}. * Internals of Debugger:: Subroutines of the debugger, and global variables. @@ -1354,6 +1356,7 @@ Threads * Basic Thread Functions:: Basic thread functions. * Mutexes:: Mutexes allow exclusive access to data. * Condition Variables:: Inter-thread events. +* The Thread List:: Show the active threads. Processes @@ -1398,7 +1401,6 @@ Packing and Unpacking Byte Arrays * Bindat Spec:: Describing data layout. * Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! Emacs Display diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index c794028b5e6..aa99b2b1a98 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -159,6 +159,11 @@ The message is @samp{No catch for tag}. @xref{Catch and Throw}. The message is @samp{Attempt to modify a protected file}. @end ignore +@item range-error +The message is @code{Arithmetic range error}. +This can happen with integers exceeding the @code{integer-width} limit. +@xref{Integer Basics}. + @item scan-error The message is @samp{Scan error}. This happens when certain syntax-parsing functions find invalid syntax or mismatched @@ -223,9 +228,6 @@ The message is @samp{Arithmetic domain error}. The message is @samp{Arithmetic overflow error}. This is a subcategory of @code{domain-error}. -@item range-error -The message is @code{Arithmetic range error}. - @item singularity-error The message is @samp{Arithmetic singularity error}. This is a subcategory of @code{domain-error}. diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index 73f5396dabe..39c5a1ec506 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -20,11 +20,12 @@ function @code{eval}. @ifnottex @menu -* Intro Eval:: Evaluation in the scheme of things. -* Forms:: How various sorts of objects are evaluated. -* Quoting:: Avoiding evaluation (to put constants in the program). -* Backquote:: Easier construction of list structure. -* Eval:: How to invoke the Lisp interpreter explicitly. +* Intro Eval:: Evaluation in the scheme of things. +* Forms:: How various sorts of objects are evaluated. +* Quoting:: Avoiding evaluation (to put constants in the program). +* Backquote:: Easier construction of list structure. +* Eval:: How to invoke the Lisp interpreter explicitly. +* Deferred Eval:: Deferred and lazy evaluation of forms. @end menu @node Intro Eval @@ -585,15 +586,15 @@ Here are some examples of expressions that use @code{quote}: @end group @group ''foo - @result{} (quote foo) + @result{} 'foo @end group @group '(quote foo) - @result{} (quote foo) + @result{} 'foo @end group @group ['foo] - @result{} [(quote foo)] + @result{} ['foo] @end group @end example @@ -884,3 +885,115 @@ particular elements, like this: @end group @end example @end defvar + +@node Deferred Eval +@section Deferred and Lazy Evaluation + +@cindex deferred evaluation +@cindex lazy evaluation + + + Sometimes it is useful to delay the evaluation of an expression, for +example if you want to avoid performing a time-consuming calculation +if it turns out that the result is not needed in the future of the +program. The @file{thunk} library provides the following functions +and macros to support such @dfn{deferred evaluation}: + +@cindex thunk +@defmac thunk-delay forms@dots{} +Return a @dfn{thunk} for evaluating the @var{forms}. A thunk is a +closure (@pxref{Closures}) that inherits the lexical environment of the +@code{thunk-delay} call. Using this macro requires +@code{lexical-binding}. +@end defmac + +@defun thunk-force thunk +Force @var{thunk} to perform the evaluation of the forms specified in +the @code{thunk-delay} that created the thunk. The result of the +evaluation of the last form is returned. The @var{thunk} also +``remembers'' that it has been forced: Any further calls of +@code{thunk-force} with the same @var{thunk} will just return the same +result without evaluating the forms again. +@end defun + +@defmac thunk-let (bindings@dots{}) forms@dots{} +This macro is analogous to @code{let} but creates ``lazy'' variable +bindings. Any binding has the form @w{@code{(@var{symbol} +@var{value-form})}}. Unlike @code{let}, the evaluation of any +@var{value-form} is deferred until the binding of the according +@var{symbol} is used for the first time when evaluating the +@var{forms}. Any @var{value-form} is evaluated at most once. Using +this macro requires @code{lexical-binding}. +@end defmac + +Example: + +@example +@group +(defun f (number) + (thunk-let ((derived-number + (progn (message "Calculating 1 plus 2 times %d" number) + (1+ (* 2 number))))) + (if (> number 10) + derived-number + number))) +@end group + +@group +(f 5) +@result{} 5 +@end group + +@group +(f 12) +@print{} Calculating 1 plus 2 times 12 +@result{} 25 +@end group + +@end example + +Because of the special nature of lazily bound variables, it is an error +to set them (e.g.@: with @code{setq}). + + +@defmac thunk-let* (bindings@dots{}) forms@dots{} +This is like @code{thunk-let} but any expression in @var{bindings} is allowed +to refer to preceding bindings in this @code{thunk-let*} form. Using +this macro requires @code{lexical-binding}. +@end defmac + +@example +@group +(thunk-let* ((x (prog2 (message "Calculating x...") + (+ 1 1) + (message "Finished calculating x"))) + (y (prog2 (message "Calculating y...") + (+ x 1) + (message "Finished calculating y"))) + (z (prog2 (message "Calculating z...") + (+ y 1) + (message "Finished calculating z"))) + (a (prog2 (message "Calculating a...") + (+ z 1) + (message "Finished calculating a")))) + (* z x)) + +@print{} Calculating z... +@print{} Calculating y... +@print{} Calculating x... +@print{} Finished calculating x +@print{} Finished calculating y +@print{} Finished calculating z +@result{} 8 + +@end group +@end example + +@code{thunk-let} and @code{thunk-let*} use thunks implicitly: their +expansion creates helper symbols and binds them to thunks wrapping the +binding expressions. All references to the original variables in the +body @var{forms} are then replaced by an expression that calls +@code{thunk-force} with the according helper variable as the argument. +So, any code using @code{thunk-let} or @code{thunk-let*} could be +rewritten to use thunks, but in many cases using these macros results +in nicer code than using thunks explicitly. diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index ebe2fdd6a0c..66678d33915 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -550,7 +550,7 @@ the functions in the list @code{after-insert-file-functions}. (@pxref{Coding Systems}) used for decoding the file's contents, including end-of-line conversion. However, if the file contains null bytes, it is by default visited without any code conversions. -@xref{Lisp and Coding Systems, inhibit-null-byte-detection}. +@xref{Lisp and Coding Systems, inhibit-nul-byte-detection}. If @var{visit} is non-@code{nil}, this function additionally marks the buffer as unmodified and sets up various fields in the buffer so that it @@ -1299,36 +1299,34 @@ Alternate names, also known as hard links, can be created by using the @item The file's @acronym{UID}, normally as a string (@code{file-attribute-user-id}). However, if it does not correspond -to a named user, the value is a number. +to a named user, the value is an integer. @item The file's @acronym{GID}, likewise (@code{file-attribute-group-id}). @item -The time of last access, as a list of four integers -@code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})} -(@code{file-attribute-access-time}). (This is similar to the value of -@code{current-time}; see @ref{Time of Day}.) The value is truncated +The time of last access as a Lisp timestamp +(@code{file-attribute-access-time}). The timestamp is in the +style of @code{current-time} (@pxref{Time of Day}) and is truncated to that of the filesystem's timestamp resolution; for example, on some FAT-based filesystems, only the date of last access is recorded, so this time will always hold the midnight of the day of the last access. @cindex modification time of file @item -The time of last modification as a list of four integers (as above) +The time of last modification as a Lisp timestamp (@code{file-attribute-modification-time}). This is the last time when the file's contents were modified. @item -The time of last status change as a list of four integers (as above) +The time of last status change as a Lisp timestamp (@code{file-attribute-status-change-time}). This is the time of the last change to the file's access mode bits, its owner and group, and other information recorded in the filesystem for the file, beyond the file's contents. @item -The size of the file in bytes (@code{file-attribute-size}). This is -floating point if the size is too large to fit in a Lisp integer. +The size of the file in bytes (@code{file-attribute-size}). @item The file's modes, as a string of ten letters or dashes, as in @@ -1338,21 +1336,13 @@ The file's modes, as a string of ten letters or dashes, as in An unspecified value, present for backward compatibility. @item -The file's inode number (@code{file-attribute-inode-number}). If -possible, this is an integer. If the inode number is too large to be -represented as an integer in Emacs Lisp but dividing it by -@math{2^{16}} yields a representable integer, then the value has the -form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16 -bits. If the inode number is too wide for even that, the value is of -the form @code{(@var{high} @var{middle} . @var{low})}, where -@code{high} holds the high bits, @var{middle} the middle 24 bits, and -@var{low} the low 16 bits. +The file's inode number (@code{file-attribute-inode-number}), +a nonnegative integer. @item The filesystem number of the device that the file is on -@code{file-attribute-device-number}). Depending on the magnitude of -the value, this can be either an integer or a cons cell, in the same -manner as the inode number. This element and the file's inode number +@code{file-attribute-device-number}), an integer. +This element and the file's inode number together give enough information to distinguish any two files on the system---no two files can have the same values for both of these numbers. @@ -1368,8 +1358,8 @@ For example, here are the file attributes for @file{files.texi}: (20000 23 0 0) (20614 64555 902289 872000) 122295 "-rw-rw-rw-" - t (5888 2 . 43978) - (15479 . 46724)) + t 6473924464520138 + 1014478468) @end group @end example @@ -1410,10 +1400,10 @@ has a mode of read and write access for the owner, group, and world. @item t is merely a placeholder; it carries no information. -@item (5888 2 . 43978) +@item 6473924464520138 has an inode number of 6473924464520138. -@item (15479 . 46724) +@item 1014478468 is on the file-system device whose number is 1014478468. @end table @end defun @@ -1567,13 +1557,16 @@ For compatibility, @var{predicate} can also be one of the symbols a list of one or more of these symbols. @end defun -@defun executable-find program +@defun executable-find program &optional remote This function searches for the executable file of the named @var{program} and returns the absolute file name of the executable, including its file-name extensions, if any. It returns @code{nil} if -the file is not found. The functions searches in all the directories +the file is not found. The function searches in all the directories in @code{exec-path}, and tries all the file-name extensions in @code{exec-suffixes} (@pxref{Subprocess Creation}). + +If @var{remote} is non-@code{nil}, and @code{default-directory} is a +remote directory, @var{program} is searched on the respective remote host. @end defun @node Changing Files @@ -2131,7 +2124,7 @@ Note that the @samp{.~3~} in the two last examples is the backup part, not an extension. @end defun -@defun file-name-base &optional filename +@defun file-name-base filename This function is the composition of @code{file-name-sans-extension} and @code{file-name-nondirectory}. For example, @@ -2139,8 +2132,6 @@ and @code{file-name-nondirectory}. For example, (file-name-base "/my/home/foo.c") @result{} "foo" @end example - -The @var{filename} argument defaults to @code{buffer-file-name}. @end defun @node Relative File Names @@ -2376,8 +2367,10 @@ start with @samp{~}.) Otherwise, the current buffer's value of @end example If the part of @var{filename} before the first slash is -@samp{~}, it expands to the value of the @env{HOME} environment -variable (usually your home directory). If the part before the first +@samp{~}, it expands to your home directory, which is typically +specified by the value of the @env{HOME} environment variable +(@pxref{General Variables,,, emacs, The GNU Emacs Manual}). +If the part before the first slash is @samp{~@var{user}} and if @var{user} is a valid login name, it expands to @var{user}'s home directory. If you do not want this expansion for a relative @var{filename} that @@ -2938,7 +2931,7 @@ are included. This is similar to @code{directory-files} in deciding which files to report on and how to report their names. However, instead of returning a list of file names, it returns for each file a -list @code{(@var{filename} @var{attributes})}, where @var{attributes} +list @code{(@var{filename} . @var{attributes})}, where @var{attributes} is what @code{file-attributes} returns for that file. The optional argument @var{id-format} has the same meaning as the corresponding argument to @code{file-attributes} (@pxref{Definition @@ -3015,10 +3008,16 @@ This command creates a directory named @var{dirname}. If @var{parents} is non-@code{nil}, as is always the case in an interactive call, that means to create the parent directories first, if they don't already exist. - @code{mkdir} is an alias for this. @end deffn +@deffn Command make-empty-file filename &optional parents +This command creates an empty file named @var{filename}. +As @code{make-directory}, this command creates parent directories +if @var{parents} is non-@code{nil}. +If @var{filename} already exists, this command signals an error. +@end deffn + @deffn Command copy-directory dirname newname &optional keep-time parents copy-contents This command copies the directory named @var{dirname} to @var{newname}. If @var{newname} is a directory name, @@ -3079,7 +3078,7 @@ expression to define the class of names (all those that match the regular expression), plus a handler that implements all the primitive Emacs file operations for file names that match. -@cindex file handler +@cindex file name handler @vindex file-name-handler-alist The variable @code{file-name-handler-alist} holds a list of handlers, together with regular expressions that determine when to apply each @@ -3150,8 +3149,8 @@ first, before handlers for jobs such as remote file access. @code{directory-file-name}, @code{directory-files}, @code{directory-files-and-attributes}, -@code{dired-compress-file}, @code{dired-uncache},@* -@code{expand-file-name}, +@code{dired-compress-file}, @code{dired-uncache}, +@code{exec-path}, @code{expand-file-name},@* @code{file-accessible-directory-p}, @code{file-acl}, @code{file-attributes}, @@ -3172,7 +3171,8 @@ first, before handlers for jobs such as remote file access. @code{file-ownership-preserved-p}, @code{file-readable-p}, @code{file-regular-p}, @code{file-remote-p}, @code{file-selinux-context}, -@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p}, +@code{file-symlink-p}, @code{file-system-info}, +@code{file-truename}, @code{file-writable-p}, @code{find-backup-file-name},@* @code{get-file-buffer}, @code{insert-directory}, @@ -3182,6 +3182,7 @@ first, before handlers for jobs such as remote file access. @code{make-directory}, @code{make-directory-internal}, @code{make-nearby-temp-file}, +@code{make-process}, @code{make-symbolic-link},@* @code{process-file}, @code{rename-file}, @code{set-file-acl}, @code{set-file-modes}, @@ -3207,7 +3208,7 @@ first, before handlers for jobs such as remote file access. @code{directory-files}, @code{directory-files-and-at@discretionary{}{}{}tributes}, @code{dired-compress-file}, @code{dired-uncache}, -@code{expand-file-name}, +@code{exec-path}, @code{expand-file-name}, @code{file-accessible-direc@discretionary{}{}{}tory-p}, @code{file-acl}, @code{file-attributes}, @@ -3228,7 +3229,8 @@ first, before handlers for jobs such as remote file access. @code{file-ownership-pre@discretionary{}{}{}served-p}, @code{file-readable-p}, @code{file-regular-p}, @code{file-remote-p}, @code{file-selinux-context}, -@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p}, +@code{file-symlink-p}, @code{file-system-info}, +@code{file-truename}, @code{file-writable-p}, @code{find-backup-file-name}, @code{get-file-buffer}, @code{insert-directory}, @@ -3237,6 +3239,7 @@ first, before handlers for jobs such as remote file access. @code{make-auto-save-file-name}, @code{make-direc@discretionary{}{}{}tory}, @code{make-direc@discretionary{}{}{}tory-internal}, +@code{make-process}, @code{make-symbolic-link}, @code{process-file}, @code{rename-file}, @code{set-file-acl}, @code{set-file-modes}, @@ -3364,8 +3367,8 @@ If @code{file-remote-p} returns the same identifier for two different filenames, that means they are stored on the same file system and can be accessed locally with respect to each other. This means, for example, that it is possible to start a remote process accessing both -files at the same time. Implementers of file handlers need to ensure -this principle is valid. +files at the same time. Implementers of file name handlers need to +ensure this principle is valid. @var{identification} specifies which part of the identifier shall be returned as string. @var{identification} can be the symbol @@ -3435,8 +3438,9 @@ between consecutive checks. For example: (let ((remote-file-name-inhibit-cache (- display-time-interval 5))) (and (file-exists-p file) - (< 0 (nth 7 (file-attributes - (file-chase-links file))))))) + (< 0 (file-attribute-size + (file-attributes + (file-chase-links file))))))) @end example @end defopt diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index b993f4932cd..629cec3c5fe 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -181,6 +181,12 @@ the value of that parameter in the created frame to its value in the selected frame. @end defvar +@defopt server-after-make-frame-hook +A normal hook run when the Emacs server creates a client frame. When +this hook is called, the created frame is the selected one. +@xref{Emacs Server,,, emacs, The GNU Emacs Manual}. +@end defopt + @node Multiple Terminals @section Multiple Terminals @@ -434,6 +440,17 @@ This function returns the attributes of the physical monitor dominating (see above) @var{frame}, which defaults to the selected frame. @end defun +On multi-monitor displays it is possible to use the command +@code{make-frame-on-monitor} to make frames on the specified monitor. + +@deffn Command make-frame-on-monitor monitor &optional display parameters +This function creates and returns a new frame on @var{monitor} located +on @var{display}, taking the other frame parameters from the alist +@var{parameters}. @var{monitor} should be the name of the physical +monitor, the same string as returned by the function +@code{display-monitor-attributes-list} in the attribute @code{name}. +@var{display} should be the name of an X display (a string). +@end deffn @node Frame Geometry @section Frame Geometry @@ -1867,6 +1884,12 @@ minibuffer window to @code{t} and vice-versa, or from @code{t} to @code{nil}. If the parameter specifies a minibuffer window already, setting it to @code{nil} has no effect. +The special value @code{child-frame} means to make a minibuffer-only +child frame (@pxref{Child Frames}) whose parent becomes the frame +created. As if specified as @code{nil}, Emacs will set this parameter +to the minibuffer window of the child frame but will not select the +child frame after its creation. + @vindex buffer-predicate@r{, a frame parameter} @item buffer-predicate The buffer-predicate function for this frame. The function @@ -2255,13 +2278,21 @@ variable do not take effect immediately, only when you specify the @vindex font-backend@r{, a frame parameter} @item font-backend A list of symbols, specifying the @dfn{font backends} to use for -drawing fonts in the frame, in order of priority. On X, there are -currently two available font backends: @code{x} (the X core font -driver) and @code{xft} (the Xft font driver). On MS-Windows, there are -currently two available font backends: @code{gdi} and -@code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs -Manual}). On other systems, there is only one available font backend, -so it does not make sense to modify this frame parameter. +drawing characters on the frame, in order of priority. In Emacs built +without Cairo drawing on X, there are currently three available font +backends: @code{x} (the X core font driver), @code{xft} (the Xft font +driver), and @code{xfthb} (the Xft font driver with HarfBuzz text +shaping). If built with the Cairo drawing, there are also three +available font backends on X: @code{x}, @code{ftcr} (the FreeType font +driver on Cairo), and @code{ftcrhb} (the FreeType font driver on Cairo +with HarfBuzz text shaping). On MS-Windows, there are currently three +available font backends: @code{gdi} (the core MS-Windows font driver), +@code{uniscribe} (font driver for OTF and TTF fonts with text shaping +by the Uniscribe engine), and @code{harfbuzz} (font driver for OTF and +TTF fonts with HarfBuzz text shaping) (@pxref{Windows Fonts,,, emacs, +The GNU Emacs Manual}). On other systems, there is only one available +font backend, so it does not make sense to modify this frame +parameter. @vindex background-mode@r{, a frame parameter} @item background-mode @@ -2524,6 +2555,7 @@ it. @deffn Command delete-frame &optional frame force @vindex delete-frame-functions +@vindex after-delete-frame-functions This function deletes the frame @var{frame}. The argument @var{frame} must specify a live frame (see below) and defaults to the selected frame. @@ -2535,7 +2567,9 @@ performed recursively; so this step makes sure that no other frames with @var{frame} as their ancestor will exist. Then, unless @var{frame} specifies a tooltip, this function runs the hook @code{delete-frame-functions} (each function getting one argument, -@var{frame}) before actually killing the frame. +@var{frame}) before actually killing the frame. After actually killing +the frame and removing the frame from the frame list, @code{delete-frame} +runs @code{after-delete-frame-functions}. Note that a frame cannot be deleted as long as its minibuffer serves as surrogate minibuffer for another frame (@pxref{Minibuffers and Frames}). @@ -2696,14 +2730,22 @@ This function returns the selected frame. Some window systems and window managers direct keyboard input to the window object that the mouse is in; others require explicit clicks or commands to @dfn{shift the focus} to various window objects. Either -way, Emacs automatically keeps track of which frame has the focus. To +way, Emacs automatically keeps track of which frames have focus. To explicitly switch to a different frame from a Lisp function, call @code{select-frame-set-input-focus}. -Lisp programs can also switch frames temporarily by calling the -function @code{select-frame}. This does not alter the window system's -concept of focus; rather, it escapes from the window manager's control -until that control is somehow reasserted. +The plural ``frames'' in the previous paragraph is deliberate: while +Emacs itself has only one selected frame, Emacs can have frames on +many different terminals (recall that a connection to a window system +counts as a terminal), and each terminal has its own idea of which +frame has input focus. When you set the input focus to a frame, you +set the focus for that frame's terminal, but frames on other terminals +may still remain focused. + +Lisp programs can switch frames temporarily by calling the function +@code{select-frame}. This does not alter the window system's concept +of focus; rather, it escapes from the window manager's control until +that control is somehow reasserted. When using a text terminal, only one frame can be displayed at a time on the terminal, so after a call to @code{select-frame}, the next @@ -2714,11 +2756,11 @@ before the buffer name (@pxref{Mode Line Variables}). @defun select-frame-set-input-focus frame &optional norecord This function selects @var{frame}, raises it (should it happen to be -obscured by other frames) and tries to give it the X server's focus. -On a text terminal, the next redisplay displays the new frame on the -entire terminal screen. The optional argument @var{norecord} has the -same meaning as for @code{select-frame} (see below). The return value -of this function is not significant. +obscured by other frames) and tries to give it the window system's +focus. On a text terminal, the next redisplay displays the new frame +on the entire terminal screen. The optional argument @var{norecord} +has the same meaning as for @code{select-frame} (see below). +The return value of this function is not significant. @end defun Ideally, the function described next should focus a frame without also @@ -2766,17 +2808,35 @@ could switch to a different terminal without switching back when you're done. @end deffn -Emacs cooperates with the window system by arranging to select frames as -the server and window manager request. It does so by generating a -special kind of input event, called a @dfn{focus} event, when -appropriate. The command loop handles a focus event by calling -@code{handle-switch-frame}. @xref{Focus Events}. +@cindex text-terminal focus notification +Emacs cooperates with the window system by arranging to select frames +as the server and window manager request. When a window system +informs Emacs that one of its frames has been selected, Emacs +internally generates a @dfn{focus-in} event. When an Emacs frame is +displayed on a text-terminal emulator, such as @command{xterm}, which +supports reporting of focus-change notification, the focus-in and +focus-out events are available even for text-mode frames. Focus +events are normally handled by @code{handle-focus-in}. + +@deffn Command handle-focus-in event +This function handles focus-in events from window systems and +terminals that support explicit focus notifications. It updates the +per-frame focus flags that @code{frame-focus-state} queries and calls +@code{after-focus-change-function}. In addition, it generates a +@code{switch-frame} event in order to switch the Emacs notion of the +selected frame to the frame most recently focused in some terminal. +It's important to note that this switching of the Emacs selected frame +to the most recently focused frame does not mean that other frames do +not continue to have the focus in their respective terminals. Do not +invoke this function yourself: instead, attach logic to +@code{after-focus-change-function}. +@end deffn @deffn Command handle-switch-frame frame -This function handles a focus event by selecting frame @var{frame}. - -Focus events normally do their job by invoking this command. -Don't call it for any other reason. +This function handles a switch-frame event, which Emacs generates for +itself upon focus notification or under various other circumstances +involving an input event arriving at a different frame from the last +event. Do not invoke this function yourself. @end deffn @defun redirect-frame-focus frame &optional focus-frame @@ -2810,14 +2870,42 @@ The redirection lasts until @code{redirect-frame-focus} is called to change it. @end defun -@defvar focus-in-hook -This is a normal hook run when an Emacs frame gains input focus. The -frame gaining focus is selected when this hook is run. -@end defvar +@defun frame-focus-state frame +This function retrieves the last known focus state of @var{frame}. + +It returns @code{nil} if the frame is known not to be focused, +@code{t} if the frame is known to be focused, or @code{unknown} if +Emacs does not know the focus state of the frame. (You may see this +last state in TTY frames running on terminals that do not support +explicit focus notifications.) +@end defun -@defvar focus-out-hook -This is a normal hook run when an Emacs frame has lost input focus and -no other Emacs frame has gained input focus instead. +@defvar after-focus-change-function +This function is an extension point that code can use to receive a +notification that focus has changed. + +This function is called with no arguments when Emacs notices that the +set of focused frames may have changed. Code wanting to do something +when frame focus changes should use @code{add-function} to add a +function to this one, and in this added function, re-scan the set of +focused frames, calling @code{frame-focus-state} to retrieve the last +known focus state of each frame. Focus events are delivered +asynchronously, and frame input focus according to an external system +may not correspond to the notion of the Emacs selected frame. +Multiple frames may appear to have input focus simultaneously due to +focus event delivery differences, the presence of multiple Emacs +terminals, and other factors, and code should be robust in the face of +this situation. + +Depending on window system, focus events may also be delivered +repeatedly and with different focus states before settling to the +expected values. Code relying on focus notifications should +``debounce'' any user-visible updates arising from focus changes, +perhaps by deferring work until redisplay. + +This function may be called in arbitrary contexts, including from +inside @code{read-event}, so take the same care as you might when +writing a process filter. @end defvar @defopt focus-follows-mouse @@ -3140,9 +3228,17 @@ top-level frame which also always appears on top of its parent window---the desktop's root window. When a parent frame is iconified or made invisible (@pxref{Visibility of Frames}), its child frames are made invisible. When a parent frame is deiconified or made visible, its -child frames are made visible. When a parent frame is about to be -deleted (@pxref{Deleting Frames}), its child frames are recursively -deleted before it. +child frames are made visible. + + When a parent frame is about to be deleted (@pxref{Deleting +Frames}), its child frames are recursively deleted before it. There +is one exception to this rule: When the child frame serves as a +surrogate minibuffer frame (@pxref{Minibuffers and Frames}) for +another frame, it is retained until the parent frame has been deleted. +If, at this time, no remaining frame uses the child frame as its +minibuffer frame, Emacs will try to delete the child frame too. If +that deletion fails for whatever reason, the child frame is made a +top-level frame. Whether a child frame can have a menu or tool bar is window-system or window manager dependent. Most window-systems explicitly disallow menus diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 0077fad8375..ab07d389282 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -376,8 +376,8 @@ keyword @code{&rest} before one final argument. @example @group (@var{required-vars}@dots{} - @r{[}&optional @var{optional-vars}@dots{}@r{]} - @r{[}&rest @var{rest-var}@r{]}) + @r{[}&optional @r{[}@var{optional-vars}@dots{}@r{]}@r{]} + @r{[}&rest @r{[}@var{rest-var}@r{]}@r{]}) @end group @end example @@ -1122,6 +1122,10 @@ a byte-code function object (@pxref{Byte Compilation}). When lexical binding is enabled, @var{function-object} is converted into a closure. @xref{Closures}. @end itemize + +When @var{function-object} is a symbol and the code is byte compiled, +the byte-compiler will warn if that function is not defined or might +not be known at run time. @end defspec @cindex @samp{#'} syntax @@ -1247,7 +1251,7 @@ This form defines a method like @code{cl-defmethod} does. @end table @end defmac -@defmac cl-defmethod name [qualifier] arguments &rest [docstring] body +@defmac cl-defmethod name [qualifier] arguments [&context (expr spec)@dots{}] &rest [docstring] body This macro defines a particular implementation for the generic function called @var{name}. The implementation code is given by @var{body}. If present, @var{docstring} is the documentation string @@ -1274,15 +1278,20 @@ defined with @code{cl-defstruct} (@pxref{Structures,,, cl, Common Lisp Extensions for GNU Emacs Lisp}), or of one of its child classes. @end table -Alternatively, the argument specializer can be of the form -@code{&context (@var{expr} @var{spec})}, in which case the value of -@var{expr} must be compatible with the specializer provided by -@var{spec}; @var{spec} can be any of the forms described above. In -other words, this form of specializer uses the value of @var{expr} -instead of arguments for the decision whether the method is -applicable. For example, @code{&context (overwrite-mode (eql t))} -will make the method compatible only when @code{overwrite-mode} is -turned on. +Method definitions can make use of a new argument-list keyword, +@code{&context}, which introduces extra specializers that test the +environment at the time the method is run. This keyword should appear +after the list of required arguments, but before any @code{&rest} or +@code{&optional} keywords. The @code{&context} specializers look much +like regular argument specializers---(@var{expr} @var{spec})---except +that @var{expr} is an expression to be evaluated in the current +context, and the @var{spec} is a value to compare against. For +example, @code{&context (overwrite-mode (eql t))} will make the method +applicable only when @code{overwrite-mode} is turned on. The +@code{&context} keyword can be followed by any number of context +specializers. Because the context specializers are not part of the +generic function's argument signature, they may be omitted in methods +that don't require them. The type specializer, @code{(@var{arg} @var{type})}, can specify one of the @dfn{system types} in the following list. When a parent type diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi index d5c9948ca73..9b900e63099 100644 --- a/doc/lispref/hash.texi +++ b/doc/lispref/hash.texi @@ -300,8 +300,8 @@ the same integer. @defun sxhash-eql obj This function returns a hash code for Lisp object @var{obj} suitable for @code{eql} comparison. I.e. it reflects identity of @var{obj} -except for the case where the object is a float number, in which case -hash code is generated for the value. +except for the case where the object is a bignum or a float number, +in which case a hash code is generated for the value. If two objects @var{obj1} and @var{obj2} are @code{eql}, then @code{(sxhash-eql @var{obj1})} and @code{(sxhash-eql @var{obj2})} are @@ -333,6 +333,11 @@ and equal-looking objects are considered the same key. (make-hash-table :test 'contents-hash) @end example +Lisp programs should @emph{not} rely on hash codes being preserved +between Emacs sessions, as the implementation of the hash functions +uses some details of the object storage that can change between +sessions and between different architectures. + @node Other Hash @section Other Hash Table Functions diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi index 7c8748b5e48..f775aa4d4b0 100644 --- a/doc/lispref/hooks.texi +++ b/doc/lispref/hooks.texi @@ -66,6 +66,7 @@ not exactly a hook, but does a similar job. @item after-make-frame-functions @itemx before-make-frame-hook +@itemx server-after-make-frame-hook @xref{Creating Frames}. @c Not general enough? @@ -123,6 +124,7 @@ The command loop runs this soon after @code{post-command-hook} (q.v.). @xref{Input Focus}. @item delete-frame-functions +@itemx after-delete-frame-functions @xref{Deleting Frames}. @item delete-terminal-functions @@ -249,6 +251,7 @@ I thought did not need to be mentioned here: Lisp: after-load-functions +after-set-visited-file-name-hook auto-coding-functions choose-completion-string-functions completing-read-function diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 62a102e3845..cfeb492af40 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -48,24 +48,63 @@ environment. After this step, the Emacs executable is no longer @dfn{bare}. @cindex dumping Emacs +@cindex @option{--temacs} option, and dumping method Because it takes some time to load the standard Lisp files, the @file{temacs} executable usually isn't run directly by users. -Instead, as one of the last steps of building Emacs, the command -@samp{temacs -batch -l loadup dump} is run. The special @samp{dump} -argument causes @command{temacs} to dump out an executable program, -called @file{emacs}, which has all the standard Lisp files preloaded. -(The @samp{-batch} argument prevents @file{temacs} from trying to -initialize any of its data on the terminal, so that the tables of -terminal information are empty in the dumped Emacs.) +Instead, one of the last steps of building Emacs runs the command +@w{@samp{temacs -batch -l loadup --temacs=@var{dump-method}}}. The +special option @option{--temacs} tells @command{temacs} how to record +all the standard preloaded Lisp functions and variables, so that when +you subsequently run Emacs, it will start much faster. The +@option{--temacs} option requires an argument @var{dump-method}, which +can be one of the following: + +@table @samp +@item pdump +@cindex portable dump file +Record the preloaded Lisp data in a @dfn{portable dump} file. This +method produces an additional data file which Emacs will load at +startup. The portable dump file is usually called @file{emacs.pdmp}, +and is installed in the Emacs @code{exec-directory} (@pxref{Help +Functions}). This method is the most preferred one, as it does not +require Emacs to employ any special techniques of memory allocation, +which might get in the way of various memory-layout techniques used by +modern systems to enhance security and privacy. + +@item pbootstrap +@cindex bootstrapping Emacs +Like @samp{pdump}, but used while @dfn{bootstrapping} Emacs, when no +previous Emacs binary and no @file{*.elc} byte-compiled Lisp files are +available. The produced portable dump file is usually named +@file{bootstrap-emacs.pdmp} in this case. + +@item dump +@cindex unexec +This method causes @command{temacs} to dump out an executable program, +called @file{emacs}, which has all the standard Lisp files already +preloaded into it. (The @samp{-batch} argument prevents +@command{temacs} from trying to initialize any of its data on the +terminal, so that the tables of terminal information are empty in the +dumped Emacs.) This method is also known as @dfn{unexec}, because it +produces a program file from a running process, and thus is in some +sense the opposite of executing a program to start a process. + +@item bootstrap +Like @samp{dump}, but used when bootstrapping Emacs with the +@code{unexec} method. +@end table @cindex preloaded Lisp files @vindex preloaded-file-list The dumped @file{emacs} executable (also called a @dfn{pure} Emacs) -is the one which is installed. The variable -@code{preloaded-file-list} stores a list of the Lisp files preloaded -into the dumped Emacs. If you port Emacs to a new operating system, -and are not able to implement dumping, then Emacs must load -@file{loadup.el} each time it starts. +is the one which is installed. If the portable dumping was used to +build Emacs, the @file{emacs} executable is actually an exact copy of +@file{temacs}, and the corresponding @file{emacs.pdmp} file is +installed as well. The variable @code{preloaded-file-list} stores a +list of the preloaded Lisp files recorded in the portable dump file or +in the dumped Emacs executable. If you port Emacs to a new operating +system, and are not able to implement dumping of any kind, then Emacs +must load @file{loadup.el} each time it starts. @cindex build details @cindex deterministic build @@ -161,14 +200,41 @@ In the unlikely event that you need a more general functionality than @code{custom-initialize-delay} provides, you can use @code{before-init-hook} (@pxref{Startup Summary}). +@defun dump-emacs-portable to-file &optional track-referrers +This function dumps the current state of Emacs into a portable dump +file @var{to-file}, using the @code{pdump} method. Normally, the +portable dump file is called @file{@var{emacs-name}.dmp}, where +@var{emacs-name} is the name of the Emacs executable file. The +optional argument @var{track-referrers}, if non-@code{nil}, causes the +portable dumping process keep additional information to help track +down the provenance of object types that are not yet supported by the +@code{pdump} method. + +If you want to use this function in an Emacs that was already dumped, +you must run Emacs with the @samp{-batch} option. +@end defun + @defun dump-emacs to-file from-file @cindex unexec This function dumps the current state of Emacs into an executable file -@var{to-file}. It takes symbols from @var{from-file} (this is normally -the executable file @file{temacs}). +@var{to-file}, using the @code{unexec} method. It takes symbols from +@var{from-file} (this is normally the executable file @file{temacs}). -If you want to use this function in an Emacs that was already dumped, -you must run Emacs with @samp{-batch}. +This function cannot be used in an Emacs that was already dumped. If +Emacs was built without @code{unexec} support, this function will not +be available. +@end defun + +@defun pdumper-stats +If the current Emacs session restored its state from a portable dump +file, this function returns information about the dump file and the +time it took to restore the Emacs state. The value is an alist +@w{@code{((dumped-with-pdumper . t) (load-time . @var{time}) +(dump-file-name . @var{file}))}}, +where @var{file} is the name of the dump file, and @var{time} is the +time in seconds it took to restore the state from the dump file. +If the current session was not restored from a portable dump file, the +value is nil. @end defun @node Pure Storage @@ -247,8 +313,8 @@ of 8k bytes, and small vectors are packed into blocks of 4k bytes). @cindex vector-like objects, storage @cindex storage of vector-like Lisp objects - Beyond the basic vector, a lot of objects like window, buffer, and -frame are managed as if they were vectors. The corresponding C data + Beyond the basic vector, a lot of objects like markers, overlays and +buffers are managed as if they were vectors. The corresponding C data structures include the @code{union vectorlike_header} field whose @code{size} member contains the subtype enumerated by @code{enum pvec_type} and an information about how many @code{Lisp_Object} fields this structure @@ -319,7 +385,6 @@ future allocations. So an overall result is: @example ((@code{conses} @var{cons-size} @var{used-conses} @var{free-conses}) (@code{symbols} @var{symbol-size} @var{used-symbols} @var{free-symbols}) - (@code{miscs} @var{misc-size} @var{used-miscs} @var{free-miscs}) (@code{strings} @var{string-size} @var{used-strings} @var{free-strings}) (@code{string-bytes} @var{byte-size} @var{used-bytes}) (@code{vectors} @var{vector-size} @var{used-vectors}) @@ -335,7 +400,7 @@ Here is an example: @example (garbage-collect) @result{} ((conses 16 49126 8058) (symbols 48 14607 0) - (miscs 40 34 56) (strings 32 2942 2607) + (strings 32 2942 2607) (string-bytes 1 78607) (vectors 16 7247) (vector-slots 8 341609 29474) (floats 8 71 102) (intervals 56 27 26) (buffers 944 8) @@ -367,19 +432,6 @@ The number of symbols in use. The number of symbols for which space has been obtained from the operating system, but that are not currently being used. -@item misc-size -Internal size of a miscellaneous entity, i.e., -@code{sizeof (union Lisp_Misc)}, which is a size of the -largest type enumerated in @code{enum Lisp_Misc_Type}. - -@item used-miscs -The number of miscellaneous objects in use. These include markers -and overlays, plus certain objects not visible to users. - -@item free-miscs -The number of miscellaneous objects for which space has been obtained -from the operating system, but that are not currently being used. - @item string-size Internal size of a string header, i.e., @code{sizeof (struct Lisp_String)}. @@ -397,7 +449,7 @@ This is used for convenience and equals to @code{sizeof (char)}. The total size of all string data in bytes. @item vector-size -Internal size of a vector header, i.e., @code{sizeof (struct Lisp_Vector)}. +Size in bytes of a vector of length 1, including its header. @item used-vectors The number of vector headers allocated from the vector blocks. @@ -407,6 +459,8 @@ Internal size of a vector slot, always equal to @code{sizeof (Lisp_Object)}. @item used-slots The number of slots in all used vectors. +Slot counts might include some or all overhead from vector headers, +depending on the platform. @item free-slots The number of free slots in all vector blocks. @@ -508,10 +562,8 @@ function @code{memory-limit} provides information on the total amount of memory Emacs is currently using. @defun memory-limit -This function returns the address of the last byte Emacs has allocated, -divided by 1024. We divide the value by 1024 to make sure it fits in a -Lisp integer. - +This function returns an estimate of the total amount of bytes of +virtual memory that Emacs is currently using, divided by 1024. You can use this to get a general idea of how your actions affect the memory usage. @end defun @@ -596,6 +648,8 @@ in this Emacs session. @defvar vector-cells-consed The total number of vector cells that have been allocated so far in this Emacs session. +This includes vector-like objects such as markers and overlays, plus +certain objects not visible to users. @end defvar @defvar symbols-consed @@ -608,12 +662,6 @@ The total number of string characters that have been allocated so far in this session. @end defvar -@defvar misc-objects-consed -The total number of miscellaneous objects that have been allocated so -far in this session. These include markers and overlays, plus -certain objects not visible to users. -@end defvar - @defvar intervals-consed The total number of intervals that have been allocated so far in this Emacs session. @@ -760,6 +808,13 @@ names in the documentation string from the ones used in the C code. @samp{usage:} is required if the function has an unlimited number of arguments. +Some primitives have multiple definitions, one per platform (e.g., +@code{x-create-frame}). In such cases, rather than writing the +same documentation string in each definition, only one definition has +the actual documentation. The others have placeholders beginning with +@samp{SKIP}, which are ignored by the function that parses the +@file{DOC} file. + All the usual rules for documentation strings in Lisp code (@pxref{Documentation Tips}) apply to C code documentation strings too. @@ -1136,6 +1191,17 @@ grow with new Emacs releases. Given the version of Emacs, the module can use only the parts of the module @acronym{API} that existed in that version, since those parts are identical in later versions. +@file{emacs-module.h} defines a preprocessor macro +@code{EMACS_MAJOR_VERSION}. It expands to an integer literal which is +the latest major version of Emacs supported by the header. +@xref{Version Info}. Note that the value of +@code{EMACS_MAJOR_VERSION} is a compile-time constant and does not +represent the version of Emacs that is currently running and has +loaded your module. If you want your module to be compatible with +various versions of @file{emacs-module.h} as well as various versions +of Emacs, you can use conditional compilation based on +@code{EMACS_MAJOR_VERSION}. + We recommend that modules always perform the compatibility verification, unless they do their job entirely in the initialization function, and don't access any Lisp objects or use any Emacs functions @@ -1322,7 +1388,9 @@ can be used to obtain the type of a @code{emacs_value} object. This function returns the value of a Lisp integer specified by @var{arg}. The C data type of the return value, @code{intmax_t}, is the widest integral data type supported by the C compiler, typically -@w{@code{long long}}. +@w{@code{long long}}. If the value of @var{arg} doesn't fit into an +@code{intmax_t}, the function signals an error using the error symbol +@code{overflow-error}. @end deftypefn @deftypefn Function double extract_float (emacs_env *@var{env}, emacs_value @var{arg}) @@ -1330,6 +1398,38 @@ This function returns the value of a Lisp float specified by @var{arg}, as a C @code{double} value. @end deftypefn +@deftypefn Function struct timespec extract_time (emacs_env *@var{env}, emacs_value @var{time}) +This function, which is available since Emacs 27, interprets +@var{time} as an Emacs Lisp time value and returns the corresponding +@code{struct timespec}. @xref{Time of Day}. @code{struct timespec} +represents a timestamp with nanosecond precision. It has the +following members: + +@table @code +@item time_t tv_sec +Whole number of seconds. +@item long tv_nsec +Fractional seconds as number of nanoseconds, always less than one +billion. +@end table + +@noindent +@xref{Elapsed Time,,,libc}. + +If @var{time} has higher precision than nanoseconds, then this +function truncates it to nanosecond precision towards negative +infinity. This function signals an error if @var{time} (truncated to +nanoseconds) cannot be represented by @code{struct timespec}. For +example, if @code{time_t} is a 32-bit integral type, then a @var{time} +value of ten billion seconds would signal an error, but a @var{time} +value of 600 picoseconds would get truncated to zero. + +If you need to deal with time values that are not representable by +@code{struct timespec}, or if you want higher precision, call the Lisp +function @code{encode-time} and work with its return value. +@xref{Time Conversion}. +@end deftypefn + @deftypefn Function bool copy_string_contents (emacs_env *@var{env}, emacs_value @var{arg}, char *@var{buf}, ptrdiff_t *@var{len}) This function stores the UTF-8 encoded text of a Lisp string specified by @var{arg} in the array of @code{char} pointed by @var{buf}, which @@ -1384,11 +1484,10 @@ objects from basic C data types. They all return the created @deftypefn Function emacs_value make_integer (emacs_env *@var{env}, intmax_t @var{n}) This function takes an integer argument @var{n} and returns the -corresponding @code{emacs_value} object. It raises the -@code{overflow-error} error condition if the value of @var{n} cannot -be represented as an Emacs integer, i.e.@: is not inside the limits -set by @code{most-negative-fixnum} and @code{most-positive-fixnum} -(@pxref{Integer Basics}). +corresponding @code{emacs_value} object. It returns either a fixnum +or a bignum depending on whether the value of @var{n} is inside the +limits set by @code{most-negative-fixnum} and +@code{most-positive-fixnum} (@pxref{Integer Basics}). @end deftypefn @deftypefn Function emacs_value make_float (emacs_env *@var{env}, double @var{d}) @@ -1396,6 +1495,18 @@ This function takes a @code{double} argument @var{d} and returns the corresponding Emacs floating-point value. @end deftypefn +@deftypefn Function emacs_value make_time (emacs_env *@var{env}, struct timespec @var{time}) +This function, which is available since Emacs 27, takes a @code{struct +timespec} argument @var{time} and returns the corresponding Emacs +timestamp as a pair @code{(@var{ticks} . @var{hz})}. @xref{Time of +Day}. The return value represents exactly the same timestamp as +@var{time}: all input values are representable, and there is never a +loss of precision. @code{@var{time}.tv_sec} and +@code{@var{time}.tv_nsec} can be arbitrary values. In particular, +there's no requirement that @var{time} be normalized. This means that +@code{@var{time}.tv_nsec} can be negative or larger than 999,999,999. +@end deftypefn + @deftypefn Function emacs_value make_string (emacs_env *@var{env}, const char *@var{str}, ptrdiff_t @var{strlen}) This function creates an Emacs string from C text string pointed by @var{str} whose length in bytes, not including the terminating null @@ -1408,6 +1519,66 @@ function raises the @code{overflow-error} error condition if string. @end deftypefn +If you define the preprocessor macro @code{EMACS_MODULE_GMP} before +including the header @file{emacs-module.h}, you can also convert +between Emacs integers and GMP @code{mpz_t} values. @xref{GMP +Basics,,,gmp}. If @code{EMACS_MODULE_GMP} is defined, +@file{emacs-module.h} wraps @code{mpz_t} in the following structure: + +@deftp struct emacs_mpz value +struct emacs_mpz @{ mpz_t value; @}; +@end deftp + +@noindent +Then you can use the following additional functions: + +@deftypefn Function bool extract_big_integer (emacs_env *@var{env}, emacs_value @var{arg}, struct emacs_mpz *@var{result}) +This function, which is available since Emacs 27, extracts the +integral value of @var{arg} into @var{result}. @var{result} must not +be @code{NULL}. @code{@var{result}->value} must be an initialized +@code{mpz_t} object. @xref{Initializing Integers,,,gmp}. If +@var{arg} is an integer, Emacs will store its value into +@code{@var{result}->value}. After you have finished using +@code{@var{result}->value}, you should free it using @code{mpz_clear} +or similar. +@end deftypefn + +@deftypefn Function emacs_value make_big_integer (emacs_env *@var{env}, const struct emacs_mpz *@var{value}) +This function, which is available since Emacs 27, takes an +arbitrary-sized integer argument and returns a corresponding +@code{emacs_value} object. @var{value} must not be @code{NULL}. +@code{@var{value}->value} must be an initialized @code{mpz_t} object. +@xref{Initializing Integers,,,gmp}. Emacs will return a corresponding +integral object. After you have finished using +@code{@var{value}->value}, you should free it using @code{mpz_clear} +or similar. +@end deftypefn + +The following example uses GMP to calculate the next probable prime +after a given integer: + +@example +#include <assert.h> +#include <gmp.h> + +#define EMACS_MODULE_GMP +#include <emacs-module.h> + +static emacs_value +next_prime (emacs_env *env, ptrdiff_t nargs, emacs_value *args, + void *data) +@{ + assert (nargs == 1); + emacs_mpz p; + mpz_init (p.value); + env->extract_big_integer (env, args[0], &p); + mpz_nextprime (p.value, p.value); + emacs_value result = env->make_big_integer (env, &p); + mpz_clear (p.value); + return result; +@} +@end example + The @acronym{API} does not provide functions to manipulate Lisp data structures, for example, create lists with @code{cons} and @code{list} (@pxref{Building Lists}), extract list members with @code{car} and @@ -1567,7 +1738,27 @@ purpose. @deftypefn Function bool should_quit (emacs_env *@var{env}) This function returns @code{true} if the user wants to quit. In that case, we recommend that your module function aborts any on-going -processing and returns as soon as possible. +processing and returns as soon as possible. In most cases, use +@code{process_input} instead. +@end deftypefn + +To process input events in addition to checking whether the user wants +to quit, use the following function, which is available since Emacs +27.1. + +@anchor{process_input} +@deftypefn Function enum emacs_process_input_result process_input (emacs_env *@var{env}) +This function processes pending input events. It returns +@code{emacs_process_input_quit} if the user wants to quit or an error +occurred while processing signals. In that case, we recommend that +your module function aborts any on-going processing and returns as +soon as possible. If the module code may continue running, +@code{process_input} returns @code{emacs_process_input_continue}. The +return value is @code{emacs_process_input_continue} if and only if +there is no pending nonlocal exit in @code{env}. If the module +continues after calling @code{process_input}, global state such as +variable values and buffer content may have been modified in arbitrary +ways. @end deftypefn @node Module Nonlocal @@ -1632,7 +1823,7 @@ The last @acronym{API} function exited via @code{throw}. @end vtable @end deftypefn -@deftypefn Function emacs_funcall_exit non_local_exit_get (emacs_env *@var{env}, emacs_value *@var{symbol}, emacs_value *@var{data}) +@deftypefn Function enum emacs_funcall_exit non_local_exit_get (emacs_env *@var{env}, emacs_value *@var{symbol}, emacs_value *@var{data}) This function returns the kind of nonlocal exit condition stored in @var{env}, like @code{non_local_exit_check} does, but it also returns the full information about the nonlocal exit, if any. If the return @@ -1698,7 +1889,7 @@ a special type to represent the pointers to all of them, which is known as In C, the tagged pointer is an object of type @code{Lisp_Object}. Any initialized variable of such a type always holds the value of one of the following basic data types: integer, symbol, string, cons cell, float, -vectorlike or miscellaneous object. Each of these data types has the +or vectorlike object. Each of these data types has the corresponding tag value. All tags are enumerated by @code{enum Lisp_Type} and placed into a 3-bit bitfield of the @code{Lisp_Object}. The rest of the bits is the value itself. Integers are immediate, i.e., directly @@ -1730,18 +1921,13 @@ Symbol, the unique-named entity commonly used as an identifier. @item struct Lisp_Float Floating-point value. - -@item union Lisp_Misc -Miscellaneous kinds of objects which don't fit into any of the above. @end table These types are the first-class citizens of an internal type system. -Since the tag space is limited, all other types are the subtypes of either -@code{Lisp_Vectorlike} or @code{Lisp_Misc}. Vector subtypes are enumerated +Since the tag space is limited, all other types are the subtypes of +@code{Lisp_Vectorlike}. Vector subtypes are enumerated by @code{enum pvec_type}, and nearly all complex objects like windows, buffers, -frames, and processes fall into this category. The rest of special types, -including markers and overlays, are enumerated by @code{enum Lisp_Misc_Type} -and form the set of subtypes of @code{Lisp_Misc}. +frames, and processes fall into this category. Below there is a description of a few subtypes of @code{Lisp_Vectorlike}. Buffer object represents the text to display and edit. Window is the part diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index 2b5f7905258..2596e87939b 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi @@ -493,7 +493,7 @@ giving a prefix argument makes @var{here} non-@code{nil}. @defvar emacs-build-time The value of this variable indicates the time at which Emacs was -built. It is a list of four integers, like the value of +built. It uses the style of @code{current-time} (@pxref{Time of Day}), or is @code{nil} if the information is not available. @@ -530,6 +530,18 @@ directory (without cleaning). This is only of relevance when developing Emacs. @end defvar +@defvar emacs-repository-version +A string that gives the repository revision from which Emacs was +built. If Emacs was built outside revision control, the value is +@code{nil}. +@end defvar + +@defvar emacs-repository-branch +A string that gives the repository branch from which Emacs was built. +In the most cases this is @code{"master"}. If Emacs was built outside +revision control, the value is @code{nil}. +@end defvar + @node Acknowledgments @section Acknowledgments diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index d839be0e932..6ad665a9502 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -1660,7 +1660,7 @@ to turn the character that follows into a Hyper character: (defun hyperify (prompt) (let ((e (read-event))) (vector (if (numberp e) - (logior (lsh 1 24) e) + (logior (ash 1 24) e) (if (memq 'hyper (event-modifiers e)) e (add-event-modifier "H-" e)))))) @@ -2443,7 +2443,7 @@ Next we define the menu items: @smallexample (define-key menu-bar-replace-menu [tags-repl-continue] - '(menu-item "Continue Replace" tags-loop-continue + '(menu-item "Continue Replace" multifile-continue :help "Continue last tags replace operation")) (define-key menu-bar-replace-menu [tags-repl] '(menu-item "Replace in tagged files" tags-query-replace diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 615f21581aa..746b4643c18 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -156,6 +156,22 @@ considered a list and @code{not} when it is considered a truth value @end example @end defun +@defun proper-list-p object +This function returns the length of @var{object} if it is a proper +list, @code{nil} otherwise (@pxref{Cons Cells}). In addition to +satisfying @code{listp}, a proper list is neither circular nor dotted. + +@example +@group +(proper-list-p '(a b c)) + @result{} 3 +@end group +@group +(proper-list-p '(a b . c)) + @result{} nil +@end group +@end example +@end defun @node List Elements @section Accessing Elements of Lists @@ -651,8 +667,20 @@ non-@code{nil}, it copies vectors too (and operates recursively on their elements). @end defun +@defun flatten-tree tree +This function returns a ``flattened'' copy of @var{tree}, that is, +a list containing all the non-@code{nil} terminal nodes, or leaves, of +the tree of cons cells rooted at @var{tree}. Leaves in the returned +list are in the same order as in @var{tree}. +@end defun + +@example +(flatten-tree '(1 (2 . 3) nil (4 5 (6)) 7)) + @result{}(1 2 3 4 5 6 7) +@end example + @defun number-sequence from &optional to separation -This returns a list of numbers starting with @var{from} and +This function returns a list of numbers starting with @var{from} and incrementing by @var{separation}, and ending at or just before @var{to}. @var{separation} can be positive or negative and defaults to 1. If @var{to} is @code{nil} or numerically equal to @var{from}, @@ -1144,7 +1172,7 @@ each time you run it! Here is what happens: @group (symbol-function 'add-foo) - @result{} (lambda (x) (nconc (quote (foo)) x)) + @result{} (lambda (x) (nconc '(foo) x)) @end group @group @@ -1162,7 +1190,7 @@ each time you run it! Here is what happens: @group (symbol-function 'add-foo) - @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x))) + @result{} (lambda (x) (nconc '(foo 1 2 3 4) x)) @end group @end smallexample @end defun @@ -1736,11 +1764,12 @@ alist @end example @end defun -@defun assoc-delete-all key alist -This function deletes from @var{alist} all the elements whose @sc{car} -is @code{equal} to @var{key}. It works like @code{assq-delete-all}, -except for the predicate used for comparing alist elements with -@var{key}. +@defun assoc-delete-all key alist &optional test +This function is like @code{assq-delete-all} except that it accepts +an optional argument @var{test}, a predicate function to compare the +keys in @var{alist}. If omitted or @code{nil}, @var{test} defaults to +@code{equal}. As @code{assq-delete-all}, this function often modifies +the original list structure of @var{alist}. @end defun @defun rassq-delete-all value alist diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index fa6b301bb0f..3261e6d1888 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -643,7 +643,7 @@ autoloading with a magic comment: Here's what that produces in @file{loaddefs.el}: @example -(autoload (quote doctor) "doctor" "\ +(autoload 'doctor "doctor" "\ Switch to *doctor* buffer and start giving psychotherapy. \(fn)" t nil) diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 3a2a9d82e97..cfea336a9e5 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -634,6 +634,12 @@ A history list for arguments that are Lisp expressions to evaluate. A history list for arguments that are faces. @end defvar +@findex read-variable@r{, history list} +@defvar custom-variable-history +A history list for variable-name arguments read by +@code{read-variable}. +@end defvar + @c Less common: coding-system-history, input-method-history, @c command-history, grep-history, grep-find-history, @c read-envvar-name-history, setenv-history, yes-or-no-p-history. @@ -2252,7 +2258,7 @@ function @code{read-passwd}. @defun read-passwd prompt &optional confirm default This function reads a password, prompting with @var{prompt}. It does not echo the password as the user types it; instead, it echoes -@samp{.} for each character in the password. If you want to apply +@samp{*} for each character in the password. If you want to apply another character to hide the password, let-bind the variable @code{read-hide-char} with that character. @@ -2397,6 +2403,25 @@ will not work. If you want to prevent resizing of minibuffer windows when displaying long messages, bind the @code{message-truncate-lines} variable instead (@pxref{Echo Area Customization}). +The option @code{resize-mini-windows} does not affect the behavior of +minibuffer-only frames (@pxref{Frame Layout}). The following option +allows to automatically resize such frames as well. + +@defopt resize-mini-frames +If this is @code{nil}, minibuffer-only frames are never resized +automatically. + +If this is a function, that function is called with the +minibuffer-only frame to be resized as sole argument. At the time +this function is called, the buffer of the minibuffer window of that +frame is the buffer whose contents will be shown the next time that +window is redisplayed. The function is expected to fit the frame to +the buffer in some appropriate way. + +Any other non-@code{nil} value means to resize minibuffer-only frames +by calling @code{fit-frame-to-buffer} (@pxref{Resizing Windows}). +@end defopt + @node Minibuffer Contents @section Minibuffer Contents @@ -2515,7 +2540,7 @@ locally inside the minibuffer (@pxref{Help Functions}). @anchor{Definition of minibuffer-scroll-window} If the value of this variable is non-@code{nil}, it should be a window object. When the function @code{scroll-other-window} is called in the -minibuffer, it scrolls this window. +minibuffer, it scrolls this window (@pxref{Textual Scrolling}). @end defvar @defun minibuffer-selected-window diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index b6b9b58c71c..f7fb9a4417d 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -142,7 +142,7 @@ in Lisp Interaction mode: (add-hook 'lisp-interaction-mode-hook 'auto-fill-mode) @end example -@defun add-hook hook function &optional append local +@defun add-hook hook function &optional depth local This function is the handy way to add function @var{function} to hook variable @var{hook}. You can use it for abnormal hooks as well as for normal hooks. @var{function} can be any Lisp function that can accept @@ -167,9 +167,18 @@ For a normal hook, hook functions should be designed so that the order in which they are executed does not matter. Any dependence on the order is asking for trouble. However, the order is predictable: normally, @var{function} goes at the front of the hook list, so it is executed -first (barring another @code{add-hook} call). If the optional argument -@var{append} is non-@code{nil}, the new hook function goes at the end of -the hook list and is executed last. +first (barring another @code{add-hook} call). + +In some cases, it is important to control the relative ordering of functions +on the hook. The optional argument @var{depth} lets you indicate where the +function should be inserted in the list: it should then be a number +between -100 and 100 where the higher the value, the closer to the end of the +list the function should go. The @var{depth} defaults to 0 and for backward +compatibility when @var{depth} is a non-nil symbol it is interpreted as a depth +of 90. Furthermore, when @var{depth} is strictly greater than 0 the function +is added @emph{after} rather than before functions of the same depth. +One should never use a depth of 100 (or -100), because one can never be +sure that no other function will ever need to come before (or after) us. @code{add-hook} can handle the cases where @var{hook} is void or its value is a single function; it sets or changes the value to a list of @@ -197,6 +206,7 @@ from the buffer-local hook list instead of from the global hook list. @cindex major mode @cindex major mode command +@cindex suspend major mode temporarily Major modes specialize Emacs for editing or interacting with particular kinds of text. Each buffer has exactly one major mode at a time. Every major mode is associated with a @dfn{major mode command}, @@ -205,7 +215,8 @@ switching to that mode in the current buffer, by setting various buffer-local variables such as a local keymap. @xref{Major Mode Conventions}. Note that unlike minor modes there is no way to ``turn off'' a major mode, instead the buffer must be switched to a different -one. +one. However, you can temporarily @dfn{suspend} a major mode and later +@dfn{restore} the suspended mode, see below. The least specialized major mode is called @dfn{Fundamental mode}, which has no mode-specific definitions or variable settings. @@ -216,6 +227,24 @@ commands, it does @emph{not} run any mode hooks (@pxref{Major Mode Conventions}), since you are not supposed to customize this mode. @end deffn +@defun major-mode-suspend +This function works like @code{fundamental-mode}, in that it kills all +buffer-local variables, but it also records the major mode in effect, +so that it could subsequently be restored. This function and +@code{major-mode-restore} (described next) are useful when you need to +put a buffer under some specialized mode other than the one Emacs +chooses for it automatically (@pxref{Auto Major Mode}), but would also +like to be able to switch back to the original mode later. +@end defun + +@defun major-mode-restore &optional avoided-modes +This function restores the major mode recorded by +@code{major-mode-suspend}. If no major mode was recorded, this +function calls @code{normal-mode} (@pxref{Auto Major Mode, +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 + 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 @@ -997,6 +1026,29 @@ list-processes}). The listing command should create or switch to a buffer, turn on the derived mode, specify the tabulated data, and finally call @code{tabulated-list-print} to populate the buffer. +@defopt tabulated-list-gui-sort-indicator-asc +This variable specifies the character to be used on GUI frames as an +indication that the column is sorted in the ascending order. + +Whenever you change the sort direction in Tabulated List buffers, this +indicator toggles between ascending (``asc'') and descending (``desc''). +@end defopt + +@defopt tabulated-list-gui-sort-indicator-desc +Like @code{tabulated-list-gui-sort-indicator-asc}, but used when the +column is sorted in the descending order. +@end defopt + +@defopt tabulated-list-tty-sort-indicator-asc +Like @code{tabulated-list-gui-sort-indicator-asc}, but used for +text-mode frames. +@end defopt + +@defopt tabulated-list-tty-sort-indicator-desc +Like @code{tabulated-list-tty-sort-indicator-asc}, but used when the +column is sorted in the descending order. +@end defopt + @defvar tabulated-list-format This buffer-local variable specifies the format of the Tabulated List data. Its value should be a vector. Each element of the vector @@ -1250,17 +1302,11 @@ You can thus get the full benefit of adaptive filling Turning on Text mode runs the normal hook `text-mode-hook'." @end group @group - (set (make-local-variable 'text-mode-variant) t) - (set (make-local-variable 'require-final-newline) - mode-require-final-newline) - (set (make-local-variable 'indent-line-function) 'indent-relative)) + (setq-local text-mode-variant t) + (setq-local require-final-newline mode-require-final-newline)) @end group @end smallexample -@noindent -(The last line is redundant nowadays, since @code{indent-relative} is -the default value, and we'll delete it in a future version.) - @cindex @file{lisp-mode.el} The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp Interaction mode) have more features than Text mode and the code is correspondingly diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index ca99cbfcde3..a56a365e9ea 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -829,18 +829,18 @@ two functions support these conversions. This function decodes a character that is assigned a @var{code-point} in @var{charset}, to the corresponding Emacs character, and returns it. If @var{charset} doesn't contain a character of that code point, -the value is @code{nil}. If @var{code-point} doesn't fit in a Lisp -integer (@pxref{Integer Basics, most-positive-fixnum}), it can be +the value is @code{nil}. + +For backward compatibility, if @var{code-point} doesn't fit in a Lisp +fixnum (@pxref{Integer Basics, most-positive-fixnum}), it can be specified as a cons cell @code{(@var{high} . @var{low})}, where @var{low} are the lower 16 bits of the value and @var{high} are the -high 16 bits. +high 16 bits. This usage is obsolescent. @end defun @defun encode-char char charset This function returns the code point assigned to the character -@var{char} in @var{charset}. If the result does not fit in a Lisp -integer, it is returned as a cons cell @code{(@var{high} . @var{low})} -that fits the second argument of @code{decode-char} above. If +@var{char} in @var{charset}. If @var{charset} doesn't have a codepoint for @var{char}, the value is @code{nil}. @end defun @@ -1379,7 +1379,7 @@ operates on the contents of @var{string} instead of bytes in the buffer. @end defun @cindex null bytes, and decoding text -@defvar inhibit-null-byte-detection +@defvar inhibit-nul-byte-detection If this variable has a non-@code{nil} value, null bytes are ignored when detecting the encoding of a region or a string. This allows the encoding of text that contains null bytes to be correctly detected, @@ -2126,9 +2126,9 @@ Return a 12-element vector of month names (locale items @code{MON_1} through @code{MON_12}). @item paper -Return a list @code{(@var{width} @var{height})} for the default paper -size measured in millimeters (locale items @code{PAPER_WIDTH} and -@code{PAPER_HEIGHT}). +Return a list @w{@code{(@var{width} @var{height})}} of 2 integers, for +the default paper size measured in millimeters (locale items +@code{_NL_PAPER_WIDTH} and @code{_NL_PAPER_HEIGHT}). @end table If the system can't provide the requested information, or if diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index e7beed0073d..cae8babcb40 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -14,9 +14,9 @@ fractional parts, such as @minus{}4.5, 0.0, and 2.71828. They can also be expressed in exponential notation: @samp{1.5e2} is the same as @samp{150.0}; here, @samp{e2} stands for ten to the second power, and -that is multiplied by 1.5. Integer computations are exact, though -they may overflow. Floating-point computations often involve rounding -errors, as the numbers have a fixed amount of precision. +that is multiplied by 1.5. Integer computations are exact. +Floating-point computations often involve rounding errors, as the +numbers have a fixed amount of precision. @menu * Integer Basics:: Representation and range of integers. @@ -34,7 +34,23 @@ errors, as the numbers have a fixed amount of precision. @node Integer Basics @section Integer Basics - The range of values for an integer depends on the machine. The + Integers in Emacs Lisp are not limited to the machine word size. + + Under the hood, though, there are two kinds of integers: smaller +ones, called @dfn{fixnums}, and larger ones, called @dfn{bignums}. +Some functions in Emacs accept only fixnums. Also, while fixnums can +always be compared for numeric equality with @code{eq}, bignums +require more-heavyweight equality predicates like @code{eql}. + + The range of values for bignums is limited by the amount of main +memory, by machine characteristics such as the size of the word used +to represent a bignum's exponent, and by the @code{integer-width} +variable. These limits are typically much more generous than the +limits for fixnums. A bignum is never numerically equal to a fixnum; +if Emacs computes an integer in fixnum range, it represents the +integer as a fixnum, not a bignum. + + The range of values for a fixnum depends on the machine. The minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e., @ifnottex @minus{}2**29 @@ -49,21 +65,17 @@ to @tex @math{2^{29}-1}), @end tex -but many machines provide a wider range. Many examples in this -chapter assume the minimum integer width of 30 bits. -@cindex overflow +but many machines provide a wider range. - The Lisp reader reads an integer as a sequence of digits with optional -initial sign and optional final period. An integer that is out of the -Emacs range is treated as a floating-point number. + The Lisp reader reads an integer as a nonempty sequence +of decimal digits with optional initial sign and optional +final period. @example 1 ; @r{The integer 1.} 1. ; @r{The integer 1.} +1 ; @r{Also the integer 1.} -1 ; @r{The integer @minus{}1.} - 9000000000000000000 - ; @r{The floating-point number 9e18.} 0 ; @r{The integer 0.} -0 ; @r{The integer 0.} @end example @@ -74,14 +86,17 @@ Emacs range is treated as a floating-point number. @cindex hex numbers @cindex octal numbers @cindex reading numbers in hex, octal, and binary - The syntax for integers in bases other than 10 uses @samp{#} -followed by a letter that specifies the radix: @samp{b} for binary, -@samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to -specify radix @var{radix}. Case is not significant for the letter -that specifies the radix. Thus, @samp{#b@var{integer}} reads + The syntax for integers in bases other than 10 consists of @samp{#} +followed by a radix indication followed by one or more digits. The +radix indications are @samp{b} for binary, @samp{o} for octal, +@samp{x} for hex, and @samp{@var{radix}r} for radix @var{radix}. +Thus, @samp{#b@var{integer}} reads @var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads @var{integer} in radix @var{radix}. Allowed values of @var{radix} run -from 2 to 36. For example: +from 2 to 36, and allowed digits are the first @var{radix} characters +taken from @samp{0}--@samp{9}, @samp{A}--@samp{Z}. +Letter case is ignored and there is no initial sign or final period. +For example: @example #b101100 @result{} 44 @@ -94,26 +109,26 @@ from 2 to 36. For example: bitwise operators (@pxref{Bitwise Operations}), it is often helpful to view the numbers in their binary form. - In 30-bit binary, the decimal integer 5 looks like this: + In binary, the decimal integer 5 looks like this: @example -0000...000101 (30 bits total) +@dots{}000101 @end example @noindent -(The @samp{...} stands for enough bits to fill out a 30-bit word; in -this case, @samp{...} stands for twenty 0 bits. Later examples also -use the @samp{...} notation to make binary integers easier to read.) +(The ellipsis @samp{@dots{}} stands for a conceptually infinite number +of bits that match the leading bit; here, an infinite number of 0 +bits. Later examples also use this @samp{@dots{}} notation.) The integer @minus{}1 looks like this: @example -1111...111111 (30 bits total) +@dots{}111111 @end example @noindent @cindex two's complement -@minus{}1 is represented as 30 ones. (This is called @dfn{two's +@minus{}1 is represented as all ones. (This is called @dfn{two's complement} notation.) Subtracting 4 from @minus{}1 returns the negative integer @minus{}5. @@ -121,24 +136,7 @@ In binary, the decimal integer 4 is 100. Consequently, @minus{}5 looks like this: @example -1111...111011 (30 bits total) -@end example - - In this implementation, the largest 30-bit binary integer is -536,870,911 in decimal. In binary, it looks like this: - -@example -0111...111111 (30 bits total) -@end example - - Since the arithmetic functions do not check whether integers go -outside their range, when you add 1 to 536,870,911, the value is the -negative integer @minus{}536,870,912: - -@example -(+ 1 536870911) - @result{} -536870912 - @result{} 1000...000000 (30 bits total) +@dots{}111011 @end example Many of the functions described in this chapter accept markers for @@ -147,11 +145,11 @@ arguments to such functions may be either numbers or markers, we often give these arguments the name @var{number-or-marker}. When the argument value is a marker, its position value is used and its buffer is ignored. -@cindex largest Lisp integer -@cindex maximum Lisp integer +@cindex largest fixnum +@cindex maximum fixnum @defvar most-positive-fixnum -The value of this variable is the largest integer that Emacs Lisp can -handle. Typical values are +The value of this variable is the greatest ``small'' integer that Emacs +Lisp can handle. Typical values are @ifnottex 2**29 @minus{} 1 @end ifnottex @@ -168,11 +166,11 @@ on 32-bit and on 64-bit platforms. @end defvar -@cindex smallest Lisp integer -@cindex minimum Lisp integer +@cindex smallest fixnum +@cindex minimum fixnum @defvar most-negative-fixnum -The value of this variable is the smallest integer that Emacs Lisp can -handle. It is negative. Typical values are +The value of this variable is the numerically least ``small'' integer +that Emacs Lisp can handle. It is negative. Typical values are @ifnottex @minus{}2**29 @end ifnottex @@ -189,6 +187,26 @@ on 32-bit and on 64-bit platforms. @end defvar +@cindex bignum range +@cindex integer range +@cindex number of bignum bits, limit on +@defvar integer-width +The value of this variable is a nonnegative integer that controls +whether Emacs signals a range error when a large integer would be +calculated. Integers with absolute values less than +@ifnottex +2**@var{n}, +@end ifnottex +@tex +@math{2^{n}}, +@end tex +where @var{n} is this variable's value, do not signal a range error. +Attempts to create larger integers typically signal a range error, +although there might be no signal if a larger integer can be created cheaply. +Setting this variable to a large number can be costly if a computation +creates huge integers. +@end defvar + In Emacs Lisp, text characters are represented by integers. Any integer between zero and the value of @code{(max-char)}, inclusive, is considered to be valid as a character. @xref{Character Codes}. @@ -213,7 +231,7 @@ least one digit after any decimal point in a floating-point number; @samp{1500.} is an integer, not a floating-point number. Emacs Lisp treats @code{-0.0} as numerically equal to ordinary zero -with respect to @code{equal} and @code{=}. This follows the +with respect to numeric comparisons like @code{=}. This follows the @acronym{IEEE} floating-point standard, which says @code{-0.0} and @code{0.0} are numerically equal even though other operations can distinguish them. @@ -227,8 +245,20 @@ infinity and negative infinity as floating-point values. It also provides for a class of values called NaN, or ``not a number''; numerical functions return such values in cases where there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a NaN@. -Although NaN values carry a sign, for practical purposes there is no other -significant difference between different NaN values in Emacs Lisp. +A NaN is never numerically equal to any value, not even to itself. +NaNs carry a sign and a significand, and non-numeric functions treat +two NaNs as equal when their +signs and significands agree. Significands of NaNs are +machine-dependent, as are the digits in their string representation. + + When NaNs and signed zeros are involved, non-numeric functions like +@code{eql}, @code{equal}, @code{sxhash-eql}, @code{sxhash-equal} and +@code{gethash} determine whether values are indistinguishable, not +whether they are numerically equal. For example, when @var{x} and +@var{y} are the same NaN, @code{(equal x y)} returns @code{t} whereas +@code{(= x y)} uses numeric comparison and returns @code{nil}; +conversely, @code{(equal 0.0 -0.0)} returns @code{nil} whereas +@code{(= 0.0 -0.0)} returns @code{t}. Here are read syntaxes for these special floating-point values: @@ -283,14 +313,18 @@ and returns the result. @var{x1} and @var{x2} must be floating point. @defun logb x This function returns the binary exponent of @var{x}. More -precisely, the value is the logarithm base 2 of @math{|x|}, rounded -down to an integer. +precisely, if @var{x} is finite and nonzero, the value is the +logarithm base 2 of @math{|x|}, rounded down to an integer. +If @var{x} is zero, infinite, or a NaN, the value is minus infinity, +plus infinity, or a NaN respectively. @example (logb 10) @result{} 3 (logb 10.0e20) @result{} 69 +(logb 0) + @result{} -1.0e+INF @end example @end defun @@ -305,6 +339,18 @@ use otherwise), but the @code{zerop} predicate requires a number as its argument. See also @code{integer-or-marker-p} and @code{number-or-marker-p}, in @ref{Predicates on Markers}. +@defun bignump object +This predicate tests whether its argument is a large integer, and +returns @code{t} if so, @code{nil} otherwise. Unlike small integers, +large integers can be @code{=} or @code{eql} even if they are not @code{eq}. +@end defun + +@defun fixnump object +This predicate tests whether its argument is a small integer, and +returns @code{t} if so, @code{nil} otherwise. Small integers can be +compared with @code{eq}. +@end defun + @defun floatp object This predicate tests whether its argument is floating point and returns @code{t} if so, @code{nil} otherwise. @@ -344,23 +390,27 @@ if so, @code{nil} otherwise. The argument must be a number. @cindex comparing numbers To test numbers for numerical equality, you should normally use -@code{=}, not @code{eq}. There can be many distinct floating-point -objects with the same numeric value. If you use @code{eq} to -compare them, then you test whether two values are the same -@emph{object}. By contrast, @code{=} compares only the numeric values -of the objects. - - In Emacs Lisp, each integer is a unique Lisp object. -Therefore, @code{eq} is equivalent to @code{=} where integers are -concerned. It is sometimes convenient to use @code{eq} for comparing -an unknown value with an integer, because @code{eq} does not report an +@code{=} instead of non-numeric comparison predicates like @code{eq}, +@code{eql} and @code{equal}. Distinct floating-point and large +integer objects can be numerically equal. If you use @code{eq} to +compare them, you test whether they are the same @emph{object}; if you +use @code{eql} or @code{equal}, you test whether their values are +@emph{indistinguishable}. In contrast, @code{=} uses numeric +comparison, and sometimes returns @code{t} when a non-numeric +comparison would return @code{nil} and vice versa. @xref{Float +Basics}. + + In Emacs Lisp, if two fixnums are numerically equal, they are the +same Lisp object. That is, @code{eq} is equivalent to @code{=} on +fixnums. It is sometimes convenient to use @code{eq} for comparing +an unknown value with a fixnum, because @code{eq} does not report an error if the unknown value is not a number---it accepts arguments of any type. By contrast, @code{=} signals an error if the arguments are not numbers or markers. However, it is better programming practice to use @code{=} if you can, even for comparing integers. - Sometimes it is useful to compare numbers with @code{equal}, which -treats two numbers as equal if they have the same data type (both + Sometimes it is useful to compare numbers with @code{eql} or @code{equal}, +which treat two numbers as equal if they have the same data type (both integers, or both floating point) and the same value. By contrast, @code{=} can treat an integer and a floating-point number as equal. @xref{Equality Predicates}. @@ -379,15 +429,6 @@ Here's a function to do this: fuzz-factor))) @end example -@cindex CL note---integers vrs @code{eq} -@quotation -@b{Common Lisp note:} Comparing numbers in Common Lisp always requires -@code{=} because Common Lisp implements multi-word integers, and two -distinct integer objects can have the same numeric value. Emacs Lisp -can have just one integer object for any given value because it has a -limited range of integers. -@end quotation - @defun = number-or-marker &rest number-or-markers This function tests whether all its arguments are numerically equal, and returns @code{t} if so, @code{nil} otherwise. @@ -397,7 +438,8 @@ and returns @code{t} if so, @code{nil} otherwise. This function acts like @code{eq} except when both arguments are numbers. It compares numbers by type and numeric value, so that @code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and -@code{(eql 1 1)} both return @code{t}. +@code{(eql 1 1)} both return @code{t}. This can be used to compare +large integers as well as small ones. @end defun @defun /= number-or-marker1 number-or-marker2 @@ -557,10 +599,6 @@ Except for @code{%}, each of these functions accepts both integer and floating-point arguments, and returns a floating-point number if any argument is floating point. - Emacs Lisp arithmetic functions do not check for integer overflow. -Thus @code{(1+ 536870911)} may evaluate to -@minus{}536870912, depending on your hardware. - @defun 1+ number-or-marker This function returns @var{number-or-marker} plus 1. For example, @@ -814,181 +852,119 @@ Rounding a value equidistant between two integers returns the even integer. @cindex logical arithmetic In a computer, an integer is represented as a binary number, a -sequence of @dfn{bits} (digits which are either zero or one). A bitwise +sequence of @dfn{bits} (digits which are either zero or one). +Conceptually the bit sequence is infinite on the left, with the +most-significant bits being all zeros or all ones. A bitwise operation acts on the individual bits of such a sequence. For example, @dfn{shifting} moves the whole sequence left or right one or more places, reproducing the same pattern moved over. The bitwise operations in Emacs Lisp apply only to integers. -@defun lsh integer1 count -@cindex logical shift -@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the -bits in @var{integer1} to the left @var{count} places, or to the right -if @var{count} is negative, bringing zeros into the vacated bits. If -@var{count} is negative, @code{lsh} shifts zeros into the leftmost -(most-significant) bit, producing a positive result even if -@var{integer1} is negative. Contrast this with @code{ash}, below. +@defun ash integer1 count +@cindex arithmetic shift +@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} +to the left @var{count} places, or to the right if @var{count} is +negative. Left shifts introduce zero bits on the right; right shifts +discard the rightmost bits. Considered as an integer operation, +@code{ash} multiplies @var{integer1} by +@ifnottex +2**@var{count}, +@end ifnottex +@tex +@math{2^{count}}, +@end tex +and then converts the result to an integer by rounding downward, toward +minus infinity. -Here are two examples of @code{lsh}, shifting a pattern of bits one -place to the left. We show only the low-order eight bits of the binary -pattern; the rest are all zero. +Here are examples of @code{ash}, shifting a pattern of bits one place +to the left and to the right. These examples show only the low-order +bits of the binary pattern; leading bits all agree with the +highest-order bit shown. As you can see, shifting left by one is +equivalent to multiplying by two, whereas shifting right by one is +equivalent to dividing by two and then rounding toward minus infinity. @example @group -(lsh 5 1) - @result{} 10 -;; @r{Decimal 5 becomes decimal 10.} -00000101 @result{} 00001010 - -(lsh 7 1) - @result{} 14 +(ash 7 1) @result{} 14 ;; @r{Decimal 7 becomes decimal 14.} -00000111 @result{} 00001110 +@dots{}000111 + @result{} +@dots{}001110 @end group -@end example - -@noindent -As the examples illustrate, shifting the pattern of bits one place to -the left produces a number that is twice the value of the previous -number. - -Shifting a pattern of bits two places to the left produces results -like this (with 8-bit binary numbers): -@example @group -(lsh 3 2) - @result{} 12 -;; @r{Decimal 3 becomes decimal 12.} -00000011 @result{} 00001100 +(ash 7 -1) @result{} 3 +@dots{}000111 + @result{} +@dots{}000011 @end group -@end example -On the other hand, shifting one place to the right looks like this: - -@example @group -(lsh 6 -1) - @result{} 3 -;; @r{Decimal 6 becomes decimal 3.} -00000110 @result{} 00000011 +(ash -7 1) @result{} -14 +@dots{}111001 + @result{} +@dots{}110010 @end group @group -(lsh 5 -1) - @result{} 2 -;; @r{Decimal 5 becomes decimal 2.} -00000101 @result{} 00000010 +(ash -7 -1) @result{} -4 +@dots{}111001 + @result{} +@dots{}111100 @end group @end example -@noindent -As the example illustrates, shifting one place to the right divides the -value of a positive integer by two, rounding downward. +Here are examples of shifting left or right by two bits: -The function @code{lsh}, like all Emacs Lisp arithmetic functions, does -not check for overflow, so shifting left can discard significant bits -and change the sign of the number. For example, left shifting -536,870,911 produces @minus{}2 in the 30-bit implementation: - -@example -(lsh 536870911 1) ; @r{left shift} - @result{} -2 -@end example - -In binary, the argument looks like this: - -@example +@smallexample @group -;; @r{Decimal 536,870,911} -0111...111111 (30 bits total) + ; @r{ binary values} +(ash 5 2) ; 5 = @r{@dots{}000101} + @result{} 20 ; = @r{@dots{}010100} +(ash -5 2) ; -5 = @r{@dots{}111011} + @result{} -20 ; = @r{@dots{}101100} @end group -@end example - -@noindent -which becomes the following when left shifted: - -@example @group -;; @r{Decimal @minus{}2} -1111...111110 (30 bits total) +(ash 5 -2) + @result{} 1 ; = @r{@dots{}000001} @end group -@end example -@end defun - -@defun ash integer1 count -@cindex arithmetic shift -@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} -to the left @var{count} places, or to the right if @var{count} -is negative. - -@code{ash} gives the same results as @code{lsh} except when -@var{integer1} and @var{count} are both negative. In that case, -@code{ash} puts ones in the empty bit positions on the left, while -@code{lsh} puts zeros in those bit positions. - -Thus, with @code{ash}, shifting the pattern of bits one place to the right -looks like this: - -@example @group -(ash -6 -1) @result{} -3 -;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} -1111...111010 (30 bits total) - @result{} -1111...111101 (30 bits total) +(ash -5 -2) + @result{} -2 ; = @r{@dots{}111110} @end group -@end example - -In contrast, shifting the pattern of bits one place to the right with -@code{lsh} looks like this: +@end smallexample +@end defun -@example -@group -(lsh -6 -1) @result{} 536870909 -;; @r{Decimal @minus{}6 becomes decimal 536,870,909.} -1111...111010 (30 bits total) - @result{} -0111...111101 (30 bits total) -@end group -@end example +@defun lsh integer1 count +@cindex logical shift +@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the +bits in @var{integer1} to the left @var{count} places, or to the right +if @var{count} is negative, bringing zeros into the vacated bits. If +@var{count} is negative, then @var{integer1} must be either a fixnum +or a positive bignum, and @code{lsh} treats a negative fixnum as if it +were unsigned by subtracting twice @code{most-negative-fixnum} before +shifting, producing a nonnegative result. This quirky behavior dates +back to when Emacs supported only fixnums; nowadays @code{ash} is a +better choice. -Here are other examples: +As @code{lsh} behaves like @code{ash} except when @var{integer1} and +@var{count1} are both negative, the following examples focus on these +exceptional cases. These examples assume 30-bit fixnums. -@c !!! Check if lined up in smallbook format! XDVI shows problem -@c with smallbook but not with regular book! --rjc 16mar92 @smallexample @group - ; @r{ 30-bit binary values} - -(lsh 5 2) ; 5 = @r{0000...000101} - @result{} 20 ; = @r{0000...010100} + ; @r{ binary values} +(ash -7 -1) ; -7 = @r{@dots{}111111111111111111111111111001} + @result{} -4 ; = @r{@dots{}111111111111111111111111111100} +(lsh -7 -1) + @result{} 536870908 ; = @r{@dots{}011111111111111111111111111100} @end group @group -(ash 5 2) - @result{} 20 -(lsh -5 2) ; -5 = @r{1111...111011} - @result{} -20 ; = @r{1111...101100} -(ash -5 2) - @result{} -20 -@end group -@group -(lsh 5 -2) ; 5 = @r{0000...000101} - @result{} 1 ; = @r{0000...000001} -@end group -@group -(ash 5 -2) - @result{} 1 -@end group -@group -(lsh -5 -2) ; -5 = @r{1111...111011} - @result{} 268435454 - ; = @r{0011...111110} -@end group -@group -(ash -5 -2) ; -5 = @r{1111...111011} - @result{} -2 ; = @r{1111...111110} +(ash -5 -2) ; -5 = @r{@dots{}111111111111111111111111111011} + @result{} -2 ; = @r{@dots{}111111111111111111111111111110} +(lsh -5 -2) + @result{} 268435454 ; = @r{@dots{}001111111111111111111111111110} @end group @end smallexample @end defun @@ -1022,23 +998,23 @@ because its binary representation consists entirely of ones. If @smallexample @group - ; @r{ 30-bit binary values} + ; @r{ binary values} -(logand 14 13) ; 14 = @r{0000...001110} - ; 13 = @r{0000...001101} - @result{} 12 ; 12 = @r{0000...001100} +(logand 14 13) ; 14 = @r{@dots{}001110} + ; 13 = @r{@dots{}001101} + @result{} 12 ; 12 = @r{@dots{}001100} @end group @group -(logand 14 13 4) ; 14 = @r{0000...001110} - ; 13 = @r{0000...001101} - ; 4 = @r{0000...000100} - @result{} 4 ; 4 = @r{0000...000100} +(logand 14 13 4) ; 14 = @r{@dots{}001110} + ; 13 = @r{@dots{}001101} + ; 4 = @r{@dots{}000100} + @result{} 4 ; 4 = @r{@dots{}000100} @end group @group (logand) - @result{} -1 ; -1 = @r{1111...111111} + @result{} -1 ; -1 = @r{@dots{}111111} @end group @end smallexample @end defun @@ -1052,18 +1028,18 @@ passed just one argument, it returns that argument. @smallexample @group - ; @r{ 30-bit binary values} + ; @r{ binary values} -(logior 12 5) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - @result{} 13 ; 13 = @r{0000...001101} +(logior 12 5) ; 12 = @r{@dots{}001100} + ; 5 = @r{@dots{}000101} + @result{} 13 ; 13 = @r{@dots{}001101} @end group @group -(logior 12 5 7) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - ; 7 = @r{0000...000111} - @result{} 15 ; 15 = @r{0000...001111} +(logior 12 5 7) ; 12 = @r{@dots{}001100} + ; 5 = @r{@dots{}000101} + ; 7 = @r{@dots{}000111} + @result{} 15 ; 15 = @r{@dots{}001111} @end group @end smallexample @end defun @@ -1077,18 +1053,18 @@ result is 0, which is an identity element for this operation. If @smallexample @group - ; @r{ 30-bit binary values} + ; @r{ binary values} -(logxor 12 5) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - @result{} 9 ; 9 = @r{0000...001001} +(logxor 12 5) ; 12 = @r{@dots{}001100} + ; 5 = @r{@dots{}000101} + @result{} 9 ; 9 = @r{@dots{}001001} @end group @group -(logxor 12 5 7) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - ; 7 = @r{0000...000111} - @result{} 14 ; 14 = @r{0000...001110} +(logxor 12 5 7) ; 12 = @r{@dots{}001100} + ; 5 = @r{@dots{}000101} + ; 7 = @r{@dots{}000111} + @result{} 14 ; 14 = @r{@dots{}001110} @end group @end smallexample @end defun @@ -1101,9 +1077,27 @@ bit is one in the result if, and only if, the @var{n}th bit is zero in @example (lognot 5) @result{} -6 -;; 5 = @r{0000...000101} (30 bits total) +;; 5 = @r{@dots{}000101} ;; @r{becomes} -;; -6 = @r{1111...111010} (30 bits total) +;; -6 = @r{@dots{}111010} +@end example +@end defun + +@cindex popcount +@cindex Hamming weight +@cindex counting set bits +@defun logcount integer +This function returns the @dfn{Hamming weight} of @var{integer}: the +number of ones in the binary representation of @var{integer}. +If @var{integer} is negative, it returns the number of zero bits in +its two's complement binary representation. The result is always +nonnegative. + +@example +(logcount 43) ; 43 = @r{@dots{}000101011} + @result{} 4 +(logcount -43) ; -43 = @r{@dots{}111010101} + @result{} 3 @end example @end defun @@ -1189,8 +1183,8 @@ returns a NaN. @defun expt x y This function returns @var{x} raised to power @var{y}. If both -arguments are integers and @var{y} is positive, the result is an -integer; in this case, overflow causes truncation, so watch out. +arguments are integers and @var{y} is nonnegative, the result is an +integer; in this case, overflow signals an error, so watch out. If @var{x} is a finite negative number and @var{y} is a finite non-integer, @code{expt} returns a NaN. @end defun @@ -1241,11 +1235,10 @@ other strings to choose various seed values. This function returns a pseudo-random integer. Repeated calls return a series of pseudo-random integers. -If @var{limit} is a positive integer, the value is chosen to be +If @var{limit} is a positive fixnum, the value is chosen to be nonnegative and less than @var{limit}. Otherwise, the value might be -any integer representable in Lisp, i.e., an integer between -@code{most-negative-fixnum} and @code{most-positive-fixnum} -(@pxref{Integer Basics}). +any fixnum, i.e., any integer from @code{most-negative-fixnum} through +@code{most-positive-fixnum} (@pxref{Integer Basics}). If @var{limit} is @code{t}, it means to choose a new seed as if Emacs were restarting, typically from the system entropy. On systems diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 69b6c859f65..745baacc297 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -166,7 +166,10 @@ latter are unique to Emacs Lisp. @node Integer Type @subsection Integer Type - The range of values for an integer depends on the machine. The + Under the hood, there are two kinds of integers---small integers, +called @dfn{fixnums}, and large integers, called @dfn{bignums}. + + The range of values for a fixnum depends on the machine. The minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e., @ifnottex @minus{}2**29 @@ -182,8 +185,15 @@ to @math{2^{29}-1}) @end tex but many machines provide a wider range. -Emacs Lisp arithmetic functions do not check for integer overflow. Thus -@code{(1+ 536870911)} is @minus{}536,870,912 if Emacs integers are 30 bits. + + Bignums can have arbitrary precision. Operations that overflow a +fixnum will return a bignum instead. + + Fixnums can be compared with @code{eq}, but bignums require +@code{eql} or @code{=}. To test whether an integer is a fixnum or a +bignum, you can compare it to @code{most-negative-fixnum} and +@code{most-positive-fixnum}, or you can use the convenience predicates +@code{fixnump} and @code{bignump} on any object. The read syntax for integers is a sequence of (base ten) digits with an optional sign at the beginning and an optional period at the end. The @@ -200,11 +210,6 @@ leading @samp{+} or a final @samp{.}. @end example @noindent -As a special exception, if a sequence of digits specifies an integer -too large or too small to be a valid integer object, the Lisp reader -reads it as a floating-point number (@pxref{Floating-Point Type}). -For instance, if Emacs integers are 30 bits, @code{536870912} is read -as the floating-point number @code{536870912.0}. @xref{Numbers}, for more information. @@ -1895,6 +1900,9 @@ with references to further information. @item arrayp @xref{Array Functions, arrayp}. +@item bignump +@xref{Predicates on Numbers, floatp}. + @item bool-vector-p @xref{Bool-Vectors, bool-vector-p}. @@ -1928,6 +1936,9 @@ with references to further information. @item custom-variable-p @xref{Variable Definitions, custom-variable-p}. +@item fixnump +@xref{Predicates on Numbers, floatp}. + @item floatp @xref{Predicates on Numbers, floatp}. @@ -2083,6 +2094,10 @@ strings), two arguments with the same contents or elements are not necessarily @code{eq} to each other: they are @code{eq} only if they are the same object, meaning that a change in the contents of one will be reflected by the same change in the contents of the other. +For other types of objects whose contents cannot be changed (e.g., +floats), two arguments with the same contents might or might not be +the same object, and @code{eq} returns @code{t} or @code{nil} +depending on whether the Lisp interpreter created one object or two. @example @group @@ -2096,6 +2111,12 @@ be reflected by the same change in the contents of the other. @end group @group +(eq 3.0 3.0) + @result{} t @r{or} nil +;; @r{The result is implementation-dependent.} +@end group + +@group (eq "asdf" "asdf") @result{} nil @end group diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index a04f03bd463..fef954eb7a3 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -95,6 +95,22 @@ if requested by environment variables such as @env{LANG}. @item It does some basic parsing of the command-line arguments. +@item +It loads your early init file (@pxref{Early Init File,,, emacs, The +GNU Emacs Manual}). This is not done if the options @samp{-q}, +@samp{-Q}, or @samp{--batch} were specified. If the @samp{-u} option +was specified, Emacs looks for the init file in that user's home +directory instead. + +@item +It calls the function @code{package-activate-all} to activate any +optional Emacs Lisp package that has been installed. @xref{Packaging +Basics}. However, Emacs doesn't activate the packages when +@code{package-enable-at-startup} is @code{nil} or when it's started +with one of the options @samp{-q}, @samp{-Q}, or @samp{--batch}. To +activate the packages in the latter case, @code{package-activate-all} +should be called explicitly (e.g., via the @samp{--funcall} option). + @vindex initial-window-system@r{, and startup} @findex window-system-initialization @item @@ -159,15 +175,6 @@ It loads your abbrevs from the file specified by (@pxref{Abbrev Files, abbrev-file-name}). This is not done if the option @samp{--batch} was specified. -@item -It calls the function @code{package-initialize} to activate any -optional Emacs Lisp package that has been installed. @xref{Packaging -Basics}. However, Emacs doesn't initialize packages when -@code{package-enable-at-startup} is @code{nil} or when it's started -with one of the options @samp{-q}, @samp{-Q}, or @samp{--batch}. To -initialize packages in the latter case, @code{package-initialize} -should be called explicitly (e.g., via the @samp{--funcall} option). - @vindex after-init-time @item It sets the variable @code{after-init-time} to the value of @@ -366,6 +373,7 @@ Equivalent to @samp{-q --no-site-file --no-splash}. @cindex init file @cindex @file{.emacs} @cindex @file{init.el} +@cindex @file{early-init.el} When you start Emacs, it normally attempts to load your @dfn{init file}. This is either a file named @file{.emacs} or @file{.emacs.el} @@ -389,6 +397,19 @@ file; this way, even if you have su'd, Emacs still loads your own init file. If those environment variables are absent, though, Emacs uses your user-id to find your home directory. +@cindex early init file + Emacs also attempts to load a second init file, called the +@dfn{early init file}, if it exists. This is a file named +@file{early-init.el} in your @file{~/.emacs.d} directory. The +difference between the early init file and the regular init file is +that the early init file is loaded much earlier during the startup +process, so you can use it to customize some things that are +initialized before loading the regular init file. For example, you +can customize the process of initializing the package system, by +setting variables such as @var{package-load-list} or +@var{package-enable-at-startup}. @xref{Package Installation,,, +emacs,The GNU Emacs Manual}. + @cindex default init file An Emacs installation may have a @dfn{default init file}, which is a Lisp library named @file{default.el}. Emacs finds this file through @@ -1181,24 +1202,19 @@ Titles}). @cindex UID @defun user-real-uid This function returns the real @acronym{UID} of the user. -The value may be floating point, in the (unlikely) event that -the UID is too large to fit in a Lisp integer. @end defun @defun user-uid This function returns the effective @acronym{UID} of the user. -The value may be floating point. @end defun @cindex GID @defun group-gid This function returns the effective @acronym{GID} of the Emacs process. -The value may be floating point. @end defun @defun group-real-gid This function returns the real @acronym{GID} of the Emacs process. -The value may be floating point. @end defun @defun system-users @@ -1214,6 +1230,11 @@ groups on the system. If Emacs cannot retrieve this information, the return value is @code{nil}. @end defun +@defun group-name gid +This function returns the group name that corresponds to the numeric +group ID @var{gid}, or @code{nil} if there is no such group. +@end defun + @node Time of Day @section Time of Day @@ -1222,11 +1243,44 @@ return value is @code{nil}. This section explains how to determine the current time and time zone. +@cindex Lisp timestamp +@cindex timestamp, Lisp + Many functions like @code{current-time} and @code{file-attributes} +return @dfn{Lisp timestamp} values that count seconds, and that can +represent absolute time by counting seconds since the @dfn{epoch} of +1970-01-01 00:00:00 UTC. + + Although traditionally Lisp timestamps were integer pairs, their +form has evolved and programs ordinarily should not depend on the +current default form. If your program needs a particular timestamp +form, you can use the @code{encode-time} function to convert it to the +needed form. @xref{Time Conversion}. + @cindex epoch - Most of these functions represent time as a list of four integers -@code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}. -This represents the number of seconds from the @dfn{epoch} (January -1, 1970 at 00:00 UTC), using the formula: + There are currently three forms of Lisp timestamps, each of +which represents a number of seconds: + +@itemize @bullet +@item +An integer. Although this is the simplest form, it cannot represent +subsecond timestamps. + +@item +A pair of integers @code{(@var{ticks} . @var{hz})}, where @var{hz} is +positive. This represents @var{ticks}/@var{hz} seconds, which is the +same time as plain @var{ticks} if @var{hz} is 1. A common value for +@var{hz} is 1000000000, for a nanosecond-resolution +clock.@footnote{Currently @var{hz} should be at least 65536 to avoid +compatibility warnings when the timestamp is passed to standard +functions, as previous versions of Emacs would interpret such a +timestamps differently due to backward-compatibility concerns. These +warnings are intended to be removed in a future Emacs version.} + +@item +A list of four integers @code{(@var{high} @var{low} @var{micro} +@var{pico})}, where 0 @leq{} @var{low} < 65536, 0 @leq{} @var{micro} < +1000000, and 0 @leq{} @var{pico} < 1000000. +This represents the number of seconds using the formula: @ifnottex @var{high} * 2**16 + @var{low} + @var{micro} * 10**@minus{}6 + @var{pico} * 10**@minus{}12. @@ -1234,21 +1288,23 @@ This represents the number of seconds from the @dfn{epoch} (January @tex $high*2^{16} + low + micro*10^{-6} + pico*10^{-12}$. @end tex -The return value of @code{current-time} represents time using this -form, as do the timestamps in the return values of other functions -such as @code{file-attributes} (@pxref{Definition of -file-attributes}). In some cases, functions may return two- or +In some cases, functions may default to returning two- or three-element lists, with omitted @var{microsec} and @var{picosec} components defaulting to zero. +On all current machines @var{picosec} is a multiple of 1000, but this +may change as higher-resolution clocks become available. +@end itemize @cindex time value Function arguments, e.g., the @var{time} argument to @code{current-time-string}, accept a more-general @dfn{time value} -format, which can be a list of integers as above, or a single number -for seconds since the epoch, or @code{nil} for the current time. You -can convert a time value into a human-readable string using -@code{current-time-string} and @code{format-time-string}, into a list -of integers using @code{seconds-to-time}, and into other forms using +format, which can be a Lisp timestamp, @code{nil} for the current +time, a single floating-point number for seconds, or a list +@code{(@var{high} @var{low} @var{micro})} or @code{(@var{high} +@var{low})} that is a truncated list timestamp with missing elements +taken to be zero. You can convert a time value into +a human-readable string using @code{format-time-string}, into a Lisp +timestamp using @code{encode-time}, and into other forms using @code{decode-time} and @code{float-time}. These functions are described in the following sections. @@ -1257,9 +1313,10 @@ This function returns the current time and date as a human-readable string. The format does not vary for the initial part of the string, which contains the day of week, month, day of month, and time of day in that order: the number of characters used for these fields is -always the same, so you can reliably -use @code{substring} to extract them. You should count -characters from the beginning of the string rather than from the end, +always the same, although (unless you require English weekday or +month abbreviations regardless of locale) it is typically more +convenient to use @code{format-time-string} than to extract +fields from the output of @code{current-time-string}, as the year might not have exactly four digits, and additional information may some day be added at the end. @@ -1276,12 +1333,7 @@ defaults to the current time zone rule. @xref{Time Zone Rules}. @end defun @defun current-time -This function returns the current time, represented as a list of four -integers @code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}. -These integers have trailing zeros on systems that return time with -lower resolutions. On all current machines @var{picosec} is a -multiple of 1000, but this may change as higher-resolution clocks -become available. +This function returns the current time as a Lisp timestamp. @end defun @defun float-time &optional time @@ -1295,13 +1347,6 @@ exact. Do not use this function if precise time stamps are required. @code{time-to-seconds} is an alias for this function. @end defun -@defun seconds-to-time time -This function converts a time value to list-of-integer form. -For example, if @var{time} is a number, @code{(time-to-seconds -(seconds-to-time @var{time}))} equals the number unless overflow -or rounding errors occur. -@end defun - @node Time Zone Rules @section Time Zone Rules @cindex time zone rules @@ -1412,7 +1457,8 @@ The year, an integer typically greater than 1900. The day of week, as an integer between 0 and 6, where 0 stands for Sunday. @item dst -@code{t} if daylight saving time is effect, otherwise @code{nil}. +@code{t} if daylight saving time is effect, @code{nil} if it is not +in effect, and @minus{}1 if this information is not available. @item utcoff An integer indicating the Universal Time offset in seconds, i.e., the number of seconds east of Greenwich. @@ -1422,32 +1468,63 @@ seconds east of Greenwich. @var{dow} and @var{utcoff}. @end defun -@defun encode-time seconds minutes hour day month year &optional zone -This function is the inverse of @code{decode-time}. It converts seven -items of calendrical data into a list-of-integer time value. For the -meanings of the arguments, see the table above under -@code{decode-time}. +@defun encode-time &optional time form &rest obsolescent-arguments +This function converts @var{time} to a Lisp timestamp. +It can act as the inverse of @code{decode-time}. + +The first argument can be a time value such as a number of seconds, a +pair @code{(@var{ticks} . @var{hz})}, a list @code{(@var{high} +@var{low} @var{micro} @var{pico})}, or @code{nil} (the default) for +the current time (@pxref{Time of Day}). It can also be a list +@code{(@var{second} @var{minute} @var{hour} @var{day} @var{month} +@var{year} @var{ignored} @var{dst} @var{zone})} that specifies a +decoded time in the style of @code{decode-time}, so that +@code{(encode-time (decode-time ...))} works. For the meanings of +these list members, see the table under @code{decode-time}. + +The optional @var{form} argument specifies the desired timestamp form +to be returned. If @var{form} is the symbol @code{integer}, this +function returns an integer count of seconds. If @var{form} is a +positive integer, it specifies a clock frequency and this function +returns an integer-pair timestamp @code{(@var{ticks} +. @var{form})}.@footnote{Currently a positive integer @var{form} +should be at least 65536 if the returned value is intended to be given +to standard functions expecting Lisp timestamps.} If @var{form} is +@code{t}, this function treats it as a positive integer suitable for +representing the timestamp; for example, it is treated as 1000000000 +if the platform timestamp has nanosecond resolution. If @var{form} is +@code{list}, this function returns an integer list @code{(@var{high} +@var{low} @var{micro} @var{pico})}. Although an omitted or @code{nil} +@var{form} currently acts like @code{list}, this is planned to change +in a future Emacs version, so callers requiring list timestamps should +pass @code{list} explicitly. + +As an obsolescent calling convention, this function can be given six +or more arguments. The first six arguments @var{second}, +@var{minute}, @var{hour}, @var{day}, @var{month}, and @var{year} +specify most of the components of a decoded time. If there are more +than six arguments the @emph{last} argument is used as @var{zone} and +any other extra arguments are ignored, so that @code{(apply +#\\='encode-time (decode-time ...))} works; otherwise @var{zone} defaults +to the current time zone rule (@pxref{Time Zone Rules}). The decoded +time's @var{dst} component is treated as if it was @minus{}1, and +@var{form} takes its default value. Year numbers less than 100 are not treated specially. If you want them to stand for years above 1900, or years above 2000, you must alter them yourself before you call @code{encode-time}. -The optional argument @var{zone} defaults to the current time zone rule. -@xref{Time Zone Rules}. - -If you pass more than seven arguments to @code{encode-time}, the first -six are used as @var{seconds} through @var{year}, the last argument is -used as @var{zone}, and the arguments in between are ignored. This -feature makes it possible to use the elements of a list returned by -@code{decode-time} as the arguments to @code{encode-time}, like this: +The @code{encode-time} function acts as a rough inverse to +@code{decode-time}. For example, you can pass the output of +the latter to the former as follows: @example -(apply 'encode-time (decode-time @dots{})) +(encode-time (decode-time @dots{})) @end example You can perform simple date arithmetic by using out-of-range values for -the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month} -arguments; for example, day 0 means the day preceding the given month. +@var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}; +for example, day 0 means the day preceding the given month. The operating system puts limits on the range of possible time values; if you try to encode a time that is out of range, an error results. @@ -1462,12 +1539,12 @@ on others, years as early as 1901 do work. @cindex formatting time values These functions convert time values to text in a string, and vice versa. -Time values include @code{nil}, numbers, and lists of two to four -integers (@pxref{Time of Day}). +Time values include @code{nil}, numbers, and Lisp timestamps +(@pxref{Time of Day}). @defun date-to-time string This function parses the time-string @var{string} and returns the -corresponding time value. The argument @var{string} should represent +corresponding Lisp timestamp. The argument @var{string} should represent a date-time, and should be in one of the forms recognized by @code{parse-time-string} (see below). This function assumes the GMT timezone if @var{string} lacks an explicit timezone information. @@ -1523,7 +1600,9 @@ This is a synonym for @samp{%m/%d/%y}. @item %e This stands for the day of month, blank-padded. @item %F -This stands for the ISO 8601 date format, i.e., @samp{"%Y-%m-%d"}. +This stands for the ISO 8601 date format, which is like +@samp{%+4Y-%m-%d} except that any flags or field width override the +@samp{+} and (after subtracting 6) the @samp{4}. @item %g This stands for the year corresponding to the ISO week within the century. @item %G @@ -1603,7 +1682,9 @@ This stands for a single @samp{%}. @end table One or more flag characters can appear immediately after the @samp{%}. -@samp{0} pads with zeros, @samp{_} pads with blanks, @samp{-} +@samp{0} pads with zeros, @samp{+} pads with zeros and also puts +@samp{+} before nonnegative year numbers with more than four digits, +@samp{_} pads with blanks, @samp{-} suppresses padding, @samp{^} upper-cases letters, and @samp{#} reverses the case of letters. @@ -1686,10 +1767,6 @@ You can also specify the field width by following the @samp{%} with a number; shorter numbers will be padded with blanks. An optional period before the width requests zero-padding instead. For example, @code{"%.3Y"} might produce @code{"004 years"}. - -@emph{Warning:} This function works only with values of @var{seconds} -that don't exceed @code{most-positive-fixnum} (@pxref{Integer Basics, -most-positive-fixnum}). @end defun @node Processor Run Time @@ -1714,10 +1791,8 @@ When called interactively, it prints the uptime in the echo area. @end deffn @defun get-internal-run-time -This function returns the processor run time used by Emacs as a list -of four integers: @code{(@var{sec-high} @var{sec-low} @var{microsec} -@var{picosec})}, using the same format as @code{current-time} -(@pxref{Time of Day}). +This function returns the processor run time used by Emacs, as a Lisp +timestamp (@pxref{Time of Day}). Note that the time returned by this function excludes the time Emacs was not using the processor, and if the Emacs process has several @@ -1742,26 +1817,36 @@ interactively, it prints the duration in the echo area. @cindex calendrical computations These functions perform calendrical computations using time values -(@pxref{Time of Day}). A value of @code{nil} for any of their +(@pxref{Time of Day}). As with any time value, a value of +@code{nil} for any of their time-value arguments stands for the current system time, and a single -integer number stands for the number of seconds since the epoch. +number stands for the number of seconds since the epoch. @defun time-less-p t1 t2 This returns @code{t} if time value @var{t1} is less than time value @var{t2}. +The result is @code{nil} if either argument is a NaN. +@end defun + +@defun time-equal-p t1 t2 +This returns @code{t} if @var{t1} and @var{t2} are equal time values. +The result is @code{nil} if either argument is a NaN. @end defun @defun time-subtract t1 t2 This returns the time difference @var{t1} @minus{} @var{t2} between -two time values, as a time value. If you need the difference in units +two time values, as a time value. However, the result is a float +if either argument is a float infinity or NaN@. +If you need the difference in units of elapsed seconds, use @code{float-time} (@pxref{Time of Day, float-time}) to convert the result into seconds. @end defun @defun time-add t1 t2 This returns the sum of two time values, as a time value. +However, the result is a float if either argument is a float infinity or NaN@. One argument should represent a time difference rather than a point in time, -either as a list or as a single number of elapsed seconds. +as a time value that is often just a single number of elapsed seconds. Here is how to add a number of seconds to a time value: @example @@ -2004,8 +2089,7 @@ the idleness time, as described below. @defun current-idle-time If Emacs is idle, this function returns the length of time Emacs has -been idle, as a list of four integers: @code{(@var{sec-high} -@var{sec-low} @var{microsec} @var{picosec})}, using the same format as +been idle, using the same format as @code{current-time} (@pxref{Time of Day}). When Emacs is not idle, @code{current-idle-time} returns @code{nil}. @@ -2113,7 +2197,7 @@ is the character Emacs currently uses for quitting, usually @kbd{C-g}. @subsection Recording Input @cindex recording input -@defun recent-keys +@defun recent-keys &optional include-cmds This function returns a vector containing the last 300 input events from the keyboard or mouse. All input events are included, whether or not they were used as parts of key sequences. Thus, you always get the last @@ -2121,6 +2205,11 @@ they were used as parts of key sequences. Thus, you always get the last (These are excluded because they are less interesting for debugging; it should be enough to see the events that invoked the macros.) +If @var{include-cmds} is non-@code{nil}, complete key sequences in the +result vector are interleaved with pseudo-events of the form +@code{(nil . @var{COMMAND})}, where @var{COMMAND} is the binding of +the key sequence (@pxref{Command Overview}). + A call to @code{clear-this-command-keys} (@pxref{Command Loop Info}) causes this function to return an empty vector immediately afterward. @end defun diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi index 39bdc01a75c..7244efbd8f7 100644 --- a/doc/lispref/package.texi +++ b/doc/lispref/package.texi @@ -22,6 +22,7 @@ user-level features of the packaging system. * Simple Packages:: How to package a single .el file. * Multi-file Packages:: How to package multiple files. * Package Archives:: Maintaining package archives. +* Archive Web Server:: Interfacing to an archive web server. @end menu @node Packaging Basics @@ -105,24 +106,36 @@ adds the package's content directory to @code{load-path}, and evaluates the autoload definitions in @file{@var{name}-autoloads.el}. Whenever Emacs starts up, it automatically calls the function -@code{package-initialize} to load installed packages. This is done -after loading the init file and abbrev file (if any) and before -running @code{after-init-hook} (@pxref{Startup Summary}). Automatic -package loading is disabled if the user option -@code{package-enable-at-startup} is @code{nil}. +@code{package-activate-all} to make installed packages available to the +current session. This is done after loading the early init file, but +before loading the regular init file (@pxref{Startup Summary}). +Packages are not automatically made available if the user option +@code{package-enable-at-startup} is set to @code{nil} in the early +init file. + +@defun package-activate-all +This function makes the packages available to the current session. +The user option @code{package-load-list} specifies which packages to +make available; by default, all installed packages are made available. +If called during startup, this function also sets +@code{package-enable-at-startup} to @code{nil}, to avoid accidentally +evaluating package autoloads more than once. @xref{Package +Installation,,, emacs, The GNU Emacs Manual}. + +In most cases, you should not need to call @code{package-activate-all}, +as this is done automatically during startup. Simply make sure to put +any code that should run before @code{package-activate-all} in the early +init file, and any code that should run after it in the primary init +file (@pxref{Init File,,, emacs, The GNU Emacs Manual}). +@end defun @deffn Command package-initialize &optional no-activate This function initializes Emacs' internal record of which packages are -installed, and loads them. The user option @code{package-load-list} -specifies which packages to load; by default, all installed packages -are loaded. If called during startup, this function also sets -@code{package-enable-at-startup} to @code{nil}, to avoid accidentally -loading the packages twice. @xref{Package Installation,,, emacs, The -GNU Emacs Manual}. +installed, and then calls @code{package-activate-all}. The optional argument @var{no-activate}, if non-@code{nil}, causes Emacs to update its record of installed packages without actually -loading them; it is for internal use only. +making them available. @end deffn @node Simple Packages @@ -237,7 +250,8 @@ dependency's version (a string). @end defun If the content directory contains a file named @file{README}, this -file is used as the long description. +file is used as the long description (overriding any @samp{;;; +Commentary:} section). If the content directory contains a file named @file{dir}, this is assumed to be an Info directory file made with @command{install-info}. @@ -299,8 +313,8 @@ access. Such local archives are mainly useful for testing. A package archive is simply a directory in which the package files, and associated files, are stored. If you want the archive to be -reachable via HTTP, this directory must be accessible to a web server. -How to accomplish this is beyond the scope of this manual. +reachable via HTTP, this directory must be accessible to a web server; +@xref{Archive Web Server}. A convenient way to set up and update a package archive is via the @code{package-x} library. This is included with Emacs, but not loaded @@ -381,3 +395,28 @@ manual. For more information on cryptographic keys and signing, @pxref{Top,, GnuPG, gnupg, The GNU Privacy Guard Manual}. Emacs comes with an interface to GNU Privacy Guard, @pxref{Top,, EasyPG, epa, Emacs EasyPG Assistant Manual}. + +@node Archive Web Server +@section Interfacing to an archive web server +@cindex archive web server + +A web server providing access to a package archive must support the +following queries: + +@table @asis +@item archive-contents +Return a lisp form describing the archive contents. The form is a list +of 'package-desc' structures (see @file{package.el}), except the first +element of the list is the archive version. + +@item <package name>-readme.txt +Return the long description of the package. + +@item <file name>.sig +Return the signature for the file. + +@item <file name> +Return the file. This will be the tarball for a multi-file +package, or the single file for a simple package. + +@end table diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index a93f4db4282..ebc31c597e6 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -177,6 +177,14 @@ before starting Emacs. Trying to modify @code{exec-path} independently of @env{PATH} can lead to confusing results. @end defopt +@defun exec-path +This function is an extension of the variable @code{exec-path}. If +@code{default-directory} indicates a remote directory, this function +returns a list of directories used for searching programs on the +respective remote host. In case of a local @code{default-directory}, +the function returns just the value of the variable @code{exec-path}. +@end defun + @node Shell Arguments @section Shell Arguments @cindex arguments for shell commands @@ -415,27 +423,27 @@ be found in the definition of the @code{insert-directory} function: @defun process-file program &optional infile buffer display &rest args This function processes files synchronously in a separate process. It -is similar to @code{call-process}, but may invoke a file handler based -on the value of the variable @code{default-directory}, which specifies -the current working directory of the subprocess. +is similar to @code{call-process}, but may invoke a file name handler +based on the value of the variable @code{default-directory}, which +specifies the current working directory of the subprocess. The arguments are handled in almost the same way as for @code{call-process}, with the following differences: -Some file handlers may not support all combinations and forms of the +Some file name handlers may not support all combinations and forms of the arguments @var{infile}, @var{buffer}, and @var{display}. For example, -some file handlers might behave as if @var{display} were @code{nil}, +some file name handlers might behave as if @var{display} were @code{nil}, regardless of the value actually passed. As another example, some -file handlers might not support separating standard output and error +file name handlers might not support separating standard output and error output by way of the @var{buffer} argument. -If a file handler is invoked, it determines the program to run based +If a file name handler is invoked, it determines the program to run based on the first argument @var{program}. For instance, suppose that a handler for remote files is invoked. Then the path that is used for searching for the program might be different from @code{exec-path}. -The second argument @var{infile} may invoke a file handler. The file -handler could be different from the handler chosen for the +The second argument @var{infile} may invoke a file name handler. The file +name handler could be different from the handler chosen for the @code{process-file} function itself. (For example, @code{default-directory} could be on one remote host, and @var{infile} on a different remote host. Or @code{default-directory} @@ -462,7 +470,7 @@ remote files. By default, this variable is always set to @code{t}, meaning that a call of @code{process-file} could potentially change any file on a -remote host. When set to @code{nil}, a file handler could optimize +remote host. When set to @code{nil}, a file name handler could optimize its behavior with respect to remote file attribute caching. You should only ever change this variable with a let-binding; never @@ -670,8 +678,11 @@ Initialize the process query flag to @var{query-flag}. @xref{Query Before Exit}. @item :stop @var{stopped} -If @var{stopped} is non-@code{nil}, start the process in the -stopped state. +If provided, @var{stopped} must be @code{nil}; it is an error to use +any non-@code{nil} value. The @code{:stop} key is ignored otherwise +and is retained for compatibility with other process types such as +pipe processes. Asynchronous subprocesses never start in the stopped +state. @item :filter @var{filter} Initialize the process filter to @var{filter}. If not specified, a @@ -686,7 +697,28 @@ a default sentinel will be used, which can be overridden later. @item :stderr @var{stderr} Associate @var{stderr} with the standard error of the process. A non-@code{nil} value should be either a buffer or a pipe process -created with @code{make-pipe-process}, described below. +created with @code{make-pipe-process}, described below. If +@var{stderr} is @code{nil}, standard error is mixed with standard +output, and both are sent to @var{buffer} or @var{filter}. + +@cindex standard error process +If @var{stderr} is a buffer, Emacs will create a pipe process, the +@dfn{standard error process}. This process will have the default +filter (@pxref{Filter Functions}), sentinel (@pxref{Sentinels}), and +coding systems (@pxref{Default Coding Systems}). On the other hand, +it will use @var{query-flag} as its query-on-exit flag (@pxref{Query +Before Exit}). It will be associated with the @var{stderr} buffer +(@pxref{Process Buffers}) and send its output (which is the standard +error of the main process) there. + +If @var{stderr} is a pipe process, Emacs will use it as standard error +process for the new process. + +@item :file-handler @var{file-handler} +If @var{file-handler} is non-@code{nil}, then look for a file name +handler for the current buffer's @code{default-directory}, and invoke +that file name handler to make the process. If there is no such +handler, proceed as if @var{file-handler} were @code{nil}. @end table The original argument list, modified with the actual connection @@ -694,9 +726,22 @@ information, is available via the @code{process-contact} function. The current working directory of the subprocess is set to the current buffer's value of @code{default-directory} if that is local (as -determined by `unhandled-file-name-directory'), or "~" otherwise. If -you want to run a process in a remote directory use -@code{start-file-process}. +determined by @code{unhandled-file-name-directory}), or @file{~} +otherwise. If you want to run a process in a remote directory, pass +@code{:file-handler t} to @code{make-process}. In that case, the +current working directory is the local name component of +@code{default-directory} (as determined by @code{file-local-name}). + +Depending on the implementation of the file name handler, it might not +be possible to apply @var{filter} or @var{sentinel} to the resulting +process object. The @code{:stderr} argument cannot be a pipe process, +file name handlers do not support pipe processes for this. A buffer +as @code{:stderr} argument is accepted, its contents is shown without +the use of pipe processes. @xref{Filter Functions}, @ref{Sentinels}, +and @ref{Accepting Output}. + +Some file name handlers may not support @code{make-process}. In such +cases, this function does nothing and returns @code{nil}. @end defun @defun make-pipe-process &rest args @@ -812,7 +857,7 @@ subprocess running @var{program} in it, and returns its process object. The difference from @code{start-process} is that this function may -invoke a file handler based on the value of @code{default-directory}. +invoke a file name handler based on the value of @code{default-directory}. This handler ought to run @var{program}, perhaps on the local host, perhaps on a remote host that corresponds to @code{default-directory}. In the latter case, the local part of @code{default-directory} becomes @@ -826,13 +871,13 @@ names relative to @code{default-directory}, or to names that identify the files locally on the remote host, by running them through @code{file-local-name}. -Depending on the implementation of the file handler, it might not be +Depending on the implementation of the file name handler, it might not be possible to apply @code{process-filter} or @code{process-sentinel} to the resulting process object. @xref{Filter Functions}, and @ref{Sentinels}. @c FIXME Can we find a better example (i.e., a more modern function @c that is actually documented). -Some file handlers may not support @code{start-file-process} (for +Some file name handlers may not support @code{start-file-process} (for example the function @code{ange-ftp-hook-function}). In such cases, this function does nothing and returns @code{nil}. @end defun @@ -1769,7 +1814,7 @@ system comes from @code{coding-system-for-read}, if that is non-@code{nil}; or else from the defaulting mechanism (@pxref{Default Coding Systems}). If the text output by a process contains null bytes, Emacs by default uses @code{no-conversion} for it; see -@ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to +@ref{Lisp and Coding Systems, inhibit-nul-byte-detection}, for how to control this behavior. @strong{Warning:} Coding systems such as @code{undecided}, which @@ -1859,6 +1904,22 @@ like this: (while (accept-process-output process)) @end example +If you have passed a non-@code{nil} @var{stderr} to +@code{make-process}, it will have a standard error process. +@xref{Asynchronous Processes}. In that case, waiting for process +output from the main process doesn't wait for output from the standard +error process. To make sure you have received both all of standard +output and all of standard error from a process, use the following +code: + +@example +(while (accept-process-output process)) +(while (accept-process-output stderr-process)) +@end example + +Reading pending standard error from a process running on a remote host +is not possible this way. + @node Processes and Threads @subsection Processes and Threads @cindex processes, threads @@ -2104,8 +2165,6 @@ attribute and @var{value} is the value of that attribute. The various attribute @var{key}s that this function can return are listed below. Not all platforms support all of these attributes; if an attribute is not supported, its association will not appear in the returned alist. -Values that are numbers can be either integer or floating point, -depending on the magnitude of the value. @table @code @item euid @@ -2189,19 +2248,17 @@ faults for all the child processes of the given process. @item utime Time spent by the process in the user context, for running the -application's code. The corresponding @var{value} is in the -@w{@code{(@var{high} @var{low} @var{microsec} @var{picosec})}} format, the same -format used by functions @code{current-time} (@pxref{Time of Day, -current-time}) and @code{file-attributes} (@pxref{File Attributes}). +application's code. The corresponding @var{value} is a Lisp +timestamp (@pxref{Time of Day}). @item stime Time spent by the process in the system (kernel) context, for -processing system calls. The corresponding @var{value} is in the same -format as for @code{utime}. +processing system calls. The corresponding @var{value} is a Lisp +timestamp. @item time The sum of @code{utime} and @code{stime}. The corresponding -@var{value} is in the same format as for @code{utime}. +@var{value} is a Lisp timestamp. @item cutime @itemx cstime @@ -2220,13 +2277,10 @@ nice values get scheduled more favorably.) The number of threads in the process. @item start -The time when the process was started, in the same -@code{(@var{high} @var{low} @var{microsec} @var{picosec})} format used by -@code{file-attributes} and @code{current-time}. +The time when the process was started, as a Lisp timestamp. @item etime -The time elapsed since the process started, in the format @code{(@var{high} -@var{low} @var{microsec} @var{picosec})}. +The time elapsed since the process started, as a Lisp timestamp. @item vsize The virtual memory size of the process, measured in kilobytes. @@ -2627,7 +2681,9 @@ Specify the host to connect to. @var{host} should be a host name or Internet address, as a string, or the symbol @code{local} to specify the local host. If you specify @var{host} for a server, it must specify a valid address for the local host, and only clients -connecting to that address will be accepted. +connecting to that address will be accepted. When using @code{local}, +by default IPv4 will be used, specify a @var{family} of @code{ipv6} to +override this. @item :service @var{service} @var{service} specifies a port number to connect to; or, for a server, @@ -2754,8 +2810,7 @@ Initialize the process filter to @var{filter}. @item :filter-multibyte @var{multibyte} If @var{multibyte} is non-@code{nil}, strings given to the process -filter are multibyte, otherwise they are unibyte. The default is the -default value of @code{enable-multibyte-characters}. +filter are multibyte, otherwise they are unibyte. The default is @code{t}. @item :sentinel @var{sentinel} Initialize the process sentinel to @var{sentinel}. @@ -3158,7 +3213,6 @@ direction is also known as @dfn{serializing} or @dfn{packing}. @menu * Bindat Spec:: Describing data layout. * Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! @end menu @node Bindat Spec @@ -3401,132 +3455,3 @@ dotted notation. @result{} "127.0.0.1" @end example @end defun - -@node Bindat Examples -@subsection Examples of Byte Unpacking and Packing -@c FIXME? This seems a very long example for something that is not used -@c very often. As of 25.2, gdb-mi.el is the only user of bindat.el in Emacs. -@c Maybe one or both of these examples should just be moved to the -@c commentary of bindat.el. - - Here are two complete examples that use bindat.el. -The first shows simple byte packing: - -@lisp -(require 'bindat) - -(defun rfc868-payload () - (bindat-pack - '((now-hi u16) - (now-lo u16)) - ;; Emacs uses Unix epoch, while RFC868 epoch - ;; is 1900-01-01 00:00:00, which is 2208988800 - ;; (or #x83aa7e80) seconds more. - (let ((now (time-add nil '(#x83aa #x7e80)))) - `((now-hi . ,(car now)) - (now-lo . ,(cadr now)))))) - -(let ((s (rfc868-payload))) - (list (multibyte-string-p s) - (mapconcat (lambda (byte) - (format "%02x" byte)) - s " ") - (current-time-string))) - @result{} (nil "dc 6d 17 01" "Fri Mar 10 13:13:53 2017") -@end lisp - -The following is an example of defining and unpacking a complex -structure. Consider the following C structures: - -@example -struct header @{ - unsigned long dest_ip; - unsigned long src_ip; - unsigned short dest_port; - unsigned short src_port; -@}; - -struct data @{ - unsigned char type; - unsigned char opcode; - unsigned short length; /* in network byte order */ - unsigned char id[8]; /* null-terminated string */ - unsigned char data[/* (length + 3) & ~3 */]; -@}; - -struct packet @{ - struct header header; - unsigned long counters[2]; /* in little endian order */ - unsigned char items; - unsigned char filler[3]; - struct data item[/* items */]; - -@}; -@end example - -The corresponding data layout specification is: - -@lisp -(setq header-spec - '((dest-ip ip) - (src-ip ip) - (dest-port u16) - (src-port u16))) - -(setq data-spec - '((type u8) - (opcode u8) - (length u16) ; network byte order - (id strz 8) - (data vec (length)) - (align 4))) - -(setq packet-spec - '((header struct header-spec) - (counters vec 2 u32r) ; little endian order - (items u8) - (fill 3) - (item repeat (items) - (struct data-spec)))) -@end lisp - -A binary data representation is: - -@lisp -(setq binary-data - [ 192 168 1 100 192 168 1 101 01 28 21 32 - 160 134 1 0 5 1 0 0 2 0 0 0 - 2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0 - 1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ]) -@end lisp - -The corresponding decoded structure is: - -@lisp -(setq decoded (bindat-unpack packet-spec binary-data)) - @result{} -((header - (dest-ip . [192 168 1 100]) - (src-ip . [192 168 1 101]) - (dest-port . 284) - (src-port . 5408)) - (counters . [100000 261]) - (items . 2) - (item ((data . [1 2 3 4 5]) - (id . "ABCDEF") - (length . 5) - (opcode . 3) - (type . 2)) - ((data . [6 7 8 9 10 11 12]) - (id . "BCDEFG") - (length . 7) - (opcode . 4) - (type . 1)))) -@end lisp - -An example of fetching data from this structure: - -@lisp -(bindat-get-field decoded 'item 1 'id) - @result{} "BCDEFG" -@end lisp diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index b182fae5955..33455114dac 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -395,20 +395,23 @@ or @samp{$}, @samp{%} or period. However, the ending character of one range should not be the starting point of another one; for example, @samp{[a-m-z]} should be avoided. +A character alternative can also specify named character classes +(@pxref{Char Classes}). This is a POSIX feature. For example, +@samp{[[:ascii:]]} matches any @acronym{ASCII} character. +Using a character class is equivalent to mentioning each of the +characters in that class; but the latter is not feasible in practice, +since some classes include thousands of different characters. +A character class should not appear as the lower or upper bound +of a range. + The usual regexp special characters are not special inside a character alternative. A completely different set of characters is -special inside character alternatives: @samp{]}, @samp{-} and @samp{^}. - -To include a @samp{]} in a character alternative, you must make it the -first character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. -To include a @samp{-}, write @samp{-} as the first or last character of -the character alternative, or as the upper bound of a range. Thus, @samp{[]-]} -matches both @samp{]} and @samp{-}. (As explained below, you cannot -use @samp{\]} to include a @samp{]} inside a character alternative, -since @samp{\} is not special there.) - -To include @samp{^} in a character alternative, put it anywhere but at -the beginning. +special: @samp{]}, @samp{-} and @samp{^}. +To include @samp{]} in a character alternative, put it at the +beginning. To include @samp{^}, put it anywhere but at the beginning. +To include @samp{-}, put it at the end. Thus, @samp{[]^-]} matches +all three of these special characters. You cannot use @samp{\} to +escape these three characters, since @samp{\} is not special here. The following aspects of ranges are specific to Emacs, in that POSIX allows but does not require this behavior and programs other than @@ -426,33 +429,52 @@ of its bounds, so that @samp{[a-z]} matches only ASCII letters, even outside the C or POSIX locale. @item -As a special case, if either bound of a range is a raw 8-bit byte, the -other bound should be a unibyte character, and the range matches only -unibyte characters. - -@item If the lower bound of a range is greater than its upper bound, the -range is empty and represents no characters. Thus, @samp{[b-a]} -always fails to match, and @samp{[^b-a]} matches any character, -including newline. However, the lower bound should be at most one -greater than the upper bound; for example, @samp{[c-a]} should be -avoided. +range is empty and represents no characters. Thus, @samp{[z-a]} +always fails to match, and @samp{[^z-a]} matches any character, +including newline. However, a reversed range should always be from +the letter @samp{z} to the letter @samp{a} to make it clear that it is +not a typo; for example, @samp{[+-*/]} should be avoided, because it +matches only @samp{/} rather than the likely-intended four characters. @end enumerate -A character alternative can also specify named character classes -(@pxref{Char Classes}). This is a POSIX feature. For example, -@samp{[[:ascii:]]} matches any @acronym{ASCII} character. -Using a character class is equivalent to mentioning each of the -characters in that class; but the latter is not feasible in practice, -since some classes include thousands of different characters. -A character class should not appear as the lower or upper bound -of a range. +Some kinds of character alternatives are not the best style even +though they have a well-defined meaning in Emacs. They include: + +@enumerate +@item +Although a range's bound can be almost any character, it is better +style to stay within natural sequences of ASCII letters and digits +because most people have not memorized character code tables. +For example, @samp{[.-9]} is less clear than @samp{[./0-9]}, +and @samp{[`-~]} is less clear than @samp{[`a-z@{|@}~]}. +Unicode character escapes can help here; for example, for most programmers +@samp{[ก-ฺ฿-๛]} is less clear than @samp{[\u0E01-\u0E3A\u0E3F-\u0E5B]}. + +@item +Although a character alternative can include duplicates, it is better +style to avoid them. For example, @samp{[XYa-yYb-zX]} is less clear +than @samp{[XYa-z]}. + +@item +Although a range can denote just one, two, or three characters, it +is simpler to list the characters. For example, +@samp{[a-a0]} is less clear than @samp{[a0]}, @samp{[i-j]} is less clear +than @samp{[ij]}, and @samp{[i-k]} is less clear than @samp{[ijk]}. + +@item +Although a @samp{-} can appear at the beginning of a character +alternative or as the upper bound of a range, it is better style to +put @samp{-} by itself at the end of a character alternative. For +example, although @samp{[-a-z]} is valid, @samp{[a-z-]} is better +style; and although @samp{[*--]} is valid, @samp{[*+,-]} is clearer. +@end enumerate @item @samp{[^ @dots{} ]} @cindex @samp{^} in regexp @samp{[^} begins a @dfn{complemented character alternative}. This matches any character except the ones specified. Thus, -@samp{[^a-z0-9A-Z]} matches all characters @emph{except} letters and +@samp{[^a-z0-9A-Z]} matches all characters @emph{except} ASCII letters and digits. @samp{^} is not special in a character alternative unless it is the first @@ -575,7 +597,7 @@ tabs, and other characters whose Unicode @samp{general-category} property (@pxref{Character Properties}) indicates they are spacing separators. @item [:cntrl:] -This matches any @acronym{ASCII} control character. +This matches any character whose code is in the range 0--31. @item [:digit:] This matches @samp{0} through @samp{9}. Thus, @samp{[-+[:digit:]]} matches any digit, as well as @samp{+} and @samp{-}. @@ -658,10 +680,10 @@ is omitted, the minimum is 0; if @var{n} is omitted, there is no maximum. For both forms, @var{m} and @var{n}, if specified, may be no larger than @ifnottex -2**15 @minus{} 1 +2**16 @minus{} 1 @end ifnottex @tex -@math{2^{15}-1} +@math{2^{16}-1} @end tex . @@ -966,7 +988,7 @@ whitespace: @end defun @cindex optimize regexp -@defun regexp-opt strings &optional paren +@defun regexp-opt strings &optional paren keep-order This function returns an efficient regular expression that will match any of the strings in the list @var{strings}. This is useful when you need to make matching or searching as fast as possible---for example, @@ -976,6 +998,9 @@ possible. A hand-tuned regular expression can sometimes be slightly more efficient, but is almost never worth the effort.}. @c E.g., see https://debbugs.gnu.org/2816 +If @var{strings} is the empty list, the return value is a regexp that +never matches anything. + The optional argument @var{paren} can be any of the following: @table @asis @@ -1001,8 +1026,15 @@ if it is necessary to ensure that a postfix operator appended to it will apply to the whole expression. @end table -The resulting regexp of @code{regexp-opt} is equivalent to but usually -more efficient than that of a simplified version: +The optional argument @var{keep-order}, if @code{nil} or omitted, +allows the returned regexp to match the strings in any order. If +non-@code{nil}, the match is guaranteed to be performed in the order +given, as if the strings were made into a regexp by joining them with +the @samp{\|} operator. + +Up to reordering, the resulting regexp of @code{regexp-opt} is +equivalent to but usually more efficient than that of a simplified +version: @example (defun simplified-regexp-opt (strings &optional paren) @@ -1038,6 +1070,13 @@ list of characters @var{chars}. @c Internal functions: regexp-opt-group +@defvar regexp-unmatchable +This variable contains a regexp that is guaranteed not to match any +string at all. It is particularly useful as default value for +variables that may be set to a pattern that actually matches +something. +@end defvar + @node Regexp Search @section Regular Expression Searching @cindex regular expression searching diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index bf2c9c8a7d6..4b67a5f9f1a 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -782,10 +782,11 @@ before being sorted. @var{function} is a function of one argument. @end defun -@defun seq-contains sequence elt &optional function - This function returns the first element in @var{sequence} that is equal to -@var{elt}. If the optional argument @var{function} is non-@code{nil}, -it is a function of two arguments to use instead of the default @code{equal}. +@defun seq-contains-p sequence elt &optional function + This function returns non-@code{nil} if at least one element in +@var{sequence} is equal to @var{elt}. If the optional argument +@var{function} is non-@code{nil}, it is a function of two arguments to +use instead of the default @code{equal}. @example @group @@ -1308,9 +1309,9 @@ not evaluate or even examine the elements of the vector. @example @group (setq avector [1 two '(three) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] + @result{} [1 two '(three) "four" [five]] (eval avector) - @result{} [1 two (quote (three)) "four" [five]] + @result{} [1 two '(three) "four" [five]] (eq avector (eval avector)) @result{} t @end group @@ -1400,9 +1401,9 @@ list with the same elements: @example @group (setq avector [1 two (quote (three)) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] + @result{} [1 two '(three) "four" [five]] (append avector nil) - @result{} (1 two (quote (three)) "four" [five]) + @result{} (1 two '(three) "four" [five]) @end group @end example @@ -1777,6 +1778,11 @@ If the ring is full, this function removes the newest element to make room for the inserted element. @end defun +@defun ring-resize ring size +Set the size of @var{ring} to @var{size}. If the new size is smaller, +then the oldest items in the ring are discarded. +@end defun + @cindex fifo data structure If you are careful not to exceed the ring size, you can use the ring as a first-in-first-out queue. For example: diff --git a/doc/lispref/spellfile b/doc/lispref/spellfile index 590d356d2d4..45a122d26ac 100644 --- a/doc/lispref/spellfile +++ b/doc/lispref/spellfile @@ -10,29 +10,22 @@ Beverly Boyes Brian CL -CSWKg Carl Carroll Chris Cleanups -DEC -DStandard Dan Dired's Disassembly Duff -EMAC EMACSLOADPATH Eckelkamp Edward Eirik -Emacses Eric Erlebacher Fcar Fcdr -Fcons -Fcoordinates Feval Frazzle Frederick @@ -42,14 +35,12 @@ Gentlemen HAL HATTED HS -HU Hanchrow Hartzell Hess Hewlett IBM ISBN -Impl Interning Ithought J's @@ -65,13 +56,9 @@ Kirman Knighten Korz Krawitz -LTsHm LaLiberte -LaTeX Lammens -Local' MAC -MONIES MSS Maclisp Magill @@ -80,69 +67,44 @@ Matthew Minibuf Misc Miscellany -Mocklisp Montanaro Myers NFS Nathan -Nope OS -OSITIONS Oct -Ovwrt -PURESIZE Packard -Qlistp Qnil -RMAIL Raul Resizing Robbins Rockwell -SCO SIGCONT SIGHUP SIGINT SIGKILL SIGQUIT SIGTSTP -SLOAD -Scoordinates -Set' Setcar Setcdr Shinichirou Snarf Sor SourceFile -Stops' Subprocess Sugou -Sunview Suominen -T's TCP ThXs Tharp -Thu Trost -UCB UNEVALLED -UNGCPRO -UniPlus -UniSoft's -VMS -Vip -Void' Warren Welty Wethought Wilding Worley Wright -XDVI -XFASTINT -XINT XWINDOW Xs Yo @@ -156,22 +118,13 @@ abc abcdefg abcxyz abd -above' abracadabra -address' -after' alist alists -anchored' -and' ar aref -arg'th -argdecl arith arrayp -arrow' -asa asdZasfd asdf asdfasfd @@ -181,28 +134,22 @@ assq at' aug autoload -automatic' -automatically' avector bBuffer bFrobnicate ba -back' bananana barfoo barx bballs -before' beforep bfoo -bil binding's bish bobp bolp bottommost boundp -brief' buf buffer' bufferp @@ -215,11 +162,8 @@ cadr callable cbreak ce -cell' cells' cf -chaprm -character' childp chistory ck @@ -230,31 +174,22 @@ cond conses consing consp -constant' -contains' continuable -convert' copyleft -correct' counterintuitive cr creatable customize deactivate deactivated -deassigns -decrement' deffnx definition' defmacro defsubr deletable -deletion' delq depiction deselecting -destructive' -destructively' diffs ding directory' @@ -273,10 +208,8 @@ dribble dup ef efg -electric' elided elt -enablement endkeyfun endrecfun environment' @@ -286,27 +219,18 @@ eol eolp eq eqlsign -erminal erste etags eval evalled -evals evaluate' -excess' exec exitcode -expression' -extra' -fails' -fascist fboundp featurep -ff fg fi file' -filespec filesystems fillarray firstchar @@ -316,41 +240,27 @@ fixit fixup floatp fmakunbound -fns fo fol -folded' following' fooba foobaz foox -for' formfeed -forms' forw -found' frob -from' -front' fset fstab ftp fu garbles gc -gcpro -gd getenv -getprv gid -gnuemacs gp grep gtr -halves' hand' -hashes' -hd hexadecimal hf hfil @@ -359,16 +269,12 @@ horsechestnut hostname hpux hscroll -ibmapa ick id idiom ii -indrm inode -input' inputinput -inserting' integerp intermixed ints @@ -378,31 +284,21 @@ keymapp kill' killed' killp -kludge kolstad -language' lastchar lcl -ledit leif lessp level' lewis -library' -link' -lisplib -listexp loadable -loadst loadup logand logior lognot logxor -long' loop's lru -lrwxrwxrwx ls lsh m's @@ -412,43 +308,31 @@ malloc mapatoms mapconcat mapvar -mark' marker's markerp mathsurround -medit memq mh -mim mini minibuffer's minibuffers misalignment -misnamed mode's modename -modes' mods modtime -mqueue msg -multicharacter myfile nCount -nXExpression na name's natnump nb -nbBuffer nconc newdef newelt newname nextrecfun -nfsusr -ninett -nlines nlinks nlistp noconfirm @@ -456,7 +340,6 @@ nodigits noerror noforce nomessage -nominees nomsg nonblank nonconstant @@ -473,10 +356,7 @@ nonprinting nonselected nonsequentially nonvoid -nonwarranty nonwritable -noop -noprint norecord normal' noselect @@ -495,32 +375,19 @@ numberp nums obarray obarrays -object' oldbuf olddef oldname -oo -oops op -or' otl out' -over' -overful -overfullrule -overstrike -overstriking -overstruck p' paren -part' passwd -pe ped perverse pid plist -pnt pointer' pointm pos @@ -530,7 +397,6 @@ prepend prepended prepends pretty' -prin princ print' printenv @@ -538,9 +404,7 @@ printer' proc process' processp -programmer' prolog -protect' ps psf psychotherapy @@ -550,12 +414,9 @@ qu quux rassq reader' -readin rebind rec rechecking -recursively' -recycler' redo redrawing redraws @@ -563,10 +424,8 @@ redump reenabled reexposed reg -region' reindent reindents -reinitialization reinitialize reinitialized reinstall @@ -576,44 +435,30 @@ resized resizes reversibly reworded -rhetorical -right' ring' risky -rmailedit rms rplaca rplacd -rtu runnable rw -rwxrwxrwx sDescribe sans se -searching' -section' -seed' sequence' sequencep -setp setplist -setprv settable setuid sexp sexps -shape' shell's sideline -special' specpdl st -stanford startkeyfun str stringp -stty subcategories subcommands subexp @@ -627,104 +472,63 @@ subr' subroutine' subrp subrs -subwindows -sugar' -suid supersession -suspension' symbolp symlink syms syntactic tabname temacs -temporarily' tempvar tenths -termcap -termcaps -terminfo termscript -termtype terpri text' -textrm -textsl -texttt -than' -the' tildes time's -to' towards transportable txt -types' uid unbind unbinding unbinds -unchanged' unclutters undefine undefines underfull -undo's -unevaluated' unexec unexpand unhesitatingly uninterned -unisoft -unpaired unread unreadable unreading unsaved -untyped -ununderline up' uptime -usecount used' -user' userlock usg val varbind -varname varref vars varset vb vconcat vectorp -vfil -vi vn voidness -vrs -vt window' windowing windowp -wrapped' -xSpecify -xcoord xcssun -xemacs -xenix -xf -xfirst xoff xon xx xxxxx -xxxxxxxxx xy -xyz -ycoord yes' zA -zap zerop diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi index 5aa49c2e954..600639f244f 100644 --- a/doc/lispref/streams.texi +++ b/doc/lispref/streams.texi @@ -809,6 +809,21 @@ when the output stream is a unibyte buffer or a marker pointing into one. @end defvar +@defvar print-charset-text-property +This variable controls printing of `charset' text property on printing +a string. The value should be @code{nil}, @code{t}, or +@code{default}. + +If the value is @code{nil}, @code{charset} text properties are never +printed. If @code{t}, they are always printed. + +If the value is @code{default}, only print @code{charset} text +properties if there is an ``unexpected'' @code{charset} property. For +ascii characters, all charsets are considered ``expected''. +Otherwise, the expected @code{charset} property of a character is +given by @code{char-charset}. +@end defvar + @defvar print-length @cindex printing limits The value of this variable is the maximum number of elements to print in diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 8420527f858..521f163663d 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -121,7 +121,7 @@ character (i.e., an integer), @code{nil} otherwise. The following functions create strings, either from scratch, or by putting strings together, or by taking them apart. -@defun make-string count character +@defun make-string count character &optional multibyte This function returns a string made up of @var{count} repetitions of @var{character}. If @var{count} is negative, an error is signaled. @@ -132,6 +132,13 @@ This function returns a string made up of @var{count} repetitions of @result{} "" @end example + Normally, if @var{character} is an @acronym{ASCII} character, the +result is a unibyte string. But if the optional argument +@var{multibyte} is non-@code{nil}, the function will produce a +multibyte string instead. This is useful when you later need to +concatenate the result with non-@acronym{ASCII} strings or replace +some of its characters with non-@acronym{ASCII} characters. + Other functions to compare with this one include @code{make-vector} (@pxref{Vectors}) and @code{make-list} (@pxref{Building Lists}). @end defun @@ -666,6 +673,28 @@ of the two strings. The sign is negative if @var{string1} (or its specified portion) is less. @end defun +@cindex Levenshtein distance +@cindex distance between strings +@cindex edit distance between strings +@defun string-distance string1 string2 &optional bytecompare +This function returns the @dfn{Levenshtein distance} between the +source string @var{string1} and the target string @var{string2}. The +Levenshtein distance is the number of single-character +changes---deletions, insertions, or replacements---required to +transform the source string into the target string; it is one possible +definition of the @dfn{edit distance} between strings. + +Letter-case of the strings is significant for the computed distance, +but their text properties are ignored. If the optional argument +@var{bytecompare} is non-@code{nil}, the function calculates the +distance in terms of bytes instead of characters. The byte-wise +comparison uses the internal Emacs representation of characters, so it +will produce inaccurate results for multibyte strings that include raw +bytes (@pxref{Text Representations}); make the strings unibyte by +encoding them (@pxref{Explicit Encoding}) if you need accurate results +with raw bytes. +@end defun + @defun assoc-string key alist &optional case-fold This function works like @code{assoc}, except that @var{key} must be a string or symbol, and comparison is done using @code{compare-strings}. @@ -893,18 +922,25 @@ Functions}). Thus, strings are enclosed in @samp{"} characters, and @item %o @cindex integer to octal Replace the specification with the base-eight representation of an -unsigned integer. +integer. Negative integers are formatted in a platform-dependent +way. The object can also be a nonnegative floating-point +number that is formatted as an integer, dropping any fraction, if the +integer does not exceed machine limits. @item %d Replace the specification with the base-ten representation of a signed -integer. +integer. The object can also be a floating-point number that is +formatted as an integer, dropping any fraction. @item %x @itemx %X @cindex integer to hexadecimal Replace the specification with the base-sixteen representation of an -unsigned integer. @samp{%x} uses lower case and @samp{%X} uses upper -case. +integer. Negative integers are formatted in a platform-dependent +way. @samp{%x} uses lower case and @samp{%X} uses upper +case. The object can also be a nonnegative floating-point number that +is formatted as an integer, dropping any fraction, if the integer does +not exceed machine limits. @item %c Replace the specification with the character which is the value given. @@ -981,17 +1017,17 @@ numbered or unnumbered format specifications but not both, except that After the @samp{%} and any field number, you can put certain @dfn{flag characters}. - The flag @samp{+} inserts a plus sign before a positive number, so + The flag @samp{+} inserts a plus sign before a nonnegative number, so that it always has a sign. A space character as flag inserts a space -before a positive number. (Otherwise, positive numbers start with the -first digit.) These flags are useful for ensuring that positive -numbers and negative numbers use the same number of columns. They are +before a nonnegative number. (Otherwise, nonnegative numbers start with the +first digit.) These flags are useful for ensuring that nonnegative +and negative numbers use the same number of columns. They are ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if both flags are used, @samp{+} takes precedence. The flag @samp{#} specifies an alternate form which depends on the format in use. For @samp{%o}, it ensures that the result begins -with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes the result +with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes nonzero results with @samp{0x} or @samp{0X}. For @samp{%e} and @samp{%f}, the @samp{#} flag means include a decimal point even if the precision is zero. For @samp{%g}, it always includes a decimal point, and also @@ -1074,6 +1110,17 @@ shows only the first three characters of the representation for precision is what the local library functions of the @code{printf} family produce. +@cindex formatting numbers for rereading later + If you plan to use @code{read} later on the formatted string to +retrieve a copy of the formatted value, use a specification that lets +@code{read} reconstruct the value. To format numbers in this +reversible way you can use @samp{%s} and @samp{%S}, to format just +integers you can also use @samp{%d}, and to format just nonnegative +integers you can also use @samp{#x%x} and @samp{#o%o}. Other formats +may be problematic; for example, @samp{%d} and @samp{%g} can mishandle +NaNs and can lose precision and type, and @samp{#x%x} and @samp{#o%o} +can mishandle negative integers. @xref{Input Functions}. + @node Case Conversion @section Case Conversion in Lisp @cindex upper case diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi index 9ad4a133509..63d534dd134 100644 --- a/doc/lispref/syntax.texi +++ b/doc/lispref/syntax.texi @@ -882,6 +882,11 @@ The value is @code{nil} if @var{state} represents a parse which has arrived at a top level position. @end defun +@defun syntax-ppss-context state +Return @code{string} if @var{state} is a string and @code{comment} if +it's a comment. +@end defun + @node Low-Level Parsing @subsection Low-Level Parsing @@ -1013,13 +1018,13 @@ corresponds to each syntax flag. @item @i{Prefix} @tab @i{Flag} @tab @i{Prefix} @tab @i{Flag} @item -@samp{1} @tab @code{(lsh 1 16)} @tab @samp{p} @tab @code{(lsh 1 20)} +@samp{1} @tab @code{(ash 1 16)} @tab @samp{p} @tab @code{(ash 1 20)} @item -@samp{2} @tab @code{(lsh 1 17)} @tab @samp{b} @tab @code{(lsh 1 21)} +@samp{2} @tab @code{(ash 1 17)} @tab @samp{b} @tab @code{(ash 1 21)} @item -@samp{3} @tab @code{(lsh 1 18)} @tab @samp{n} @tab @code{(lsh 1 22)} +@samp{3} @tab @code{(ash 1 18)} @tab @samp{n} @tab @code{(ash 1 22)} @item -@samp{4} @tab @code{(lsh 1 19)} @tab @samp{c} @tab @code{(lsh 1 23)} +@samp{4} @tab @code{(ash 1 19)} @tab @samp{c} @tab @code{(ash 1 23)} @end multitable @defun string-to-syntax desc diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index f3d222b7083..c4fc5247a11 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -61,6 +61,8 @@ the character after point. * Checksum/Hash:: Computing cryptographic hashes. * GnuTLS Cryptography:: Cryptographic algorithms imported from GnuTLS. * Parsing HTML/XML:: Parsing HTML and XML. +* Parsing JSON:: Parsing and generating JSON values. +* JSONRPC:: JSON Remote Procedure Call protocol * Atomic Changes:: Installing several buffer changes atomically. * Change Hooks:: Supplying functions to be run when text is changed. @end menu @@ -498,14 +500,14 @@ after point. It leaves the mark after the inserted text. The value is @code{nil}. @end deffn -@deffn Command self-insert-command count +@deffn Command self-insert-command count &optional char @cindex character insertion @cindex self-insertion -This command inserts the last character typed; it does so @var{count} -times, before point, and returns @code{nil}. Most printing characters -are bound to this command. In routine use, @code{self-insert-command} -is the most frequently called function in Emacs, but programs rarely use -it except to install it on a keymap. +This command inserts the character @var{char} (the last character typed); +it does so @var{count} times, before point, and returns @code{nil}. +Most printing characters are bound to this command. In routine use, +@code{self-insert-command} is the most frequently called function in Emacs, +but programs rarely use it except to install it on a keymap. In an interactive call, @var{count} is the numeric prefix argument. @@ -721,12 +723,18 @@ You thought @end example @end deffn -@deffn Command delete-indentation &optional join-following-p +@deffn Command delete-indentation &optional join-following-p beg end This function joins the line point is on to the previous line, deleting any whitespace at the join and in some cases replacing it with one space. If @var{join-following-p} is non-@code{nil}, @code{delete-indentation} joins this line to the following line -instead. The function returns @code{nil}. +instead. Otherwise, if @var{beg} and @var{end} are non-@code{nil}, +this function joins all lines in the region they define. + +In an interactive call, @var{join-following-p} is the prefix argument, +and @var{beg} and @var{end} are, respectively, the start and end of +the region if it is active, else @code{nil}. The function returns +@code{nil}. If there is a fill prefix, and the second of the lines being joined starts with the prefix, then @code{delete-indentation} deletes the @@ -1325,9 +1333,8 @@ elements follow immediately after this element. @item (t . @var{time-flag}) This kind of element indicates that an unmodified buffer became -modified. A @var{time-flag} of the form -@code{(@var{sec-high} @var{sec-low} @var{microsec} -@var{picosec})} represents the visited file's modification time as of +modified. A @var{time-flag} that is a non-integer Lisp timestamp +represents the visited file's modification time as of when it was previously visited or saved, using the same format as @code{current-time}; see @ref{Time of Day}. A @var{time-flag} of 0 means the buffer does not correspond to any file; @@ -3186,6 +3193,95 @@ buffer to scan. Positions are relative to @var{object}. The default for @var{object} is the current buffer. @end defun +@defun text-property-search-forward prop &optional value predicate not-current +Search for the next region that has text property @var{prop} set to +@var{value} according to @var{predicate}. + +This function is modelled after @code{search-forward} and friends in +that it moves point, but it returns a structure that describes the +match instead of returning it in @code{match-beginning} and friends. + +If the text property can't be found, the function returns @code{nil}. +If it's found, point is placed at the end of the region that has this +text property match, and a @code{prop-match} structure is returned. + +@var{predicate} can either be @code{t} (which is a synonym for +@code{equal}), @code{nil} (which means ``not equal''), or a predicate +that will be called with two parameters: The first is @var{value}, and +the second is the value of the text property we're inspecting. + +If @var{not-current}, if point is in a region where we have a match, +then skip past that and find the next instance instead. + +The @code{prop-match} structure has the following accessors: +@code{prop-match-beginning} (the start of the match), +@code{prop-match-end} (the end of the match), and +@code{prop-match-value} (the value of @var{property} at the start of +the match). + +In the examples below, imagine that you're in a buffer that looks like +this: + +@example +This is a bold and here's bolditalic and this is the end. +@end example + +That is, the ``bold'' words are the @code{bold} face, and the +``italic'' word is in the @code{italic} face. + +With point at the start: + +@lisp +(while (setq match (text-property-search-forward 'face 'bold t)) + (push (buffer-substring (prop-match-beginning match) + (prop-match-end match)) + words)) +@end lisp + +This will pick out all the words that use the @code{bold} face. + +@lisp +(while (setq match (text-property-search-forward 'face nil t)) + (push (buffer-substring (prop-match-beginning match) + (prop-match-end match)) + words)) +@end lisp + +This will pick out all the bits that have no face properties, which +will result in the list @samp{("This is a " "and here's " "and this is +the end")} (only reversed, since we used @code{push}). + +@lisp +(while (setq match (text-property-search-forward 'face nil nil)) + (push (buffer-substring (prop-match-beginning match) + (prop-match-end match)) + words)) +@end lisp + +This will pick out all the regions where @code{face} is set to +something, but this is split up into where the properties change, so +the result here will be @samp{("bold" "bold" "italic")}. + +For a more realistic example where you might use this, consider that +you have a buffer where certain sections represent URLs, and these are +tagged with @code{shr-url}. + +@lisp +(while (setq match (text-property-search-forward 'shr-url nil nil)) + (push (prop-match-value match) urls)) +@end lisp + +This will give you a list of all those URLs. + +@end defun + +@defun text-property-search-backward prop &optional value predicate not-current +This is just like @code{text-property-search-backward}, but searches +backward instead. Point is placed at the beginning of the matched +region instead of the end, though. +@end defun + + @node Special Properties @subsection Properties with Special Meanings @@ -3237,6 +3333,17 @@ foreground or background color, similar to @code{(:foreground @var{color-name})} or @code{(:background @var{color-name})}. This form is supported for backward compatibility only, and should be avoided. + +@item +A cons cell of the form @w{@code{(:filtered @var{filter} +@var{face-spec})}}, that specifies the face given by @var{face-spec}, +but only if @var{filter} matches when the face is used for display. +The @var{face-spec} can use any of the forms mentioned above. The +@var{filter} should be of the form @w{@code{(:window @var{param} +@var{value})}}, which matches for windows whose parameter @var{param} +is @code{eq} to @var{value}. If the variable +@code{face-filters-always-match} is non-@code{nil}, all face filters +are deemed to have matched. @end itemize Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by @@ -3514,9 +3621,12 @@ Furthermore, insertion will not modify any existing character, so this hook will only be run when removing some characters, replacing them with others, or changing their text-properties. -If these functions modify the buffer, they should bind -@code{inhibit-modification-hooks} to @code{t} around doing so, to -avoid confusing the internal mechanism that calls these hooks. +Unlike with other similar hooks, when Emacs calls these functions, +@code{inhibit-modification-hooks} does @emph{not} get bound to +non-@code{nil}. If the functions modify the buffer, you should +consider binding this variable to non-@code{nil} to prevent any buffer +changes running the change hooks. Otherwise, you must be prepared for +recursive calls. @xref{Change Hooks}. Overlays also support the @code{modification-hooks} property, but the details are somewhat different (@pxref{Overlay Properties}). @@ -3532,6 +3642,13 @@ preceding character. These functions receive two arguments, the beginning and end of the inserted text. The functions are called @emph{after} the actual insertion takes place. +When these functions are called, @code{inhibit-modification-hooks} is +bound to non-@code{nil}. If the functions modify the buffer, you +might want to bind @code{inhibit-modification-hooks} to @code{nil}, so +as to cause the change hooks to run for these modifications. However, +doing this may call your own change hook recursively, so be sure to +prepare for that. + See also @ref{Change Hooks}, for other hooks that are called when you change text in a buffer. @@ -3619,6 +3736,12 @@ string to display, which is passed through The GNU Emacs Manual}) provides an example. @end defvar +@defvar face-filters-always-match +If this variable is non-@code{nil}, face filters that specify +attributes applied only when certain conditions are met will be deemed +to match always. +@end defvar + @node Format Properties @subsection Formatted Text Properties @@ -4331,22 +4454,59 @@ all markers unrelocated. You can use the following function to replace the text of one buffer with the text of another buffer: -@deffn Command replace-buffer-contents source +@deffn Command replace-buffer-contents source &optional max-secs max-costs This function replaces the accessible portion of the current buffer with the accessible portion of the buffer @var{source}. @var{source} may either be a buffer object or the name of a buffer. When @code{replace-buffer-contents} succeeds, the text of the accessible portion of the current buffer will be equal to the text of the -accessible portion of the @var{source} buffer. This function attempts -to keep point, markers, text properties, and overlays in the current -buffer intact. One potential case where this behavior is useful is -external code formatting programs: they typically write the -reformatted text into a temporary buffer or file, and using -@code{delete-region} and @code{insert-buffer-substring} would destroy -these properties. However, the latter combination is typically -faster. @xref{Deletion}, and @ref{Insertion}. +accessible portion of the @var{source} buffer. + +This function attempts to keep point, markers, text properties, and +overlays in the current buffer intact. One potential case where this +behavior is useful is external code formatting programs: they +typically write the reformatted text into a temporary buffer or file, +and using @code{delete-region} and @code{insert-buffer-substring} +would destroy these properties. However, the latter combination is +typically faster (@xref{Deletion}, and @ref{Insertion}). + +For its working, @code{replace-buffer-contents} needs to compare the +contents of the original buffer with that of @code{source} which is a +costly operation if the buffers are huge and there is a high number of +differences between them. In order to keep +@code{replace-buffer-contents}'s runtime in bounds, it has two +optional arguments. + +@code{max-secs} defines a hard boundary in terms of seconds. If given +and exceeded, it will fall back to @code{delete-region} and +@code{insert-buffer-substring}. + +@code{max-costs} defines the quality of the difference computation. +If the actual costs exceed this limit, heuristics are used to provide +a faster but suboptimal solution. The default value is 1000000. + +@code{replace-buffer-contents} returns t if a non-destructive +replacement could be performed. Otherwise, i.e., if @code{max-secs} +was exceeded, it returns nil. @end deffn +@defun replace-region-contents beg end replace-fn &optional max-secs max-costs +This function replaces the region between @code{beg} and @code{end} +using the given @code{replace-fn}. The function @code{replace-fn} is +run in the current buffer narrowed to the specified region and it +should return either a string or a buffer replacing the region. + +The replacement is performed using @code{replace-buffer-contents} (see +above) which also describes the @code{max-secs} and @code{max-costs} +arguments and the return value. + +Note: If the replacement is a string, it will be placed in a temporary +buffer so that @code{replace-buffer-contents} can operate on it. +Therefore, if you already have the replacement in a buffer, it makes +no sense to convert it to a string using @code{buffer-substring} or +similar. +@end defun + @node Decompression @section Dealing With Compressed Data @@ -4365,14 +4525,17 @@ This function returns non-@code{nil} if built-in zlib decompression is available. @end defun -@defun zlib-decompress-region start end +@defun zlib-decompress-region start end &optional allow-partial This function decompresses the region between @var{start} and @var{end}, using built-in zlib decompression. The region should contain data that were compressed with gzip or zlib. On success, the function replaces the contents of the region with the decompressed -data. On failure, the function leaves the region unchanged and -returns @code{nil}. This function can be called only in unibyte -buffers. +data. If @var{allow-partial} is @code{nil} or omitted, then on +failure, the function leaves the region unchanged and returns +@code{nil}. Otherwise, it returns the number of bytes that were not +decompressed and replaces the region text by whatever data was +successfully decompressed. This function can be called only in +unibyte buffers. @end defun @@ -4388,7 +4551,7 @@ Internet informational document describing a standard. RFCs are usually written by technical experts acting on their own initiative, and are traditionally written in a pragmatic, experience-driven manner. -}2045. This section describes the functions for +}2045 and also in RFC 4648. This section describes the functions for converting to and from this code. @deffn Command base64-encode-region beg end &optional no-line-break @@ -4405,6 +4568,16 @@ text, to avoid overlong lines. However, if the optional argument the output is just one long line. @end deffn +@deffn Command base64url-encode-region beg end &optional no-pad +This function is like @code{base64-encode-region}, but it implements +the URL variant of base 64 encoding, per RFC 4648, and it doesn't +insert newline characters into the encoded text, so the output is +just one long line. + +If the optional argument @var{no-pad} is non-@code{nil} then this +function doesn't generate the padding (@code{=}). +@end deffn + @defun base64-encode-string string &optional no-line-break This function converts the string @var{string} into base 64 code. It returns a string containing the encoded text. As for @@ -4417,20 +4590,36 @@ text, to avoid overlong lines. However, if the optional argument the result string is just one long line. @end defun -@deffn Command base64-decode-region beg end +@defun base64url-encode-string string &optional no-pad +Like @code{base64-encode-string}, but generates the URL variant of +base 64, and doesn't insert newline characters into the encoded text, +so the result is just one long line. + +If the optional argument @var{no-pad} is non-@code{nil} then this +function doesn't generate the padding. +@end defun + +@deffn Command base64-decode-region beg end &optional base64url This function converts the region from @var{beg} to @var{end} from base 64 code into the corresponding decoded text. It returns the length of the decoded text. The decoding functions ignore newline characters in the encoded text. + +If optional argument @var{base64url} is is non-@code{nil}, then padding +is optional, and the URL variant of base 64 encoding is used. @end deffn -@defun base64-decode-string string +@defun base64-decode-string string &optional base64url This function converts the string @var{string} from base 64 code into the corresponding decoded text. It returns a unibyte string containing the decoded text. The decoding functions ignore newline characters in the encoded text. + + +If optional argument @var{base64url} is is non-@code{nil}, then padding +is optional, and the URL variant of base 64 encoding is used. @end defun @node Checksum/Hash @@ -4531,9 +4720,9 @@ It should be somewhat more efficient on larger buffers than @cindex symmetric cipher @cindex cipher, symmetric -If compiled with GnuTLS, Emacs offers built-in cryptographic support. -Following the GnuTLS API terminology, the available tools are digests, -MACs, symmetric ciphers, and AEAD ciphers. + If compiled with GnuTLS, Emacs offers built-in cryptographic +support. Following the GnuTLS API terminology, the available tools +are digests, MACs, symmetric ciphers, and AEAD ciphers. The terms used herein, such as IV (Initialization Vector), require some familiarity with cryptography and will not be defined in detail. @@ -4551,7 +4740,7 @@ structure of the GnuTLS library. @cindex format of gnutls cryptography inputs @cindex gnutls cryptography inputs format -The inputs to GnuTLS cryptographic functions can be specified in + The inputs to GnuTLS cryptographic functions can be specified in several ways, both as primitive Emacs Lisp types or as lists. The list form is currently similar to how @code{md5} and @@ -4718,8 +4907,15 @@ IV used. @section Parsing HTML and XML @cindex parsing html -When Emacs is compiled with libxml2 support, the following functions -are available to parse HTML or XML text into Lisp object trees. + Emacs can be compiled with built-in libxml2 support. + +@defun libxml-available-p +This function returns non-@code{nil} if built-in libxml2 support is +available in this Emacs session. +@end defun + +When libxml2 support is available, the following functions can be used +to parse HTML or XML text into Lisp object trees. @defun libxml-parse-html-region start end &optional base-url discard-comments This function parses the text between @var{start} and @var{end} as @@ -4731,7 +4927,10 @@ The optional argument @var{base-url}, if non-@code{nil}, should be a string specifying the base URL for relative URLs occurring in links. If the optional argument @var{discard-comments} is non-@code{nil}, -then the parse tree is created without any comments. +any top-level comment is discarded. (This argument is obsolete and +will be removed in future Emacs versions. To remove comments, use the +@code{xml-remove-comments} utility function on the data before you +call the parsing function.) In the parse tree, each HTML node is represented by a list in which the first element is a symbol representing the node name, the second @@ -4786,9 +4985,9 @@ about syntax). @cindex DOM @cindex Document Object Model -The @acronym{DOM} returned by @code{libxml-parse-html-region} (and the -other @acronym{XML} parsing functions) is a tree structure where each -node has a node name (called a @dfn{tag}), and optional key/value + The @acronym{DOM} returned by @code{libxml-parse-html-region} (and +the other @acronym{XML} parsing functions) is a tree structure where +each node has a node name (called a @dfn{tag}), and optional key/value @dfn{attribute} list, and then a list of @dfn{child nodes}. The child nodes are either strings or @acronym{DOM} objects. @@ -4906,6 +5105,350 @@ textual nodes that just contain white-space. @end table +@node Parsing JSON +@section Parsing and generating JSON values +@cindex JSON +@cindex JavaScript Object Notation + + When Emacs is compiled with @acronym{JSON} (@dfn{JavaScript Object +Notation}) support, it provides several functions to convert +between Lisp objects and JSON values. Any JSON value can be converted +to a Lisp object, but not vice versa. Specifically: + +@itemize +@item +JSON uses three keywords: @code{true}, @code{null}, @code{false}. +@code{true} is represented by the symbol @code{t}. By default, the +remaining two are represented, respectively, by the symbols +@code{:null} and @code{:false}. + +@item +JSON only has floating-point numbers. They can represent both Lisp +integers and Lisp floating-point numbers. + +@item +JSON strings are always Unicode strings encoded in UTF-8. Lisp +strings can contain non-Unicode characters. + +@item +JSON has only one sequence type, the array. JSON arrays are +represented using Lisp vectors. + +@item +JSON has only one map type, the object. JSON objects are represented +using Lisp hashtables, alists or plists. When an alist or plist +contains several elements with the same key, Emacs uses only the first +element for serialization, in accordance with the behavior of +@code{assq}. +@end itemize + +@noindent +Note that @code{nil}, being both a valid alist and a valid plist, +represents @code{@{@}}, the empty JSON object; not @code{null}, +@code{false}, or an empty array, all of which are different JSON +values. + + If some Lisp object can't be represented in JSON, the serialization +functions will signal an error of type @code{wrong-type-argument}. +The parsing functions can also signal the following errors: + +@table @code +@item json-end-of-file +Signaled when encountering a premature end of the input text. + +@item json-trailing-content +Signaled when encountering unexpected input after the first JSON +object parsed. + +@item json-parse-error +Signaled when encountering invalid JSON syntax. +@end table + + Only top-level values (arrays and objects) can be serialized to +JSON. The subobjects within these top-level values can be of any +type. Likewise, the parsing functions will only return vectors, +hashtables, alists, and plists. + +@defun json-serialize object &rest args +This function returns a new Lisp string which contains the JSON +representation of @var{object}. The argument @var{args} is a list of +keyword/argument pairs. The following keywords are accepted: + +@table @code +@item :null-object +The value decides which Lisp object to use to represent the JSON +keyword @code{null}. It defaults to the symbol @code{:null}. + +@item :false-object +The value decides which Lisp object to use to represent the JSON +keyword @code{false}. It defaults to the symbol @code{:false}. +@end table + +@end defun + +@defun json-insert object &rest args +This function inserts the JSON representation of @var{object} into the +current buffer before point. The argument @var{args} are interpreted +as in @code{json-parse-string}. +@end defun + +@defun json-parse-string string &rest args +This function parses the JSON value in @var{string}, which must be a +Lisp string. If @var{string} doesn't contain a valid JSON object, +this function signals the @code{json-parse-error} error. + +The argument @var{args} is a list of keyword/argument pairs. The +following keywords are accepted: + +@table @code +@item :object-type +The value decides which Lisp object to use for representing the +key-value mappings of a JSON object. It can be either +@code{hash-table}, the default, to make hashtables with strings as +keys; @code{alist} to use alists with symbols as keys; or @code{plist} +to use plists with keyword symbols as keys. + +@item :array-type +The value decides which Lisp object to use for representing a JSON +array. It can be either @code{array}, the default, to use Lisp +arrays; or @code{list} to use lists. + +@item :null-object +The value decides which Lisp object to use to represent the JSON +keyword @code{null}. It defaults to the symbol @code{:null}. + +@item :false-object +The value decides which Lisp object to use to represent the JSON +keyword @code{false}. It defaults to the symbol @code{:false}. +@end table + +@end defun + +@defun json-parse-buffer &rest args +This function reads the next JSON value from the current buffer, +starting at point. It moves point to the position immediately after +the value if contains a valid JSON object; otherwise it signals the +@code{json-parse-error} error and doesn't move point. The arguments +@var{args} are interpreted as in @code{json-parse-string}. +@end defun + +@node JSONRPC +@section JSONRPC communication +@cindex JSON remote procedure call protocol +@cindex JSONRPC + +The @code{jsonrpc} library implements the @acronym{JSONRPC} +specification, version 2.0, as it is described in +@uref{http://www.jsonrpc.org/}. As the name suggests, JSONRPC is a +generic @dfn{Remote Procedure Call} protocol designed around +@acronym{JSON} objects, which you can convert to and from Lisp objects +(@pxref{Parsing JSON}). + +@menu +* JSONRPC Overview:: +* Process-based JSONRPC connections:: +* JSONRPC JSON object format:: +* JSONRPC deferred requests:: +@end menu + +@node JSONRPC Overview +@subsection Overview + +Quoting from the @uref{http://www.jsonrpc.org/, spec}, JSONRPC "is +transport agnostic in that the concepts can be used within the same +process, over sockets, over http, or in many various message passing +environments." + +@findex jsonrpc-connection +To model this agnosticism, the @code{jsonrpc} library uses objects of +a @code{jsonrpc-connection} class, which represent a connection to a +remote JSON endpoint (for details on Emacs's object system, +@pxref{Top,EIEIO,,eieio,EIEIO}). In modern object-oriented parlance, +this class is ``abstract'', i.e.@: the actual class of a useful +connection object is always a subclass of @code{jsonrpc-connection}. +Nevertheless, we can define two distinct APIs around the +@code{jsonrpc-connection} class: + +@cindex JSONRPC application interfaces +@enumerate + +@item A user interface for building JSONRPC applications + +@findex :request-dispatcher +@findex :notification-dispatcher +@findex jsonrpc-notify +@findex jsonrpc-request +@findex jsonrpc-async-request +In this scenario, the JSONRPC application selects a concrete subclass +of @code{jsonrpc-connection}, and proceeds to create objects of that +subclass using @code{make-instance}. To initiate a contact to the +remote endpoint, the JSONRPC application passes this object to the +functions @code{jsonrpc-notify}, @code{jsonrpc-request}, and/or +@code{jsonrpc-async-request}. For handling remotely initiated +contacts, which generally come in asynchronously, the instantiation +should include @code{:request-dispatcher} and +@code{:notification-dispatcher} initargs, which are both functions of +3 arguments: the connection object; a symbol naming the JSONRPC method +invoked remotely; and a JSONRPC @code{params} object. + +@findex jsonrpc-error +The function passed as @code{:request-dispatcher} is responsible for +handling the remote endpoint's requests, which expect a reply from the +local endpoint (in this case, the program you're building). Inside +that function, you may either return locally (a normal return) or +non-locally (an error return). A local return value must be a Lisp +object that can be serialized as JSON (@pxref{Parsing JSON}). This +determines a success response, and the object is forwarded to the +server as the JSONRPC @code{result} object. A non-local return, +achieved by calling the function @code{jsonrpc-error}, causes an error +response to be sent to the server. The details of the accompanying +JSONRPC @code{error} are filled out with whatever was passed to +@code{jsonrpc-error}. A non-local return triggered by an unexpected +error of any other type also causes an error response to be sent +(unless you have set @code{debug-on-error}, in which case this calls +the Lisp debugger, @pxref{Error Debugging}). + +@item A inheritance interface for building JSONRPC transport implementations + +In this scenario, @code{jsonrpc-connection} is subclassed to implement +a different underlying transport strategy (for details on how to +subclass, see @ref{Inheritance,Inheritance,,eieio}.). Users of the +application-building interface can then instantiate objects of this +concrete class (using the @code{make-instance} function) and connect +to JSONRPC endpoints using that strategy. + +This API has mandatory and optional parts. + +@findex jsonrpc-connection-send +To allow its users to initiate JSONRPC contacts (notifications or +requests) or reply to endpoint requests, the subclass must have an +implementation of the @code{jsonrpc-connection-send} method. + +@findex jsonrpc-connection-receive +Likewise, for handling the three types of remote contacts (requests, +notifications, and responses to local requests), the transport +implementation must arrange for the function +@code{jsonrpc-connection-receive} to be called after noticing a new +JSONRPC message on the wire (whatever that "wire" may be). + +@findex jsonrpc-shutdown +@findex jsonrpc-running-p +Finally, and optionally, the @code{jsonrpc-connection} subclass should +implement the @code{jsonrpc-shutdown} and @code{jsonrpc-running-p} +methods if these concepts apply to the transport. If they do, then +any system resources (e.g.@: processes, timers, etc.) used to listen for +messages on the wire should be released in @code{jsonrpc-shutdown}, +i.e.@: they should only be needed while @code{jsonrpc-running-p} is +non-nil. + +@end enumerate + +@node Process-based JSONRPC connections +@subsection Process-based JSONRPC connections +@cindex JSONRPC process-based connections + +@findex jsonrpc-process-connection +For convenience, the @code{jsonrpc} library comes with a built-in +@code{jsonrpc-process-connection} transport implementation that can +talk to local subprocesses (using the standard input and standard +output); or TCP hosts (using sockets); or any other remote endpoint +that Emacs's process object can represent (@pxref{Processes}). + +Using this transport, the JSONRPC messages are encoded on the wire as +plain text and prefaced by some basic HTTP-style enveloping headers, +such as ``Content-Length''. + +For an example of an application using this transport scheme on top of +JSONRPC, see the +@uref{https://microsoft.github.io/language-server-protocol/specification, +Language Server Protocol}. + +@cindex JSONRPC connection initargs +Along with the mandatory @code{:request-dispatcher} and +@code{:notification-dispatcher} initargs, users of the +@code{jsonrpc-process-connection} class should pass the following +initargs as keyword-value pairs to @code{make-instance}: + +@table @code +@item :process +Value must be a live process object or a function of no arguments +producing one such object. If passed a process object, the object is +expected to contain a pre-established connection; otherwise, the +function is called immediately after the object is made. + +@item :on-shutdown +Value must be a function of a single argument, the +@code{jsonrpc-process-connection} object. The function is called +after the underlying process object has been deleted (either +deliberately by @code{jsonrpc-shutdown}, or unexpectedly, because of +some external cause). +@end table + +@node JSONRPC JSON object format +@subsection JSONRPC JSON object format +@cindex JSONRPC object format + +JSONRPC JSON objects are exchanged as Lisp plists (@pxref{Property +Lists}): JSON-compatible plists are handed to the dispatcher functions +and, likewise, JSON-compatible plists should be given to +@code{jsonrpc-notify}, @code{jsonrpc-request}, and +@code{jsonrpc-async-request}. + +@findex jsonrpc-lambda +To facilitate handling plists, this library makes liberal use of +@code{cl-lib} library (@pxref{Top,cl-lib,,cl,Common Lisp Extensions +for GNU Emacs Lisp}) and suggests (but doesn't force) its clients to +do the same. A macro @code{jsonrpc-lambda} can be used to create a +lambda for destructuring a JSON-object like in this example: + +@example +(jsonrpc-async-request + myproc :frobnicate `(:foo "trix") + :success-fn (jsonrpc-lambda (&key bar baz &allow-other-keys) + (message "Server replied back with %s and %s!" + bar baz)) + :error-fn (jsonrpc-lambda (&key code message _data) + (message "Sadly, server reports %s: %s" + code message))) +@end example + +@node JSONRPC deferred requests +@subsection Deferred JSONRPC requests +@cindex JSONRPC deferred requests + +In many @acronym{RPC} situations, synchronization between the two +communicating endpoints is a matter of correctly designing the RPC +application: when synchronization is needed, requests (which are +blocking) should be used; when it isn't, notifications should suffice. +However, when Emacs acts as one of these endpoints, asynchronous +events (e.g. timer- or process-related) may be triggered while there +is still uncertainty about the state of the remote endpoint. +Furthermore, acting on these events may only sometimes demand +synchronization, depending on the event's specific nature. + +@findex :deferred@r{, JSONRPC keyword} +The @code{:deferred} keyword argument to @code{jsonrpc-request} and +@code{jsonrpc-async-request} is designed to let the caller indicate +that the specific request needs synchronization and its actual +issuance may be delayed to the future, until some condition is +satisfied. Specifying @code{:deferred} for a request doesn't mean it +@emph{will} be delayed, only that it @emph{can} be. If the request +isn't sent immediately, @code{jsonrpc} will make renewed efforts to +send it at certain key times during communication, such as when +receiving or sending other messages to the endpoint. + +@findex jsonrpc-connection-ready-p +Before any attempt to send the request, the application-specific +conditions are checked. Since the @code{jsonrpc} library can't know +what these conditions are, the program can use the +@code{jsonrpc-connection-ready-p} generic function (@pxref{Generic +Functions}) to specify them. The default method for this function +returns @code{t}, but you can add overriding methods that return +@code{nil} in some situations, based on the arguments passed to it, +which are the @code{jsonrpc-connection} object (@pxref{JSONRPC +Overview}) and whichever value you passed as the @code{:deferred} +keyword argument. + @node Atomic Changes @section Atomic Change Groups @cindex atomic changes @@ -5051,8 +5594,8 @@ making. When that happens, the arguments to individual changes are made, but won't necessarily be the minimal such region, and the arguments to each successive call of @code{after-change-functions} will then delimit the part of text being -changed exactly. In general, we advise to use either before- or the -after-change hooks, but not both. +changed exactly. In general, we advise using either the before- or +the after-change hook, but not both. @defmac combine-after-change-calls body@dots{} The macro executes @var{body} normally, but arranges to call the @@ -5076,6 +5619,30 @@ because it may lead to inefficient behavior for some change hook functions. @end defmac +@defmac combine-change-calls beg end body@dots{} +This executes @var{body} normally, except any buffer changes it makes +do not trigger the calls to @code{before-change-functions} and +@code{after-change-functions}. Instead there is a single call of each +of these hooks for the region enclosed by @var{beg} and @var{end}, the +parameters supplied to @code{after-change-functions} reflecting the +changes made to the size of the region by @var{body}. + +The result of this macro is the result returned by @var{body}. + +This macro is useful when a function makes a possibly large number of +repetitive changes to the buffer, and the change hooks would otherwise +take a long time to run, were they to be run for each individual +buffer modification. Emacs itself uses this macro, for example, in +the commands @code{comment-region} and @code{uncomment-region}. + +@strong{Warning:} You must not alter the values of +@code{before-change-functions} or @code{after-change-function} within +@var{body}. + +@strong{Warning:} You must not make any buffer changes outside of the +region specified by @var{beg} and @var{end}. +@end defmac + @defvar first-change-hook This variable is a normal hook that is run whenever a buffer is changed that was previously in the unmodified state. @@ -5093,5 +5660,8 @@ same hook variables, so that by default modifying the buffer from a modification hook does not cause other modification hooks to be run. If you do want modification hooks to be run in a particular piece of code that is itself run from a modification hook, then rebind locally -@code{inhibit-modification-hooks} to @code{nil}. +@code{inhibit-modification-hooks} to @code{nil}. However, doing this +may cause recursive calls to the modification hooks, so be sure to +prepare for that (for example, by binding some variable which tells +your hook to do nothing). @end defvar diff --git a/doc/lispref/threads.texi b/doc/lispref/threads.texi index 7b14ab5a730..db68f9192bd 100644 --- a/doc/lispref/threads.texi +++ b/doc/lispref/threads.texi @@ -45,6 +45,7 @@ closure are shared by any threads invoking the closure. * Basic Thread Functions:: Basic thread functions. * Mutexes:: Mutexes allow exclusive access to data. * Condition Variables:: Inter-thread events. +* The Thread List:: Show the active threads. @end menu @node Basic Thread Functions @@ -75,8 +76,8 @@ thread, @code{nil} otherwise. @defun thread-join thread Block until @var{thread} exits, or until the current thread is -signaled. If @var{thread} has already exited, this returns -immediately. +signaled. It returns the result of the @var{thread} function. If +@var{thread} has already exited, this returns immediately. @end defun @defun thread-signal thread error-symbol data @@ -87,6 +88,9 @@ thread, then this just calls @code{signal} immediately. Otherwise, If @var{thread} was blocked by a call to @code{mutex-lock}, @code{condition-wait}, or @code{thread-join}; @code{thread-signal} will unblock it. + +If @var{thread} is the main thread, the signal is not propagated +there. Instead, it is shown as message in the main thread. @end defun @defun thread-yield @@ -127,15 +131,21 @@ Return a list of all the live thread objects. A new list is returned by each invocation. @end defun +@defvar main-thread +This variable keeps the main thread Emacs is running, or @code{nil} if +Emacs is compiled without thread support. +@end defvar + When code run by a thread signals an error that is unhandled, the thread exits. Other threads can access the error form which caused the thread to exit using the following function. -@defun thread-last-error +@defun thread-last-error &optional cleanup This function returns the last error form recorded when a thread exited due to an error. Each thread that exits abnormally overwrites the form stored by the previous thread's error with a new value, so -only the last one can be accessed. +only the last one can be accessed. If @var{cleanup} is +non-@code{nil}, the stored form is reset to @code{nil}. @end defun @node Mutexes @@ -262,3 +272,53 @@ Return the name of @var{cond}, as passed to Return the mutex associated with @var{cond}. Note that the associated mutex cannot be changed. @end defun + +@node The Thread List +@section The Thread List + +@cindex thread list +@cindex list of threads +@findex list-threads +The @code{list-threads} command lists all the currently alive threads. +In the resulting buffer, each thread is identified either by the name +passed to @code{make-thread} (@pxref{Basic Thread Functions}), or by +its unique internal identifier if it was not created with a name. The +status of each thread at the time of the creation or last update of +the buffer is shown, in addition to the object the thread was blocked +on at the time, if it was blocked. + +@defvar thread-list-refresh-seconds +The @file{*Threads*} buffer will automatically update twice per +second. You can make the refresh rate faster or slower by customizing +this variable. +@end defvar + +Here are the commands available in the thread list buffer: + +@table @kbd + +@cindex backtrace of thread +@cindex thread backtrace +@item b +Show a backtrace of the thread at point. This will show where in its +code the thread had yielded or was blocked at the moment you pressed +@kbd{b}. Be aware that the backtrace is a snapshot; the thread could +have meanwhile resumed execution, and be in a different state, or +could have exited. + +You may use @kbd{g} in the thread's backtrace buffer to get an updated +backtrace, as backtrace buffers do not automatically update. +@xref{Backtraces}, for a description of backtraces and the other +commands which work on them. + +@item s +Signal the thread at point. After @kbd{s}, type @kbd{q} to send a +quit signal or @kbd{e} to send an error signal. Threads may implement +handling of signals, but the default behavior is to exit on any +signal. Therefore you should only use this command if you understand +how to restart the target thread, because your Emacs session may +behave incorrectly if necessary threads are killed. + +@item g +Update the list of threads and their statuses. +@end table diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index d41fe825729..30f2c983adc 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -1013,7 +1013,7 @@ etc.). If there is no maintainer line, the person(s) in the Author field is/are presumed to be the maintainers. Some files in Emacs use -@samp{FSF} for the maintainer. This means that the original author is +@samp{emacs-devel@@gnu.org} for the maintainer, which means the author is no longer responsible for the file, and that it is maintained as part of Emacs. diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 1a1860df307..6e6448ec1e9 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -303,7 +303,7 @@ that Lisp avoids infinite recursion on an ill-defined function. @code{max-lisp-eval-depth} provides another limit on depth of nesting. @xref{Definition of max-lisp-eval-depth,, Eval}. -The default value is 1300. Entry to the Lisp debugger increases the +The default value is 1500. Entry to the Lisp debugger increases the value, if there is little room left, to make sure the debugger itself has room to execute. @end defopt @@ -2196,9 +2196,9 @@ This function looks for connection-local variables according to @var{criteria}, and immediately applies them in the current buffer. @end defun -@defmac with-connection-local-profiles profiles &rest body -All connection-local variables, which are specified by a connection -profile in @var{profiles}, are applied. +@defmac with-connection-local-variables &rest body +All connection-local variables, which are specified by +@code{default-directory}, are applied. After that, @var{body} is executed, and the connection-local variables are unwound. Example: @@ -2212,8 +2212,15 @@ are unwound. Example: @end group @group -(with-connection-local-profiles '(remote-perl) - do something useful) +(connection-local-set-profiles + '(:application 'tramp :protocol "ssh" :machine "remotehost") + 'remote-perl) +@end group + +@group +(let ((default-directory "/ssh:remotehost:/working/dir/")) + (with-connection-local-variables + do something useful)) @end group @end example @end defmac diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index ea9329e0517..a6cb86eb84c 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -568,12 +568,6 @@ its pixel height is the pixel height of the screen areas spanned by its children. @end defun -@defun window-pixel-height-before-size-change &optional Lisp_Object &optional window -This function returns the height of window @var{window} in pixels at the -time @code{window-size-change-functions} was run for the last time on -@var{window}'s frame (@pxref{Window Hooks}). -@end defun - @cindex window pixel width @cindex pixel width of a window @cindex total pixel width of a window @@ -588,12 +582,6 @@ If @var{window} is an internal window, its pixel width is the width of the screen areas spanned by its children. @end defun -@defun window-pixel-width-before-size-change &optional Lisp_Object &optional window -This function returns the width of window @var{window} in pixels at the -time @code{window-size-change-functions} was run for the last time on -@var{window}'s frame (@pxref{Window Hooks}). -@end defun - @cindex full-width window @cindex full-height window The following functions can be used to determine whether a given @@ -1775,7 +1763,7 @@ raise the frame or make sure input focus is directed to that frame. @xref{Input Focus}. @end defun -@cindex select window hook +@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 @@ -1791,8 +1779,8 @@ 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 a reasonable way to run a function -whenever a window gets selected more ``permanently''. +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 @@ -1804,6 +1792,13 @@ 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 @@ -2274,6 +2269,12 @@ selected window or never appeared in it before, or if buffer. @end defopt +@defopt switch-to-buffer-obey-display-actions +If this variable is non-@code{nil}, @code{switch-to-buffer} respects +display actions specified by @code{display-buffer-overriding-action}, +@code{display-buffer-alist} and other display related variables. +@end defopt + The next two commands are similar to @code{switch-to-buffer}, except for the described features. @@ -2630,6 +2631,63 @@ window and displaying the buffer in that window. It can fail if all windows are dedicated to other buffers (@pxref{Dedicated Windows}). @end defun +@defun display-buffer-in-direction buffer alist +This function tries to display @var{buffer} at a location specified by +@var{alist}. For this purpose, @var{alist} should contain a +@code{direction} entry whose value is one of @code{left}, @code{above} +(or @code{up}), @code{right} and @code{below} (or @code{down}). Other +values are usually interpreted as @code{below}. + +If @var{alist} also contains a @code{window} entry, its value +specifies a reference window. That value can be a special symbol like +@code{main} which stands for the selected frame's main window +(@pxref{Side Window Options and Functions}) or @code{root} standing +for the selected frame's root window (@pxref{Windows and Frames}). It +can also specify an arbitrary valid window. Any other value (or +omitting the @code{window} entry entirely) means to use the selected +window as reference window. + +This function first tries to reuse a window in the specified direction +that already shows @var{buffer}. If no such window exists, it tries +to split the reference window in order to produce a new window in the +specified direction. If this fails as well, it will try to display +@var{buffer} in an existing window in the specified direction. In +either case, the window chosen will appear on the side of the +reference window specified by the @code{direction} entry, sharing at +least one edge with the reference window. + +If the reference window is live, the edge the chosen window will share +with it is always the opposite of the one specified by the +@code{direction} entry. For example, if the value of the +@code{direction} entry is @code{left}, the chosen window's right edge +coordinate (@pxref{Coordinates and Windows}) will equal the reference +window's left edge coordinate. + +If the reference window is internal, a reused window must share with +it the edge specified by the @code{direction} entry. Hence if, for +example, the reference window is the frame's root window and the value +of the @code{direction} entry is @code{left}, a reused window must be +on the left of the frame. This means that the left edge coordinate of +the chosen window and that of the reference window are the same. + +A new window, however, will be created by splitting the reference +window such that the chosen window will share the opposite edge with +the reference window. In our example, a new root window would be +created with a new live window and the reference window as its +children. The chosen window's right edge coordinate would then equal +the left edge coordinate of the reference window. Its left edge +coordinate would equal the left edge coordinate of the frame's new +root window. + +Four special values for @code{direction} entries allow to implicitly +specify the selected frame's main window as the reference window: +@code{leftmost}, @code{top}, @code{rightmost} and @code{bottom}. This +means that instead of, for example, @w{@code{(direction . left) +(window . main)}} one can just specify @w{@code{(direction +. leftmost)}}. An existing @code{window} @var{alist} entry is ignored +in such cases. +@end defun + @defun display-buffer-below-selected buffer alist This function tries to display @var{buffer} in a window below the selected window. If there is a window below the selected one and that @@ -2643,6 +2701,12 @@ suitable @code{window-height} or @code{window-width} entry, see above. If splitting the selected window fails and there is a non-dedicated window below the selected one showing some other buffer, this function tries to use that window for showing @var{buffer}. + +If @var{alist} contains a @code{window-min-height} entry, this +function ensures that the window used is or can become at least as +high as specified by that entry's value. Note that this is only a +guarantee. In order to actually resize the window used, @var{alist} +must also provide an appropriate @code{window-height} entry. @end defun @defun display-buffer-at-bottom buffer alist @@ -2828,6 +2892,22 @@ The value specifies an alist of window parameters to give the chosen window. All action functions that choose a window should process this entry. +@vindex window-min-height@r{, a buffer display action alist entry} +@item window-min-height +The value specifies a minimum height of the window used, in lines. If +a window is not or cannot be made as high as specified by this entry, +the window is not considered for use. The only client of this entry +is presently @code{display-buffer-below-selected}. + +Note that providing such an entry alone does not necessarily make the +window as tall as specified by its value. To actually resize an +existing window or make a new window as tall as specified by that +value, a @code{window-height} entry specifying that value should be +provided as well. Such a @code{window-height} entry can, however, +specify a completely different value or ask the window height to be +fit to that of its buffer in which case the @code{window-min-height} +entry provides the guaranteed minimum height of the window used. + @vindex window-height@r{, a buffer display action alist entry} @item window-height The value specifies whether and how to adjust the height of the chosen @@ -2891,6 +2971,13 @@ 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 dedicated@r{, a buffer display action alist entry} +@item dedicated +If non-@code{nil}, such an entry tells @code{display-buffer} to mark +any window it creates as dedicated to its buffer (@pxref{Dedicated +Windows}). It does that by calling @code{set-window-dedicated-p} with +the chosen window as first argument and the entry's value as second. + @vindex preserve-size@r{, a buffer display action alist entry} @item preserve-size If non-@code{nil} such an entry tells Emacs to preserve the size of @@ -2936,12 +3023,20 @@ If non-@code{nil}, the value specifies the slot of the side window supposed to display the buffer. This entry is used only by @code{display-buffer-in-side-window}. +@vindex direction@r{, a buffer display action alist entry} +@item direction +The value specifies a direction which, together with a @code{window} +entry, allows @code{display-buffer-in-direction} to determine the +location of the window to display the buffer. + @vindex window@r{, a buffer display action alist entry} @item window The value specifies a window that is in some way related to the window chosen by @code{display-buffer}. This entry is currently used by @code{display-buffer-in-atom-window} to indicate the window on whose -side the new window shall be created. +side the new window shall be created. It is also used by +@code{display-buffer-in-direction} to specify the reference window on +whose side the resulting window shall appear. @vindex allow-no-window@r{, a buffer display action alist entry} @item allow-no-window @@ -3910,6 +4005,9 @@ display. Other functions do not treat @code{t} differently from any non-@code{nil} value. @end defun +You can also tell @code{display-buffer} to mark a window it creates as +dedicated to its buffer by providing a suitable @code{dedicated} +action alist entry (@pxref{Buffer Display Action Alists}). @node Quitting Windows @section Quitting Windows @@ -4931,6 +5029,13 @@ line reappears after the echo area momentarily displays the message @samp{End of buffer}. @end deffn +@deffn Command scroll-other-window-down &optional count +This function scrolls the text in another window downward @var{count} +lines. Negative values of @var{count}, or @code{nil}, are handled as +in @code{scroll-down}. In other respects, it behaves the same way as +@code{scroll-other-window} does. +@end deffn + @defvar other-window-scroll-buffer If this variable is non-@code{nil}, it tells @code{scroll-other-window} which buffer's window to scroll. @@ -5033,7 +5138,7 @@ beginning or end of the buffer (depending on scrolling direction); only if point is already on that position do they signal an error. @end defopt -@deffn Command recenter &optional count +@deffn Command recenter &optional count redisplay @cindex centering point This function scrolls the text in the selected window so that point is displayed at a specified vertical position within the window. It does @@ -5047,8 +5152,12 @@ line in the window. If @var{count} is @code{nil} (or a non-@code{nil} list), @code{recenter} puts the line containing point in the middle of the -window. If @var{count} is @code{nil}, this function may redraw the -frame, according to the value of @code{recenter-redisplay}. +window. If @var{count} is @code{nil} and @var{redisplay} is +non-@code{nil}, this function may redraw the frame, according to the +value of @code{recenter-redisplay}. Thus, omitting the second +argument can be used to countermand the effect of +@code{recenter-redisplay} being non-@code{nil}. Interactive calls +pass non-‘nil’ for @var{redisplay}. When @code{recenter} is called interactively, @var{count} is the raw prefix argument. Thus, typing @kbd{C-u} as the prefix sets the @@ -5076,8 +5185,9 @@ respect to the entire window group. @defopt recenter-redisplay If this variable is non-@code{nil}, calling @code{recenter} with a -@code{nil} argument redraws the frame. The default value is -@code{tty}, which means only redraw the frame if it is a tty frame. +@code{nil} @var{count} argument and non-@code{nil} @var{redisplay} +argument redraws the frame. The default value is @code{tty}, which +means only redraw the frame if it is a tty frame. @end defopt @deffn Command recenter-top-bottom &optional count @@ -5736,10 +5846,6 @@ prevent the code in @var{forms} from opening new windows, because new windows might be opened in other frames (@pxref{Choosing Window}), and @code{save-window-excursion} only saves and restores the window configuration on the current frame. - -Do not use this macro in @code{window-size-change-functions}; exiting -the macro triggers execution of @code{window-size-change-functions}, -leading to an endless loop. @end defmac @defun window-configuration-p object @@ -5801,9 +5907,10 @@ This function puts the window state @var{state} into @var{window}. The argument @var{state} should be the state of a window returned by an earlier invocation of @code{window-state-get}, see above. The optional argument @var{window} can be either a live window or an -internal window (@pxref{Windows and Frames}) and defaults to the -selected one. If @var{window} is not live, it is replaced by a live -window before putting @var{state} into it. +internal window (@pxref{Windows and Frames}). If @var{window} is not +a live window, it is replaced by a new live window created on the same +frame before putting @var{state} into it. If @var{window} is @code{nil}, +it puts the window state into a new window. If the optional argument @var{ignore} is non-@code{nil}, it means to ignore minimum window sizes and fixed-size restrictions. If @var{ignore} @@ -5857,10 +5964,10 @@ This function sets @var{window}'s value of @var{parameter} to is the selected window. @end defun -By default, the functions that save and restore window configurations or the -states of windows (@pxref{Window Configurations}) do not care about -window parameters. This means that when you change the value of a -parameter within the body of a @code{save-window-excursion}, the +By default, the functions that save and restore window configurations +or the states of windows (@pxref{Window Configurations}) do not care +about window parameters. This means that when you change the value of +a parameter within the body of a @code{save-window-excursion}, the previous value is not restored when that macro exits. It also means that when you restore via @code{window-state-put} a window state saved earlier by @code{window-state-get}, all cloned windows have their @@ -6027,27 +6134,26 @@ applications. It might be replaced by an improved solution in future versions of Emacs. @end table + @node Window Hooks @section Hooks for Window Scrolling and Changes @cindex hooks for window operations -This section describes how a Lisp program can take action whenever a -window displays a different part of its buffer or a different buffer. -There are three actions that can change this: scrolling the window, -switching buffers in the window, and changing the size of the window. -The first two actions run @code{window-scroll-functions}; the last runs -@code{window-size-change-functions}. +This section describes how Lisp programs can take action after a +window has been scrolled or other window modifications occurred. We +first consider the case where a window shows a different part of its +buffer. @defvar window-scroll-functions This variable holds a list of functions that Emacs should call before -redisplaying a window with scrolling. Displaying a different buffer in -the window also runs these functions. +redisplaying a window with scrolling. Displaying a different buffer +in a window and making a new window also call these functions. -This variable is not a normal hook, because each function is called with -two arguments: the window, and its new display-start position. At the -time of the call, the display-start position of the window argument is -already set to its new value, and the buffer to be displayed in the -window is already set as the current buffer. +This variable is not a normal hook, because each function is called +with two arguments: the window, and its new display-start position. +At the time of the call, the display-start position of the argument +window is already set to its new value, and the buffer to be displayed +in the window is set as the current buffer. These functions must take care when using @code{window-end} (@pxref{Window Start and End}); if you need an up-to-date value, you @@ -6058,55 +6164,294 @@ is scrolled. It's not designed for that, and such use probably won't work. @end defvar -@defun run-window-scroll-functions &optional window -This function calls @code{window-scroll-functions} for the specified -@var{window}, which defaults to the selected window. -@end defun +In addition, you can use @code{jit-lock-register} to register a Font +Lock fontification function, which will be called whenever parts of a +buffer are (re)fontified because a window was scrolled or its size +changed. @xref{Other Font Lock Variables}. + +@cindex window change functions + The remainder of this section covers six hooks that are called +during redisplay provided a significant, non-scrolling change of a +window has been detected. For simplicity, these hooks and the +functions they call will be collectively referred to as @dfn{window +change functions}. + +@cindex window buffer change +The first of these hooks is run after a @dfn{window buffer change} is +detected, which means that a window was created, deleted or assigned +another buffer. + +@defvar window-buffer-change-functions +This variable specifies functions called during redisplay when window +buffers have changed. The value should be a list of functions that +take one argument. + +Functions specified buffer-locally are called for any window showing +the corresponding buffer if that window has been created or assigned +that buffer since the last time window change functions were run. In +this case the window is passed as argument. + +Functions specified by the default value are called for a frame if at +least one window on that frame has been added, deleted or assigned +another buffer since the last time window change functions were run. +In this case the frame is passed as argument. +@end defvar + +@cindex window size change +The second of these hooks is run when a @dfn{window size change} has +been detected which means that a window was created, assigned another +buffer, or changed its total size or that of its text area. @defvar window-size-change-functions -This variable holds a list of functions to be called if the size of any -window changes for any reason. The functions are called once per -redisplay, and once for each frame on which size changes have occurred. - -Each function receives the frame as its sole argument. To find out -whether a specific window has changed size, compare the return values of -@code{window-pixel-width-before-size-change} and -@code{window-pixel-width} respectively -@code{window-pixel-height-before-size-change} and -@code{window-pixel-height} for that window (@pxref{Window Sizes}). - -These function are usually only called when at least one window was -added or has changed size since the last time this hook was run for -the associated frame. In some rare cases this hook also runs when a -window that was added intermittently has been deleted afterwards. In -these cases none of the windows on the frame will appear to have -changed its size. +This variable specifies functions called during redisplay when a +window size change occurred. The value should be a list of functions +that take one argument. + +Functions specified buffer-locally are called for any window showing +the corresponding buffer if that window has been added or assigned +another buffer or changed its total or body size since the last time +window change functions were run. In this case the window is passed +as argument. + +Functions specified by the default value are called for a frame if at +least one window on that frame has been added or assigned another +buffer or changed its total or body size since the last time window +change functions were run. In this case the frame is passed as +argument. @end defvar +@cindex window selection change +The third of these hooks is run when a @dfn{window selection change} +has selected another window since the last redisplay. + +@defvar window-selection-change-functions +This variable specifies functions called during redisplay when the +selected window or a frame's selected window has changed. The value +should be a list of functions that take one argument. + +Functions specified buffer-locally are called for any window showing +the corresponding buffer if that window has been selected or +deselected (among all windows or among all windows on its frame) since +the last time window change functions were run. In this case the +window is passed as argument. + +Functions specified by the default value are called for a frame if +that frame has been selected or deselected or the frame's selected +window has changed since the last time window change functions were +run. In this case the frame is passed as argument. +@end defvar + +@cindex window state change +The fourth of these hooks is run when a @dfn{window state change} has +been detected, which means that at least one of the three preceding +window changes has occurred. + +@defvar window-state-change-functions +This variable specifies functions called during redisplay when a +window buffer or size change occurred or the selected window or a +frame's selected window has changed. The value should be a list of +functions that take one argument. + +Functions specified buffer-locally are called for any window showing +the corresponding buffer if that window has been added or assigned +another buffer, changed its total or body size or has been selected or +deselected (among all windows or among all windows on its frame) since +the last time window change functions were run. In this case the +window is passed as argument. + +Functions specified by the default value are called for a frame if at +least one window on that frame has been added, deleted or assigned +another buffer, changed its total or body size or that frame has been +selected or deselected or the frame's selected window has changed +since the last time window change functions were run. In this case +the frame is passed as argument. + +Functions specified by the default value are also run for a frame when +that frame's window state change flag (see below) has been set since +last redisplay. +@end defvar + +@cindex window configuration change +The fifth of these hooks is run when a @dfn{window configuration +change} has been detected which means that either the buffer or the +size of a window changed. It differs from the four preceding hooks in +the way it is run. + @defvar window-configuration-change-hook -A normal hook that is run every time the window configuration of a -frame changes. Window configuration changes include splitting and -deleting windows, and the display of a different buffer in a window. - -The hook can be also used for tracking changes of window sizes. It -is, however, not run when the size of a frame changes or automatic -resizing of a minibuffer window (@pxref{Minibuffer Windows}) changes -the size of another window. As a rule, adding a function to -@code{window-size-change-functions}, see above, is the recommended way -for reliably tracking size changes of any window. - -The buffer-local value of this hook is run once for each window on the -affected frame, with the relevant window selected and its buffer -current. The global value of this hook is run once for the modified -frame, with that frame selected. +This variable specifies functions called during redisplay when either +the buffer or the size of a window has changed. The value should be a +list of functions that take no argument. + +Functions specified buffer-locally are called for any window showing +the corresponding buffer if at least one window on that frame has been +added, deleted or assigned another buffer or changed its total or +body size since the last time window change functions were run. Each +call is performed with the window showing the buffer temporarily +selected and its buffer current. + +Functions specified by the default value are called for each frame if +at least one window on that frame has been added, deleted or assigned +another buffer or changed its total or body size since the last time +window change functions were run. Each call is performed with the +frame temporarily selected and the selected window's buffer current. +@end defvar + +Finally, Emacs runs a normal hook that generalizes the behavior of +@code{window-state-change-functions}. + +@defvar window-state-change-hook +The default value of this variable specifies functions called during +redisplay when a window state change has been detected or the window +state change flag has been set on at least one frame. The value +should be a list of functions that take no argument. + +Applications should put a function on this hook only if they want to +react to changes that happened on (or have been signaled for) two or +more frames since last redisplay. In every other case, putting the +function on @code{window-state-change-functions} should be preferred. @end defvar -@defun run-window-configuration-change-hook &optional frame -This function runs @code{window-configuration-change-hook} for the -specified @var{frame}, which defaults to the selected frame. +Window change functions are called during redisplay for each frame as +follows: First, any buffer-local window buffer change function, window +size change function, selected window change and window state change +functions are called in this order. Next, the default values for +these functions are called in the same order. Then any buffer-local +window configuration change functions are called followed by functions +specified by the default value of those functions. Finally, functions +on @code{window-state-change-hook} are run. + + Window change functions are run for a specific frame only if a +corresponding change was registered for that frame earlier. Such +changes include the creation or deletion of a window or the assignment +of another buffer or size to a window. Note that even when such a +change has been registered, this does not mean that any of the hooks +described above is run. If, for example, a change was registered +within the scope of a window excursion (@pxref{Window +Configurations}), this will trigger a call of window change functions +only if that excursion still persists at the time change functions are +run. If it is exited earlier, hooks will be run only if registered by +a change outside the scope of that excursion. + +@cindex window state change flag + The @dfn{window state change flag} of a frame, if set, will cause +the default values of @code{window-state-change-functions} (for that +frame) and @code{window-state-change-hook} to be run during next +redisplay regardless of whether a window state change actually +occurred for that frame or not. After running any functions on these +hooks, the flag is reset for each frame. Applications can set that +flag and inspect its value using the following functions. + +@defun set-frame-window-state-change &optional frame arg +This function sets @var{frame}'s window state change flag if @var{arg} +is non-@code{nil} and resets it otherwise. @var{frame} must be a live +frame and defaults to the selected one. @end defun - In addition, you can use @code{jit-lock-register} to register a Font -Lock fontification function, which will be called whenever parts of a -buffer are (re)fontified because a window was scrolled or its size -changed. @xref{Other Font Lock Variables}. +@defun frame-window-state-change &optional frame +This functions returns @code{t} if @var{frame}'s window state change +flag is set and @code{nil} otherwise. @var{frame} must be a live +frame and defaults to the selected one. +@end defun + + While window change functions are run, the functions described next +can be called to get more insight into what has changed for a specific +window or frame since the last redisplay. All these functions take a +live window as single, optional argument, defaulting to the selected +window. + +@defun window-old-buffer &optional window +This function returns the buffer shown in @var{window} at the last +time window change functions were run for @var{window}'s frame. If it +returns @code{nil}, @var{window} has been created after that. If it +returns @code{t}, @var{window} was not shown at that time but has been +restored from a previously saved window configuration afterwards. +Otherwise, the return value is the buffer shown by @code{window} at +that time. +@end defun + +@defun window-old-pixel-width &optional window +This function returns the total pixel width of @var{window} the +last time window change functions found @code{window} live on its +frame. It is zero if @code{window} was created after that. +@end defun + +@defun window-old-pixel-height &optional window +This function returns the total pixel height of @var{window} the last +time window change functions found @code{window} live on its frame. +It is zero if @code{window} was created after that. +@end defun + +@defun window-old-body-pixel-width &optional window +This function returns the pixel width of @var{window}'s text area the +last time window change functions found @code{window} live on its +frame. It is zero if @code{window} was created after that. +@end defun + +@defun window-old-body-pixel-height &optional window +This function returns the pixel height of @var{window}'s text area the +last time window change functions found @code{window} live on its +frame. It is zero if @code{window} was created after that. +@end defun + +In order to find out which window or frame was selected the last time +window change functions were run, the following functions can be used: + +@defun frame-old-selected-window &optional frame +This function returns the selected window of @var{frame} at the last +time window change functions were run. If omitted or @code{nil} +@var{frame} defaults to the selected frame. +@end defun + +@defun old-selected-window +This function returns the selected window at the last time window +change functions were run. +@end defun + +@defun old-selected-frame +This function returns the selected frame at the last time window +change functions were run. +@end defun + +Note that window change functions provide no information about which +windows have been deleted since the last time they were run. If +necessary, applications should remember any window showing a specific +buffer in a local variable of that buffer and update it in a function +run by the default values of any of the hooks that are run when a +window buffer change was detected. + + The following caveats should be considered when adding a function +to window change functions: + +@itemize @bullet +@item +Some operations will not trigger a call of window change functions. +These include showing another buffer in a minibuffer window or any +change of a tooltip window. + +@item +Window change functions should not create or delete windows or change +the buffer, size or selection status of any window because there is no +guarantee that the information about such a change will be propagated +to other window change functions. If at all, any such change should +be executed only by the last function listed by the default value of +@code{window-state-change-hook}. + +@item +Macros like @code{save-window-excursion}, @code{with-selected-window} +or @code{with-current-buffer} can be used when running window change +functions. + +@item +Running window change functions does not save and restore match data. +Unless running @code{window-configuration-change-hook} it does not +save or restore the selected window or frame or the current buffer +either. + +@item +Any redisplay triggering the run of window change functions may be +aborted. If the abort occurs before window change functions have run +to their completion, they will be run again with the previous values, +that is, as if redisplay had not been performed. If aborted later, +they will be run with the new values, that is, as if redisplay had +been actually performed. +@end itemize diff --git a/doc/man/emacsclient.1 b/doc/man/emacsclient.1 index 5aaa6d1f083..24ca1c9a468 100644 --- a/doc/man/emacsclient.1 +++ b/doc/man/emacsclient.1 @@ -94,6 +94,7 @@ open a new Emacs frame on the current terminal .TP .B \-s, \-\-socket-name=FILENAME use socket named FILENAME for communication. +This can also be specified via the EMACS_SOCKET_NAME environment variable. .TP .B \-V, \-\-version print version information and exit diff --git a/doc/man/etags.1 b/doc/man/etags.1 index 57120e78dda..d1453ca969a 100644 --- a/doc/man/etags.1 +++ b/doc/man/etags.1 @@ -64,7 +64,7 @@ Files specified with absolute file names will be recorded with absolute file names. Files generated from a source file\-\-like a C file generated from a source Cweb file\-\-will be recorded with the name of the source file. -Compressed files are supported using gzip, bzip2, and xz. +Compressed files are supported using gzip, bzip2, xz, and zstd. The programs recognize the language used in an input file based on its file name and contents. The \fB\-\-language\fP switch can be used to force parsing of the file names following the switch according to the given @@ -145,7 +145,7 @@ May be used (only once) in place of a file name on the command line. \fBetags\fP will read from standard input and mark the produced tags as belonging to the file \fBFILE\fP. .TP -\fB \-Q, \-\-class\-qualify\fP +\fB\-Q, \-\-class\-qualify\fP Qualify tag names with their class name in C++, ObjC, Java, and Perl. This produces tag names of the form \fIclass\fP\fB::\fP\fImember\fP for C++ and Perl, diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index d02f42bbeb9..a03efaf8bef 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -224,13 +224,13 @@ ${buildinfodir}/tramp.info tramp.html: ${srcdir}/trampver.texi .PHONY: mostlyclean clean distclean bootstrap-clean maintainer-clean mostlyclean: - rm -f *.aux *.log *.toc *.c[mp] *.c[mp]s *.fn *.fns \ - *.ky *.kys *.op *.ops *.p[gj] *.p[gj]s *.sc *.scs *.ss \ - *.t[gp] *.t[gp]s *.vr *.vrs + rm -f ./*.aux ./*.log ./*.toc ./*.c[mp] ./*.c[mp]s ./*.fn ./*.fns \ + ./*.ky ./*.kys ./*.op ./*.ops ./*.p[gj] ./*.p[gj]s ./*.sc ./*.scs ./*.ss \ + ./*.t[gp] ./*.t[gp]s ./*.vr ./*.vrs rm -f gnustmp* clean: mostlyclean - rm -f *.dvi *.html *.pdf *.ps + rm -f ./*.dvi ./*.html ./*.pdf ./*.ps distclean: clean rm -f Makefile diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi index e467fc135f3..bbb66ecab5b 100644 --- a/doc/misc/auth.texi +++ b/doc/misc/auth.texi @@ -1,7 +1,5 @@ \input texinfo @c -*-texinfo-*- -@include gnus-overrides.texi - @set VERSION 0.3 @setfilename ../../info/auth.info @@ -86,7 +84,7 @@ password (known as the secret). Similarly, the auth-source library supports multiple storage backend, currently either the classic ``netrc'' backend, examples of which you -can see later in this document, the Secret Service API, and pass, the +can see later in this document, JSON files, the Secret Service API, and pass, the standard unix password manager. This is done with EIEIO-based backends and you can write your own if you want. @@ -109,6 +107,15 @@ The @code{user} is the user name. It's known as @var{:user} in @code{auth-source-search} queries. You can also use @code{login} and @code{account}. +You can also use this file to specify client certificates to use when +setting up TLS connections. The format is: +@example +machine @var{mymachine} port @var{myport} key @var{key} cert @var{cert} +@end example + +@var{key} and @var{cert} are filenames containing the key and +certificate to use respectively. + You can use spaces inside a password or other token by surrounding the token with either single or double quotes. @@ -169,6 +176,9 @@ get fancy, the default and simplest configuration is: ;;; use pass (@file{~/.password-store}) ;;; (@pxref{The Unix password store}) (setq auth-sources '(password-store)) +;;; JSON data in format [@{ "machine": "SERVER", +;;; "login": "USER", "password": "PASSWORD" @}...] +(setq auth-sources '("~/.authinfo.json.gpg")) @end lisp By adding multiple entries to @code{auth-sources} with a particular @@ -235,6 +245,16 @@ don't use a port entry, you match any Tramp method, as explained earlier. Since Tramp has about 88 connection methods, this may be necessary if you have an unusual (see earlier comment on those) setup. +The netrc format is directly translated into JSON, if you are into +that sort of thing. Just point to a JSON file with entries like this: + +@example +[ + @{ "machine": "yourmachine.com", "port": "http", + "login": "testuser", "password": "testpass" @} +] +@end example + @node Multiple GMail accounts with Gnus @chapter Multiple GMail accounts with Gnus @@ -335,25 +355,36 @@ Returns all the item labels of @var{collection} as a list. @defun secrets-create-item collection item password &rest attributes This function creates a new item in @var{collection} with label -@var{item} and password @var{password}. @var{attributes} are -key-value pairs set for the created item. The keys are keyword -symbols, starting with a colon. Example: +@var{item} and password @var{password}. The label @var{item} does not +have to be unique in @var{collection}. @var{attributes} are key-value +pairs set for the created item. The keys are keyword symbols, +starting with a colon. Example: @example -;;; The session "session", the label is "my item" -;;; and the secret (password) is "geheim" +;;; The session is "session", the label is "my item" +;;; and the secret (password) is "geheim". (secrets-create-item "session" "my item" "geheim" :method "sudo" :user "joe" :host "remote-host") @end example + +The key @code{:xdg:schema} determines the scope of the item to be +generated, i.e.@: for which applications the item is intended for. +This is just a string like "org.freedesktop.NetworkManager.Mobile" or +"org.gnome.OnlineAccounts", the other required keys are determined by +this. If no @code{:xdg:schema} is given, +"org.freedesktop.Secret.Generic" is used by default. @end defun @defun secrets-get-secret collection item -Return the secret of item labeled @var{item} in @var{collection}. -If there is no such item, return @code{nil}. +Return the secret of item labeled @var{item} in @var{collection}. If +there are several items labeled @var{item}, it is undefined which one +is returned. If there is no such item, return @code{nil}. @end defun @defun secrets-delete-item collection item -This function deletes item @var{item} in @var{collection}. +This function deletes item @var{item} in @var{collection}. If there +are several items labeled @var{item}, it is undefined which one is +deleted. @end defun The lookup attributes, which are specified during creation of a @@ -363,18 +394,20 @@ from a given secret item and they can be used for searching of items. @defun secrets-get-attribute collection item attribute Returns the value of key @var{attribute} of item labeled @var{item} in -@var{collection}. If there is no such item, or the item doesn't own -this key, the function returns @code{nil}. +@var{collection}. If there are several items labeled @var{item}, it +is undefined which one is returned. If there is no such item, or the +item doesn't own this key, the function returns @code{nil}. @end defun @defun secrets-get-attributes collection item Return the lookup attributes of item labeled @var{item} in -@var{collection}. If there is no such item, or the item has no -attributes, it returns @code{nil}. Example: +@var{collection}. If there are several items labeled @var{item}, it +is undefined which one is returned. If there is no such item, or the +item has no attributes, it returns @code{nil}. Example: @example (secrets-get-attributes "session" "my item") - @result{} ((:user . "joe") (:host ."remote-host")) + @result{} ((:user . "joe") (:host . "remote-host")) @end example @end defun @@ -412,19 +445,60 @@ then fall back to @file{~/.authinfo.gpg}. @uref{http://www.passwordstore.org,,The standard unix password manager} (or just @code{pass}) stores your passwords in -@code{gpg}-protected files following the Unix philosophy. +@code{gpg}-protected files following the Unix philosophy. The store +location (any directory) must be specified in the +@code{auth-source-pass-filename} variable which defaults to +@file{~/.password-store}. + +Emacs integration of @code{pass} follows the approach suggested by the +pass project itself for data organization to find data. In +particular, to store a password for the user @code{rms} on the host +@code{gnu.org} and port @code{22}, you should use one of the following +filenames. + +@table @file +@item gnu.org.gpg +No username or port in the filename means that any username and port +will match. + +@item gnu.org/rms.gpg +The username to match can be expressed as filename inside a directory +whose name matches the host. This is useful if the store has +passwords for several users on the same host. + +@item rms@@gnu.org.gpg +The username can also be expressed as a prefix, separated from the +host with an at-sign (@code{@@}). -Emacs integration of @code{pass} follows the first approach suggested -by the pass project itself for data organization to find data. This -means that the filename of the file containing the password for a user -on a particular host must contain the host name. The file itself must -contain the password on the first line, as well as a @code{username} -field containing the username on a subsequent line. A @code{port} -field can be used to differentiate the authentication data for several -services with the same username on the same host. +@item gnu.org:22.gpg +The port (aka. service) to match can only be expressed after the host and separated with a colon (@code{:}). The separator can be changed through the @code{auth-source-pass-port-separator} variable. + +@item gnu.org:22/rms.gpg + +@item rms@@gnu.org:22.gpg + +@item a/b/gnu.org.gpg +Entries can be stored in arbitrary directories. + +@item a/b/gnu.org/rms.gpg + +@item a/b/rms@@gnu.org.gpg + +@item a/b/gnu.org:22.gpg + +@item a/b/gnu.org:22/rms.gpg + +@item a/b/rms@@gnu.org:22.gpg +@end table + +If several entries match, the one matching the most items (where an +``item'' is one of username, port or host) is preferred. For example, +while searching for an entry matching the @code{rms} user on host +@code{gnu.org} and port @code{22}, then the entry +@file{gnu.org:22/rms.gpg} is preferred over @file{gnu.org.gpg}. Users of @code{pass} may also be interested in functionality provided -by other Emacs packages dealing with pass: +by other Emacs packages: @itemize @item @@ -435,6 +509,16 @@ by other Emacs packages dealing with pass: @uref{https://github.com/jabranham/helm-pass,,helm-pass}: helm interface for pass. @end itemize +@defvar auth-source-pass-filename +Set this variable to a string locating the password store on the disk. +Defaults to @file{~/.password-store}. +@end defvar + +@defvar auth-source-pass-port-separator +Set this variable to a string that should separate an host name from a +port in an entry. Defaults to @samp{:}. +@end defvar + @node Help for developers @chapter Help for developers diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi index 8ef08a36d8a..75bbae58b27 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -32717,7 +32717,7 @@ create an intermediate set. (while (> n 0) (if (oddp n) (setq count (1+ count))) - (setq n (lsh n -1))) + (setq n (ash n -1))) count)) @end smallexample @@ -32761,7 +32761,7 @@ routines are especially fast when dividing by an integer less than (let ((count 0)) (while (> n 0) (setq count (+ count (logand n 1)) - n (lsh n -1))) + n (ash n -1))) count)) @end smallexample @@ -32774,7 +32774,7 @@ uses. The @code{idivmod} function does an integer division, returning both the quotient and the remainder at once. Again, note that while it -might seem that @samp{(logand n 511)} and @samp{(lsh n -9)} are +might seem that @samp{(logand n 511)} and @samp{(ash n -9)} are more efficient ways to split off the bottom nine bits of @code{n}, actually they are less efficient because each operation is really a division by 512 in disguise; @code{idivmod} allows us to do the diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index bdeff22693f..1df9dce2279 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -197,7 +197,7 @@ modify this GNU manual.'' @titlepage @sp 10 -@center @titlefont{CC Mode 5.32} +@center @titlefont{CC Mode 5.34} @sp 2 @center A GNU Emacs mode for editing C and C-like languages @sp 2 @@ -387,7 +387,7 @@ was added in version 5.30. This manual describes @ccmode{} @comment The following line must appear on its own, so that the -version 5.32. +version 5.34. @comment Release.py script can update the version number automatically @ccmode{} supports the editing of C, C++, Objective-C, @@ -2140,7 +2140,10 @@ with @code{c-doc-comment-style}: Supply a variable or function in @code{c-doc-comment-style}. If it's a variable, it's prepended to @code{font-lock-keywords}. If it's a function, it's called at mode initialization and the result is prepended. For an example, see -@code{javadoc-font-lock-keywords} in @file{cc-fonts.el}. +@code{javadoc-font-lock-keywords} in @file{cc-fonts.el}. It is even +possible, to a limited extent, to fontify constructs inside a doc +comment with other faces. For an example, see pike autodoc comment +style towards the end of @file{cc-fonts-el}. If you add support for another doc comment style, please consider contributing it: send a note to @email{bug-cc-mode@@gnu.org}. @@ -5638,9 +5641,9 @@ any problems writing custom line-up functions for AWK mode. The calling convention for line-up functions is described fully in @ref{Custom Line-Up}. Roughly speaking, the return value is either an -offset itself (such as @code{+} or @code{[0]}) or it's @code{nil}, -meaning ``this function is inappropriate in this case; try a -different one''. @xref{c-offsets-alist}. +offset itself (such as @code{+} or @code{[0]}), another line-up +function, or it's @code{nil}, meaning ``this function is inappropriate +in this case - try a different one''. @xref{c-offsets-alist}. The subsections below describe all the standard line-up functions, categorized by the sort of token the lining-up centers around. For @@ -5995,6 +5998,125 @@ brace block. @comment ------------------------------------------------------------ +@defun c-lineup-2nd-brace-entry-in-arglist +@findex lineup-2nd-brace-entry-in-arglist (c-) +Line up the second entry of a brace block under the first, when the +first line is also contained in an arglist or an enclosing brace +@emph{on that line}. + +I.e. handle something like the following: + +@example +@group +set_line (line_t @{point_t@{0.4, 0.2@}, + point_t@{0.2, 0.5@}, @hereFn{brace-list-intro} + .....@}); + ^ enclosing parenthesis. +@end group +@end example + + +The middle line of that example will have a syntactic context with +three syntactic symbols, @code{arglist-cont-nonempty}, +@code{brace-list-intro}, and @code{brace-list-entry} (@pxref{Brace +List Symbols}). + +This function is intended for use in a list. If the construct being +analyzed isn't like the preceding, the function returns nil. +Otherwise it returns the function +@code{c-lineup-arglist-intro-after-paren}, which the caller then uses +to perform indentation. + +@workswith{} @code{brace-list-intro}. +@end defun + +@comment ------------------------------------------------------------ + +@defun c-lineup-class-decl-init-+ +@findex lineup-class-decl-init-+ (c-) +Line up the second entry of a class (etc.) initializer +@code{c-basic-offset} characters in from the identifier when: +@enumerate +@item +The type is a class, struct, union, etc. (but not an enum); +@item +There is a brace block in the type declaration, specifying it; and +@item +The first element of the initializer is on the same line as its +opening brace. +@end enumerate + +I.e. we have a construct like this: + +@example +@group +struct STR @{ + int i; float f; +@} str_1 = @{1, 1.7@}, + str_2 = @{2, + 3.1 @hereFn{brace-list-intro} + @}; + @sssTBasicOffset{} +@end group +@end example + + +Note that the syntactic context of the @code{brace-list-intro} line +also has a syntactic element with the symbol @code{brace-list-entry} +(@pxref{Brace List Symbols}). + +This function is intended for use in a list. If the above structure +isn't present, the function returns nil, allowing a different offset +specification to indent the line. + +@workswith{} @code{brace-list-intro}. +@end defun + +@comment ------------------------------------------------------------ + +@defun c-lineup-class-decl-init-after-brace +@findex lineup-class-decl-init-after-brace (c-) +Line up the second entry of a class (etc.) initializer after its +opening brace when: +@enumerate +@item +The type is a class, struct, union, etc. (but not an enum); +@item +There is a brace block in the type declaration, specifying it; and +@item +The first element of the initializer is on the same line as its +opening brace. +@end enumerate + +I.e. we have a construct like this: + +@example +@group +struct STR @{ + int i; float f; +@} str_1 = @{1, 1.7@}, + str_2 = @{2, + 3.1 @hereFn{brace-list-intro} + @}; +@end group +@end example + + +Note that the syntactic context of the @code{brace-list-intro} line +also has a syntactic element with the symbol @code{brace-list-entry} +(@pxref{Brace List Symbols}). Also note that this function works by +returning the symbol @code{c-lineup-arglist-intro-after-paren}, which +the caller then uses to perform the indentation. + +This function is intended for use in a list. If the above structure +isn't present, the function returns nil, allowing a different offset +specification to indent the line. + +@workswith{} @code{brace-list-intro}. +@end defun + +@comment ------------------------------------------------------------ + @defun c-lineup-multi-inher @findex lineup-multi-inher @r{(c-)} Line up the classes in C++ multiple inheritance clauses and member @@ -7309,13 +7431,15 @@ could amend your C++ Mode hook like this: @emph{How do I stop my C++ lambda expressions being indented way over to the right?} -Change the offset associated with @code{inlambda} from its default, -the function @code{c-lineup-inexpr-block}, to 0. For example, if you -are setting offsets in a hook function you might include the following -line: +This is now the default, so you don't need to do anything. To restore +the previous default, indenting lambda expressions to the right of the +constructs which introduce them, change the offset associated with +@code{inlambda} from 0 to @code{c-lineup-inexpr-block}. For example, +if you are setting offsets in a hook function you might include the +following line: @example -(c-set-offset 'inlambda 0) +(c-set-offset 'inlambda 'c-lineup-inexpr-block) @end example For details of the different ways you can make this setting, diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 6ce0b72aa5f..ee73c65b789 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -784,7 +784,7 @@ default. Some examples: (cl-deftype null () '(satisfies null)) ; predefined (cl-deftype list () '(or null cons)) ; predefined (cl-deftype unsigned-byte (&optional bits) - (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits))))) + (list 'integer 0 (if (eq bits '*) bits (1- (ash 1 bits))))) (unsigned-byte 8) @equiv{} (integer 0 255) (unsigned-byte) @equiv{} (integer 0 *) unsigned-byte @equiv{} (integer 0 *) @@ -1359,7 +1359,8 @@ Because of the nature of macros, @code{cl-macrolet} is always lexically scoped. The @code{cl-macrolet} binding will affect only calls that appear physically within the body @var{forms}, possibly after expansion of other macros in the -body. +body. Calls of @code{cl-macrolet} bound macros are expanded in the +global environment. @end defmac @defmac cl-symbol-macrolet (bindings@dots{}) forms@dots{} @@ -1709,9 +1710,9 @@ but surrounds the loop with an implicit @code{nil} block. The body is executed with @var{var} bound to the integers from zero (inclusive) to @var{count} (exclusive), in turn. Then @c FIXME lispref does not state this part explicitly, could move this there. -the @code{result} form is evaluated with @var{var} bound to the total +the @var{result} form is evaluated with @var{var} bound to the total number of iterations that were done (i.e., @code{(max 0 @var{count})}) -to get the return value for the loop form. +to get the return value for the loop form. Use of @var{result} is deprecated. @end defmac @defmac cl-do-symbols (var [obarray [result]]) forms@dots{} @@ -4149,7 +4150,7 @@ package, @code{cl-typep} simply looks for a function called only if they used the default predicate name. @item :include -This option implements a very limited form of C++-style inheritance. +This option implements a very limited form of C@t{++}-style inheritance. The argument is the name of another structure type previously created with @code{cl-defstruct}. The effect is to cause the new structure type to inherit all of the included structure's slots @@ -4194,6 +4195,10 @@ of a @code{person}, plus extra slots that are specific to astronauts. Operations that work on people (like @code{person-name}) work on astronauts just like other people. +@item :noinline +If this option is present, this structure's functions will not be +inlined, even functions that normally would. + @item :print-function In full Common Lisp, this option allows you to specify a function that is called to print an instance of the structure type. The diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi index b8e1ad459d1..1e3414563f3 100644 --- a/doc/misc/dired-x.texi +++ b/doc/misc/dired-x.texi @@ -92,7 +92,6 @@ For @file{dired-x.el} as distributed with GNU Emacs @value{EMACSVER}. * Introduction:: * Installation:: * Omitting Files in Dired:: -* Local Variables:: * Shell Command Guessing:: * Virtual Dired:: * Advanced Mark Commands:: @@ -478,77 +477,6 @@ Loading @file{dired-x.el} will install Dired Omit by putting call @code{dired-extra-startup}, which in turn calls @code{dired-omit-startup} in your @code{dired-mode-hook}. -@node Local Variables -@chapter Local Variables for Dired Directories - -@cindex Local Variables for Dired Directories -@vindex dired-local-variables-file -@vindex dired-enable-local-variables -@noindent -This Dired-X feature is obsolete as of Emacs 24.1. The standard Emacs -directory local variables mechanism (@pxref{Directory -Variables,,,emacs,The GNU Emacs manual}) replaces it. For an example of -the new mechanisms, @pxref{Omitting Variables}. - -When Dired visits a directory, it looks for a file whose name is the -value of variable @code{dired-local-variables-file} (default: @file{.dired}). -If such a file is found, Dired will temporarily insert it into the Dired -buffer and run @code{hack-local-variables}. - -@noindent -For example, if the user puts - -@example -Local Variables: -dired-actual-switches: "-lat" -dired-omit-mode: t -End: -@end example - -@noindent -into a file called @file{.dired} in a directory then when that directory is -viewed it will be - -@enumerate -@item -sorted by date -@item -omitted automatically -@end enumerate - -@noindent -You can set @code{dired-local-variables-file} to @code{nil} to suppress this. -The value of @code{dired-enable-local-variables} controls if and how these -local variables are read. This variable exists so that it may override the -default value of @code{enable-local-variables}. - -@noindent -Please see the GNU Emacs Manual to learn more about local variables. -@xref{File Variables,Local Variables in Files,Local Variables in -Files,emacs,The GNU Emacs Manual}. - -@noindent -The following variables affect Dired Local Variables - -@table @code -@vindex dired-local-variables-file -@item dired-local-variables-file -Default: @code{".dired"} - -If non-@code{nil}, file name for local variables for Dired. If Dired finds a -file with that name in the current directory, it will temporarily insert it -into the Dired buffer and run @code{hack-local-variables}. - -@vindex dired-enable-local-variables -@item dired-enable-local-variables -Default: @code{t} - -Controls the use of local-variables lists in Dired. This variable -temporarily overrides the value of @code{enable-local-variables} when -the Dired Local Variables are hacked. It takes the same values as that -variable. A value of @code{nil} means to ignore any Dired Local Variables. -@end table - @node Shell Command Guessing @chapter Shell Command Guessing @cindex Guessing shell commands for files. diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi index 4edb53d9533..7ab386c97a4 100644 --- a/doc/misc/ede.texi +++ b/doc/misc/ede.texi @@ -1824,7 +1824,7 @@ This class implements the @code{ede-cpp-root} project type. @table @code @item :include-path Type: @code{list} @* -Default Value: @code{(quote ("/include" "../include/"))} +Default Value: @code{("/include" "../include/")} The default locate function expands filenames within a project. If a header file (.h, .hh, etc.)@: name is expanded, and @@ -2262,14 +2262,14 @@ The variable GNUSTEP_INSTALLATION_DOMAIN is set at this value. @item :preamble Type: @code{(or null list)} @* -Default Value: @code{(quote ("GNUmakefile.preamble"))} +Default Value: @code{("GNUmakefile.preamble")} The auxiliary makefile for additional variables. Included just before the specific target files. @item :postamble Type: @code{(or null list)} @* -Default Value: @code{(quote ("GNUmakefile.postamble"))} +Default Value: @code{("GNUmakefile.postamble")} The auxiliary makefile for additional rules. Included just after the specific target files. diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi index 443aae3dbd5..4c698eb7e2c 100644 --- a/doc/misc/ediff.texi +++ b/doc/misc/ediff.texi @@ -1147,7 +1147,7 @@ file (unlike what the @code{patch} utility would usually do). Instead, the source file retains its name and the result of applying the patch is placed in a temporary file that has the suffix @file{_patched} attached. Generally, this applies to files that are handled using black magic, such -as special file handlers (ange-ftp and some compression and encryption +as special file name handlers (ange-ftp and some compression and encryption packages also use this method). Regular files are treated by the @code{patch} utility in the usual manner, @@ -2421,7 +2421,7 @@ Boris Goldowsky <boris@@cs.rochester.edu> made it possible to highlight fine differences in Ediff buffers. Alastair Burt <burt@@dfki.uni-kl.de> ported Ediff to XEmacs, Eric Freudenthal <freudent@@jan.ultra.nyu.edu> made it work with VC, Marc Paquette <marcpa@@cam.org> wrote the -toolbar support package for Ediff, and Hrvoje Niksic <hniksic@@xemacs.org> +toolbar support package for Ediff, and Hrvoje Nikšić <hniksic@@xemacs.org> adapted it to the Emacs customization package. Many people provided help with bug reports, feature suggestions, and advice. diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi index 4c0d17f9a7b..485776e1c73 100644 --- a/doc/misc/efaq.texi +++ b/doc/misc/efaq.texi @@ -1570,38 +1570,68 @@ exhibits all the colors Emacs knows about on the current display. Syntax highlighting is on by default since version 22.1. +@cindex direct color in terminals Emacs 26.1 and later support direct color mode in terminals. If Emacs finds Terminfo capabilities @samp{setb24} and @samp{setf24}, 24-bit direct color mode is used. The capability strings are expected to take one 24-bit pixel value as argument and transform the pixel to a string that can be used to send 24-bit colors to the terminal. -There aren't yet any standard terminal type definitions that would -support the capabilities, but Emacs can be invoked with a custom -definition as shown below. +Standard terminal definitions don't support these capabilities and +therefore custom definition is needed. @example -$ cat terminfo-24bit.src +$ cat terminfo-custom.src -# Use colon separators. -xterm-24bit|xterm with 24-bit direct color mode, +xterm-emacs|xterm with 24-bit direct color mode for Emacs, use=xterm-256color, - setb24=\E[48:2:%p1%@{65536@}%/%d:%p1%@{256@}%/%@{255@}%&%d:%p1%@{255@}%&%dm, - setf24=\E[38:2:%p1%@{65536@}%/%d:%p1%@{256@}%/%@{255@}%&%d:%p1%@{255@}%&%dm, -# Use semicolon separators. -xterm-24bits|xterm with 24-bit direct color mode, - use=xterm-256color, - setb24=\E[48;2;%p1%@{65536@}%/%d;%p1%@{256@}%/%@{255@}%&%d;%p1%@{255@}%&%dm, - setf24=\E[38;2;%p1%@{65536@}%/%d;%p1%@{256@}%/%@{255@}%&%d;%p1%@{255@}%&%dm, + setb24=\E[48\:2\:\:%p1%@{65536@}%/%d\:%p1%@{256@}%/%@{255@}%&\ + %d\:%p1%@{255@}%&%dm, + setf24=\E[38\:2\:\:%p1%@{65536@}%/%d\:%p1%@{256@}%/%@{255@}%&\ + %d\:%p1%@{255@}%&%dm, + +$ tic -x -o ~/.terminfo terminfo-custom.src + +$ TERM=xterm-emacs emacs -nw +@end example + +@cindex 24-bit direct color mode +Emacs 27.1 and later support Terminfo capability @samp{RGB} for +detecting 24-bit direct color mode. Multiple standard terminal +definitions support this capability. + +@example +$ TERM=xterm-direct infocmp | grep seta[bf] + + setab=\E[%?%p1%@{8@}%<%t4%p1%d%e48\:2\:\:%p1%@{65536@}%/\ + %d\:%p1%@{256@}%/%@{255@}%&%d\:%p1%@{255@}%&%d%;m, + setaf=\E[%?%p1%@{8@}%<%t3%p1%d%e38\:2\:\:%p1%@{65536@}%/\ + %d\:%p1%@{256@}%/%@{255@}%&%d\:%p1%@{255@}%&%d%;m, + +$ TERM=xterm-direct emacs -nw +@end example + +If your terminal is incompatible with XTerm, you may have to use +another @env{TERM} definition. Any terminal whose name includes +@samp{direct} should be a candidate. The @command{toe} command can be +used to find out which of these are installed on your system: -$ tic -x -o ~/.terminfo terminfo-24bit.src +@example +$ toe | grep '\-direct' -$ TERM=xterm-24bit emacs -nw +konsole-direct konsole with direct-color indexing +vte-direct vte with direct-color indexing +st-direct st with direct-color indexing +xterm-direct2 xterm with direct-color indexing (old) +xterm-direct xterm with direct-color indexing @end example -Currently there's no standard way to determine whether a terminal -supports direct color mode. If such standard arises later on, support -for @samp{setb24} and @samp{setf24} may be removed. +Terminals with @samp{RGB} capability treat pixels #000001 - #000007 as +indexed colors to maintain backward compatibility with applications +that are unaware of direct color mode. Therefore the seven darkest +blue shades may not be available. If this is a problem, you can +always use custom terminal definition with @samp{setb24} and +@samp{setf24}. @node Debugging a customization file @section How do I debug a @file{.emacs} file? @@ -1975,9 +2005,18 @@ or by invoking @code{server-start} from @file{.emacs}: (if (@var{some conditions are met}) (server-start)) @end lisp -When this is done, Emacs creates a Unix domain socket named -@file{server} in @file{/tmp/emacs@var{userid}}. See -@code{server-socket-dir}. +When this is done, Emacs by default creates a Unix domain socket named +@file{server} in a well-known directory, typically +@file{$XDG_RUNTIME_DIR/emacs} if Emacs is running under an X Window System +desktop and @file{$TMPDIR/emacs@var{userid}} otherwise. See the variable +@code{server-socket-dir}. Traditionally, Emacs used +@file{$TMPDIR/emacs@var{userid}} even when running under an X desktop; +if you prefer this traditional (and less-secure) behavior, you +can set the environment variable @env{EMACS_SOCKET_NAME} to +@samp{$TMPDIR/emacs@var{userid}/server} before invoking Emacs and +@samp{emacsclient}, although it will be your responsibility to create +the directory @samp{$TMPDIR/emacs@var{userid}} with appropriate +ownership and permissions. To get your news reader, mail reader, etc., to invoke @samp{emacsclient}, try setting the environment variable @code{EDITOR} @@ -2958,7 +2997,7 @@ Emacs compiled on a 64-bit machine can handle much larger buffers. @cindex Shell buffer, echoed commands and @samp{^M} in @cindex Echoed commands in @code{shell-mode} -Try typing @kbd{M-x shell-strip-ctrl-m @key{RET}} while in @code{shell-mode} to +Try typing @kbd{M-x comint-strip-ctrl-m @key{RET}} while in @code{shell-mode} to make them go away. If that doesn't work, you have several options: For @code{tcsh}, put this in your @file{.cshrc} (or @file{.tcshrc}) @@ -3011,7 +3050,7 @@ characters from the buffer by adding this to your @file{.emacs} init file: @smalllisp -(add-hook 'comint-output-filter-functions 'shell-strip-ctrl-m) +(add-hook 'comint-output-filter-functions #'comint-strip-ctrl-m) @end smalllisp On a related note: if your shell is echoing your input line in the shell @@ -3733,7 +3772,7 @@ to bind the key is in the kill ring, and can be yanked into your command are required. For example, @lisp -(global-set-key (quote [f1]) (quote help-for-help)) +(global-set-key [f1] 'help-for-help) @end lisp @noindent @@ -3744,7 +3783,7 @@ For example, in TeX mode, a local binding might be @lisp (add-hook 'tex-mode-hook (lambda () - (local-set-key (quote [f1]) (quote help-for-help)))) + (local-set-key [f1] 'help-for-help))) @end lisp @@ -4538,7 +4577,7 @@ these systems, you should configure @code{movemail} to use @code{flock}. @c isaacson@@seas.upenn.edu Ron Isaacson says: When you hit -@kbd{r} to reply in Rmail, by default it CCs all of the original +@kbd{r} to reply in Rmail, by default it Ccs all of the original recipients (everyone on the original @samp{To} and @samp{CC} lists). With a prefix argument (i.e., typing @kbd{C-u} before @kbd{r}), it replies only to the sender. However, going through the whole diff --git a/doc/misc/emacs-gnutls.texi b/doc/misc/emacs-gnutls.texi index aae583c641c..add79d12e42 100644 --- a/doc/misc/emacs-gnutls.texi +++ b/doc/misc/emacs-gnutls.texi @@ -179,17 +179,35 @@ Just use @code{open-protocol-stream} or @code{open-network-stream} You should not have to use the @file{gnutls.el} functions directly. But you can test them with @code{open-gnutls-stream}. -@defun open-gnutls-stream name buffer host service &optional nowait +@defun open-gnutls-stream name buffer host service &optional parameters This function creates a buffer connected to a specific @var{host} and -@var{service} (port number or service name). The parameters and their -syntax are the same as those given to @code{open-network-stream} -(@pxref{Network,, Network Connections, elisp, The Emacs Lisp Reference -Manual}). The connection process is called @var{name} (made unique if -necessary). This function returns the connection process. - -The @var{nowait} parameter means that the socket should be -asynchronous, and the connection process will be returned to the -caller before TLS negotiation has happened. +@var{service} (port number or service name). The mandatory arguments +and their syntax are the same as those given to +@code{open-network-stream} (@pxref{Network,, Network Connections, +elisp, The Emacs Lisp Reference Manual}). The connection process is +called @var{name} (made unique if necessary). This function returns +the connection process. + +The optional @var{parameters} argument is a list of keywords and +values. The only keywords which currently have any effect are +@code{:client-certificate} and @code{:nowait}. + +Passing @w{@code{:client certificate t}} triggers looking up of client +certificates matching @var{host} and @var{service} using the +@file{auth-source} library. Any resulting client certificates are passed +down to the lower TLS layers. The format used by @file{.authinfo} to +specify the per-server keys is described in @ref{Help for +users,,auth-source, auth, Emacs auth-source Library}. + +Passing @w{@code{:nowait t}} means that the socket should be asynchronous, +and the connection process will be returned to the caller before TLS +negotiation has happened. + +For historical reasons @var{parameters} can also be a symbol, which is +interpreted the same as passing a list containing @code{:nowait} and +the value of that symbol. + +Example calls: @lisp ;; open a HTTPS connection diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi index 373bdeb9013..6e95013c186 100644 --- a/doc/misc/emacs-mime.texi +++ b/doc/misc/emacs-mime.texi @@ -1,7 +1,5 @@ \input texinfo -@include gnus-overrides.texi - @setfilename ../../info/emacs-mime.info @settitle Emacs MIME Manual @include docstyle.texi @@ -404,12 +402,12 @@ variable will cause @samp{text/html} parts to be treated as attachments. @item mm-text-html-renderer @vindex mm-text-html-renderer -This selects the function used to render @acronym{HTML}. The predefined -renderers are selected by the symbols @code{shr}, @code{gnus-w3m}, -@code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more -information about emacs-w3m}, @code{links}, @code{lynx}, -@code{w3m-standalone} or @code{html2text}. If @code{nil} use an -external viewer. You can also specify a function, which will be +This selects the function used to render @acronym{HTML}. The +predefined renderers are selected by the symbols @code{shr}, +@code{gnus-w3m}, @code{w3m}@footnote{See +@uref{http://emacs-w3m.namazu.org/} for more information about +emacs-w3m}, @code{links}, @code{lynx}, @code{w3m-standalone} or +@code{html2text}. You can also specify a function, which will be called with a @acronym{MIME} handle as the argument. @item mm-html-inhibit-images @@ -710,7 +708,7 @@ RFC 822 (or later) date when the part was read (@code{Content-Disposition}). @item recipients Who to encrypt/sign the part to. This field is used to override any -auto-detection based on the To/CC headers. +auto-detection based on the To/Cc headers. @item sender Identity used to sign the part. This field is used to override the @@ -1207,8 +1205,8 @@ plaintext name. @example (mail-header-parse-address - "Hrvoje Niksic <hniksic@@srce.hr>") -@result{} ("hniksic@@srce.hr" . "Hrvoje Niksic") + "Hrvoje Nikšić <hniksic@@srce.hr>") +@result{} ("hniksic@@srce.hr" . "Hrvoje Nikšić") @end example @item mail-header-parse-addresses @@ -1218,8 +1216,8 @@ the one described above. @example (mail-header-parse-addresses - "Hrvoje Niksic <hniksic@@srce.hr>, Steinar Bang <sb@@metis.no>") -@result{} (("hniksic@@srce.hr" . "Hrvoje Niksic") + "Hrvoje Nikšić <hniksic@@srce.hr>, Steinar Bang <sb@@metis.no>") +@result{} (("hniksic@@srce.hr" . "Hrvoje Nikšić") ("sb@@metis.no" . "Steinar Bang")) @end example @@ -1526,45 +1524,54 @@ many mailers don't support it. @xref{rfc2231}. @section time-date While not really a part of the @acronym{MIME} library, it is convenient to -document this library here. It deals with parsing @code{Date} headers +document time conversion functions often used when parsing @code{Date} headers and manipulating time. (Not by using tesseracts, though, I'm sorry to say.) -These functions convert between five formats: A date string, an Emacs -time structure, a decoded time list, a second number, and a day number. +These functions convert between five formats: A date string, a Lisp +timestamp, a decoded time list, a second number, and a day number. Here's a bunch of time/date/second/day examples: @example (parse-time-string "Sat Sep 12 12:21:54 1998 +0200") -@result{} (54 21 12 12 9 1998 6 nil 7200) +@result{} (54 21 12 12 9 1998 6 -1 7200) -(date-to-time "Sat Sep 12 12:21:54 1998 +0200") -@result{} (13818 19266) +(encode-time (date-to-time "Sat Sep 12 12:21:54 1998 +0200") + 1000000) +@result{} (905595714000000 . 1000000) -(parse-iso8601-time-string "1998-09-12T12:21:54+0200") -@result{} (13818 19266) +(encode-time (parse-iso8601-time-string "1998-09-12T12:21:54+0200") + 1000000) +@result{} (905595714000000 . 1000000) -(float-time '(13818 19266)) +(float-time '(905595714000000 . 1000000)) @result{} 905595714.0 -(seconds-to-time 905595714.0) -@result{} (13818 19266 0 0) +(encode-time 905595714.0 1000000) +@result{} (905595714000000 . 1000000) -(time-to-days '(13818 19266)) +(time-to-days '(905595714000000 . 1000000)) @result{} 729644 -(days-to-time 729644) -@result{} (961933 512) +(encode-time (days-to-time 729644) 1000000) +@result{} (63041241600000000 . 1000000) -(time-since '(13818 19266)) -@result{} (6797 9607 984839 247000) +(encode-time (time-since '(905595714000000 . 1000000)) + 1000000) +@result{} (631963244775642171 . 1000000000) -(time-less-p '(13818 19266) '(13818 19145)) +(time-less-p '(905595714000000 . 1000000) + '(905595593000000000 . 1000000000)) @result{} nil -(time-subtract '(13818 19266) '(13818 19145)) -@result{} (0 121) +(time-equal-p '(905595593000000000 . 1000000000) + '(905595593000000 . 1000000 )) +@result{} t + +(time-subtract '(905595714000000 . 1000000) + '(905595593000000000 . 1000000000)) +@result{} (121000000000 . 1000000000) (days-between "Sat Sep 12 12:21:54 1998 +0200" "Sat Sep 07 12:21:54 1998 +0200") @@ -1573,13 +1580,13 @@ Here's a bunch of time/date/second/day examples: (date-leap-year-p 2000) @result{} t -(time-to-day-in-year '(13818 19266)) +(time-to-day-in-year '(905595714000000 . 1000000)) @result{} 255 (time-to-number-of-days (time-since (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT"))) -@result{} 4314.095589286675 +@result{} 6472.722661506652 @end example And finally, we have @code{safe-date-to-time}, which does the same as @@ -1594,22 +1601,24 @@ An RFC 822 (or similar) date string. For instance: @code{"Sat Sep 12 12:21:54 1998 +0200"}. @item time -An internal Emacs time. For instance: @code{(13818 26466 0 0)}. +A Lisp timestamp. +For instance: @code{(905595714000000 . 1000000)}. @item seconds -A floating point representation of the internal Emacs time. For -instance: @code{905595714.0}. +An integer or floating point count of seconds. For instance: +@code{905595714.0}, @code{905595714}. @item days An integer number representing the number of days since 00000101. For instance: @code{729644}. @item decoded time -A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 t +A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 nil 7200)}. @end table -All the examples above represent the same moment. +All the examples above represent the same moment, except that +@var{days} represents the day containing the moment. These are the functions available: @@ -1620,8 +1629,9 @@ Take a date and return a time. @item float-time Take a time and return seconds. (This is a built-in function.) -@item seconds-to-time -Take seconds and return a time. +@item encode-time +Take seconds (and other ways to represent time, notably decoded time +lists), and return a time. @item time-to-days Take a time and return days. @@ -1643,6 +1653,10 @@ return a ``zero'' time. Take two times and say whether the first time is less (i.e., earlier) than the second time. (This is a built-in function.) +@item time-equal-p +Check whether two time values are equal. The time values need not be +in the same format. (This is a built-in function.) + @item time-since Take a time and return a time saying how long it was since that time. @@ -1847,11 +1861,23 @@ Interface functions: @table @code @item mailcap-parse-mailcaps @findex mailcap-parse-mailcaps +@vindex mailcap-prefer-mailcap-viewers Parse the @file{~/.mailcap} file. @item mailcap-mime-info Takes a @acronym{MIME} type as its argument and returns the matching viewer. +The @code{mailcap-prefer-mailcap-viewers} variable controls which +viewer is chosen. The default non-@code{nil} value means that +settings from @file{~/.mailcap} is preferred over system-wide or +Emacs-provided viewer settings. + +If @code{nil}, Emacs-provided viewer settings have precedence. Next, +the most specific viewer has precedence over less specific settings, +no matter if they're system-provided or private, so @samp{image/gif} +in @file{/etc/mailcap} will ``win'' over an @samp{image/*} setting in +@file{~/.mailcap}. + @end table diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi index d70eca81f9c..d2d86555e3c 100644 --- a/doc/misc/ert.texi +++ b/doc/misc/ert.texi @@ -273,9 +273,11 @@ moving point to it and typing @kbd{@key{RET}} jumps to its definition. @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. +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. @kindex l@r{, in ert results buffer} @kbd{l} shows the list of @code{should} forms executed in the test. @@ -321,6 +323,20 @@ summary as shown below: emacs -batch -l ert -f ert-summarize-tests-batch-and-exit output.log @end example +@vindex ert-quiet +By default, ERT in batch mode is quite verbose, printing a line with +result after each test. This gives you progress information: how many +tests have been executed and how many there are. However, in some +cases this much output may be undesirable. In this case, set +@code{ert-quiet} variable to a non-nil value: + +@example +emacs -batch -l ert -l my-tests.el \ + --eval "(let ((ert-quiet t)) (ert-run-tests-batch-and-exit))" +@end example + +In quiet mode ERT prints only unexpected results and summary. + If ERT is not part of your Emacs distribution, you may need to use @code{-L /path/to/ert/} so that Emacs can find it. You may need additional @code{-L} flags to ensure that @code{my-tests.el} and all the diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index 712780e3352..716b4b7a50d 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -329,7 +329,7 @@ List subprocesses of the Emacs process, if any, using the function @item kill @cmindex kill Kill processes. Takes a PID or a process object and an optional -signal specifier. +signal specifier which can either be a number or a signal name. @item listify @cmindex listify @@ -499,15 +499,14 @@ be directories @emph{and} files. Eshell provides predefined completions for the built-in functions and some common external commands, and you can define your own for any command. -Eshell completion also works for lisp forms and glob patterns. If the -point is on a lisp form, then @key{TAB} will behave similarly to completion -in @code{elisp-mode} and @code{lisp-interaction-mode}. For glob -patterns, If there are few enough possible completions of the patterns, -they will be cycled when @key{TAB} is pressed, otherwise it will be removed -from the input line and the possible completions will be listed. +Eshell completion also works for lisp forms and glob patterns. If the point is +on a lisp form, then @key{TAB} will behave similarly to completion in +@code{elisp-mode} and @code{lisp-interaction-mode}. For glob patterns, the +pattern will be removed from the input line, and replaced by the +completion. -If you want to see the entire list of possible completions when it's -below the cycling threshold, press @kbd{M-?}. +If you want to see the entire list of possible completions (e.g. when it's +below the @code{completion-cycle-threshold}), press @kbd{M-?}. @subsection pcomplete Pcomplete, short for programmable completion, is the completion diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi index d2c60b0abf7..8dc58e84257 100644 --- a/doc/misc/eww.texi +++ b/doc/misc/eww.texi @@ -85,6 +85,10 @@ searched via @code{eww-search-prefix}. The default search engine is either prefix the file name with @code{file://} or use the command @kbd{M-x eww-open-file}. + If you invoke @code{eww} with a prefix argument, as in @w{@kbd{C-u +M-x eww}}, it will create a new EWW buffer instead of reusing the +default one, which is normally called @file{*eww*}. + @findex eww-quit @findex eww-reload @findex eww-copy-page-url @@ -125,9 +129,10 @@ HTML-specified colors or not. This sets the @code{shr-use-colors} variable. @vindex eww-download-directory @kindex d @cindex Download - A URL under the point can be downloaded with @kbd{d} -(@code{eww-download}). The file will be written to the directory -specified in @code{eww-download-directory} (Default: @file{~/Downloads/}). + A URL can be downloaded with @kbd{d} (@code{eww-download}). This +will download the link under point if there is one, or else the URL of +the current page. The file will be written to the directory specified +in @code{eww-download-directory} (default: @file{~/Downloads/}). @findex eww-back-url @findex eww-forward-url @@ -262,6 +267,16 @@ contrast. If that is still too low for you, you can customize the variables @code{shr-color-visible-distance-min} and @code{shr-color-visible-luminance-min} to get a better contrast. +@vindex shr-discard-aria-hidden +@cindex @code{aria-hidden}, HTML attribute + The HTML attribute @code{aria-hidden} is meant to tell screen +readers to ignore a tag's contents. You can customize the variable +@code{shr-discard-aria-hidden} to tell @code{shr} to ignore such tags. +This can be useful when using a screen reader on the output of +@code{shr} (e.g., on EWW buffer text). It can be useful even when not +using a screen reader, since web authors often put this attribute on +non-essential decorative elements. + @cindex Desktop Support @cindex Saving Sessions In addition to maintaining the history at run-time, EWW will also diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi index 2689b5d8cd9..ebb89c32036 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 0.3 -@set UPDATED April 2004 +@set VERSION 1.0 +@set UPDATED June 2018 @settitle GNU Flymake @value{VERSION} @include docstyle.texi @syncodeindex pg cp @@ -37,7 +37,7 @@ modify this GNU manual.'' @titlepage @title GNU Flymake @subtitle for version @value{VERSION}, @value{UPDATED} -@author Pavel Kobiakov(@email{pk_at_work@@yahoo.com}) and João Távora. +@author João Távora and Pavel Kobiakov(@email{pk_at_work@@yahoo.com}). @page @vskip 0pt plus 1filll @insertcopying @@ -84,8 +84,8 @@ Syntax check is done ``on-the-fly''. It is started whenever @code{flymake-start-on-flymake-mode} is nil; @item -a newline character is added to the buffer, unless -@code{flymake-start-syntax-check-on-newline} is nil; +the buffer is saved, unless @code{flymake-start-on-save-buffer} is +nil; @item some changes were made to the buffer more than @code{0.5} seconds ago @@ -95,9 +95,15 @@ some changes were made to the buffer more than @code{0.5} seconds ago Syntax check can also be started manually by typing the @kbd{M-x flymake-start @key{RET}} command. +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. + @code{flymake-goto-next-error} and @code{flymake-goto-prev-error} are commands that allow easy navigation to the next/previous erroneous -line, respectively. If might be a good idea to map them to @kbd{M-n} +regions, respectively. If 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 @@ -212,14 +218,14 @@ If any changes are made to the buffer, syntax check is automatically started after this many seconds, unless the user makes another change, which resets the timer. -@item flymake-start-syntax-check-on-newline -A boolean flag indicating whether to start syntax check immediately -after a newline character is inserted into the buffer. - @item flymake-start-on-flymake-mode A boolean flag indicating whether to start syntax check immediately after enabling @code{flymake-mode}. +@item flymake-start-on-save-buffer +A boolean flag indicating whether to start syntax check after saving +the buffer. + @item flymake-error A custom face for highlighting regions for which an error has been reported. @@ -275,54 +281,61 @@ The following sections discuss each approach in detail. @cindex customizing error types @cindex error types, customization -@vindex flymake-diagnostic-types-alist -The variable @code{flymake-diagnostic-types-alist} is looked up by -Flymake every time an annotation for a diagnostic is created in the -buffer. Specifically, this variable holds a table of correspondence -between symbols designating diagnostic types and an additional -sub-table of properties pertaining to each diagnostic type. +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}). -Both tables are laid out in association list (@pxref{Association -Lists,,, elisp, The Emacs Lisp Reference Manual}) format, and thus can -be conveniently accessed with the functions of the @code{assoc} -family. - -You can use any symbol-value association in the properties sub-table, -but some symbols have special meaning as to where and how Flymake -presents the diagnostic: +The following properties can be set: @itemize @item @cindex bitmap of diagnostic -@code{bitmap}, an image displayed in the fringe according to +@code{flymake-bitmap}, an image displayed in the fringe according to @code{flymake-fringe-indicator-position}. The value actually follows the syntax of @code{flymake-error-bitmap} (@pxref{Customizable variables}). It is overridden by any @code{before-string} overlay property. @item -@cindex severity of diagnostic -@code{severity} is a non-negative integer specifying the diagnostic's -severity. The higher the value, the more serious is the error. If -the overlay property @code{priority} is not specified, @code{severity} -is used to set it and help sort overlapping overlays. +@code{flymake-overlay-control}, an alist ((@var{OVPROP} . @var{VALUE}) +@var{...}) of further properties used to affect the appearance of +Flymake annotations. With the exception of @code{category} and +@code{evaporate}, these properties are applied directly to the created +overlay (@pxref{Overlay Properties,,, elisp, The Emacs Lisp Reference +Manual}). -@item -Every property pertaining to overlays (@pxref{Overlay Properties,,, -elisp, The Emacs Lisp Reference Manual}), except @code{category} and -@code{evaporate}. These properties are used to affect the appearance -of Flymake annotations. +As an example, here's how to make diagnostics of the type @code{:note} +stand out more prominently: -As an example, here's how to make errors (diagnostics of the type -@code{:error}) stand out even more prominently in the buffer, by -raising the characters using a @code{display} overlay property. +@example +(push '(face . highlight) (get :note 'flymake-overlay-control)) +@end example + +If you push another alist entry in front, it overrides the previous +one. So this effectively removes the face from @code{:note} +diagnostics: @example -(push '(display . (raise 1.2)) - (cdr (assoc :error flymake-diagnostic-types-alist))) +(push '(face . nil) (get :note 'flymake-overlay-control)) @end example +To restore the original look for @code{:note} types, empty or remove +its @code{flymake-overlay-control} property: + +@example +(put :note 'flymake-overlay-control '()) +@end example + +@item +@cindex severity of diagnostic +@code{flymake-severity} is a non-negative integer specifying the +diagnostic's severity. The higher the value, the more serious is the +error. If the overlay property @code{priority} is not specified in +@code{flymake-overlay-control}, @code{flymake-severity} is used to set +it and help sort overlapping overlays. + @item @vindex flymake-category @code{flymake-category} is a symbol whose property list is considered @@ -333,32 +346,29 @@ the default for missing values of any other properties. @vindex flymake-error @vindex flymake-warning @vindex flymake-note -Three default diagnostic types, @code{:error}, @code{:warning} and -@code{:note} are predefined in -@code{flymake-diagnostic-types-alist}. By default each lists a single +Three default diagnostic types are predefined: @code{:error}, +@code{:warning}, and @code{:note}. By default, each one of them has a @code{flymake-category} property whose value is, respectively, the -symbols @code{flymake-error}, @code{flymake-warning} and +category symbol @code{flymake-error}, @code{flymake-warning} and @code{flymake-note}. -These category symbols' plists is where the values of customizable -variables and faces such as @code{flymake-error-bitmap} are found. -Thus, if you change their plists, Flymake may stop honoring these -user customizations. +These category symbols' plist is where the values of customizable +variables and faces (such as @code{flymake-error-bitmap}) are found. +Thus, if you change their plists, Flymake may stop honoring these user +customizations. -The @code{flymake-category} special property is also especially useful -for backends which create diagnostics objects with non-default -types that differ from an existing type by only a few properties -(@pxref{Flymake utility functions}). +The @code{flymake-category} special property is especially useful for +backends which create diagnostics objects with non-default types that +differ from an existing type by only a few properties (@pxref{Flymake +utility functions}). As an example, consider configuring a new diagnostic type -@code{:low-priority-note} that behaves much like the @code{:note} -priority but without an overlay face. +@code{:low-priority-note} that behaves much like @code{:note}, but +without an overlay face. @example -(add-to-list - 'flymake-diagnostic-types-alist - `(:low-priority-note . ((face . nil) - (flymake-category . flymake-note)))) +(put :low-priority-note 'flymake-overlay-control '((face . nil))) +(put :low-priority-note 'flymake-category 'flymake-note) @end example @vindex flymake-diagnostics @@ -389,20 +399,17 @@ Internet search for the text of a @code{:warning} or @code{:error}. (eww-browse-url (concat "https://duckduckgo.com/?q=" - (replace-regexp-in-string " " - "+" - (flymake-diagnostic-text topmost-diag))) + (replace-regexp-in-string + " " "+" (flymake-diagnostic-text topmost-diag))) t))) (dolist (type '(:warning :error)) - (let ((a (assoc type flymake-diagnostic-types-alist))) - (setf (cdr a) - (append `((mouse-face . highlight) - (keymap . ,(let ((map (make-sparse-keymap))) - (define-key map [mouse-2] - 'my-search-for-message) - map))) - (cdr a))))) + (push '(mouse-face . highlight) (get type 'flymake-overlay-control)) + (push `(keymap . ,(let ((map (make-sparse-keymap))) + (define-key map [mouse-2] + 'my-search-for-message) + map)) + (get type 'flymake-overlay-control))) @end example @node Backend functions @@ -428,18 +435,35 @@ calling convention: one for calls made by Flymake into the backend via the backend function, the other in the reverse direction via a callback. To be usable, backends must adhere to both. -Backend functions must accept an arbitrary number of arguments: +The first argument passed to a backend function is always +@var{report-fn}, a callback function detailed below. Beyond it, +functions must be prepared to accept (and possibly ignore) an +arbitrary number of keyword-value pairs of the form +@w{@code{(@var{:key} @var{value} @var{:key2} @var{value2}...)}}. + +Currently, Flymake may pass the following keywords and values to the +backend function: @itemize -@item -the first argument is always @var{report-fn}, a callback function -detailed below; -@item -the remaining arguments are keyword-value pairs of the -form @w{@code{(@var{:key} @var{value} @var{:key2} @var{value2}...)}}. Currently, -Flymake provides no such arguments, but backend functions must be -prepared to accept (and possibly ignore) any number of them. +@item @code{:recent-changes} +The value is a list recent changes since the last time the backend +function was called for the buffer. If the list is empty, this +indicates that no changes have been recorded. If it is the first time +that this backend function is called for this activation of +@code{flymake-mode}, then this argument isn't provided at all +(i.e. it's not merely nil). + +Each element is in the form (@var{beg} @var{end} @var{text}) where +@var{beg} and @var{end} are buffer positions, and @var{text} is a +string containing the text contained between those positions (if any), +after the change was performed. + +@item @code{:changes-start} and @code{:changes-end} +The value is, repectively, the minimum and maximum buffer positions +touched by the recent changes. These are provided for convenience and +only if @code{:recent-changes} is also provided. + @end itemize Whenever Flymake or the user decide to re-check the buffer, backend @@ -495,6 +519,11 @@ details of the situation encountered, if any. @code{:force}, whose value should be a boolean suggesting that Flymake consider the report even if it was somehow unexpected. + +@item +@code{:region}, a cons (@var{beg} . @var{end}) of buffer positions +indicating that the report applies to that region and that previous +reports targeting other parts of the buffer remain valid. @end itemize @menu @@ -512,9 +541,9 @@ 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 key to -@code{flymake-diagnostic-types-alist} and @var{text} is a description -of the problem detected in this region. +@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. @end deffn @cindex access diagnostic object @@ -715,14 +744,13 @@ Patterns for error/warning messages in the form @code{(regexp file-idx line-idx col-idx err-text-idx)}. @xref{Parsing the output}. @item flymake-proc-diagnostic-type-pred -A function to classify a diagnostic text as particular type of -error. Should be a function taking an error text and returning one of -the symbols indexing @code{flymake-diagnostic-types-alist}. If non-nil -is returned but there is no such symbol in that table, a warning is -assumed. If nil is returned, an error is assumed. Can also be a -regular expression that should match only warnings. This variable -replaces the old @code{flymake-warning-re} and -@code{flymake-warning-predicate}. +A function to classify a diagnostic text as particular type of error. +Should be a function taking an error text and returning a diagnostic +symbol (@pxref{Flymake error types}). If non-nil is returned but +there is no such symbol in that table, a warning is assumed. If nil +is returned, an error is assumed. Can also be a regular expression +that should match only warnings. This variable replaces the old +@code{flymake-warning-re} and @code{flymake-warning-predicate}. @item flymake-proc-compilation-prevents-syntax-check A flag indicating whether compilation and syntax check of the same diff --git a/doc/misc/gnus-coding.texi b/doc/misc/gnus-coding.texi index 95544628f79..6affea48724 100644 --- a/doc/misc/gnus-coding.texi +++ b/doc/misc/gnus-coding.texi @@ -227,161 +227,6 @@ ends (probably @file{nnml.el}, @file{nnfolder.el} and @c requires nnheader. -@section Compatibility - -No Gnus and Gnus 5.10.10 and up should work on: -@itemize @bullet -@item -Emacs 21.1 and up. -@item -XEmacs 21.4 and up. -@end itemize - -Gnus 5.10.8 and below should work on: -@itemize @bullet -@item -Emacs 20.7 and up. -@item -XEmacs 21.1 and up. -@end itemize - -@node Gnus Maintenance Guide -@chapter Gnus Maintenance Guide - -@section Stable and development versions - -The development of Gnus normally is done on the Git repository trunk -as of April 19, 2010 (formerly it was done in CVS; the repository is -at http://git.gnus.org), i.e., there are no separate branches to -develop and test new features. Most of the time, the trunk is -developed quite actively with more or less daily changes. Only after -a new major release, e.g., 5.10.1, there's usually a feature period of -several months. After the release of Gnus 5.10.6 the development of -new features started again on the trunk while the 5.10 series is -continued on the stable branch (v5-10) from which more stable releases -will be done when needed (5.10.8, @dots{}). @ref{Gnus Development, -,Gnus Development, gnus, The Gnus Newsreader} - -Stable releases of Gnus finally become part of Emacs. E.g., Gnus 5.8 -became a part of Emacs 21 (relabeled to Gnus 5.9). The 5.10 series -became part of Emacs 22 as Gnus 5.11. - -@section Syncing - -@c Some MIDs related to this follow. Use http://thread.gmane.org/MID -@c (and click on the subject) to get the thread on Gmane. - -@c Some quotes from Miles Bader follow... - -@c <v9eklyke6b.fsf@marauder.physik.uni-ulm.de> -@c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp> - -In the past, the inclusion of Gnus into Emacs was quite cumbersome. For -each change made to Gnus in Emacs repository, it had to be checked that -it was applied to the new Gnus version, too. Else, bug fixes done in -Emacs repository might have been lost. - -With the inclusion of Gnus 5.10, Miles Bader has set up an Emacs-Gnus -gateway to ensure the bug fixes from Emacs CVS are propagated to Gnus -CVS semi-automatically. - -After Emacs moved to bzr and Gnus moved to git, Katsumi Yamaoka has -taken over the chore of keeping Emacs and Gnus in sync. In general, -changes made to one repository will usually be replicated in the other -within a few days. - -Basically the idea is that the gateway will cause all common files in -Emacs and Gnus v5-13 to be identical except when there's a very good -reason (e.g., the Gnus version string in Emacs says @samp{5.11}, but -the v5-13 version string remains @samp{5.13.x}). Furthermore, all -changes in these files in either Emacs or the v5-13 branch will be -installed into the Gnus git trunk, again except where there's a good -reason. - -@c (typically so far the only exception has been that the changes -@c already exist in the trunk in modified form). -Because of this, when the next major version of Gnus will be included in -Emacs, it should be very easy---just plonk in the files from the Gnus -trunk without worrying about lost changes from the Emacs tree. - -The effect of this is that as hacker, you should generally only have to -make changes in one place: - -@itemize -@item -If it's a file which is thought of as being outside of Gnus (e.g., the -new @file{encrypt.el}), you should probably make the change in the Emacs -tree, and it will show up in the Gnus tree a few days later. - -If you don't have Emacs repository access (or it's inconvenient), you -can change such a file in the v5-10 branch, and it should propagate to -the Emacs repository---however, it will get some extra scrutiny (by -Miles) to see if the changes are possibly controversial and need -discussion on the mailing list. Many changes are obvious bug-fixes -however, so often there won't be any problem. - -@item -If it's to a Gnus file, and it's important enough that it should be part -of Emacs and the v5-10 branch, then you can make the change on the v5-10 -branch, and it will go into Emacs and the Gnus git trunk (a few days -later). The most prominent examples for such changes are bug-fixed -including improvements on the documentation. - -If you know that there will be conflicts (perhaps because the affected -source code is different in v5-10 and the Gnus git trunk), then you can -install your change in both places, and when I try to sync them, there -will be a conflict---however, since in most such cases there would be a -conflict @emph{anyway}, it's often easier for me to resolve it simply if -I see two @samp{identical} changes, and can just choose the proper one, -rather than having to actually fix the code. - -@item -For general Gnus development changes, of course you just make the -change on the Gnus Git trunk and it goes into Emacs a few years -later... :-) - -@end itemize - -Of course in any case, if you just can't wait for me to sync your -change, you can commit it in more than one place and probably there will -be no problem; usually the changes are textually identical anyway, so -can be easily resolved automatically (sometimes I notice silly things in -such multiple commits, like whitespace differences, and unify those ;-). - - -@c I do Emacs->Gnus less often (than Gnus->Emacs) because it tends to -@c require more manual work. - -@c By default I sync about once a week. I also try to follow any Gnus -@c threads on the mailing lists and make sure any changes being discussed -@c are kept more up-to-date (so say 1-2 days delay for "topical" changes). - -@c <buovfd71nkk.fsf@mctpc71.ucom.lsi.nec.co.jp> - -@c BTW, just to add even more verbose explanation about the syncing thing: - -@section Miscellanea - -@heading @file{GNUS-NEWS} - -The @file{etc/GNUS-NEWS} is created from -@file{doc/misc/gnus-news.texi}. Don't edit @file{etc/GNUS-NEWS}. -Edit @file{doc/misc/gnus-news.texi}, type @command{make -update-gnus-news} in the @file{lisp} directory and commit -@file{etc/GNUS-NEWS} and @file{doc/misc/gnus-news.texi}. - -@heading Conventions for version information in defcustoms - -For new customizable variables introduced in Oort Gnus (including the -v5-10 branch) use @code{:version "22.1" ;; Oort Gnus} (including the -comment) or, e.g., @code{:version "22.2" ;; Gnus 5.10.10} if the feature -was added for Emacs 22.2 and Gnus 5.10.10. -@c -If the variable is new in No Gnus use @code{:version "23.1" ;; No Gnus}. - -The same applies for customizable variables when its default value was -changed. - @node GNU Free Documentation License @appendix GNU Free Documentation License @include doclicense.texi diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi index bc0357144dc..840cc082054 100644 --- a/doc/misc/gnus-faq.texi +++ b/doc/misc/gnus-faq.texi @@ -1161,13 +1161,13 @@ from using them): @example (setq nnmail-split-methods '(("duplicates" "^Gnus-Warning:.*duplicate") - ("XEmacs-NT" "^\\(To:\\|CC:\\).*localpart@@xemacs.invalid.*") - ("Gnus-Tut" "^\\(To:\\|CC:\\).*localpart@@socha.invalid.*") - ("tcsh" "^\\(To:\\|CC:\\).*localpart@@mx.gw.invalid.*") - ("BAfH" "^\\(To:\\|CC:\\).*localpart@@.*uni-muenchen.invalid.*") - ("Hamster-src" "^\\(CC:\\|To:\\).*hamster-sourcen@@yahoogroups.\\(de\\|com\\).*") + ("XEmacs-NT" "^\\(To:\\|Cc:\\).*localpart@@xemacs.invalid.*") + ("Gnus-Tut" "^\\(To:\\|Cc:\\).*localpart@@socha.invalid.*") + ("tcsh" "^\\(To:\\|Cc:\\).*localpart@@mx.gw.invalid.*") + ("BAfH" "^\\(To:\\|Cc:\\).*localpart@@.*uni-muenchen.invalid.*") + ("Hamster-src" "^\\(Cc:\\|To:\\).*hamster-sourcen@@yahoogroups.\\(de\\|com\\).*") ("Tagesschau" "^From: tagesschau <localpart@@www.tagesschau.invalid>$") - ("Replies" "^\\(CC:\\|To:\\).*localpart@@Frank-Schmitt.invalid.*") + ("Replies" "^\\(Cc:\\|To:\\).*localpart@@Frank-Schmitt.invalid.*") ("EK" "^From:.*\\(localpart@@privateprovider.invalid\\|localpart@@workplace.invalid\\).*") ("Spam" "^Content-Type:.*\\(ks_c_5601-1987\\|EUC-KR\\|big5\\|iso-2022-jp\\).*") ("Spam" "^Subject:.*\\(This really work\\|XINGA\\|ADV:\\|XXX\\|adult\\|sex\\).*") @@ -1177,10 +1177,10 @@ from using them): ("Spam" "^From:.*\\(verizon\.net\\|prontomail\.com\\|money\\|ConsumerDirect\\).*") ("Spam" "^Delivered-To: GMX delivery to spamtrap@@gmx.invalid$") ("Spam" "^Received: from link2buy.com") - ("Spam" "^CC: .*azzrael@@t-online.invalid") + ("Spam" "^Cc: .*azzrael@@t-online.invalid") ("Spam" "^X-Mailer-Version: 1.50 BETA") - ("Uni" "^\\(CC:\\|To:\\).*localpart@@uni-koblenz.invalid.*") - ("Inbox" "^\\(CC:\\|To:\\).*\\(my\ name\\|address@@one.invalid\\|address@@two.invalid\\)") + ("Uni" "^\\(Cc:\\|To:\\).*localpart@@uni-koblenz.invalid.*") + ("Inbox" "^\\(Cc:\\|To:\\).*\\(my\ name\\|address@@one.invalid\\|address@@two.invalid\\)") ("Spam" ""))) @end example @noindent diff --git a/doc/misc/gnus-news.el b/doc/misc/gnus-news.el deleted file mode 100644 index c90269fffef..00000000000 --- a/doc/misc/gnus-news.el +++ /dev/null @@ -1,115 +0,0 @@ -;;; gnus-news.el --- a hack to create GNUS-NEWS from texinfo source -;; Copyright (C) 2004-2019 Free Software Foundation, Inc. - -;; Author: Reiner Steib <Reiner.Steib@gmx.de> -;; Keywords: tools - -;; This file is part of GNU Emacs. - -;; GNU Emacs is free software: you can redistribute it and/or modify -;; it under the terms of the GNU General Public License as published by -;; the Free Software Foundation, either version 3 of the License, or -;; (at your option) any later version. - -;; GNU Emacs is distributed in the hope that it will be useful, -;; but WITHOUT ANY WARRANTY; without even the implied warranty of -;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -;; GNU General Public License for more details. - -;; You should have received a copy of the GNU General Public License -;; along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>. - -;;; Commentary: - -;;; Code: - -(defvar gnus-news-header-disclaimer -"GNUS NEWS -- history of user-visible changes. - -Copyright (C) 1999-2019 Free Software Foundation, Inc. -See the end of the file for license conditions. - -Please send Gnus bug reports to bugs@gnus.org. -For older news, see Gnus info node \"New Features\".\n\n") - -(defvar gnus-news-trailer -" -* For older news, see Gnus info node \"New Features\". - ----------------------------------------------------------------------- - -This file is part of GNU Emacs. - -GNU Emacs is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation, either version 3 of the License, or -\(at your option) any later version. - -GNU Emacs is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with GNU Emacs. If not, see <https://www.gnu.org/licenses/>. - - \nLocal variables:\nmode: outline -paragraph-separate: \"[ ]*$\"\nend:\n") - -(defvar gnus-news-makeinfo-command "makeinfo") - -(defvar gnus-news-fill-column 80) - -(defvar gnus-news-makeinfo-switches - (concat " --no-headers --paragraph-indent=0" - " --no-validate" ;; Allow unresolved references. - " --fill-column=" (number-to-string - (+ 3 ;; will strip leading spaces later - (or gnus-news-fill-column 80))))) - -(defun batch-gnus-news () - "Make GNUS-NEWS in batch mode." - (let (infile outfile) - (setq infile (car command-line-args-left) - command-line-args-left (cdr command-line-args-left) - outfile (car command-line-args-left) - command-line-args-left nil) - (if (and infile outfile) - (message "Creating `%s' from `%s'..." outfile infile) - (error "Not enough files given.")) - (gnus-news-translate-file infile outfile))) - -(defun gnus-news-translate-file (infile outfile) - "Translate INFILE (texinfo) to OUTFILE (GNUS-NEWS)." - (let* ((dir (concat (or (getenv "srcdir") ".") "/")) - (infile (concat dir infile)) - (buffer (find-file-noselect (concat dir outfile)))) - (with-temp-buffer - ;; Could be done using 'texinfmt' stuff as in 'infohack.el'. - (insert - (shell-command-to-string - (concat gnus-news-makeinfo-command " " - gnus-news-makeinfo-switches " " infile))) - (goto-char (point-max)) - (delete-char -1) - (goto-char (point-min)) - (save-excursion - (while (re-search-forward "^ \\* " nil t) - (replace-match "\f\n* "))) - (save-excursion - (while (re-search-forward "^ \\* " nil t) - (replace-match "** "))) - (save-excursion - (while (re-search-forward "^ " nil t) - (replace-match ""))) - ;; Avoid '*' from @ref at beginning of line: - (save-excursion - (while (re-search-forward "^\\*Note" nil t) - (replace-match " \\&"))) - (goto-char (point-min)) - (insert gnus-news-header-disclaimer) - (goto-char (point-max)) - (insert gnus-news-trailer) - (write-region (point-min) (point-max) outfile)))) - -;;; gnus-news.el ends here diff --git a/doc/misc/gnus-news.texi b/doc/misc/gnus-news.texi deleted file mode 100644 index 9bf8d190416..00000000000 --- a/doc/misc/gnus-news.texi +++ /dev/null @@ -1,371 +0,0 @@ -@c -*-texinfo-*- - -@c Copyright (C) 2004-2019 Free Software Foundation, Inc. - -@c Permission is granted to anyone to make or distribute verbatim copies -@c of this document as received, in any medium, provided that the -@c copyright notice and this permission notice are preserved, -@c thus giving the recipient permission to redistribute in turn. - -@c Permission is granted to distribute modified versions -@c of this document, or of portions of it, -@c under the above conditions, provided also that they -@c carry prominent notices stating who last changed them. - -@c This file contains a list of news features Gnus. It is supposed to be -@c included in 'gnus.texi'. 'GNUS-NEWS' is automatically generated from -@c this file (see 'gnus-news.el'). - -@itemize @bullet - -@item Supported Emacs versions -The following Emacs versions are supported by No Gnus: -@itemize @bullet - -@item Emacs 22 and up -@item XEmacs 21.4 -@item XEmacs 21.5 -@item SXEmacs - -@end itemize - -@item Installation changes - -@itemize @bullet -@item Upgrading from previous (stable) version if you have used No Gnus. - -If you have tried No Gnus (the unstable Gnus branch leading to this -release) but went back to a stable version, be careful when upgrading -to this version. In particular, you will probably want to remove the -@file{~/News/marks} directory (perhaps selectively), so that flags are -read from your @file{~/.newsrc.eld} instead of from the stale marks -file, where this release will store flags for nntp. See a later entry -for more information about nntp marks. Note that downgrading isn't -safe in general. - -@item Incompatibility when switching from Emacs 23 to Emacs 22 -In Emacs 23, Gnus uses Emacs's new internal coding system @code{utf-8-emacs} -for saving articles drafts and @file{~/.newsrc.eld}. These files may not -be read correctly in Emacs 22 and below. If you want to use Gnus across -different Emacs versions, you may set @code{mm-auto-save-coding-system} -to @code{emacs-mule}. -@c FIXME: Untested. (Or did anyone test it?) -@c Cf. http://thread.gmane.org/gmane.emacs.gnus.general/66251/focus=66344 - -@item Lisp files are now installed in @file{.../site-lisp/gnus/} by default. -It defaulted to @file{.../site-lisp/} formerly. In addition to this, -the new installer issues a warning if other Gnus installations which -will shadow the latest one are detected. You can then remove those -shadows manually or remove them using @code{make -remove-installed-shadows}. - -@item The installation directory's name is allowed to have spaces and/or tabs. -@end itemize - -@item New packages and libraries within Gnus - -@itemize @bullet - -@item New version of @code{nnimap} - -@code{nnimap} has been reimplemented in a mostly-compatible way. See -the Gnus manual for a description of the new interface. In -particular, @code{nnimap-inbox} and the client side split method has -changed. - -@item Gnus includes the Emacs Lisp @acronym{SASL} library. - -This provides a clean @acronym{API} to @acronym{SASL} mechanisms from -within Emacs. The user visible aspects of this, compared to the earlier -situation, include support for @acronym{DIGEST}-@acronym{MD5} and -@acronym{NTLM}. @xref{Top, ,Emacs SASL, sasl, Emacs SASL}. - -@item ManageSieve connections uses the @acronym{SASL} library by default. - -The primary change this brings is support for @acronym{DIGEST-MD5} and -@acronym{NTLM}, when the server supports it. - -@item Gnus includes a password cache mechanism in password.el. - -It is enabled by default (see @code{password-cache}), with a short -timeout of 16 seconds (see @code{password-cache-expiry}). If -@acronym{PGG} is used as the @acronym{PGP} back end, the @acronym{PGP} -passphrase is managed by this mechanism. Passwords for ManageSieve -connections are managed by this mechanism, after querying the user -about whether to do so. - -@item Using EasyPG with Gnus -When EasyPG, is available, Gnus will use it instead of @acronym{PGG}. -EasyPG is an Emacs user interface to GNU Privacy Guard. @xref{Top, -,EasyPG Assistant user's manual, epa, EasyPG Assistant user's manual}. -EasyPG is included in Emacs 23 and available separately as well. -@end itemize - -@item Changes in group mode -@c ************************ - -@itemize @bullet - -@item -Symbols like @code{gcc-self} now have the same precedence rules in -@code{gnus-parameters} as other ``real'' variables: The last match -wins instead of the first match. - -@item -Old intermediate incoming mail files (@file{Incoming*}) are deleted -after a couple of days, not immediately. @xref{Mail Source -Customization}. -(New in Gnus 5.10.10 / No Gnus 0.8) -@c This entry is also present in the node "Oort Gnus". - -@end itemize - -@item Changes in summary and article mode - -@itemize @bullet - -@item There's now only one variable that determines how @acronym{HTML} -is rendered: @code{mm-text-html-renderer}. - -@item Gnus now supports sticky article buffers. Those are article buffers -that are not reused when you select another article. @xref{Sticky -Articles}. - -@c @item Bookmarks -@c FIXME: To be added - -@item Gnus can selectively display @samp{text/html} articles -with a WWW browser with @kbd{K H}. @xref{MIME Commands}. - -@c gnus-registry-marks -@c FIXME: To be added - -@item International host names (@acronym{IDNA}) can now be decoded -inside article bodies using @kbd{W i} -(@code{gnus-summary-idna-message}). This requires that GNU Libidn -(@url{https://www.gnu.org/software/libidn/}) has been installed. -@c FIXME: Also mention @code{message-use-idna}? - -@item The non-@acronym{ASCII} group names handling has been much -improved. The back ends that fully support non-@acronym{ASCII} group -names are now @code{nntp}, @code{nnml}, and @code{nnrss}. Also the -agent, the cache, and the marks features work with those back ends. -@xref{Non-ASCII Group Names}. - -@item Gnus now displays @acronym{DNS} master files sent as text/dns -using dns-mode. - -@item Gnus supports new limiting commands in the Summary buffer: -@kbd{/ r} (@code{gnus-summary-limit-to-replied}) and @kbd{/ R} -(@code{gnus-summary-limit-to-recipient}). @xref{Limiting}. - -@item You can now fetch all ticked articles from the server using -@kbd{Y t} (@code{gnus-summary-insert-ticked-articles}). @xref{Summary -Generation Commands}. - -@item Gnus supports a new sort command in the Summary buffer: -@kbd{C-c C-s C-t} (@code{gnus-summary-sort-by-recipient}). @xref{Summary -Sorting}. - -@item @acronym{S/MIME} now features @acronym{LDAP} user certificate searches. -You need to configure the server in @code{smime-ldap-host-list}. - -@item URLs inside Open@acronym{PGP} headers are retrieved and imported -to your PGP key ring when you click on them. - -@item -Picons can be displayed right from the textual address, see -@code{gnus-picon-style}. @xref{Picons}. - -@item @acronym{ANSI} @acronym{SGR} control sequences can be transformed -using @kbd{W A}. - -@acronym{ANSI} sequences are used in some Chinese hierarchies for -highlighting articles (@code{gnus-article-treat-ansi-sequences}). - -@item Gnus now MIME decodes articles even when they lack "MIME-Version" header. -This changes the default of @code{gnus-article-loose-mime}. - -@item @code{gnus-decay-scores} can be a regexp matching score files. -For example, set it to @samp{\\.ADAPT\\'} and only adaptive score files -will be decayed. @xref{Score Decays}. - -@item Strings prefixing to the @code{To} and @code{Newsgroup} headers in -summary lines when using @code{gnus-ignored-from-addresses} can be -customized with @code{gnus-summary-to-prefix} and -@code{gnus-summary-newsgroup-prefix}. @xref{To From Newsgroups}. - -@item You can replace @acronym{MIME} parts with external bodies. -See @code{gnus-mime-replace-part} and @code{gnus-article-replace-part}. -@xref{MIME Commands}, @ref{Using MIME}. - -@item -The option @code{mm-fill-flowed} can be used to disable treatment of -format=flowed messages. Also, flowed text is disabled when sending -inline @acronym{PGP} signed messages. @xref{Flowed text, ,Flowed text, -emacs-mime, The Emacs MIME Manual}. (New in Gnus 5.10.7) -@c This entry is also present in the node "Oort Gnus". - -@item Now the new command @kbd{S W} -(@code{gnus-article-wide-reply-with-original}) for a wide reply in the -article buffer yanks a text that is in the active region, if it is set, -as well as the @kbd{R} (@code{gnus-article-reply-with-original}) command. -Note that the @kbd{R} command in the article buffer no longer accepts a -prefix argument, which was used to make it do a wide reply. -@xref{Article Keymap}. - -@item The new command @kbd{C-h b} -(@code{gnus-article-describe-bindings}) used in the article buffer now -shows not only the article commands but also the real summary commands -that are accessible from the article buffer. - -@end itemize - -@item Changes in Message mode - -@itemize @bullet -@item Gnus now defaults to saving all outgoing messages in per-month -nnfolder archives. - -@item Gnus now supports the ``hashcash'' client puzzle anti-spam mechanism. -Use @code{(setq message-generate-hashcash t)} to enable. -@xref{Hashcash}. - -@item You can now drag and drop attachments to the Message buffer. -See @code{mml-dnd-protocol-alist} and @code{mml-dnd-attach-options}. -@xref{MIME, ,MIME, message, Message Manual}. - -@item The option @code{message-yank-empty-prefix} now controls how -empty lines are prefixed in cited text. @xref{Insertion Variables, -,Insertion Variables, message, Message Manual}. - -@item Gnus uses narrowing to hide headers in Message buffers. -The @code{References} header is hidden by default. To make all -headers visible, use @code{(setq message-hidden-headers nil)}. -@xref{Message Headers, ,Message Headers, message, Message Manual}. - -@item You can highlight different levels of citations like in the -article buffer. See @code{gnus-message-highlight-citation}. - -@item @code{auto-fill-mode} is enabled by default in Message mode. -See @code{message-fill-column}. @xref{Various Message Variables, , -Message Headers, message, Message Manual}. - -@item You can now store signature files in a special directory -named @code{message-signature-directory}. - -@item The option @code{message-citation-line-format} controls the format -of the "Whomever writes:" line. You need to set -@code{message-citation-line-function} to -@code{message-insert-formatted-citation-line} as well. -@end itemize - -@item Changes in Browse Server mode - -@itemize @bullet -@item Gnus' sophisticated subscription methods are now available in -Browse Server buffers as well using the variable -@code{gnus-browse-subscribe-newsgroup-method}. - -@end itemize - - -@item Changes in back ends - -@itemize @bullet -@item The nntp back end stores article marks in @file{~/News/marks}. - -The directory can be changed using the (customizable) variable -@code{nntp-marks-directory}, and marks can be disabled using the -(back end) variable @code{nntp-marks-is-evil}. The advantage of this -is that you can copy @file{~/News/marks} (using rsync, scp or -whatever) to another Gnus installation, and it will realize what -articles you have read and marked. The data in @file{~/News/marks} -has priority over the same data in @file{~/.newsrc.eld}. - -@item -You can import and export your @acronym{RSS} subscriptions from -@acronym{OPML} files. @xref{RSS}. - -@item @acronym{IMAP} identity (@acronym{RFC} 2971) is supported. - -By default, Gnus does not send any information about itself, but you can -customize it using the variable @code{nnimap-id}. - -@item The @code{nnrss} back end now supports multilingual text. -Non-@acronym{ASCII} group names for the @code{nnrss} groups are also -supported. @xref{RSS}. - -@item Retrieving mail with @acronym{POP3} is supported over @acronym{SSL}/@acronym{TLS} and with StartTLS. - -@item The nnml back end allows other compression programs beside @file{gzip} -for compressed message files. @xref{Mail Spool}. - -@item The nnml back end supports group compaction. - -This feature, accessible via the functions -@code{gnus-group-compact-group} (@kbd{G z} in the group buffer) and -@code{gnus-server-compact-server} (@kbd{z} in the server buffer) -renumbers all articles in a group, starting from 1 and removing gaps. -As a consequence, you get a correct total article count (until -messages are deleted again). - -@c @item nnmairix.el -@c FIXME - -@c @item nnir.el -@c FIXME - -@end itemize - -@item Appearance -@c Maybe it's not worth to separate this from "Miscellaneous"? - -@itemize @bullet - -@item The tool bar has been updated to use GNOME icons. -You can also customize the tool bars: @kbd{M-x customize-apropos @key{RET} --tool-bar$} should get you started. (Only for Emacs, not in XEmacs.) -@c FIXME: Document this in the manual - -@item The tool bar icons are now (de)activated correctly -in the group buffer, see the variable @code{gnus-group-update-tool-bar}. -Its default value depends on your Emacs version. -@c FIXME: Document this in the manual - -@item You can change the location of XEmacs's toolbars in Gnus buffers. -See @code{gnus-use-toolbar} and @code{message-use-toolbar}. - -@end itemize - -@item Miscellaneous changes - -@itemize @bullet -@item Having edited the select-method for the foreign server in the -server buffer is immediately reflected to the subscription of the groups -which use the server in question. For instance, if you change -@code{nntp-via-address} into @samp{bar.example.com} from -@samp{foo.example.com}, Gnus will connect to the news host by way of the -intermediate host @samp{bar.example.com} from next time. - -@item The @file{all.SCORE} file can be edited from the group buffer -using @kbd{W e}. - -@item You can set @code{gnus-mark-copied-or-moved-articles-as-expirable} -to a non-@code{nil} value so that articles that have been read may be -marked as expirable automatically when copying or moving them to a group -that has auto-expire turned on. The default is @code{nil} and copying -and moving of articles behave as before; i.e., the expirable marks will -be unchanged except that the marks will be removed when copying or -moving articles to a group that has not turned auto-expire on. -@xref{Expiring Mail}. - -@item NoCeM support has been removed. - -@item Carpal mode has been removed. - -@end itemize - -@end itemize - -@c gnus-news.texi ends here. diff --git a/doc/misc/gnus-overrides.texi b/doc/misc/gnus-overrides.texi deleted file mode 100644 index e69de29bb2d..00000000000 --- a/doc/misc/gnus-overrides.texi +++ /dev/null diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index ee504f5d351..28f000c4898 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -1,7 +1,5 @@ \input texinfo -@include gnus-overrides.texi - @setfilename ../../info/gnus.info @settitle Gnus Manual @include docstyle.texi @@ -3102,6 +3100,21 @@ interest in relation to the sieve parameter. The Sieve language is described in RFC 3028. @xref{Top, Emacs Sieve, Top, sieve, Emacs Sieve}. +@item match-list +@cindex match-list +If this parameter is set to @code{t} and @code{nnmail-split-method} is +set to @code{gnus-group-split}, Gnus will match @code{to-address}, +@code{to-list}, @code{extra-aliases} and @code{split-regexp} against +the @code{list} split abbreviation. The split regexp is modified to +match either a @code{@@} or a dot @code{.} in mail addresses to +conform to RFC2919 @code{List-ID}. + +See @code{nnmail-split-abbrev-alist} for the regular expression +matching mailing-list headers. + +@xref{Group Mail Splitting}, for details on how to automatically split +on group parameters. + @item (agent parameters) If the agent has been enabled, you can set any of its parameters to control the behavior of the agent in individual groups. See Agent @@ -5577,7 +5590,7 @@ command uses the process/prefix convention. Mail a wide reply to the author of the current article (@code{gnus-summary-wide-reply}). A @dfn{wide reply} is a reply that goes out to all people listed in the @code{To}, @code{From} (or -@code{Reply-to}) and @code{Cc} headers. If @code{Mail-Followup-To} is +@code{Reply-To}) and @code{Cc} headers. If @code{Mail-Followup-To} is present, that's used instead. @item S W @@ -5601,7 +5614,7 @@ message to the mailing list, and include the original message Mail a very wide reply to the author of the current article (@code{gnus-summary-wide-reply}). A @dfn{very wide reply} is a reply that goes out to all people listed in the @code{To}, @code{From} (or -@code{Reply-to}) and @code{Cc} headers in all the process/prefixed +@code{Reply-To}) and @code{Cc} headers in all the process/prefixed articles. This command uses the process/prefix convention. @item S V @@ -5643,8 +5656,7 @@ as an rfc822 @acronym{MIME} section; if the prefix is 3, decode message and forward as an rfc822 @acronym{MIME} section; if the prefix is 4, forward message directly inline; otherwise, the message is forwarded as no prefix given but use the flipped value of (@code{message-forward-as-mime}). By -default, the message is decoded and forwarded as an rfc822 @acronym{MIME} -section. +default, the forwarded message is inlined into the mail. @item S m @itemx m @@ -5836,6 +5848,15 @@ buffer (@code{gnus-summary-yank-message}). This command prompts for what message buffer you want to yank into, and understands the process/prefix convention (@pxref{Process/Prefix}). +@item S A +@kindex S A @r{(Summary)} +@findex gnus-summary-attach-article +Attach the current article into an already existing Message +composition buffer (@code{gnus-summary-attach-message}). If no such +buffer exists, a new one is created. This command prompts for what +message buffer you want to yank into, and understands the +process/prefix convention (@pxref{Process/Prefix}). + @end table @@ -6657,7 +6678,8 @@ Limit the summary buffer to the unseen articles @kindex / v @r{(Summary)} @findex gnus-summary-limit-to-score Limit the summary buffer to articles that have a score at or above some -score (@code{gnus-summary-limit-to-score}). +score (@code{gnus-summary-limit-to-score}). If given a prefix, below +some score. @item / p @kindex / p @r{(Summary)} @@ -9791,9 +9813,6 @@ this command passes the @acronym{HTML} content to the browser without eliminating these ``web bugs'' you should only use it for mails from trusted senders. -If you always want to display @acronym{HTML} parts in the browser, set -@code{mm-text-html-renderer} to @code{nil}. - This command creates temporary files to pass @acronym{HTML} contents including images if any to the browser, and deletes them when exiting the group (if you want). @@ -10135,6 +10154,17 @@ partial article, and want to see the complete article instead, then the @kbd{A C} command (@code{gnus-summary-show-complete-article}) will do so. +@item w +@itemx A w +@kindex w @r{(Summary)} +@kindex A w @r{(Summary)} +@cindex web +@cindex url +@findex gnus-summary-browse-url +Scan the article buffer for links, and offer them to the user for +browsing with @code{browse-url}. By default, only scan the article +body; with a prefix arg, also scan the article headers. + @end table @@ -13209,6 +13239,11 @@ Also @pxref{Formatting Variables}. @subsection Server Commands @cindex server commands +The following keybinding are available in the server buffer. Be aware +that some of the commands will only work on servers that you've added +through this interface (with @kbd{a}), not with servers you've defined +in your init files. + @table @kbd @item v @@ -14294,6 +14329,12 @@ fetch all textual parts, while leaving the rest on the server. If non-@code{nil}, record all @acronym{IMAP} commands in the @samp{"*imap log*"} buffer. +@item nnimap-use-namespaces +If non-@code{nil}, omit the IMAP namespace prefix in nnimap group +names. If your IMAP mailboxes are called something like @samp{INBOX} +and @samp{INBOX.Lists.emacs}, but you'd like the nnimap group names to +be @samp{INBOX} and @samp{Lists.emacs}, you should enable this option. + @end table @@ -15469,6 +15510,9 @@ Matches the @samp{To}, @samp{Cc}, @samp{Apparently-To}, @samp{Resent-To} and @samp{Resent-Cc} fields. @item any Is the union of the @code{from} and @code{to} entries. +@item list +Matches the @samp{List-ID}, @samp{List-Post}, @samp{X-Mailing-List}, +@samp{X-BeenThere} and @samp{X-Loop} fields. @end table @vindex nnmail-split-fancy-syntax-table @@ -18479,7 +18523,7 @@ something along the lines of the following: (defun my-article-old-p () "Say whether an article is old." (< (time-to-days (date-to-time (mail-header-date gnus-headers))) - (- (time-to-days (current-time)) gnus-agent-expire-days))) + (- (time-to-days nil) gnus-agent-expire-days))) @end lisp with the predicate then defined as: @@ -19467,8 +19511,8 @@ score file and edit it. @item V w @kindex V w @r{(Summary)} -@findex gnus-score-find-favourite-words -List words used in scoring (@code{gnus-score-find-favourite-words}). +@findex gnus-score-find-favorite-words +List words used in scoring (@code{gnus-score-find-favorite-words}). @item V R @kindex V R @r{(Summary)} @@ -21434,6 +21478,18 @@ The prefix to remove from each file name returned by notmuch in order to get a group name (albeit with @samp{/} instead of @samp{.}). This is a regular expression. +@item nnir-notmuch-filter-group-names-function +A function used to transform the names of groups being searched in, +for use as a ``path:'' search keyword for notmuch. If nil, the +default, ``path:'' keywords are not used. Otherwise, this should be a +callable which accepts a single group name and returns a transformed +name as notmuch expects to see it. In many mail backends, for +instance, dots in group names must be converted to forward slashes: to +achieve this, set this option to +@example +(lambda (g) (replace-regexp-in-string "\\." "/" g)) +@end example + @end table @@ -25855,13 +25911,13 @@ Reset: (setq spam-stat (make-hash-table :test 'equal)) Learn spam: (spam-stat-process-spam-directory "~/Mail/mail/spam") Learn non-spam: (spam-stat-process-non-spam-directory "~/Mail/mail/misc") Save table: (spam-stat-save) -File size: (nth 7 (file-attributes spam-stat-file)) +File size: (file-attribute-size (file-attributes spam-stat-file)) Number of words: (hash-table-count spam-stat) Test spam: (spam-stat-test-directory "~/Mail/mail/spam") Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc") Reduce table size: (spam-stat-reduce-size) Save table: (spam-stat-save) -File size: (nth 7 (file-attributes spam-stat-file)) +File size: (file-attribute-size (file-attributes spam-stat-file)) Number of words: (hash-table-count spam-stat) Test spam: (spam-stat-test-directory "~/Mail/mail/spam") Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc") @@ -26659,12 +26715,6 @@ Overall, a casual user who hasn't written much code that depends on @sc{gnus} internals should suffer no problems. If problems occur, please let me know by issuing that magic command @kbd{M-x gnus-bug}. -@vindex gnus-bug-create-help-buffer -If you are in the habit of sending bug reports @emph{very} often, you -may find the helpful help buffer annoying after a while. If so, set -@code{gnus-bug-create-help-buffer} to @code{nil} to avoid having it pop -up at you. - @node Conformity @subsection Conformity @@ -27068,7 +27118,7 @@ Richard Mlynarik, Lantz Moore, Morioka Tomohiko, @c Morioka Erik Toubro Nielsen, -Hrvoje Niksic, +Hrvoje Nikšić, Andy Norman, Fred Oberhauser, C. R. Oldham, @@ -27171,6 +27221,8 @@ actually are people who are using Gnus. Who'd'a thunk it! * Ma Gnus:: Celebrating 25 years of Gnus. @end menu +For summaries of more recent changes, see the normal Emacs @file{NEWS} files. + These lists are, of course, just @emph{short} overviews of the @emph{most} important new features. No, really. There are tons more. Yes, we have feeping creaturism in full effect. @@ -28541,7 +28593,358 @@ A new command which starts Gnus offline in slave mode. New features in No Gnus: @c FIXME: Gnus 5.12? -@include gnus-news.texi +@itemize @bullet + +@item Supported Emacs versions +The following Emacs versions are supported by No Gnus: +@itemize @bullet + +@item Emacs 22 and up +@item XEmacs 21.4 +@item XEmacs 21.5 +@item SXEmacs + +@end itemize + +@item Installation changes + +@itemize @bullet +@item Upgrading from previous (stable) version if you have used No Gnus. + +If you have tried No Gnus (the unstable Gnus branch leading to this +release) but went back to a stable version, be careful when upgrading +to this version. In particular, you will probably want to remove the +@file{~/News/marks} directory (perhaps selectively), so that flags are +read from your @file{~/.newsrc.eld} instead of from the stale marks +file, where this release will store flags for nntp. See a later entry +for more information about nntp marks. Note that downgrading isn't +safe in general. + +@item Incompatibility when switching from Emacs 23 to Emacs 22 +In Emacs 23, Gnus uses Emacs's new internal coding system @code{utf-8-emacs} +for saving articles drafts and @file{~/.newsrc.eld}. These files may not +be read correctly in Emacs 22 and below. If you want to use Gnus across +different Emacs versions, you may set @code{mm-auto-save-coding-system} +to @code{emacs-mule}. +@c FIXME: Untested. (Or did anyone test it?) +@c Cf. http://thread.gmane.org/gmane.emacs.gnus.general/66251/focus=66344 + +@item Lisp files are now installed in @file{.../site-lisp/gnus/} by default. +It defaulted to @file{.../site-lisp/} formerly. In addition to this, +the new installer issues a warning if other Gnus installations which +will shadow the latest one are detected. You can then remove those +shadows manually or remove them using @code{make +remove-installed-shadows}. + +@item The installation directory's name is allowed to have spaces and/or tabs. +@end itemize + +@item New packages and libraries within Gnus + +@itemize @bullet + +@item New version of @code{nnimap} + +@code{nnimap} has been reimplemented in a mostly-compatible way. See +the Gnus manual for a description of the new interface. In +particular, @code{nnimap-inbox} and the client side split method has +changed. + +@item Gnus includes the Emacs Lisp @acronym{SASL} library. + +This provides a clean @acronym{API} to @acronym{SASL} mechanisms from +within Emacs. The user visible aspects of this, compared to the earlier +situation, include support for @acronym{DIGEST}-@acronym{MD5} and +@acronym{NTLM}. @xref{Top, ,Emacs SASL, sasl, Emacs SASL}. + +@item ManageSieve connections uses the @acronym{SASL} library by default. + +The primary change this brings is support for @acronym{DIGEST-MD5} and +@acronym{NTLM}, when the server supports it. + +@item Gnus includes a password cache mechanism in password.el. + +It is enabled by default (see @code{password-cache}), with a short +timeout of 16 seconds (see @code{password-cache-expiry}). If +@acronym{PGG} is used as the @acronym{PGP} back end, the @acronym{PGP} +passphrase is managed by this mechanism. Passwords for ManageSieve +connections are managed by this mechanism, after querying the user +about whether to do so. + +@item Using EasyPG with Gnus +When EasyPG, is available, Gnus will use it instead of @acronym{PGG}. +EasyPG is an Emacs user interface to GNU Privacy Guard. @xref{Top, +,EasyPG Assistant user's manual, epa, EasyPG Assistant user's manual}. +EasyPG is included in Emacs 23 and available separately as well. +@end itemize + +@item Changes in group mode +@c ************************ + +@itemize @bullet + +@item +Symbols like @code{gcc-self} now have the same precedence rules in +@code{gnus-parameters} as other ``real'' variables: The last match +wins instead of the first match. + +@item +Old intermediate incoming mail files (@file{Incoming*}) are deleted +after a couple of days, not immediately. @xref{Mail Source +Customization}. +(New in Gnus 5.10.10 / No Gnus 0.8) +@c This entry is also present in the node "Oort Gnus". + +@end itemize + +@item Changes in summary and article mode + +@itemize @bullet + +@item There's now only one variable that determines how @acronym{HTML} +is rendered: @code{mm-text-html-renderer}. + +@item Gnus now supports sticky article buffers. Those are article buffers +that are not reused when you select another article. @xref{Sticky +Articles}. + +@c @item Bookmarks +@c FIXME: To be added + +@item Gnus can selectively display @samp{text/html} articles +with a WWW browser with @kbd{K H}. @xref{MIME Commands}. + +@c gnus-registry-marks +@c FIXME: To be added + +@item International host names (@acronym{IDNA}) can now be decoded +inside article bodies using @kbd{W i} +(@code{gnus-summary-idna-message}). This requires that GNU Libidn +(@url{https://www.gnu.org/software/libidn/}) has been installed. +@c FIXME: Also mention @code{message-use-idna}? + +@item The non-@acronym{ASCII} group names handling has been much +improved. The back ends that fully support non-@acronym{ASCII} group +names are now @code{nntp}, @code{nnml}, and @code{nnrss}. Also the +agent, the cache, and the marks features work with those back ends. +@xref{Non-ASCII Group Names}. + +@item Gnus now displays @acronym{DNS} master files sent as text/dns +using dns-mode. + +@item Gnus supports new limiting commands in the Summary buffer: +@kbd{/ r} (@code{gnus-summary-limit-to-replied}) and @kbd{/ R} +(@code{gnus-summary-limit-to-recipient}). @xref{Limiting}. + +@item You can now fetch all ticked articles from the server using +@kbd{Y t} (@code{gnus-summary-insert-ticked-articles}). @xref{Summary +Generation Commands}. + +@item Gnus supports a new sort command in the Summary buffer: +@kbd{C-c C-s C-t} (@code{gnus-summary-sort-by-recipient}). @xref{Summary +Sorting}. + +@item @acronym{S/MIME} now features @acronym{LDAP} user certificate searches. +You need to configure the server in @code{smime-ldap-host-list}. + +@item URLs inside Open@acronym{PGP} headers are retrieved and imported +to your PGP key ring when you click on them. + +@item +Picons can be displayed right from the textual address, see +@code{gnus-picon-style}. @xref{Picons}. + +@item @acronym{ANSI} @acronym{SGR} control sequences can be transformed +using @kbd{W A}. + +@acronym{ANSI} sequences are used in some Chinese hierarchies for +highlighting articles (@code{gnus-article-treat-ansi-sequences}). + +@item Gnus now MIME decodes articles even when they lack "MIME-Version" header. +This changes the default of @code{gnus-article-loose-mime}. + +@item @code{gnus-decay-scores} can be a regexp matching score files. +For example, set it to @samp{\\.ADAPT\\'} and only adaptive score files +will be decayed. @xref{Score Decays}. + +@item Strings prefixing to the @code{To} and @code{Newsgroup} headers in +summary lines when using @code{gnus-ignored-from-addresses} can be +customized with @code{gnus-summary-to-prefix} and +@code{gnus-summary-newsgroup-prefix}. @xref{To From Newsgroups}. + +@item You can replace @acronym{MIME} parts with external bodies. +See @code{gnus-mime-replace-part} and @code{gnus-article-replace-part}. +@xref{MIME Commands}, @ref{Using MIME}. + +@item +The option @code{mm-fill-flowed} can be used to disable treatment of +format=flowed messages. Also, flowed text is disabled when sending +inline @acronym{PGP} signed messages. @xref{Flowed text, ,Flowed text, +emacs-mime, The Emacs MIME Manual}. (New in Gnus 5.10.7) +@c This entry is also present in the node "Oort Gnus". + +@item Now the new command @kbd{S W} +(@code{gnus-article-wide-reply-with-original}) for a wide reply in the +article buffer yanks a text that is in the active region, if it is set, +as well as the @kbd{R} (@code{gnus-article-reply-with-original}) command. +Note that the @kbd{R} command in the article buffer no longer accepts a +prefix argument, which was used to make it do a wide reply. +@xref{Article Keymap}. + +@item The new command @kbd{C-h b} +(@code{gnus-article-describe-bindings}) used in the article buffer now +shows not only the article commands but also the real summary commands +that are accessible from the article buffer. + +@end itemize + +@item Changes in Message mode + +@itemize @bullet +@item Gnus now defaults to saving all outgoing messages in per-month +nnfolder archives. + +@item Gnus now supports the ``hashcash'' client puzzle anti-spam mechanism. +Use @code{(setq message-generate-hashcash t)} to enable. +@xref{Hashcash}. + +@item You can now drag and drop attachments to the Message buffer. +See @code{mml-dnd-protocol-alist} and @code{mml-dnd-attach-options}. +@xref{MIME, ,MIME, message, Message Manual}. + +@item The option @code{message-yank-empty-prefix} now controls how +empty lines are prefixed in cited text. @xref{Insertion Variables, +,Insertion Variables, message, Message Manual}. + +@item Gnus uses narrowing to hide headers in Message buffers. +The @code{References} header is hidden by default. To make all +headers visible, use @code{(setq message-hidden-headers nil)}. +@xref{Message Headers, ,Message Headers, message, Message Manual}. + +@item You can highlight different levels of citations like in the +article buffer. See @code{gnus-message-highlight-citation}. + +@item @code{auto-fill-mode} is enabled by default in Message mode. +See @code{message-fill-column}. @xref{Various Message Variables, , +Message Headers, message, Message Manual}. + +@item You can now store signature files in a special directory +named @code{message-signature-directory}. + +@item The option @code{message-citation-line-format} controls the format +of the "Whomever writes:" line. You need to set +@code{message-citation-line-function} to +@code{message-insert-formatted-citation-line} as well. +@end itemize + +@item Changes in Browse Server mode + +@itemize @bullet +@item Gnus' sophisticated subscription methods are now available in +Browse Server buffers as well using the variable +@code{gnus-browse-subscribe-newsgroup-method}. + +@end itemize + + +@item Changes in back ends + +@itemize @bullet +@item The nntp back end stores article marks in @file{~/News/marks}. + +The directory can be changed using the (customizable) variable +@code{nntp-marks-directory}, and marks can be disabled using the +(back end) variable @code{nntp-marks-is-evil}. The advantage of this +is that you can copy @file{~/News/marks} (using rsync, scp or +whatever) to another Gnus installation, and it will realize what +articles you have read and marked. The data in @file{~/News/marks} +has priority over the same data in @file{~/.newsrc.eld}. + +@item +You can import and export your @acronym{RSS} subscriptions from +@acronym{OPML} files. @xref{RSS}. + +@item @acronym{IMAP} identity (@acronym{RFC} 2971) is supported. + +By default, Gnus does not send any information about itself, but you can +customize it using the variable @code{nnimap-id}. + +@item The @code{nnrss} back end now supports multilingual text. +Non-@acronym{ASCII} group names for the @code{nnrss} groups are also +supported. @xref{RSS}. + +@item Retrieving mail with @acronym{POP3} is supported over @acronym{SSL}/@acronym{TLS} and with StartTLS. + +@item The nnml back end allows other compression programs beside @file{gzip} +for compressed message files. @xref{Mail Spool}. + +@item The nnml back end supports group compaction. + +This feature, accessible via the functions +@code{gnus-group-compact-group} (@kbd{G z} in the group buffer) and +@code{gnus-server-compact-server} (@kbd{z} in the server buffer) +renumbers all articles in a group, starting from 1 and removing gaps. +As a consequence, you get a correct total article count (until +messages are deleted again). + +@c @item nnmairix.el +@c FIXME + +@c @item nnir.el +@c FIXME + +@end itemize + +@item Appearance +@c Maybe it's not worth to separate this from "Miscellaneous"? + +@itemize @bullet + +@item The tool bar has been updated to use GNOME icons. +You can also customize the tool bars: @kbd{M-x customize-apropos @key{RET} +-tool-bar$} should get you started. (Only for Emacs, not in XEmacs.) +@c FIXME: Document this in the manual + +@item The tool bar icons are now (de)activated correctly +in the group buffer, see the variable @code{gnus-group-update-tool-bar}. +Its default value depends on your Emacs version. +@c FIXME: Document this in the manual + +@item You can change the location of XEmacs's toolbars in Gnus buffers. +See @code{gnus-use-toolbar} and @code{message-use-toolbar}. + +@end itemize + +@item Miscellaneous changes + +@itemize @bullet +@item Having edited the select-method for the foreign server in the +server buffer is immediately reflected to the subscription of the groups +which use the server in question. For instance, if you change +@code{nntp-via-address} into @samp{bar.example.com} from +@samp{foo.example.com}, Gnus will connect to the news host by way of the +intermediate host @samp{bar.example.com} from next time. + +@item The @file{all.SCORE} file can be edited from the group buffer +using @kbd{W e}. + +@item You can set @code{gnus-mark-copied-or-moved-articles-as-expirable} +to a non-@code{nil} value so that articles that have been read may be +marked as expirable automatically when copying or moving them to a group +that has auto-expire turned on. The default is @code{nil} and copying +and moving of articles behave as before; i.e., the expirable marks will +be unchanged except that the marks will be removed when copying or +moving articles to a group that has not turned auto-expire on. +@xref{Expiring Mail}. + +@item NoCeM support has been removed. + +@item Carpal mode has been removed. + +@end itemize + +@end itemize + @node Ma Gnus @subsubsection Ma Gnus @@ -30053,7 +30456,7 @@ Below is a slightly shortened version of the @code{nndir} back end. nnml-current-directory nnmh-current-directory) (defvoo nndir-nov-is-evil nil - "*Non-nil means that nndir will never retrieve NOV headers." + "Non-nil means that nndir will never retrieve NOV headers." nnml-nov-is-evil) (defvoo nndir-current-group "" diff --git a/doc/misc/message.texi b/doc/misc/message.texi index 21a57590066..7089bb5dfe3 100644 --- a/doc/misc/message.texi +++ b/doc/misc/message.texi @@ -1,7 +1,5 @@ \input texinfo @c -*-texinfo-*- -@include gnus-overrides.texi - @setfilename ../../info/message.info @settitle Message Manual @include docstyle.texi @@ -162,7 +160,7 @@ header should be. If it does not, it should just return @code{nil}, and the normal methods for determining the To header will be used. Each list element should be a cons, where the @sc{car} should be the -name of a header (e.g., @code{Cc}) and the @sc{cdr} should be the header +name of a header (e.g., @code{CC}) and the @sc{cdr} should be the header value (e.g., @samp{larsi@@ifi.uio.no}). All these headers will be inserted into the head of the outgoing mail. @@ -174,7 +172,7 @@ inserted into the head of the outgoing mail. The @code{message-wide-reply} pops up a message buffer that's a wide reply to the message in the current buffer. A @dfn{wide reply} is a reply that goes out to all people listed in the @code{To}, @code{From} -(or @code{Reply-to}) and @code{Cc} headers. +(or @code{Reply-To}) and @code{CC} headers. @vindex message-wide-reply-to-function Message uses the normal methods to determine where wide replies are to go, @@ -185,7 +183,7 @@ but you can change the behavior to suit your needs by fiddling with the @vindex message-dont-reply-to-names Addresses that match the @code{message-dont-reply-to-names} regular expression (or list of regular expressions or a predicate function) -will be removed from the @code{Cc} header. A value of @code{nil} means +will be removed from the @code{CC} header. A value of @code{nil} means to exclude only your email address. @vindex message-prune-recipient-rules @@ -199,7 +197,7 @@ to match addresses to be pruned. It's complicated to explain, but it's easy to use. For instance, if you get an email from @samp{foo@@example.org}, but -@samp{foo@@zot.example.org} is also in the @code{Cc} list, then your +@samp{foo@@zot.example.org} is also in the @code{CC} list, then your wide reply will go out to both these addresses, since they are unique. To avoid this, do something like the following: @@ -316,7 +314,7 @@ when forwarding a message. @item message-forward-included-headers @vindex message-forward-included-headers In non-@code{nil}, only headers that match this regexp will be kept -when forwarding a message. +when forwarding a message. This can also be a list of regexps. @item message-make-forward-subject-function @vindex message-make-forward-subject-function @@ -345,10 +343,10 @@ constructed. The default value is @code{nil}. @item message-forward-as-mime @vindex message-forward-as-mime -If this variable is @code{t} (the default), forwarded messages are -included as inline @acronym{MIME} RFC822 parts. If it's @code{nil}, forwarded -messages will just be copied inline to the new message, like previous, -non @acronym{MIME}-savvy versions of Gnus would do. +If this variable is @code{t}, forwarded messages are included as +inline @acronym{MIME} RFC822 parts. If it's @code{nil} (the default), +forwarded messages will just be copied inline to the new message, like +previous, non @acronym{MIME}-savvy versions of Gnus would do. @item message-forward-before-signature @vindex message-forward-before-signature @@ -487,10 +485,10 @@ MFT field. If there is one, it is left alone. (Except if it's empty; in that case, the field is removed and is not replaced with an automatically generated one. This lets you disable MFT generation on a per-message basis.) If there is none, then the list of recipient -addresses (in the To: and Cc: headers) is checked to see if one of them +addresses (in the To: and CC: headers) is checked to see if one of them is a list address you are subscribed to. If none of them is a list address, then no MFT is generated; otherwise, a MFT is added to the -other headers and set to the value of all addresses in To: and Cc: +other headers and set to the value of all addresses in To: and CC: @kindex C-c C-f C-a @findex message-generate-unsubscribed-mail-followup-to @@ -516,7 +514,7 @@ header, Gnus' action will depend on the value of the variable @table @code @item use - Always honor MFTs. The To: and Cc: headers in your followup will be + Always honor MFTs. The To: and CC: headers in your followup will be derived from the MFT header of the original post. This is the default. @item nil @@ -593,17 +591,17 @@ in the key binding is for Originator.) @item C-c C-f C-b @kindex C-c C-f C-b @findex message-goto-bcc -Go to the @code{Bcc} header (@code{message-goto-bcc}). +Go to the @code{BCC} header (@code{message-goto-bcc}). @item C-c C-f C-w @kindex C-c C-f C-w @findex message-goto-fcc -Go to the @code{Fcc} header (@code{message-goto-fcc}). +Go to the @code{FCC} header (@code{message-goto-fcc}). @item C-c C-f C-c @kindex C-c C-f C-c @findex message-goto-cc -Go to the @code{Cc} header (@code{message-goto-cc}). +Go to the @code{CC} header (@code{message-goto-cc}). @item C-c C-f C-s @kindex C-c C-f C-s @@ -662,7 +660,7 @@ fetches the contents of the @samp{To:} header in the current mail buffer, and appends the current @code{user-mail-address}. If the optional argument @code{include-cc} is non-@code{nil}, the -addresses in the @samp{Cc:} header are also put into the +addresses in the @samp{CC:} header are also put into the @samp{Mail-Followup-To:} header. @end table @@ -696,7 +694,7 @@ or @code{Newsgroups} header of the article you're replying to @kindex C-c C-l @findex message-to-list-only Send a message to the list only. Remove all addresses but the list -address from @code{To:} and @code{Cc:} headers. +address from @code{To:} and @code{CC:} headers. @item C-c M-n @kindex C-c M-n @@ -746,13 +744,13 @@ by the @code{message-cross-post-note-function} variable. @item C-c C-f t @kindex C-c C-f t @findex message-reduce-to-to-cc -Replace contents of @samp{To} header with contents of @samp{Cc} -header (or the @samp{Bcc} header, if there is no @samp{Cc} header). +Replace contents of @samp{To} header with contents of @samp{CC} +header (or the @samp{BCC} header, if there is no @samp{CC} header). @item C-c C-f w @kindex C-c C-f w @findex message-insert-wide-reply -Insert @samp{To} and @samp{Cc} headers as if you were doing a wide +Insert @samp{To} and @samp{CC} headers as if you were doing a wide reply even if the message was not made for a wide reply first. @item C-c C-f a @@ -902,7 +900,7 @@ found in RFC 3490. Message is a @acronym{IDNA}-compliant posting agent. The user generally doesn't have to do anything to make the @acronym{IDNA} happen---Message will encode non-@acronym{ASCII} domain names in @code{From}, -@code{To}, and @code{Cc} headers automatically. +@code{To}, and @code{CC} headers automatically. Until @acronym{IDNA} becomes more well known, Message queries you whether @acronym{IDNA} encoding of the domain name really should @@ -1011,7 +1009,7 @@ and/or encrypted messages as explained in the following. * Passphrase caching:: How to cache passphrases * PGP Compatibility:: Compatibility with older implementations * Encrypt-to-self:: Reading your own encrypted messages -* Bcc Warning:: Do not use encryption with Bcc headers +* BCC Warning:: Do not use encryption with BCC headers @end menu @node Signing and encryption @@ -1300,7 +1298,7 @@ information about the problem.) @subsection Encrypt-to-self By default, messages are encrypted to all recipients (@code{To}, -@code{Cc}, @code{Bcc} headers). Thus, you will not be able to decrypt +@code{CC}, @code{BCC} headers). Thus, you will not be able to decrypt your own messages. To make sure that messages are also encrypted to your own key(s), several alternative solutions exist: @enumerate @@ -1318,17 +1316,17 @@ OpenPGP) or @code{mml-secure-smime-encrypt-to-self} (for @acronym{S/MIME} with EasyPG). @end enumerate -@node Bcc Warning -@subsection Bcc Warning +@node BCC Warning +@subsection BCC Warning -The @code{Bcc} header is meant to hide recipients of messages. +The @code{BCC} header is meant to hide recipients of messages. However, when encrypted messages are used, the e-mail addresses of all -@code{Bcc}-headers are given away to all recipients without +@code{BCC}-headers are given away to all recipients without warning, which is a bug. @vindex mml-secure-safe-bcc-list -But now Message got to warn if @code{Bcc} recipients are found in an +But now Message got to warn if @code{BCC} recipients are found in an encrypted message when you are just about to send it. If you are sure -those @code{Bcc} addresses are safe to expose, set the +those @code{BCC} addresses are safe to expose, set the @code{mml-secure-safe-bcc-list} variable, that is a list of e-mail addresses. See @uref{https://debbugs.gnu.org/cgi/bugreport.cgi?bug=18718}. @@ -1468,20 +1466,24 @@ alias ding "ding@@ifi.uio.no (ding mailing list)" @end example After adding lines like this to your @file{~/.mailrc} file, you should -be able to just write @samp{lmi} in the @code{To} or @code{Cc} (and so +be able to just write @samp{lmi} in the @code{To} or @code{CC} (and so on) headers and press @kbd{SPC} to expand the alias. No expansion will be performed upon sending of the message---all expansions have to be done explicitly. If you're using @code{ecomplete}, all addresses from @code{To} and -@code{Cc} headers will automatically be put into the +@code{CC} headers will automatically be put into the @file{~/.ecompleterc} file. When you enter text in the @code{To} and -@code{Cc} headers, @code{ecomplete} will check out the values stored +@code{CC} headers, @code{ecomplete} will check out the values stored there and ``electrically'' say what completions are possible. To choose one of these completions, use the @kbd{M-n} command to move -down to the list. Use @kbd{M-n} and @kbd{M-p} to move down and up the -list, and @kbd{RET} to choose a completion. +down to the list. Use @kbd{@key{DOWN}} or @kbd{M-n} and +@kbd{@key{UP}} or @kbd{M-p} to move down and up the list, and +@kbd{@key{RET}} to choose a completion. + +The @code{ecomplete-sort-predicate} variable controls how +@code{ecomplete} matches are sorted. @node Spelling @section Spelling @@ -1677,7 +1679,7 @@ trailing old subject. In this case, @item message-alternative-emails @vindex message-alternative-emails Regexp or predicate function matching alternative email addresses. -The first address in the To, Cc or From headers of the original +The first address in the To, CC or From headers of the original article matching this variable is used as the From field of outgoing messages, replacing the default From value. @@ -1697,7 +1699,7 @@ off @code{message-setup-hook}. @item message-allow-no-recipients @vindex message-allow-no-recipients Specifies what to do when there are no recipients other than -@code{Gcc} or @code{Fcc}. If it is @code{always}, the posting is +@code{Gcc} or @code{FCC}. If it is @code{always}, the posting is allowed. If it is @code{never}, the posting is not allowed. If it is @code{ask} (the default), you are prompted. @@ -1709,7 +1711,7 @@ hidden when composing a message. @lisp (setq message-hidden-headers - '(not "From" "Subject" "To" "Cc" "Newsgroups")) + '(not "From" "Subject" "To" "CC" "Newsgroups")) @end lisp Headers are hidden using narrowing, you can use @kbd{M-x widen} to @@ -1718,9 +1720,9 @@ expose them in the buffer. @item message-header-synonyms @vindex message-header-synonyms A list of lists of header synonyms. E.g., if this list contains a -member list with elements @code{Cc} and @code{To}, then +member list with elements @code{CC} and @code{To}, then @code{message-carefully-insert-headers} will not insert a @code{To} -header when the message is already @code{Cc}ed to the recipient. +header when the message is already @code{CC}ed to the recipient. @end table @@ -1738,7 +1740,7 @@ header when the message is already @code{Cc}ed to the recipient. @item message-ignored-mail-headers @vindex message-ignored-mail-headers Regexp of headers to be removed before mailing. The default is@* -@samp{^[GF]cc:\\|^Resent-Fcc:\\|^Xref:\\|^X-Draft-From:\\|@* +@samp{^[GF]cc:\\|^Resent-FCC:\\|^Xref:\\|^X-Draft-From:\\|@* ^X-Gnus-Agent-Meta-Information:}. @item message-default-mail-headers @@ -2052,7 +2054,7 @@ Check whether the @code{Newsgroups} header exists and is not empty. @item quoting-style Check whether text follows last quoted portion. @item repeated-newsgroups -Check whether the @code{Newsgroups} and @code{Followup-to} headers +Check whether the @code{Newsgroups} and @code{Followup-To} headers contains repeated group names. @item reply-to Check whether the @code{Reply-To} header looks ok. @@ -2065,7 +2067,7 @@ Check for the existence of version and sendsys commands. @item shoot Check whether the domain part of the @code{Message-ID} header looks ok. @item shorten-followup-to -Check whether to add a @code{Followup-to} header to shorten the number +Check whether to add a @code{Followup-To} header to shorten the number of groups to post to. @item signature Check the length of the signature. @@ -2076,7 +2078,7 @@ Check whether the @code{Subject} header exists and is not empty. @item subject-cmsg Check the subject for commands. @item valid-newsgroups -Check whether the @code{Newsgroups} and @code{Followup-to} headers +Check whether the @code{Newsgroups} and @code{Followup-To} headers are valid syntactically. @end table @@ -2087,7 +2089,7 @@ for which the check is disabled by default if @item message-ignored-news-headers @vindex message-ignored-news-headers Regexp of headers to be removed before posting. The default is@* -@samp{^NNTP-Posting-Host:\\|^Xref:\\|^[BGF]cc:\\|^Resent-Fcc:\\|@* +@samp{^NNTP-Posting-Host:\\|^Xref:\\|^[BGF]cc:\\|^Resent-FCC:\\|@* ^X-Draft-From:\\|^X-Gnus-Agent-Meta-Information:}. @item message-default-news-headers @@ -2467,7 +2469,7 @@ an article\\nthat has been posted to %s as well.\\n\\n"}. @item message-fcc-externalize-attachments @vindex message-fcc-externalize-attachments -If @code{nil}, attach files as normal parts in Fcc copies; if it is +If @code{nil}, attach files as normal parts in FCC copies; if it is non-@code{nil}, attach local files as external parts. @item message-interactive @@ -2622,13 +2624,13 @@ consulted, in turn: A @dfn{wide reply} is a mail response that includes @emph{all} entities mentioned in the message you are responding to. All mailboxes from the following headers will be concatenated to form the outgoing -@code{To}/@code{Cc} headers: +@code{To}/@code{CC} headers: @table @code @item From (unless there's a @code{Reply-To}, in which case that is used instead). -@item Cc +@item CC @item To @end table @@ -2652,7 +2654,7 @@ sent: @end table If a @code{Mail-Copies-To} header is present, it will be used as the -basis of the new @code{Cc} header, except if this header is +basis of the new @code{CC} header, except if this header is @samp{never}. @end table diff --git a/doc/misc/mh-e.texi b/doc/misc/mh-e.texi index 52e22178b2d..25dd53c4fb9 100644 --- a/doc/misc/mh-e.texi +++ b/doc/misc/mh-e.texi @@ -847,9 +847,9 @@ sending the original message, like this: To: cc: Subject: Re: Test -In-reply-to: <31054.1142621351@@stop.mail-abuse.org> +In-Reply-To: <31054.1142621351@@stop.mail-abuse.org> References: <31054.1142621351@@stop.mail-abuse.org> -Comments: In-reply-to Bill Wohler <wohler@@stop.mail-abuse.org> +Comments: In-Reply-To Bill Wohler <wohler@@stop.mail-abuse.org> message dated "Fri, 17 Mar 2006 10:49:11 -0800." X-Mailer: MH-E 8.1; nmh 1.1; GNU Emacs 23.1 -------- @@ -2589,13 +2589,6 @@ centers the output and wraps long lines more than most. It does not always handle special characters like @samp{®} or @samp{–}. It does not download images. @c ------------------------- -@item @samp{nil} -This choice obviously requires an external browser. With this setting, -HTML messages have a button for the body part which you can view with -@kbd{K v} (@code{mh-folder-toggle-mime-part}). Rendering of special -characters and handling of remote images depends on your choice of -browser. -@c ------------------------- @item @samp{shr} @cindex @samp{shr} This choice does not require an external program, but it does require diff --git a/doc/misc/org.texi b/doc/misc/org.texi index b3c0d52db1b..de3b7bbed49 100644 --- a/doc/misc/org.texi +++ b/doc/misc/org.texi @@ -891,9 +891,7 @@ org}. been visited, i.e., where no Org built-in function have been loaded. Otherwise autoload Org functions will mess up the installation. -Then, to make sure your Org configuration is taken into account, initialize -the package system with @code{(package-initialize)} in your Emacs init file -before setting any Org option. If you want to use Org's package repository, +If you want to use Org's package repository, check out the @uref{https://orgmode.org/elpa.html, Org ELPA page}. @subsubheading Downloading Org as an archive @@ -9689,7 +9687,7 @@ If you are away from your computer, it can be very useful to have a printed version of some agenda views to carry around. Org mode can export custom agenda views as plain text, HTML@footnote{You need to install @file{htmlize.el} from @uref{https://github.com/hniksic/emacs-htmlize,Hrvoje -Niksic's repository.}}, Postscript, PDF@footnote{To create PDF output, the +Nikšić's repository.}}, Postscript, PDF@footnote{To create PDF output, the ghostscript @file{ps2pdf} utility must be installed on the system. Selecting a PDF file will also create the postscript file.}, and iCalendar files. If you want to do this only occasionally, use the command @@ -18168,7 +18166,7 @@ Suggested Org crypt settings in Emacs init file: @lisp (require 'org-crypt) (org-crypt-use-before-save-magic) -(setq org-tags-exclude-from-inheritance (quote ("crypt"))) +(setq org-tags-exclude-from-inheritance '("crypt")) (setq org-crypt-key nil) ;; GPG key to use for encryption @@ -19707,8 +19705,8 @@ mentioned in the manual. For a complete list, use @kbd{M-x org-customize @c Local variables: @c fill-column: 77 @c indent-tabs-mode: nil -@c paragraph-start: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$" -@c paragraph-separate: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$" +@c paragraph-start: "^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$" +@c paragraph-separate: "^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$" @c End: diff --git a/doc/misc/pgg.texi b/doc/misc/pgg.texi index ffb8e4a3578..2fac24a4277 100644 --- a/doc/misc/pgg.texi +++ b/doc/misc/pgg.texi @@ -1,7 +1,5 @@ \input texinfo @c -*-texinfo-*- -@include gnus-overrides.texi - @setfilename ../../info/pgg.info @set VERSION 0.1 diff --git a/doc/misc/rcirc.texi b/doc/misc/rcirc.texi index bbcd0ed4620..1482a14fad5 100644 --- a/doc/misc/rcirc.texi +++ b/doc/misc/rcirc.texi @@ -337,9 +337,10 @@ channel name and join that channel. (Also @code{/join #emacs}.) @cindex disconnect from a channel @cindex stop talking on a channel @cindex kill channel buffer -This leaves the current channel. You can optionally provide a reason -for parting. When you kill a channel buffer, you automatically part the -corresponding channel. (Also @code{/part you are too weird!}.) +This leaves the current channel. You can optionally provide a +different channel name and reason for parting. When you kill a +channel buffer, you automatically part the corresponding channel. +(Also @code{/part #emacs you are too weird!}.) @item C-c C-r @kindex C-c C-r diff --git a/doc/misc/sasl.texi b/doc/misc/sasl.texi index 3e7768d3191..1d31150f045 100644 --- a/doc/misc/sasl.texi +++ b/doc/misc/sasl.texi @@ -1,7 +1,5 @@ \input texinfo @c -*-texinfo-*- -@include gnus-overrides.texi - @setfilename ../../info/sasl.info @set VERSION 0.2 diff --git a/doc/misc/sieve.texi b/doc/misc/sieve.texi index 7f28994f1e3..2d07b0a8d7b 100644 --- a/doc/misc/sieve.texi +++ b/doc/misc/sieve.texi @@ -1,7 +1,5 @@ \input texinfo @c -*-texinfo-*- -@include gnus-overrides.texi - @setfilename ../../info/sieve.info @settitle Emacs Sieve Manual @include docstyle.texi diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex index f2be62ce47b..ed3f0ee98f4 100644 --- a/doc/misc/texinfo.tex +++ b/doc/misc/texinfo.tex @@ -3,10 +3,9 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2017-12-26.21} +\def\texinfoversion{2019-06-01.23} % -% Copyright 1985-1986, 1988, 1990-2017, 2019 Free Software Foundation, -% Inc. +% Copyright 1985, 1986, 1988, 1990-2019 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 @@ -242,17 +241,7 @@ % \def\finalout{\overfullrule=0pt } -% Do @cropmarks to get crop marks. -% -\newif\ifcropmarks -\let\cropmarks = \cropmarkstrue -% -% Dimensions to add cropmarks at corners. -% Added by P. A. MacKay, 12 Nov. 1986 -% \newdimen\outerhsize \newdimen\outervsize % set by the paper size routines -\newdimen\cornerlong \cornerlong=1pc -\newdimen\cornerthick \cornerthick=.3pt \newdimen\topandbottommargin \topandbottommargin=.75in % Output a mark which sets \thischapter, \thissection and \thiscolor. @@ -268,8 +257,8 @@ % \domark is called twice inside \chapmacro, to add one % mark before the section break, and one after. -% In the second call \prevchapterdefs is the same as \lastchapterdefs, -% and \prevsectiondefs is the same as \lastsectiondefs. +% In the second call \prevchapterdefs is the same as \currentchapterdefs, +% and \prevsectiondefs is the same as \currentsectiondefs. % Then if the page is not broken at the mark, some of the previous % section appears on the page, and we can get the name of this section % from \firstmark for @everyheadingmarks top. @@ -277,11 +266,11 @@ % % See page 260 of The TeXbook. \def\domark{% - \toks0=\expandafter{\lastchapterdefs}% - \toks2=\expandafter{\lastsectiondefs}% + \toks0=\expandafter{\currentchapterdefs}% + \toks2=\expandafter{\currentsectiondefs}% \toks4=\expandafter{\prevchapterdefs}% \toks6=\expandafter{\prevsectiondefs}% - \toks8=\expandafter{\lastcolordefs}% + \toks8=\expandafter{\currentcolordefs}% \mark{% \the\toks0 \the\toks2 % 0: marks for @everyheadingmarks top \noexpand\or \the\toks4 \the\toks6 % 1: for @everyheadingmarks bottom @@ -298,19 +287,19 @@ % @setcolor (or @url, or @link, etc.) between @contents and the very % first @chapter. \def\gettopheadingmarks{% - \ifcase0\topmark\fi + \ifcase0\the\savedtopmark\fi \ifx\thischapter\empty \ifcase0\firstmark\fi \fi } \def\getbottomheadingmarks{\ifcase1\botmark\fi} -\def\getcolormarks{\ifcase2\topmark\fi} +\def\getcolormarks{\ifcase2\the\savedtopmark\fi} % Avoid "undefined control sequence" errors. -\def\lastchapterdefs{} -\def\lastsectiondefs{} -\def\lastsection{} +\def\currentchapterdefs{} +\def\currentsectiondefs{} +\def\currentsection{} \def\prevchapterdefs{} \def\prevsectiondefs{} -\def\lastcolordefs{} +\def\currentcolordefs{} % Margin to add to right of even pages, to left of odd pages. \newdimen\bindingoffset @@ -320,39 +309,57 @@ % Main output routine. % \chardef\PAGE = 255 -\output = {\onepageout{\pagecontents\PAGE}} +\newtoks\defaultoutput +\defaultoutput = {\savetopmark\onepageout{\pagecontents\PAGE}} +\output=\expandafter{\the\defaultoutput} \newbox\headlinebox \newbox\footlinebox +% When outputting the double column layout for indices, an output routine +% is run several times, which hides the original value of \topmark. This +% can lead to a page heading being output and duplicating the chapter heading +% of the index. Hence, save the contents of \topmark at the beginning of +% the output routine. The saved contents are valid until we actually +% \shipout a page. +% +% (We used to run a short output routine to actually set \topmark and +% \firstmark to the right values, but if this was called with an empty page +% containing whatsits for writing index entries, the whatsits would be thrown +% away and the index auxiliary file would remain empty.) +% +\newtoks\savedtopmark +\newif\iftopmarksaved +\topmarksavedtrue +\def\savetopmark{% + \iftopmarksaved\else + \global\savedtopmark=\expandafter{\topmark}% + \global\topmarksavedtrue + \fi +} + % \onepageout takes a vbox as an argument. -% \shipout a vbox for a single page, adding an optional header, footer, -% cropmarks, and footnote. This also causes index entries for this page -% to be written to the auxiliary files. +% \shipout a vbox for a single page, adding an optional header, footer +% and footnote. This also causes index entries for this page to be written +% to the auxiliary files. % \def\onepageout#1{% - \ifcropmarks \hoffset=0pt \else \hoffset=\normaloffset \fi + \hoffset=\normaloffset % \ifodd\pageno \advance\hoffset by \bindingoffset \else \advance\hoffset by -\bindingoffset\fi % - % Common context changes for both heading and footing. - % Do this outside of the \shipout so @code etc. will be expanded in - % the headline as they should be, not taken literally (outputting ''code). - \def\commmonheadfootline{\let\hsize=\txipagewidth \texinfochars} - % % Retrieve the information for the headings from the marks in the page, % and call Plain TeX's \makeheadline and \makefootline, which use the % values in \headline and \footline. % % This is used to check if we are on the first page of a chapter. - \ifcase1\topmark\fi + \ifcase1\the\savedtopmark\fi \let\prevchaptername\thischaptername \ifcase0\firstmark\fi \let\curchaptername\thischaptername % \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi - \ifodd\pageno \getoddfootingmarks \else \getevenfootingmarks \fi % \ifx\curchaptername\prevchaptername \let\thischapterheading\thischapter @@ -363,7 +370,14 @@ \def\thischapterheading{}% \fi % + % Common context changes for both heading and footing. + % Do this outside of the \shipout so @code etc. will be expanded in + % the headline as they should be, not taken literally (outputting ''code). + \def\commmonheadfootline{\let\hsize=\txipagewidth \texinfochars} + % \global\setbox\headlinebox = \vbox{\commmonheadfootline \makeheadline}% + % + \ifodd\pageno \getoddfootingmarks \else \getevenfootingmarks \fi \global\setbox\footlinebox = \vbox{\commmonheadfootline \makefootline}% % {% @@ -372,37 +386,12 @@ % take effect in \write's, yet the group defined by the \vbox ends % before the \shipout runs. % - \indexdummies % don't expand commands in the output. - \normalturnoffactive % \ in index entries must not stay \, e.g., if - % the page break happens to be in the middle of an example. - % We don't want .vr (or whatever) entries like this: - % \entry{{\indexbackslash }acronym}{32}{\code {\acronym}} - % "\acronym" won't work when it's read back in; - % it needs to be - % {\code {{\backslashcurfont }acronym} + \atdummies % don't expand commands in the output. + \turnoffactive \shipout\vbox{% % Do this early so pdf references go to the beginning of the page. \ifpdfmakepagedest \pdfdest name{\the\pageno} xyz\fi % - \ifcropmarks \vbox to \outervsize\bgroup - \hsize = \outerhsize - \vskip-\topandbottommargin - \vtop to0pt{% - \line{\ewtop\hfil\ewtop}% - \nointerlineskip - \line{% - \vbox{\moveleft\cornerthick\nstop}% - \hfill - \vbox{\moveright\cornerthick\nstop}% - }% - \vss}% - \vskip\topandbottommargin - \line\bgroup - \hfil % center the page within the outer (page) hsize. - \ifodd\pageno\hskip\bindingoffset\fi - \vbox\bgroup - \fi - % \unvbox\headlinebox \pagebody{#1}% \ifdim\ht\footlinebox > 0pt @@ -413,24 +402,9 @@ \unvbox\footlinebox \fi % - \ifcropmarks - \egroup % end of \vbox\bgroup - \hfil\egroup % end of (centering) \line\bgroup - \vskip\topandbottommargin plus1fill minus1fill - \boxmaxdepth = \cornerthick - \vbox to0pt{\vss - \line{% - \vbox{\moveleft\cornerthick\nsbot}% - \hfill - \vbox{\moveright\cornerthick\nsbot}% - }% - \nointerlineskip - \line{\ewbot\hfil\ewbot}% - }% - \egroup % \vbox from first cropmarks clause - \fi - }% end of \shipout\vbox - }% end of group with \indexdummies + }% + }% + \global\topmarksavedfalse \advancepageno \ifnum\outputpenalty>-20000 \else\dosupereject\fi } @@ -449,17 +423,6 @@ \ifr@ggedbottom \kern-\dimen@ \vfil \fi} } -% Here are the rules for the cropmarks. Note that they are -% offset so that the space between them is truly \outerhsize or \outervsize -% (P. A. MacKay, 12 November, 1986) -% -\def\ewtop{\vrule height\cornerthick depth0pt width\cornerlong} -\def\nstop{\vbox - {\hrule height\cornerthick depth\cornerlong width\cornerthick}} -\def\ewbot{\vrule height0pt depth\cornerthick width\cornerlong} -\def\nsbot{\vbox - {\hrule height\cornerlong depth\cornerthick width\cornerthick}} - % Argument parsing @@ -485,11 +448,10 @@ }% } -% First remove any @comment, then any @c comment. Also remove a @texinfoc -% comment (see \scanmacro for details). Pass the result on to \argcheckspaces. +% First remove any @comment, then any @c comment. Pass the result on to +% \argcheckspaces. \def\argremovecomment#1\comment#2\ArgTerm{\argremovec #1\c\ArgTerm} -\def\argremovec#1\c#2\ArgTerm{\argremovetexinfoc #1\texinfoc\ArgTerm} -\def\argremovetexinfoc#1\texinfoc#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm} +\def\argremovec#1\c#2\ArgTerm{\argcheckspaces#1\^^M\ArgTerm} % Each occurrence of `\^^M' or `<space>\^^M' is replaced by a single space. % @@ -1161,6 +1123,16 @@ where each line of input produces a line of output.} \fi \fi +\newif\ifpdforxetex +\pdforxetexfalse +\ifpdf + \pdforxetextrue +\fi +\ifx\XeTeXrevision\thisisundefined\else + \pdforxetextrue +\fi + + % PDF uses PostScript string constants for the names of xref targets, % for display in the outlines, and in other places. Thus, we have to % double any backslashes. Otherwise, a name like "\node" will be @@ -1217,7 +1189,7 @@ output) for that.)} % Set color, and create a mark which defines \thiscolor accordingly, % so that \makeheadline knows which color to restore. \def\setcolor#1{% - \xdef\lastcolordefs{\gdef\noexpand\thiscolor{#1}}% + \xdef\currentcolordefs{\gdef\noexpand\thiscolor{#1}}% \domark \pdfsetcolor{#1}% } @@ -1225,7 +1197,7 @@ output) for that.)} \def\maincolor{\rgbBlack} \pdfsetcolor{\maincolor} \edef\thiscolor{\maincolor} - \def\lastcolordefs{} + \def\currentcolordefs{} % \def\makefootline{% \baselineskip24pt @@ -1526,6 +1498,9 @@ output) for that.)} \startlink attr{/Border [0 0 0]}% user{/Subtype /Link /A << /S /URI /URI (#1) >>}% \endgroup} + % \pdfgettoks - Surround page numbers in #1 with @pdflink. #1 may + % be a simple number, or a list of numbers in the case of an index + % entry. \def\pdfgettoks#1.{\setbox\boxA=\hbox{\toksA={#1.}\toksB={}\maketoks}} \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks} \def\adn#1{\addtokens{\toksC}{#1}\global\countA=1\let\next=\maketoks} @@ -1600,7 +1575,7 @@ output) for that.)} % Set color, and create a mark which defines \thiscolor accordingly, % so that \makeheadline knows which color to restore. \def\setcolor#1{% - \xdef\lastcolordefs{\gdef\noexpand\thiscolor{#1}}% + \xdef\currentcolordefs{\gdef\noexpand\thiscolor{#1}}% \domark \pdfsetcolor{#1}% } @@ -1608,7 +1583,7 @@ output) for that.)} \def\maincolor{\rgbBlack} \pdfsetcolor{\maincolor} \edef\thiscolor{\maincolor} - \def\lastcolordefs{} + \def\currentcolordefs{} % \def\makefootline{% \baselineskip24pt @@ -2200,7 +2175,7 @@ end % A few fonts for @defun names and args. \setfont\defbf\bfshape{10}{\magstep1}{OT1} \setfont\deftt\ttshape{10}{\magstep1}{OT1TT} -\setfont\defsl\slshape{10}{\magstep1}{OT1TT} +\setfont\defsl\slshape{10}{\magstep1}{OT1} \setfont\defttsl\ttslshape{10}{\magstep1}{OT1TT} \def\df{\let\ttfont=\deftt \let\bffont = \defbf \let\ttslfont=\defttsl \let\slfont=\defsl \bf} @@ -2233,6 +2208,20 @@ end \font\smallersy=cmsy8 \def\smallerecsize{0800} +% Fonts for math mode superscripts (7pt). +\def\sevennominalsize{7pt} +\setfont\sevenrm\rmshape{7}{1000}{OT1} +\setfont\seventt\ttshape{10}{700}{OT1TT} +\setfont\sevenbf\bfshape{10}{700}{OT1} +\setfont\sevenit\itshape{7}{1000}{OT1IT} +\setfont\sevensl\slshape{10}{700}{OT1} +\setfont\sevensf\sfshape{10}{700}{OT1} +\setfont\sevensc\scshape{10}{700}{OT1} +\setfont\seventtsl\ttslshape{10}{700}{OT1TT} +\font\seveni=cmmi7 +\font\sevensy=cmsy7 +\def\sevenecsize{0700} + % Fonts for title page (20.4pt): \def\titlenominalsize{20pt} \setfont\titlerm\rmbshape{12}{\magstep3}{OT1} @@ -2334,7 +2323,7 @@ end % A few fonts for @defun names and args. \setfont\defbf\bfshape{10}{\magstephalf}{OT1} \setfont\deftt\ttshape{10}{\magstephalf}{OT1TT} -\setfont\defsl\slshape{10}{\magstephalf}{OT1TT} +\setfont\defsl\slshape{10}{\magstephalf}{OT1} \setfont\defttsl\ttslshape{10}{\magstephalf}{OT1TT} \def\df{\let\ttfont=\deftt \let\bffont = \defbf \let\slfont=\defsl \let\ttslfont=\defttsl \bf} @@ -2367,6 +2356,20 @@ end \font\smallersy=cmsy8 \def\smallerecsize{0800} +% Fonts for math mode superscripts (7pt). +\def\sevennominalsize{7pt} +\setfont\sevenrm\rmshape{7}{1000}{OT1} +\setfont\seventt\ttshape{10}{700}{OT1TT} +\setfont\sevenbf\bfshape{10}{700}{OT1} +\setfont\sevenit\itshape{7}{1000}{OT1IT} +\setfont\sevensl\slshape{10}{700}{OT1} +\setfont\sevensf\sfshape{10}{700}{OT1} +\setfont\sevensc\scshape{10}{700}{OT1} +\setfont\seventtsl\ttslshape{10}{700}{OT1TT} +\font\seveni=cmmi7 +\font\sevensy=cmsy7 +\def\sevenecsize{0700} + % Fonts for title page (20.4pt): \def\titlenominalsize{20pt} \setfont\titlerm\rmbshape{12}{\magstep3}{OT1} @@ -2501,13 +2504,20 @@ end % In order for the font changes to affect most math symbols and letters, -% we have to define the \textfont of the standard families. We don't -% bother to reset \scriptfont and \scriptscriptfont; awaiting user need. +% we have to define the \textfont of the standard families. +% We don't bother to reset \scriptscriptfont; awaiting user need. % \def\resetmathfonts{% \textfont0=\rmfont \textfont1=\ifont \textfont2=\syfont \textfont\itfam=\itfont \textfont\slfam=\slfont \textfont\bffam=\bffont \textfont\ttfam=\ttfont \textfont\sffam=\sffont + % + % Fonts for superscript. Note that the 7pt fonts are used regardless + % of the current font size. + \scriptfont0=\sevenrm \scriptfont1=\seveni \scriptfont2=\sevensy + \scriptfont\itfam=\sevenit \scriptfont\slfam=\sevensl + \scriptfont\bffam=\sevenbf \scriptfont\ttfam=\seventt + \scriptfont\sffam=\sevensf } % @@ -2517,6 +2527,9 @@ end % to also set the current \fam for math mode. Our \STYLE (e.g., \rm) % commands hardwire \STYLEfont to set the current font. % +% The fonts used for \ifont are for "math italics" (\itfont is for italics +% in regular text). \syfont is also used in math mode only. +% % Each font-changing command also sets the names \lsize (one size lower) % and \lllsize (three sizes lower). These relative commands are used % in, e.g., the LaTeX logo and acronyms. @@ -2833,7 +2846,7 @@ end % @t, explicit typewriter. \def\t#1{% - {\tt \rawbackslash \plainfrenchspacing #1}% + {\tt \plainfrenchspacing #1}% \null } @@ -2860,7 +2873,6 @@ end % Turn off hyphenation. \nohyphenation % - \rawbackslash \plainfrenchspacing #1% }% @@ -3047,41 +3059,33 @@ end \global\def/{\normalslash} } -% we put a little stretch before and after the breakable chars, to help -% line breaking of long url's. The unequal skips make look better in -% cmtt at least, especially for dots. -\def\urefprestretchamount{.13em} -\def\urefpoststretchamount{.1em} -\def\urefprestretch{\urefprebreak \hskip0pt plus\urefprestretchamount\relax} -\def\urefpoststretch{\urefpostbreak \hskip0pt plus\urefprestretchamount\relax} -% -\def\urefcodeamp{\urefprestretch \&\urefpoststretch} -\def\urefcodedot{\urefprestretch .\urefpoststretch} -\def\urefcodehash{\urefprestretch \#\urefpoststretch} -\def\urefcodequest{\urefprestretch ?\urefpoststretch} +\def\urefcodeamp{\urefprebreak \&\urefpostbreak} +\def\urefcodedot{\urefprebreak .\urefpostbreak} +\def\urefcodehash{\urefprebreak \#\urefpostbreak} +\def\urefcodequest{\urefprebreak ?\urefpostbreak} \def\urefcodeslash{\futurelet\next\urefcodeslashfinish} { \catcode`\/=\active \global\def\urefcodeslashfinish{% - \urefprestretch \slashChar + \urefprebreak \slashChar % Allow line break only after the final / in a sequence of % slashes, to avoid line break between the slashes in http://. - \ifx\next/\else \urefpoststretch \fi + \ifx\next/\else \urefpostbreak \fi } } -% One more complication: by default we'll break after the special -% characters, but some people like to break before the special chars, so -% allow that. Also allow no breaking at all, for manual control. +% By default we'll break after the special characters, but some people like to +% break before the special chars, so allow that. Also allow no breaking at +% all, for manual control. % \parseargdef\urefbreakstyle{% \def\txiarg{#1}% \ifx\txiarg\wordnone \def\urefprebreak{\nobreak}\def\urefpostbreak{\nobreak} \else\ifx\txiarg\wordbefore - \def\urefprebreak{\allowbreak}\def\urefpostbreak{\nobreak} + \def\urefprebreak{\urefallowbreak}\def\urefpostbreak{\nobreak} \else\ifx\txiarg\wordafter - \def\urefprebreak{\nobreak}\def\urefpostbreak{\allowbreak} + \def\urefprebreak{\nobreak}\def\urefpostbreak{\urefallowbreak} \else \errhelp = \EMsimple \errmessage{Unknown @urefbreakstyle setting `\txiarg'}% @@ -3091,6 +3095,14 @@ end \def\wordbefore{before} \def\wordnone{none} +% Allow a ragged right output to aid breaking long URL's. Putting stretch in +% between characters of the URL doesn't look good. +\def\urefallowbreak{% + \hskip 0pt plus 4 em\relax + \allowbreak + \hskip 0pt plus -4 em\relax +} + \urefbreakstyle after % @url synonym for @uref, since that's how everyone uses it. @@ -3101,7 +3113,7 @@ end % So now @email is just like @uref, unless we are pdf. % %\def\email#1{\angleleft{\tt #1}\angleright} -\ifpdf +\ifpdforxetex \def\email#1{\doemail#1,,\finish} \def\doemail#1,#2,#3\finish{\begingroup \unsepspaces @@ -3111,18 +3123,7 @@ end \endlink \endgroup} \else - \ifx\XeTeXrevision\thisisundefined - \let\email=\uref - \else - \def\email#1{\doemail#1,,\finish} - \def\doemail#1,#2,#3\finish{\begingroup - \unsepspaces - \pdfurl{mailto:#1}% - \setbox0 = \hbox{\ignorespaces #2}% - \ifdim\wd0>0pt\unhbox0\else\code{#1}\fi - \endlink - \endgroup} - \fi + \let\email=\uref \fi % @kbdinputstyle -- arg is `distinct' (@kbd uses slanted tty font always), @@ -4656,19 +4657,6 @@ end } } -% We have this subroutine so that we can handle at least some @value's -% properly in indexes (we call \makevalueexpandable in \indexdummies). -% The command has to be fully expandable (if the variable is set), since -% the result winds up in the index file. This means that if the -% variable's value contains other Texinfo commands, it's almost certain -% it will fail (although perhaps we could fix that with sufficient work -% to do a one-level expansion on the result, instead of complete). -% -% Unfortunately, this has the consequence that when _ is in the *value* -% of an @set, it does not print properly in the roman fonts (get the cmr -% dot accent at position 126 instead). No fix comes to mind, and it's -% been this way since 2003 or earlier, so just ignore it. -% \def\expandablevalue#1{% \expandafter\ifx\csname SET#1\endcsname\relax {[No value for ``#1'']}% @@ -4697,7 +4685,7 @@ end % if possible, otherwise sort late. \def\indexnofontsvalue#1{% \expandafter\ifx\csname SET#1\endcsname\relax - ZZZZZZZ + ZZZZZZZ% \else \csname SET#1\endcsname \fi @@ -4847,23 +4835,8 @@ end \def\docodeindexxxx #1{\doind{\indexname}{\code{#1}}} -% Used when writing an index entry out to an index file to prevent -% expansion of Texinfo commands that can appear in an index entry. -% -\def\indexdummies{% - \escapechar = `\\ % use backslash in output files. - \definedummyletter\@% - \definedummyletter\ % - % - % For texindex which always views { and } as separators. - \def\{{\lbracechar{}}% - \def\}{\rbracechar{}}% - % - % Do the redefinitions. - \definedummies -} - -% Used for the aux and toc files, where @ is the escape character. +% Used for the aux, toc and index files to prevent expansion of Texinfo +% commands. % \def\atdummies{% \definedummyletter\@% @@ -4893,8 +4866,7 @@ end \def\definedummyletter#1{\def#1{\string#1}}% \let\definedummyaccent\definedummyletter -% Called from \indexdummies and \atdummies, to effectively prevent -% the expansion of commands. +% Called from \atdummies to prevent the expansion of commands. % \def\definedummies{% % @@ -4943,6 +4915,7 @@ end % Assorted special characters. \definedummyword\atchar \definedummyword\arrow + \definedummyword\backslashchar \definedummyword\bullet \definedummyword\comma \definedummyword\copyright @@ -4979,6 +4952,8 @@ end \definedummyword\sup \definedummyword\textdegree % + \definedummyword\subentry + % % We want to disable all macros so that they are not expanded by \write. \macrolist \let\value\dummyvalue @@ -5059,11 +5034,10 @@ end \commondummyword\xref } -% For testing: output @{ and @} in index sort strings as \{ and \}. -\newif\ifusebracesinindexes - \let\indexlbrace\relax \let\indexrbrace\relax +\let\indexatchar\relax +\let\indexbackslash\relax {\catcode`\@=0 \catcode`\\=13 @@ -5097,10 +5071,8 @@ end } \gdef\indexnonalnumreappear{% - \useindexbackslash \let-\normaldash \let<\normalless - \def\@{@}% } } @@ -5211,36 +5183,16 @@ end -\let\SETmarginindex=\relax % put index entries in margin (undocumented)? - -% Most index entries go through here, but \dosubind is the general case. % #1 is the index name, #2 is the entry text. -\def\doind#1#2{\dosubind{#1}{#2}{}} - -% There is also \dosubind {index}{topic}{subtopic} -% which makes an entry in a two-level index such as the operation index. -% TODO: Two-level index? Operation index? - -% Workhorse for all indexes. -% #1 is name of index, #2 is stuff to put there, #3 is subentry -- -% empty if called from \doind, as we usually are (the main exception -% is with most defuns, which call us directly). -% -\def\dosubind#1#2#3{% +\def\doind#1#2{% \iflinks {% - \requireopenindexfile{#1}% - % Store the main index entry text (including the third arg). - \toks0 = {#2}% - % If third arg is present, precede it with a space. - \def\thirdarg{#3}% - \ifx\thirdarg\empty \else - \toks0 = \expandafter{\the\toks0 \space #3}% - \fi % + \requireopenindexfile{#1}% \edef\writeto{\csname#1indfile\endcsname}% % - \safewhatsit\dosubindwrite + \def\indextext{#2}% + \safewhatsit\doindwrite }% \fi } @@ -5262,21 +5214,7 @@ end \fi} \def\indexisfl{fl} -% Output \ as {\indexbackslash}, because \ is an escape character in -% the index files. -\let\indexbackslash=\relax -{\catcode`\@=0 \catcode`\\=\active - @gdef@useindexbackslash{@def\{{@indexbackslash}}} -} - -% Definition for writing index entry text. -\def\sortas#1{\ignorespaces}% - -% Definition for writing index entry sort key. Should occur at the at -% the beginning of the index entry, like -% @cindex @sortas{september} \september -% The \ignorespaces takes care of following space, but there's no way -% to remove space before it. +% Definition for writing index entry sort key. { \catcode`\-=13 \gdef\indexwritesortas{% @@ -5287,51 +5225,150 @@ end \xdef\indexsortkey{#1}\endgroup} } +\def\indexwriteseealso#1{ + \gdef\pagenumbertext{\string\seealso{#1}}% +} +\def\indexwriteseeentry#1{ + \gdef\pagenumbertext{\string\seeentry{#1}}% +} + +% The default definitions +\def\sortas#1{}% +\def\seealso#1{\i{\putwordSeeAlso}\ #1}% for sorted index file only +\def\putwordSeeAlso{See also} +\def\seeentry#1{\i{\putwordSee}\ #1}% for sorted index file only + -% Write the entry in \toks0 to the index file. +% Given index entry text like "aaa @subentry bbb @sortas{ZZZ}": +% * Set \bracedtext to "{aaa}{bbb}" +% * Set \fullindexsortkey to "aaa @subentry ZZZ" +% * If @seealso occurs, set \pagenumbertext % -\def\dosubindwrite{% - % Put the index entry in the margin if desired. - \ifx\SETmarginindex\relax\else - \insert\margin{\hbox{\vrule height8pt depth3pt width0pt \the\toks0}}% +\def\splitindexentry#1{% + \gdef\fullindexsortkey{}% + \xdef\bracedtext{}% + \def\sep{}% + \def\seealso##1{}% + \def\seeentry##1{}% + \expandafter\doindexsegment#1\subentry\finish\subentry +} + +% append the results from the next segment +\def\doindexsegment#1\subentry{% + \def\segment{#1}% + \ifx\segment\isfinish + \else + % + % Fully expand the segment, throwing away any @sortas directives, and + % trim spaces. + \edef\trimmed{\segment}% + \edef\trimmed{\expandafter\eatspaces\expandafter{\trimmed}}% + % + \xdef\bracedtext{\bracedtext{\trimmed}}% + % + % Get the string to sort by. Process the segment with all + % font commands turned off. + \bgroup + \let\sortas\indexwritesortas + \let\seealso\indexwriteseealso + \let\seeentry\indexwriteseeentry + \indexnofonts + % The braces around the commands are recognized by texindex. + \def\lbracechar{{\string\indexlbrace}}% + \def\rbracechar{{\string\indexrbrace}}% + \let\{=\lbracechar + \let\}=\rbracechar + \def\@{{\string\indexatchar}}% + \def\atchar##1{\@}% + \def\backslashchar{{\string\indexbackslash}}% + \uccode`\~=`\\ \uppercase{\let~\backslashchar}% + % + \let\indexsortkey\empty + \global\let\pagenumbertext\empty + % Execute the segment and throw away the typeset output. This executes + % any @sortas or @seealso commands in this segment. + \setbox\dummybox = \hbox{\segment}% + \ifx\indexsortkey\empty{% + \indexnonalnumdisappear + \xdef\trimmed{\segment}% + \xdef\trimmed{\expandafter\eatspaces\expandafter{\trimmed}}% + \xdef\indexsortkey{\trimmed}% + \ifx\indexsortkey\empty\xdef\indexsortkey{ }\fi + }\fi + % + % Append to \fullindexsortkey. + \edef\tmp{\gdef\noexpand\fullindexsortkey{% + \fullindexsortkey\sep\indexsortkey}}% + \tmp + \egroup + \def\sep{\subentry}% + % + \expandafter\doindexsegment \fi +} +\def\isfinish{\finish}% +\newbox\dummybox % used above + +\let\subentry\relax + +% Use \ instead of @ in index files. To support old texi2dvi and texindex. +% This works without changing the escape character used in the toc or aux +% files because the index entries are fully expanded here, and \string uses +% the current value of \escapechar. +\def\escapeisbackslash{\escapechar=`\\} + +% Use \ in index files by default. texi2dvi didn't support @ as the escape +% character (as it checked for "\entry" in the files, and not "@entry"). When +% the new version of texi2dvi has had a chance to become more prevalent, then +% the escape character can change back to @ again. This should be an easy +% change to make now because both @ and \ are only used as escape characters in +% index files, never standing for themselves. +% +\set txiindexescapeisbackslash + +% Write the entry in \indextext to the index file. +% +\def\doindwrite{% + \maybemarginindex % - % Remember, we are within a group. - \indexdummies % Must do this here, since \bf, etc expand at this stage - \useindexbackslash % \indexbackslash isn't defined now so it will be output - % as is; and it will print as backslash. - % The braces around \indexbrace are recognized by texindex. - % - % Get the string to sort by, by processing the index entry with all - % font commands turned off. - {\indexnofonts - \def\lbracechar{{\indexlbrace}}% - \def\rbracechar{{\indexrbrace}}% - \let\{=\lbracechar - \let\}=\rbracechar - \indexnonalnumdisappear - \xdef\indexsortkey{}% - \let\sortas=\indexwritesortas - \edef\temp{\the\toks0}% - \setbox\dummybox = \hbox{\temp}% Make sure to execute any \sortas - \ifx\indexsortkey\empty - \xdef\indexsortkey{\temp}% - \ifx\indexsortkey\empty\xdef\indexsortkey{ }\fi - \fi - }% + \atdummies + % + \expandafter\ifx\csname SETtxiindexescapeisbackslash\endcsname\relax\else + \escapeisbackslash + \fi + % + % For texindex which always views { and } as separators. + \def\{{\lbracechar{}}% + \def\}{\rbracechar{}}% + \uccode`\~=`\\ \uppercase{\def~{\backslashchar{}}}% + % + % Split the entry into primary entry and any subentries, and get the index + % sort key. + \splitindexentry\indextext % % Set up the complete index entry, with both the sort key and % the original text, including any font commands. We write % three arguments to \entry to the .?? file (four in the % subentry case), texindex reduces to two when writing the .??s % sorted result. + % \edef\temp{% \write\writeto{% - \string\entry{\indexsortkey}{\noexpand\folio}{\the\toks0}}% + \string\entry{\fullindexsortkey}% + {\ifx\pagenumbertext\empty\noexpand\folio\else\pagenumbertext\fi}% + \bracedtext}% }% \temp } -\newbox\dummybox % used above + +% Put the index entry in the margin if desired (undocumented). +\def\maybemarginindex{% + \ifx\SETmarginindex\relax\else + \insert\margin{\hbox{\vrule height8pt depth3pt width0pt \relax\indextext}}% + \fi +} +\let\SETmarginindex=\relax + % Take care of unwanted page breaks/skips around a whatsit: % @@ -5419,9 +5456,14 @@ end % \entry {topic}{pagelist} % for a topic that is used without subtopics % \primary {topic} +% \entry {topic}{} % for the beginning of a topic that is used with subtopics % \secondary {subtopic}{pagelist} % for each subtopic. +% \secondary {subtopic}{} +% for a subtopic with sub-subtopics +% \tertiary {subtopic}{subsubtopic}{pagelist} +% for each sub-subtopic. % Define the user-accessible indexing commands % @findex, @vindex, @kindex, @cindex. @@ -5433,11 +5475,6 @@ end \def\tindex {\tpindex} \def\pindex {\pgindex} -\def\cindexsub {\begingroup\obeylines\cindexsub} -{\obeylines % -\gdef\cindexsub "#1" #2^^M{\endgroup % -\dosubind{cp}{#2}{#1}}} - % Define the macros used in formatting output of the sorted index material. % @printindex causes a particular index (the ??s file) to get printed. @@ -5451,14 +5488,10 @@ end \plainfrenchspacing \everypar = {}% don't want the \kern\-parindent from indentation suppression. % - % See if the index file exists and is nonempty. - % Change catcode of @ here so that if the index file contains - % \initial {@} - % as its first line, TeX doesn't complain about mismatched braces - % (because it thinks @} is a control sequence). - \catcode`\@ = 12 % See comment in \requireopenindexfile. \def\indexname{#1}\ifx\indexname\indexisfl\def\indexname{f1}\fi + % + % See if the index file exists and is nonempty. \openin 1 \jobname.\indexname s \ifeof 1 % \enddoublecolumns gets confused if there is no text in the index, @@ -5468,8 +5501,6 @@ end \putwordIndexNonexistent \typeout{No file \jobname.\indexname s.}% \else - \catcode`\\ = 0 - % % If the index file exists but is empty, then \openin leaves \ifeof % false. We have to make TeX try to read something from the file, so % it can discover if there is anything in it. @@ -5477,47 +5508,51 @@ end \ifeof 1 \putwordIndexIsEmpty \else - % Index files are almost Texinfo source, but we use \ as the escape - % character. It would be better to use @, but that's too big a change - % to make right now. - \def\indexbackslash{\ttbackslash}% - \let\indexlbrace\{ % Likewise, set these sequences for braces - \let\indexrbrace\} % used in the sort key. - \begindoublecolumns - \let\dotheinsertentrybox\dotheinsertentryboxwithpenalty - % - % Read input from the index file line by line. - \loopdo - \ifeof1 \else - \read 1 to \nextline - \fi - % - \indexinputprocessing - \thisline - % - \ifeof1\else - \let\thisline\nextline - \repeat - %% - \enddoublecolumns + \expandafter\printindexzz\thisline\relax\relax\finish% \fi \fi \closein 1 \endgroup} -\def\loopdo#1\repeat{\def\body{#1}\loopdoxxx} -\def\loopdoxxx{\let\next=\relax\body\let\next=\loopdoxxx\fi\next} -\def\indexinputprocessing{% - \ifeof1 - \let\firsttoken\relax +% If the index file starts with a backslash, forgo reading the index +% file altogether. If somebody upgrades texinfo.tex they may still have +% old index files using \ as the escape character. Reading this would +% at best lead to typesetting garbage, at worst a TeX syntax error. +\def\printindexzz#1#2\finish{% + \expandafter\ifx\csname SETtxiindexescapeisbackslash\endcsname\relax + \uccode`\~=`\\ \uppercase{\if\noexpand~}\noexpand#1 + \expandafter\ifx\csname SETtxiskipindexfileswithbackslash\endcsname\relax +\errmessage{% +ERROR: A sorted index file in an obsolete format was skipped. +To fix this problem, please upgrade your version of 'texi2dvi' +or 'texi2pdf' to that at <https://ftp.gnu.org/gnu/texinfo>. +If you are using an old version of 'texindex' (part of the Texinfo +distribution), you may also need to upgrade to a newer version (at least 6.0). +You may be able to typeset the index if you run +'texindex \jobname.\indexname' yourself. +You could also try setting the 'txiindexescapeisbackslash' flag by +running a command like +'texi2dvi -t "@set txiindexescapeisbackslash" \jobname.texi'. If you do +this, Texinfo will try to use index files in the old format. +If you continue to have problems, deleting the index files and starting again +might help (with 'rm \jobname.?? \jobname.??s')% +}% + \else + (Skipped sorted index file in obsolete format) + \fi + \else + \begindoublecolumns + \input \jobname.\indexname s + \enddoublecolumns + \fi \else - \edef\act{\gdef\noexpand\firsttoken{\getfirsttoken\nextline}}% - \act + \begindoublecolumns + \catcode`\\=0\relax + \catcode`\@=12\relax + \input \jobname.\indexname s + \enddoublecolumns \fi } -\def\getfirsttoken#1{\expandafter\getfirsttokenx#1\endfirsttoken} -\long\def\getfirsttokenx#1#2\endfirsttoken{\noexpand#1} - % These macros are used by the sorted index file itself. % Change them to control the appearance of the index. @@ -5526,12 +5561,19 @@ end \catcode`\|=13 \catcode`\<=13 \catcode`\>=13 \catcode`\+=13 \catcode`\"=13 \catcode`\$=3 \gdef\initialglyphs{% + % special control sequences used in the index sort key + \let\indexlbrace\{% + \let\indexrbrace\}% + \let\indexatchar\@% + \def\indexbackslash{\math{\backslash}}% + % % Some changes for non-alphabetic characters. Using the glyphs from the % math fonts looks more consistent than the typewriter font used elsewhere % for these characters. - \def\indexbackslash{\math{\backslash}}% - \let\\=\indexbackslash + \uccode`\~=`\\ \uppercase{\def~{\math{\backslash}}} % + % In case @\ is used for backslash + \uppercase{\let\\=~} % Can't get bold backslash so don't use bold forward slash \catcode`\/=13 \def/{{\secrmnotbold \normalslash}}% @@ -5591,12 +5633,6 @@ end \def\entry{% \begingroup % - % For pdfTeX and XeTeX. - % The redefinition of \domark stops marks being added in \pdflink to - % preserve coloured links across page boundaries. Otherwise the marks - % would get in the way of \lastbox in \insertentrybox. - \let\domark\relax - % % Start a new paragraph if necessary, so our assignments below can't % affect previous text. \par @@ -5629,35 +5665,31 @@ end \gdef\finishentry#1{% \egroup % end box A \dimen@ = \wd\boxA % Length of text of entry - \global\setbox\boxA=\hbox\bgroup\unhbox\boxA - % #1 is the page number. - % - % Get the width of the page numbers, and only use - % leaders if they are present. - \global\setbox\boxB = \hbox{#1}% - \ifdim\wd\boxB = 0pt - \null\nobreak\hfill\ % - \else - % - \null\nobreak\indexdotfill % Have leaders before the page number. + \global\setbox\boxA=\hbox\bgroup + \unhbox\boxA + % #1 is the page number. % - \ifpdf - \pdfgettoks#1.% - \hskip\skip\thinshrinkable\the\toksA + % Get the width of the page numbers, and only use + % leaders if they are present. + \global\setbox\boxB = \hbox{#1}% + \ifdim\wd\boxB = 0pt + \null\nobreak\hfill\ % \else - \ifx\XeTeXrevision\thisisundefined - \hskip\skip\thinshrinkable #1% - \else + % + \null\nobreak\indexdotfill % Have leaders before the page number. + % + \ifpdforxetex \pdfgettoks#1.% \hskip\skip\thinshrinkable\the\toksA + \else + \hskip\skip\thinshrinkable #1% \fi \fi - \fi \egroup % end \boxA \ifdim\wd\boxB = 0pt - \global\setbox\entrybox=\vbox{\unhbox\boxA}% - \else - \global\setbox\entrybox=\vbox\bgroup + \noindent\unhbox\boxA\par + \nobreak + \else\bgroup % We want the text of the entries to be aligned to the left, and the % page numbers to be aligned to the right. % @@ -5723,55 +5755,11 @@ end \egroup % The \vbox \fi \endgroup - \dotheinsertentrybox }} \newskip\thinshrinkable \skip\thinshrinkable=.15em minus .15em -\newbox\entrybox -\def\insertentrybox{% - \ourunvbox\entrybox -} - -% default definition -\let\dotheinsertentrybox\insertentrybox - -% Use \lastbox to take apart vbox box by box, and add each sub-box -% to the current vertical list. -\def\ourunvbox#1{% -\bgroup % for local binding of \delayedbox - % Remove the last box from box #1 - \global\setbox#1=\vbox{% - \unvbox#1% - \unskip % remove any glue - \unpenalty - \global\setbox\interbox=\lastbox - }% - \setbox\delayedbox=\box\interbox - \ifdim\ht#1=0pt\else - \ourunvbox#1 % Repeat on what's left of the box - \nobreak - \fi - \box\delayedbox -\egroup -} -\newbox\delayedbox -\newbox\interbox - -% Used from \printindex. \firsttoken should be the first token -% after the \entry. If it's not another \entry, we are at the last -% line of a group of index entries, so insert a penalty to discourage -% widowed index entries. -\def\dotheinsertentryboxwithpenalty{% - \ifx\firsttoken\isentry - \else - \penalty 9000 - \fi - \insertentrybox -} -\def\isentry{\entry}% - % Like plain.tex's \dotfill, except uses up at least 1 em. % The filll stretch here overpowers both the fil and fill stretch to push % the page number to the right. @@ -5781,24 +5769,15 @@ end \def\primary #1{\line{#1\hfil}} -\newskip\secondaryindent \secondaryindent=0.5cm -\def\secondary#1#2{{% - \parfillskip=0in - \parskip=0in - \hangindent=1in - \hangafter=1 - \noindent\hskip\secondaryindent\hbox{#1}\indexdotfill - \ifpdf - \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph. - \else - \ifx\XeTeXrevision\thisisundefined - #2 - \else - \pdfgettoks#2.\ \the\toksA % The page number ends the paragraph. - \fi - \fi - \par -}} +\def\secondary{\indententry{0.5cm}} +\def\tertiary{\indententry{1cm}} + +\def\indententry#1#2#3{% + \bgroup + \leftskip=#1 + \entry{#2}{#3}% + \egroup +} % Define two-column mode, which we use to typeset indexes. % Adapted from the TeXbook, page 416, which is to say, @@ -5808,60 +5787,21 @@ end \newbox\partialpage \newdimen\doublecolumnhsize -% Use inside an output routine to save \topmark and \firstmark -\def\savemarks{% - \global\savedtopmark=\expandafter{\topmark }% - \global\savedfirstmark=\expandafter{\firstmark }% -} -\newtoks\savedtopmark -\newtoks\savedfirstmark - -% Set \topmark and \firstmark for next time \output runs. -% Can't be run from withinside \output (because any material -% added while an output routine is active, including -% penalties, is saved for after it finishes). The page so far -% should be empty, otherwise what's on it will be thrown away. -\def\restoremarks{% - \mark{\the\savedtopmark}% - \bgroup\output = {% - \setbox\dummybox=\box\PAGE - }abc\eject\egroup - % "abc" because output routine doesn't fire for a completely empty page. - \mark{\the\savedfirstmark}% -} - \def\begindoublecolumns{\begingroup % ended by \enddoublecolumns % If not much space left on page, start a new page. \ifdim\pagetotal>0.8\vsize\vfill\eject\fi % % Grab any single-column material above us. \output = {% - % - % Here is a possibility not foreseen in manmac: if we accumulate a - % whole lot of material, we might end up calling this \output - % routine twice in a row (see the doublecol-lose test, which is - % essentially a couple of indexes with @setchapternewpage off). In - % that case we just ship out what is in \partialpage with the normal - % output routine. Generally, \partialpage will be empty when this - % runs and this will be a no-op. See the indexspread.tex test case. - \ifvoid\partialpage \else - \onepageout{\pagecontents\partialpage}% - \fi + \savetopmark % \global\setbox\partialpage = \vbox{% % Unvbox the main output page. \unvbox\PAGE \kern-\topskip \kern\baselineskip }% - \savemarks }% \eject % run that output routine to set \partialpage - \restoremarks - % - % We recover the two marks that the last output routine saved in order - % to propagate the information in marks added around a chapter heading, - % which could be otherwise be lost by the time the final page is output. - % % % Use the double-column output routine for subsequent pages. \output = {\doublecolumnout}% @@ -5887,7 +5827,9 @@ end \divide\doublecolumnhsize by 2 \hsize = \doublecolumnhsize % - % Double the \vsize as well. + % Get the available space for the double columns -- the normal + % (undoubled) page height minus any material left over from the + % previous page. \advance\vsize by -\ht\partialpage \vsize = 2\vsize % @@ -5900,17 +5842,15 @@ end % \def\doublecolumnout{% % + \savetopmark \splittopskip=\topskip \splitmaxdepth=\maxdepth - % Get the available space for the double columns -- the normal - % (undoubled) page height minus any material left over from the - % previous page. \dimen@ = \vsize \divide\dimen@ by 2 % % box0 will be the left-hand column, box2 the right. \setbox0=\vsplit\PAGE to\dimen@ \setbox2=\vsplit\PAGE to\dimen@ \global\advance\vsize by 2\ht\partialpage - \onepageout\pagesofar + \onepageout\pagesofar % empty except for the first time we are called \unvbox\PAGE \penalty\outputpenalty } @@ -5926,7 +5866,7 @@ end } -% Finished with with double columns. +% Finished with double columns. \def\enddoublecolumns{% % The following penalty ensures that the page builder is exercised % _before_ we change the output routine. This is necessary in the @@ -5958,7 +5898,7 @@ end % \output = {% % Split the last of the double-column material. - \savemarks + \savetopmark \balancecolumns }% \eject % call the \output just set @@ -5966,10 +5906,9 @@ end % Having called \balancecolumns once, we do not % want to call it again. Therefore, reset \output to its normal % definition right away. - \global\output = {\onepageout{\pagecontents\PAGE}}% + \global\output=\expandafter{\the\defaultoutput} % \endgroup % started in \begindoublecolumns - \restoremarks % Leave the double-column material on the current page, no automatic % page break. \box\balancedcolumns @@ -5993,13 +5932,14 @@ end \def\balancecolumns{% \setbox0 = \vbox{\unvbox\PAGE}% like \box255 but more efficient, see p.120. \dimen@ = \ht0 - \advance\dimen@ by \topskip - \advance\dimen@ by-\baselineskip - \ifdim\dimen@<5\baselineskip + \ifdim\dimen@<7\baselineskip % Don't split a short final column in two. \setbox2=\vbox{}% \global\setbox\balancedcolumns=\vbox{\pagesofar}% \else + % double the leading vertical space + \advance\dimen@ by \topskip + \advance\dimen@ by-\baselineskip \divide\dimen@ by 2 % target to split to \dimen@ii = \dimen@ \splittopskip = \topskip @@ -6134,11 +6074,9 @@ end % @raisesections: treat @section as chapter, @subsection as section, etc. \def\raisesections{\global\advance\secbase by -1} -\let\up=\raisesections % original BFox name % @lowersections: treat @chapter as section, @section as subsection, etc. \def\lowersections{\global\advance\secbase by 1} -\let\down=\lowersections % original BFox name % we only have subsub. \chardef\maxseclevel = 3 @@ -6483,27 +6421,22 @@ end \expandafter\ifx\thisenv\titlepage\else \checkenv{}% chapters, etc., should not start inside an environment. \fi - % FIXME: \chapmacro is currently called from inside \titlepage when - % \setcontentsaftertitlepage to print the "Table of Contents" heading, but - % this should probably be done by \sectionheading with an option to print - % in chapter size. - % % Insert the first mark before the heading break (see notes for \domark). - \let\prevchapterdefs=\lastchapterdefs - \let\prevsectiondefs=\lastsectiondefs - \gdef\lastsectiondefs{\gdef\thissectionname{}\gdef\thissectionnum{}% + \let\prevchapterdefs=\currentchapterdefs + \let\prevsectiondefs=\currentsectiondefs + \gdef\currentsectiondefs{\gdef\thissectionname{}\gdef\thissectionnum{}% \gdef\thissection{}}% % \def\temptype{#2}% \ifx\temptype\Ynothingkeyword - \gdef\lastchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}% + \gdef\currentchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}% \gdef\thischapter{\thischaptername}}% \else\ifx\temptype\Yomitfromtockeyword - \gdef\lastchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}% + \gdef\currentchapterdefs{\gdef\thischaptername{#1}\gdef\thischapternum{}% \gdef\thischapter{}}% \else\ifx\temptype\Yappendixkeyword \toks0={#1}% - \xdef\lastchapterdefs{% + \xdef\currentchapterdefs{% \gdef\noexpand\thischaptername{\the\toks0}% \gdef\noexpand\thischapternum{\appendixletter}% % \noexpand\putwordAppendix avoids expanding indigestible @@ -6514,7 +6447,7 @@ end }% \else \toks0={#1}% - \xdef\lastchapterdefs{% + \xdef\currentchapterdefs{% \gdef\noexpand\thischaptername{\the\toks0}% \gdef\noexpand\thischapternum{\the\chapno}% % \noexpand\putwordChapter avoids expanding indigestible @@ -6534,18 +6467,18 @@ end % % Now the second mark, after the heading break. No break points % between here and the heading. - \let\prevchapterdefs=\lastchapterdefs - \let\prevsectiondefs=\lastsectiondefs + \let\prevchapterdefs=\currentchapterdefs + \let\prevsectiondefs=\currentsectiondefs \domark % {% \chapfonts \rm \let\footnote=\errfootnoteheading % give better error message % - % Have to define \lastsection before calling \donoderef, because the + % Have to define \currentsection before calling \donoderef, because the % xref code eventually uses it. On the other hand, it has to be called % after \pchapsepmacro, or the headline will change too soon. - \gdef\lastsection{#1}% + \gdef\currentsection{#1}% % % Only insert the separating space if we have a chapter/appendix % number, and don't print the unnumbered ``number''. @@ -6634,10 +6567,10 @@ end \csname #2fonts\endcsname \rm % % Insert first mark before the heading break (see notes for \domark). - \let\prevsectiondefs=\lastsectiondefs + \let\prevsectiondefs=\currentsectiondefs \ifx\temptype\Ynothingkeyword \ifx\sectionlevel\seckeyword - \gdef\lastsectiondefs{\gdef\thissectionname{#1}\gdef\thissectionnum{}% + \gdef\currentsectiondefs{\gdef\thissectionname{#1}\gdef\thissectionnum{}% \gdef\thissection{\thissectionname}}% \fi \else\ifx\temptype\Yomitfromtockeyword @@ -6645,7 +6578,7 @@ end \else\ifx\temptype\Yappendixkeyword \ifx\sectionlevel\seckeyword \toks0={#1}% - \xdef\lastsectiondefs{% + \xdef\currentsectiondefs{% \gdef\noexpand\thissectionname{\the\toks0}% \gdef\noexpand\thissectionnum{#4}% % \noexpand\putwordSection avoids expanding indigestible @@ -6658,7 +6591,7 @@ end \else \ifx\sectionlevel\seckeyword \toks0={#1}% - \xdef\lastsectiondefs{% + \xdef\currentsectiondefs{% \gdef\noexpand\thissectionname{\the\toks0}% \gdef\noexpand\thissectionnum{#4}% % \noexpand\putwordSection avoids expanding indigestible @@ -6684,28 +6617,28 @@ end % % Now the second mark, after the heading break. No break points % between here and the heading. - \global\let\prevsectiondefs=\lastsectiondefs + \global\let\prevsectiondefs=\currentsectiondefs \domark % % Only insert the space after the number if we have a section number. \ifx\temptype\Ynothingkeyword \setbox0 = \hbox{}% \def\toctype{unn}% - \gdef\lastsection{#1}% + \gdef\currentsection{#1}% \else\ifx\temptype\Yomitfromtockeyword % for @headings -- no section number, don't include in toc, - % and don't redefine \lastsection. + % and don't redefine \currentsection. \setbox0 = \hbox{}% \def\toctype{omit}% \let\sectionlevel=\empty \else\ifx\temptype\Yappendixkeyword \setbox0 = \hbox{#4\enspace}% \def\toctype{app}% - \gdef\lastsection{#1}% + \gdef\currentsection{#1}% \else \setbox0 = \hbox{#4\enspace}% \def\toctype{num}% - \gdef\lastsection{#1}% + \gdef\currentsection{#1}% \fi\fi\fi % % Write the toc entry (before \donoderef). See comments in \chapmacro. @@ -6795,13 +6728,8 @@ end % 1 and 2 (the page numbers aren't printed), and so are the first % two pages of the document. Thus, we'd have two destinations named % `1', and two named `2'. - \ifpdf + \ifpdforxetex \global\pdfmakepagedesttrue - \else - \ifx\XeTeXrevision\thisisundefined - \else - \global\pdfmakepagedesttrue - \fi \fi } @@ -7164,11 +7092,7 @@ end % @cartouche ... @end cartouche: draw rectangle w/rounded corners around % environment contents. -\font\circle=lcircle10 -\newdimen\circthick -\newdimen\cartouter\newdimen\cartinner -\newskip\normbskip\newskip\normpskip\newskip\normlskip -\circthick=\fontdimen8\circle + % \def\ctl{{\circle\char'013\hskip -6pt}}% 6pt from pl file: 1/2charwidth \def\ctr{{\hskip 6pt\circle\char'010}} @@ -7183,7 +7107,18 @@ end % \newskip\lskip\newskip\rskip +% only require the font if @cartouche is actually used +\def\cartouchefontdefs{% + \font\circle=lcircle10\relax + \circthick=\fontdimen8\circle +} +\newdimen\circthick +\newdimen\cartouter\newdimen\cartinner +\newskip\normbskip\newskip\normpskip\newskip\normlskip + + \envdef\cartouche{% + \cartouchefontdefs \ifhmode\par\fi % can't be in the midst of a paragraph. \startsavinginserts \lskip=\leftskip \rskip=\rightskip @@ -7362,13 +7297,9 @@ end % @raggedright does more-or-less normal line breaking but no right -% justification. From plain.tex. Don't stretch around special -% characters in urls in this environment, since the stretch at the right -% should be enough. +% justification. From plain.tex. \envdef\raggedright{% \rightskip0pt plus2.4em \spaceskip.3333em \xspaceskip.5em\relax - \def\urefprestretchamount{0pt}% - \def\urefpoststretchamount{0pt}% } \let\Eraggedright\par @@ -7530,7 +7461,7 @@ end \nonfillstart \tt % easiest (and conventionally used) font for verbatim % The \leavevmode here is for blank lines. Otherwise, we would - % never \starttabox and the \egroup would end verbatim mode. + % never \starttabbox and the \egroup would end verbatim mode. \def\par{\leavevmode\egroup\box\verbbox\endgraf}% \tabexpand \setupmarkupstyle{verbatim}% @@ -7593,9 +7524,12 @@ end {% \makevalueexpandable \setupverbatim - \indexnofonts % Allow `@@' and other weird things in file names. - \wlog{texinfo.tex: doing @verbatiminclude of #1^^J}% - \input #1 + {% + \indexnofonts % Allow `@@' and other weird things in file names. + \wlog{texinfo.tex: doing @verbatiminclude of #1^^J}% + \edef\tmp{\noexpand\input #1 } + \expandafter + }\tmp \afterenvbreak }% } @@ -7740,6 +7674,21 @@ end \fi\fi } +% \dosubind {index}{topic}{subtopic} +% +% If SUBTOPIC is present, precede it with a space, and call \doind. +% (At some time during the 20th century, this made a two-level entry in an +% index such as the operation index. Nobody seemed to notice the change in +% behaviour though.) +\def\dosubind#1#2#3{% + \def\thirdarg{#3}% + \ifx\thirdarg\empty + \doind{#1}{#2}% + \else + \doind{#1}{#2\space#3}% + \fi +} + % Untyped functions: % @deffn category name args @@ -7754,7 +7703,6 @@ end % \deffngeneral {subind}category name args % \def\deffngeneral#1#2 #3 #4\endheader{% - % Remember that \dosubind{fn}{foo}{} is equivalent to \doind{fn}{foo}. \dosubind{fn}{\code{#3}}{#1}% \defname{#2}{}{#3}\magicamp\defunargs{#4\unskip}% } @@ -7961,6 +7909,7 @@ end \gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} \gdef\magicamp{\let&=\amprm} } +\let\ampchar\& \newcount\parencount @@ -8041,36 +7990,18 @@ end } \fi -% alias because \c means cedilla in @tex or @math -\let\texinfoc=\c - -\newcount\savedcatcodeone -\newcount\savedcatcodetwo - % Used at the time of macro expansion. % Argument is macro body with arguments substituted \def\scanmacro#1{% \newlinechar`\^^M \def\xeatspaces{\eatspaces}% % - % Temporarily undo catcode changes of \printindex. Set catcode of @ to - % 0 so that @-commands in macro expansions aren't printed literally when - % formatting an index file, where \ is used as the escape character. - \savedcatcodeone=\catcode`\@ - \savedcatcodetwo=\catcode`\\ - \catcode`\@=0 - \catcode`\\=\active - % % Process the macro body under the current catcode regime. - \scantokens{#1@texinfoc}% - % - \catcode`\@=\savedcatcodeone - \catcode`\\=\savedcatcodetwo + \scantokens{#1@comment}% % - % The \texinfoc is to remove the \newlinechar added by \scantokens, and - % can be noticed by \parsearg. - % We avoid surrounding the call to \scantokens with \bgroup and \egroup - % to allow macros to open or close groups themselves. + % The \comment is to remove the \newlinechar added by \scantokens, and + % can be noticed by \parsearg. Note \c isn't used because this means cedilla + % in math mode. } % Used for copying and captions @@ -8171,12 +8102,14 @@ end \def\macroargctxt{% \scanctxt \catcode`\ =\active + \catcode`\@=\other \catcode`\^^M=\other \catcode`\\=\active } \def\macrolineargctxt{% used for whole-line arguments without braces \scanctxt + \catcode`\@=\other \catcode`\{=\other \catcode`\}=\other } @@ -8740,9 +8673,29 @@ end % also remove a trailing comma, in case of something like this: % @node Help-Cross, , , Cross-refs \def\donode#1 ,#2\finishnodeparse{\dodonode #1,\finishnodeparse} -\def\dodonode#1,#2\finishnodeparse{\gdef\lastnode{#1}} +\def\dodonode#1,#2\finishnodeparse{\gdef\lastnode{#1}\omittopnode} + +% Used so that the @top node doesn't have to be wrapped in an @ifnottex +% conditional. +% \doignore goes to more effort to skip nested conditionals but we don't need +% that here. +\def\omittopnode{% + \ifx\lastnode\wordTop + \expandafter\ignorenode\fi +} +\def\wordTop{Top} + +% Until the next @node or @bye command, divert output to a box that is not +% output. +\def\ignorenode{\setbox\dummybox\vbox\bgroup\def\node{\egroup\node}% +\ignorenodebye +} + +{\let\bye\relax +\gdef\ignorenodebye{\let\bye\ignorenodebyedef} +\gdef\ignorenodebyedef{\egroup(`Top' node ignored)\bye}} +% The redefinition of \bye here is because it is declared \outer -\let\nwnode=\node \let\lastnode=\empty % Write a cross-reference definition for the current node. #1 is the @@ -8765,7 +8718,7 @@ end % \setref{NAME}{SNT} defines a cross-reference point NAME (a node or an % anchor), which consists of three parts: -% 1) NAME-title - the current sectioning name taken from \lastsection, +% 1) NAME-title - the current sectioning name taken from \currentsection, % or the anchor name. % 2) NAME-snt - section number and type, passed as the SNT arg, or % empty for anchors. @@ -8787,7 +8740,7 @@ end \write\auxfile{@xrdef{#1-% #1 of \setref, expanded by the \edef ##1}{##2}}% these are parameters of \writexrdef }% - \toks0 = \expandafter{\lastsection}% + \toks0 = \expandafter{\currentsection}% \immediate \writexrdef{title}{\the\toks0 }% \immediate \writexrdef{snt}{\csname #2\endcsname}% \Ynumbered etc. \safewhatsit{\writexrdef{pg}{\folio}}% will be written later, at \shipout @@ -9217,19 +9170,6 @@ end \catcode`\^^]=\other \catcode`\^^^=\other \catcode`\^^_=\other - % It was suggested to set the catcode of ^ to 7, which would allow ^^e4 etc. - % in xref tags, i.e., node names. But since ^^e4 notation isn't - % supported in the main text, it doesn't seem desirable. Furthermore, - % that is not enough: for node names that actually contain a ^ - % character, we would end up writing a line like this: 'xrdef {'hat - % b-title}{'hat b} and \xrdef does a \csname...\endcsname on the first - % argument, and \hat is not an expandable control sequence. It could - % all be worked out, but why? Either we support ^^ or we don't. - % - % The other change necessary for this was to define \auxhat: - % \def\auxhat{\def^{'hat }}% extra space so ok if followed by letter - % and then to call \auxhat in \setq. - % \catcode`\^=\other % % Special characters. Should be turned off anyway, but... @@ -9247,14 +9187,7 @@ end \catcode`\%=\other \catcode`+=\other % avoid \+ for paranoia even though we've turned it off % - % This is to support \ in node names and titles, since the \ - % characters end up in a \csname. It's easier than - % leaving it active and making its active definition an actual \ - % character. What I don't understand is why it works in the *value* - % of the xrdef. Seems like it should be a catcode12 \, and that - % should not typeset properly. But it works, so I'm moving on for - % now. --karl, 15jan04. - \catcode`\\=\other + \catcode`\\=\active % % @ is our escape character in .aux files, and we need braces. \catcode`\{=1 @@ -9585,13 +9518,13 @@ end \global\advance\floatno by 1 % {% - % This magic value for \lastsection is output by \setref as the + % This magic value for \currentsection is output by \setref as the % XREFLABEL-title value. \xrefX uses it to distinguish float % labels (which have a completely different output format) from % node and anchor labels. And \xrdef uses it to construct the % lists of floats. % - \edef\lastsection{\floatmagic=\safefloattype}% + \edef\currentsection{\floatmagic=\safefloattype}% \setref{\floatlabel}{Yfloat}% }% \fi @@ -9714,7 +9647,7 @@ end % #1 is the control sequence we are passed; we expand into a conditional % which is true if #1 represents a float ref. That is, the magic -% \lastsection value which we \setref above. +% \currentsection value which we \setref above. % \def\iffloat#1{\expandafter\doiffloat#1==\finish} % @@ -11202,21 +11135,14 @@ directory should work if nowhere else does.} \relax } -% define all Unicode characters we know about, for the sake of @U. +% Define all Unicode characters we know about. This makes UTF-8 the default +% input encoding and allows @U to work. \iftxinativeunicodecapable \nativeunicodechardefsatu \else \utfeightchardefs \fi - -% Make non-ASCII characters printable again for compatibility with -% existing Texinfo documents that may use them, even without declaring a -% document encoding. -% -\setnonasciicharscatcode \other - - \message{formatting,} \newdimen\defaultparindent \defaultparindent = 15pt @@ -11532,11 +11458,9 @@ directory should work if nowhere else does.} % \backslashcurfont outputs one backslash character in current font, % as in \char`\\. \global\chardef\backslashcurfont=`\\ -\global\let\rawbackslashxx=\backslashcurfont % let existing .??s files work -% \realbackslash is an actual character `\' with catcode other, and -% \doublebackslash is two of them (for the pdf outlines). -{\catcode`\\=\other @gdef@realbackslash{\} @gdef@doublebackslash{\\}} +% \realbackslash is an actual character `\' with catcode other. +{\catcode`\\=\other @gdef@realbackslash{\}} % In Texinfo, backslash is an active character; it prints the backslash % in fixed width font. @@ -11554,10 +11478,8 @@ directory should work if nowhere else does.} @def@ttbackslash{{@tt @ifmmode @mathchar29020 @else @backslashcurfont @fi}} @let@backslashchar = @ttbackslash % @backslashchar{} is for user documents. -% \rawbackslash defines an active \ to do \backslashcurfont. % \otherbackslash defines an active \ to be a literal `\' character with -% catcode other. We switch back and forth between these. -@gdef@rawbackslash{@let\=@backslashcurfont} +% catcode other. @gdef@otherbackslash{@let\=@realbackslash} % Same as @turnoffactive except outputs \ as {\tt\char`\\} instead of @@ -11629,7 +11551,7 @@ directory should work if nowhere else does.} @ifx\@eatinput @let\ = @ttbackslash @fi @catcode13=5 % regular end of line @enableemergencynewline - @let@c=@texinfoc + @let@c=@comment @let@parsearg@originalparsearg % Also turn back on active characters that might appear in the input % file name, in case not using a pre-dumped format. @@ -11675,7 +11597,7 @@ directory should work if nowhere else does.} @markupsetuprqdefault @c Local variables: -@c eval: (add-hook 'write-file-hooks 'time-stamp) +@c eval: (add-hook 'before-save-hook 'time-stamp) @c page-delimiter: "^\\\\message\\|emacs-page" @c time-stamp-start: "def\\\\texinfoversion{" @c time-stamp-format: "%:y-%02m-%02d.%02H" diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 633f2d16b6b..dc01f119e7a 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -2,9 +2,8 @@ @setfilename ../../info/tramp.info @c %**start of header @include docstyle.texi -@c In the Tramp repository, the version number is auto-frobbed from -@c configure.ac, so you should edit that file and run -@c "autoconf && ./configure" to change the version number. +@c In the Tramp GIT, the version number is auto-frobbed from tramp.el, +@c and the bug report address is auto-frobbed from configure.ac. @include trampver.texi @settitle @value{tramp} @value{trampver} User Manual @c %**end of header @@ -12,16 +11,6 @@ @c This is *so* much nicer :) @footnotestyle end -@c Macro for formatting a file name according to the respective -@c syntax. Macro arguments should not have any leading or trailing -@c whitespace. Not very elegant, but I don't know it better. - -@macro trampfn {method, userhost, localname} -@value{prefix}@c -\method\@value{postfixhop}@c -\userhost\@value{postfix}\localname\ -@end macro - @copying Copyright @copyright{} 1999--2019 Free Software Foundation, Inc. @@ -38,10 +27,10 @@ copy and modify this GNU manual.'' @end quotation @end copying -@c Entries for @command{install-info} to use +@c Entries for @command{install-info} to use. We cannot use @value{tramp}. @dircategory Emacs network features @direntry -* @value{tramp}: (tramp). Transparent Remote Access, Multiple Protocol +* Tramp: (tramp). Transparent Remote Access, Multiple Protocol Emacs remote file access via ssh and scp. @end direntry @@ -62,7 +51,7 @@ editing package for Emacs. @value{tramp} stands for ``Transparent Remote (file) Access, Multiple Protocol''. This package provides remote file editing, similar to -Ange FTP. +Ange FTP@. The difference is that Ange FTP uses FTP to transfer files between the local and the remote host, whereas @value{tramp} uses a combination of @@ -83,9 +72,9 @@ Savannah Project Page}. @end ifhtml There is a mailing list for @value{tramp}, available at -@email{tramp-devel@@gnu.org}, and archived at -@uref{https://lists.gnu.org/r/tramp-devel/, the -@value{tramp} Mail Archive}. +@email{@value{tramp-bug-report-address}}, and archived at +@uref{https://lists.gnu.org/r/tramp-devel/, the @value{tramp} Mail +Archive}. @page @insertcopying @@ -96,7 +85,6 @@ There is a mailing list for @value{tramp}, available at For the end user: * Obtaining @value{tramp}:: How to obtain @value{tramp}. -* History:: History of @value{tramp}. @ifset installchapter * Installation:: Installing @value{tramp} with your Emacs. @end ifset @@ -122,8 +110,11 @@ For the developer: --- The Detailed Node Listing --- @c @ifset installchapter + Installing @value{tramp} with your Emacs +* System Requirements:: Prerequisites for @value{tramp} installation. +* Basic Installation:: Installation steps. * Installation parameters:: Parameters in order to control installation. * Testing:: A test suite for @value{tramp}. * Load paths:: How to plug-in @value{tramp} into your environment. @@ -162,6 +153,7 @@ Using @value{tramp} * Ad-hoc multi-hops:: Declaring multiple hops in the file name. * Remote processes:: Integration with other Emacs packages. * Cleanup remote connections:: Cleanup remote connections. +* Archive file names:: Access to files in file archives. How file names, directories and localnames are mangled and managed @@ -316,18 +308,44 @@ behind the scenes when you open a file with @value{tramp}. @node Obtaining @value{tramp} @chapter Obtaining @value{tramp} @cindex obtaining @value{tramp} +@cindex GNU ELPA +@vindex tramp-version @value{tramp} is included as part of Emacs (since Emacs 22.1). @value{tramp} is also freely packaged for download on the Internet at -@uref{https://ftp.gnu.org/gnu/tramp/}. +@uref{https://ftp.gnu.org/gnu/tramp/}. The version number of +@value{tramp} can be obtained by the variable @code{tramp-version}. +For released @value{tramp} versions, this is a three-number string +like ``2.4.2''. + +A @value{tramp} release, which is packaged with Emacs, could differ +slightly from the corresponding standalone release. This is because +it isn't always possible to synchronize release dates between Emacs +and @value{tramp}. Such version numbers have the Emacs version number +as suffix, like ``2.3.5.26.3''. This means @value{tramp} 2.3.5 as +integrated in Emacs 26.3. A complete list of @value{tramp} versions +packaged with Emacs can be retrieved by + +@vindex customize-package-emacs-version-alist +@lisp +(assoc 'Tramp customize-package-emacs-version-alist) +@end lisp + +@value{tramp} is also available as @uref{https://elpa.gnu.org, GNU +ELPA} package. Besides the standalone releases, further minor version +of @value{tramp} will appear on GNU ELPA, until the next @value{tramp} +release appears. These minor versions have a four-number string, like +``2.4.2.1''. @value{tramp} development versions are available on Git servers. -Development versions contain new and incomplete features. +Development versions contain new and incomplete features. The +development version of @value{tramp} is always the version number of +the next release, plus the suffix ``-pre'', like ``2.4.3-pre''. -One way to obtain from Git server is to visit the Savannah project -page at the following URL and then clicking on the Git link in the -navigation bar at the top. +One way to obtain @value{tramp} from Git server is to visit the +Savannah project page at the following URL and then clicking on the +Git link in the navigation bar at the top. @noindent @uref{https://savannah.gnu.org/projects/tramp/} @@ -385,33 +403,8 @@ $ autoconf @end example -@node History -@chapter History of @value{tramp} -@cindex history -@cindex development history - -@value{tramp} development started at the end of November 1998 as -@file{rssh.el}. It provided only one method of access. It used -@command{ssh} for login and @command{scp} to transfer file contents. -The name was changed to @file{rcp.el} before it got its present name -@value{tramp}. New methods of remote access were added, so was support -for version control. - -April 2000 was the first time when multi-hop methods were added. In -July 2002, @value{tramp} unified file names with Ange FTP@. In July -2004, proxy hosts replaced multi-hop methods. Running commands on -remote hosts was introduced in December 2005. Support for gateways -since April 2007 (and removed in December 2016). GVFS integration -started in February 2009. Remote commands on MS Windows hosts since -September 2011. Ad-hoc multi-hop methods (with a changed syntax) -re-enabled in November 2011. In November 2012, added Juergen -Hoetzel's @file{tramp-adb.el}. - -XEmacs support was stopped in January 2016. Since March 2017, -@value{tramp} syntax mandates a method. - @c Installation chapter is necessary only in case of standalone -@c installation. Text taken from trampinst.texi. +@c installation. @ifset installchapter @include trampinst.texi @end ifset @@ -463,13 +456,13 @@ this case it is written as @code{host#port}. @anchor{Quick Start Guide: @option{ssh} and @option{plink} methods} @section Using @option{ssh} and @option{plink} -@cindex method ssh -@cindex ssh method -@cindex method plink -@cindex plink method +@cindex method @option{ssh} +@cindex @option{ssh} method +@cindex method @option{plink} +@cindex @option{plink} method If your local host runs an SSH client, and the remote host runs an SSH -server, the most simple remote file name is +server, the simplest remote file name is @file{@trampfn{ssh,user@@host,/path/to/file}}. The remote file name @file{@trampfn{ssh,,}} opens a remote connection to yourself on the local host, and is taken often for testing @value{tramp}. @@ -482,12 +475,12 @@ an @command{ssh} server: @anchor{Quick Start Guide: @option{su}, @option{sudo} and @option{sg} methods} @section Using @option{su}, @option{sudo} and @option{sg} -@cindex method su -@cindex su method -@cindex method sudo -@cindex sudo method -@cindex method sg -@cindex sg method +@cindex method @option{su} +@cindex @option{su} method +@cindex method @option{sudo} +@cindex @option{sudo} method +@cindex method @option{sg} +@cindex @option{sg} method Sometimes, it is necessary to work on your local host under different permissions. For this, you could use the @option{su} or @option{sudo} @@ -500,12 +493,46 @@ The method @option{sg} stands for ``switch group''; the changed group must be used here as user name. The default host name is the same. +@anchor{Quick Start Guide: @option{ssh}, @option{plink}, @option{su}, @option{sudo} and @option{sg} methods} +@section Combining @option{ssh} or @option{plink} with @option{su} or @option{sudo} +@cindex method @option{ssh} +@cindex @option{ssh} method +@cindex method @option{plink} +@cindex @option{plink} method +@cindex method @option{su} +@cindex @option{su} method +@cindex method @option{sudo} +@cindex @option{sudo} method + +If the @option{su} or @option{sudo} option shall be performed on +another host, it could be comnbined with a leading @option{ssh} or +@option{plink} option. That means, @value{tramp} connects first to +the other host with non-administrative credentials, and changes to +administrative credentials on that host afterwards. In a simple case, +the syntax looks like +@file{@value{prefix}ssh@value{postfixhop}user@@host|sudo@value{postfixhop}@value{postfix}/path/to/file}. +@xref{Ad-hoc multi-hops}. + + +@anchor{Quick Start Guide: @option{sudoedit} method} +@section Using @command{sudoedit} +@cindex method @option{sudoedit} +@cindex @option{sudoedit} method + +The @option{sudoedit} method is similar to the @option{sudo} method. +However, it is a different implementation: it does not keep an open +session running in the background. This is for security reasons; on +the backside this method is less performant than the @option{sudo} +method, it is restricted to the @samp{localhost} only, and it does not +support external processes. + + @anchor{Quick Start Guide: @option{smb} method} @section Using @command{smbclient} -@cindex method smb -@cindex smb method -@cindex ms windows (with smb method) -@cindex smbclient +@cindex method @option{smb} +@cindex @option{smb} method +@cindex ms windows (with @option{smb} method) +@cindex @command{smbclient} In order to access a remote MS Windows host or Samba server, the @command{smbclient} client is used. The remote file name syntax is @@ -518,39 +545,48 @@ of the local file name is the share exported by the remote host, @section Using GVFS-based methods @cindex methods, gvfs @cindex gvfs based methods -@cindex method sftp -@cindex sftp method -@cindex method afp -@cindex afp method -@cindex method dav -@cindex method davs -@cindex dav method -@cindex davs method - -On systems, which have installed the virtual file system for the Gnome -Desktop (GVFS), its offered methods could be used by @value{tramp}. -Examples are @file{@trampfn{sftp,user@@host,/path/to/file}}, +@cindex method @option{sftp} +@cindex @option{sftp} method +@cindex method @option{afp} +@cindex @option{afp} method +@cindex method @option{dav} +@cindex method @option{davs} +@cindex @option{dav} method +@cindex @option{davs} method + +On systems, which have installed the virtual file system for the +@acronym{GNOME} Desktop (GVFS), its offered methods could be used by +@value{tramp}. Examples are +@file{@trampfn{sftp,user@@host,/path/to/file}}, @file{@trampfn{afp,user@@host,/path/to/file}} (accessing Apple's AFP file system), @file{@trampfn{dav,user@@host,/path/to/file}} and @file{@trampfn{davs,user@@host,/path/to/file}} (for WebDAV shares). -@anchor{Quick Start Guide: Google Drive} -@section Using Google Drive -@cindex method gdrive -@cindex gdrive method +@anchor{Quick Start Guide: GNOME Online Accounts based methods} +@section Using @acronym{GNOME} Online Accounts based methods +@cindex @acronym{GNOME} Online Accounts +@cindex method @option{gdrive} +@cindex @option{gdrive} method @cindex google drive +@cindex method @option{nextcloud} +@cindex @option{nextcloud} method +@cindex nextcloud -Another GVFS-based method allows to access a Google Drive file system. -The file name syntax is here always -@file{@trampfn{gdrive,john.doe@@gmail.com,/path/to/file}}. -@samp{john.doe@@gmail.com} stands here for your Google Drive account. +GVFS-based methods include also @acronym{GNOME} Online Accounts, which +support the @option{Files} service. These are the Google Drive file +system, and the OwnCloud/NextCloud file system. The file name syntax +is here always +@file{@trampfn{gdrive,john.doe@@gmail.com,/path/to/file}} +(@samp{john.doe@@gmail.com} stands here for your Google Drive +account), or @file{@trampfn{nextcloud,user@@host#8081,/path/to/file}} +(@samp{8081} stands for the port number) for OwnCloud/NextCloud files. @anchor{Quick Start Guide: Android} @section Using Android -@cindex method adb -@cindex adb method +@cindex method @option{adb} +@cindex @option{adb} method @cindex android An Android device, which is connected via USB to your local host, can @@ -558,6 +594,18 @@ be accessed via the @command{adb} command. No user or host name is needed. The file name syntax is @file{@trampfn{adb,,/path/to/file}}. +@anchor{Quick Start Guide: @option{rclone} method} +@section Using @command{rclone} +@cindex method @option{rclone} +@cindex @option{rclone} method + +A convenient way to access system storages is the @command{rclone} +program. If you have configured a storage in @command{rclone} under a +name @samp{storage} (for example), you could access it via the remote +file name syntax @file{@trampfn{rclone,storage,/path/to/file}}. User +names are not needed. + + @node Configuration @chapter Configuring @value{tramp} @cindex configuration @@ -582,6 +630,13 @@ installed and loaded: (customize-set-variable 'tramp-verbose 6 "Enable remote command traces") @end lisp +For functions used to configure @value{tramp}, the following clause +might be used in your init file: + +@lisp +(with-eval-after-load 'tramp (tramp-change-syntax 'simplified)) +@end lisp + @menu * Connection types:: Types of connections to remote hosts. @@ -654,8 +709,8 @@ Inline methods can work in situations where an external transfer program is unavailable. Inline methods also work when transferring files between different @emph{user identities} on the same host. -@cindex uuencode -@cindex mimencode +@cindex @command{uuencode} +@cindex @command{mimencode} @cindex base-64 encoding @value{tramp} checks the remote host for the availability and @@ -676,15 +731,15 @@ such optimization. @table @asis @item @option{rsh} -@cindex method rsh -@cindex rsh method +@cindex method @option{rsh} +@cindex @option{rsh} method @command{rsh} is an option for connecting to hosts within local networks since @command{rsh} is not as secure as other methods. @item @option{ssh} -@cindex method ssh -@cindex ssh method +@cindex method @option{ssh} +@cindex @option{ssh} method @command{ssh} is a more secure option than others to connect to a remote host. @@ -695,15 +750,15 @@ host name, a hash sign, then a port number). It is the same as passing @samp{-p 42} to the @command{ssh} command. @item @option{telnet} -@cindex method telnet -@cindex telnet method +@cindex method @option{telnet} +@cindex @option{telnet} method Connecting to a remote host with @command{telnet} is as insecure as the @option{rsh} method. @item @option{su} -@cindex method su -@cindex su method +@cindex method @option{su} +@cindex @option{su} method Instead of connecting to a remote host, @command{su} program allows editing as another user. The host can be either @samp{localhost} or @@ -711,21 +766,27 @@ the host returned by the function @command{(system-name)}. See @ref{Multi-hops} for an exception to this behavior. @item @option{sudo} -@cindex method sudo -@cindex sudo method +@cindex method @option{sudo} +@cindex @option{sudo} method Similar to @option{su} method, @option{sudo} uses @command{sudo}. @command{sudo} must have sufficient rights to start a shell. +For security reasons, a @option{sudo} connection is disabled after a +predefined timeout (5 minutes per default). This can be changed, see +@ref{Predefined connection information}. + @item @option{doas} -@cindex method doas -@cindex doas method +@cindex method @option{doas} +@cindex @option{doas} method -This method is used on OpenBSD like the @command{sudo} command. +This method is used on OpenBSD like the @command{sudo} command. Like +the @option{sudo} method, a @option{doas} connection is disabled after +a predefined timeout. @item @option{sg} -@cindex method sg -@cindex sg method +@cindex method @option{sg} +@cindex @option{sg} method The @command{sg} program allows editing as different group. The host can be either @samp{localhost} or the host returned by the function @@ -734,8 +795,8 @@ denotes a group name. See @ref{Multi-hops} for an exception to this behavior. @item @option{sshx} -@cindex method sshx -@cindex sshx method +@cindex method @option{sshx} +@cindex @option{sshx} method Works like @option{ssh} but without the extra authentication prompts. @option{sshx} uses @samp{ssh -t -t @var{host} -l @var{user} /bin/sh} @@ -755,23 +816,23 @@ missing shell prompts that confuses @value{tramp}. @option{sshx} supports the @samp{-p} argument. @item @option{krlogin} -@cindex method krlogin -@cindex krlogin method -@cindex kerberos (with krlogin method) +@cindex method @option{krlogin} +@cindex @option{krlogin} method +@cindex kerberos (with @option{krlogin} method) This method is also similar to @option{ssh}. It uses the @command{krlogin -x} command only for remote host login. @item @option{ksu} -@cindex method ksu -@cindex ksu method -@cindex kerberos (with ksu method) +@cindex method @option{ksu} +@cindex @option{ksu} method +@cindex kerberos (with @option{ksu} method) This is another method from the Kerberos suite. It behaves like @option{su}. @item @option{plink} -@cindex method plink -@cindex plink method +@cindex method @option{plink} +@cindex @option{plink} method @option{plink} method is for MS Windows users with the PuTTY implementation of SSH@. It uses @samp{plink -ssh} to log in to the @@ -783,8 +844,8 @@ session. @option{plink} method supports the @samp{-P} argument. @item @option{plinkx} -@cindex method plinkx -@cindex plinkx method +@cindex method @option{plinkx} +@cindex @option{plinkx} method Another method using PuTTY on MS Windows with session names instead of host names. @option{plinkx} calls @samp{plink -load @var{session} @@ -814,10 +875,9 @@ methods. @table @asis @item @option{rcp} -@cindex method rcp -@cindex rcp method -@cindex rcp (with rcp method) -@cindex rsh (with rcp method) +@cindex method @option{rcp} +@cindex @option{rcp} method +@cindex @command{rsh} (with @option{rcp} method) This method uses the @command{rsh} and @command{rcp} commands to connect to the remote host and transfer files. This is the fastest @@ -827,10 +887,9 @@ The alternative method @option{remcp} uses the @command{remsh} and @command{rcp} commands. @item @option{scp} -@cindex method scp -@cindex scp method -@cindex scp (with scp method) -@cindex ssh (with scp method) +@cindex method @option{scp} +@cindex @option{scp} method +@cindex @command{ssh} (with @option{scp} method) Using a combination of @command{ssh} to connect and @command{scp} to transfer is the most secure. While the performance is good, it is @@ -844,10 +903,9 @@ argument list to @command{ssh}, and @samp{-P 42} in the argument list to @command{scp}. @item @option{rsync} -@cindex method rsync -@cindex rsync method -@cindex rsync (with rsync method) -@cindex ssh (with rsync method) +@cindex method @option{rsync} +@cindex @option{rsync} method +@cindex @command{ssh} (with @option{rsync} method) @command{ssh} command to connect in combination with @command{rsync} command to transfer is similar to the @option{scp} method. @@ -859,10 +917,9 @@ is lost if the file exists only on one side of the connection. This method supports the @samp{-p} argument. @item @option{scpx} -@cindex method scpx -@cindex scpx method -@cindex scp (with scpx method) -@cindex ssh (with scpx method) +@cindex method @option{scpx} +@cindex @option{scpx} method +@cindex @command{ssh} (with @option{scpx} method) @option{scpx} is useful to avoid login shell questions. It is similar in performance to @option{scp}. @option{scpx} uses @samp{ssh -t -t @@ -876,16 +933,14 @@ This method supports the @samp{-p} argument. @item @option{pscp} @item @option{psftp} -@cindex method pscp -@cindex pscp method -@cindex pscp (with pscp method) -@cindex plink (with pscp method) -@cindex putty (with pscp method) -@cindex method psftp -@cindex psftp method -@cindex pscp (with psftp method) -@cindex plink (with psftp method) -@cindex putty (with psftp method) +@cindex method @option{pscp} +@cindex @option{pscp} method +@cindex @command{plink} (with @option{pscp} method) +@cindex @command{putty} (with @option{pscp} method) +@cindex method @option{psftp} +@cindex @option{psftp} method +@cindex @command{plink} (with @option{psftp} method) +@cindex @command{putty} (with @option{psftp} method) These methods are similar to @option{scp} or @option{sftp}, but they use the @command{plink} command to connect to the remote host, and @@ -898,10 +953,9 @@ session. These methods support the @samp{-P} argument. @item @option{fcp} -@cindex method fcp -@cindex fcp method -@cindex fsh (with fcp method) -@cindex fcp (with fcp method) +@cindex method @option{fcp} +@cindex @option{fcp} method +@cindex @command{fsh} (with @option{fcp} method) This method is similar to @option{scp}, but uses @command{fsh} to connect and @command{fcp} to transfer files. @command{fsh/fcp}, a @@ -913,18 +967,17 @@ benefits. The command used for this connection is: @samp{fsh @var{host} -l @var{user} /bin/sh -i} -@cindex method fsh -@cindex fsh method +@cindex method @option{fsh} +@cindex @option{fsh} method @option{fsh} has no inline method since the multiplexing it offers is not useful for @value{tramp}. @command{fsh} connects to remote host and @value{tramp} keeps that one connection open. @item @option{nc} -@cindex method nc -@cindex nc method -@cindex nc (with nc method) -@cindex telnet (with nc method) +@cindex method @option{nc} +@cindex @option{nc} method +@cindex @command{telnet} (with @option{nc} method) Using @command{telnet} to connect and @command{nc} to transfer files is sometimes the only combination suitable for accessing routers or @@ -932,19 +985,43 @@ NAS hosts. These dumb devices have severely restricted local shells, such as the @command{busybox} and do not host any other encode or decode programs. +@item @option{sudoedit} +@cindex method @option{sudoedit} +@cindex @option{sudoedit} method + +The @option{sudoedit} method allows to edit a file as a different user +on the local host. You could regard this as @value{tramp}'s +implementation of the @command{sudoedit}. Contrary to the +@option{sudo} method, all magic file name functions are implemented by +single @command{sudo @dots{}} commands. The purpose is to make +editing such a file as secure as possible; there must be no session +running in the Emacs background which could be attacked from inside +Emacs. + +Consequently, external processes are not implemented. + +The host name of such remote file names must represent the local host. +Since the default value is already proper, it is recommended not to +use any host name in the remote file name, like +@file{@trampfn{sudoedit,,/path/to/file}} or +@file{@trampfn{sudoedit,user@@,/path/to/file}}. + +Like the @option{sudo} method, a @option{sudoedit} password expires +after a predefined timeout. + @item @option{ftp} -@cindex method ftp -@cindex ftp method +@cindex method @option{ftp} +@cindex @option{ftp} method When @value{tramp} uses @option{ftp}, it forwards requests to whatever -ftp program is specified by Ange FTP. This external program must be +ftp program is specified by Ange FTP@. This external program must be capable of servicing requests from @value{tramp}. @item @option{smb} -@cindex method smb -@cindex smb method -@cindex ms windows (with smb method) -@cindex smbclient +@cindex method @option{smb} +@cindex @option{smb} method +@cindex ms windows (with @option{smb} method) +@cindex @command{smbclient} This non-native @value{tramp} method connects via the Server Message Block (SMB) networking protocol to hosts running file servers that are @@ -1015,9 +1092,9 @@ can. @item @option{adb} -@cindex method adb -@cindex adb method -@cindex android (with adb method) +@cindex method @option{adb} +@cindex @option{adb} method +@cindex android (with @option{adb} method) @vindex tramp-adb-program @vindex PATH@r{, environment variable} @@ -1052,6 +1129,48 @@ specified using @file{device#42} host name syntax or @value{tramp} can use the default value as declared in @command{adb} command. Port numbers are not applicable to Android devices connected through USB@. + +@item @option{rclone} +@cindex method @option{rclone} +@cindex @option{rclone} method + +@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 +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}. + +A system storage must be configured via the @command{rclone config} +command, outside Emacs. If you have configured a storage in +@command{rclone} under a name @samp{storage} (for example), you could +access it via the remote file name + +@example +@trampfn{rclone,storage,/path/to/file} +@end example + +User names are part of the @command{rclone} configuration, and not +needed in the remote file name. If a user name is contained in the +remote file name, it is ignored. + +Internally, @value{tramp} mounts the remote system storage at location +@file{/tmp/tramp.rclone.storage}, with @file{storage} being the name +of the configured system storage. + +Optional flags to the different @option{rclone} operations could be +passed as connection property, @xref{Predefined connection +information}. Supported properties are @samp{mount-args}, +@samp{copyto-args} and @samp{moveto-args}. + +Access via @option{rclone} is slow. If you have an alternative method +for accessing the system storage, you shall prefer this. @ref{GVFS +based methods} for example, methods @option{gdrive} and +@option{nextcloud}. + +@strong{Note}: The @option{rclone} method is experimental, don't use +it in production systems! + @end table @@ -1061,7 +1180,7 @@ numbers are not applicable to Android devices connected through USB@. @cindex gvfs based methods @cindex dbus -GVFS is the virtual file system for the Gnome Desktop, +GVFS is the virtual file system for the @acronym{GNOME} Desktop, @uref{https://en.wikipedia.org/wiki/GVFS}. Remote files on GVFS are mounted locally through FUSE and @value{tramp} uses this locally mounted directory internally. @@ -1072,8 +1191,8 @@ D-Bus, dbus}. @table @asis @item @option{afp} -@cindex method afp -@cindex afp method +@cindex method @option{afp} +@cindex @option{afp} method This method is for connecting to remote hosts with the Apple Filing Protocol for accessing files on macOS volumes. @value{tramp} access @@ -1082,10 +1201,10 @@ syntax requires a leading volume (share) name, for example: @item @option{dav} @item @option{davs} -@cindex method dav -@cindex method davs -@cindex dav method -@cindex davs method +@cindex method @option{dav} +@cindex method @option{davs} +@cindex @option{dav} method +@cindex @option{davs} method @option{dav} method provides access to WebDAV files and directories based on standard protocols, such as HTTP@. @option{davs} does the same @@ -1093,11 +1212,11 @@ but with SSL encryption. Both methods support the port numbers. Paths being part of the WebDAV volume to be mounted by GVFS, as it is common for OwnCloud or NextCloud file names, are not supported by -these methods. +these methods. See method @option{nextcloud} for handling them. @item @option{gdrive} -@cindex method gdrive -@cindex gdrive method +@cindex method @option{gdrive} +@cindex @option{gdrive} method @cindex google drive Via the @option{gdrive} method it is possible to access your Google @@ -1111,36 +1230,36 @@ Since Google Drive uses cryptic blob file names internally, could produce unexpected behavior in case two files in the same directory have the same @code{display-name}, such a situation must be avoided. -@item @option{obex} -@cindex method obex -@cindex obex method +@item @option{nextcloud} +@cindex @acronym{GNOME} Online Accounts +@cindex method @option{nextcloud} +@cindex @option{nextcloud} method +@cindex nextcloud -OBEX is an FTP-like access protocol for cell phones and similar simple -devices. @value{tramp} supports OBEX over Bluetooth. +As the name indicates, the method @option{nextcloud} allows you to +access OwnCloud or NextCloud hosted files and directories. Like the +@option{gdrive} method, your credentials must be populated in your +@command{Online Accounts} application outside Emacs. The method +supports port numbers. @item @option{sftp} -@cindex method sftp -@cindex sftp method +@cindex method @option{sftp} +@cindex @option{sftp} method This method uses @command{sftp} in order to securely access remote hosts. @command{sftp} is a more secure option for connecting to hosts that for security reasons refuse @command{ssh} connections. -@item @option{synce} -@cindex method synce -@cindex synce method - -@option{synce} method allows connecting to MS Windows Mobile devices. -It uses GVFS for mounting remote files and directories via FUSE and -requires the SYNCE-GVFS plugin. - @end table @defopt tramp-gvfs-methods This user option is a list of external methods for GVFS@. By default, this list includes @option{afp}, @option{dav}, @option{davs}, -@option{gdrive}, @option{obex}, @option{sftp} and @option{synce}. -Other methods to include are: @option{ftp} and @option{smb}. +@option{gdrive}, @option{nextcloud} and @option{sftp}. Other methods +to include are @option{ftp}, @option{http}, @option{https} and +@option{smb}. These methods are not intended to be used directly as +GVFS based method. Instead, they are added here for the benefit of +@ref{Archive file names}. @end defopt @@ -1378,7 +1497,8 @@ connect to @samp{bastion.your.domain}, then: @end lisp @var{proxy} can take patterns @code{%h} or @code{%u} for @var{host} or -@var{user} respectively. +@var{user} respectively. Ports or domains, if they are part of +a hop file name, are not expanded by those patterns. To login as @samp{root} on remote hosts in the domain @samp{your.domain}, but login as @samp{root} is disabled for non-local @@ -1395,8 +1515,10 @@ Opening @file{@trampfn{sudo,randomhost.your.domain,}} first connects to @samp{randomhost.your.domain} via @code{ssh} under your account name, and then performs @code{sudo -u root} on that host. -It is key for the sudo method in the above example to be applied on -the host after reaching it and not on the local host. +It is key for the @option{sudo} method in the above example to be +applied on the host after reaching it and not on the local host. +@value{tramp} checks therefore, that the host name for such hops +matches the host name of the previous hop. @var{host}, @var{user} and @var{proxy} can also take Lisp forms. These forms when evaluated must return either a string or @code{nil}. @@ -1462,8 +1584,8 @@ Host host.other.domain @end group @end example -@code{nc} is BSD's netcat program, which establishes HTTP tunnels. Any -other program with such a feature could be used as well. +@code{nc} is BSD's netcat program, which establishes HTTP tunnels. +Any other program with such a feature could be used as well. In the example, opening @file{@trampfn{ssh,host.your.domain,}} passes the HTTP proxy server @samp{proxy.your.domain} on port 3128. @@ -1492,6 +1614,74 @@ predefined methods. Any part of this list can be modified with more suitable settings. Refer to the Lisp documentation of that variable, accessible with @kbd{C-h v tramp-methods @key{RET}}. +In the ELPA archives, there are several examples of such extensions. +They can be installed with Emacs' Package Manager. This includes + +@table @samp +@c @item anything-tramp +@c @item counsel-tramp +@c @item helm-tramp +@c Contact Masashí Míyaura <masasam@users.noreply.github.com> + +@c @item ibuffer-tramp.el +@c Contact Svend Sorensen <svend@@ciffer.net> + +@item docker-tramp +@cindex method @option{docker} +@cindex @option{docker} method +Integration for Docker containers. A container is accessed via +@file{@trampfn{docker,user@@container,/path/to/file}}, where +@samp{user} is the (optional) user that you want to use, and +@samp{container} is the id or name of the container. + +@item kubernetes-tramp +@cindex method @option{kubectl} +@cindex @option{kubectl} method +Integration for Docker containers deployed in a Kubernetes cluster. +It is derived from @samp{docker-tramp}. A container is accessed via +@file{@trampfn{kubectl,user@@container,/path/to/file}}, @samp{user} +and @samp{container} have the same meaning as in @samp{docker-tramp}. + +@item lxc-tramp +@cindex method @option{lxc} +@cindex @option{lxc} method +Integration for LXC containers. A container is accessed via +@file{@trampfn{lxc,container,/path/to/file}}, @samp{container} has the +same meaning as in @samp{docker-tramp}. A @samp{user} specification +is ignored. + +@item lxd-tramp +@cindex method @option{lxd} +@cindex @option{lxd} method +Integration for LXD containers. A container is accessed via +@file{@trampfn{lxd,user@@container,/path/to/file}}, @samp{user} and +@samp{container} have the same meaning as in @samp{docker-tramp}. + +@item magit-tramp +@cindex method @option{git} +@cindex @option{git} method +Browing git repositories with @code{magit}. A versioned file is accessed via +@file{@trampfn{git,rev@@root-dir,/path/to/file}}. @samp{rev} is a git +revision, and @samp{root-dir} is a virtual host name for the root +directory, specified in @code{magit-tramp-hosts-alist}. + +@item tramp-hdfs +@cindex method @option{hdfs} +@cindex @option{hdfs} method +Access of a hadoop/hdfs file system. A file is accessed via +@file{@trampfn{hdfs,user@@node,/path/to/file}}, where @samp{user} is +the user that you want to use, and @samp{node} is the name of the +hadoop server. + +@item vagrant-tramp +@cindex method @option{vagrant} +@cindex @option{vagrant} method +Convenience method to access vagrant boxes. It is often used in +multi-hop file names like +@file{@value{prefix}vagrant@value{postfixhop}box|sudo@value{postfixhop}box@value{postfix}/path/to/file}, +where @samp{box} is the name of the vagrant box. +@end table + @node Customizing Completion @section Selecting config files for user/host name completion @@ -1641,7 +1831,7 @@ the need. The package @file{auth-source.el}, originally developed for No Gnus, reads passwords from different sources, @xref{Help for users, , auth-source, auth}. The default authentication file is -@file{~/.authinfo.gpg}, but this can be changed via the variable +@file{~/.authinfo.gpg}, but this can be changed via the user option @code{auth-sources}. @noindent @@ -1660,9 +1850,26 @@ file name syntax, must be appended to the machine and login items: machine melancholia#4711 port davs login daniel%BIZARRE password geheim @end example +@vindex auth-source-save-behavior +If there doesn't exist a proper entry, the password is read +interactively. After successful login (verification of the password), +it is offered to save a corresponding entry for further use by +@code{auth-source} backends which support this. This could be changed +by setting the user option @code{auth-source-save-behavior} to @code{nil}. + @vindex auth-source-debug Set @code{auth-source-debug} to @code{t} to debug messages. +@vindex ange-ftp-netrc-filename +@strong{Note} that @file{auth-source.el} is not used for @option{ftp} +connections, because @value{tramp} passes the work to Ange FTP@. If +you want, for example, use your @file{~/.authinfo.gpg} authentication +file, you must customize @code{ange-ftp-netrc-filename}: + +@lisp +(customize-set-variable 'ange-ftp-netrc-filename "~/.authinfo.gpg") +@end lisp + @anchor{Caching passwords} @subsection Caching passwords @@ -1742,6 +1949,24 @@ The parameters @code{tramp-remote-shell} and @code{tramp-remote-shell-login} in @code{tramp-methods} now have new values for the remote host. +A common use case is to override the session timeout of a connection, +that is the time (in seconds) after a connection is disabled, and must +be reestablished. This can be set for any connection; for the +@option{sudo} and @option{doas} methods there exist predefined values. +A value of @code{nil} disables this feature. For example: + +@lisp +@group +(add-to-list 'tramp-connection-properties + (list (regexp-quote "@trampfn{sudo,root@@system-name,}") + "session-timeout" 30)) +@end group +@end lisp + +@noindent +@samp{system-name} stands here for the host returned by the function +@command{(system-name)}. + @var{property} could also be any property found in @code{tramp-persistency-file-name}. @@ -1807,10 +2032,43 @@ preserves the path value, which can be used to update shell supports the login argument @samp{-l}. @end defopt +Starting with Emacs 26, @code{tramp-remote-path} can be set per host +via connection-local +@ifinfo +variables, @xref{Connection Variables, , , emacs}. +@end ifinfo +@ifnotinfo +variables. +@end ifnotinfo +You could define your own search directories like this: + +@lisp +@group +(connection-local-set-profile-variables 'remote-path-with-bin + '((tramp-remote-path . ("~/bin" tramp-default-remote-path)))) +@end group + +@group +(connection-local-set-profile-variables 'remote-path-with-apply-pub-bin + '((tramp-remote-path . ("/appli/pub/bin" tramp-default-remote-path)))) +@end group + +@group +(connection-local-set-profiles + '(:application tramp :machine "randomhost") 'remote-path-with-bin) +@end group + +@group +(connection-local-set-profiles + '(:application tramp :user "anotheruser" :machine "anotherhost") + 'remote-path-with-apply-pub-bin) +@end group +@end lisp + When remote search paths are changed, local @value{tramp} caches must -be recomputed. To force @value{tramp} to recompute afresh, exit -Emacs, remove the persistent file (@pxref{Connection caching}), and -restart Emacs. +be recomputed. To force @value{tramp} to recompute afresh, call +@kbd{M-x tramp-cleanup-this-connection @key{RET}} or friends +(@pxref{Cleanup remote connections}). @node Remote shell setup @@ -2019,10 +2277,10 @@ shell-specific config files. For example, bash can use parsing. This redefinition affects the looks of a prompt in an interactive remote shell through commands, such as @kbd{M-x shell @key{RET}}. Such prompts, however, can be reset to something more -readable and recognizable using these @value{tramp} variables. +readable and recognizable using these environment variables. -@value{tramp} sets the @env{INSIDE_EMACS} variable in the startup -script file @file{~/.emacs_SHELLNAME}. +@value{tramp} sets the @env{INSIDE_EMACS} environment variable in the +startup script file @file{~/.emacs_SHELLNAME}. @env{SHELLNAME} is @code{bash} or equivalent shell names. Change it by setting the environment variable @env{ESHELL} in the @file{.emacs} as @@ -2048,8 +2306,8 @@ fi @end ifinfo @item @command{busybox} / @command{nc} -@cindex unix command nc -@cindex nc unix command +@cindex unix command @command{nc} +@cindex @command{nc} unix command @value{tramp}'s @option{nc} method uses the @command{nc} command to install and execute a listener as follows (see @code{tramp-methods}): @@ -2267,8 +2525,8 @@ to direct all auto saves to that location. This section is incomplete. Please share your solutions. -@cindex method sshx with cygwin -@cindex sshx method with cygwin +@cindex method @option{sshx} with cygwin +@cindex @option{sshx} method with cygwin Cygwin's @command{ssh} works only with a Cygwin version of Emacs. To check for compatibility: type @kbd{M-x eshell @key{RET}}, and start @@ -2290,8 +2548,8 @@ On @uref{https://www.emacswiki.org/emacs/SshWithNTEmacs, the Emacs Wiki} it is explained how to use the helper program @command{fakecygpty} to fix this problem. -@cindex method scpx with cygwin -@cindex scpx method with cygwin +@cindex method @option{scpx} with cygwin +@cindex @option{scpx} method with cygwin When using the @option{scpx} access method, Emacs may call @command{scp} with MS Windows file naming, such as @code{c:/foo}. But @@ -2347,6 +2605,7 @@ is a feature of Emacs that may cause missed prompts when using * Ad-hoc multi-hops:: Declaring multiple hops in the file name. * Remote processes:: Integration with other Emacs packages. * Cleanup remote connections:: Cleanup remote connections. +* Archive file names:: Access to files in file archives. @end menu @@ -2429,7 +2688,7 @@ names. Beside the @code{default} value, @var{syntax} can be @item @code{simplified} @cindex simplified syntax -The remote file name syntax is similar to the syntax used by Ange FTP. +The remote file name syntax is similar to the syntax used by Ange FTP@. A remote file name has the form @code{@value{prefix}user@@host@value{postfix}path/to/file}. The @code{user@@} part is optional, and the method is determined by @@ -2453,11 +2712,12 @@ and @code{user@@} parts are optional. @defvar tramp-file-name-regexp This variable keeps a regexp which matches the selected remote file -name syntax. However, it is not recommended to use this variable in -external packages, a call of @code{file-remote-p} is much more -appropriate. +name syntax. Its value changes after every call of +@code{tramp-change-syntax}. However, it is not recommended to use +this variable in external packages, a call of @code{file-remote-p} is +much more appropriate. @ifinfo -@pxref{Magic File Names, , , elisp} +@pxref{Magic File Names, , , elisp}. @end ifinfo @end defvar @end ifset @@ -2531,6 +2791,14 @@ names on that host. When the configuration (@pxref{Customizing Completion}) includes user names, then the completion lists will account for the user names as well. +@vindex tramp-completion-use-auth-sources +Results from @code{auth-sources} search (@pxref{Using an +authentication file}) are added to the completion candidates. This +search could be annoying, for example due to a passphrase request of +the @file{~/.authinfo.gpg} authentication file. The user option +@code{tramp-completion-use-auth-sources} controls, whether such a +search is performed during completion. + Remote hosts previously visited or hosts whose connections are kept persistently (@pxref{Connection caching}) will be included in the completion lists. @@ -2553,7 +2821,7 @@ Example: @print{} @trampfn{ssh,melancholia,/etc} @kbd{C-x C-f @trampfn{ssh,melancholia,//etc} @key{TAB}} - @print{} /etc + @print{} @trampfn{ssh,melancholia,/etc} @kbd{C-x C-f @trampfn{ssh,melancholia,/usr/local/bin///etc} @key{TAB}} @print{} /etc @@ -2579,9 +2847,9 @@ directory contents. @cindex multi-hop, ad-hoc @cindex proxy hosts, ad-hoc -@value{tramp} file name syntax can accommodate ad hoc specification of +@value{tramp} file name syntax can accommodate ad-hoc specification of multiple proxies without using @code{tramp-default-proxies-alist} -configuration setup(@pxref{Multi-hops}). +configuration setup (@pxref{Multi-hops}). Each proxy is specified using the same syntax as the remote host specification minus the file name part. Each hop is separated by a @@ -2596,13 +2864,14 @@ proxy @samp{bird@@bastion} to a remote file on @samp{you@@remotehost}: Each involved method must be an inline method (@pxref{Inline methods}). -Proxies can take patterns @code{%h} or @code{%u}. - @value{tramp} adds the ad-hoc definitions on the fly to -@code{tramp-default-proxies-alist} and is available for re-use -during that Emacs session. Subsequent @value{tramp} connections to -the same remote host can then use the shortcut form: -@samp{@trampfn{ssh,you@@remotehost,/path}}. +@code{tramp-default-proxies-alist} and is available for re-use during +that Emacs session. Subsequent @value{tramp} connections to the same +remote host can then use the shortcut form: +@samp{@trampfn{ssh,you@@remotehost,/path}}. Ad-hoc definitions are +removed from @code{tramp-default-proxies-alist} via the command +@kbd{M-x tramp-cleanup-all-connections @key{RET}} (@pxref{Cleanup +remote connections}). @defopt tramp-save-ad-hoc-proxies For ad-hoc definitions to be saved automatically in @@ -2614,6 +2883,17 @@ For ad-hoc definitions to be saved automatically in @end lisp @end defopt +Ad-hoc proxies can take patterns @code{%h} or @code{%u} like in +@code{tramp-default-proxies-alist}. The following file name expands +to user @code{root} on host @code{remotehost}, starting with an +@option{ssh} session on host @code{remotehost}: +@samp{@value{prefix}ssh@value{postfixhop}%h|su@value{postfixhop}remotehost@value{postfix}}. + +On the other hand, if a trailing hop does not specifiy a host name, +the host name of the previous hop is reused. Therefore, the following +file name is equivalent to the previous example: +@samp{@value{prefix}ssh@value{postfixhop}remotehost|su@value{postfixhop}@value{postfix}}. + @node Remote processes @section Integration with other Emacs packages @@ -2776,7 +3056,7 @@ Starting with Emacs 26, you could use connection-local variables for setting different values of @code{explicit-shell-file-name} for different remote hosts. @ifinfo -@pxref{Connection Local Variables, , , elisp} +@xref{Connection Variables, , , emacs}. @end ifinfo @lisp @@ -2829,6 +3109,25 @@ host. Example: @kbd{M-x auto-revert-tail-mode @key{RET}} runs similarly showing continuous output. +@vindex shell-file-name +@vindex shell-command-switch +@code{shell-command} uses the variables @code{shell-file-name} and +@code{shell-command-switch} in order to determine which shell to run. +For remote hosts, their default values are @file{/bin/sh} and +@option{-c}, respectively (except for the @option{adb} method, which +uses @file{/system/bin/sh}). Like the variables in the previous +section, these variables can be changed via connection-local +variables. + +@vindex async-shell-command-width +@vindex COLUMNS@r{, environment variable} +If Emacs supports the variable @code{async-shell-command-width} (since +Emacs 27.1), @value{tramp} cares about its value for asynchronous +shell commands. It specifies the number of display columns for +command output. For synchronous shell commands, a similar effect can +be achieved by adding the environment variable @env{COLUMNS} to +@code{tramp-remote-process-environment}. + @subsection Running @code{eshell} on a remote host @cindex @code{eshell} @@ -2877,7 +3176,7 @@ uid=0(root) gid=0(root) groups=0(root) @anchor{Running a debugger on a remote host} @subsection Running a debugger on a remote host -@cindex @code{gud} +@cindex @file{gud.el} @cindex @code{gdb} @cindex @code{perldb} @@ -2972,7 +3271,8 @@ interactively, this command lists active remote connections in the minibuffer. Each connection is of the format @file{@trampfn{method,user@@host,}}. Flushing remote connections also cleans the password cache (@pxref{Password handling}), file cache, -connection cache (@pxref{Connection caching}), and connection buffers. +connection cache (@pxref{Connection caching}), recentf cache +(@pxref{File Conveniences, , , emacs}), and connection buffers. @end deffn @deffn Command tramp-cleanup-this-connection @@ -2982,16 +3282,257 @@ as in @code{tramp-cleanup-connection}. @deffn Command tramp-cleanup-all-connections Flushes all active remote connection objects, the same as in -@code{tramp-cleanup-connection}. +@code{tramp-cleanup-connection}. This command removes also ad-hoc +proxy definitions (@pxref{Ad-hoc multi-hops}). + @end deffn @deffn Command tramp-cleanup-all-buffers Just as for @code{tramp-cleanup-all-connections}, all remote -connections are cleaned up in addition to killing buffers related to -that remote connection. +connections and ad-hoc proxy definition are cleaned up in addition to +killing buffers related to that remote connection. @end deffn +@node Archive file names +@section Archive file names +@cindex file archives +@cindex archive file names +@cindex method archive +@cindex archive method + +@value{tramp} offers also transparent access to files inside file +archives. This is possible only on machines which have installed the +virtual file system for the @acronym{GNOME} Desktop (GVFS), @ref{GVFS +based methods}. Internally, file archives are mounted via the GVFS +@option{archive} method. + +A file archive is a regular file of kind @file{/path/to/dir/file.EXT}. +The extension @samp{.EXT} identifies the type of the file archive. A +file inside a file archive, called archive file name, has the name +@file{/path/to/dir/file.EXT/dir/file}. + +Most of the @ref{Magic File Names, , magic file name operations, +elisp}, are implemented for archive file names, exceptions are all +operations which write into a file archive, and process related +operations. Therefore, functions like + +@lisp +(copy-file "/path/to/dir/file.tar/dir/file" "/somewhere/else") +@end lisp + +@noindent +work out of the box. This is also true for file name completion, and +for libraries like @code{dired} or @code{ediff}, which accept archive +file names as well. + +@vindex tramp-archive-suffixes +File archives are identified by the file name extension @samp{.EXT}. +Since GVFS uses internally the library @code{libarchive(3)}, all +suffixes, which are accepted by this library, work also for archive +file names. Accepted suffixes are listed in the constant +@code{tramp-archive-suffixes}. They are + +@itemize +@item @samp{.7z} --- +7-Zip archives +@cindex @file{7z} file archive suffix +@cindex file archive suffix @file{7z} + +@item @samp{.apk} --- +Android package kits +@cindex @file{apk} file archive suffix +@cindex file archive suffix @file{apk} + +@item @samp{.ar} --- +UNIX archiver formats +@cindex @file{ar} file archive suffix +@cindex file archive suffix @file{ar} + +@item @samp{.cab}, @samp{.CAB} --- +Microsoft Windows cabinets +@cindex @file{cab} file archive suffix +@cindex @file{CAB} file archive suffix +@cindex file archive suffix @file{cab} +@cindex file archive suffix @file{CAB} + +@item @samp{.cpio} --- +CPIO archives +@cindex @file{cpio} file archive suffix +@cindex file archive suffix @file{cpio} + +@item @samp{.deb} --- +Debian packages +@cindex @file{deb} file archive suffix +@cindex file archive suffix @file{deb} + +@item @samp{.depot} --- +HP-UX SD depots +@cindex @file{depot} file archive suffix +@cindex file archive suffix @file{depot} + +@item @samp{.exe} --- +Self extracting Microsoft Windows EXE files +@cindex @file{exe} file archive suffix +@cindex file archive suffix @file{exe} + +@item @samp{.iso} --- +ISO 9660 images +@cindex @file{iso} file archive suffix +@cindex file archive suffix @file{iso} + +@item @samp{.jar} --- +Java archives +@cindex @file{jar} file archive suffix +@cindex file archive suffix @file{jar} + +@item @samp{.lzh}, @samp{.LZH} --- +Microsoft Windows compressed LHA archives +@cindex @file{lzh} file archive suffix +@cindex @file{LZH} file archive suffix +@cindex file archive suffix @file{lzh} +@cindex file archive suffix @file{LZH} + +@item @samp{.msu}, @samp{.MSU} --- +Microsoft Windows Update packages +@cindex @file{msu} file archive suffix +@cindex @file{MSU} file archive suffix +@cindex file archive suffix @file{msu} +@cindex file archive suffix @file{MSU} + +@item @samp{.mtree} --- +BSD mtree format +@cindex @file{mtree} file archive suffix +@cindex file archive suffix @file{mtree} + +@item @samp{.odb}, @samp{.odf}, @samp{.odg}, @samp{.odp}, @samp{.ods}, +@samp{.odt} --- +OpenDocument formats +@cindex @file{odb} file archive suffix +@cindex @file{odf} file archive suffix +@cindex @file{odg} file archive suffix +@cindex @file{odp} file archive suffix +@cindex @file{ods} file archive suffix +@cindex @file{odt} file archive suffix +@cindex file archive suffix @file{odb} +@cindex file archive suffix @file{odf} +@cindex file archive suffix @file{odg} +@cindex file archive suffix @file{odp} +@cindex file archive suffix @file{ods} +@cindex file archive suffix @file{odt} + +@item @samp{.pax} --- +Posix archives +@cindex @file{pax} file archive suffix +@cindex file archive suffix @file{pax} + +@item @samp{.rar} --- +RAR archives +@cindex @file{rar} file archive suffix +@cindex file archive suffix @file{rar} + +@item @samp{.rpm} --- +Red Hat packages +@cindex @file{rpm} file archive suffix +@cindex file archive suffix @file{rpm} + +@item @samp{.shar} --- +Shell archives +@cindex @file{shar} file archive suffix +@cindex file archive suffix @file{shar} + +@item @samp{.tar}, @samp{.tbz}, @samp{.tgz}, @samp{.tlz}, @samp{.txz}, +@samp{.tzst} --- +(Compressed) tape archives +@cindex @file{tar} file archive suffix +@cindex @file{tbz} file archive suffix +@cindex @file{tgz} file archive suffix +@cindex @file{tlz} file archive suffix +@cindex @file{txz} file archive suffix +@cindex @file{tzst} file archive suffix +@cindex file archive suffix @file{tar} +@cindex file archive suffix @file{tbz} +@cindex file archive suffix @file{tgz} +@cindex file archive suffix @file{tlz} +@cindex file archive suffix @file{txz} +@cindex file archive suffix @file{tzst} + +@item @samp{.warc} --- +Web archives +@cindex @file{warc} file archive suffix +@cindex file archive suffix @file{warc} + +@item @samp{.xar} --- +macOS XAR archives +@cindex @file{xar} file archive suffix +@cindex file archive suffix @file{xar} + +@item @samp{.xpi} --- +XPInstall Mozilla addons +@cindex @file{xpi} file archive suffix +@cindex file archive suffix @file{xpi} + +@item @samp{.xps} --- +Open XML Paper Specification (OpenXPS) documents +@cindex @file{xps} file archive suffix +@cindex file archive suffix @file{xps} + +@item @samp{.zip}, @samp{.ZIP} --- +ZIP archives +@cindex @file{zip} file archive suffix +@cindex @file{ZIP} file archive suffix +@cindex file archive suffix @file{zip} +@cindex file archive suffix @file{ZIP} +@end itemize + +@vindex tramp-archive-compression-suffixes +File archives could also be compressed, identified by an additional +compression suffix. Valid compression suffixes are listed in the +constant @code{tramp-archive-compression-suffixes}. They are +@samp{.bz2}, @samp{.gz}, @samp{.lrz}, @samp{.lz}, @samp{.lz4}, +@samp{.lzma}, @samp{.lzo}, @samp{.uu}, @samp{.xz}, @samp{.Z}, and +@samp{.zst}. A valid archive file name would be +@file{/path/to/dir/file.tar.gz/dir/file}. Even several suffixes in a +row are possible, like @file{/path/to/dir/file.tar.gz.uu/dir/file}. + +@vindex tramp-archive-all-gvfs-methods +An archive file name could be a remote file name, as in +@file{/ftp:anonymous@@ftp.gnu.org:/gnu/tramp/tramp-2.3.2.tar.gz/INSTALL}. +Since all file operations are mapped internally to GVFS operations, +remote file names supported by @code{tramp-gvfs} perform better, +because no local copy of the file archive must be downloaded first. +For example, @samp{/sftp:user@@host:...} performs better than the +similar @samp{/scp:user@@host:...}. See the constant +@code{tramp-archive-all-gvfs-methods} for a complete list of +@code{tramp-gvfs} supported method names. + +If @code{url-handler-mode} is enabled, archives could be visited via +URLs, like +@file{https://ftp.gnu.org/gnu/tramp/tramp-2.3.2.tar.gz/INSTALL}. This +allows complex file operations like + +@lisp +@group +(progn + (url-handler-mode 1) + (ediff-directories + "https://ftp.gnu.org/gnu/tramp/tramp-2.3.1.tar.gz/tramp-2.3.1" + "https://ftp.gnu.org/gnu/tramp/tramp-2.3.2.tar.gz/tramp-2.3.2" "")) +@end group +@end lisp + +It is even possible to access file archives in file archives, as + +@lisp +@group +(progn + (url-handler-mode 1) + (find-file + "http://ftp.debian.org/debian/pool/main/c/coreutils/coreutils_8.28-1_amd64.deb/control.tar.gz/control")) +@end group +@end lisp + + @node Bug Reports @chapter Reporting Bugs and Problems @cindex bug reports @@ -3007,9 +3548,9 @@ discussing, and general discussions about @value{tramp}. post for moderator approval. Sometimes this approval step may take as long as 48 hours due to public holidays. -@email{tramp-devel@@gnu.org} is the mailing list. Messages sent to -this address go to all the subscribers. This is @emph{not} the -address to send subscription requests to. +@email{@value{tramp-bug-report-address}} is the mailing list. +Messages sent to this address go to all the subscribers. This is +@emph{not} the address to send subscription requests to. To subscribe to the mailing list, visit: @uref{https://lists.gnu.org/mailman/listinfo/tramp-devel/, the @@ -3043,7 +3584,9 @@ When including @value{tramp}'s messages in the bug report, increase the verbosity level to 6 (@pxref{Traces and Profiles, Traces}) in the @file{~/.emacs} file before repeating steps to the bug. Include the contents of the @file{*tramp/foo*} and @file{*debug tramp/foo*} -buffers with the bug report. +buffers with the bug report. Both buffers could contain +non-@acronym{ASCII} characters which are relevant for analysis, append +the buffers as attachments to the bug report. @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 @@ -3076,7 +3619,8 @@ Where is the latest @value{tramp}? @item Which systems does it work on? -The package works successfully on Emacs 24, Emacs 25, and Emacs 26. +The package works successfully on Emacs 24, Emacs 25, Emacs 26, and +Emacs 27. While Unix and Unix-like systems are the primary remote targets, @value{tramp} has equal success connecting to other platforms, such as @@ -3099,6 +3643,7 @@ Keep the file @code{tramp-persistency-file-name}, which is where @value{tramp} caches remote information about hosts and files. Caching is enabled by default. Don't disable it. +@vindex remote-file-name-inhibit-cache Set @code{remote-file-name-inhibit-cache} to @code{nil} if remote files are not independently updated outside @value{tramp}'s control. That cache cleanup will be necessary if the remote directories or @@ -3235,7 +3780,7 @@ Set @code{file-precious-flag} to @code{t} for files accessed by @value{tramp} so the file contents are checked using checksum by first saving to a temporary file. @ifinfo -@pxref{Saving Buffers, , , elisp} +@pxref{Saving Buffers, , , elisp}. @end ifinfo @lisp @@ -3251,6 +3796,16 @@ first saving to a temporary file. @item +@value{tramp} fails in a chrooted environment + +@vindex tramp-local-host-regexp +When connecting to a local host, @value{tramp} uses some internal +optimizations. They fail, when there is a chrooted environment. In +order to disable those optimizations, set user option +@code{tramp-local-host-regexp} to @code{nil}. + + +@item @value{tramp} does not recognize if a @command{ssh} session hangs @command{ssh} sessions on the local host hang when the network is @@ -3765,6 +4320,15 @@ export EDITOR=/path/to/emacsclient.sh @item +How to determine whether a buffer is remote? + +The buffer-local variable @code{default-directory} tells this. If the +form @code{(file-remote-p default-directory)} returns non-@code{nil}, +the buffer is remote. See the optional arguments of +@code{file-remote-p} for determining details of the remote connection. + + +@item How to disable other packages from calling @value{tramp}? There are packages that call @value{tramp} without the user ever @@ -3806,6 +4370,7 @@ in @file{.emacs}: @end lisp @item +@vindex tramp-mode To disable both @value{tramp} (and Ange FTP), set @code{tramp-mode} to @code{nil} in @file{.emacs}. @strong{Note}, that we don't use @code{customize-set-variable}, in order to avoid loading @value{tramp}. @@ -3815,6 +4380,21 @@ To disable both @value{tramp} (and Ange FTP), set @code{tramp-mode} to @end lisp @item +@vindex tramp-ignored-file-name-regexp +To deactivate @value{tramp} for some look-alike remote file names, set +@code{tramp-ignored-file-name-regexp} to a proper regexp in +@file{.emacs}. @strong{Note}, that we don't use +@code{customize-set-variable}, in order to avoid loading +@value{tramp}. + +@lisp +(setq tramp-ignored-file-name-regexp "\\`/ssh:example\\.com:") +@end lisp + +This is needed, if you mount for example a virtual file system on your +local host's root directory as @file{/ssh:example.com:}. + +@item To unload @value{tramp}, type @kbd{M-x tramp-unload-tramp @key{RET}}. Unloading @value{tramp} resets Ange FTP plugins also. @end itemize @@ -3823,7 +4403,7 @@ Unloading @value{tramp} resets Ange FTP plugins also. @c For the developer @node Files directories and localnames -@chapter How file names, directories and localnames are mangled and managed. +@chapter How file names, directories and localnames are mangled and managed @menu * Localname deconstruction:: Splitting a localname into its component parts. @@ -3849,9 +4429,10 @@ handlers. @section Integrating with external Lisp packages @subsection File name completion. +@vindex non-essential Sometimes, it is not convenient to open a new connection to a remote host, including entering the password and alike. For example, this is -nasty for packages providing file name completion. Such a package +nasty for packages providing file name completion. Such a package could signal to @value{tramp}, that they don't want it to establish a new connection. Use the variable @code{non-essential} temporarily and bind it to non-@code{nil} value. @@ -3906,6 +4487,7 @@ root-directory, it is most likely sufficient to make the @node Traces and Profiles @chapter How to Customize Traces +@vindex tramp-verbose @value{tramp} messages are raised with verbosity levels ranging from 0 to 10. @value{tramp} does not display all messages; only those with a diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index aecbbe261c8..5b1408a4974 100644 --- a/doc/misc/trampver.texi +++ b/doc/misc/trampver.texi @@ -5,12 +5,12 @@ @c Copyright (C) 2003-2019 Free Software Foundation, Inc. @c See file doclicense.texi for copying conditions. -@c In the Tramp GIT, the version number is auto-frobbed from -@c configure.ac, so you should edit that file and run -@c "autoconf && ./configure" to change the version number. -@set trampver 2.3.4.26.2 +@c In the Tramp GIT, the version number is auto-frobbed from tramp.el, +@c and the bug report address is auto-frobbed from configure.ac. +@set trampver 2.4.2-pre +@set tramp-bug-report-address tramp-devel@@gnu.org -@c Other flags from configuration +@c Other flags from configuration. @set instprefix /usr/local @set lispdir /usr/local/share/emacs/site-lisp @set infodir /usr/local/share/info @@ -44,3 +44,17 @@ @set ipv6prefix @set ipv6postfix @end ifset + +@c Macro for formatting a file name according to the respective +@c syntax. trampver.texi is included several times in tramp.texi and +@c trampinst.texi. Redefining the macro is reported as warning for +@c creating the dvi and pdf files, so we declare the macro only the +@c first time this file is included. +@ifclear trampfndefined +@set trampfndefined +@macro trampfn {method, userhost, localname} +@value{prefix}@c +\method\@value{postfixhop}@c +\userhost\@value{postfix}\localname\ +@end macro +@end ifclear diff --git a/doc/misc/url.texi b/doc/misc/url.texi index b190c58c023..0cdfcac24e8 100644 --- a/doc/misc/url.texi +++ b/doc/misc/url.texi @@ -571,13 +571,6 @@ if it has the file suffix @file{.z}, @file{.gz}, @file{.Z}, hard-coded, and cannot be altered by customizing @code{jka-compr-compression-info-list}.) -@defopt url-directory-index-file -This option specifies the filename to look for when a @code{file} or -@code{ftp} URL specifies a directory. The default is -@file{index.html}. If this file exists and is readable, it is viewed. -Otherwise, Emacs visits the directory using Dired. -@end defopt - @node info @section info @cindex Info @@ -1291,6 +1284,20 @@ It may also be a list of the types of messages to be logged. @end defopt @defopt url-privacy-level @end defopt +@defopt url-lastloc-privacy-level +Provided @code{lastloc} is not prohibited by @code{url-privacy-level}, +this determines who we send our last location to. @code{none} means +we include our last location in every outgoing request. +@code{domain-match} means we send it only if the domain of our last +location matches the domain of the URI we are requesting. +@code{host-match} means we only send our last location back to the +same host. The default is @code{domain-match}. + +Using @code{domain-match} for this option requires emacs to make one +or more DNS requests each time a new host is contacted, to determine +the domain of the host. Results of these lookups are cached, so +repeated visits do not require repeated domain lookups. +@end defopt @defopt url-uncompressor-alist @end defopt @defopt url-passwd-entry-func |