diff options
Diffstat (limited to 'doc')
199 files changed, 4497 insertions, 2525 deletions
diff --git a/doc/emacs/ChangeLog.1 b/doc/emacs/ChangeLog.1 index 26a0d3e9f9d..b9f7e49fc91 100644 --- a/doc/emacs/ChangeLog.1 +++ b/doc/emacs/ChangeLog.1 @@ -83,7 +83,7 @@ 2014-12-08 Eric S. Raymond <esr@snark.thyrsus.com> - * maintaining.texi: Suopport fo Arch has been moved to obosolete, + * maintaining.texi: Support for Arch has been moved to obsolete, remove references that imply otherwise. 2014-11-29 Paul Eggert <eggert@cs.ucla.edu> @@ -10919,7 +10919,7 @@ ;; coding: utf-8 ;; End: - Copyright (C) 1993-1999, 2001-2018 Free Software Foundation, Inc. + Copyright (C) 1993-1999, 2001-2019 Free Software Foundation, Inc. This file is part of GNU Emacs. diff --git a/doc/emacs/Makefile.in b/doc/emacs/Makefile.in index 54e173f8d67..01c6700197c 100644 --- a/doc/emacs/Makefile.in +++ b/doc/emacs/Makefile.in @@ -1,6 +1,6 @@ ### @configure_input@ -# Copyright (C) 1994, 1996-2018 Free Software Foundation, Inc. +# Copyright (C) 1994, 1996-2019 Free Software Foundation, Inc. # This file is part of GNU Emacs. diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi index 00b9e560ac0..9c8a280efb3 100644 --- a/doc/emacs/abbrevs.texi +++ b/doc/emacs/abbrevs.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Abbrevs diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi index 20c8d4e610b..0e4a982da40 100644 --- a/doc/emacs/ack.texi +++ b/doc/emacs/ack.texi @@ -1,6 +1,6 @@ @c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1994-1997, 1999-2018 Free Software Foundation, Inc. +@c Copyright (C) 1994-1997, 1999-2019 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @node Acknowledgments @@ -829,8 +829,8 @@ command with its arguments. Richard Mlynarik wrote @file{cl-indent.el}, a package for indenting Common Lisp code; @file{ebuff-menu.el}, an electric browser for buffer listings; @file{ehelp.el}, bindings for browsing help screens; -and @file{rfc822.el}, a parser for E-mail addresses in the RFC-822 format, -used in mail messages and news articles. +and @file{rfc822.el}, a parser for E-mail addresses in the format +used in mail messages and news articles (Internet RFC 822 and its successors). @item Gerd Möllmann was the Emacs maintainer from the beginning of Emacs 21 diff --git a/doc/emacs/anti.texi b/doc/emacs/anti.texi index b91516315ad..9eac08c2643 100644 --- a/doc/emacs/anti.texi +++ b/doc/emacs/anti.texi @@ -1,6 +1,6 @@ @c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 2005-2018 Free Software Foundation, Inc. +@c Copyright (C) 2005-2019 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Antinews diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi index 45fca1f508d..cd7c1ff895e 100644 --- a/doc/emacs/arevert-xtra.texi +++ b/doc/emacs/arevert-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2018 Free Software Foundation, Inc. +@c Copyright (C) 2004-2019 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in emacs-xtra.texi (when producing the diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi index f911c673bff..86403b7a23d 100644 --- a/doc/emacs/basic.texi +++ b/doc/emacs/basic.texi @@ -1,6 +1,6 @@ @c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Basic diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi index dd7a653186c..27fcb7369a9 100644 --- a/doc/emacs/buffers.texi +++ b/doc/emacs/buffers.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Buffers diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index 496c4275bc2..78d07b8d39e 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Building @@ -934,6 +934,7 @@ height and width values during the debugging session. @cindex GDB User Interface layout @vindex gdb-many-windows +@vindex gdb-show-main If the variable @code{gdb-many-windows} is @code{nil} (the default), @kbd{M-x gdb} normally displays only the GUD interaction buffer. However, if the variable @code{gdb-show-main} is also non-@code{nil}, @@ -1033,6 +1034,15 @@ allows you to go backwards, which can be useful for running through code that has already executed, in order to examine its execution in more detail. +@vindex gdb-mi-decode-strings + If the file names of the source files are shown with octal escapes, +set the variable @code{gdb-mi-decode-strings} to the appropriate +coding-system, most probably @code{utf-8}. (This is @code{nil} by +default because GDB may emit octal escapes in situations where +decoding is undesirable, and also because the program being debugged +might use an encoding different from the one used to encode non-ASCII +file names on your system.) + @node Breakpoints Buffer @subsubsection Breakpoints Buffer @@ -1172,6 +1182,11 @@ also updates the Locals buffer (described in the next section). @end iftex +@vindex gdb-stack-buffer-addresses + If you want the frame address to be shown each stack frame, +customize the variable @code{gdb-stack-buffer-addresses} to a +non-@code{nil} value. + @node Other GDB Buffers @subsubsection Other GDB Buffers diff --git a/doc/emacs/cal-xtra.texi b/doc/emacs/cal-xtra.texi index 80e9b851817..7fa20deac04 100644 --- a/doc/emacs/cal-xtra.texi +++ b/doc/emacs/cal-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -*- coding: utf-8 -*- -@c Copyright (C) 2004-2018 Free Software Foundation, Inc. +@c Copyright (C) 2004-2019 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in emacs-xtra.texi (when producing the diff --git a/doc/emacs/calendar.texi b/doc/emacs/calendar.texi index 7021146e698..138a24fd459 100644 --- a/doc/emacs/calendar.texi +++ b/doc/emacs/calendar.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -*- coding: utf-8 -*- -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Calendar/Diary diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi index 2e2767ccada..00d5be70eb2 100644 --- a/doc/emacs/cmdargs.texi +++ b/doc/emacs/cmdargs.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Emacs Invocation @@ -383,6 +383,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 @@ -528,12 +543,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 @@ -1029,7 +1049,7 @@ specifies a window 164 columns wide, enough for two ordinary width windows side by side, and 55 lines tall. The default frame width is 80 characters and the default height is -40 lines. You can omit either the width or the height or both. If +36 lines. You can omit either the width or the height or both. If you start the geometry with an integer, Emacs interprets it as the width. If you start with an @samp{x} followed by an integer, Emacs interprets it as the height. Thus, @samp{81} specifies just the diff --git a/doc/emacs/commands.texi b/doc/emacs/commands.texi index a992dedc929..4773d7675bd 100644 --- a/doc/emacs/commands.texi +++ b/doc/emacs/commands.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @iftex diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index ddde5b22e6b..c649c170293 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -1,6 +1,6 @@ @c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Customization @@ -32,6 +32,8 @@ Reference Manual}. By changing them, you can redefine keys. * Init File:: How to write common customizations in the initialization file. +* Authentication:: Keeping persistent authentication information. + @end menu @node Easy Customization @@ -763,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 @@ -1419,6 +1423,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 @@ -2557,10 +2607,9 @@ 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 + Normally Emacs uses your home directory to find @file{~/.emacs}; +that's what @samp{~} means in a file name. @xref{General Variables, HOME}. +If neither @file{~/.emacs} nor @file{~/.emacs.el} is found, Emacs looks for @file{~/.emacs.d/init.el} (which, like @file{~/.emacs.el}, can be byte-compiled). @@ -2640,3 +2689,40 @@ provided by the Emacs startup, such as @code{window-setup-hook} or For more information on the early init file, @pxref{Init File,,, elisp, The Emacs Lisp Reference Manual}. + +@node Authentication +@section Keeping Persistent Authentication Information + + Some Emacs packages, which connect to other services, require +authentication (@pxref{Passwords}), e.g., see @ref{Top, Gnus,, gnus, The +Gnus Manual}, or @ref{Top, Tramp,, tramp, The Tramp Manual}. Because +it might be annoying to provide the same user name and password again +and again, Emacs offers to keep this information persistent via the +@file{auth-source} library. + +@cindex @file{~/.authinfo} file +@cindex @file{~/.authinfo.gpg} file +@cindex ~/.netrc file + By default, the authentication information is taken from the file +@file{~/.authinfo} or @file{~/.authinfo.gpg} or @file{~/.netrc}. +These files have a syntax similar to netrc files as known from the +@command{ftp} program, like this: + +@example +machine @var{mymachine} login @var{myloginname} password @var{mypassword} port @var{myport} +@end example + + Similarly, the @file{auth-source} library supports multiple storage +backend, currently either the classic netrc backend, JSON files, the +Secret Service API, and pass, the standard unix password manager. + +@vindex auth-sources + All these alternatives can be customized via the user option +@code{auth-sources}, see @ref{Help for users, Emacs auth-source,, +auth, Emacs auth-source}. + +@vindex auth-source-save-behavior + When a password is entered interactively, which is not found via the +configured backend, some of the backends offer to save it +persistently. This can be changed by customizing the user option +@code{auth-source-save-behavior}. diff --git a/doc/emacs/dired-xtra.texi b/doc/emacs/dired-xtra.texi index 4412e475711..025da21478a 100644 --- a/doc/emacs/dired-xtra.texi +++ b/doc/emacs/dired-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2018 Free Software Foundation, Inc. +@c Copyright (C) 2004-2019 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in emacs-xtra.texi (when producing the diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi index 1b03a3967aa..9f454ea2ad6 100644 --- a/doc/emacs/dired.texi +++ b/doc/emacs/dired.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Dired @@ -779,9 +779,15 @@ suitable guess made using the variables @code{lpr-command} and @item Z Compress the specified files (@code{dired-do-compress}). If the file appears to be a compressed file already, uncompress it instead. Each -marked file is compressed into its own archive. This uses the +marked file is compressed into its own archive; this uses the @command{gzip} program if it is available, otherwise it uses -@command{compress}. +@command{compress}. On a directory name, this command produces a +compressed @file{.tar.gz} archive containing all of the directory's +files, by running the @command{tar} command with output piped to +@command{gzip}. To allow decompression of compressed directories, +typing @kbd{Z} on a @file{.tar.gz} or @file{.tgz} archive file unpacks +all the files in the archive into a directory whose name is the +archive name with the extension removed. @findex dired-do-compress-to @kindex c @r{(Dired)} diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index d9a08b974f6..f464a3a59f0 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -1,6 +1,6 @@ @c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. diff --git a/doc/emacs/emacs-xtra.texi b/doc/emacs/emacs-xtra.texi index 3c46d72f040..dcd8fae1b61 100644 --- a/doc/emacs/emacs-xtra.texi +++ b/doc/emacs/emacs-xtra.texi @@ -16,7 +16,7 @@ @copying This manual describes specialized features of Emacs. -Copyright @copyright{} 2004--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2004--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index b64a59df707..7edc1a5fae1 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -27,7 +27,7 @@ This is the @cite{GNU Emacs Manual}, @end ifnottex updated for Emacs version @value{EMACSVER}. -Copyright @copyright{} 1985--1987, 1993--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1985--1987, 1993--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -1114,6 +1114,7 @@ Customization By changing them, you can redefine keys. * Init File:: How to write common customizations in the initialization file. +* Authentication:: Keeping persistent authentication information. Easy Customization Interface @@ -1134,6 +1135,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 diff --git a/doc/emacs/emerge-xtra.texi b/doc/emacs/emerge-xtra.texi index 1d817125b36..6c5e46b6de6 100644 --- a/doc/emacs/emerge-xtra.texi +++ b/doc/emacs/emerge-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2018 Free Software Foundation, Inc. +@c Copyright (C) 2004-2019 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in emacs-xtra.texi (when producing the diff --git a/doc/emacs/entering.texi b/doc/emacs/entering.texi index 84b3e5d4cbf..4362553a223 100644 --- a/doc/emacs/entering.texi +++ b/doc/emacs/entering.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 2001-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 2001-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @iftex diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 6c68075ae4a..a57428230cc 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Files @@ -1427,23 +1427,30 @@ manually, type @kbd{M-x diff-mode}. @cindex hunk, diff The changes specified in a patch are grouped into @dfn{hunks}, which are contiguous chunks of text that contain one or more changed lines. -Hunks can also include unchanged lines to provide context for the +Hunks usually also include unchanged lines to provide context for the changes. Each hunk is preceded by a @dfn{hunk header}, which -specifies the old and new line numbers at which the hunk occurs. Diff -mode highlights each hunk header, to distinguish it from the actual -contents of the hunk. +specifies the old and new line numbers where the hunk's changes occur. +Diff mode highlights each hunk header, to distinguish it from the +actual contents of the hunk. + + The first hunk in a patch is preceded by a file header, which shows +the names of the new and the old versions of the file, and their time +stamps. If a patch shows changes for more than one file, each file +has such a header before the first hunk of that file's changes. @vindex diff-update-on-the-fly You can edit a Diff mode buffer like any other buffer. (If it is -read-only, you need to make it writable first. @xref{Misc Buffer}.) -Whenever you change a hunk, Diff mode attempts to automatically -correct the line numbers in the hunk headers, to ensure that the patch -remains correct. To disable automatic line number correction, -change the variable @code{diff-update-on-the-fly} to @code{nil}. - - Diff mode treats each hunk as an error message, similar to -Compilation mode. Thus, you can use commands such as @kbd{M-g M-n} to -visit the corresponding source locations. @xref{Compilation Mode}. +read-only, you need to make it writable first; see @ref{Misc Buffer}.) +Whenever you edit a hunk, Diff mode attempts to automatically correct +the line numbers in the hunk headers, to ensure that the patch remains +correct, and could still be applied by @command{patch}. To disable +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{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. In addition, Diff mode provides the following commands to navigate, manipulate and apply parts of patches: @@ -1451,37 +1458,34 @@ manipulate and apply parts of patches: @table @kbd @item M-n @findex diff-hunk-next -Move to the next hunk-start (@code{diff-hunk-next}). +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}). Like -@kbd{M-n}, this has the side-effect of refining the hunk you move to, -unless you disable Diff Auto-Refine mode. +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 command refines the hunk you move to if you set +@code{diff-refine} to the symbol @code{navigation}. @item M-@} @findex diff-file-next Move to the next file-start, in a multi-file patch -(@code{diff-file-next}). +(@code{diff-file-next}). With prefix argument @var{n}, move forward +to the start of the @var{n}th next file. @item M-@{ @findex diff-file-prev Move to the previous file-start, in a multi-file patch -(@code{diff-file-prev}). +(@code{diff-file-prev}). With prefix argument @var{n}, move back to +the start of the @var{n}th previous file. @item M-k @findex diff-hunk-kill @@ -1496,7 +1500,10 @@ In a multi-file patch, kill the current file part. @findex diff-apply-hunk @cindex patches, applying Apply this hunk to its target file (@code{diff-apply-hunk}). With a -prefix argument of @kbd{C-u}, revert this hunk. +prefix argument of @kbd{C-u}, revert this hunk, i.e.@: apply the +reverse of the hunk, which changes the ``new'' version into the ``old'' +version. If @code{diff-jump-to-old-file} is non-@code{nil}, apply the +hunk to the ``old'' version of the file instead. @item C-c C-b @findex diff-refine-hunk @@ -1504,10 +1511,27 @@ 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 Go to the source file and line corresponding to this hunk -(@code{diff-goto-source}). +(@code{diff-goto-source}). By default, this jumps to the ``new'' +version of the file, the one shown first on the file header. +With a prefix argument, jump to the ``old'' version instead. If +@code{diff-jump-to-old-file} is non-@code{nil}, this command by +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 @@ -1517,41 +1541,47 @@ Start an Ediff session with the patch (@code{diff-ediff-patch}). @item C-c C-n @findex diff-restrict-view Restrict the view to the current hunk (@code{diff-restrict-view}). -@xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the +@xref{Narrowing}. With a prefix argument, restrict the view to the current file of a multiple-file patch. To widen again, use @kbd{C-x n w} (@code{widen}). @item C-c C-r @findex diff-reverse-direction Reverse the direction of comparison for the entire buffer -(@code{diff-reverse-direction}). +(@code{diff-reverse-direction}). With a prefix argument, reverse the +direction only inside the current region (@pxref{Mark}). Reversing +the direction means changing the hunks and the file-start headers to +produce a patch that would change the ``new'' version into the ``old'' +one. @item C-c C-s @findex diff-split-hunk -Split the hunk at point (@code{diff-split-hunk}). This is for -manually editing patches, and only works with the @dfn{unified diff -format} produced by the @option{-u} or @option{--unified} options to -the @command{diff} program. If you need to split a hunk in the -@dfn{context diff format} produced by the @option{-c} or -@option{--context} options to @command{diff}, first convert the buffer -to the unified diff format with @kbd{C-c C-u}. +Split the hunk at point (@code{diff-split-hunk}) into two separate +hunks. This inserts a hunk header and modifies the header of the +current hunk. This command is useful for manually editing patches, +and only works with the @dfn{unified diff format} produced by the +@option{-u} or @option{--unified} options to the @command{diff} +program. If you need to split a hunk in the @dfn{context diff format} +produced by the @option{-c} or @option{--context} options to +@command{diff}, first convert the buffer to the unified diff format +with @kbd{C-c C-u}. @item C-c C-d @findex diff-unified->context Convert the entire buffer to the @dfn{context diff format} (@code{diff-unified->context}). With a prefix argument, convert only -the text within the region. +the hunks within the region. @item C-c C-u @findex diff-context->unified Convert the entire buffer to unified diff format (@code{diff-context->unified}). With a prefix argument, convert unified format to context format. When the mark is active, convert -only the text within the region. +only the hunks within the region. @item C-c C-w @findex diff-ignore-whitespace-hunk -Re-diff the current hunk, disregarding changes in whitespace +Re-generate the current hunk, disregarding changes in whitespace (@code{diff-ignore-whitespace-hunk}). @item C-x 4 A @@ -1582,7 +1612,12 @@ that whitespace in both the patch and the patched source file(s). This command does not save the modifications that it makes, so you can decide whether to save the changes (the list of modified files is displayed in the echo area). With a prefix argument, it tries to -modify the original source files rather than the patched source files. +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 @@ -1668,10 +1703,12 @@ Dired rather than @code{delete-file}. @xref{Dired Deletion}. @cindex trash @cindex recycle bin +@findex move-file-to-trash @kbd{M-x move-file-to-trash} moves a file into the system @dfn{Trash} (or @dfn{Recycle Bin}). This is a facility available on most operating systems; files that are moved into the Trash can be -brought back later if you change your mind. +brought back later if you change your mind. (The way to restore +trashed files is system-dependent.) @vindex delete-by-moving-to-trash By default, Emacs deletion commands do @emph{not} use the Trash. To diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi index 8277278f521..fc610583c87 100644 --- a/doc/emacs/fixit.texi +++ b/doc/emacs/fixit.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Fixit diff --git a/doc/emacs/fortran-xtra.texi b/doc/emacs/fortran-xtra.texi index fa5a3e6eafb..30f7c421d51 100644 --- a/doc/emacs/fortran-xtra.texi +++ b/doc/emacs/fortran-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2018 Free Software Foundation, Inc. +@c Copyright (C) 2004-2019 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in emacs-xtra.texi (when producing the diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index 6bbaae24b17..6001096f35b 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Frames @@ -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/glossary.texi b/doc/emacs/glossary.texi index 02939679fef..ad16d72ddbf 100644 --- a/doc/emacs/glossary.texi +++ b/doc/emacs/glossary.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Glossary diff --git a/doc/emacs/gnu.texi b/doc/emacs/gnu.texi index 4a42a641a72..fef4f71c6ee 100644 --- a/doc/emacs/gnu.texi +++ b/doc/emacs/gnu.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1985-1987, 1993, 1995, 2001-2018 Free Software +@c Copyright (C) 1985-1987, 1993, 1995, 2001-2019 Free Software @c Foundation, Inc. @c @c Permission is granted to anyone to make or distribute verbatim copies diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index 66673eb2337..4851659b8b7 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Help diff --git a/doc/emacs/indent.texi b/doc/emacs/indent.texi index bf43909edf3..5f40acba151 100644 --- a/doc/emacs/indent.texi +++ b/doc/emacs/indent.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Indentation @@ -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/killing.texi b/doc/emacs/killing.texi index 4c47c8b0479..2d56f1d26e1 100644 --- a/doc/emacs/killing.texi +++ b/doc/emacs/killing.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. diff --git a/doc/emacs/kmacro.texi b/doc/emacs/kmacro.texi index 0151c816a89..65387ae783c 100644 --- a/doc/emacs/kmacro.texi +++ b/doc/emacs/kmacro.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Keyboard Macros @@ -241,10 +241,17 @@ determined by the customizable variable @code{kmacro-ring-max}. @section The Keyboard Macro Counter Each keyboard macro has an associated counter, which is initialized -to 0 when you start defining the macro. This counter allows you to -insert a number into the buffer that depends on the number of times -the macro has been called. The counter is incremented each time its -value is inserted into the buffer. +to 0 when you start defining the macro. This @dfn{current counter} +allows you to insert a number into the buffer that depends on the +number of times the macro has been called. The counter is normally +incremented each time its value is inserted into the buffer. + +In addition to the current counter, keyboard macros also maintain the +@dfn{previous counter}, which records the value the current counter +had last time it was incremented or set. Note that incrementing the +current counter by zero, e.g., with @w{@kbd{C-u 0 C-x C-k C-i}}, also +records the value of the current counter as the previous counter +value. @table @kbd @item @key{F3} @@ -270,8 +277,8 @@ value of the keyboard macro's counter into the buffer, and increments the counter by 1. (If you are not defining a macro, @key{F3} begins a macro definition instead. @xref{Basic Keyboard Macro}.) You can use a numeric prefix argument to specify a different increment. If you -just specify a @kbd{C-u} prefix, that is the same as an increment of -zero: it inserts the current counter value without changing it. +just specify a @kbd{C-u} prefix, that inserts the previous counter +value, and doesn't change the current value. As an example, let us show how the keyboard macro counter can be used to build a numbered list. Consider the following key sequence: diff --git a/doc/emacs/m-x.texi b/doc/emacs/m-x.texi index adf46ff19d7..2b2be38cb37 100644 --- a/doc/emacs/m-x.texi +++ b/doc/emacs/m-x.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node M-x diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi index 34b645dbc17..d9920957ad7 100644 --- a/doc/emacs/macos.texi +++ b/doc/emacs/macos.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2000-2018 Free Software Foundation, Inc. +@c Copyright (C) 2000-2019 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Mac OS / GNUstep @appendix Emacs and macOS / GNUstep @@ -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 4527c23d9e7..fd0119e98ce 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual., Abbrevs, This is part of the Emacs manual., Top -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Maintaining @@ -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 @@ -1981,7 +1990,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 multifile-continue +@item M-x fileloop-continue Restart one of the last 2 commands above, from the current location of point. @end table @@ -2017,9 +2026,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 multifile-continue +@findex fileloop-continue Having found one match with @code{tags-search}, you probably want to -find all the rest. @kbd{M-x multifile-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. @@ -2042,10 +2051,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 multifile-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 multifile-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 diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi index 626f9dda25f..aa753888e5f 100644 --- a/doc/emacs/mark.texi +++ b/doc/emacs/mark.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Mark diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi index 6fc28903fc7..820d3baad13 100644 --- a/doc/emacs/mini.texi +++ b/doc/emacs/mini.texi @@ -1,6 +1,6 @@ @c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Minibuffer diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index ab33cafb8e8..7d7065a441a 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @iftex @@ -795,6 +795,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}. @@ -1693,7 +1697,9 @@ each one a unique @dfn{server name}, using the variable @code{server-name}. For example, @kbd{M-x set-variable @key{RET} server-name @key{RET} "foo" @key{RET}} sets the server name to @samp{foo}. The @code{emacsclient} program can specify a server by -name, using the @samp{-s} option (@pxref{emacsclient Options}). +name, using the @samp{-s} or the @samp{-f} option (@pxref{emacsclient +Options}), depending on whether or not the server uses a TCP socket +(@pxref{TCP Emacs server}). If you want to run multiple Emacs daemons (@pxref{Initial Options}), you can give each daemon its own server name like this: @@ -1758,21 +1764,23 @@ use @kbd{M-x server-generate-key} to get a random key. When you start a TCP Emacs server, Emacs creates a @dfn{server file} containing the TCP information to be used by @command{emacsclient} to connect to the server. The variable @code{server-auth-dir} specifies -the directory containing the server file; by default, this is +the default directory containing the server file; by default, this is @file{~/.emacs.d/server/}. In the absence of a local socket with file permissions, the permissions of this directory determine which users can have their @command{emacsclient} processes talk to the Emacs -server. +server. If @code{server-name} is an absolute file name, the server +file is created where specified by that file name. @vindex EMACS_SERVER_FILE@r{, environment variable} To tell @command{emacsclient} to connect to the server over TCP with 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, @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. +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. @node Invoking emacsclient @subsection Invoking @code{emacsclient} @@ -1961,10 +1969,13 @@ evaluation performed is for side-effect rather than result. @item -s @var{server-name} @itemx --socket-name=@var{server-name} -Connect to the Emacs server named @var{server-name}. The server name -is given by the variable @code{server-name} on the Emacs server. If -this option is omitted, @command{emacsclient} connects to the first -server it finds. (This option is not supported on MS-Windows.) +Connect to the Emacs server named @var{server-name}. (This option is +not supported on MS-Windows.) The server name is given by the +variable @code{server-name} on the Emacs server. If this option is +omitted, @command{emacsclient} connects to the first server it finds. +If you set @code{server-name} of the Emacs server to an absolute file +name, give the same absolute file name as @var{server-name} to this +option to instruct @command{emacsclient} to connect to that server. Alternatively, you can set the @env{EMACS_SOCKET_NAME} environment variable to point to the server socket. (The command-line option diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi index 2bbc17b26db..4505bb5dc2d 100644 --- a/doc/emacs/modes.texi +++ b/doc/emacs/modes.texi @@ -1,6 +1,6 @@ @c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Modes diff --git a/doc/emacs/msdos-xtra.texi b/doc/emacs/msdos-xtra.texi index 64ce8414fc0..e0d3bcd4093 100644 --- a/doc/emacs/msdos-xtra.texi +++ b/doc/emacs/msdos-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2018 Free Software Foundation, Inc. +@c Copyright (C) 2004-2019 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in emacs-xtra.texi (when producing the diff --git a/doc/emacs/msdos.texi b/doc/emacs/msdos.texi index c69c7d37f9b..9fc4b6262fb 100644 --- a/doc/emacs/msdos.texi +++ b/doc/emacs/msdos.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Microsoft Windows diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi index 6c0c5b23989..6a26667510a 100644 --- a/doc/emacs/mule.texi +++ b/doc/emacs/mule.texi @@ -1,6 +1,6 @@ @c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1997, 1999-2018 Free Software Foundation, Inc. +@c Copyright (C) 1997, 1999-2019 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node International @chapter International Character Set Support @@ -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 43f5a8497d9..26e64243301 100644 --- a/doc/emacs/package.texi +++ b/doc/emacs/package.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Packages diff --git a/doc/emacs/picture-xtra.texi b/doc/emacs/picture-xtra.texi index 9ebc78ec628..704cff16502 100644 --- a/doc/emacs/picture-xtra.texi +++ b/doc/emacs/picture-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2018 Free Software Foundation, Inc. +@c Copyright (C) 2004-2019 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in emacs-xtra.texi (when producing the diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index cfeb61e44d4..c1ad5b57023 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -1,6 +1,6 @@ @c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Programs diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi index 98eed064536..1881b49627e 100644 --- a/doc/emacs/regs.texi +++ b/doc/emacs/regs.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Registers diff --git a/doc/emacs/rmail.texi b/doc/emacs/rmail.texi index a17ef4938e6..4901ca9709e 100644 --- a/doc/emacs/rmail.texi +++ b/doc/emacs/rmail.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Rmail @@ -318,7 +318,7 @@ effect of a @kbd{d} command in most cases. It undeletes the current message if the current message is deleted. Otherwise it moves backward to previous messages until a deleted message is found, and undeletes that message. A numeric prefix argument serves as a repeat count, to -allow deletion of several messages in a single command. +allow undeletion of several messages in a single command. You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u} moves back to and undeletes the message that the @kbd{d} deleted. But diff --git a/doc/emacs/screen.texi b/doc/emacs/screen.texi index 8f2be4b9a7e..67da9daab87 100644 --- a/doc/emacs/screen.texi +++ b/doc/emacs/screen.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Screen diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi index 801e8bb33eb..a1c987c1252 100644 --- a/doc/emacs/search.texi +++ b/doc/emacs/search.texi @@ -1,6 +1,6 @@ @c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Search @@ -315,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 @@ -548,12 +548,12 @@ an incremental search. This feature is disabled if @item Motion Commands @cindex motion commands, during incremental search -When @code{search-exit-option} is customized to @code{shift-move}, +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{search-exit-option} is @code{move}, you can extend the +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. @@ -684,6 +684,8 @@ matching}) has no effect on them. @kindex M-s M-w @findex eww-search-words @vindex eww-search-prefix +@cindex Internet search +@cindex search Internet for keywords To search the Web for the text in region, type @kbd{M-s M-w}. This command performs an Internet search for the words in region using the search engine whose @acronym{URL} is specified by the variable @@ -972,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.) @@ -1872,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 00b3c4d7531..c6b8912e2e3 100644 --- a/doc/emacs/sending.texi +++ b/doc/emacs/sending.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Sending Mail diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi index 1e96163105b..96492783b92 100644 --- a/doc/emacs/text.texi +++ b/doc/emacs/text.texi @@ -1,6 +1,6 @@ @c -*- coding: utf-8 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Text diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi index bb05378f4c9..1bdd9fa0141 100644 --- a/doc/emacs/trouble.texi +++ b/doc/emacs/trouble.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @iftex diff --git a/doc/emacs/vc-xtra.texi b/doc/emacs/vc-xtra.texi index 17d6a3b55b9..ca919e847e4 100644 --- a/doc/emacs/vc-xtra.texi +++ b/doc/emacs/vc-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2018 Free Software Foundation, Inc. +@c Copyright (C) 2004-2019 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included in emacs-xtra.texi when producing the printed diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi index 35dd6d1235a..1c17695c8dd 100644 --- a/doc/emacs/vc1-xtra.texi +++ b/doc/emacs/vc1-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2018 Free Software Foundation, Inc. +@c Copyright (C) 2004-2019 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in vc-xtra.texi (when producing the diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi index 17ce4ad04d3..ece53130531 100644 --- a/doc/emacs/windows.texi +++ b/doc/emacs/windows.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2018 Free Software +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node Windows @@ -48,8 +48,8 @@ other windows at all. However, there are other commands such as @kbd{C-x 4 b} that select a different window and switch buffers in it. Also, all commands that display information in a window, including (for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b} -(@code{list-buffers}), work by switching buffers in a nonselected -window without affecting the selected window. +(@code{list-buffers}), usually work by displaying buffers in a +nonselected window without affecting the selected window. When multiple windows show the same buffer, they can have different regions, because they can have different values of point. However, @@ -262,6 +262,8 @@ Delete all windows in the selected frame except the selected window Delete the selected window and kill the buffer that was showing in it (@code{kill-buffer-and-window}). The last character in this key sequence is a zero. +@item M-x delete-windows-on @key{RET} @var{buffer} @key{RET} +Delete windows showing the specified @var{buffer}. @item C-x ^ Make selected window taller (@code{enlarge-window}). @item C-x @} @@ -297,6 +299,11 @@ selected window. whole frame. (This command cannot be used while the minibuffer window is active; attempting to do so signals an error.) + @kbd{M-x delete-windows-on} deletes windows that show a specific +buffer. It prompts for the buffer, defaulting to the current buffer. +With prefix argument of zero, @kbd{C-u 0}, this command deletes +windows only on the current display's frames. + @cindex resize window @cindex resizing windows @kindex C-x ^ @@ -347,11 +354,9 @@ heights of all the windows in the selected frame. in response to a user command. There are several different ways in which commands do this. - Many commands, like @kbd{C-x C-f} (@code{find-file}), display the -buffer by ``taking over'' the selected window, expecting that the -user's attention will be diverted to that buffer. These commands -usually work by calling @code{switch-to-buffer} internally -(@pxref{Select Buffer}). + Many commands, like @kbd{C-x C-f} (@code{find-file}), by default +display the buffer by ``taking over'' the selected window, expecting +that the user's attention will be diverted to that buffer. Some commands try to display intelligently, trying not to take over the selected window, e.g., by splitting off a new window and @@ -374,10 +379,9 @@ key (@pxref{Pop Up Window}). Commands with names ending in @code{-other-frame} behave like @code{display-buffer}, except that they (i) never display in the -selected window and (ii) prefer to create a new frame to display the -desired buffer instead of splitting a window---as though the variable -@code{pop-up-frames} is set to @code{t} (@pxref{Window Choice}). -Several of these commands are bound in the @kbd{C-x 5} prefix key. +selected window and (ii) prefer to either create a new frame or use a +window on some other frame to display the desired buffer. Several of +these commands are bound in the @kbd{C-x 5} prefix key. @menu * Window Choice:: How @code{display-buffer} works. @@ -390,33 +394,61 @@ Several of these commands are bound in the @kbd{C-x 5} prefix key. The @code{display-buffer} command (as well as commands that call it internally) chooses a window to display by following the steps given -below. @xref{Choosing Window,,Choosing a Window for Display, elisp, -The Emacs Lisp Reference Manual}, for details about how to alter this -sequence of steps. +below. @xref{Choosing Window,,Choosing a Window for Displaying a +Buffer, elisp, The Emacs Lisp Reference Manual}, for details about how +to alter this sequence of steps. @itemize -@vindex same-window-buffer-names -@vindex same-window-regexps @item -First, check if the buffer should be displayed in the selected window -regardless of other considerations. You can tell Emacs to do this by -adding the desired buffer's name to the list -@code{same-window-buffer-names}, or adding a matching regular -expression to the list @code{same-window-regexps}. By default, these -variables are @code{nil}, so this step is skipped. +If the buffer should be displayed in the selected window regardless of +other considerations, reuse the selected window. By default, this +step is skipped, but you can tell Emacs not to skip it by adding a +regular expression matching the buffer's name together with a +reference to the @code{display-buffer-same-window} action function +(@pxref{Buffer Display Action Functions,,Action Functions for Buffer +Display, elisp, The Emacs Lisp Reference Manual}) to the option +@code{display-buffer-alist} (@pxref{Choosing Window,,Choosing a Window +for Displaying a Buffer, elisp, The Emacs Lisp Reference Manual}). +For example, to display the buffer @file{*scratch*} preferably in the +selected window write: + +@example +@group +(customize-set-variable + 'display-buffer-alist + '("\\*scratch\\*" (display-buffer-same-window))) +@end group +@end example + +By default, @code{display-buffer-alist} is @code{nil}. @item Otherwise, if the buffer is already displayed in an existing window, -reuse that window. Normally, only windows on the selected frame -are considered, but windows on other frames are also reusable if you -change @code{pop-up-frames} (see below) to @code{t}. +reuse that window. Normally, only windows on the selected frame are +considered, but windows on other frames are also reusable if you use +the corresponding @code{reusable-frames} action alist entry +(@pxref{Buffer Display Action Alists,,Action Alists for Buffer +Display, elisp, The Emacs Lisp Reference Manual}). See the +next step for an example of how to do that. -@vindex pop-up-frames @item Otherwise, optionally create a new frame and display the buffer there. -By default, this step is skipped. To enable it, change the variable -@code{pop-up-frames} to a non-@code{nil} value. The special value -@code{graphic-only} means to do this only on graphical displays. +By default, this step is skipped. To enable it, change the value of +the option @code{display-buffer-base-action} (@pxref{Choosing +Window,,Choosing a Window for Displaying a Buffer, elisp, The Emacs +Lisp Reference Manual}) as follows: + +@example +@group +(customize-set-variable + 'display-buffer-base-action + '((display-buffer-reuse-window display-buffer-pop-up-frame) + (reusable-frames . 0))) +@end group +@end example + +This customization will also try to make the preceding step search for +a reusable window on all visible or iconified frames. @item Otherwise, try to create a new window by splitting a window on the @@ -436,9 +468,9 @@ window was not split before (to avoid excessive splitting). @item Otherwise, display the buffer in a window previously showing it. -Normally, only windows on the selected frame are considered, but if -@code{pop-up-frames} is non-@code{nil} the window may be also on another -frame. +Normally, only windows on the selected frame are considered, but with +a suitable @code{reusable-frames} action alist entry (see above) the +window may be also on another frame. @item Otherwise, display the buffer in an existing window on the selected @@ -449,41 +481,35 @@ If all the above methods fail for whatever reason, create a new frame and display the buffer there. @end itemize -A more advanced and flexible way to customize the behavior of -@code{display-buffer} is by using the option @code{display-buffer-alist} -mentioned in the next section. - @node Temporary Displays @subsection Displaying non-editable buffers. -@cindex pop-up windows @cindex temporary windows Some buffers are shown in windows for perusal rather than for editing. Help commands (@pxref{Help}) typically use a buffer called @file{*Help*} for that purpose, minibuffer completion (@pxref{Completion}) uses a -buffer called @file{*Completions*} instead. Such buffers are usually +buffer called @file{*Completions*}, etc. Such buffers are usually displayed only for a short period of time. Normally, Emacs chooses the window for such temporary displays via -@code{display-buffer} as described above. The @file{*Completions*} -buffer, on the other hand, is normally displayed in a window at the -bottom of the selected frame, regardless of the number of windows -already shown on that frame. +@code{display-buffer}, as described in the previous subsection. The +@file{*Completions*} buffer, on the other hand, is normally displayed +in a window at the bottom of the selected frame, regardless of the +number of windows already shown on that frame. If you prefer Emacs to display a temporary buffer in a different -fashion, we recommend customizing the variable -@code{display-buffer-alist} (@pxref{Choosing Window,,Choosing a Window -for Display, elisp, The Emacs Lisp Reference Manual}). For example, -to display @file{*Completions*} by splitting a window as described in -the previous section, use the following form in your initialization -file (@pxref{Init File}): +fashion, customize the variable @code{display-buffer-alist} +(@pxref{Choosing Window,,Choosing a Window for Displaying a Buffer, +elisp, The Emacs Lisp Reference Manual}) appropriately. For example, +to display @file{*Completions*} always below the selected window, use +the following form in your initialization file (@pxref{Init File}): @example @group (customize-set-variable 'display-buffer-alist - '(("\\*Completions\\*" display-buffer-pop-up-window))) + '(("\\*Completions\\*" display-buffer-below-selected))) @end group @end example @@ -491,10 +517,10 @@ file (@pxref{Init File}): The @file{*Completions*} buffer is also special in the sense that Emacs usually tries to make its window just as large as necessary to display all of its contents. To resize windows showing other -temporary displays like, for example, the @file{*Help*} buffer -accordingly, turn on the minor mode (@pxref{Minor Modes}) -@code{temp-buffer-resize-mode} (@pxref{Temporary Displays,,Temporary -Displays, elisp, The Emacs Lisp Reference Manual}). +temporary displays, like, for example, the @file{*Help*} buffer, turn +on the minor mode (@pxref{Minor Modes}) @code{temp-buffer-resize-mode} +(@pxref{Temporary Displays,,Temporary Displays, elisp, The Emacs Lisp +Reference Manual}). @vindex temp-buffer-max-height @vindex temp-buffer-max-width @@ -502,7 +528,7 @@ Displays, elisp, The Emacs Lisp Reference Manual}). can be controlled by customizing the options @code{temp-buffer-max-height} and @code{temp-buffer-max-width} (@pxref{Temporary Displays,,Temporary Displays, elisp, The Emacs Lisp -Reference Manual}) and cannot exceed the size of the containing frame. +Reference Manual}), and cannot exceed the size of the containing frame. @node Window Convenience @@ -534,7 +560,7 @@ buffer. @xref{Follow Mode}. between neighboring windows in a frame. @kbd{M-x windmove-right} selects the window immediately to the right of the currently selected one, and similarly for the left, up, and down -counterparts. @kbd{M-x windmove-default-keybindings} binds these +counterparts. @w{@kbd{M-x windmove-default-keybindings}} binds these commands to @kbd{S-right} etc.; doing so disables shift selection for those keys (@pxref{Shift Selection}). diff --git a/doc/emacs/xresources.texi b/doc/emacs/xresources.texi index 903090f51a9..d8b70ef9009 100644 --- a/doc/emacs/xresources.texi +++ b/doc/emacs/xresources.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1987, 1993-1995, 1997, 2001-2018 Free Software +@c Copyright (C) 1987, 1993-1995, 1997, 2001-2019 Free Software @c Foundation, Inc. @c See file emacs.texi for copying conditions. @node X Resources diff --git a/doc/lispintro/ChangeLog.1 b/doc/lispintro/ChangeLog.1 index 9e15544630c..2df76f4e029 100644 --- a/doc/lispintro/ChangeLog.1 +++ b/doc/lispintro/ChangeLog.1 @@ -782,7 +782,7 @@ ;; coding: utf-8 ;; End: - Copyright (C) 2001-2018 Free Software Foundation, Inc. + Copyright (C) 2001-2019 Free Software Foundation, Inc. This file is part of GNU Emacs. diff --git a/doc/lispintro/Makefile.in b/doc/lispintro/Makefile.in index e2a1229d5ca..37fffb8a0f2 100644 --- a/doc/lispintro/Makefile.in +++ b/doc/lispintro/Makefile.in @@ -1,6 +1,6 @@ ### @configure_input@ -# Copyright (C) 1994-1999, 2001-2018 Free Software Foundation, Inc. +# Copyright (C) 1994-1999, 2001-2019 Free Software Foundation, Inc. # This file is part of GNU Emacs. diff --git a/doc/lispintro/README b/doc/lispintro/README index c39f6d2402a..fd4ede1dfa0 100644 --- a/doc/lispintro/README +++ b/doc/lispintro/README @@ -1,4 +1,4 @@ -Copyright (C) 2001-2018 Free Software Foundation, Inc. +Copyright (C) 2001-2019 Free Software Foundation, Inc. See the end of the file for license conditions. diff --git a/doc/lispintro/cons-1.eps b/doc/lispintro/cons-1.eps index cc1d5c7c409..dff7130952e 100644 --- a/doc/lispintro/cons-1.eps +++ b/doc/lispintro/cons-1.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:26:58 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2018 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2019 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-2.eps b/doc/lispintro/cons-2.eps index 00d08e423d9..ccba32056ab 100644 --- a/doc/lispintro/cons-2.eps +++ b/doc/lispintro/cons-2.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:26:39 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2018 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2019 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-2a.eps b/doc/lispintro/cons-2a.eps index 26f690a1435..3beaa5b640b 100644 --- a/doc/lispintro/cons-2a.eps +++ b/doc/lispintro/cons-2a.eps @@ -4,7 +4,7 @@ %%CreationDate: Tue Mar 14 15:09:30 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2018 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2019 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-3.eps b/doc/lispintro/cons-3.eps index d75620e28e4..6bae8f74116 100644 --- a/doc/lispintro/cons-3.eps +++ b/doc/lispintro/cons-3.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:25:41 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2018 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2019 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-4.eps b/doc/lispintro/cons-4.eps index 154df88e531..fd056b55196 100644 --- a/doc/lispintro/cons-4.eps +++ b/doc/lispintro/cons-4.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:25:06 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2018 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2019 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-5.eps b/doc/lispintro/cons-5.eps index d5c08ac1635..d3f7581eab9 100644 --- a/doc/lispintro/cons-5.eps +++ b/doc/lispintro/cons-5.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:27:28 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2018 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2019 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/drawers.eps b/doc/lispintro/drawers.eps index e3a7f0a7dd2..4569b21fde9 100644 --- a/doc/lispintro/drawers.eps +++ b/doc/lispintro/drawers.eps @@ -9,7 +9,7 @@ %%EndComments %%BeginProlog -% Copyright (C) 2001-2018 Free Software Foundation, Inc. +% Copyright (C) 2001-2019 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 0b0c0a167d9..519decb1d04 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -113,7 +113,7 @@ Edition @value{edition-number}, @value{update-date} Distributed with Emacs version @value{EMACSVER}. @end ifnottex @sp 1 -Copyright @copyright{} 1990--1995, 1997, 2001--2018 Free Software +Copyright @copyright{} 1990--1995, 1997, 2001--2019 Free Software Foundation, Inc. @sp 1 @@ -4636,7 +4636,7 @@ languages, not just Lisp, and C, and it works with non-programming text as well. For example, @code{xref-find-definitions} will jump to the various nodes in the Texinfo source file of this document (provided that you've run the @command{etags} utility to record all -the nodes in the manuals that come with Emacs; @pxref{Create tags +the nodes in the manuals that come with Emacs; @pxref{Create Tags Table,,, emacs, The GNU Emacs Manual}). To use the @code{xref-find-definitions} command, type @kbd{M-.} @@ -14825,7 +14825,7 @@ According to its documentation as shown by @kbd{C-h f} (the @code{describe-function} command), the @code{find-file-noselect} function reads the named file into a buffer and returns the buffer. (Its most recent version includes an optional @var{wildcards} argument, -too, as well as another to read a file literally and an other you +too, as well as another to read a file literally and another to suppress warning messages. These optional arguments are irrelevant.) However, the @code{find-file-noselect} function does not select the @@ -15599,7 +15599,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 diff --git a/doc/lispintro/lambda-1.eps b/doc/lispintro/lambda-1.eps index 4b6d8275cb5..a78a60cb42f 100644 --- a/doc/lispintro/lambda-1.eps +++ b/doc/lispintro/lambda-1.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:31:53 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2018 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2019 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/lambda-2.eps b/doc/lispintro/lambda-2.eps index 473785c81af..a7c2e7b830b 100644 --- a/doc/lispintro/lambda-2.eps +++ b/doc/lispintro/lambda-2.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:33:09 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2018 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2019 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/lambda-3.eps b/doc/lispintro/lambda-3.eps index c1a251682f8..d73a9d69104 100644 --- a/doc/lispintro/lambda-3.eps +++ b/doc/lispintro/lambda-3.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:33:49 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2018 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2019 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispref/ChangeLog.1 b/doc/lispref/ChangeLog.1 index 42240ae2880..a271d2158cc 100644 --- a/doc/lispref/ChangeLog.1 +++ b/doc/lispref/ChangeLog.1 @@ -13989,7 +13989,7 @@ ;; coding: utf-8 ;; End: - Copyright (C) 1998-2018 Free Software Foundation, Inc. + Copyright (C) 1998-2019 Free Software Foundation, Inc. This file is part of GNU Emacs. diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in index 221f4f97f51..5de04a7784c 100644 --- a/doc/lispref/Makefile.in +++ b/doc/lispref/Makefile.in @@ -1,6 +1,6 @@ ### @configure_input@ -# Copyright (C) 1990-1996, 1998-2018 Free Software Foundation, Inc. +# Copyright (C) 1990-1996, 1998-2019 Free Software Foundation, Inc. # This file is part of GNU Emacs. diff --git a/doc/lispref/README b/doc/lispref/README index cca433868b2..3e121bfd2bb 100644 --- a/doc/lispref/README +++ b/doc/lispref/README @@ -1,4 +1,4 @@ -Copyright (C) 2001-2018 Free Software Foundation, Inc. -*- outline -*- +Copyright (C) 2001-2019 Free Software Foundation, Inc. -*- outline -*- See the end of the file for license conditions. diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi index 1e9471ba27a..b67c014a83d 100644 --- a/doc/lispref/abbrevs.texi +++ b/doc/lispref/abbrevs.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1999, 2001-2018 Free Software Foundation, +@c Copyright (C) 1990-1994, 1999, 2001-2019 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Abbrevs @@ -473,7 +473,7 @@ Set the property @var{prop} of abbrev table @var{table} to value @var{val}. @defun abbrev-table-get table prop Return the property @var{prop} of abbrev table @var{table}, or @code{nil} -if the abbrev has no such property. +if @var{table} has no such property. @end defun The following properties have special meaning: diff --git a/doc/lispref/anti.texi b/doc/lispref/anti.texi index 556203b69f0..6066e266387 100644 --- a/doc/lispref/anti.texi +++ b/doc/lispref/anti.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2002-2018 Free Software Foundation, Inc. +@c Copyright (C) 1999, 2002-2019 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @c This node must have no pointers. diff --git a/doc/lispref/back.texi b/doc/lispref/back.texi index df39479bb61..c4c346628bf 100644 --- a/doc/lispref/back.texi +++ b/doc/lispref/back.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001-2018 Free Software Foundation, Inc. +@c Copyright (C) 2001-2019 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @c @c %**start of header diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi index 8ce8f6180d1..6a5b6d1661d 100644 --- a/doc/lispref/backups.texi +++ b/doc/lispref/backups.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1999, 2001-2018 Free Software Foundation, +@c Copyright (C) 1990-1995, 1999, 2001-2019 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Backups and Auto-Saving diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index b2a4b0eab1a..260f159851b 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Buffers @@ -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 @@ -658,7 +657,8 @@ visiting a file or if the time has been explicitly cleared by too. For instance, in a Dired buffer listing a directory, it returns the last modification time of that directory, as recorded by Dired. -If the buffer is not visiting a file, this function returns @minus{}1. +If the buffer is visiting a file that doesn't exist, this function +returns @minus{}1. @end defun @defun set-visited-file-modtime &optional time @@ -935,6 +935,10 @@ This is a normal hook run whenever the buffer list changes. Functions (@pxref{Creating Buffers}), @code{rename-buffer} (@pxref{Buffer Names}), @code{kill-buffer} (@pxref{Killing Buffers}), @code{bury-buffer} (see above) and @code{select-window} (@pxref{Selecting Windows}). + +Functions run by this hook should avoid calling @code{select-window} +with a nil @var{norecord} argument or @code{with-temp-buffer} since +either may lead to infinite recursion. @end defvar @node Creating Buffers diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 427379bc79c..cd44c1c87ef 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Command Loop @@ -1012,7 +1012,8 @@ If the last event came from a keyboard macro, the value is @code{macro}. sequence of text that has the @code{display} or @code{composition} property, or is invisible. Therefore, after a command finishes and returns to the command loop, if point is within such a sequence, the -command loop normally moves point to the edge of the sequence. +command loop normally moves point to the edge of the sequence, making this +sequence effectively intangible. A command can inhibit this feature by setting the variable @code{disable-point-adjustment}: @@ -2879,6 +2880,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 6d21ca3e6ab..d9db55e22cd 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 2001-2018 Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 2001-2019 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Byte Compilation @chapter Byte Compilation diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 0f7502f1c20..5d4184e3fb4 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -1,11 +1,12 @@ @c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Control Structures @chapter Control Structures @cindex special forms for control structures +@cindex forms for control structures @cindex control structures A Lisp program consists of a set of @dfn{expressions}, or @@ -48,6 +49,7 @@ structure constructs (@pxref{Macros}). @section Sequencing @cindex sequencing @cindex sequential execution +@cindex forms for sequential execution Evaluating forms in the order they appear is the most common way control passes from one form to another. In some contexts, such as in a @@ -146,6 +148,7 @@ following @var{forms}, in textual order, returning the result of @node Conditionals @section Conditionals @cindex conditional evaluation +@cindex forms, conditional Conditional control structures choose among alternatives. Emacs Lisp has five conditional forms: @code{if}, which is much the same as in @@ -419,64 +422,68 @@ This is not completely equivalent because it can evaluate @var{arg1} or @node Pattern-Matching Conditional @section Pattern-Matching Conditional @cindex pcase -@cindex pattern matching +@cindex pattern matching, programming style Aside from the four basic conditional forms, Emacs Lisp also has a pattern-matching conditional form, the @code{pcase} macro, a hybrid of @code{cond} and @code{cl-case} (@pxref{Conditionals,,,cl,Common Lisp Extensions}) that overcomes their limitations and introduces -the @dfn{pattern matching} programming style. -First, the limitations: +the @dfn{pattern matching programming style}. +The limitations that @code{pcase} overcomes are: @itemize -@item The @code{cond} form chooses among alternatives -by evaluating the predicate @var{condition} of each -of its clauses (@pxref{Conditionals}). -The primary limitation is that variables let-bound in @var{condition} -are not available to the clause's @var{body-forms}. +@item +The @code{cond} form chooses among alternatives by evaluating the +predicate @var{condition} of each of its clauses +(@pxref{Conditionals}). The primary limitation is that variables +let-bound in @var{condition} are not available to the clause's +@var{body-forms}. Another annoyance (more an inconvenience than a limitation) is that when a series of @var{condition} predicates implement -equality tests, there is a lot of repeated code. -For that, why not use @code{cl-case}? +equality tests, there is a lot of repeated code. (@code{cl-case} +solves this inconvenience.) @item The @code{cl-case} macro chooses among alternatives by evaluating the equality of its first argument against a set of specific values. -The limitations are two-fold: + +Its limitations are two-fold: @enumerate -@item The equality tests use @code{eql}. -@item The values must be known and written in advance. +@item +The equality tests use @code{eql}. +@item +The values must be known and written in advance. @end enumerate @noindent These render @code{cl-case} unsuitable for strings or compound -data structures (e.g., lists or vectors). -For that, why not use @code{cond}? -(And here we end up in a circle.) +data structures (e.g., lists or vectors). (@code{cond} doesn't have +these limitations, but it has others, see above.) @end itemize @noindent Conceptually, the @code{pcase} macro borrows the first-arg focus of @code{cl-case} and the clause-processing flow of @code{cond}, replacing @var{condition} with a generalization of -the equality test called @dfn{matching}, +the equality test which is a variant of @dfn{pattern matching}, and adding facilities so that you can concisely express a clause's predicate, and arrange to share let-bindings between a clause's predicate and @var{body-forms}. The concise expression of a predicate is known as a @dfn{pattern}. -When the predicate, called on the value of the first arg, -returns non-@code{nil}, the pattern matches the value -(or sometimes ``the value matches the pattern''). +When the predicate, called on the value of the first arg, returns +non-@code{nil}, we say that ``the pattern matches the value'' (or +sometimes ``the value matches the pattern''). @menu -* The @code{pcase} macro: pcase Macro. Plus examples and caveats. +* The @code{pcase} macro: pcase Macro. Includes examples and caveats. * Extending @code{pcase}: Extending pcase. Define new kinds of patterns. -* Backquote-Style Patterns: Backquote Patterns. Structural matching. +* Backquote-Style Patterns: Backquote Patterns. Structural patterns matching. +* Destructuring with pcase Patterns:: Using pcase patterns to extract subfields. @end menu @node pcase Macro @@ -497,26 +504,30 @@ of the last of @var{body-forms} in the successful clause. Otherwise, @code{pcase} evaluates to @code{nil}. @end defmac -The rest of this subsection -describes different forms of core patterns, -presents some examples, -and concludes with important caveats on using the -let-binding facility provided by some pattern forms. -A core pattern can have the following forms: +@cindex pcase pattern +Each @var{pattern} has to be a @dfn{pcase pattern}, which can use +either one of the core patterns defined below, or one of the patterns +defined via @code{pcase-defmacro} (@pxref{Extending pcase}). + +The rest of this subsection describes different forms of core +patterns, presents some examples, and concludes with important caveats +on using the let-binding facility provided by some pattern forms. A +core pattern can have the following forms: @table @code @item _ Matches any @var{expval}. -This is known as @dfn{don't care} or @dfn{wildcard}. +This is also known as @dfn{don't care} or @dfn{wildcard}. @item '@var{val} -Matches if @var{expval} is @code{equal} to @var{val}. +Matches if @var{expval} equals @var{val}. The comparison is done as +if by @code{equal} (@pxref{Equality Predicates}). @item @var{keyword} @itemx @var{integer} @itemx @var{string} -Matches if @var{expval} is @code{equal} to the literal object. +Matches if @var{expval} equals the literal object. This is a special case of @code{'@var{val}}, above, possible because literal objects of these types are self-quoting. @@ -528,17 +539,17 @@ Matches any @var{expval}, and additionally let-binds @var{symbol} to If @var{symbol} is part of a sequencing pattern @var{seqpat} (e.g., by using @code{and}, below), the binding is also available to the portion of @var{seqpat} following the appearance of @var{symbol}. -This usage has some caveats (@pxref{pcase-symbol-caveats,,caveats}). +This usage has some caveats, see @ref{pcase-symbol-caveats,,caveats}. Two symbols to avoid are @code{t}, which behaves like @code{_} -(above) and is deprecated, and @code{nil}, which signals error. +(above) and is deprecated, and @code{nil}, which signals an error. Likewise, it makes no sense to bind keyword symbols (@pxref{Constant Variables}). @item (pred @var{function}) Matches if the predicate @var{function} returns non-@code{nil} when called on @var{expval}. -@var{function} can have one of the possible forms: +the predicate @var{function} can have one of the following forms: @table @asis @item function name (a symbol) @@ -565,20 +576,17 @@ the actual function call becomes: @w{@code{(= 42 @var{expval})}}. @item (app @var{function} @var{pattern}) Matches if @var{function} called on @var{expval} returns a value that matches @var{pattern}. -@var{function} can take one of the -forms described for @code{pred}, above. -Unlike @code{pred}, however, -@code{app} tests the result against @var{pattern}, -rather than against a boolean truth value. +@var{function} can take one of the forms described for @code{pred}, +above. Unlike @code{pred}, however, @code{app} tests the result +against @var{pattern}, rather than against a boolean truth value. @item (guard @var{boolean-expression}) Matches if @var{boolean-expression} evaluates to non-@code{nil}. @item (let @var{pattern} @var{expr}) -Evaluates @var{expr} to get @var{exprval} -and matches if @var{exprval} matches @var{pattern}. -(It is called @code{let} because -@var{pattern} can bind symbols to values using @var{symbol}.) +Evaluates @var{expr} to get @var{exprval} and matches if @var{exprval} +matches @var{pattern}. (It is called @code{let} because @var{pattern} +can bind symbols to values using @var{symbol}.) @end table @cindex sequencing pattern @@ -591,18 +599,16 @@ but instead of processing values, they process sub-patterns. @table @code @item (and @var{pattern1}@dots{}) -Attempts to match @var{pattern1}@dots{}, in order, -until one of them fails to match. -In that case, @code{and} likewise fails to match, -and the rest of the sub-patterns are not tested. -If all sub-patterns match, @code{and} matches. +Attempts to match @var{pattern1}@dots{}, in order, until one of them +fails to match. In that case, @code{and} likewise fails to match, and +the rest of the sub-patterns are not tested. If all sub-patterns +match, @code{and} matches. @item (or @var{pattern1} @var{pattern2}@dots{}) Attempts to match @var{pattern1}, @var{pattern2}, @dots{}, in order, -until one of them succeeds. -In that case, @code{or} likewise matches, -and the rest of the sub-patterns are not tested. -(Note that there must be at least two sub-patterns. +until one of them succeeds. In that case, @code{or} likewise matches, +and the rest of the sub-patterns are not tested. (Note that there +must be at least two sub-patterns. Simply @w{@code{(or @var{pattern1})}} signals error.) @c Issue: Is this correct and intended? @c Are there exceptions, qualifications? @@ -1037,12 +1043,11 @@ Both use a single backquote construct (@pxref{Backquote}). This subsection describes @dfn{backquote-style patterns}, a set of builtin patterns that eases structural matching. -For background, @xref{Pattern-Matching Conditional}. +For background, @pxref{Pattern-Matching Conditional}. -@dfn{Backquote-style patterns} are a powerful set of -@code{pcase} pattern extensions (created using @code{pcase-defmacro}) -that make it easy to match @var{expval} against -specifications of its @emph{structure}. +Backquote-style patterns are a powerful set of @code{pcase} pattern +extensions (created using @code{pcase-defmacro}) that make it easy to +match @var{expval} against specifications of its @emph{structure}. For example, to match @var{expval} that must be a list of two elements whose first element is a specific string and the second @@ -1166,10 +1171,110 @@ evaluation results: (evaluate '(sub 1 2) nil) @result{} error @end example +@node Destructuring with pcase Patterns +@subsection Destructuring with @code{pcase} Patterns +@cindex destructuring with pcase patterns + +Pcase patterns not only express a condition on the form of the objects +they can match, but they can also extract sub-fields of those objects. +For example we can extract 2 elements from a list that is the value of +the variable @code{my-list} with the following code: + +@example + (pcase my-list + (`(add ,x ,y) (message "Contains %S and %S" x y))) +@end example + +This will not only extract @code{x} and @code{y} but will additionally +test that @code{my-list} is a list containing exactly 3 elements and +whose first element is the symbol @code{add}. If any of those tests +fail, @code{pcase} will immediately return @code{nil} without calling +@code{message}. + +Extraction of multiple values stored in an object is known as +@dfn{destructuring}. Using @code{pcase} patterns allows to perform +@dfn{destructuring binding}, which is similar to a local binding +(@pxref{Local Variables}), but gives values to multiple elements of +a variable by extracting those values from an object of compatible +structure. + +The macros described in this section use @code{pcase} patterns to +perform destructuring binding. The condition of the object to be of +compatible structure means that the object must match the pattern, +because only then the object's subfields can be extracted. For +example: + +@example + (pcase-let ((`(add ,x ,y) my-list)) + (message "Contains %S and %S" x y)) +@end example + +@noindent +does the same as the previous example, except that it directly tries +to extract @code{x} and @code{y} from @code{my-list} without first +verifying if @code{my-list} is a list which has the right number of +elements and has @code{add} as its first element. The precise +behavior when the object does not actually match the pattern is +undefined, although the body will not be silently skipped: either an +error is signaled or the body is run with some of the variables +potentially bound to arbitrary values like @code{nil}. + +The pcase patterns that are useful for destructuring bindings are +generally those described in @ref{Backquote Patterns}, since they +express a specification of the structure of objects that will match. + +For an alternative facility for destructuring binding, see +@ref{seq-let}. + +@defmac pcase-let bindings body@dots{} +Perform destructuring binding of variables according to +@var{bindings}, and then evaluate @var{body}. + +@var{bindings} is a list of bindings of the form @w{@code{(@var{pattern} +@var{exp})}}, where @var{exp} is an expression to evaluate and +@var{pattern} is a @code{pcase} pattern. + +All @var{exp}s are evaluated first, after which they are matched +against their respective @var{pattern}, introducing new variable +bindings that can then be used inside @var{body}. The variable +bindings are produced by destructuring binding of elements of +@var{pattern} to the values of the corresponding elements of the +evaluated @var{exp}. +@end defmac + +@defmac pcase-let* bindings body@dots{} +Perform destructuring binding of variables according to +@var{bindings}, and then evaluate @var{body}. + +@var{bindings} is a list of bindings of the form @code{(@var{pattern} +@var{exp})}, where @var{exp} is an expression to evaluate and +@var{pattern} is a @code{pcase} pattern. The variable bindings are +produced by destructuring binding of elements of @var{pattern} to the +values of the corresponding elements of the evaluated @var{exp}. + +Unlike @code{pcase-let}, but similarly to @code{let*}, each @var{exp} +is matched against its corresponding @var{pattern} before processing +the next element of @var{bindings}, so the variable bindings +introduced in each one of the @var{bindings} are available in the +@var{exp}s of the @var{bindings} that follow it, additionally to +being available in @var{body}. +@end defmac + +@defmac pcase-dolist (pattern list) body@dots{} +Execute @var{body} once for each element of @var{list}, on each +iteration performing a destructuring binding of variables in +@var{pattern} to the values of the corresponding subfields of the +element of @var{list}. The bindings are performed as if by +@code{pcase-let}. When @var{pattern} is a simple variable, this ends +up being equivalent to @code{dolist} (@pxref{Iteration}). +@end defmac + + @node Iteration @section Iteration @cindex iteration @cindex recursion +@cindex forms, iteration Iteration means executing part of a program repetitively. For example, you might want to repeat some computation once for each element @@ -1394,6 +1499,7 @@ exited. @node Catch and Throw @subsection Explicit Nonlocal Exits: @code{catch} and @code{throw} +@cindex forms for nonlocal exits Most control constructs affect only the flow of control within the construct itself. The function @code{throw} is the exception to this @@ -1765,6 +1871,7 @@ variables precisely as they were at the time of the error. @subsubsection Writing Code to Handle Errors @cindex error handler @cindex handling errors +@cindex forms for handling errors The usual effect of signaling an error is to terminate the command that is running and return immediately to the Emacs editor command loop. @@ -2134,6 +2241,7 @@ and their conditions. @node Cleanups @subsection Cleaning Up from Nonlocal Exits @cindex nonlocal exits, cleaning up +@cindex forms for cleanup The @code{unwind-protect} construct is essential whenever you temporarily put a data structure in an inconsistent state; it permits diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index 1cc7cb65b5f..f71dedfd8b0 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1997-2018 Free Software Foundation, Inc. +@c Copyright (C) 1997-2019 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Customization @chapter Customization Settings diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 89927db21ec..9e433433107 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1994, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Debugging diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index b4a4d6c454d..a97aabe9dff 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1,6 +1,6 @@ @c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2018 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2019 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Display @chapter Emacs Display @@ -1034,8 +1034,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 @@ -3079,10 +3079,17 @@ value, which inherits from @var{face}'s global definition. This function returns a list of all defined face names. @end defun +@cindex face number +@cindex face property of face symbols @defun face-id face This function returns the @dfn{face number} of face @var{face}. This is a number that uniquely identifies a face at low levels within Emacs. It is seldom necessary to refer to a face by its face number. +However, functions that manipulate glyphs, such as +@code{make-glyph-code} and @code{glyph-face} (@pxref{Glyphs}) access +the face numbers internally. Note that the face number is stored as +the value of the @code{face} property of the face symbol, so we +recommend not to set that property of a face to any value of your own. @end defun @defun face-documentation face @@ -3950,6 +3957,9 @@ fringe, and likewise @var{right} for the right fringe. A value of @var{outside-margins} is non-@code{nil}, that specifies that fringes should appear outside of the display margins. +If @var{window} is not large enough to accommodate fringes of the +desired width, this leaves the fringes of @var{window} unchanged. + The values specified here may be later overridden by invoking @code{set-window-buffer} (@pxref{Buffers and Windows}) on @var{window} with its @var{keep-margins} argument @code{nil} or omitted. @@ -4371,6 +4381,9 @@ vertical scroll bar. The possible values are @code{bottom}, @code{t}, which means to use the frame's default, and @code{nil} for no horizontal scroll bar. +If @var{window} is not large enough to accommodate a scroll bar of the +desired dimension, this leaves the corresponding scroll bar unchanged. + The values specified here may be later overridden by invoking @code{set-window-buffer} (@pxref{Buffers and Windows}) on @var{window} with its @var{keep-margins} argument @code{nil} or omitted. @@ -4887,6 +4900,16 @@ and the buffer position where the @code{display} property was found, respectively. Both positions can be different when @code{object} is a string. +Note that @var{condition} will only be evaluated when redisplay +examines the text where this display spec is located, so this feature +is best suited for conditions that are relatively stable, i.e.@: +yield, for each particular buffer position, the same results on every +evaluation. If the results change for the same text location, e.g., +if the result depends on the position of point, then the conditional +specification might not do what you want, because redisplay examines +only those parts of buffer text where it has reasons to assume that +something changed since the last display cycle. + @node Display Margins @subsection Displaying in the Margins @cindex display margins @@ -4950,6 +4973,9 @@ This function specifies the margin widths for window @var{window}, in character cell units. The argument @var{left} controls the left margin, and @var{right} controls the right margin (default @code{0}). +If @var{window} is not large enough to accommodate margins of the +desired width, this leaves the margins of @var{window} unchanged. + The values specified here may be later overridden by invoking @code{set-window-buffer} (@pxref{Buffers and Windows}) on @var{window} with its @var{keep-margins} argument @code{nil} or omitted. @@ -5112,6 +5138,47 @@ 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 :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 @@ -5251,6 +5318,16 @@ This function returns @code{t} if image @var{spec} has a mask bitmap. (@pxref{Input Focus}). @end defun +@defun image-scaling-p &optional frame +This function returns @code{t} if @var{frame} supports image scaling. +@var{frame} @code{nil} or omitted means to use the selected frame +(@pxref{Input Focus}). + +If image scaling is not supported, @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 @@ -5387,42 +5464,6 @@ 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 @@ -5431,9 +5472,6 @@ 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 2aace03a681..2c0ee3969b9 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -1,6 +1,6 @@ @comment -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1992-1994, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1992-1994, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 0b846291a07..e18759654d9 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -99,7 +99,7 @@ This is the @cite{GNU Emacs Lisp Reference Manual} @end ifnottex corresponding to Emacs version @value{EMACSVER}. -Copyright @copyright{} 1990--1996, 1998--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1990--1996, 1998--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -1045,9 +1045,7 @@ Windows * Cyclic Window Ordering:: Moving around the existing windows. * Buffers and Windows:: Each window displays the contents of a buffer. * Switching Buffers:: Higher-level functions for switching to a buffer. -* Choosing Window:: How to choose a window for displaying a buffer. -* Display Action Functions:: Subroutines for @code{display-buffer}. -* Choosing Window Options:: Extra options affecting how buffers are displayed. +* Displaying Buffers:: Displaying a buffer in a suitable window. * Window History:: Each window remembers the buffers displayed in it. * Dedicated Windows:: How to avoid displaying another buffer in a specific window. @@ -1069,6 +1067,18 @@ Windows redisplay going past a certain point, or window configuration changes. +Displaying Buffers + +* Choosing Window:: How to choose a window for displaying a buffer. +* Buffer Display Action Functions:: Support functions for buffer display. +* Buffer Display Action Alists:: Alists for fine-tuning buffer display + action functions. +* Choosing Window Options:: Extra options affecting how buffers are displayed. +* Precedence of Action Functions:: A tutorial explaining the precedence of + buffer display action functions. +* The Zen of Buffer Display:: How to avoid that buffers get lost in between + windows. + Side Windows * Displaying Buffers in Side Windows:: An action function for displaying diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index e61ea98e210..aa99b2b1a98 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1999, 2001-2018 Free Software Foundation, +@c Copyright (C) 1990-1993, 1999, 2001-2019 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Standard Errors diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index c9401be2535..db42dfb6373 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998, 2001-2018 Free Software Foundation, +@c Copyright (C) 1990-1994, 1998, 2001-2019 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Evaluation @@ -128,6 +128,7 @@ with the other types, which are self-evaluating forms. @cindex vector evaluation @cindex literal evaluation @cindex self-evaluating form +@cindex form, self-evaluating A @dfn{self-evaluating form} is any form that is not a list or symbol. Self-evaluating forms evaluate to themselves: the result of @@ -180,6 +181,8 @@ program. Here is an example: @node Symbol Forms @subsection Symbol Forms @cindex symbol evaluation +@cindex symbol forms +@cindex forms, symbol When a symbol is evaluated, it is treated as a variable. The result is the variable's value, if it has one. If the symbol has no value as @@ -216,6 +219,7 @@ its value ordinarily cannot be changed. @xref{Constant Variables}. @node Classifying Lists @subsection Classification of List Forms @cindex list form evaluation +@cindex forms, list A form that is a nonempty list is either a function call, a macro call, or a special form, according to its first element. These three @@ -350,6 +354,7 @@ Here is how you could define @code{indirect-function} in Lisp: @subsection Evaluation of Function Forms @cindex function form evaluation @cindex function call +@cindex forms, function call If the first element of a list being evaluated is a Lisp function object, byte-code object or primitive function object, then that list is @@ -373,6 +378,7 @@ body form becomes the value of the function call. @node Macro Forms @subsection Lisp Macro Evaluation @cindex macro call evaluation +@cindex forms, macro call If the first element of a list being evaluated is a macro object, then the list is a @dfn{macro call}. When a macro call is evaluated, the @@ -419,6 +425,7 @@ expansion. @node Special Forms @subsection Special Forms @cindex special forms +@cindex forms, special @cindex evaluation of special forms A @dfn{special form} is a primitive function specially marked so that @@ -540,6 +547,7 @@ described in @ref{Autoload}. @node Quoting @section Quoting +@cindex forms, quote The special form @code{quote} returns its single argument, as written, without evaluating it. This provides a way to include constant symbols @@ -599,6 +607,7 @@ only part of a list, while computing and substituting other parts. @cindex backquote (list substitution) @cindex ` (list substitution) @findex ` +@cindex forms, backquote @dfn{Backquote constructs} allow you to quote a list, but selectively evaluate elements of that list. In the simplest case, it diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 5682919b645..af16b1cf4bc 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Files @@ -16,7 +16,7 @@ described in @ref{Backups and Auto-Saving}. names. A file name is a string. Most of these functions expand file name arguments using the function @code{expand-file-name}, so that @file{~} is handled correctly, as are relative file names (including -@file{../}). @xref{File Name Expansion}. +@file{../} and the empty string). @xref{File Name Expansion}. In addition, certain @dfn{magic} file names are handled specially. For example, when a remote file name is specified, Emacs accesses the @@ -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 @@ -1306,7 +1306,7 @@ The file's @acronym{GID}, likewise (@code{file-attribute-group-id}). @item The time of last access as a Lisp timestamp -(@code{file-attribute-status-change-time}). The timestamp is in the +(@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 @@ -2367,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 @@ -2400,6 +2402,17 @@ This is for the sake of filesystems that have the concept of a superroot above the root directory @file{/}. On other filesystems, @file{/../} is interpreted exactly the same as @file{/}. +Expanding @file{.} or the empty string returns the default directory: + +@example +@group +(expand-file-name "." "/usr/spool/") + @result{} "/usr/spool" +(expand-file-name "" "/usr/spool/") + @result{} "/usr/spool" +@end group +@end example + Note that @code{expand-file-name} does @emph{not} expand environment variables; only @code{substitute-in-file-name} does that: @@ -2510,9 +2523,9 @@ with @samp{/:}. @defmac file-name-quote name This macro adds the quotation prefix @samp{/:} to the file @var{name}. For a local file @var{name}, it prefixes @var{name} with @samp{/:}. -If @var{name} is a remote file name, the local part of @var{name} is -quoted. If @var{name} is already a quoted file name, @var{name} is -returned unchanged. +If @var{name} is a remote file name, the local part of @var{name} +(@pxref{Magic File Names}) is quoted. If @var{name} is already a +quoted file name, @var{name} is returned unchanged. @example @group @@ -2691,8 +2704,8 @@ that remote host. If such a directory does not exist, or @code{temporary-file-directory} is returned. @end defun -In order to extract the local part of the path name from a temporary -file, @code{file-local-name} could be used. +In order to extract the local part of the file's name of a temporary +file, use @code{file-local-name} (@pxref{Magic File Names}). @node File Name Completion @subsection File Name Completion @@ -3065,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 @@ -3169,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}, @@ -3225,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}, @@ -3352,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 @@ -3381,11 +3396,24 @@ non-magic directory to serve as its current directory, and this function is a good way to come up with one. @end defun +@cindex local part of remote file name @defun file-local-name filename -This function returns the local part of file @var{filename}. For a -remote @var{filename}, it returns a file name which could be used -directly as argument of a remote process. If @var{filename} is local, -this function returns the file name. +This function returns the @dfn{local part} of @var{filename}. This is +the part of the file's name that identifies it on the remote host, and +is typically obtained by removing from the remote file name the parts +that specify the remote host and the method of accessing it. For +example: + +@smallexample +(file-local-name "/ssh:@var{user}@@@var{host}:/foo/bar") + @result{} "/foo/bar" +@end smallexample + +For a remote @var{filename}, this function returns a file name which +could be used directly as an argument of a remote process +(@pxref{Asynchronous Processes}, and @pxref{Synchronous Processes}), +and as the program to run on the remote host. If @var{filename} is +local, this function returns it unchanged. @end defun @defopt remote-file-name-inhibit-cache diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index ba4b9313731..9b3e02f4de0 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Frames @@ -440,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 @@ -503,7 +514,7 @@ Height | | | Height | | | Height In practice not all of the areas shown in the drawing will or may be present. The meaning of these areas is described below. -@table @samp +@table @asis @item Outer Frame @cindex outer frame @cindex outer edges @@ -1873,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 @@ -3203,9 +3220,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 @@ -3261,11 +3286,11 @@ and should be preferred when specifying a non-@code{nil} @code{drag-with-mode-line} parameter. When a child frame is used for displaying a buffer via -@code{display-buffer-in-child-frame} (@pxref{Display Action Functions}), -the frame's @code{auto-hide-function} parameter (@pxref{Frame -Interaction Parameters}) can be set to a function, in order to -appropriately deal with the frame when the window displaying the buffer -shall be quit. +@code{display-buffer-in-child-frame} (@pxref{Buffer Display Action +Functions}), the frame's @code{auto-hide-function} parameter +(@pxref{Frame Interaction Parameters}) can be set to a function, in +order to appropriately deal with the frame when the window displaying +the buffer shall be quit. When a child frame is used during minibuffer interaction, for example, to display completions in a separate window, the @code{minibuffer-exit} diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 69e9919f708..222f863c988 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -1,6 +1,6 @@ @c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Functions @@ -1082,15 +1082,18 @@ This macro returns an anonymous function with argument list @var{args}, documentation string @var{doc} (if any), interactive spec @var{interactive} (if any), and body forms given by @var{body}. -In effect, this macro makes @code{lambda} forms self-quoting: -evaluating a form whose @sc{car} is @code{lambda} yields the form -itself: +Under dynamic binding, this macro effectively makes @code{lambda} +forms self-quoting: evaluating a form whose @sc{car} is @code{lambda} +yields the form itself: @example (lambda (x) (* x x)) @result{} (lambda (x) (* x x)) @end example +Note that when evaluating under lexical binding the result is a +closure object (@pxref{Closures}). + The @code{lambda} form has one other effect: it tells the Emacs evaluator and byte-compiler that its argument is a function, by using @code{function} as a subroutine (see below). diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi index 9c4b56d8dcb..5aaf31247b4 100644 --- a/doc/lispref/hash.texi +++ b/doc/lispref/hash.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2001-2018 Free Software Foundation, Inc. +@c Copyright (C) 1999, 2001-2019 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Hash Tables @chapter Hash Tables diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 2688a2bff6e..63a782c3263 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -1,6 +1,6 @@ @c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Documentation diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi index 0d50a293f26..71992464e09 100644 --- a/doc/lispref/hooks.texi +++ b/doc/lispref/hooks.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1998, 2001-2018 Free Software Foundation, +@c Copyright (C) 1990-1993, 1998, 2001-2019 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Standard Hooks diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 27bfbe8bd85..8ebe47d9ad7 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1993, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node GNU Emacs Internals @@ -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 @@ -1557,7 +1623,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 @@ -1622,7 +1708,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 @@ -1730,7 +1816,7 @@ 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 -of display structure which shows the buffer or used as a container to +of display structure which shows the buffer or is used as a container to recursively place other windows on the same frame. (Do not confuse Emacs Lisp window object with the window as an entity managed by the user interface system like X; in Emacs terminology, the latter is called frame.) Finally, @@ -1757,7 +1843,8 @@ Here are some of the fields in @code{struct buffer_text}: @table @code @item beg -The address of the buffer contents. +The address of the buffer contents. The buffer contents is a linear C +array of @code{char}, with the gap somewhere in its midst. @item gpt @itemx gpt_byte @@ -1781,8 +1868,8 @@ buffer-modification event, and is never otherwise changed; @code{save_modiff} contains the value of @code{modiff} the last time the buffer was visited or saved; @code{chars_modiff} counts only modifications to the characters in the buffer, ignoring all other -kinds of changes; and @code{overlay_modiff} counts only modifications -to the overlays. +kinds of changes (such as text properties); and @code{overlay_modiff} +counts only modifications to the buffer's overlays. @item beg_unchanged @itemx end_unchanged @@ -1890,13 +1977,22 @@ position. @item name A Lisp string that names the buffer. It is guaranteed to be unique. -@xref{Buffer Names}. +@xref{Buffer Names}. This and the following fields have their names +in the C struct definition end in a @code{_} to indicate that they +should not be accessed directly, but via the @code{BVAR} macro, like +this: + +@example + Lisp_Object buf_name = BVAR (buffer, name); +@end example @item save_length The length of the file this buffer is visiting, when last read or -saved. This and other fields concerned with saving are not kept in -the @code{buffer_text} structure because indirect buffers are never -saved. +saved. It can have 2 special values: @minus{}1 means auto-saving was +turned off in this buffer, and @minus{}2 means don't turn off +auto-saving if buffer text shrinks a lot. This and other fields +concerned with saving are not kept in the @code{buffer_text} structure +because indirect buffers are never saved. @item directory The directory for expanding relative file names. This is the value of @@ -2020,75 +2116,104 @@ if that window no longer displays this buffer. @table @code @item frame -The frame that this window is on. +The frame that this window is on, as a Lisp object. + +@item mini +Non-zero if this window is a minibuffer window, a window showing the +minibuffer or the echo area. -@item mini_p -Non-@code{nil} if this window is a minibuffer window. +@item pseudo_window_p +@cindex pseudo window +Non-zero if this window is a @dfn{pseudo window}. A pseudo window is +either a window used to display the menu bar or the tool bar (when +Emacs uses toolkits that don't display their own menu bar and tool +bar) or a window showing a tooltip on a tooltip frame. Pseudo windows +are in general not accessible from Lisp code. @item parent -Internally, Emacs arranges windows in a tree; each group of siblings has -a parent window whose area includes all the siblings. This field points -to a window's parent. +Internally, Emacs arranges windows in a tree; each group of siblings +has a parent window whose area includes all the siblings. This field +points to the window's parent in that tree, as a Lisp object. For the +root window of the tree and a minibuffer window this is always +@code{nil}. Parent windows do not display buffers, and play little role in display -except to shape their child windows. Emacs Lisp programs usually have -no access to the parent windows; they operate on the windows at the +except to shape their child windows. Emacs Lisp programs cannot +directly manipulate parent windows; they operate on the windows at the leaves of the tree, which actually display buffers. -@c FIXME: These two slots and the 'buffer' slot below were replaced -@c with a single slot 'contents' on 2013-03-28. --xfq -@item hchild -@itemx vchild -These fields contain the window's leftmost child and its topmost child -respectively. @code{hchild} is used if the window is subdivided -horizontally by child windows, and @code{vchild} if it is subdivided -vertically. In a live window, only one of @code{hchild}, @code{vchild}, -and @code{buffer} (q.v.@:) is non-@code{nil}. +@item contents +For a leaf window and windows showing a tooltip, this is the buffer, +as a Lisp object, that the window is displaying. For an internal +(``parent'') window, this is its first child window. For a pseudo +window showing a menu or tool bar this is @code{nil}. It is also +@code{nil} for a window that has been deleted. @item next @itemx prev -The next sibling and previous sibling of this window. @code{next} is -@code{nil} if the window is the right-most or bottom-most in its group; -@code{prev} is @code{nil} if it is the left-most or top-most in its -group. +The next and previous sibling of this window as Lisp objects. +@code{next} is @code{nil} if the window is the right-most or +bottom-most in its group; @code{prev} is @code{nil} if it is the +left-most or top-most in its group. Whether the sibling is left/right +or up/down is determined by the @code{horizontal} field of the +sibling's parent: if it's non-zero, the siblings are arranged +horizontally. + +As a special case, @code{next} of a frame's root window points to the +frame's minibuffer window, provided this is not a minibuffer-only or +minibuffer-less frame. On such frames @code{prev} of the minibuffer +window points to that frame's root window. In any other case, the +root window's @code{next} and the minibuffer window's (if present) +@code{prev} fields are @code{nil}. @item left_col The left-hand edge of the window, measured in columns, relative to the -leftmost column in the frame (column 0). +leftmost column (column 0) of the window's native frame. @item top_line The top edge of the window, measured in lines, relative to the topmost -line in the frame (line 0). +line (line 0) of the window's native frame. + +@item pixel_left +@itemx pixel_top +The left-hand and top edges of this window, measured in pixels, +relative to the top-left corner (0, 0) of the window's native frame. @item total_cols @itemx total_lines -The width and height of the window, measured in columns and lines -respectively. The width includes the scroll bar and fringes, and/or -the separator line on the right of the window (if any). +The total width and height of the window, measured in columns and +lines respectively. The values include scroll bars and fringes, +dividers and/or the separator line on the right of the window (if +any). -@item buffer -The buffer that the window is displaying. +@item pixel_width; +@itemx pixel_height; +The total width and height of the window measured in pixels. @item start A marker pointing to the position in the buffer that is the first -character displayed in the window. +character (in the logical order, @pxref{Bidirectional Display}) +displayed in the window. @item pointm @cindex window point internals This is the value of point in the current buffer when this window is selected; when it is not selected, it retains its previous value. +@item old_pointm +The value of @code{pointm} at the last redisplay time. + @item force_start If this flag is non-@code{nil}, it says that the window has been -scrolled explicitly by the Lisp program. This affects what the next -redisplay does if point is off the screen: instead of scrolling the -window to show the text around point, it moves point to a location that -is on the screen. +scrolled explicitly by the Lisp program, and the value of the the +window's @code{start} was set for redisplay to honor. This affects +what the next redisplay does if point is off the screen: instead of +scrolling the window to show the text around point, it moves point to +a location that is on the screen. -@item frozen_window_start_p -This field is set temporarily to 1 to indicate to redisplay that -@code{start} of this window should not be changed, even if point -gets invisible. +@item optional_new_start +This is similar to @code{force_start}, but the next redisplay will +only obey it if point stays visible. @item start_at_line_beg Non-@code{nil} means current value of @code{start} was the beginning of a line @@ -2114,30 +2239,36 @@ The buffer's value of point, as of the last time a redisplay completed in this window. @item last_had_star -A non-@code{nil} value means the window's buffer was modified when the +A non-zero value means the window's buffer was modified when the window was last updated. -@item vertical_scroll_bar -This window's vertical scroll bar. +@item vertical_scroll_bar_type +@itemx horizontal_scroll_bar_type +The types of this window's vertical and horizontal scroll bars. + +@item scroll_bar_width +@itemx scroll_bar_height +The width of this window's vertical scroll bar and the height of this +window's horizontal scroll bar, in pixels. @item left_margin_cols @itemx right_margin_cols The widths of the left and right margins in this window. A value of -@code{nil} means no margin. +zero means no margin. @item left_fringe_width @itemx right_fringe_width -The widths of the left and right fringes in this window. A value of -@code{nil} or @code{t} means use the values of the frame. +The pixel widths of the left and right fringes in this window. A +value of @minus{}1 means use the values of the frame. @item fringes_outside_margins -A non-@code{nil} value means the fringes outside the display margins; +A non-zero value means the fringes outside the display margins; othersize they are between the margin and the text. @item window_end_pos This is computed as @code{z} minus the buffer position of the last glyph in the current matrix of the window. The value is only valid if -@code{window_end_valid} is not @code{nil}. +@code{window_end_valid} is non-zero. @item window_end_bytepos The byte position corresponding to @code{window_end_pos}. @@ -2147,16 +2278,17 @@ The window-relative vertical position of the line containing @code{window_end_pos}. @item window_end_valid -This field is set to a non-@code{nil} value if @code{window_end_pos} is truly -valid. This is @code{nil} if nontrivial redisplay is pre-empted, since in that -case the display that @code{window_end_pos} was computed for did not get -onto the screen. +This field is set to a non-zero value if @code{window_end_pos} and +@code{window_end_vpos} are truly valid. This is zero if nontrivial +redisplay is pre-empted, since in that case the display that +@code{window_end_pos} was computed for did not get onto the screen. @item cursor A structure describing where the cursor is in this window. -@item last_cursor -The value of @code{cursor} as of the last redisplay that finished. +@item last_cursor_vpos +The window-relative vertical position of the line showing the cursor +as of the last redisplay that finished. @item phys_cursor A structure describing where the cursor of this window physically is. @@ -2184,8 +2316,16 @@ the last redisplay. This is set to 1 during redisplay when this window must be updated. @item hscroll -This is the number of columns that the display in the window is scrolled -horizontally to the left. Normally, this is 0. +This is the number of columns that the display in the window is +scrolled horizontally to the left. Normally, this is 0. When only +the current line is hscrolled, this describes how much the current +line is scrolled. + +@item min_hscroll +Minimum value of @code{hscroll}, set by the user via +@code{set-window-hscroll} (@pxref{Horizontal Scrolling}). When only +the current line is hscrolled, this describes the horizontal scrolling +of lines other than the current one. @item vscroll Vertical scroll amount, in pixels. Normally, this is 0. @@ -2193,24 +2333,37 @@ Vertical scroll amount, in pixels. Normally, this is 0. @item dedicated Non-@code{nil} if this window is dedicated to its buffer. +@item combination_limit +This window's combination limit, meaningful only for a parent window. +If this is @code{t}, then it is not allowed to delete this window and +recombine its child windows with other siblings of this window. + +@item window_parameters +The alist of this window's parameters. + @item display_table The window's display table, or @code{nil} if none is specified for it. @item update_mode_line -Non-@code{nil} means this window's mode line needs to be updated. +Non-zero means this window's mode line needs to be updated. + +@item mode_line_height +@itemx header_line_height +The height in pixels of the mode line and the header line, or +@minus{}1 if not known. @item base_line_number -The line number of a certain position in the buffer, or @code{nil}. +The line number of a certain position in the buffer, or zero. This is used for displaying the line number of point in the mode line. @item base_line_pos The position in the buffer for which the line number is known, or -@code{nil} meaning none is known. If it is a buffer, don't display +zero meaning none is known. If it is @minus{}1, don't display the line number as long as the window shows that buffer. @item column_number_displayed -The column number currently displayed in this window's mode line, or @code{nil} -if column numbers are not being displayed. +The column number currently displayed in this window's mode line, or +@minus{}1 if column numbers are not being displayed. @item current_matrix @itemx desired_matrix @@ -2227,7 +2380,7 @@ Glyph matrices describing the current and desired display of this window. @table @code @item name -A string, the name of the process. +A Lisp string, the name of the process. @item command A list containing the command arguments that were used to start this @@ -2235,10 +2388,10 @@ process. For a network or serial process, it is @code{nil} if the process is running or @code{t} if the process is stopped. @item filter -A function used to accept output from the process. +A Lisp function used to accept output from the process. @item sentinel -A function called whenever the state of the process changes. +A Lisp function called whenever the state of the process changes. @item buffer The associated buffer of the process. @@ -2265,7 +2418,8 @@ does not ask for confirmation about killing the process. The raw process status, as returned by the @code{wait} system call. @item status -The process status, as @code{process-status} should return it. +The process status, as @code{process-status} should return it. This +is a Lisp symbol, a cons cell, or a list. @item tick @itemx update_tick @@ -2274,8 +2428,8 @@ needs to be reported, either by running the sentinel or by inserting a message in the process buffer. @item pty_flag -Non-@code{nil} if communication with the subprocess uses a pty; -@code{nil} if it uses a pipe. +Non-zero if communication with the subprocess uses a pty; zero if it +uses a pipe. @item infd The file descriptor for input from the process. diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index 197f54ecc52..2596e87939b 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi @@ -1,6 +1,6 @@ @c -*-coding: utf-8-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 2001-2018 Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 2001-2019 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Introduction @@ -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 d9d213df15a..6ad665a9502 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -1,6 +1,6 @@ @c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-2018 Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 1998-2019 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Keymaps @chapter Keymaps @@ -2502,7 +2502,7 @@ can do it this way: Emacs usually shows a @dfn{menu bar} at the top of each frame. @xref{Menu Bars,,,emacs, The GNU Emacs Manual}. Menu bar items are -subcommands of the fake function key @code{menu-bar}, as defined +subcommands of the fake function key @key{MENU-BAR}, as defined in the active keymaps. To add an item to the menu bar, invent a fake function key of your @@ -2554,9 +2554,10 @@ bar item: @end example @noindent -Here, @code{edit} is the fake function key used by the global map for -the @samp{Edit} menu bar item. The main reason to suppress a global -menu bar item is to regain space for mode-specific items. +Here, @code{edit} is the symbol produced by a fake function key, it is +used by the global map for the @samp{Edit} menu bar item. The main +reason to suppress a global menu bar item is to regain space for +mode-specific items. @defvar menu-bar-final-items Normally the menu bar shows global items followed by items defined by the @@ -2601,7 +2602,7 @@ If the value is @code{grow-only}, the tool bar expands automatically, but does not contract automatically. The tool bar contents are controlled by a menu keymap attached to a -fake function key called @code{tool-bar} (much like the way the menu +fake function key called @key{TOOL-BAR} (much like the way the menu bar is controlled). So you define a tool bar item using @code{define-key}, like this: diff --git a/doc/lispref/lay-flat.texi b/doc/lispref/lay-flat.texi index da2215906d1..1f12efe3559 100644 --- a/doc/lispref/lay-flat.texi +++ b/doc/lispref/lay-flat.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001-2018 Free Software Foundation, Inc. +@c Copyright (C) 2001-2019 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @c @comment %**start of header diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 1548dd49b2f..746b4643c18 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Lists @@ -656,7 +656,7 @@ resulting list. Instead, the sequence becomes the final @sc{cdr}, like any other non-list final argument. @defun copy-tree tree &optional vecp -This function returns a copy of the tree @code{tree}. If @var{tree} is a +This function returns a copy of the tree @var{tree}. If @var{tree} is a cons cell, this makes a new cons cell with the same @sc{car} and @sc{cdr}, then recursively copies the @sc{car} and @sc{cdr} in the same way. @@ -667,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}, diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 6f15cd9c60a..6f1213f097b 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Loading diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi index dbd35b48484..a422ba9750d 100644 --- a/doc/lispref/macros.texi +++ b/doc/lispref/macros.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998, 2001-2018 Free Software Foundation, +@c Copyright (C) 1990-1995, 1998, 2001-2019 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Macros diff --git a/doc/lispref/maps.texi b/doc/lispref/maps.texi index fc40f28ded8..bcf8f175e09 100644 --- a/doc/lispref/maps.texi +++ b/doc/lispref/maps.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1999, 2001-2018 Free Software Foundation, +@c Copyright (C) 1990-1993, 1999, 2001-2019 Free Software Foundation, @c Inc. @c See the file elisp.texi for copying conditions. @node Standard Keymaps diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi index 349ec12aa81..27fe1414f09 100644 --- a/doc/lispref/markers.texi +++ b/doc/lispref/markers.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Markers diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 5c660551d23..6c37fa92d6c 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Minibuffers @@ -1108,11 +1108,11 @@ different function to completely override the normal behavior of in the minibuffer to do completion. @defvar minibuffer-completion-table -The value of this variable is the completion table used for completion -in the minibuffer. This is the global variable that contains what -@code{completing-read} passes to @code{try-completion}. It is used by -minibuffer completion commands such as -@code{minibuffer-complete-word}. +The value of this variable is the completion table (@pxref{Basic +Completion}) used for completion in the minibuffer. This is the +global variable that contains what @code{completing-read} passes to +@code{try-completion}. It is used by minibuffer completion commands +such as @code{minibuffer-complete-word}. @end defvar @defvar minibuffer-completion-predicate @@ -1770,7 +1770,8 @@ possible match, and ignore the match if the predicate returns @code{nil}. @item -A flag specifying the type of completion operation to perform. This +A flag specifying the type of completion operation to perform; see +@ref{Basic Completion}, for the details of those operations. This flag may be one of the following values. @table @code @@ -1841,17 +1842,26 @@ the same as for @code{display-sort-function}. @defun completion-table-dynamic function &optional switch-buffer This function is a convenient way to write a function that can act as -a programmed completion function. The argument @var{function} should be -a function that takes one argument, a string, and returns an alist of -possible completions of it. It is allowed to ignore the argument and -return a full list of all possible completions. You can think of -@code{completion-table-dynamic} as a transducer between that interface +a programmed completion function. The argument @var{function} should +be a function that takes one argument, a string, and returns a +completion table (@pxref{Basic Completion}) containing all the +possible completions. The table returned by @var{function} can also +include elements that don't match the string argument; they are +automatically filtered out by @code{completion-table-dynamic}. In +particular, @var{function} can ignore its argument and return a full +list of all possible completions. You can think of +@code{completion-table-dynamic} as a transducer between @var{function} and the interface for programmed completion functions. If the optional argument @var{switch-buffer} is non-@code{nil}, and completion is performed in the minibuffer, @var{function} will be called with current buffer set to the buffer from which the minibuffer was entered. + +The return value of @code{completion-table-dynamic} is a function that +can be used as the 2nd argument to @code{try-completion} and +@code{all-completions}. Note that this function will always return +empty metadata and trivial boundaries (@pxref{Programmed Completion}). @end defun @defun completion-table-with-cache function &optional ignore-case @@ -1876,9 +1886,10 @@ Emacs Manual}. This command uses the abnormal hook variable @defvar completion-at-point-functions The value of this abnormal hook should be a list of functions, which -are used to compute a completion table for completing the text at -point. It can be used by major modes to provide mode-specific -completion tables (@pxref{Major Mode Conventions}). +are used to compute a completion table (@pxref{Basic Completion}) for +completing the text at point. It can be used by major modes to +provide mode-specific completion tables (@pxref{Major Mode +Conventions}). When the command @code{completion-at-point} runs, it calls the functions in the list one by one, without any argument. Each function @@ -2391,6 +2402,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 diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 49b7e1ea3fb..1afbc5a5cee 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Modes @@ -1015,6 +1015,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 @@ -1121,6 +1144,65 @@ that tags placed via @code{tabulated-list-put-tag} will not be removed from entries that haven't changed (normally all tags are removed). @end defun +@defun tabulated-list-delete-entry +This function deletes the entry at point. + +It returns a list @code{(@var{id} @var{cols})}, where @var{id} is the +ID of the deleted entry and @var{cols} is a vector of its column +descriptors. It moves point to the beginning of the current line. It +returns @code{nil} if there is no entry at point. + +Note that this function only changes the buffer contents; it does not +alter @code{tabulated-list-entries}. +@end defun + +@defun tabulated-list-get-id &optional pos +This @code{defsubst} returns the ID object from +@code{tabulated-list-entries} (if that is a list) or from the list +returned by @code{tabulated-list-entries} (if it is a function). If +omitted or @code{nil}, @var{pos} defaults to point. +@end defun + +@defun tabulated-list-get-entry &optional pos +This @code{defsubst} returns the entry object from +@code{tabulated-list-entries} (if that is a list) or from the list +returned by @code{tabulated-list-entries} (if it is a function). This +will be a vector for the ID at @var{pos}. If there is no entry at +@var{pos}, then the function returns @code{nil}. +@end defun + +@vindex tabulated-list-use-header-line +@defun tabulated-list-header-overlay-p &optional POS +This @code{defsubst} returns non-nil if there is a fake header at +@var{pos}. A fake header is used if +@code{tabulated-list-use-header-line} is @code{nil} to put the column +names at the beginning of the buffer. If omitted or @code{nil}, +@var{pos} defaults to @code{point-min}. +@end defun + +@vindex tabulated-list-padding +@defun tabulated-list-put-tag tag &optional advance +This function puts @var{tag} in the padding area of the current line. +The padding area can be empty space at the beginning of the line, the +width of which is governed by @code{tabulated-list-padding}. +@var{tag} should be a string, with a length less than or equal to +@code{tabulated-list-padding}. If @var{advance} is non-nil, this +function advances point by one line. +@end defun + +@defun tabulated-list-set-col col desc &optional change-entry-data +This function changes the tabulated list entry at point, setting +@var{col} to @var{desc}. @var{col} is the column number to change, or +the name of the column to change. @var{desc} is the new column +descriptor, which is inserted via @code{tabulated-list-print-col}. + +If @var{change-entry-data} is non-nil, this function modifies the +underlying data (usually the column descriptor in the list +@code{tabulated-list-entries}) by setting the column descriptor of the +vector to @code{desc}. +@end defun + + @node Generic Modes @subsection Generic Modes @cindex generic mode @@ -1178,6 +1260,7 @@ the conventions listed above: (modify-syntax-entry ?\\ ". " st) ;; Add 'p' so M-c on 'hello' leads to 'Hello', not 'hello'. (modify-syntax-entry ?' "w p" st) + @dots{} st) "Syntax table used while in `text-mode'.") @end group @@ -1187,6 +1270,7 @@ the conventions listed above: (defvar text-mode-map (let ((map (make-sparse-keymap))) (define-key map "\e\t" 'ispell-complete-word) + @dots{} map) "Keymap for `text-mode'. Many other modes, such as `mail-mode', `outline-mode' and @@ -1230,11 +1314,11 @@ illustrate how these modes are written. @smallexample @group ;; @r{Create mode-specific table variables.} -(defvar lisp-mode-abbrev-table nil) -(define-abbrev-table 'lisp-mode-abbrev-table ()) +(define-abbrev-table 'lisp-mode-abbrev-table () + "Abbrev table for Lisp mode.") (defvar lisp-mode-syntax-table - (let ((table (copy-syntax-table emacs-lisp-mode-syntax-table))) + (let ((table (make-syntax-table lisp--mode-syntax-table))) (modify-syntax-entry ?\[ "_ " table) (modify-syntax-entry ?\] "_ " table) (modify-syntax-entry ?# "' 14" table) @@ -1249,10 +1333,9 @@ each calls the following function to set various variables: @smallexample @group -(defun lisp-mode-variables (&optional syntax keywords-case-insensitive) +(defun lisp-mode-variables (&optional syntax keywords-case-insensitive elisp) (when syntax (set-syntax-table lisp-mode-syntax-table)) - (setq local-abbrev-table lisp-mode-abbrev-table) @dots{} @end group @end smallexample @@ -1263,8 +1346,7 @@ variable to handle Lisp comments: @smallexample @group - (make-local-variable 'comment-start) - (setq comment-start ";") + (setq-local comment-start ";") @dots{} @end group @end smallexample @@ -1278,6 +1360,7 @@ common. The following code sets up the common commands: @group (defvar lisp-mode-shared-map (let ((map (make-sparse-keymap))) + (set-keymap-parent map prog-mode-map) (define-key map "\e\C-q" 'indent-sexp) (define-key map "\177" 'backward-delete-char-untabify) map) @@ -1292,7 +1375,7 @@ And here is the code to set up the keymap for Lisp mode: @group (defvar lisp-mode-map (let ((map (make-sparse-keymap)) - (menu-map (make-sparse-keymap "Lisp"))) + (menu-map (make-sparse-keymap "Lisp"))) (set-keymap-parent map lisp-mode-shared-map) (define-key map "\e\C-x" 'lisp-eval-defun) (define-key map "\C-c\C-z" 'run-lisp) @@ -1316,17 +1399,13 @@ Blank lines separate paragraphs. Semicolons start comments. \\@{lisp-mode-map@} Note that `run-lisp' may be used either to start an inferior Lisp job -or to switch back to an existing one. +or to switch back to an existing one." @end group - @group -Entry to this mode calls the value of `lisp-mode-hook' -if that value is non-nil." (lisp-mode-variables nil t) - (set (make-local-variable 'find-tag-default-function) - 'lisp-find-tag-default) - (set (make-local-variable 'comment-start-skip) - "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") + (setq-local find-tag-default-function 'lisp-find-tag-default) + (setq-local comment-start-skip + "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *") (setq imenu-case-fold-search t)) @end group @end smallexample @@ -1366,7 +1445,7 @@ The value of this variable is a list of all minor mode commands. @cindex conventions for writing minor modes There are conventions for writing minor modes just as there are for -major modes. These conventions are described below. The easiest way to +major modes (@pxref{Major Modes}). These conventions are described below. The easiest way to follow them is to use the macro @code{define-minor-mode}. @xref{Defining Minor Modes}. @@ -1477,10 +1556,10 @@ or like this, using @code{add-to-list} (@pxref{List Variables}): @end smallexample @end itemize - In addition, several major mode conventions apply to minor modes as -well: those regarding the names of global symbols, the use of a hook at -the end of the initialization function, and the use of keymaps and other -tables. + In addition, several major mode conventions (@pxref{Major Mode +Conventions}) apply to minor modes as well: those regarding the names +of global symbols, the use of a hook at the end of the initialization +function, and the use of keymaps and other tables. The minor mode should, if possible, support enabling and disabling via Custom (@pxref{Customization}). To do this, the mode variable should be diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index 9fb5587521d..9c64c3cf2ca 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -1,6 +1,6 @@ @c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998-1999, 2001-2018 Free Software Foundation, Inc. +@c Copyright (C) 1998-1999, 2001-2019 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Non-ASCII Characters @chapter Non-@acronym{ASCII} Characters @@ -287,12 +287,11 @@ unibyte string, it is returned unchanged. Use this function for characters. @end defun -@c FIXME: Should '@var{character}' be '@var{byte}'? @defun byte-to-string byte @cindex byte to string This function returns a unibyte string containing a single byte of -character data, @var{character}. It signals an error if -@var{character} is not an integer between 0 and 255. +character data, @var{byte}. It signals an error if @var{byte} is not +an integer between 0 and 255. @end defun @defun multibyte-char-to-unibyte char @@ -1379,7 +1378,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, @@ -1633,11 +1632,16 @@ coding system for a file based on its undecoded contents. Each function in this list should be written to look at text in the current buffer, but should not modify it in any way. The buffer will -contain undecoded text of parts of the file. Each function should -take one argument, @var{size}, which tells it how many characters to -look at, starting from point. If the function succeeds in determining -a coding system for the file, it should return that coding system. -Otherwise, it should return @code{nil}. +contain the text of parts of the file. Each function should take one +argument, @var{size}, which tells it how many characters to look at, +starting from point. If the function succeeds in determining a coding +system for the file, it should return that coding system. Otherwise, +it should return @code{nil}. + +The functions in this list could be called either when the file is +visited and Emacs wants to decode its contents, and/or when the file's +buffer is about to be saved and Emacs wants to determine how to encode +its contents. If a file has a @samp{coding:} tag, that takes precedence, so these functions won't be called. @@ -2116,9 +2120,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 d03113674f5..fbdd83fa86e 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Numbers @@ -313,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 diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index a0940032eee..745baacc297 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -1,6 +1,6 @@ @c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Lisp Data Types diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index cb337573259..59cd5a8fe8a 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node System Interface @@ -1230,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 @@ -1308,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. @@ -1538,7 +1544,28 @@ Time values include @code{nil}, numbers, and Lisp timestamps @defun date-to-time string This function parses the time-string @var{string} and returns the -corresponding Lisp timestamp. +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. +@end defun + +@defun parse-time-string string +This function parses the time-string @var{string} into a list of the +following form: + +@example +(@var{sec} @var{min} @var{hour} @var{day} @var{mon} @var{year} @var{dow} @var{dst} @var{tz}) +@end example + +@noindent +The format of this list is the same as what @code{decode-time} accepts +(@pxref{Time Conversion}), and is described in more detail there. Any +element that cannot be determined from the input will be set to +@code{nil}. The argument @var{string} should resemble an RFC 822 (or later) or +ISO 8601 string, like ``Fri, 25 Mar 2016 16:24:56 +0100'' or +``1998-09-12T12:21:54-0200'', but this function will attempt to parse +less well-formed time strings as well. @end defun @defun format-time-string format-string &optional time zone @@ -1573,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 @@ -1653,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. diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi index 37c1ee6697d..7244efbd8f7 100644 --- a/doc/lispref/package.texi +++ b/doc/lispref/package.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2010-2018 Free Software Foundation, Inc. +@c Copyright (C) 2010-2019 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Packaging @chapter Preparing Lisp code for distribution @@ -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 @@ -249,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}. @@ -311,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 @@ -393,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/positions.texi b/doc/lispref/positions.texi index a09b6b6d097..527a3ab420c 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -1,6 +1,6 @@ @c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2018 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2019 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Positions @chapter Positions diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index d88c7fbe622..6be311b5639 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Processes @@ -423,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} @@ -459,7 +459,9 @@ present in @var{args}. To avoid confusion, it may be best to avoid absolute file names in @var{args}, but rather to specify all file names as relative to @code{default-directory}. The function @code{file-relative-name} is useful for constructing such relative -file names. +file names. Alternatively, you can use @code{file-local-name} +(@pxref{Magic File Names}) to obtain an absolute file name as seen +from the remote host's perspective. @end defun @defvar process-file-side-effects @@ -468,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 @@ -612,10 +614,9 @@ these features. However, for subprocesses used by Lisp programs for internal purposes (i.e., no user interaction with the subprocess is required), where significant amounts of data need to be exchanged between the subprocess and the Lisp program, it is often better to use -a pipe, because pipes are more efficient, and because they are immune -to stray character injections that ptys introduce for large (around -500 byte) messages. Also, the total number of ptys is limited on many -systems, and it is good not to waste them unnecessarily. +a pipe, because pipes are more efficient. Also, the total number of +ptys is limited on many systems, and it is good not to waste them +unnecessarily. @defun make-process &rest args This function is the basic low-level primitive for starting @@ -696,6 +697,12 @@ non-@code{nil} value should be either a buffer or a pipe process 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}. + +@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 @@ -703,9 +710,18 @@ 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. @xref{Filter Functions}, and @ref{Sentinels}. + +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 @@ -821,22 +837,27 @@ 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 the working directory of the process. This function does not try to invoke file name handlers for -@var{program} or for the rest of @var{args}. - -Depending on the implementation of the file handler, it might not be +@var{program} or for the rest of @var{args}. For that reason, if +@var{program} or any of @var{args} use the remote-file syntax +(@pxref{Magic File Names}), they must be converted either to file +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 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 @@ -1768,7 +1789,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 @@ -1806,7 +1827,8 @@ until output arrives from a process. This function allows Emacs to read pending output from processes. The output is given to their filter functions. If @var{process} is non-@code{nil} then this function does not return until some output -has been received from @var{process}. +has been received from @var{process} or @var{process} has closed the +connection. The arguments @var{seconds} and @var{millisec} let you specify timeout periods. The former specifies a period measured in seconds and the @@ -1831,10 +1853,32 @@ speech synthesis. The function @code{accept-process-output} returns non-@code{nil} if it got output from @var{process}, or from any process if @var{process} is -@code{nil}. It returns @code{nil} if the timeout expired before output +@code{nil}; this can occur even after a process has exited if the +corresponding connection contains buffered data. The function returns +@code{nil} if the timeout expired or the connection was closed before output arrived. @end defun +If a connection from a process contains buffered data, +@code{accept-process-output} can return non-@code{nil} even after the +process has exited. Therefore, although the following loop: + +@example +;; This loop contains a bug. +(while (process-live-p process) + (accept-process-output process)) +@end example + +@noindent +will often read all output from @var{process}, it has a race condition +and can miss some output if @code{process-live-p} returns @code{nil} +while the connection still contains data. Better is to write the loop +like this: + +@example +(while (accept-process-output process)) +@end example + @node Processes and Threads @subsection Processes and Threads @cindex processes, threads @@ -2596,7 +2640,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, diff --git a/doc/lispref/records.texi b/doc/lispref/records.texi index 81a52341b12..3a89b687351 100644 --- a/doc/lispref/records.texi +++ b/doc/lispref/records.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2017-2018 Free Software Foundation, Inc. +@c Copyright (C) 2017-2019 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Records @chapter Records diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index 1b6b80d31b2..0f312915f9e 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Searching and Matching @@ -406,13 +406,13 @@ Note also that 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 put it after 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 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 last character of the character alternative, +tho you can also put it first or after 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. @@ -559,7 +559,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{-}. @@ -950,7 +950,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, @@ -960,6 +960,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 @@ -985,8 +988,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) diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 6a6f4d5c82e..a7f270c0680 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Sequences Arrays Vectors @@ -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 @@ -1049,15 +1050,18 @@ that @var{sequence} can be a list, vector or string. This is primarily useful for side-effects. @end defmac -@defmac seq-let arguments sequence body@dots{} +@anchor{seq-let} +@defmac seq-let var-sequence val-sequence body@dots{} @cindex sequence destructuring - This macro binds the variables defined in @var{arguments} to the -elements of @var{sequence}. @var{arguments} can themselves include -sequences, allowing for nested destructuring. + This macro binds the variables defined in @var{var-sequence} to the +values that are the corresponding elements of @var{val-sequence}. +This is known as @dfn{destructuring binding}. The elements of +@var{var-sequence} can themselves include sequences, allowing for +nested destructuring. -The @var{arguments} sequence can also include the @code{&rest} marker -followed by a variable name to be bound to the rest of -@code{sequence}. +The @var{var-sequence} sequence can also include the @code{&rest} +marker followed by a variable name to be bound to the rest of +@var{val-sequence}. @example @group @@ -1081,6 +1085,9 @@ followed by a variable name to be bound to the rest of @end group @result{} [3 4] @end example + +The @code{pcase} patterns provide an alternative facility for +destructuring binding, see @ref{Destructuring with pcase Patterns}. @end defmac @defun seq-random-elt sequence @@ -1771,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/streams.texi b/doc/lispref/streams.texi index 032669cb102..600639f244f 100644 --- a/doc/lispref/streams.texi +++ b/doc/lispref/streams.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1994, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Read and Print diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 3558f17301d..521f163663d 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -1,6 +1,6 @@ @c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Strings and Characters diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index 11e92f6217f..a214a2d3fd8 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Symbols diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi index dcfade3f67d..b0c04ef9c25 100644 --- a/doc/lispref/syntax.texi +++ b/doc/lispref/syntax.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Syntax Tables @@ -556,8 +556,8 @@ the current syntax table in the usual way. @defvar parse-sexp-lookup-properties If this is non-@code{nil}, the syntax scanning functions, like -@code{forward-sexp}, pay attention to syntax text properties. -Otherwise they use only the current syntax table. +@code{forward-sexp}, pay attention to @code{syntax-table} text +properties. Otherwise they use only the current syntax table. @end defvar @defvar syntax-propertize-function @@ -927,9 +927,9 @@ nicely. @defvar multibyte-syntax-as-symbol If this variable is non-@code{nil}, @code{scan-sexps} treats all -non-@acronym{ASCII} characters as symbol constituents regardless -of what the syntax table says about them. (However, text properties -can still override the syntax.) +non-@acronym{ASCII} characters as symbol constituents regardless of +what the syntax table says about them. (However, @code{syntax-table +}text properties can still override the syntax.) @end defvar @defopt parse-sexp-ignore-comments @@ -939,7 +939,6 @@ whitespace by the functions in this section and by @code{forward-sexp}, @code{scan-lists} and @code{scan-sexps}. @end defopt -@vindex parse-sexp-lookup-properties The behavior of @code{parse-partial-sexp} is also affected by @code{parse-sexp-lookup-properties} (@pxref{Syntax Properties}). @@ -1042,8 +1041,8 @@ This function returns the syntax code for the raw syntax descriptor @var{syntax-code} component, masks off the high 16 bits which record the syntax flags, and returns the resulting integer. -If @var{syntax} is @code{nil}, the return value is returns @code{nil}. -This is so that the expression +If @var{syntax} is @code{nil}, the return value is @code{nil}. This +is so that the expression @example (syntax-class (syntax-after pos)) diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index 6c38d8eed09..21c5a73f887 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2018 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2019 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Text @chapter Text @@ -500,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. @@ -3496,9 +3496,14 @@ property is obsolete; use the @code{cursor-intangible} property instead. @kindex cursor-intangible @r{(text property)} @findex cursor-intangible-mode When the minor mode @code{cursor-intangible-mode} is turned on, point -is moved away of any position that has a non-@code{nil} +is moved away from any position that has a non-@code{nil} @code{cursor-intangible} property, just before redisplay happens. +@vindex cursor-sensor-inhibit +When the variable @code{cursor-sensor-inhibit} is non-@code{nil}, the +@code{cursor-intangible} property and the +@code{cursor-sensor-functions} property (described below) are ignored. + @item field @kindex field @r{(text property)} Consecutive characters with the same @code{field} property constitute a @@ -3680,6 +3685,9 @@ depending on whether the cursor is entering the text that has this property or leaving it. The functions are called only when the minor mode @code{cursor-sensor-mode} is turned on. +When the variable @code{cursor-sensor-inhibit} is non-@code{nil}, the +@code{cursor-sensor-functions} property is ignored. + @item composition @kindex composition @r{(text property)} This text property is used to display a sequence of characters as a @@ -4428,22 +4436,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 @@ -5171,11 +5216,11 @@ class: @item A user interface for building JSONRPC applications -In this scenario, the JSONRPC application instantiates -@code{jsonrpc-connection} objects of one of its concrete subclasses -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 +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 @code{jsonrpc-async-request}. For handling remotely initiated contacts, which generally come in asynchronously, the instantiation should include @code{:request-dispatcher} and diff --git a/doc/lispref/threads.texi b/doc/lispref/threads.texi index c9d5f790485..db68f9192bd 100644 --- a/doc/lispref/threads.texi +++ b/doc/lispref/threads.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2012-2018 Free Software Foundation, Inc. +@c Copyright (C) 2012-2019 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Threads @chapter Threads @@ -17,9 +17,9 @@ correct programs should not rely on cooperative threading. Currently, thread switching will occur upon explicit request via @code{thread-yield}, when waiting for keyboard input or for process -output (e.g., during @code{accept-process-output}), or during blocking -operations relating to threads, such as mutex locking or -@code{thread-join}. +output from asynchronous processes (e.g., during +@code{accept-process-output}), or during blocking operations relating +to threads, such as mutex locking or @code{thread-join}. Emacs Lisp provides primitives to create and control threads, and also to create and control mutexes and condition variables, useful for diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 08cc10da14c..d41fe825729 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -1,6 +1,6 @@ @c -*- mode: texinfo; coding: utf-8 -*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1993, 1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Tips @@ -679,10 +679,15 @@ starting double-quote is not part of the string! @cindex curly quotes @cindex curved quotes When a documentation string refers to a Lisp symbol, write it as it -would be printed (which usually means in lower case), surrounding -it with curved single quotes (@t{‘} and @t{’}). There are -two exceptions: write @code{t} and @code{nil} without surrounding -punctuation. For example: @samp{CODE can be ‘lambda’, nil, or t}. +would be printed (which usually means in lower case), surrounding it +with curved single quotes (@t{‘..’}). There are two exceptions: write +@code{t} and @code{nil} without surrounding punctuation. For example: + +@example + CODE can be ‘lambda’, nil, or t. +@end example + +@noindent @xref{Quotation Marks,,, emacs, The GNU Emacs Manual}, for how to enter curved single quotes. @@ -942,7 +947,7 @@ explains these conventions, starting with an example: @group ;;; foo.el --- Support for the Foo programming language -;; Copyright (C) 2010-2018 Your Name +;; Copyright (C) 2010-2019 Your Name @end group ;; Author: Your Name <yourname@@example.com> diff --git a/doc/lispref/two-volume-cross-refs.txt b/doc/lispref/two-volume-cross-refs.txt index b5379df38d0..e3db8ff651b 100644 --- a/doc/lispref/two-volume-cross-refs.txt +++ b/doc/lispref/two-volume-cross-refs.txt @@ -1,4 +1,4 @@ -Copyright (C) 2001-2018 Free Software Foundation, Inc. +Copyright (C) 2001-2019 Free Software Foundation, Inc. See end for copying conditions. Two Volume Cross References diff --git a/doc/lispref/two-volume.make b/doc/lispref/two-volume.make index 07a6d2c1717..63c97c23958 100644 --- a/doc/lispref/two-volume.make +++ b/doc/lispref/two-volume.make @@ -1,4 +1,4 @@ -# Copyright (C) 2007-2018 Free Software Foundation, Inc. +# Copyright (C) 2007-2019 Free Software Foundation, Inc. # See end for copying conditions. # although it would be nice to use tex rather than pdftex to avoid diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 6560660120b..aca7d2f5e93 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2018 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2019 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Variables @chapter Variables @@ -2191,9 +2191,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: @@ -2207,8 +2207,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 52bfbde41c6..6b716323357 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2018 Free Software +@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software @c Foundation, Inc. @c See the file elisp.texi for copying conditions. @node Windows @@ -25,9 +25,7 @@ is displayed in windows. * Cyclic Window Ordering:: Moving around the existing windows. * Buffers and Windows:: Each window displays the contents of a buffer. * Switching Buffers:: Higher-level functions for switching to a buffer. -* Choosing Window:: How to choose a window for displaying a buffer. -* Display Action Functions:: Subroutines for @code{display-buffer}. -* Choosing Window Options:: Extra options affecting how buffers are displayed. +* Displaying Buffers:: Displaying a buffer in a suitable window. * Window History:: Each window remembers the buffers displayed in it. * Dedicated Windows:: How to avoid displaying another buffer in a specific window. @@ -200,12 +198,13 @@ relationships between live windows. The root node of a window tree is called the @dfn{root window}. It can be either a live window (if the frame has just one window), or an internal window. - A minibuffer window (@pxref{Minibuffer Windows}) is not part of its -frame's window tree unless the frame is a minibuffer-only frame. -Nonetheless, most of the functions in this section accept the -minibuffer window as an argument. Also, the function -@code{window-tree} described at the end of this section lists the -minibuffer window alongside the actual window tree. + A minibuffer window (@pxref{Minibuffer Windows}) that is not alone +on its frame does not have a parent window, so it strictly speaking is +not part of its frame's window tree. Nonetheless, it is a sibling +window of the frame's root window, and thus can be reached via +@code{window-next-sibling}. Also, the function @code{window-tree} +described at the end of this section lists the minibuffer window +alongside the actual window tree. @defun frame-root-window &optional frame-or-window This function returns the root window for @var{frame-or-window}. The @@ -569,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 @@ -589,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 @@ -1542,11 +1529,11 @@ direction as the existing window combination (otherwise, a new internal window is created anyway). @item window-size -This means that @code{display-buffer} makes a new parent window when it -splits a window and is passed a @code{window-height} or -@code{window-width} entry in the @var{alist} argument (@pxref{Display -Action Functions}). Otherwise, window splitting behaves as for a value -of @code{nil}. +This means that @code{display-buffer} makes a new parent window when +it splits a window and is passed a @code{window-height} or +@code{window-width} entry in the @var{alist} argument (@pxref{Buffer +Display Action Functions}). Otherwise, window splitting behaves as +for a value of @code{nil}. @item temp-buffer-resize In this case @code{with-temp-buffer-window} makes a new parent window @@ -1771,7 +1758,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 @@ -1787,8 +1774,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 @@ -1800,6 +1787,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 @@ -1879,7 +1873,7 @@ most recently used one (@pxref{Cyclic Window Ordering}). @cindex ordering of windows, cyclic @cindex window ordering, cyclic - When you use the command @kbd{C-x o} (@code{other-window}) to select + When you use the command @w{@kbd{C-x o}} (@code{other-window}) to select some other window, it moves through live windows in a specific order. For any given configuration of windows, this order never varies. It is called the @dfn{cyclic ordering of windows}. @@ -1899,7 +1893,7 @@ if omitted or @code{nil}, it defaults to the selected window. The optional argument @var{minibuf} specifies whether minibuffer windows should be included in the cyclic ordering. Normally, when @var{minibuf} is @code{nil}, a minibuffer window is included only if it is currently -active; this matches the behavior of @kbd{C-x o}. (Note that a +active; this matches the behavior of @w{@kbd{C-x o}}. (Note that a minibuffer window is active as long as its minibuffer is in use; see @ref{Minibuffers}). @@ -2083,7 +2077,8 @@ variables in the specified buffer. However, if the optional argument @var{keep-margins} is non-@code{nil}, it leaves @var{window}'s display margins, fringes and scroll bar settings alone. -When writing an application, you should normally use the higher-level +When writing an application, you should normally use +@code{display-buffer} (@pxref{Choosing Window}) or the higher-level functions described in @ref{Switching Buffers}, instead of calling @code{set-window-buffer} directly. @@ -2168,7 +2163,6 @@ frame on its terminal, the buffer is replaced anyway. @node Switching Buffers @section Switching to a Buffer in a Window @cindex switching to a buffer -@cindex displaying a buffer This section describes high-level functions for switching to a specified buffer in some window. In general, ``switching to a buffer'' means to @@ -2264,6 +2258,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. @@ -2327,32 +2327,70 @@ unless @var{norecord} is non-@code{nil}. @end deffn +@node Displaying Buffers +@section Displaying a Buffer in a Suitable Window +@cindex buffer display +@cindex displaying a buffer + +This section describes lower-level functions Emacs uses to find or +create a window for displaying a specified buffer. The common +workhorse of these functions is @code{display-buffer} which eventually +handles all incoming requests for buffer display (@pxref{Choosing +Window}). + + @code{display-buffer} delegates the task of finding a suitable +window to so-called action functions (@pxref{Buffer Display Action +Functions}). First, @code{display-buffer} compiles a so-called action +alist---a special association list that action functions can use to +fine-tune their behavior. Then it passes that alist on to each action +function it calls (@pxref{Buffer Display Action Alists}). + + The behavior of @code{display-buffer} is highly customizable. To +understand how customizations are used in practice, you may wish to +study examples illustrating the order of precedence which +@code{display-buffer} uses to call action functions (@pxref{Precedence +of Action Functions}). To avoid conflicts between Lisp programs +calling @code{display-buffer} and user customizations of its behavior, +it may make sense to follow a number of guidelines which are sketched +in the final part of this section (@pxref{The Zen of Buffer Display}). + +@menu +* Choosing Window:: How to choose a window for displaying a buffer. +* Buffer Display Action Functions:: Support functions for buffer display. +* Buffer Display Action Alists:: Alists for fine-tuning buffer display. +* Choosing Window Options:: Extra options affecting how buffers are displayed. +* Precedence of Action Functions:: Examples to explain the precedence of + action functions. +* The Zen of Buffer Display:: How to avoid that buffers get lost in between + windows. +@end menu + + @node Choosing Window -@section Choosing a Window for Display +@subsection Choosing a Window for Displaying a Buffer - The command @code{display-buffer} flexibly chooses a window for +The command @code{display-buffer} flexibly chooses a window for display, and displays a specified buffer in that window. It can be called interactively, via the key binding @kbd{C-x 4 C-o}. It is also used as a subroutine by many functions and commands, including @code{switch-to-buffer} and @code{pop-to-buffer} (@pxref{Switching Buffers}). +@cindex buffer display display action @cindex display action -@cindex action function, for @code{display-buffer} -@cindex action alist, for @code{display-buffer} This command performs several complex steps to find a window to display in. These steps are described by means of @dfn{display -actions}, which have the form @code{(@var{function} . @var{alist})}. -Here, @var{function} is either a function or a list of functions, -which we refer to as @dfn{action functions}; @var{alist} is an -association list, which we refer to as an @dfn{action alist}. +actions}, which have the form @code{(@var{functions} . @var{alist})}. +Here, @var{functions} is either a single function or a list of +functions, referred to as ``action functions'' (@pxref{Buffer Display +Action Functions}); and @var{alist} is an association list, referred +to as ``action alist'' (@pxref{Buffer Display Action Alists}). +@xref{The Zen of Buffer Display}, for samples of display actions. An action function accepts two arguments: the buffer to display and an action alist. It attempts to display the buffer in some window, picking or creating a window according to its own criteria. If successful, it returns the window; otherwise, it returns @code{nil}. -@xref{Display Action Functions}, for a list of predefined action -functions. @code{display-buffer} works by combining display actions from several sources, and calling the action functions in turn, until one @@ -2363,12 +2401,14 @@ value. This command makes @var{buffer-or-name} appear in some window, without selecting the window or making the buffer current. The argument @var{buffer-or-name} must be a buffer or the name of an existing -buffer. The return value is the window chosen to display the buffer. +buffer. The return value is the window chosen to display the buffer, +or @code{nil} if no suitable window was found. The optional argument @var{action}, if non-@code{nil}, should normally be a display action (described above). @code{display-buffer} builds a list of action functions and an action alist, by consolidating display -actions from the following sources (in order): +actions from the following sources (in order of their precedence, +from highest to lowest): @itemize @item @@ -2388,40 +2428,65 @@ The constant @code{display-buffer-fallback-action}. @end itemize @noindent -Each action function is called in turn, passing the buffer as the -first argument and the combined action alist as the second argument, -until one of the functions returns non-@code{nil}. The caller can -pass @code{(allow-no-window . t)} as an element of the action alist to -indicate its readiness to handle the case of not displaying the -buffer in a window. +In practice this means that @code{display-buffer} builds a list of all +action functions specified by these display actions. The first +element of this list is the first action function specified by +@code{display-buffer-overriding-action}, if any. Its last element is +@code{display-buffer-pop-up-frame}---the last action function +specified by @code{display-buffer-fallback-action}. Duplicates are +not removed from this list---hence one and the same action function +may be called multiple times during one call of @code{display-buffer}. + +@code{display-buffer} calls the action functions specified by this +list in turn, passing the buffer as the first argument and the +combined action alist as the second argument, until one of the +functions returns non-@code{nil}. @xref{Precedence of Action +Functions}, for examples how display actions specified by different +sources are processed by @code{display-buffer}. + +Note that the second argument is always the list of @emph{all} action +alist entries specified by the sources named above. Hence, the first +element of that list is the first action alist entry specified by +@code{display-buffer-overriding-action}, if any. Its last element is +the last alist entry of @code{display-buffer-base-action}, if any (the +action alist of @code{display-buffer-fallback-action} is empty). + +Note also, that the combined action alist may contain duplicate +entries and entries for the same key with different values. As a +rule, action functions always use the first association of a key they +find. Hence, the association an action function uses is not +necessarily the association provided by the display action that +specified that action function, The argument @var{action} can also have a non-@code{nil}, non-list value. This has the special meaning that the buffer should be displayed in a window other than the selected one, even if the selected window is already displaying it. If called interactively -with a prefix argument, @var{action} is @code{t}. +with a prefix argument, @var{action} is @code{t}. Lisp programs +should always supply a list value. The optional argument @var{frame}, if non-@code{nil}, specifies which frames to check when deciding whether the buffer is already displayed. -It is equivalent to adding an element @code{(reusable-frames -. @var{frame})} to the action alist of @var{action}. @xref{Display -Action Functions}. +It is equivalent to adding an element @w{@code{(reusable-frames +. @var{frame})}} to the action alist of @var{action} (@pxref{Buffer +Display Action Alists}). The @var{frame} argument is provided for +compatibility reasons, Lisp programs should not use it. @end deffn @defvar display-buffer-overriding-action The value of this variable should be a display action, which is treated with the highest priority by @code{display-buffer}. The -default value is empty, i.e., @code{(nil . nil)}. +default value is an empty display action, i.e., @w{@code{(nil . nil)}}. @end defvar @defopt display-buffer-alist The value of this option is an alist mapping conditions to display actions. Each condition may be either a regular expression matching a buffer name or a function that takes two arguments: a buffer name and -the @var{action} argument passed to @code{display-buffer}. If the name -of the buffer passed to @code{display-buffer} either matches a regular -expression in this alist or the function specified by a condition -returns non-@code{nil}, then @code{display-buffer} uses the +the @var{action} argument passed to @code{display-buffer}. If either +the name of the buffer passed to @code{display-buffer} matches a +regular expression in this alist, or the function specified by a +condition returns non-@code{nil}, then @code{display-buffer} uses the corresponding display action to display the buffer. @end defopt @@ -2437,13 +2502,19 @@ This display action specifies the fallback behavior for @end defvr -@node Display Action Functions -@section Action Functions for @code{display-buffer} +@node Buffer Display Action Functions +@subsection Action Functions for Buffer Display +@cindex buffer display action function +@cindex action function, for buffer display -The following basic action functions are defined in Emacs. Each of -these functions takes two arguments: @var{buffer}, the buffer to -display, and @var{alist}, an action alist. Each action function -returns the window if it succeeds, and @code{nil} if it fails. +An @dfn{action function} is a function @code{display-buffer} calls for +choosing a window to display a buffer. Action functions take two +arguments: @var{buffer}, the buffer to display, and @var{alist}, an +action alist (@pxref{Buffer Display Action Alists}). They are +supposed to return a window displaying @var{buffer} if they succeed +and @code{nil} if they fail. + + The following basic action functions are defined in Emacs. @defun display-buffer-same-window buffer alist This function tries to display @var{buffer} in the selected window. @@ -2453,57 +2524,105 @@ to another buffer (@pxref{Dedicated Windows}). It also fails if @end defun @defun display-buffer-reuse-window buffer alist -This function tries to display @var{buffer} by finding a window -that is already displaying it. +This function tries to display @var{buffer} by finding a window that +is already displaying it. If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry, -the selected window is not eligible for reuse. If @var{alist} -contains a @code{reusable-frames} entry, its value determines which -frames to search for a reusable window: - -@itemize @bullet -@item -@code{nil} means consider windows on the selected frame. -(Actually, the last non-minibuffer frame.) -@item -@code{t} means consider windows on all frames. -@item -@code{visible} means consider windows on all visible frames. -@item -0 means consider windows on all visible or iconified frames. -@item -A frame means consider windows on that frame only. -@end itemize - -Note that these meanings differ slightly from those of the -@var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window -Ordering}). - -If @var{alist} contains no @code{reusable-frames} entry, this function -normally searches just the selected frame; however, if the variable -@code{pop-up-frames} is non-@code{nil}, it searches all frames on the -current terminal. @xref{Choosing Window Options}. - -If this function chooses a window on another frame, it makes that frame -visible and, unless @var{alist} contains an @code{inhibit-switch-frame} -entry (@pxref{Choosing Window Options}), raises that frame if necessary. +the selected window is not eligible for reuse. The set of frames to +search for a window already displaying @var{buffer} can be specified +with the help of the @code{reusable-frames} action alist entry. If +@var{alist} contains no @code{reusable-frames} entry, this function +searches just the selected frame. + +If this function chooses a window on another frame, it makes that +frame visible and, unless @var{alist} contains an +@code{inhibit-switch-frame} entry, raises that frame if necessary. @end defun @defun display-buffer-reuse-mode-window buffer alist This function tries to display @var{buffer} by finding a window that is displaying a buffer in a given mode. -If @var{alist} contains a @code{mode} entry, its value is a major mode -(a symbol) or a list of major modes. If @var{alist} contains no -@code{mode} entry, the current major mode of @var{buffer} is used. A -window is a candidate if it displays a buffer that derives from one of -the given modes. +If @var{alist} contains a @code{mode} entry, its value specifes a +major mode (a symbol) or a list of major modes. If @var{alist} +contains no @code{mode} entry, the current major mode of @var{buffer} +is used instead. A window is a candidate if it displays a buffer +whose mode derives from one of the modes specified thusly. -The behavior is also controlled by entries for +The behavior is also controlled by @var{alist} entries for @code{inhibit-same-window}, @code{reusable-frames} and -@code{inhibit-switch-frame} as is done in the function -@code{display-buffer-reuse-window}. +@code{inhibit-switch-frame}, like @code{display-buffer-reuse-window} +does. +@end defun + +@defun display-buffer-pop-up-window buffer alist +This function tries to display @var{buffer} by splitting the largest +or least recently-used window (usually located on the selected frame). +It actually performs the split by calling the function specified by +@code{split-window-preferred-function} (@pxref{Choosing Window +Options}). + +The size of the new window can be adjusted by supplying +@code{window-height} and @code{window-width} entries in @var{alist}. +If @var{alist} contains a @code{preserve-size} entry, Emacs will also +try to preserve the size of the new window during future resize +operations (@pxref{Preserving Window Sizes}). + +This function fails if no window can be split. More often than not, +this happens because no window is large enough to allow splitting. +Setting @code{split-height-threshold} or @code{split-width-threshold} +to lower values may help in this regard. Spliting also fails when the +selected frame has an @code{unsplittable} frame parameter; +@pxref{Buffer Parameters}. +@end defun + +@defun display-buffer-in-previous-window buffer alist +This function tries to display @var{buffer} in a window where it was +previously displayed. If @var{alist} has a non-@code{nil} +@code{inhibit-same-window} entry, the selected window is not eligible +for reuse. If @var{alist} contains a @code{reusable-frames} entry, +its value determines which frames to search for a suitable window. +If @var{alist} has a @code{previous-window} entry and the window +specified by that entry is live and not dedicated to another buffer, +that window will be preferred, even if it never showed @var{buffer} +before. +@end defun + +@defun display-buffer-use-some-window buffer alist +This function tries to display @var{buffer} by choosing an existing +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-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 +window already displays @var{buffer}, it reuses that window. + +If there is no such window, this function tries to create a new window +by splitting the selected one, and displays @var{buffer} there. It will +also try to adjust that window's size provided @var{alist} contains a +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 +This function tries to display @var{buffer} in a window at the bottom +of the selected frame. + +This either tries to split the window at the bottom of the frame or +the frame's root window, or to reuse an existing window at the bottom +of the selected frame. @end defun @defun display-buffer-pop-up-frame buffer alist @@ -2511,37 +2630,37 @@ This function creates a new frame, and displays the buffer in that frame's window. It actually performs the frame creation by calling the function specified in @code{pop-up-frame-function} (@pxref{Choosing Window Options}). If @var{alist} contains a -@code{pop-up-frame-parameters} entry, the associated value -is added to the newly created frame's parameters. +@code{pop-up-frame-parameters} entry, the associated value is added to +the newly created frame's parameters. @end defun @defun display-buffer-in-child-frame buffer alist This function tries to display @var{buffer} in a child frame -(@pxref{Child Frames}) of the selected frame, either reusing an existing -child frame or by making a new one. If @var{alist} has a non-@code{nil} -@code{child-frame-parameters} entry, the corresponding value is an alist -of frame parameters to give the new frame. A @code{parent-frame} -parameter specifying the selected frame is provided by default. If the -child frame should be or become the child of another frame, a -corresponding entry must be added to @var{alist}. +(@pxref{Child Frames}) of the selected frame, either reusing an +existing child frame or by making a new one. If @var{alist} has a +non-@code{nil} @code{child-frame-parameters} entry, the corresponding +value is an alist of frame parameters to give the new frame. A +@code{parent-frame} parameter specifying the selected frame is +provided by default. If the child frame should become the child of +another frame, a corresponding entry must be added to @var{alist}. The appearance of child frames is largely dependent on the parameters provided via @var{alist}. It is advisable to use at least ratios to specify the size (@pxref{Size Parameters}) and the position -(@pxref{Position Parameters}) of the child frame and to add the -@code{keep-ratio} in order to make sure that the child frame remains -visible. For other parameters that should be considered see @ref{Child -Frames}. +(@pxref{Position Parameters}) of the child frame, and to add a +@code{keep-ratio} parameter (@pxref{Frame Interaction Parameters}), in +order to make sure that the child frame remains visible. For other +parameters that should be considered see @ref{Child Frames}. @end defun @defun display-buffer-use-some-frame buffer alist -This function tries to display @var{buffer} by trying to find a -frame that meets a predicate (by default any frame other than the -current frame). +This function tries to display @var{buffer} by finding a frame that +meets a predicate (by default any frame other than the selected +frame). -If this function chooses a window on another frame, it makes that frame -visible and, unless @var{alist} contains an @code{inhibit-switch-frame} -entry (@pxref{Choosing Window Options}), raises that frame if necessary. +If this function chooses a window on another frame, it makes that +frame visible and, unless @var{alist} contains an +@code{inhibit-switch-frame} entry, raises that frame if necessary. If @var{alist} has a non-@code{nil} @code{frame-predicate} entry, its value is a function taking one argument (a frame), returning @@ -2549,237 +2668,328 @@ non-@code{nil} if the frame is a candidate; this function replaces the default predicate. If @var{alist} has a non-@code{nil} @code{inhibit-same-window} entry, -the selected window is used; thus if the selected frame has a single -window, it is not used. +the selected window is not used; thus if the selected frame has a +single window, it is not used. @end defun -@defun display-buffer-pop-up-window buffer alist -This function tries to display @var{buffer} by splitting the largest -or least recently-used window (typically one on the selected frame). -It actually performs the split by calling the function specified in -@code{split-window-preferred-function} (@pxref{Choosing Window -Options}). - -The size of the new window can be adjusted by supplying -@code{window-height} and @code{window-width} entries in @var{alist}. To -adjust the window's height, use an entry whose @sc{car} is -@code{window-height} and whose @sc{cdr} is one of: - -@itemize @bullet -@item -@code{nil} means to leave the height of the new window alone. +@defun display-buffer-no-window buffer alist +If @var{alist} has a non-@code{nil} @code{allow-no-window} entry, then +this function does not display @var{buffer} and returns the symbol +@code{fail}. This constitutes the only exception to the convention +that an action function returns either @code{nil} or a window showing +@var{buffer}. If @var{alist} has no such @code{allow-no-window} +entry, this function returns @code{nil}. + +If this function returns @code{fail}, @code{display-buffer} will skip +the execution of any further display actions and return @code{nil} +immediately. If this function returns @code{nil}, +@code{display-buffer} will continue with the next display action, if +any. -@item -A number specifies the desired height of the new window. An integer -specifies the number of lines of the window. A floating-point -number gives the fraction of the window's height with respect to the -height of the frame's root window. +It is assumed that when a caller of @code{display-buffer} specifies a +non-@code{nil} @code{allow-no-window} entry, it is also able to handle +a @code{nil} return value. +@end defun -@item -If the @sc{cdr} specifies a function, that function is called with one -argument: the new window. The function is supposed to adjust the -height of the window; its return value is ignored. Suitable functions -are @code{shrink-window-if-larger-than-buffer} and -@code{fit-window-to-buffer}, see @ref{Resizing Windows}. -@end itemize +Two other action functions are described in their proper +sections---@code{display-buffer-in-side-window} (@pxref{Displaying +Buffers in Side Windows}) and @code{display-buffer-in-atom-window} +(@pxref{Atomic Windows}). + + +@node Buffer Display Action Alists +@subsection Action Alists for Buffer Display +@cindex buffer display action alist +@cindex action alist for buffer display + +An @dfn{action alist} is an association list mapping predefined +symbols recognized by action functions to values these functions are +supposed to interpret accordingly. In each call, +@code{display-buffer} constructs a new, possibly empty action alist +and passes that entire list on to any action function it calls. + + By design, action functions are free in their interpretation of +action alist entries. In fact, some entries like +@code{allow-no-window} or @code{previous-window} have a meaning only +for one or a few action functions, and are ignored by the rest. Other +entries, like @code{inhibit-same-window} or @code{window-parameters}, +are supposed to be respected by most action functions, including those +provided by application programs and external packages. + + In the previous subsection we have described in detail how +individual action functions interpret the action alist entries they +care about. Here we give a reference list of all known action alist +entries according to their symbols, together with their values and +action functions (@pxref{Buffer Display Action Functions}) that +recognize them. Throughout this list, the terms ``buffer'' will refer +to the buffer @code{display-buffer} is supposed to display, and +``value'' refers to the entry's value. -To adjust the window's width, use an entry whose @sc{car} is -@code{window-width} and whose @sc{cdr} is one of: +@table @code +@vindex inhibit-same-window@r{, a buffer display action alist entry} +@item inhibit-same-window +If the value is non-@code{nil}, this signals that the selected window +must not be used for displaying the buffer. All action functions that +(re-)use an existing window should respect this entry. + +@vindex previous-window@r{, a buffer display action alist entry} +@item previous-window +The value must specify a window that may have displayed the buffer +previously. @code{display-buffer-in-previous-window} will give +preference to such a window provided it is still live and not +dedicated to another buffer. + +@vindex mode@r{, a buffer display action alist entry} +@item mode +The value is either a major mode or a list of major modes. +@code{display-buffer-reuse-mode-window} may reuse a window whenever +the value specified by this entry matches the major mode of that +window's buffer. Other action functions ignore such entries. + +@vindex frame-predicate@r{, a buffer display action alist entry} +@item frame-predicate +The value must be a function taking one argument (a frame), supposed +to return non-@code{nil} if that frame is a candidate for displaying +the buffer. This entry is used by +@code{display-buffer-use-some-frame}. + +@vindex reusable-frames@r{, a buffer display action alist entry} +@item reusable-frames +The value specifies the set of frames to search for a window that can +be reused because it already displays the buffer. It can be set as +follows: @itemize @bullet @item -@code{nil} means to leave the width of the new window alone. - +@code{nil} means consider only windows on the selected frame. +(Actually, the last frame used that is not a minibuffer-only frame.) @item -A number specifies the desired width of the new window. An integer -specifies the number of columns of the window. A floating-point -number gives the fraction of the window's width with respect to the -width of the frame's root window. - +@code{t} means consider windows on all frames. +@item +@code{visible} means consider windows on all visible frames. @item -If the @sc{cdr} specifies a function, that function is called with one -argument: the new window. The function is supposed to adjust the width -of the window; its return value is ignored. +0 means consider windows on all visible or iconified frames. +@item +A frame means consider windows on that frame only. @end itemize -If @var{alist} contains a @code{preserve-size} entry, Emacs will try to -preserve the size of the new window during future resize operations -(@pxref{Preserving Window Sizes}). The @sc{cdr} of that entry must be a -cons cell whose @sc{car}, if non-@code{nil}, means to preserve the width -of the window and whose @sc{cdr}, if non-@code{nil}, means to preserve -the height of the window. - -This function can fail if no window splitting can be performed for some -reason (e.g., if the selected frame has an @code{unsplittable} frame -parameter; @pxref{Buffer Parameters}). -@end defun +Note that the meaning of @code{nil} differs slightly from that of the +@var{all-frames} argument to @code{next-window} (@pxref{Cyclic Window +Ordering}). -@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 -window already displays @var{buffer}, it reuses that window. +A major client of this is @code{display-buffer-reuse-window}, but all +other action functions that try to reuse a window are affected as +well. -If there is no such window, this function tries to create a new window -by splitting the selected one and display @var{buffer} there. It will -also adjust that window's size provided @var{alist} contains a suitable -@code{window-height} or @code{window-width} entry, see above. +@vindex inhibit-switch-frame@r{, a buffer display action alist entry} +@item inhibit-switch-frame +A non-@code{nil} value prevents another frame from being raised or +selected, if the window chosen by @code{display-buffer} is displayed +there. Primarily affected by this are +@code{display-buffer-use-some-frame} and +@code{display-buffer-reuse-window}. +@code{display-buffer-pop-up-frame} should be affected as well, but +there is no guarantee that the window manager will comply. + +@vindex window-parameters@r{, a buffer display action alist entry} +@item window-parameters +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 +window and can be one of the following: -If splitting the selected window fails and there is a non-dedicated -window below the selected one showing some other buffer, it uses that -window for showing @var{buffer}. -@end defun +@itemize @bullet +@item +@code{nil} means to leave the height of the chosen window alone. -@defun display-buffer-in-previous-window buffer alist -This function tries to display @var{buffer} in a window previously -showing it. If @var{alist} has a non-@code{nil} -@code{inhibit-same-window} entry, the selected window is not eligible -for reuse. If @var{alist} contains a @code{reusable-frames} entry, its -value determines which frames to search for a suitable window as with -@code{display-buffer-reuse-window}. +@item +An integer number specifies the desired total height of the chosen +window in lines. -If @var{alist} has a @code{previous-window} entry, the window -specified by that entry will override any other window found by the -methods above, even if that window never showed @var{buffer} before. -@end defun +@item +A floating-point number specifies the fraction of the chosen window's +desired total height with respect to the total height of its frame's +root window. -@defun display-buffer-at-bottom buffer alist -This function tries to display @var{buffer} in a window at the bottom -of the selected frame. +@item +If the value specifies a function, that function is called with one +argument---the chosen window. The function is supposed to adjust the +height of the window; its return value is ignored. Suitable functions +are @code{shrink-window-if-larger-than-buffer} and +@code{fit-window-to-buffer}, see @ref{Resizing Windows}. +@end itemize -This either splits the window at the bottom of the frame or the -frame's root window, or reuses an existing window at the bottom of the -selected frame. -@end defun +By convention, the height of the chosen window is adjusted only if the +window is part of a vertical combination (@pxref{Windows and Frames}) +to avoid changing the height of other, unrelated windows. Also, this +entry should be processed only under certain conditions which are +specified right below this list. -@defun display-buffer-use-some-window buffer alist -This function tries to display @var{buffer} by choosing an existing -window and displaying the buffer in that window. It can fail if all -windows are dedicated to another buffer (@pxref{Dedicated Windows}). -@end defun +@vindex window-width@r{, a buffer display action alist entry} +@item window-width +This entry is similar to the @code{window-height} entry described +before, but used to adjust the chosen window's width instead. The +value can be one of the following: -@defun display-buffer-no-window buffer alist -If @var{alist} has a non-@code{nil} @code{allow-no-window} entry, then -this function does not display @code{buffer}. This allows you to -override the default action and avoid displaying the buffer. It is -assumed that when the caller specifies a non-@code{nil} -@code{allow-no-window} value it can handle a @code{nil} value returned -from @code{display-buffer} in this case. -@end defun +@itemize @bullet +@item +@code{nil} means to leave the width of the chosen window alone. -If the @var{alist} argument of any of these functions contains a -@code{window-parameters} entry, @code{display-buffer} assigns the -elements of the associated value as window parameters of the chosen -window. +@item +An integer specifies the desired total width of the chosen window in +columns. - To illustrate the use of action functions, consider the following -example. +@item +A floating-point number specifies the fraction of the chosen window's +desired total width with respect to the total width of the frame's +root window. -@example -@group -(display-buffer - (get-buffer-create "*foo*") - '((display-buffer-reuse-window - display-buffer-pop-up-window - display-buffer-pop-up-frame) - (reusable-frames . 0) - (window-height . 10) (window-width . 40))) -@end group -@end example +@item +If the value specifies a function, that function is called with one +argument---the chosen window. The function is supposed to adjust the +width of the window; its return value is ignored. +@end itemize -@noindent -Evaluating the form above will cause @code{display-buffer} to proceed as -follows: If a buffer called *foo* already appears on a visible or -iconified frame, it will reuse its window. Otherwise, it will try to -pop up a new window or, if that is impossible, a new frame and show the -buffer there. If all these steps fail, it will proceed using whatever -@code{display-buffer-base-action} and -@code{display-buffer-fallback-action} prescribe. - - Furthermore, @code{display-buffer} will try to adjust a reused window -(provided *foo* was put by @code{display-buffer} there before) or a -popped-up window as follows: If the window is part of a vertical -combination, it will set its height to ten lines. Note that if, instead -of the number 10, we specified the function -@code{fit-window-to-buffer}, @code{display-buffer} would come up with a -one-line window to fit the empty buffer. If the window is part of a -horizontal combination, it sets its width to 40 columns. Whether a new -window is vertically or horizontally combined depends on the shape of -the window split and the values of -@code{split-window-preferred-function}, @code{split-height-threshold} -and @code{split-width-threshold} (@pxref{Choosing Window Options}). - - Now suppose we combine this call with a preexisting setup for -@code{display-buffer-alist} as follows. +By convention, the width of the chosen window is adjusted only if the +window is part of a horizontal combination (@pxref{Windows and +Frames}) to avoid changing the width of other, unrelated windows. +Also, this entry should be processed under only certain conditions +which are specified right below this list. + +@vindex 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 +the window chosen (@pxref{Preserving Window Sizes}). The value should +be either @w{@code{(t . nil)}} to preserve the width of the window, +@w{@code{(nil . t)}} to preserve its height or @w{@code{(t . t)}} to +preserve both, its width and its height. This entry should be +processed only under certain conditions which are specified right +after this list. + +@vindex pop-up-frame-parameters@r{, a buffer display action alist entry} +@item pop-up-frame-parameters +The value specifies an alist of frame parameters to give a new frame, +if one is created. @code{display-buffer-pop-up-frame} is its one and +only addressee. + +@vindex parent-frame@r{, a buffer display action alist entry} +@item parent-frame +The value specifies the parent frame to be used when the buffer is +displayed on a child frame. This entry is used only by +@code{display-buffer-in-child-frame}. + +@vindex child-frame-parameters@r{, a buffer display action alist entry} +@item child-frame-parameters +The value specifies an alist of frame parameters to use when the buffer +is displayed on a child frame. This entry is used only by +@code{display-buffer-in-child-frame}. + +@vindex side@r{, a buffer display action alist entry} +@item side +The value denotes the side of the frame or window where a new window +displaying the buffer shall be created. This entry is used by +@code{display-buffer-in-side-window} to indicate the side of the frame +where a new side window shall be placed (@pxref{Displaying Buffers in +Side Windows}). It is also used by +@code{display-buffer-in-atom-window} to indicate the side of an +existing window where the new window shall be located (@pxref{Atomic +Windows}). -@example -@group -(let ((display-buffer-alist - (cons - '("\\*foo\\*" - (display-buffer-reuse-window display-buffer-below-selected) - (reusable-frames) - (window-height . 5)) - display-buffer-alist))) - (display-buffer - (get-buffer-create "*foo*") - '((display-buffer-reuse-window - display-buffer-pop-up-window - display-buffer-pop-up-frame) - (reusable-frames . 0) - (window-height . 10) (window-width . 40)))) -@end group -@end example +@vindex slot@r{, a buffer display action alist entry} +@item slot +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}. -@noindent -This form will have @code{display-buffer} first try reusing a window -that shows *foo* on the selected frame. If there's no such window, it -will try to split the selected window or, if that is impossible, use the -window below the selected window. +@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. + +@vindex allow-no-window@r{, a buffer display action alist entry} +@item allow-no-window +If the value is non-@code{nil}, @code{display-buffer} does not +necessarily have to display the buffer and the caller is prepared to +accept that. This entry is not intended for user customizations, +since there is no guarantee that an arbitrary caller of +@code{display-buffer} will be able to handle the case that no window +will display the buffer. @code{display-buffer-no-window} is the only +action function that cares about this entry. +@end table - If there's no window below the selected one, or the window below the -selected one is dedicated to its buffer, @code{display-buffer} will -proceed as described in the previous example. Note, however, that when -it tries to adjust the height of any reused or popped-up window, it will -in any case try to set its number of lines to 5 since that value -overrides the corresponding specification in the @var{action} argument -of @code{display-buffer}. +By convention, the entries @code{window-height}, @code{window-width} +and @code{preserve-size} are applied after the chosen window's buffer +has been set up and if and only if that window never showed another +buffer before. More precisely, the latter means that the window must +have been either created by the current @code{display-buffer} call or +the window was created earlier by @code{display-buffer} to show the +buffer and never was used to show another buffer until it was reused +by the current invocation of @code{display-buffer}. @node Choosing Window Options -@section Additional Options for Displaying Buffers +@subsection Additional Options for Displaying Buffers -The behavior of the standard display actions of @code{display-buffer} -(@pxref{Choosing Window}) can be modified by a variety of user -options. +The behavior of buffer display actions (@pxref{Choosing Window}) can +be further modified by the following user options. @defopt pop-up-windows If the value of this variable is non-@code{nil}, @code{display-buffer} is allowed to split an existing window to make a new window for displaying in. This is the default. -This variable is provided mainly for backward compatibility. It is +This variable is provided for backward compatibility only. It is obeyed by @code{display-buffer} via a special mechanism in -@code{display-buffer-fallback-action}, which only calls the action -function @code{display-buffer-pop-up-window} (@pxref{Display Action -Functions}) when the value is @code{nil}. It is not consulted by -@code{display-buffer-pop-up-window} itself, which the user may specify -directly in @code{display-buffer-alist} etc. +@code{display-buffer-fallback-action}, which calls the action function +@code{display-buffer-pop-up-window} (@pxref{Buffer Display Action +Functions}) when the value of this option is non-@code{nil}. It is +not consulted by @code{display-buffer-pop-up-window} itself, which the +user may specify directly in @code{display-buffer-alist} etc. @end defopt @defopt split-window-preferred-function This variable specifies a function for splitting a window, in order to make a new window for displaying a buffer. It is used by the @code{display-buffer-pop-up-window} action function to actually split -the window (@pxref{Display Action Functions}). +the window. -The default value is @code{split-window-sensibly}, which is documented -below. The value must be a function that takes one argument, a window, -and return either a new window (which will be used to display the -desired buffer) or @code{nil} (which means the splitting failed). +The value must be a function that takes one argument, a window, and +returns either a new window (which will be used to display the desired +buffer) or @code{nil} (which means the splitting failed). The default +value is @code{split-window-sensibly}, which is documented next. @end defopt @defun split-window-sensibly &optional window -This function tries to split @var{window}, and return the newly created +This function tries to split @var{window} and return the newly created window. If @var{window} cannot be split, it returns @code{nil}. If @var{window} is omitted or @code{nil}, it defaults to the selected window. @@ -2790,31 +3000,31 @@ placing the new window below, subject to the restriction imposed by @code{split-height-threshold} (see below), in addition to any other restrictions. If that fails, it tries to split by placing the new window to the right, subject to @code{split-width-threshold} (see -below). If that fails, and the window is the only window on its +below). If that also fails, and the window is the only window on its frame, this function again tries to split and place the new window below, disregarding @code{split-height-threshold}. If this fails as well, this function gives up and returns @code{nil}. @end defun @defopt split-height-threshold -This variable, used by @code{split-window-sensibly}, specifies whether -to split the window placing the new window below. If it is an +This variable specifies whether @code{split-window-sensibly} is +allowed to split the window placing the new window below. If it is an integer, that means to split only if the original window has at least that many lines. If it is @code{nil}, that means not to split this way. @end defopt @defopt split-width-threshold -This variable, used by @code{split-window-sensibly}, specifies whether -to split the window placing the new window to the right. If the value -is an integer, that means to split only if the original window has at -least that many columns. If the value is @code{nil}, that means not -to split this way. +This variable specifies whether @code{split-window-sensibly} is +allowed to split the window placing the new window to the right. If +the value is an integer, that means to split only if the original +window has at least that many columns. If the value is @code{nil}, +that means not to split this way. @end defopt @defopt even-window-sizes This variable, if non-@code{nil}, causes @code{display-buffer} to even -window sizes whenever it reuses an existing window and that window is +window sizes whenever it reuses an existing window, and that window is adjacent to the selected one. If its value is @code{width-only}, sizes are evened only if the reused @@ -2839,9 +3049,9 @@ search any visible or iconified frame, not just the selected frame. This variable is provided mainly for backward compatibility. It is obeyed by @code{display-buffer} via a special mechanism in @code{display-buffer-fallback-action}, which calls the action function -@code{display-buffer-pop-up-frame} (@pxref{Display Action Functions}) -if the value is non-@code{nil}. (This is done before attempting to -split a window.) This variable is not consulted by +@code{display-buffer-pop-up-frame} (@pxref{Buffer Display Action +Functions}) if the value is non-@code{nil}. (This is done before +attempting to split a window.) This variable is not consulted by @code{display-buffer-pop-up-frame} itself, which the user may specify directly in @code{display-buffer-alist} etc. @end defopt @@ -2849,8 +3059,7 @@ directly in @code{display-buffer-alist} etc. @defopt pop-up-frame-function This variable specifies a function for creating a new frame, in order to make a new window for displaying a buffer. It is used by the -@code{display-buffer-pop-up-frame} action function (@pxref{Display -Action Functions}). +@code{display-buffer-pop-up-frame} action function. The value should be a function that takes no arguments and returns a frame, or @code{nil} if no frame could be created. The default value @@ -2860,30 +3069,670 @@ is a function that creates a frame using the parameters specified by @defopt pop-up-frame-alist This variable holds an alist of frame parameters (@pxref{Frame -Parameters}), which is used by the default function in +Parameters}), which is used by the function specified by @code{pop-up-frame-function} to make a new frame. The default is @code{nil}. -@end defopt -@defopt same-window-buffer-names -A list of buffer names for buffers that should be displayed in the -selected window. If a buffer's name is in this list, -@code{display-buffer} handles the buffer by showing it in the selected -window. +This option is provided for backward compatibility only. Note, that +when @code{display-buffer-pop-up-frame} calls the function specified +by @code{pop-up-frame-function}, it prepends the value of all +@code{pop-up-frame-parameters} action alist entries to +@code{pop-up-frame-alist} so that the values specified by the action +alist entry effectively override any corresponding values of +@code{pop-up-frame-alist}. + +Hence, users should set up a @code{pop-up-frame-parameters} action +alist entry in @code{display-buffer-alist} instead of customizing +@code{pop-up-frame-alist}. Only this will guarantee that the value of +a parameter specified by the user overrides the value of that +parameter specified by the caller of @code{display-buffer}. @end defopt -@defopt same-window-regexps -A list of regular expressions that specify buffers that should be -displayed in the selected window. If the buffer's name matches any of -the regular expressions in this list, @code{display-buffer} handles the -buffer by showing it in the selected window. -@end defopt + Many efforts in the design of @code{display-buffer} have been given +to maintain compatibility with code that uses older options like +@code{pop-up-windows}, @code{pop-up-frames}, +@code{pop-up-frame-alist}, @code{same-window-buffer-names} and +@code{same-window-regexps}. Lisp Programs and users should refrain +from using these options. Above we already warned against customizing +@code{pop-up-frame-alist}. Here we describe how to convert the +remaining options to use display actions instead. + +@table @code +@item pop-up-windows +@vindex pop-up-windows@r{, replacement for} +This variable is @code{t} by default. Instead of customizing it to +@code{nil} and thus telling @code{display-buffer} what not to do, it's +much better to list in @code{display-buffer-base-action} the action +functions it should try instead as, for example: + +@example +@group +(customize-set-variable + 'display-buffer-base-action + '((display-buffer-reuse-window display-buffer-same-window + display-buffer-in-previous-window + display-buffer-use-some-window))) +@end group +@end example + +@item pop-up-frames +@vindex pop-up-frames@r{, replacement for} +Instead of customizing this variable to @code{t}, customize +@code{display-buffer-base-action}, for example, as follows: + +@example +@group +(customize-set-variable + 'display-buffer-base-action + '((display-buffer-reuse-window display-buffer-pop-up-frame) + (reusable-frames . 0))) +@end group +@end example + +@item same-window-buffer-names +@itemx same-window-regexps +@vindex same-window-buffer-names@r{, replacement for} +@vindex same-window-regexps@r{, replacement for} +Instead of adding a buffer name or a regular expression to one of +these options use a @code{display-buffer-alist} entry for that buffer +specifying the action function @code{display-buffer-same-window}. + +@example +@group +(customize-set-variable + 'display-buffer-alist + (cons '("\\*foo\\*" (display-buffer-same-window)) + display-buffer-alist)) +@end group +@end example +@end table + + +@node Precedence of Action Functions +@subsection Precedence of Action Functions +@cindex precedence of buffer display action functions +@cindex execution order of buffer display action functions +@cindex buffer display action functions, precedence + +From the past subsections we already know that @code{display-buffer} +must be supplied with a number of display actions (@pxref{Choosing +Window}) in order to display a buffer. In a completely uncustomized +Emacs, these actions are specified by +@code{display-buffer-fallback-action} in the following order of +precedence: Reuse a window, pop up a new window on the same frame, use +a window previously showing the buffer, use some window and pop up a +new frame. (Note that the remaining actions named by +@code{display-buffer-fallback-action} are void in an uncustomized +Emacs). + +Consider the following form: + +@example +(display-buffer (get-buffer-create "*foo*")) +@end example + +@noindent +Evaluating this form in the buffer @file{*scratch*} of an uncustomized +Emacs session will usually fail to reuse a window that shows +@file{*foo*} already, but succeed in popping up a new window. +Evaluating the same form again will now not cause any visible +changes---@code{display-buffer} reused the window already showing +@file{*foo*} because that action was applicable and had the highest +precedence among all applicable actions. + + Popping up a new window will fail if there is not enough space on +the selected frame. In an uncustomized Emacs it typically fails when +there are already two windows on a frame. For example, if you now +type @w{@kbd{C-x 1}} followed by @w{@kbd{C-x 2}} and evaluate the form +once more, @file{*foo*} should show up in the lower +window---@code{display-buffer} just used ``some'' window. If, before +typing @w{@kbd{C-x 2}} you had typed @w{@kbd{C-x o}}, @file{*foo*} +would have been shown in the upper window because ``some'' window +stands for the ``least recently used'' window and the selected window +has been least recently used if and only if it is alone on its frame. + + Let's assume you did not type @w{@kbd{C-x o}} and @file{*foo*} is +shown in the lower window. Type @w{@kbd{C-x o}} to get there followed +by @w{@kbd{C-x left}} and evaluate the form again. This should +display @file{*foo*} in the same, lower window because that window had +already shown @file{*foo*} previously and was therefore chosen instead +of some other window. + + So far we have only observed the default behavior in an uncustomized +Emacs session. To see how this behavior can be customized, let's +consider the option @code{display-buffer-base-action}. It provides a +very coarse customization which conceptually affects the display of +@emph{any} buffer. It can be used to supplement the actions supplied +by @code{display-buffer-fallback-action} by reordering them or by +adding actions that are not present there but fit more closely the +user's editing practice. However, it can also be used to change the +default behavior in a more profound way. + + Let's consider a user who, as a rule, prefers to display buffers on +another frame. Such a user might provide the following customization: + +@example +@group +(customize-set-variable + 'display-buffer-base-action + '((display-buffer-reuse-window display-buffer-pop-up-frame) + (reusable-frames . 0))) +@end group +@end example + +@noindent +This setting will cause @code{display-buffer} to first try to find a +window showing the buffer on a visible or iconified frame and, if no +such frame exists, pop up a new frame. You can observe this behavior +on a graphical system by typing @w{@kbd{C-x 1}} in the window showing +@file{*scratch*} and evaluating our canonical @code{display-buffer} +form. This will usually create (and give focus to) a new frame whose +root window shows @file{*foo*}. Iconify that frame and evaluate the +canonical form again: @code{display-buffer} will reuse the window on +the new frame (usually raising the frame and giving it focus too). + + Only if creating a new frame fails, @code{display-buffer} will +apply the actions supplied by @code{display-buffer-fallback-action} +which means to again try reusing a window, popping up a new window and +so on. A trivial way to make frame creation fail is supplied by the +following form: + +@example +@group +(let ((pop-up-frame-function 'ignore)) + (display-buffer (get-buffer-create "*foo*"))) +@end group +@end example + +@noindent +We will forget about that form immediately after observing that it +fails to create a new frame and uses a fallback action instead. + + Note that @code{display-buffer-reuse-window} appears redundant in +the customization of @code{display-buffer-base-action} because it is +already part of @code{display-buffer-fallback-action} and should be +tried there anyway. However, that would fail because due to the +precedence of @code{display-buffer-base-action} over +@code{display-buffer-fallback-action}, at that time +@code{display-buffer-pop-up-frame} would have already won the race. +In fact, this: + +@example +@group +(customize-set-variable + 'display-buffer-base-action + '(display-buffer-pop-up-frame (reusable-frames . 0))) +@end group +@end example + +@noindent +would cause @code{display-buffer} to @emph{always} pop up a new frame +which is probably not what our user wants. + + So far, we have only shown how @emph{users} can customize the +default behavior of @code{display-buffer}. Let us now see how +@emph{applications} can change the course of @code{display-buffer}. +The canonical way to do that is to use the @var{action} argument of +@code{display-buffer} or a function that calls it, like, for example, +@code{pop-to-buffer} (@pxref{Switching Buffers}). + + Suppose an application wants to display @file{*foo*} preferably +below the selected window (to immediately attract the attention of the +user to the new window) or, if that fails, in a window at the bottom +of the frame. It could do that with a call like this: + +@example +@group +(display-buffer + (get-buffer-create "*foo*") + '((display-buffer-below-selected display-buffer-at-bottom))) +@end group +@end example + +@noindent +In order to see how this new, modified form works, delete any frame +showing @file{*foo*}, type @w{@kbd{C-x 1}} followed by @w{@kbd{C-x 2}} in the +window showing @file{*scratch*}, and subsequently evaluate that form. +@code{display-buffer} should split the upper window, and show +@file{*foo*} in the new window. Alternatively, if after @w{@kbd{C-x 2}} +you had typed @w{@kbd{C-x o}}, @code{display-buffer} would have split the +window at the bottom instead. + + Suppose now that, before evaluating the new form, you have made the +selected window as small as possible, for example, by evaluating the +form @code{(fit-window-to-buffer)} in that window. In that case, +@code{display-buffer} would have failed to split the selected window +and would have split the frame's root window instead, effectively +displaying @file{*foo*} at the bottom of the frame. + + In either case, evaluating the new form a second time should reuse +the window already showing @file{*foo*} since both functions supplied +by the @var{action} argument try to reuse such a window first. + + By setting the @var{action} argument, an application effectively +overrules any customization of @code{display-buffer-base-action}. Our +user can now either accept the choice of the application, or redouble +by customizing the option @code{display-buffer-alist} as follows: + +@example +@group +(customize-set-variable + 'display-buffer-alist + '(("\\*foo\\*" + (display-buffer-reuse-window display-buffer-pop-up-frame)))) +@end group +@end example + +@noindent +Trying this with the new, modified form above in a configuration that +does not show @file{*foo*} anywhere, will display @file{*foo*} on a +separate frame, completely ignoring the @var{action} argument of +@code{display-buffer}. + + Note that we didn't care to specify a @code{reusable-frames} action +alist entry in our specification of @code{display-buffer-alist}. +@code{display-buffer} always takes the first one it finds---in our +case the one specified by @code{display-buffer-base-action}. If we +wanted to use a different specification, for example, to exclude +iconified frames showing @file{*foo*} from the list of reusable ones, +we would have to specify that separately, however: + +@example +@group +(customize-set-variable + 'display-buffer-alist + '(("\\*foo\\*" + (display-buffer-reuse-window display-buffer-pop-up-frame) + (reusable-frames . visible)))) +@end group +@end example + +@noindent +If you try this, you will notice that repeated attempts to display +@file{*foo*} will succeed to reuse a frame only if that frame is +visible. + + The above example would allow the conclusion that users customize +@code{display-buffer-alist} for the sole purpose to overrule the +@var{action} argument chosen by applications. Such a conclusion would +be incorrect. @code{display-buffer-alist} is the standard option for +users to direct the course of display of specific buffers in a +preferred way regardless of whether the display is also guided by an +@var{action} argument. + + We can, however, reasonably conclude that customizing +@code{display-buffer-alist} differs from customizing +@code{display-buffer-base-action} in two major aspects: it is stronger +because it overrides the @var{action} argument of +@code{display-buffer}, and it allows to explicitly specify the +affected buffers. In fact, displaying other buffers is not affected +in any way by a customization for @file{*foo*}. For example, + +@example +(display-buffer (get-buffer-create "*bar*")) +@end example + +@noindent +continues being governed by the settings of +@code{display-buffer-base-action} and +@code{display-buffer-fallback-action} only. + + We could stop with our examples here but Lisp programs still have +an ace up their sleeves which they can use to overrule any +customization of @code{display-buffer-alist}. It's the variable +@code{display-buffer-overriding-action} which they can bind around +@code{display-buffer} calls as follows: + +@example +@group +(let ((display-buffer-overriding-action + '((display-buffer-same-window)))) + (display-buffer + (get-buffer-create "*foo*") + '((display-buffer-below-selected display-buffer-at-bottom)))) +@end group +@end example + +@noindent +Evaluating this form will usually display @file{*foo*} in the selected +window regardless of the @var{action} argument and any user +customizations. (Usually, an application will not bother to also +provide an @var{action} argument. Here it just serves to illustrate +the fact that it gets overridden.) + +It might be illustrative to look at the list of action functions +@code{display-buffer} would have tried to display @file{*foo*} with +the customizations we provided here. The list (including comments +explaining who added this and the subsequent elements) is: + +@example +@group +(display-buffer-same-window ;; `display-buffer-overriding-action' + display-buffer-reuse-window ;; `display-buffer-alist' + display-buffer-pop-up-frame + display-buffer-below-selected ;; ACTION argument + display-buffer-at-bottom + display-buffer-reuse-window ;; `display-buffer-base-action' + display-buffer-pop-up-frame + display-buffer--maybe-same-window ;; `display-buffer-fallback-action' + display-buffer-reuse-window + display-buffer--maybe-pop-up-frame-or-window + display-buffer-in-previous-window + display-buffer-use-some-window + display-buffer-pop-up-frame) +@end group +@end example + +@noindent +Note that among the internal functions listed here, +@code{display-buffer--maybe-same-window} is effectively ignored while +@code{display-buffer--maybe-pop-up-frame-or-window} actually runs +@code{display-buffer-pop-up-window}. + +The action alist passed in each function call is: + +@example +@group +((reusable-frames . visible) + (reusable-frames . 0)) +@end group +@end example + +@noindent +which shows that we have used the second specification of +@code{display-buffer-alist} above, overriding the specification +supplied by @code{display-buffer-base-action}. Suppose our user had +written that as + +@example +@group +(customize-set-variable + 'display-buffer-alist + '(("\\*foo\\*" + (display-buffer-reuse-window display-buffer-pop-up-frame) + (inhibit-same-window . t) + (reusable-frames . visible)))) +@end group +@end example + +@noindent +In this case the @code{inhibit-same-window} alist entry will +successfully invalidate the @code{display-buffer-same-window} +specification from @code{display-buffer-overriding-action} and +@code{display-buffer} will show @file{*foo*} on another frame. To +make @code{display-buffer-overriding-action} more robust in this +regard, the application would have to specify an appropriate +@code{inhibit-same-window} entry too, for example, as follows: + +@example +@group +(let ((display-buffer-overriding-action + '(display-buffer-same-window (inhibit-same-window . nil)))) + (display-buffer (get-buffer-create "*foo*"))) +@end group +@end example + +@noindent +This last example shows that while the precedence order of action +functions is fixed, as described in @ref{Choosing Window}, an action +alist entry specified by a display action ranked lower in that order +can affect the execution of a higher ranked display action. + + +@node The Zen of Buffer Display +@subsection The Zen of Buffer Display +@cindex guidelines for buffer display +@cindex writing buffer display actions +@cindex buffer display conventions + +In its most simplistic form, a frame accommodates always one single +window that can be used for displaying a buffer. As a consequence, it +is always the latest call of @code{display-buffer} that will have +succeeded in placing its buffer there. + + Since working with such a frame is not very practical, Emacs by +default allows for more complex frame layouts controlled by the +default values of the frame size and the @code{split-height-threshold} +and @code{split-width-threshold} options. Displaying a buffer not yet +shown on a frame then either splits the single window on that frame or +(re-)uses one of its two windows. + + The default behavior is abandoned as soon as the user customizes +one of these thresholds or manually changes the frame's layout. The +default behavior is also abandoned when calling @code{display-buffer} +with a non-@code{nil} @var{action} argument or the user customizes one +of the options mentioned in the previous subsections. Mastering +@code{display-buffer} soon may become a frustrating experience due to +the plethora of applicable display actions and the resulting frame +layouts. + + However, refraining from using buffer display functions and falling +back on a split & delete windows metaphor is not a good idea either. +Buffer display functions give Lisp programs and users a framework to +reconcile their different needs; no comparable framework exists for +splitting and deleting windows. Buffer display functions also allow +to at least partially restore the layout of a frame when removing a +buffer from it later (@pxref{Quitting Windows}). + + Below we will give a number of guidelines to redeem the frustration +mentioned above and thus to avoid literally losing buffers in-between +the windows of a frame. + +@table @asis +@item Write display actions without stress +Writing display actions can be a pain because one has to lump together +action functions and action alists in one huge list. (Historical +reasons prevented us from having @code{display-buffer} support +separate arguments for these.) It might help to memorize some basic +forms like the ones listed below: + +@example +'(nil (inhibit-same-window . t)) +@end example + +@noindent +specifies an action alist entry only and no action function. Its sole +purpose is to inhibit a @code{display-buffer-same-window} function +specified elsewhere from showing the buffer in the same window, see +also the last example of the preceding subsection. + +@example +'(display-buffer-below-selected) +@end example + +@noindent +on the other hand, specifies one action function and an empty action +alist. To combine the effects of the above two specifications one +would write the form + +@example +'(display-buffer-below-selected (inhibit-same-window . t)) +@end example + +@noindent +to add another action function one would write + +@example +@group +'((display-buffer-below-selected display-buffer-at-bottom) + (inhibit-same-window . t)) +@end group +@end example + +@noindent +and to add another alist entry one would write + +@example +@group +'((display-buffer-below-selected display-buffer-at-bottom) + (inhibit-same-window . t) + (window-height . fit-window-to-buffer)) +@end group +@end example + +@noindent +That last form can be used as @var{action} argument of +@code{display-buffer} in the following way: + +@example +@group +(display-buffer + (get-buffer-create "*foo*") + '((display-buffer-below-selected display-buffer-at-bottom) + (inhibit-same-window . t) + (window-height . fit-window-to-buffer))) +@end group +@end example + +@noindent +In a customization of @code{display-buffer-alist} it would be used as +follows: + +@example +@group +(customize-set-variable + 'display-buffer-alist + '(("\\*foo\\*" + (display-buffer-below-selected display-buffer-at-bottom) + (inhibit-same-window . t) + (window-height . fit-window-to-buffer)))) +@end group +@end example + +@noindent +To add a customization for a second buffer one would then write: + +@example +@group +(customize-set-variable + 'display-buffer-alist + '(("\\*foo\\*" + (display-buffer-below-selected display-buffer-at-bottom) + (inhibit-same-window . t) + (window-height . fit-window-to-buffer)) + ("\\*bar\\*" + (display-buffer-reuse-window display-buffer-pop-up-frame) + (reusable-frames . visible)))) +@end group +@end example + +@item Treat each other with respect +@code{display-buffer-alist} and @code{display-buffer-base-action} are +user options---Lisp programs must never set or rebind them. +@code{display-buffer-overriding-action}, on the other hand, is +reserved for applications---who seldom use that option and if they use +it, then with utmost care. + + Older implementations of @code{display-buffer} frequently caused +users and applications to fight over the settings of user options like +@code{pop-up-frames} and @code{pop-up-windows} (@pxref{Choosing Window +Options}). This was one major reason for redesigning +@code{display-buffer}---to provide a clear framework specifying what +users and applications should be allowed to do. + + Lisp programs must be prepared that user customizations may +cause buffers to get displayed in an unexpected way. They should +never assume in their subsequent behavior, that the buffer has been +shown precisely the way they asked for in the @var{action} argument of +@code{display-buffer}. + + Users should not pose too many and too severe restrictions on how +arbitrary buffers get displayed. Otherwise, they will risk to lose +the characteristics of showing a buffer for a certain purpose. +Suppose a Lisp program has been written to compare different versions +of a buffer in two windows side-by-side. If the customization of +@code{display-buffer-alist} prescribes that any such buffer should be +always shown in or below the selected window, the program will have a +hard time to set up the desired window configuration via +@code{display-buffer}. + + To specify a preference for showing an arbitrary buffer, users +should customize @code{display-buffer-base-action}. An example of how +users who prefer working with multiple frames would do that was given +in the previous subsection. @code{display-buffer-alist} should be +reserved for displaying specific buffers in a specific way. + +@item Consider reusing a window that already shows the buffer +Generally, it's always a good idea for users and Lisp +programmers to be prepared for the case that a window already shows +the buffer in question and to reuse that window. In the preceding +subsection we have shown that failing to do so properly may cause +@code{display-buffer} to continuously pop up a new frame although a +frame showing that buffer existed already. In a few cases only, it +might be undesirable to reuse a window, for example, when a different +portion of the buffer should be shown in that window. + + Hence, @code{display-buffer-reuse-window} is one action function +that should be used as often as possible, both in @var{action} +arguments and customizations. An @code{inhibit-same-window} entry in +the @var{action} argument usually takes care of the most common case +where reusing a window showing the buffer should be avoided---that +where the window in question is the selected one. + +@item Attract focus to the window chosen +This is a no-brainer for people working with multiple frames---the +frame showing the buffer will automatically raise and get focus unless +an @code{inhibit-switch-frame} entry forbids it. For single frame +users this task can be considerably more difficult. In particular, +@code{display-buffer-pop-up-window} and +@code{display-buffer-use-some-window} can become obtrusive in this +regard. They split or use a seemingly arbitrary (often the largest or +least recently used) window, distracting the user's attention. + +Some Lisp programs therefore try to choose a window at the bottom of +the frame, for example, in order to display the buffer in vicinity of +the minibuffer window where the user is expected to answer a question +related to the new window. For non-input related actions +@code{display-buffer-below-selected} might be preferable because the +selected window usually already has the user's attention. + +@item Handle subsequent invocations of @code{display-buffer} +@code{display-buffer} is not overly well suited for displaying several +buffers in sequence and making sure that all these buffers are shown +orderly in the resulting window configuration. Again, the standard +action functions @code{display-buffer-pop-up-window} and +@code{display-buffer-use-some-window} are not very suited for this +purpose due to their somewhat chaotic nature in more complex +configurations. + + To produce a window configuration displaying multiple buffers (or +different views of one and the same buffer) in one and the same +display cycle, Lisp programmers will unavoidably have to write +their own action functions. A few tricks listed below might help in +this regard. + +@itemize @bullet +@item +Making windows atomic (@pxref{Atomic Windows}) avoids breaking an +existing window composition when popping up a new window. +The new window will pop up outside the composition instead. + +@item +Temporarily dedicating windows to their buffers (@pxref{Dedicated +Windows}) avoids using a window for displaying a different +buffer. A non-dedicated window will be used instead. + +@item +Calling @code{window-preserve-size} (@pxref{Preserving Window Sizes}) +will try to keep the size of the argument window unchanged when +popping up a new window. You have to make sure that another window in +the same combination can be shrunk instead, though. + +@item +Side windows (@pxref{Side Windows}) can be used for displaying +specific buffers always in a window at the same position of a frame. +This permits grouping buffers that do not compete for being shown at +the same time on a frame and showing any such buffer in the same window +without disrupting the display of other buffers. + +@item +Child frames (@pxref{Child Frames}) can be used to display a buffer +within the screen estate of the selected frame without disrupting that +frame's window configuration and without the overhead associated with +full-fledged frames as inflicted by @code{display-buffer-pop-up-frame}. +@end itemize +@end table -@defun same-window-p buffer-name -This function returns @code{t} if displaying a buffer -named @var{buffer-name} with @code{display-buffer} would -put it in the selected window. -@end defun @node Window History @section Window History @@ -3053,6 +3902,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 @@ -3202,12 +4054,13 @@ main window is either a ``normal'' live window or specifies the area containing all the normal windows. In their most simple form of use, side windows allow to display -specific buffers always in the same area of a frame. Hence they can be -regarded as a generalization of the concept provided by -@code{display-buffer-at-bottom} (@pxref{Display Action Functions}) to -the remaining sides of a frame. With suitable customizations, however, -side windows can be also used to provide frame layouts similar to those -found in so-called integrated development environments (IDEs). +specific buffers always in the same area of a frame. Hence they can +be regarded as a generalization of the concept provided by +@code{display-buffer-at-bottom} (@pxref{Buffer Display Action +Functions}) to the remaining sides of a frame. With suitable +customizations, however, side windows can be also used to provide +frame layouts similar to those found in so-called integrated +development environments (IDEs). @menu * Displaying Buffers in Side Windows:: An action function for displaying @@ -3221,9 +4074,9 @@ found in so-called integrated development environments (IDEs). @node Displaying Buffers in Side Windows @subsection Displaying Buffers in Side Windows -The following action function for @code{display-buffer} (@pxref{Display -Action Functions}) creates or reuses a side window for displaying the -specified buffer. +The following action function for @code{display-buffer} (@pxref{Buffer +Display Action Functions}) creates or reuses a side window for +displaying the specified buffer. @defun display-buffer-in-side-window buffer alist This function displays @var{buffer} in a side window of the selected @@ -3263,11 +4116,11 @@ explicitly provided via a @code{window-parameters} entry in @var{alist}. @end defun By default, side windows cannot be split via @code{split-window} -(@pxref{Splitting Windows}). Also, a side window is not reused or split -by any buffer display action (@pxref{Display Action Functions}) unless -it is explicitly specified as target of that action. Note also that -@code{delete-other-windows} cannot make a side window the only window on -its frame (@pxref{Deleting Windows}). +(@pxref{Splitting Windows}). Also, a side window is not reused or +split by any buffer display action (@pxref{Buffer Display Action +Functions}) unless it is explicitly specified as target of that +action. Note also that @code{delete-other-windows} cannot make a side +window the only window on its frame (@pxref{Deleting Windows}). Once set up, side windows also change the behavior of the commands @code{switch-to-prev-buffer} and @code{switch-to-next-buffer} @@ -3453,9 +4306,9 @@ retain their respective sizes when maximizing the frame, the variable @xref{Resizing Windows}. The last form also makes sure that none of the created side windows -are accessible via @kbd{C-x o} by installing the @code{no-other-window} +are accessible via @w{@kbd{C-x o}} by installing the @code{no-other-window} parameter for each of these windows. In addition, it makes sure that -side windows are not deleted via @kbd{C-x 1} by installing the +side windows are not deleted via @w{@kbd{C-x 1}} by installing the @code{no-delete-other-windows} parameter for each of these windows. Since @code{dired} buffers have no fixed names, we use a special @@ -3547,7 +4400,7 @@ does is to set the @code{window-atom} parameter of each descendant of To create a new atomic window from an existing live window or to add a new window to an existing atomic window, the following buffer display -action function (@pxref{Display Action Functions}) can be used: +action function (@pxref{Buffer Display Action Functions}) can be used: @defun display-buffer-in-atom-window buffer alist This function tries to display @var{buffer} in a new window that will be @@ -4096,7 +4949,8 @@ fashion. @defopt scroll-up-aggressively Likewise, for scrolling up. The value, @var{f}, specifies how far point should be placed from the bottom of the window; thus, as with -@code{scroll-up-aggressively}, a larger value scrolls more aggressively. +@code{scroll-down-aggressively}, a larger value scrolls more +aggressively. @end defopt @defopt scroll-step @@ -4846,10 +5700,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 @@ -4911,9 +5761,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} @@ -4967,10 +5818,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 @@ -5159,27 +6010,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 @@ -5190,65 +6040,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}). - -The buffer-local value of this hook is run once for the buffer and the -frame in question, provided at least one window showing the buffer on -that frame has changed its size. As it still receives the frame as -its sole argument, any function called on a buffer-local basis will be -oblivious to which window(s) showing the buffer changed its (their) -size and has to check out these windows by using the method described -in the previous paragraph. - -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. - -You may use @code{save-selected-window} in these functions -(@pxref{Selecting Windows}). However, do not use -@code{save-window-excursion} (@pxref{Window Configurations}); exiting -that macro counts as a size change, which would cause these functions to -be called again. +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. Resizing the -frame or individual windows do not count as configuration changes. Use -@code{window-size-change-functions}, see above, when you want to track -size changes that are not caused by the deletion or creation of windows. - -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 -@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. +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 + +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/ChangeLog.1 b/doc/man/ChangeLog.1 index b72837fea75..68e411232ab 100644 --- a/doc/man/ChangeLog.1 +++ b/doc/man/ChangeLog.1 @@ -176,7 +176,7 @@ ;; coding: utf-8 ;; End: - Copyright (C) 2007-2018 Free Software Foundation, Inc. + Copyright (C) 2007-2019 Free Software Foundation, Inc. This file is part of GNU Emacs. diff --git a/doc/man/ebrowse.1 b/doc/man/ebrowse.1 index c0245f8259f..b0448d48981 100644 --- a/doc/man/ebrowse.1 +++ b/doc/man/ebrowse.1 @@ -82,7 +82,7 @@ should give you access to the complete manual. was written by Gerd Moellmann. . .SH COPYING -Copyright 2008-2018 Free Software Foundation, Inc. +Copyright 2008-2019 Free Software Foundation, Inc. .PP Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are diff --git a/doc/man/emacs.1.in b/doc/man/emacs.1.in index e332fb45c7b..11a3390b17e 100644 --- a/doc/man/emacs.1.in +++ b/doc/man/emacs.1.in @@ -279,8 +279,8 @@ window's width, height, and position as specified. The geometry specification is in the standard X format; see .BR X (7) for more information. -The width and height are specified in characters; the default is -80 by 24. +The width and height are specified in characters; the default for GUI +frames is 80 by 36. See the Emacs manual, section "Options for Window Size and Position", for information on how window sizes interact with selecting or deselecting the tool bar and menu bar. @@ -653,7 +653,7 @@ For detailed credits and acknowledgments, see the GNU Emacs manual. . . .SH COPYING -Copyright 1995, 1999-2018 Free Software Foundation, Inc. +Copyright 1995, 1999-2019 Free Software Foundation, Inc. .PP Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are diff --git a/doc/man/etags.1 b/doc/man/etags.1 index 558b249f31b..7cc501cc496 100644 --- a/doc/man/etags.1 +++ b/doc/man/etags.1 @@ -281,7 +281,7 @@ Stallman. .BR vi ( 1 ). .SH COPYING -Copyright 1992, 1999, 2001-2018 Free Software Foundation, Inc. +Copyright 1992, 1999, 2001-2019 Free Software Foundation, Inc. .PP Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are diff --git a/doc/misc/ChangeLog.1 b/doc/misc/ChangeLog.1 index 9ef3f0ea6f2..9b25c90f7f6 100644 --- a/doc/misc/ChangeLog.1 +++ b/doc/misc/ChangeLog.1 @@ -12116,7 +12116,7 @@ ;; coding: utf-8 ;; End: - Copyright (C) 1993-1999, 2001-2018 Free Software Foundation, Inc. + Copyright (C) 1993-1999, 2001-2019 Free Software Foundation, Inc. This file is part of GNU Emacs. diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index fd07ea4ca13..a03efaf8bef 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -1,6 +1,6 @@ ### @configure_input@ -# Copyright (C) 1994, 1996-2018 Free Software Foundation, Inc. +# Copyright (C) 1994, 1996-2019 Free Software Foundation, Inc. # This file is part of GNU Emacs. diff --git a/doc/misc/ada-mode.texi b/doc/misc/ada-mode.texi index ca6214527cc..1ac90cdc7f1 100644 --- a/doc/misc/ada-mode.texi +++ b/doc/misc/ada-mode.texi @@ -4,7 +4,7 @@ @include docstyle.texi @copying -Copyright @copyright{} 1999--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1999--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi index fcbc83ead5b..a46e3d73fce 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 @@ -11,7 +9,7 @@ @copying This file describes the Emacs auth-source library. -Copyright @copyright{} 2008--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2008--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -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. diff --git a/doc/misc/autotype.texi b/doc/misc/autotype.texi index 7e2476c225d..5eb45e28343 100644 --- a/doc/misc/autotype.texi +++ b/doc/misc/autotype.texi @@ -11,7 +11,7 @@ @c @cindex autotypist @copying -Copyright @copyright{} 1994--1995, 1999, 2001--2018 +Copyright @copyright{} 1994--1995, 1999, 2001--2019 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/bovine.texi b/doc/misc/bovine.texi index fc744eb6487..f138c47e498 100644 --- a/doc/misc/bovine.texi +++ b/doc/misc/bovine.texi @@ -24,7 +24,7 @@ @c %**end of header @copying -Copyright @copyright{} 1999--2004, 2012--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1999--2004, 2012--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi index f7b23d35471..ca322f21720 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -95,7 +95,7 @@ This file documents Calc, the GNU Emacs calculator, included with GNU Emacs @value{EMACSVER}. @end ifnotinfo -Copyright @copyright{} 1990--1991, 2001--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1990--1991, 2001--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -1775,7 +1775,7 @@ evaluated first, then @samp{*}, then @samp{/}, then finally is equivalent to @example -2 + ((3*4*5) / (6*(7^8)) - 9 +2 + ((3*4*5) / (6*(7^8))) - 9 @end example @noindent @@ -2026,7 +2026,7 @@ You can also ``unstore'' a variable when you are through with it: @smallexample @group -2: 2 + 5 => 5 +2: 2 + 3 => 5 1: 2 a + 2 b => 2 a + 2 b . diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index 5a229c1cd6f..f73a7fb57cb 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -148,7 +148,17 @@ CC Mode @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @comment Define an index for syntactic symbols. +@c Version for Texinfo <= 4.x +@ifclear txicommandconditionals +@ifnottex @c In texi2dvi, the @defindex would create an empty cc-mode.ss + @c For Info, unlike tex, @syncodeindex needs a matching @defindex. @defindex ss +@end ifnottex +@end ifclear +@c Version for Texinfo >= 5.x +@ifset txicommandconditionals +@defindex ss +@end ifset @comment Combine key, syntactic symbol and concept indices into one. @syncodeindex ss cp @@ -157,7 +167,7 @@ CC Mode @copying This manual is for CC Mode in Emacs. -Copyright @copyright{} 1995--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1995--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -2282,6 +2292,8 @@ method, ``Top-level commands or the customization interface''. If you make conflicting settings in several of these ways, the way that takes precedence is the one that appears latest in this list: +@c Version of list for Texinfo <= 4.x +@ifclear txicommandconditionals @itemize @w{} @item @table @asis @@ -2292,6 +2304,18 @@ that takes precedence is the one that appears latest in this list: @itemx File Local Variable setting @end table @end itemize +@end ifclear +@c Version of list for Texinfo >= 5.x +@ifset txicommandconditionals +@itemize @w{} +@item Style +@item File Style@footnote{In earlier versions of @ccmode{}, a File Style setting took precedence over any other setting apart from a File Local Variable setting.} +@item Top-level command or ``customization interface'' +@item Hook +@item File Local Variable setting +@end itemize +@end ifset + Here is a summary of the different ways of writing your configuration settings: @@ -2548,7 +2572,7 @@ Basics}). @item The style variable @code{c-offsets-alist} (@pxref{c-offsets-alist}) is an association list with an element for each syntactic symbol. It's -handled a little differently from the other style variables. It's +handled a little differently from the other style variables. Its default global binding is the empty list @code{nil}, rather than @code{set-from-style}. Before the style system is initialized, you can add individual elements to @code{c-offsets-alist} by calling @@ -5286,7 +5310,7 @@ The simplest and most used kind of ``offset'' setting in @defopt c-basic-offset @vindex basic-offset @r{(c-)} This style variable holds the basic offset between indentation levels. -It's factory default is 4, but all the built-in styles set it +Its factory default is 4, but all the built-in styles set it themselves, to some value between 2 (for @code{gnu} style) and 8 (for @code{bsd}, @code{linux}, and @code{python} styles). @end defopt @@ -5614,9 +5638,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 @@ -5971,6 +5995,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 diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 6985f194213..32b5076c902 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -7,7 +7,7 @@ @copying This file documents the GNU Emacs Common Lisp emulation package. -Copyright @copyright{} 1993, 2001--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1993, 2001--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi index 5b14382d8b8..c7d499884da 100644 --- a/doc/misc/dbus.texi +++ b/doc/misc/dbus.texi @@ -10,7 +10,7 @@ @syncodeindex fn cp @copying -Copyright @copyright{} 2007--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2007--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -1015,7 +1015,7 @@ but different to The value for a byte D-Bus type can be any integer in the range 0 through 255. If a character is used as argument, modifiers -represented outside this range are stripped of. For example, +represented outside this range are stripped off. For example, @code{:byte ?x} is equal to @code{:byte ?\M-x}, but it is not equal to @code{:byte ?\C-x} or @code{:byte ?\M-\C-x}. diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi index f65542f02ea..b6a9d23f7dc 100644 --- a/doc/misc/dired-x.texi +++ b/doc/misc/dired-x.texi @@ -20,7 +20,7 @@ @comment %**end of header (This is for running Texinfo on a region.) @copying -Copyright @copyright{} 1994--1995, 1999, 2001--2018 +Copyright @copyright{} 1994--1995, 1999, 2001--2019 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/ebrowse.texi b/doc/misc/ebrowse.texi index b6f2c1865fd..0d4a44ee7ce 100644 --- a/doc/misc/ebrowse.texi +++ b/doc/misc/ebrowse.texi @@ -11,7 +11,7 @@ @copying This file documents Ebrowse, a C++ class browser for GNU Emacs. -Copyright @copyright{} 2000--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2000--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi index 42bedb10f68..7ab386c97a4 100644 --- a/doc/misc/ede.texi +++ b/doc/misc/ede.texi @@ -6,7 +6,7 @@ @copying This file describes EDE, the Emacs Development Environment. -Copyright @copyright{} 1998--2001, 2004--2005, 2008--2018 +Copyright @copyright{} 1998--2001, 2004--2005, 2008--2019 Free Software Foundation, Inc. @quotation @@ -1038,7 +1038,7 @@ details on using @eieio{} to extending classes, and writing methods. If you intend to extend @ede{}, it is most likely that a new target type is needed in one of the existing project types. The rest of this chapter -will discuss extending the @code{ede-project} class, and it's targets. +will discuss extending the @code{ede-project} class, and its targets. See @file{project-am.el} for basic details on adding targets to it. For the @code{ede-project} type, the core target class is called @@ -1477,7 +1477,7 @@ Get the inode of the directory project @var{PROJ} is in. @end deffn @deffn Method ede-project-root :AFTER this -If a project knows it's root, return it here. +If a project knows its root, return it here. Allows for one-project-object-for-a-tree type systems. @end deffn @@ -1486,7 +1486,7 @@ Find a subproject of @var{PROJ} that corresponds to @var{DIR}. @end deffn @deffn Method ede-project-root-directory :AFTER this &optional file -If a project knows it's root, return it here. +If a project knows its root, return it here. Allows for one-project-object-for-a-tree type systems. Optional @var{FILE} is the file to test. It is ignored in preference of the anchor file for the project. @@ -2516,7 +2516,7 @@ In sources for @var{THIS}, change version numbers to @var{VERSION}. @end deffn @deffn Method project-delete-target :AFTER ot -Delete the current target @var{OT} from it's parent project. +Delete the current target @var{OT} from its parent project. @end deffn @deffn Method ede-target-sourcecode :AFTER this @@ -2715,7 +2715,7 @@ Converts all symbols into the objects to be used. @end deffn @deffn Method project-delete-target :AFTER this -Delete the current target @var{THIS} from it's parent project. +Delete the current target @var{THIS} from its parent project. @end deffn @deffn Method ede-proj-makefile-target-name :AFTER this @@ -4013,7 +4013,7 @@ Type: @code{list} The commands used to execute this compiler. The object which uses this compiler will place these commands after -it's rule definition. +its rule definition. @item :autoconf Type: @code{list} @* @@ -4125,7 +4125,7 @@ Type: @code{list} The commands used to execute this compiler. The object which uses this compiler will place these commands after -it's rule definition. +its rule definition. @item :objectextention Type: @code{string} @@ -4265,7 +4265,7 @@ Type: @code{list} The commands used to execute this compiler. The object which uses this compiler will place these commands after -it's rule definition. +its rule definition. @item :objectextention Type: @code{string} diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi index 746c4c829d2..c4ef1da3158 100644 --- a/doc/misc/ediff.texi +++ b/doc/misc/ediff.texi @@ -26,7 +26,7 @@ This file documents Ediff, a comprehensive visual interface to Unix diff and patch utilities. -Copyright @copyright{} 1995--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1995--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -210,11 +210,11 @@ ancestors. Ediff selects only the files that are under version control. @item ediff-windows-wordwise @findex ediff-windows-wordwise -Compare windows word-by-word. +Compare text visible in 2 windows word-by-word. @item ediff-windows-linewise @findex ediff-windows-linewise -Compare windows line-by-line. +Compare text visible in 2 windows line-by-line. @item ediff-regions-wordwise @findex ediff-regions-wordwise @@ -373,13 +373,12 @@ The commands @code{ediff-windows-wordwise}, @code{ediff-windows-linewise}, @code{ediff-regions-wordwise} and @code{ediff-regions-linewise} do comparison on parts of existing Emacs buffers. The commands @code{ediff-windows-wordwise} and -@code{ediff-regions-wordwise} are intended for relatively small segments -of buffers (e.g., up to 100 lines, depending on the speed of your machine), +@code{ediff-regions-wordwise} could be slow on very large buffers, as they perform comparison on the basis of words rather than lines. -(Word-wise comparison of large chunks of text can be slow.) +(Word-wise comparison of large chunks of text is relatively expensive.) -To compare large regions, use @code{ediff-regions-linewise}. This -command displays differences much like @code{ediff-files} and +To compare very large regions, use @code{ediff-regions-linewise}. +This command displays differences much like @code{ediff-files} and @code{ediff-buffers}. The functions @code{ediff-patch-file} and @code{ediff-patch-buffer} apply a @@ -1148,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, diff --git a/doc/misc/edt.texi b/doc/misc/edt.texi index 754e3c82b23..74224e96314 100644 --- a/doc/misc/edt.texi +++ b/doc/misc/edt.texi @@ -6,7 +6,7 @@ @copying This file documents the EDT emulation package for Emacs. -Copyright @copyright{} 1986, 1992, 1994--1995, 1999--2018 +Copyright @copyright{} 1986, 1992, 1994--1995, 1999--2019 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/efaq-w32.texi b/doc/misc/efaq-w32.texi index e18bb739f84..8e067a7a269 100644 --- a/doc/misc/efaq-w32.texi +++ b/doc/misc/efaq-w32.texi @@ -15,7 +15,7 @@ Answers to Frequently asked Questions about using Emacs on Microsoft Windows. @include emacsver.texi @copying -Copyright @copyright{} 2008, 2010-2018 Free Software Foundation, Inc. +Copyright @copyright{} 2008, 2010-2019 Free Software Foundation, Inc. @quotation This list of frequently asked questions about GNU Emacs on MS Windows diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi index 0d4e4ba8bdd..485776e1c73 100644 --- a/doc/misc/efaq.texi +++ b/doc/misc/efaq.texi @@ -12,7 +12,7 @@ @c appreciate a notice if you do). @copying -Copyright @copyright{} 2001--2018 Free Software Foundation, Inc.@* +Copyright @copyright{} 2001--2019 Free Software Foundation, Inc.@* Copyright @copyright{} 1994, 1995, 1996, 1997, 1998, 1999, 2000 Reuven M. Lerner@* Copyright @copyright{} 1992, 1993 Steven Byrnes@* @@ -2005,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} diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi index 689ff72b723..d03ee79f18b 100644 --- a/doc/misc/eieio.texi +++ b/doc/misc/eieio.texi @@ -12,7 +12,7 @@ @copying This manual documents EIEIO, an object framework for Emacs Lisp. -Copyright @copyright{} 2007--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2007--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/emacs-gnutls.texi b/doc/misc/emacs-gnutls.texi index a690ccfccef..add79d12e42 100644 --- a/doc/misc/emacs-gnutls.texi +++ b/doc/misc/emacs-gnutls.texi @@ -9,7 +9,7 @@ @copying This file describes the Emacs GnuTLS integration. -Copyright @copyright{} 2012--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2012--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -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 f46b2a7fc1d..dd651fff356 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 @@ -12,7 +10,7 @@ @copying This file documents the Emacs MIME interface functionality. -Copyright @copyright{} 1998--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1998--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -698,13 +696,15 @@ Translation}. A description of the part (@code{Content-Description}). @item creation-date -RFC822 date when the part was created (@code{Content-Disposition}). +Date when the part was created (@code{Content-Disposition}). +This uses the format of RFC 822 or its successors. @item modification-date -RFC822 date when the part was modified (@code{Content-Disposition}). +RFC 822 (or later) date when the part was modified +(@code{Content-Disposition}). @item read-date -RFC822 date when the part was read (@code{Content-Disposition}). +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 @@ -754,7 +754,7 @@ be obtained. Values include @samp{ftp}, @samp{anon-ftp}, @samp{tftp}, @samp{localfile}, and @samp{mailserver}. (@code{Content-Type}.) @item expiration -The RFC822 date after which the file may no longer be fetched. +RFC 822 (or later) date after which the file may no longer be fetched. (@code{Content-Type}.) @item size @@ -1301,7 +1301,7 @@ on. High-level functionality is dealt with in the first chapter @menu * rfc2045:: Encoding @code{Content-Type} headers. * rfc2231:: Parsing @code{Content-Type} headers. -* ietf-drums:: Handling mail headers defined by RFC822bis. +* ietf-drums:: Handling mail headers defined by RFC 2822. * rfc2047:: En/decoding encoded words in headers. * time-date:: Functions for parsing dates and manipulating time. * qp:: Quoted-Printable en/decoding. @@ -1385,8 +1385,8 @@ Encode a parameter in headers likes @code{Content-Type} and @node ietf-drums @section ietf-drums -@dfn{drums} is an IETF working group that is working on the replacement -for RFC822. +@dfn{drums} was an IETF working group that worked on Internet RFC 2822, +the first successor to RFC 822 and a predecessor of the current email standard. The functions provided by this library include: @@ -1597,7 +1597,7 @@ The five data representations used are the following: @table @var @item date -An RFC822 (or similar) date string. For instance: @code{"Sat Sep 12 +An RFC 822 (or similar) date string. For instance: @code{"Sat Sep 12 12:21:54 1998 +0200"}. @item time @@ -1889,55 +1889,55 @@ in @file{/etc/mailcap} will ``win'' over an @samp{image/*} setting in The Emacs @acronym{MIME} library implements handling of various elements according to a (somewhat) large number of RFCs, drafts and standards documents. This chapter lists the relevant ones. They can all be -fetched from @uref{http://quimby.gnus.org/notes/}. +fetched from @uref{https://www.rfc-editor.org}. @table @dfn -@item RFC822 -@itemx STD11 -Standard for the Format of ARPA Internet Text Messages. +@item RFC 5322 +Internet Message Format -@item RFC1036 -Standard for Interchange of USENET Messages +@item RFC 5536 +Netnews Article Format -@item RFC2045 +@item RFC 2045 Format of Internet Message Bodies -@item RFC2046 +@item RFC 2046 Media Types -@item RFC2047 +@item RFC 2047 Message Header Extensions for Non-@acronym{ASCII} Text -@item RFC2048 -Registration Procedures +@item RFC 6838 +Media Type Specifications and Registration Procedures -@item RFC2049 +@item RFC 4289 +Registration Procedures (obsoleting RFC 2048) + +@item RFC 2049 Conformance Criteria and Examples -@item RFC2231 +@item RFC 2231 @acronym{MIME} Parameter Value and Encoded Word Extensions: Character Sets, Languages, and Continuations -@item RFC1843 +@item RFC 1843 HZ---A Data Format for Exchanging Files of Arbitrarily Mixed Chinese and @acronym{ASCII} characters -@item draft-ietf-drums-msg-fmt-05.txt -Draft for the successor of RFC822 - -@item RFC2112 +@item RFC 2387 The @acronym{MIME} Multipart/Related Content-type -@item RFC1892 -The Multipart/Report Content Type for the Reporting of Mail System +@item RFC 6522 +@itemx STD 73 +The Multipart/Report Media Type for the Reporting of Mail System Administrative Messages -@item RFC2183 +@item RFC 2183 Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field -@item RFC2646 -Documentation of the text/plain format parameter for flowed text. +@item RFC 3676 +The Text/Plain Format and DelSp Parameters @end table diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi index d5dfe70760e..330ce7092f9 100644 --- a/doc/misc/epa.texi +++ b/doc/misc/epa.texi @@ -10,7 +10,7 @@ @copying This file describes EasyPG Assistant @value{VERSION}. -Copyright @copyright{} 2007--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2007--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index 55556c52810..e1d2217806a 100644 --- a/doc/misc/erc.texi +++ b/doc/misc/erc.texi @@ -10,7 +10,7 @@ @copying This manual is for ERC as distributed with Emacs @value{EMACSVER}. -Copyright @copyright{} 2005--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2005--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi index 6a34f5c5722..d2d86555e3c 100644 --- a/doc/misc/ert.texi +++ b/doc/misc/ert.texi @@ -15,7 +15,7 @@ @end direntry @copying -Copyright @copyright{} 2008, 2010--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2008, 2010--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index c19d5e1a437..716b4b7a50d 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -10,7 +10,7 @@ @copying This manual is for Eshell, the Emacs shell. -Copyright @copyright{} 1999--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1999--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -213,8 +213,8 @@ available in the Emacs Lisp library. It does this by transforming the input line into a callable Lisp form.@footnote{To see the Lisp form that will be invoked, type: @samp{eshell-parse-command "echo hello"}} The command can be either an Elisp function or an external command. -Eshell looks first for an @ref{Aliases, alias} with the same name as the -command, then a @ref{Built-ins, built-in command} or a function with the +Eshell looks first for an alias (@pxref{Aliases}) with the same name as the +command, then a built-in (@pxref{Built-ins}) or a function with the same name; if there is no match, it then tries to execute it as an external command. @@ -253,7 +253,7 @@ eshell/ls is a compiled Lisp function in `em-ls.el' @end example If you want to discard a given built-in command, you could declare an -alias, @ref{Aliases}. Example: +alias (@pxref{Aliases}). Example: @example ~ $ which sudo @@ -280,8 +280,7 @@ with no arguments, prints the current paths in this variable. @item alias @cmindex alias -Define an alias (@pxref{Aliases}). This does not add it to the aliases -file. +Define an alias (@pxref{Aliases}). This adds it to the aliases file. @item clear @cmindex clear @@ -419,7 +418,7 @@ Lisp functions, based on successful completion). @end table -@ref{Aliases} for the built-in variables @samp{$*}, @samp{$1}, +@xref{Aliases}, for the built-in variables @samp{$*}, @samp{$1}, @samp{$2}, @dots{}, in alias definitions. @node Variables @@ -500,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 @@ -630,8 +628,8 @@ to @code{"hello"}. Eshell's globbing syntax is very similar to that of Zsh. Users coming from Bash can still use Bash-style globbing, as there are no incompatibilities. Most globbing is pattern-based expansion, but there -is also predicate-based expansion. See -@ref{Filename Generation, , , zsh, The Z Shell Manual} +is also predicate-based expansion. @xref{Filename Generation, , , +zsh, The Z Shell Manual}, for full syntax. To customize the syntax and behavior of globbing in Eshell see the Customize@footnote{@xref{Easy Customization, , , emacs, The GNU Emacs Manual}.} diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi index e41be8684ed..117b62e9ac8 100644 --- a/doc/misc/eudc.texi +++ b/doc/misc/eudc.texi @@ -14,7 +14,7 @@ This file documents EUDC version 1.40.0. EUDC is the Emacs Unified Directory Client, a common interface to directory servers and contact information. -Copyright @copyright{} 1998, 2000--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1998, 2000--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi index aa17eee9d94..8dc58e84257 100644 --- a/doc/misc/eww.texi +++ b/doc/misc/eww.texi @@ -8,7 +8,7 @@ @copying This file documents the GNU Emacs Web Wowser (EWW) package. -Copyright @copyright{} 2014--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2014--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -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 @@ -118,16 +122,17 @@ variable-pitch fonts or not. This sets the @code{shr-use-fonts} variable. @findex eww-toggle-colors @findex shr-use-colors @kindex F - The @kbd{C} command (@code{eww-toggle-colors}) toggles whether to use + The @kbd{M-C} command (@code{eww-toggle-colors}) toggles whether to use HTML-specified colors or not. This sets the @code{shr-use-colors} variable. @findex eww-download @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 diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi index bda7e1428b5..894203ca5a1 100644 --- a/doc/misc/flymake.texi +++ b/doc/misc/flymake.texi @@ -14,7 +14,7 @@ This manual is for GNU Flymake (version @value{VERSION}, @value{UPDATED}), which is a universal on-the-fly syntax checker for GNU Emacs. -Copyright @copyright{} 2004--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2004--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/forms.texi b/doc/misc/forms.texi index 70463419e80..d669ed6d038 100644 --- a/doc/misc/forms.texi +++ b/doc/misc/forms.texi @@ -19,7 +19,7 @@ @copying This file documents Forms mode, a form-editing major mode for GNU Emacs. -Copyright @copyright{} 1989, 1997, 2001--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1989, 1997, 2001--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/gnus-coding.texi b/doc/misc/gnus-coding.texi index 4590524348d..6affea48724 100644 --- a/doc/misc/gnus-coding.texi +++ b/doc/misc/gnus-coding.texi @@ -8,7 +8,7 @@ @syncodeindex pg cp @copying -Copyright @copyright{} 2004--2005, 2007--2018 Free Software +Copyright @copyright{} 2004--2005, 2007--2019 Free Software Foundation, Inc. @quotation @@ -141,7 +141,7 @@ There are no Gnus dependencies in this file. There are no Gnus dependencies in this file. @item ietf-drums.el -Functions for parsing RFC822bis headers. +Functions for parsing RFC 2822 headers. @c As of 2005-10-21... There are no Gnus dependencies in this file. @@ -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 2ae5a0a0420..075f5218414 100644 --- a/doc/misc/gnus-faq.texi +++ b/doc/misc/gnus-faq.texi @@ -1,7 +1,7 @@ @c \input texinfo @c -*-texinfo-*- @c Uncomment 1st line before texing this file alone. @c %**start of header -@c Copyright (C) 1995, 2001-2018 Free Software Foundation, Inc. +@c Copyright (C) 1995, 2001-2019 Free Software Foundation, Inc. @c @c @setfilename gnus-faq.info @c @settitle Frequently Asked Questions @@ -284,7 +284,7 @@ what's this? @subsubheading Answer You get the message described in the q/a pair above while -starting Gnus, right? It's an other symptom for the same +starting Gnus, right? It's another symptom for the same problem, so read the answer above. @node FAQ 2-3 diff --git a/doc/misc/gnus-news.el b/doc/misc/gnus-news.el deleted file mode 100644 index 301ea932795..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-2018 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-2018 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 171f59a3ad0..00000000000 --- a/doc/misc/gnus-news.texi +++ /dev/null @@ -1,371 +0,0 @@ -@c -*-texinfo-*- - -@c Copyright (C) 2004-2018 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 fb9113f4608..b9c91a02a3a 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 @@ -10,7 +8,7 @@ @syncodeindex pg cp @copying -Copyright @copyright{} 1995--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1995--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -9418,7 +9416,7 @@ function must return @code{mid}, @code{mail}, @code{invalid} or @item gnus-button-mid-or-mail-heuristic @findex gnus-button-mid-or-mail-heuristic Function that guesses whether its argument is a message ID or a mail -address. Returns @code{mid} if it's a message IDs, @code{mail} if +address. Returns @code{mid} if it's a message ID, @code{mail} if it's a mail address, @code{ask} if unsure and @code{invalid} if the string is invalid. @@ -9679,7 +9677,7 @@ Each article is divided into two parts---the head and the body. The body can be divided into a signature part and a text part. The variable that says what is to be considered a signature is @code{gnus-signature-separator}. This is normally the standard -@samp{^-- $} as mandated by son-of-RFC 1036. However, many people use +@samp{^-- $} as mandated by RFC 5536. However, many people use non-standard signature separators, so this variable can also be a list of regular expressions to be tested, one by one. (Searches are done from the end of the body towards the beginning.) One likely value is: @@ -15991,8 +15989,9 @@ Mailers and list servers are notorious for doing all sorts of really, really stupid things with mail. ``Hey, RFC 822 doesn't explicitly prohibit us from adding the string @code{wE aRe ElItE!!!!!1!!} to the end of all lines passing through our server, so let's do that!!!!1!'' -Yes, but RFC 822 wasn't designed to be read by morons. Things that were -considered to be self-evident were not discussed. So. Here we are. +Yes, but RFC 822 and its successors weren't designed to be read by +morons. Things that were considered to be self-evident were not +discussed. So. Here we are. Case in point: The German version of Microsoft Exchange adds @samp{AW: } to the subjects of replies instead of @samp{Re: }. I could pretend to @@ -17374,7 +17373,7 @@ Announcement messages from LANL Gov Announce. @cindex forwarded messages @item rfc822-forward -A message forwarded according to RFC822. +A message forwarded according to RFC 822 or its successors. @item outlook The Outlook mail box. @@ -21468,6 +21467,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 @@ -26709,18 +26720,20 @@ with, of course. @table @strong -@item RFC (2)822 +@item RFC 822 @cindex RFC 822 @cindex RFC 2822 -There are no known breaches of this standard. +@cindex RFC 5322 +There are no known breaches of this standard or its successors +(currently RFCs 2822 and 5322). @item RFC 1036 @cindex RFC 1036 -There are no known breaches of this standard, either. +There are no known breaches of this (now-obsolete) standard, either. -@item Son-of-RFC 1036 -@cindex Son-of-RFC 1036 -We do have some breaches to this one. +@item RFC 5536 +@cindex RFC 5536 +We do have some breaches of this standard, the successor of RFC 1036. @table @emph @@ -26735,10 +26748,9 @@ it wasn't for the @code{X-Newsreader} header. @item USEFOR @cindex USEFOR -USEFOR is an IETF working group writing a successor to RFC 1036, based -on Son-of-RFC 1036. They have produced a number of drafts proposing -various changes to the format of news articles. The Gnus towers will -look into implementing the changes when the draft is accepted as an RFC. +USEFOR was an IETF working group that produced Internet RFCs 5536 and 5537. +The Gnus towers will look into implementing the changes embodied by these +standards. @item MIME---RFC 2045--2049 etc @cindex @acronym{MIME} @@ -27204,6 +27216,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. @@ -28574,7 +28588,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 @@ -29517,7 +29882,8 @@ header = <text> eol @end example @cindex BNF -(The version of BNF used here is the one used in RFC822.) +(The version of extended BNF used here is ABNF, the one used in Internet RFCs. +See RFC 5234.) If the return value is @code{nov}, the data buffer should contain @dfn{network overview database} lines. These are basically fields @@ -30315,7 +30681,7 @@ almost suspect that the author looked at the @acronym{NOV} specification and just shamelessly @emph{stole} the entire thing, and one would be right. @dfn{Header} is a severely overloaded term. ``Header'' is used in -RFC 1036 to talk about lines in the head of an article (e.g., +RFC 5536 to talk about lines in the head of an article (e.g., @code{From}). It is used by many people as a synonym for ``head''---``the header and the body''. (That should be avoided, in my opinion.) And Gnus uses a format internally that it calls ``header'', diff --git a/doc/misc/htmlfontify.texi b/doc/misc/htmlfontify.texi index c4cf7dac0a6..f1da8785eb7 100644 --- a/doc/misc/htmlfontify.texi +++ b/doc/misc/htmlfontify.texi @@ -10,7 +10,7 @@ This manual documents Htmlfontify, a source code -> crosslinked + formatted + syntax colorized html transformer. -Copyright @copyright{} 2002-2003, 2013-2018 Free Software Foundation, +Copyright @copyright{} 2002-2003, 2013-2019 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/idlwave.texi b/doc/misc/idlwave.texi index ca4d89c5f8f..fd48bc05168 100644 --- a/doc/misc/idlwave.texi +++ b/doc/misc/idlwave.texi @@ -23,7 +23,7 @@ Emacs, and interacting with an IDL shell run as a subprocess. This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE @value{VERSION}. -Copyright @copyright{} 1999--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1999--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/ido.texi b/doc/misc/ido.texi index 098b28ee524..bb7e7232657 100644 --- a/doc/misc/ido.texi +++ b/doc/misc/ido.texi @@ -7,7 +7,7 @@ @copying This file documents the Ido package for GNU Emacs. -Copyright @copyright{} 2013-2018 Free Software Foundation, Inc. +Copyright @copyright{} 2013-2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/info.texi b/doc/misc/info.texi index e277b13ba87..e69779a03ca 100644 --- a/doc/misc/info.texi +++ b/doc/misc/info.texi @@ -15,7 +15,7 @@ This file describes how to use Info, the menu-driven GNU documentation system. -Copyright @copyright{} 1989, 1992, 1996--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1989, 1992, 1996--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/mairix-el.texi b/doc/misc/mairix-el.texi index 8d620c720e6..c45ed11e498 100644 --- a/doc/misc/mairix-el.texi +++ b/doc/misc/mairix-el.texi @@ -5,7 +5,7 @@ @include docstyle.texi @copying -Copyright @copyright{} 2008--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2008--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/message.texi b/doc/misc/message.texi index 61eca759f46..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 @@ -11,7 +9,7 @@ @copying This file documents Message, the Emacs message composition mode. -Copyright @copyright{} 1996--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1996--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/mh-e.texi b/doc/misc/mh-e.texi index 85455257475..99070950026 100644 --- a/doc/misc/mh-e.texi +++ b/doc/misc/mh-e.texi @@ -25,7 +25,7 @@ This is version @value{VERSION}@value{EDITION} of @cite{The MH-E Manual}, last updated @value{UPDATED}. -Copyright @copyright{} 1995, 2001--2003, 2005--2018 Free Software +Copyright @copyright{} 1995, 2001--2003, 2005--2019 Free Software Foundation, Inc. @c This dual license has been agreed upon by the FSF. diff --git a/doc/misc/newsticker.texi b/doc/misc/newsticker.texi index ac29ced8fb7..5db3f43b2b9 100644 --- a/doc/misc/newsticker.texi +++ b/doc/misc/newsticker.texi @@ -15,7 +15,7 @@ This manual documents Newsticker, a feed reader for Emacs. It corresponds to Emacs version @value{EMACSVER}. @noindent -Copyright @copyright{} 2004--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2004--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/nxml-mode.texi b/doc/misc/nxml-mode.texi index 32b873e8919..edab900652d 100644 --- a/doc/misc/nxml-mode.texi +++ b/doc/misc/nxml-mode.texi @@ -9,7 +9,7 @@ This manual documents nXML mode, an Emacs major mode for editing XML with RELAX NG support. -Copyright @copyright{} 2007--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2007--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/octave-mode.texi b/doc/misc/octave-mode.texi index 927a15dcf62..d409b90e276 100644 --- a/doc/misc/octave-mode.texi +++ b/doc/misc/octave-mode.texi @@ -6,7 +6,7 @@ @c %**end of header @copying -Copyright @copyright{} 1996--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1996--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/org.texi b/doc/misc/org.texi index 9ea78f5ace9..7862713f47a 100644 --- a/doc/misc/org.texi +++ b/doc/misc/org.texi @@ -260,7 +260,7 @@ @copying This manual is for Org version @value{VERSION}. -Copyright @copyright{} 2004--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2004--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -13789,7 +13789,7 @@ Copyright information is printed on the back of the title page. This is a short example of a complete Texinfo file, version 1.0. - Copyright \copy 2018 Free Software Foundation, Inc. + Copyright \copy 2019 Free Software Foundation, Inc. @end example @node Info directory file @@ -14066,7 +14066,7 @@ This manual is for GNU Sample (version @{@{@{version@}@}@}, This manual is for GNU Sample (version @{@{@{version@}@}@}, @{@{@{updated@}@}@}), which is an example in the Texinfo documentation. - Copyright \copy 2018 Free Software Foundation, Inc. + Copyright \copy 2019 Free Software Foundation, Inc. #+BEGIN_QUOTE Permission is granted to copy, distribute and/or modify this diff --git a/doc/misc/pcl-cvs.texi b/doc/misc/pcl-cvs.texi index fe501542f86..3379783f6c6 100644 --- a/doc/misc/pcl-cvs.texi +++ b/doc/misc/pcl-cvs.texi @@ -7,7 +7,7 @@ @c %**end of header @copying -Copyright @copyright{} 1991--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1991--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/pgg.texi b/doc/misc/pgg.texi index e5fe2faf2da..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 @@ -12,7 +10,7 @@ This file describes PGG @value{VERSION}, an Emacs interface to various PGP implementations. -Copyright @copyright{} 2001, 2003--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2001, 2003--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/rcirc.texi b/doc/misc/rcirc.texi index 0287054b1d2..bbcd0ed4620 100644 --- a/doc/misc/rcirc.texi +++ b/doc/misc/rcirc.texi @@ -6,7 +6,7 @@ @c %**end of header @copying -Copyright @copyright{} 2006--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2006--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/reftex.texi b/doc/misc/reftex.texi index 4367d773e63..baa8de4b4dc 100644 --- a/doc/misc/reftex.texi +++ b/doc/misc/reftex.texi @@ -46,7 +46,7 @@ This manual documents @RefTeX{} (version @value{VERSION}), a package to do labels, references, citations and indices for LaTeX documents with Emacs. -Copyright @copyright{} 1997--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1997--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/remember.texi b/doc/misc/remember.texi index 8e42708be92..e692f14cdaa 100644 --- a/doc/misc/remember.texi +++ b/doc/misc/remember.texi @@ -9,7 +9,7 @@ @copying This manual is for Remember Mode, version 2.0 -Copyright @copyright{} 2001, 2004--2005, 2007--2018 +Copyright @copyright{} 2001, 2004--2005, 2007--2019 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/sasl.texi b/doc/misc/sasl.texi index 00e25f45583..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 @@ -11,7 +9,7 @@ @copying This file describes the Emacs SASL library, version @value{VERSION}. -Copyright @copyright{} 2000, 2004--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2000, 2004--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/sc.texi b/doc/misc/sc.texi index 453ccf2ec53..7d53c6dbe5e 100644 --- a/doc/misc/sc.texi +++ b/doc/misc/sc.texi @@ -15,7 +15,7 @@ This document describes Supercite, an Emacs package for citing and attributing replies to mail and news messages. -Copyright @copyright{} 1993, 2001--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1993, 2001--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -851,7 +851,8 @@ scanned. Info key-value pairs are created for each header found. Also, such useful information as the author's name and email address are extracted. If the variable @code{sc-mail-warn-if-non-rfc822-p} is non-@code{nil}, then Supercite will warn you if it finds a mail header -that does not conform to RFC822. This is rare and indicates a problem +that does not conform to RFC 822 (or later). +This is rare and indicates a problem either with your MUA or the original author's MUA, or some MTA (mail transport agent) along the way. diff --git a/doc/misc/sem-user.texi b/doc/misc/sem-user.texi index 8484a7bfe23..3fe104af1f5 100644 --- a/doc/misc/sem-user.texi +++ b/doc/misc/sem-user.texi @@ -1,5 +1,5 @@ @c This is part of the Semantic manual. -@c Copyright (C) 1999-2005, 2007, 2009-2018 Free Software Foundation, +@c Copyright (C) 1999-2005, 2007, 2009-2019 Free Software Foundation, @c Inc. @c See file semantic.texi for copying conditions. diff --git a/doc/misc/semantic.texi b/doc/misc/semantic.texi index 8d4920ce727..34afcba495c 100644 --- a/doc/misc/semantic.texi +++ b/doc/misc/semantic.texi @@ -25,7 +25,7 @@ @copying This manual documents the Semantic library and utilities. -Copyright @copyright{} 1999--2005, 2007, 2009--2018 Free Software +Copyright @copyright{} 1999--2005, 2007, 2009--2019 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/ses.texi b/doc/misc/ses.texi index aa4fe81ba52..f98a3b164bf 100644 --- a/doc/misc/ses.texi +++ b/doc/misc/ses.texi @@ -12,7 +12,7 @@ @copying This file documents @acronym{SES}: the Simple Emacs Spreadsheet. -Copyright @copyright{} 2002--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2002--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/sieve.texi b/doc/misc/sieve.texi index cad3cd86469..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 @@ -12,7 +10,7 @@ @copying This file documents the Emacs Sieve package, for server-side mail filtering. -Copyright @copyright{} 2001--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2001--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/smtpmail.texi b/doc/misc/smtpmail.texi index c3387054baf..365f55718e7 100644 --- a/doc/misc/smtpmail.texi +++ b/doc/misc/smtpmail.texi @@ -4,7 +4,7 @@ @include docstyle.texi @syncodeindex vr fn @copying -Copyright @copyright{} 2003--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2003--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/speedbar.texi b/doc/misc/speedbar.texi index d67c4e61456..503f9cd6465 100644 --- a/doc/misc/speedbar.texi +++ b/doc/misc/speedbar.texi @@ -5,7 +5,7 @@ @syncodeindex fn cp @copying -Copyright @copyright{} 1999--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1999--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/srecode.texi b/doc/misc/srecode.texi index 7d8416e9013..9df11b4b9f9 100644 --- a/doc/misc/srecode.texi +++ b/doc/misc/srecode.texi @@ -16,7 +16,7 @@ @c %**end of header @copying -Copyright @copyright{} 2007--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2007--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex index 5840aff4d7c..667292a96a1 100644 --- a/doc/misc/texinfo.tex +++ b/doc/misc/texinfo.tex @@ -3,12 +3,9 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2018-09-21.20} +\def\texinfoversion{2019-03-23.11} % -% Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, -% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, -% 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 -% 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 @@ -244,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. @@ -270,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. @@ -279,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 @@ -300,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 @@ -322,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 @@ -365,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}% % {% @@ -374,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 @@ -415,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 } @@ -451,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 @@ -487,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. % @@ -1163,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 @@ -1219,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}% } @@ -1227,7 +1197,7 @@ output) for that.)} \def\maincolor{\rgbBlack} \pdfsetcolor{\maincolor} \edef\thiscolor{\maincolor} - \def\lastcolordefs{} + \def\currentcolordefs{} % \def\makefootline{% \baselineskip24pt @@ -1605,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}% } @@ -1613,7 +1583,7 @@ output) for that.)} \def\maincolor{\rgbBlack} \pdfsetcolor{\maincolor} \edef\thiscolor{\maincolor} - \def\lastcolordefs{} + \def\currentcolordefs{} % \def\makefootline{% \baselineskip24pt @@ -2876,7 +2846,7 @@ end % @t, explicit typewriter. \def\t#1{% - {\tt \rawbackslash \plainfrenchspacing #1}% + {\tt \plainfrenchspacing #1}% \null } @@ -2903,7 +2873,6 @@ end % Turn off hyphenation. \nohyphenation % - \rawbackslash \plainfrenchspacing #1% }% @@ -3090,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'}% @@ -3134,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 1fil\relax + \allowbreak + \hskip 0pt plus -1fil\relax +} + \urefbreakstyle after % @url synonym for @uref, since that's how everyone uses it. @@ -3144,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 @@ -3154,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), @@ -4699,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'']}% @@ -4740,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 @@ -4890,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\@% @@ -4936,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{% % @@ -5102,11 +5031,9 @@ end \commondummyword\xref } -% For testing: output @{ and @} in index sort strings as \{ and \}. -\newif\ifusebracesinindexes - \let\indexlbrace\relax \let\indexrbrace\relax +\let\indexatchar\relax {\catcode`\@=0 \catcode`\\=13 @@ -5140,10 +5067,8 @@ end } \gdef\indexnonalnumreappear{% - \useindexbackslash \let-\normaldash \let<\normalless - \def\@{@}% } } @@ -5254,36 +5179,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 } @@ -5305,21 +5210,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{% @@ -5330,51 +5221,121 @@ end \xdef\indexsortkey{#1}\endgroup} } +\def\indexwriteseealso#1{ + \gdef\pagenumbertext{@seealso{#1}}% +} -% Write the entry in \toks0 to the index file. +% The default definitions +\def\sortas#1{}% +\def\seealso#1{\i{\putwordSeeAlso}\ #1}% for sorted index file only +\def\putwordSeeAlso{see also} + +% 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{}% + \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 + \indexnofonts + % The braces around the commands are recognized by texindex. + \def\lbracechar{{\indexlbrace}}% + \def\rbracechar{{\indexrbrace}}% + \let\{=\lbracechar + \let\}=\rbracechar + \def\@{{\indexatchar}}% + \def\atchar##1{\@}% + % + \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 + +% Write the entry in \toks0 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 + % + % For texindex which always views { and } as separators. + \def\{{\lbracechar{}}% + \def\}{\rbracechar{}}% + % + % 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: % @@ -5462,9 +5423,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. @@ -5476,11 +5442,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. @@ -5494,14 +5455,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, @@ -5511,8 +5468,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. @@ -5520,47 +5475,27 @@ 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{% + % NB this won't work if the index file starts with a group... + \uccode`\~=`\\ \uppercase{\if\noexpand~}\noexpand#1 + \message{skipping sorted index file}% + (Skipped sorted index file in obsolete format) \else - \edef\act{\gdef\noexpand\firsttoken{\getfirsttoken\nextline}}% - \act + \begindoublecolumns + \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. @@ -5569,12 +5504,18 @@ 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\@% + % % 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}}% @@ -5634,12 +5575,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 @@ -5672,35 +5607,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. % @@ -5766,55 +5697,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. @@ -5824,24 +5711,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, @@ -5851,60 +5729,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}% @@ -5930,7 +5769,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 % @@ -5943,17 +5784,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 } @@ -6001,7 +5840,7 @@ end % \output = {% % Split the last of the double-column material. - \savemarks + \savetopmark \balancecolumns }% \eject % call the \output just set @@ -6009,10 +5848,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 @@ -6036,13 +5874,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 @@ -6177,11 +6016,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 @@ -6526,27 +6363,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 @@ -6557,7 +6389,7 @@ end }% \else \toks0={#1}% - \xdef\lastchapterdefs{% + \xdef\currentchapterdefs{% \gdef\noexpand\thischaptername{\the\toks0}% \gdef\noexpand\thischapternum{\the\chapno}% % \noexpand\putwordChapter avoids expanding indigestible @@ -6577,18 +6409,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''. @@ -6677,10 +6509,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 @@ -6688,7 +6520,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 @@ -6701,7 +6533,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 @@ -6727,28 +6559,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. @@ -6838,13 +6670,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 } @@ -7207,11 +7034,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}} @@ -7226,7 +7049,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 @@ -7405,13 +7239,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 @@ -7573,7 +7403,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}% @@ -7636,9 +7466,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 }% } @@ -7783,6 +7616,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 @@ -7797,7 +7645,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}% } @@ -8085,36 +7932,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 @@ -8215,12 +8044,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 } @@ -8784,9 +8615,21 @@ 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} + +% Divert output to a box that is not output until the next @node command. +\def\ignorenode{\setbox\dummybox\vbox\bgroup\def\node{\egroup\node}} -\let\nwnode=\node \let\lastnode=\empty % Write a cross-reference definition for the current node. #1 is the @@ -8809,7 +8652,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. @@ -8831,7 +8674,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 @@ -9261,19 +9104,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... @@ -9291,14 +9121,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 @@ -9629,13 +9452,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 @@ -9758,7 +9581,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} % @@ -11246,21 +11069,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 @@ -11576,11 +11392,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. @@ -11598,10 +11412,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 @@ -11673,7 +11485,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. diff --git a/doc/misc/todo-mode.texi b/doc/misc/todo-mode.texi index 1e4ea856fc7..18e5a8fa3b1 100644 --- a/doc/misc/todo-mode.texi +++ b/doc/misc/todo-mode.texi @@ -9,7 +9,7 @@ @c %**end of header @copying -Copyright @copyright{} 2013-2018 Free Software Foundation, Inc. +Copyright @copyright{} 2013-2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index f68205519f3..ac5aa680d5e 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -13,7 +13,7 @@ @footnotestyle end @copying -Copyright @copyright{} 1999--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1999--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -86,7 +86,6 @@ Archive}. 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 @@ -379,32 +378,6 @@ $ 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}. Archive file names are supported since -December 2017. - -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. @ifset installchapter @@ -495,6 +468,19 @@ 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{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 @option{smb} @@ -562,6 +548,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 @@ -721,11 +719,17 @@ the host returned by the function @command{(system-name)}. See 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 @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 @option{sg} @@ -928,6 +932,30 @@ 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 @option{ftp} @cindex @option{ftp} method @@ -1048,6 +1076,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 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, 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 @@ -1374,7 +1444,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 @@ -1490,6 +1561,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 @@ -1668,6 +1807,16 @@ 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 @@ -1747,6 +1896,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}. @@ -1812,6 +1979,39 @@ 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, call @kbd{M-x tramp-cleanup-this-connection @key{RET}} or friends @@ -2609,11 +2809,16 @@ proxy @samp{bird@@bastion} to a remote file on @samp{you@@remotehost}: @kbd{C-x C-f @value{prefix}ssh@value{postfixhop}bird@@bastion|ssh@value{postfixhop}you@@remotehost@value{postfix}/path @key{RET}} @end example +Each involved method must be an inline method (@pxref{Inline methods}). + @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 @@ -2798,7 +3003,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 @@ -2851,6 +3056,14 @@ host. Example: @kbd{M-x auto-revert-tail-mode @key{RET}} runs similarly showing continuous output. +@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. + @subsection Running @code{eshell} on a remote host @cindex @code{eshell} @@ -2994,7 +3207,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 @@ -3004,13 +3218,15 @@ 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 @@ -3682,7 +3898,9 @@ Due to the remote shell saving tilde expansions triggered by @value{tramp} can suppress this behavior with the user option @code{tramp-histfile-override}. When set to @code{t}, environment variable @env{HISTFILE} is unset, and environment variables -@env{HISTFILESIZE} and @env{HISTSIZE} are set to 0. +@env{HISTFILESIZE} and @env{HISTSIZE} are set to 0. Don't use this +with @command{bash} 5.0.0. There is a bug in @command{bash} which +lets @command{bash} die. Alternatively, @code{tramp-histfile-override} could be a string. Environment variable @env{HISTFILE} is set to this file name then. Be @@ -4035,7 +4253,7 @@ export EDITOR=/path/to/emacsclient.sh @item -How to determine wheter a buffer is remote? +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}, diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index aac7243446f..5b1408a4974 100644 --- a/doc/misc/trampver.texi +++ b/doc/misc/trampver.texi @@ -2,12 +2,12 @@ @c texi/trampver.texi. Generated from trampver.texi.in by configure. @c This is part of the Emacs manual. -@c Copyright (C) 2003-2018 Free Software Foundation, Inc. +@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 tramp.el, @c and the bug report address is auto-frobbed from configure.ac. -@set trampver 2.4.1-pre +@set trampver 2.4.2-pre @set tramp-bug-report-address tramp-devel@@gnu.org @c Other flags from configuration. diff --git a/doc/misc/url.texi b/doc/misc/url.texi index eaeae603526..0cdfcac24e8 100644 --- a/doc/misc/url.texi +++ b/doc/misc/url.texi @@ -21,7 +21,7 @@ @copying This is the manual for the @code{url} Emacs Lisp library. -Copyright @copyright{} 1993--1999, 2002, 2004--2018 Free Software +Copyright @copyright{} 1993--1999, 2002, 2004--2019 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/vhdl-mode.texi b/doc/misc/vhdl-mode.texi index c0efdbf75f4..8af658682cd 100644 --- a/doc/misc/vhdl-mode.texi +++ b/doc/misc/vhdl-mode.texi @@ -10,7 +10,7 @@ @copying This file documents VHDL Mode, an Emacs mode for editing VHDL code. -Copyright @copyright{} 1995--2008, 2010, 2012, 2015--2018 Free Software +Copyright @copyright{} 1995--2008, 2010, 2012, 2015--2019 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/vip.texi b/doc/misc/vip.texi index 92aea388af3..47a3f349a16 100644 --- a/doc/misc/vip.texi +++ b/doc/misc/vip.texi @@ -4,7 +4,7 @@ @include docstyle.texi @copying -Copyright @copyright{} 1987, 2001--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1987, 2001--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/viper.texi b/doc/misc/viper.texi index e67734bc01c..922c91b3922 100644 --- a/doc/misc/viper.texi +++ b/doc/misc/viper.texi @@ -8,7 +8,7 @@ @include docstyle.texi @copying -Copyright @copyright{} 1995--1997, 2001--2018 Free Software Foundation, Inc. +Copyright @copyright{} 1995--1997, 2001--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/widget.texi b/doc/misc/widget.texi index bf21ac33899..6d94768644f 100644 --- a/doc/misc/widget.texi +++ b/doc/misc/widget.texi @@ -9,7 +9,7 @@ @c %**end of header @copying -Copyright @copyright{} 2000--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2000--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/wisent.texi b/doc/misc/wisent.texi index 12bb09c7b25..b404c2a82dc 100644 --- a/doc/misc/wisent.texi +++ b/doc/misc/wisent.texi @@ -24,7 +24,7 @@ @c %**end of header @copying -Copyright @copyright{} 1988--1993, 1995, 1998--2004, 2007, 2012--2018 +Copyright @copyright{} 1988--1993, 1995, 1998--2004, 2007, 2012--2019 Free Software Foundation, Inc. @c Since we are both GNU manuals, we do not need to ack each other here. diff --git a/doc/misc/woman.texi b/doc/misc/woman.texi index f8ddbd2aff6..9c04a145021 100644 --- a/doc/misc/woman.texi +++ b/doc/misc/woman.texi @@ -15,7 +15,7 @@ This file documents WoMan: A program to browse Unix manual pages ``W.O. (without) man''. -Copyright @copyright{} 2001--2018 Free Software Foundation, Inc. +Copyright @copyright{} 2001--2019 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document |