diff options
Diffstat (limited to 'doc')
85 files changed, 3499 insertions, 1590 deletions
diff --git a/doc/emacs/ChangeLog.1 b/doc/emacs/ChangeLog.1 index 439ef51acb8..5be61aee4fb 100644 --- a/doc/emacs/ChangeLog.1 +++ b/doc/emacs/ChangeLog.1 @@ -4398,7 +4398,7 @@ mail-header-separator. (Mail Headers): Put info about initialization and changing in one place at the start. Update FCC section for mbox Rmail. Clarify From - section, mention mail-setup-with-from. Clarify Reply-to section. + section, mention mail-setup-with-from. Clarify Reply-To section. Add Mail-followup-to and mail-mailing-lists. Clarify References section. (Mail Aliases): Update example, make less contentious. diff --git a/doc/emacs/Makefile.in b/doc/emacs/Makefile.in index fa451b1f927..01c6700197c 100644 --- a/doc/emacs/Makefile.in +++ b/doc/emacs/Makefile.in @@ -206,8 +206,8 @@ doc-emacsver: ## Temp files. mostlyclean: - rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \ - *.op *.ops *.pg *.pgs *.tp *.tps *.vr *.vrs + rm -f ./*.aux ./*.log ./*.toc ./*.cp ./*.cps ./*.fn ./*.fns ./*.ky ./*.kys \ + ./*.op ./*.ops ./*.pg ./*.pgs ./*.tp ./*.tps ./*.vr ./*.vrs ## Products not in the release tarfiles. clean: mostlyclean diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index 7ce62498b8e..78d07b8d39e 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -190,6 +190,9 @@ compilation buffer produce automatic source display. @item g Re-run the last command whose output is shown in the @file{*compilation*} buffer. +@item M-x next-error-select-buffer +Select a buffer to be used by next invocation of @code{next-error} and +@code{previous-error}. @end table @kindex M-g M-n @@ -202,16 +205,18 @@ Re-run the last command whose output is shown in the This command can be invoked from any buffer, not just a Compilation mode buffer. The first time you invoke it after a compilation, it visits the locus of the first error message. Each subsequent -@w{@kbd{C-x `}} visits the next error, in a similar fashion. If you +@w{@kbd{M-g M-n}} visits the next error, in a similar fashion. If you visit a specific error with @key{RET} or a mouse click in the -@file{*compilation*} buffer, subsequent @w{@kbd{C-x `}} commands -advance from there. When @w{@kbd{C-x `}} finds no more error messages -to visit, it signals an error. @w{@kbd{C-u C-x `}} starts again from +@file{*compilation*} buffer, subsequent @w{@kbd{M-g M-n}} commands +advance from there. When @w{@kbd{M-g M-n}} finds no more error messages +to visit, it signals an error. @w{@kbd{C-u M-g M-n}} starts again from the beginning of the compilation buffer, and visits the first locus. @kbd{M-g M-p} or @kbd{M-g p} (@code{previous-error}) iterates through errors in the opposite direction. +@vindex next-error-find-buffer-function +@findex next-error-select-buffer The @code{next-error} and @code{previous-error} commands don't just act on the errors or matches listed in @file{*compilation*} and @file{*grep*} buffers; they also know how to iterate through error or @@ -219,10 +224,15 @@ match lists produced by other commands, such as @kbd{M-x occur} (@pxref{Other Repeating Search}). If the current buffer contains error messages or matches, these commands will iterate through them; otherwise, Emacs looks for a buffer containing error messages or -matches amongst the windows of the selected frame, then for any buffer -that @code{next-error} or @code{previous-error} previously visited, -and finally all other buffers. Any buffer these commands iterate -through that is not currently displayed in a window will be displayed. +matches amongst the windows of the selected frame (if the variable +@code{next-error-find-buffer-function} is customized to the value +@code{next-error-buffer-on-selected-frame}), then for a buffer used +previously by @code{next-error} or @code{previous-error}, and finally +all other buffers. Any buffer these commands iterate through that is +not currently displayed in a window will be displayed. You can use +the @command{next-error-select-buffer} command to switch to +a different buffer to be used by the subsequent invocation of +@code{next-error}. @vindex compilation-skip-threshold By default, the @code{next-error} and @code{previous-error} commands @@ -394,8 +404,8 @@ grep -nH -e foo *.el | grep bar | grep toto @end example The output from @command{grep} goes in the @file{*grep*} buffer. You -can find the corresponding lines in the original files using @w{@kbd{C-x -`}}, @key{RET}, and so forth, just like compilation errors. +can find the corresponding lines in the original files using @w{@kbd{M-g +M-n}}, @key{RET}, and so forth, just like compilation errors. @xref{Compilation Mode}, for detailed description of commands and key bindings available in the @file{*grep*} buffer. @@ -449,6 +459,18 @@ the variable @code{grep-files-aliases}. @kbd{M-x rgrep}. The default value includes the data directories used by various version control systems. +@vindex grep-find-abbreviate +@findex grep-find-toggle-abbreviation + By default, the shell commands constructed for @code{lgrep}, +@code{rgrep}, and @code{zgrep} are abbreviated for display by +concealing the part that contains a long list of files and directories +to ignore. You can reveal the concealed part by clicking on the +button with ellipsis, which represents them. You can also +interactively toggle viewing the concealed part by typing @kbd{M-x +grep-find-toggle-abbreviation}. To disable this abbreviation of the +shell commands, customize the option @code{grep-find-abbreviate} to a +@code{nil} value. + @node Flymake @section Finding Syntax Errors On The Fly @cindex checking syntax diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi index c870e6dad9d..d51d97b48a2 100644 --- a/doc/emacs/cmdargs.texi +++ b/doc/emacs/cmdargs.texi @@ -528,12 +528,17 @@ This variable defaults to @file{~/.bash_history} if you use Bash, to otherwise. @item HOME @vindex HOME@r{, environment variable} -The location of your files in the directory tree; used for -expansion of file names starting with a tilde (@file{~}). On MS-DOS, -it defaults to the directory from which Emacs was started, with -@samp{/bin} removed from the end if it was present. On Windows, the -default value of @env{HOME} is the @file{Application Data} -subdirectory of the user profile directory (normally, this is +The location of your files in the directory tree; used for expansion +of file names starting with a tilde (@file{~}). If set, it should be +set to an absolute file name. (If set to a relative file name, Emacs +interprets it relative to the directory where Emacs was started, but +we don't recommend to use this feature.) If unset, @env{HOME} +normally defaults to the home directory of the user given by +@env{LOGNAME}, @env{USER} or your user ID, or to @file{/} if all else +fails. On MS-DOS, it defaults to the directory from which Emacs was +started, with @samp{/bin} removed from the end if it was present. On +Windows, the default value of @env{HOME} is the @file{Application +Data} subdirectory of the user profile directory (normally, this is @file{C:/Documents and Settings/@var{username}/Application Data}, where @var{username} is your user name), though for backwards compatibility @file{C:/} will be used instead if a @file{.emacs} file diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 4aaf58cc264..618692e479f 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -2209,6 +2209,7 @@ Manual}. * Terminal Init:: Each terminal type can have an init file. * Find Init:: How Emacs finds the init file. * Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file. +* Early Init File:: Another init file, which is read early on. @end menu @node Init Syntax @@ -2556,10 +2557,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). @@ -2609,3 +2609,33 @@ instance: @noindent Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}. + +@node Early Init File +@subsection The Early Init File +@cindex early init file + + Most customizations for Emacs should be put in the normal init file, +@file{.emacs} or @file{~/.emacs.d/init.el}. However, it is sometimes desirable +to have customizations that take effect during Emacs startup earlier than the +normal init file is processed. Such customizations can be put in the early +init file, @file{~/.emacs.d/early-init.el}. This file is loaded before the +package system and GUI is initialized, so in it you can customize variables +that affect frame appearance as well as the package initialization process, +such as @code{package-enable-at-startup}, @code{package-load-list}, and +@code{package-user-dir}. Note that variables like @code{package-archives} +which only affect the installation of new packages, and not the process of +making already-installed packages available, may be customized in the regular +init file. @xref{Package Installation}. + + We do not recommend that you move into @file{early-init.el} +customizations that can be left in the normal init files. That is +because the early init file is read before the GUI is initialized, so +customizations related to GUI features will not work reliably in +@file{early-init.el}. By contrast, the normal init files are read +after the GUI is initialized. If you must have customizations in the +early init file that rely on GUI features, make them run off hooks +provided by the Emacs startup, such as @code{window-setup-hook} or +@code{tty-setup-hook}. @xref{Hooks}. + + For more information on the early init file, @pxref{Init File,,, +elisp, The Emacs Lisp Reference Manual}. diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi index cf9665ac5b4..9f454ea2ad6 100644 --- a/doc/emacs/dired.texi +++ b/doc/emacs/dired.texi @@ -663,6 +663,14 @@ Copy the specified files (@code{dired-do-copy}). The argument @var{new} is the directory to copy into, or (if copying a single file) the new name. This is like the shell command @code{cp}. +@vindex dired-create-destination-dirs +The option @code{dired-create-destination-dirs} controls whether Dired +should create non-existent directories in the destination while +copying/renaming files. The default value @code{nil} means Dired +never creates such missing directories; the value @code{always}, +means Dired automatically creates them; the value @code{ask} +means Dired asks you for confirmation before creating them. + @vindex dired-copy-preserve-time If @code{dired-copy-preserve-time} is non-@code{nil}, then copying with this command preserves the modification time of the old file in @@ -694,6 +702,9 @@ single file, the argument @var{new} is the new name of the file. If you rename several files, the argument @var{new} is the directory into which to move the files (this is like the shell command @command{mv}). +The option @code{dired-create-destination-dirs} controls whether Dired +should create non-existent directories in @var{new}. + Dired automatically changes the visited file name of buffers associated with renamed files so that they refer to the new names. @@ -1463,6 +1474,11 @@ rotation is lossless, and uses an external utility called directory's name, and creates that directory. It signals an error if the directory already exists. +@findex dired-create-empty-file + The command (@code{dired-create-empty-file}) reads a +file name, and creates that file. It signals an error if +the file already exists. + @cindex searching multiple files via Dired @kindex M-s a C-s @r{(Dired)} @kindex M-s a M-C-s @r{(Dired)} diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index 9cf6baa7e91..f464a3a59f0 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -974,8 +974,10 @@ the buffer is loaded. For example, to highlight all occurrences of the word ``whim'' using the default face (a yellow background), type @kbd{M-s h r whim @key{RET} @key{RET}}. Any face can be used for highlighting, Hi Lock provides several of its own and these are -pre-loaded into a list of default values. While being prompted -for a face use @kbd{M-n} and @kbd{M-p} to cycle through them. +pre-loaded into a list of default values. While being prompted for a +face use @kbd{M-n} and @kbd{M-p} to cycle through them. A prefix +numeric argument limits the highlighting to the corresponding +subexpression. @vindex hi-lock-auto-select-face Setting the option @code{hi-lock-auto-select-face} to a non-@code{nil} diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index d501db71914..54c20251ef7 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -1163,6 +1163,7 @@ The Emacs Initialization File * Terminal Init:: Each terminal type can have an init file. * Find Init:: How Emacs finds the init file. * Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file. +* Early Init File:: Another init file, which is read early on. Dealing with Emacs Trouble diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index cd64fb109ea..d12d1edae72 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -206,7 +206,10 @@ saved it. If the file has changed, Emacs offers to reread it. If you try to visit a file larger than @code{large-file-warning-threshold} (the default is 10000000, which is about 10 megabytes), Emacs asks you for confirmation first. You can -answer @kbd{y} to proceed with visiting the file. Note, however, that +answer @kbd{y} to proceed with visiting the file or @kbd{l} to visit +the file literally (see below). Visiting large files literally speeds +up navigation and editing of such files, because various +potentially-expensive features are turned off. Note, however, that Emacs cannot visit files that are larger than the maximum Emacs buffer size, which is limited by the amount of memory Emacs can allocate and by the integers that Emacs can represent (@pxref{Buffers}). If you @@ -400,11 +403,14 @@ possible responses are analogous to those of @code{query-replace}: @table @kbd @item y +@item @key{SPC} Save this buffer and ask about the rest of the buffers. @item n +@item @key{DEL} Don't save this buffer, but ask about the rest of the buffers. @item ! Save this buffer and all the rest with no more questions. +@item q @c following generates acceptable underfull hbox @item @key{RET} Terminate @code{save-some-buffers} without any more saving. @@ -1016,13 +1022,16 @@ separate file, without altering the file you actually use. This is called @dfn{auto-saving}. It prevents you from losing more than a limited amount of work if the system crashes. +@vindex auto-save-no-message When Emacs determines that it is time for auto-saving, it considers each buffer, and each is auto-saved if auto-saving is enabled for it -and it has been changed since the last time it was auto-saved. The -message @samp{Auto-saving...} is displayed in the echo area during -auto-saving, if any files are actually auto-saved. Errors occurring -during auto-saving are caught so that they do not interfere with the -execution of commands you have been typing. +and it has been changed since the last time it was auto-saved. When +the @code{auto-save-no-message} variable is set to @code{nil} (the +default), the message @samp{Auto-saving...} is displayed in the echo +area during auto-saving, if any files are actually auto-saved; to +disable these messages, customize the variable to a non-@code{nil} +value. Errors occurring during auto-saving are caught so that they do +not interfere with the execution of commands you have been typing. @menu * Files: Auto Save Files. The file where auto-saved changes are @@ -1309,17 +1318,8 @@ default), and @code{list-directory-verbose-switches} is a string giving the switches to use in a verbose listing (@code{"-l"} by default). -@vindex directory-free-space-program -@vindex directory-free-space-args In verbose directory listings, Emacs adds information about the -amount of free space on the disk that contains the directory. You can -customize how this is done for local filesystems via the variables -@code{directory-free-space-program} and -@code{directory-free-space-args}: the former specifies what program to -run (default: @command{df}), the latter which arguments to pass to -that program (default is system-dependent). (On MS-Windows and -MS-DOS, these two variables are ignored, and an internal Emacs -implementation of the same functionality is used instead.) +amount of free space on the disk that contains the directory. The command @kbd{M-x delete-directory} prompts for a directory's name using the minibuffer, and deletes the directory if it is empty. If @@ -1448,7 +1448,7 @@ automatic line number correction, change the variable @code{diff-update-on-the-fly} to @code{nil}. Diff mode arranges for hunks to be treated as compiler error -messages by @kbd{C-x `} and other commands that handle error messages +messages by @kbd{M-g M-n} and other commands that handle error messages (@pxref{Compilation Mode}). Thus, you can use the compilation-mode commands to visit the corresponding source locations. @@ -1530,6 +1530,10 @@ default jumps to the ``old'' file, and the meaning of the prefix argument is reversed. If the prefix argument is a number greater than 8 (e.g., if you type @kbd{C-u C-u C-c C-c}), then this command also sets @code{diff-jump-to-old-file} for the next invocation. +If the source file is under version control (@pxref{Version Control}), +this jumps to the work file by default. With a prefix argument, jump +to the ``old'' revision of the file (@pxref{Old Revisions}), when +point is on the old line, or otherwise jump to the ``new'' revision. @item C-c C-e @findex diff-ediff-patch @@ -1613,6 +1617,10 @@ displayed in the echo area). With a prefix argument, it tries to modify the original (``old'') source files rather than the patched (``new'') source files. +@vindex diff-font-lock-syntax + If non-@code{nil}, fragments of source in hunks are highlighted +according to the appropriate major mode. + @node Copying and Naming @section Copying, Naming and Renaming Files diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi index bb1b4c87137..fc610583c87 100644 --- a/doc/emacs/fixit.texi +++ b/doc/emacs/fixit.texi @@ -149,6 +149,12 @@ Transpose two words (@code{transpose-words}). Transpose two balanced expressions (@code{transpose-sexps}). @item C-x C-t Transpose two lines (@code{transpose-lines}). +@item M-x transpose-sentences +Transpose two sentences (@code{transpose-sentences}). +@item M-x transpose-paragraphs +Transpose two paragraphs (@code{transpose-paragraphs}). +@item M-x transpose-regions +Transpose two regions. @end table @kindex C-t @@ -183,10 +189,14 @@ punctuation characters between the words do not move. For example, @w{@samp{BAR FOO,}}. When point is at the end of the line, it will transpose the word before point with the first word on the next line. +@findex transpose-sentences +@findex transpose-paragraphs @kbd{C-M-t} (@code{transpose-sexps}) is a similar command for transposing two expressions (@pxref{Expressions}), and @kbd{C-x C-t} -(@code{transpose-lines}) exchanges lines. They work like @kbd{M-t} -except as regards the units of text they transpose. +(@code{transpose-lines}) exchanges lines. @kbd{M-x +transpose-sentences} and @kbd{M-x transpose-paragraphs} transpose +sentences and paragraphs, respectively. These commands work like +@kbd{M-t} except as regards the units of text they transpose. A numeric argument to a transpose command serves as a repeat count: it tells the transpose command to move the character (or word or @@ -204,6 +214,15 @@ otherwise a command with a repeat count of zero would do nothing): to transpose the character (or word or expression or line) ending after point with the one ending after the mark. +@findex transpose-regions + @kbd{M-x transpose-regions} transposes the text between point and +mark with the text between the last two marks pushed to the mark ring +(@pxref{Setting Mark}). With a numeric prefix argument, it transposes +the text between point and mark with the text between two successive +marks that many entries back in the mark ring. This command is best +used for transposing multiple characters (or words or sentences or +paragraphs) in one go. + @node Fixing Case @section Case Conversion diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index 9ffea416827..4851659b8b7 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -523,13 +523,17 @@ currently in use. @xref{Coding Systems}. @section Other Help Commands @kindex C-h i +@kindex C-h 4 i @findex info +@findex info-other-window @cindex Info @cindex manuals, included @kbd{C-h i} (@code{info}) runs the Info program, which browses -structured documentation files. The entire Emacs manual is available -within Info, along with many other manuals for the GNU system. Type -@kbd{h} after entering Info to run a tutorial on using Info. +structured documentation files. @kbd{C-h 4 i} +(@code{info-other-window}) does the same, but shows the Info buffer in +another window. The entire Emacs manual is available within Info, +along with many other manuals for the GNU system. Type @kbd{h} after +entering Info to run a tutorial on using Info. @cindex find Info manual by its file name With a numeric argument @var{n}, @kbd{C-h i} selects the Info buffer diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index cddffd6f2a5..d97cfd355cc 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -831,6 +831,14 @@ working tree containing the current VC fileset). If you invoke this command from a Dired buffer, it applies to the working tree containing the directory. +@findex vc-root-version-diff +@kindex C-u C-x v D + To compare two arbitrary revisions of the whole trees, call +@code{vc-root-diff} with a prefix argument: @kbd{C-u C-x v D}. This +prompts for two revision IDs (@pxref{VCS Concepts}), and displays a +diff between those versions of the entire version-controlled directory +trees (RCS, SCCS, CVS, and SRC do not support this feature). + @vindex vc-diff-switches You can customize the @command{diff} options that @kbd{C-x v =} and @kbd{C-x v D} use for generating diffs. The options used are taken @@ -963,6 +971,7 @@ and the maximum number of revisions to display. Directory Mode}) or a Dired buffer (@pxref{Dired}), it applies to the file listed on the current line. +@kindex C-x v L @findex vc-print-root-log @findex log-view-toggle-entry-display @kbd{C-x v L} (@code{vc-print-root-log}) displays a @@ -1640,21 +1649,35 @@ entry is considered a page. This facilitates editing the entries. @kbd{C-j} and auto-fill indent each new line like the previous line; this is convenient for entering the contents of an entry. -You can use the @code{next-error} command (by default bound to -@kbd{C-x `}) to move between entries in the Change Log, when Change -Log mode is on. You will jump to the actual site in the file that was -changed, not just to the next Change Log entry. You can also use -@code{previous-error} to move back in the same list. +@findex change-log-goto-source + You can use the command @code{change-log-goto-source} (by default +bound to @kbd{C-c C-c}) to go to the source location of the change log +entry near point, when Change Log mode is on. Then subsequent +invocations of the @code{next-error} command (by default bound to +@kbd{M-g M-n} and @kbd{C-x `}) will move between entries in the change +log. You will jump to the actual site in the file that was changed, +not just to the next change log entry. You can also use +@code{previous-error} to move back through the change log entries. @findex change-log-merge You can use the command @kbd{M-x change-log-merge} to merge other log files into a buffer in Change Log Mode, preserving the date ordering of entries. +@vindex add-log-dont-create-changelog-file Version control systems are another way to keep track of changes in -your program and keep a change log. In the VC log buffer, typing -@kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant -Change Log entry, if one exists. @xref{Log Buffer}. +your program and keep a change log. Many projects that use a VCS don't +keep a separate versioned change log file nowadays, so you may wish to +avoid having such a file in the repository. If the value of +@code{add-log-dont-create-changelog-file} is non-@code{nil}, commands +like @kbd{C-x 4 a} (@code{add-change-log-entry-other-window}) will +record changes in a suitably named temporary buffer instead of a file, +if such a file does not already exist. + +Whether you have a change log file or use a temporary buffer for +change logs, you can type @kbd{C-c C-a} +(@code{log-edit-insert-changelog}) in the VC Log buffer to insert the +relevant change log entries, if they exist. @xref{Log Buffer}. @node Format of ChangeLog @subsection Format of ChangeLog @@ -1809,6 +1832,8 @@ Find definitions of identifier, but display it in another window @item C-x 5 .@: @key{RET} Find definition of identifier, and display it in a new frame (@code{xref-find-definitions-other-frame}). +@item M-x xref-find-definitions-at-mouse +Find definition of identifier at mouse click. @item M-, Go back to where you previously invoked @kbd{M-.} and friends (@code{xref-pop-marker-stack}). @@ -1849,6 +1874,11 @@ former is @w{@kbd{C-x 4 .}} (@code{xref-find-definitions-other-window}), and the latter is @w{@kbd{C-x 5 .}} (@code{xref-find-definitions-other-frame}). + The command @code{xref-find-definitions-at-mouse} works like +@code{xref-find-definitions}, but it looks for the identifier name at +or around the place of a mouse event. This command is intended to be +bound to a mouse event, such as @kbd{C-M-mouse-1}, for example. + @findex xref-find-apropos @kindex C-M-. The command @kbd{C-M-.} (@code{xref-find-apropos}) finds the @@ -1960,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 tags-loop-continue +@item M-x multifile-continue Restart one of the last 2 commands above, from the current location of point. @end table @@ -1996,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 tags-loop-continue +@findex multifile-continue Having found one match with @code{tags-search}, you probably want to -find all the rest. @kbd{M-x tags-loop-continue} resumes the +find all the rest. @kbd{M-x multifile-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. @@ -2021,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 tags-loop-continue}; this +replace subsequently by typing @kbd{M-x multifile-continue}; this command resumes the last tags search or replace command that you did. For instance, to skip the rest of the current file, you can type -@w{@kbd{M-> M-x tags-loop-continue}}. +@w{@kbd{M-> M-x multifile-continue}}. Note that the commands described above carry out much broader searches than the @code{xref-find-definitions} family. The @@ -2056,7 +2086,7 @@ Display a list of all known identifiers matching @var{regexp}. Display a list of the identifiers defined in the program file @var{file}. -@item M-x next-file +@item M-x tags-next-file Visit files recorded in the selected tags table. @end table @@ -2095,8 +2125,8 @@ variable @code{tags-apropos-additional-actions}; see its documentation for details. @end ignore -@findex next-file - @kbd{M-x next-file} visits files covered by the selected tags table. +@findex tags-next-file + @kbd{M-x tags-next-file} visits files covered by the selected tags table. The first time it is called, it visits the first file covered by the table. Each subsequent call visits the next covered file, unless a prefix argument is supplied, in which case it returns to the first diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi index d17ef2dad63..820d3baad13 100644 --- a/doc/emacs/mini.texi +++ b/doc/emacs/mini.texi @@ -362,14 +362,26 @@ While in the completion list buffer, this chooses the completion at point (@code{choose-completion}). @findex next-completion +@item @key{TAB} @item @key{RIGHT} -While in the completion list buffer, this moves point to the following -completion alternative (@code{next-completion}). +While in the completion list buffer, these keys move point to the +following completion alternative (@code{next-completion}). @findex previous-completion +@item @key{S-TAB} @item @key{LEFT} -While in the completion list buffer, this moves point to the previous -completion alternative (@code{previous-completion}). +While in the completion list buffer, these keys move point to the +previous completion alternative (@code{previous-completion}). + +@findex quit-window +@item @kbd{q} +While in the completion list buffer, this quits the window showing it +and selects the window showing the minibuffer (@code{quit-window}). + +@findex kill-current-buffer +@item @kbd{z} +While in the completion list buffer, kill it and delete the window +showing it (@code{kill-current-buffer}). @end table @node Completion Exit diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index 41a540a7610..13e18f8a71d 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -314,7 +314,28 @@ You can decide to register a permanent security exception for an unverified connection, a temporary exception, or refuse the connection entirely. -Below is a list of the checks done on the @code{medium} level. +@vindex network-security-protocol-checks +In addition to the basic certificate correctness checks, several +@acronym{TLS} algorithm checks are available. Some encryption +technologies that were previously thought to be secure have shown +themselves to be fragile, so Emacs (by default) warns you about some +of these problems. + +The protocol network checks is controlled via the +@code{network-security-protocol-checks} variable. + +It's an alist where the first element of each association is the name +of the check, the second element is the security level where the check +should be used, and the optional third element is a parameter supplied +to the check. + +An element like @code{(rc4 medium)} will result in the function +@code{nsm-protocol-check--rc4} being called like thus: +@w{@code{(nsm-protocol-check--rc4 host port status optional-parameter)}}. +The function should return non-@code{nil} if the connection should +proceed and @code{nil} otherwise. + +Below is a list of the checks done on the default @code{medium} level. @table @asis @@ -352,12 +373,44 @@ over these connections. Similarly, if you're sending email via connection to be encrypted. If the connection isn't encrypted, @acronym{NSM} will warn you. +@item Diffie-Hellman low prime bits +When doing the public key exchange, the number of prime bits should be +high enough to ensure that the channel can't be eavesdropped on by third +parties. If this number is too low, Emacs will warn you. (This is the +@code{diffie-hellman-prime-bits} check in +@code{network-security-protocol-checks}). + +@item @acronym{RC4} stream cipher +The @acronym{RC4} stream cipher is believed to be of low quality and +may allow eavesdropping by third parties. (This is the @code{rc4} +check in @code{network-security-protocol-checks}). + +@item @acronym{SHA1} in the host certificate or in intermediate certificates +It is believed that if an intermediate certificate uses the +@acronym{SHA1} hashing algorithm, then third parties can issue +certificates pretending to be that issuing instance. These +connections are therefore vulnerable to man-in-the-middle attacks. +(These are the @code{signature-sha1} and @code{intermediate-sha1} +checks in @code{network-security-protocol-checks}). + +@item @acronym{SSL1}, @acronym{SSL2} and @acronym{SSL3} +The protocols older than @acronym{TLS1.0} are believed to be +vulnerable to a variety of attacks, and you may want to avoid using +these if what you're doing requires higher security. (This is the +@code{ssl} check in @code{network-security-protocol-checks}). + @end table If @code{network-security-level} is @code{high}, the following checks will be made, in addition to the above: @table @asis +@item @acronym{3DES} cipher +The @acronym{3DES} stream cipher provides at most 112 bits of +effective security, which is considered to be towards the low end. +(This is the @code{3des} check in +@code{network-security-protocol-checks}). + @item a validated certificate changes the public key Servers change their keys occasionally, and that is normally nothing to be concerned about. However, if you are worried that your network @@ -365,19 +418,6 @@ connections are being hijacked by agencies who have access to pliable Certificate Authorities which issue new certificates for third-party services, you may want to keep track of these changes. -@item Diffie-Hellman low prime bits -When doing the public key exchange, the number of prime bits -should be high to ensure that the channel can't be eavesdropped on by -third parties. If this number is too low, you will be warned. - -@item @acronym{RC4} stream cipher -The @acronym{RC4} stream cipher is believed to be of low quality and -may allow eavesdropping by third parties. - -@item @acronym{SSL1}, @acronym{SSL2} and @acronym{SSL3} -The protocols older than @acronym{TLS1.0} are believed to be -vulnerable to a variety of attacks, and you may want to avoid using -these if what you're doing requires higher security. @end table Finally, if @code{network-security-level} is @code{paranoid}, you will @@ -402,6 +442,7 @@ This means that one can't casually read the settings file to see what servers the user has connected to. If this variable is @code{t}, @acronym{NSM} will also save host names in the @code{nsm-settings-file}. + @end table @@ -985,8 +1026,8 @@ Move backward across one shell command, but not beyond the current line Ask the shell for its working directory, and update the Shell buffer's default directory. @xref{Directory Tracking}. -@item M-x send-invisible @key{RET} @var{text} @key{RET} -@findex send-invisible +@item M-x comint-send-invisible @key{RET} @var{text} @key{RET} +@findex comint-send-invisible Send @var{text} as input to the shell, after reading it without echoing. This is useful when a shell command runs a program that asks for a password. @@ -1133,7 +1174,7 @@ Fetch the next subsequent command from the history @item C-c . @kindex C-c . @r{(Shell mode)} -@findex comint-input-previous-argument +@findex comint-insert-previous-argument Fetch one argument from an old shell command (@code{comint-input-previous-argument}). @@ -1180,14 +1221,20 @@ you just repeated. Then type @key{RET} to reexecute this command. You can reexecute several successive commands by typing @kbd{C-c C-x @key{RET}} over and over. - The command @kbd{C-c .}@: (@code{comint-input-previous-argument}) + The command @kbd{C-c .}@: (@code{comint-insert-previous-argument}) copies an individual argument from a previous command, like -@kbd{@key{ESC} .} in Bash. The simplest use copies the last argument from the -previous shell command. With a prefix argument @var{n}, it copies the -@var{n}th argument instead. Repeating @kbd{C-c .} copies from an -earlier shell command instead, always using the same value of @var{n} -(don't give a prefix argument when you repeat the @kbd{C-c .} -command). +@kbd{@key{ESC} .}@: in Bash and @command{zsh}. The simplest use +copies the last argument from the previous shell command. With a +prefix argument @var{n}, it copies the @var{n}th argument instead. +Repeating @kbd{C-c .} copies from an earlier shell commands, always +using the same value of @var{n} (don't give a prefix argument when +you repeat the @kbd{C-c .} command). + +@vindex comint-insert-previous-argument-from-end + If you set @code{comint-insert-previous-argument-from-end} to a +non-@code{nil} value, @kbd{C-c .}@: will instead copy the @var{n}th +argument counting from the last one; this emulates @kbd{@key{ESC} .}@: +in @command{zsh}. These commands get the text of previous shell commands from a special history list, not from the shell buffer itself. Thus, editing the shell @@ -1919,6 +1966,10 @@ 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.) +Alternatively, you can set the @env{EMACS_SOCKET_NAME} environment +variable to point to the server socket. (The command-line option +overrides the environment variable.) + @item -t @itemx --tty @itemx -nw @@ -2565,7 +2616,7 @@ e.g., the daemon cannot use GUI features, so parameters such as frame position, size, and decorations cannot be restored. For that reason, you may wish to delay restoring the desktop in daemon mode until the first client connects, by calling @code{desktop-read} in a hook -function that you add to @code{after-make-frame-functions} +function that you add to @code{server-after-make-frame-hook} (@pxref{Creating Frames,,, elisp, The Emacs Lisp Reference Manual}). @node Recursive Edit diff --git a/doc/emacs/msdos.texi b/doc/emacs/msdos.texi index fb876340b41..9fc4b6262fb 100644 --- a/doc/emacs/msdos.texi +++ b/doc/emacs/msdos.texi @@ -808,6 +808,13 @@ communications with subprocesses to programs that exhibit unusual behavior with respect to buffering pipe I/O. @ifnottex +@vindex w32-pipe-read-delay + If you need to invoke MS-DOS programs as Emacs subprocesses, you may +see low rate of reading data from such programs. Setting the variable +@code{w32-pipe-read-delay} to a non-zero value may improve throughput +in these cases; we suggest the value of 50 for such situations. The +default is zero. + @findex w32-shell-execute The function @code{w32-shell-execute} can be useful for writing customized commands that run MS-Windows applications registered to diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi index 99e04740d3c..26e64243301 100644 --- a/doc/emacs/package.texi +++ b/doc/emacs/package.texi @@ -241,57 +241,53 @@ lower-priority archives will not be shown in the menu, if the same package is available from a higher-priority archive. (This is controlled by the value of @code{package-menu-hide-low-priority}.) - Once a package is downloaded and installed, it is @dfn{loaded} into -the current Emacs session. Loading a package is not quite the same as -loading a Lisp library (@pxref{Lisp Libraries}); loading a package -adds its directory to @code{load-path} and loads its autoloads. The -effect of a package's autoloads varies from package to package. Most -packages just make some new commands available, while others have more + Once a package is downloaded and installed, it is made available to +the current Emacs session. Making a package available adds its +directory to @code{load-path} and loads its autoloads. The effect of +a package's autoloads varies from package to package. Most packages +just make some new commands available, while others have more wide-ranging effects on the Emacs session. For such information, consult the package's help buffer. - By default, Emacs also automatically loads all installed packages in -subsequent Emacs sessions. This happens at startup, after processing -the init file (@pxref{Init File}). As an exception, Emacs does not -load packages at startup if invoked with the @samp{-q} or + After a package is installed, it is automatically made available by +Emacs in all subsequent sessions. This happens at startup, before +processing the init file but after processing the early init file +(@pxref{Early Init File}). As an exception, Emacs does not make +packages available at startup if invoked with the @samp{-q} or @samp{--no-init-file} options (@pxref{Initial Options}). @vindex package-enable-at-startup - To disable automatic package loading, change the variable -@code{package-enable-at-startup} to @code{nil}. - -@findex package-initialize - The reason automatic package loading occurs after loading the init -file is that user options only receive their customized values after -loading the init file, including user options which affect the -packaging system. In some circumstances, you may want to load -packages explicitly in your init file (usually because some other code -in your init file depends on a package). In that case, your init file -should call the function @code{package-initialize}. It is up to you -to ensure that relevant user options, such as @code{package-load-list} -(see below), are set up prior to the @code{package-initialize} call. -This will automatically set @code{package-enable-at-startup} to @code{nil}, to -avoid loading the packages again after processing the init file. -Alternatively, you may choose to completely inhibit package loading at -startup, and invoke the command @kbd{M-x package-initialize} to load -your packages manually. + To keep Emacs from automatically making packages available at +startup, change the variable @code{package-enable-at-startup} to +@code{nil}. You must do this in the early init file, as the variable +is read before loading the regular init file. Currently this variable +cannot be set via Customize. + +@findex package-activate-all + If you have set @code{package-enable-at-startup} to @code{nil}, you +can still make packages available either during or after startup. To +make installed packages available during startup, call the function +@code{package-activate-all} in your init file. To make installed +packages available after startup, invoke the command @kbd{M-: +(package-activate-all) RET}. @vindex package-load-list - For finer control over package loading, you can use the variable -@code{package-load-list}. Its value should be a list. A list element -of the form @code{(@var{name} @var{version})} tells Emacs to load -version @var{version} of the package named @var{name}. Here, -@var{version} should be a version string (corresponding to a specific -version of the package), or @code{t} (which means to load any -installed version), or @code{nil} (which means no version; this -disables the package, preventing it from being loaded). A list -element can also be the symbol @code{all}, which means to load the -latest installed version of any package not named by the other list -elements. The default value is just @code{'(all)}. - - For example, if you set @code{package-load-list} to @code{'((muse -"3.20") all)}, then Emacs only loads version 3.20 of the @samp{muse} -package, plus any installed version of packages other than + For finer control over which packages are made available at startup, +you can use the variable @code{package-load-list}. Its value should +be a list. A list element of the form @w{@code{(@var{name} +@var{version})}} tells Emacs to make available version @var{version} of +the package named @var{name}. Here, @var{version} should be a version +string (corresponding to a specific version of the package), or +@code{t} (which means to make available any installed version), or +@code{nil} (which means no version; this disables the package, +preventing it from being made available). A list element can also be +the symbol @code{all}, which means to make available the latest +installed version of any package not named by the other list elements. +The default value is just @code{'(all)}. + + For example, if you set @code{package-load-list} to @w{@code{'((muse +"3.20") all)}}, then Emacs only makes available version 3.20 of the +@samp{muse} package, plus any installed version of packages other than @samp{muse}. Any other version of @samp{muse} that happens to be installed will be ignored. The @samp{muse} package will be listed in the package menu with the @samp{held} status. diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index 9d712eb66cc..c1ad5b57023 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -156,56 +156,22 @@ Emacs we use it for all languages. @cindex open-parenthesis in leftmost column @cindex ( in leftmost column - Many programming-language modes assume by default that any opening -delimiter found at the left margin is the start of a top-level -definition, or defun. Therefore, @strong{don't put an opening -delimiter at the left margin unless it should have that significance}. -For instance, never put an open-parenthesis at the left margin in a -Lisp file unless it is the start of a top-level list. - - The convention speeds up many Emacs operations, which would -otherwise have to scan back to the beginning of the buffer to analyze -the syntax of the code. - - If you don't follow this convention, not only will you have trouble -when you explicitly use the commands for motion by defuns; other -features that use them will also give you trouble. This includes the -indentation commands (@pxref{Program Indent}) and Font Lock mode -(@pxref{Font Lock}). - - The most likely problem case is when you want an opening delimiter -at the start of a line inside a string. To avoid trouble, put an -escape character (@samp{\}, in C and Emacs Lisp, @samp{/} in some -other Lisp dialects) before the opening delimiter. This will not -affect the contents of the string, but will prevent that opening -delimiter from starting a defun. Here's an example: - -@example - (insert "Foo: -\(bar) -") -@end example - - To help you catch violations of this convention, Font Lock mode -highlights confusing opening delimiters (those that ought to be -quoted) in bold red. + Many programming-language modes have traditionally assumed that any +opening parenthesis or brace found at the left margin is the start of +a top-level definition, or defun. So, by default, commands which seek +the beginning of a defun accept such a delimiter as signifying that +position. @vindex open-paren-in-column-0-is-defun-start - If you need to override this convention, you can do so by setting -the variable @code{open-paren-in-column-0-is-defun-start}. -If this user option is set to @code{t} (the default), opening -parentheses or braces at column zero always start defuns. When it is + If you want to override this convention, you can do so by setting +the user option @code{open-paren-in-column-0-is-defun-start} to +@code{nil}. If this option is set to @code{t} (the default), commands +seeking the start of a defun will stop at opening parentheses or +braces at column zero which aren't in a comment or string. When it is @code{nil}, defuns are found by searching for parens or braces at the -outermost level. - - Usually, you should leave this option at its default value of -@code{t}. If your buffer contains parentheses or braces in column -zero which don't start defuns, and it is somehow impractical to remove -these parentheses or braces, it might be helpful to set the option to -@code{nil}. Be aware that this might make scrolling and display in -large buffers quite sluggish. Furthermore, the parentheses and braces -must be correctly matched throughout the buffer for it to work -properly. +outermost level. Since low-level Emacs routines no longer depend on +this convention, you usually won't need to change +@code{open-paren-in-column-0-is-defun-start} from its default. @node Moving by Defuns @subsection Moving by Defuns diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi index b9d0afe42ee..1881b49627e 100644 --- a/doc/emacs/regs.texi +++ b/doc/emacs/regs.texi @@ -80,7 +80,9 @@ information until you store something else in it. @kindex C-x r j @findex jump-to-register The command @kbd{C-x r j @var{r}} switches to the buffer recorded in -register @var{r}, and moves point to the recorded position. The +register @var{r}, pushes a mark, and moves point to the recorded +position. (The mark is not pushed if point was already at the +recorded position, or in successive calls to the command.) The contents of the register are not changed, so you can jump to the saved position any number of times. diff --git a/doc/emacs/rmail.texi b/doc/emacs/rmail.texi index 94e1e63d44e..4901ca9709e 100644 --- a/doc/emacs/rmail.texi +++ b/doc/emacs/rmail.texi @@ -529,13 +529,18 @@ file name from the message @samp{Subject} header. @kindex C-o @r{(Rmail)} @findex rmail-output-as-seen The commands @kbd{o} and @kbd{C-o} copy the current message into a -specified file, adding it at the end. The two commands differ mainly -in how much to copy: @kbd{o} copies the full message headers, even if -they are not all visible, while @kbd{C-o} copies exactly the headers -currently displayed and no more. @xref{Rmail Display}. In addition, -@kbd{o} converts the message to Babyl format (used by Rmail in Emacs -version 22 and before) if the file is in Babyl format; @kbd{C-o} -cannot output to Babyl files at all. +specified file, adding it at the end. A positive prefix argument +serves as a repeat count: that many consecutive messages will be +copied to the specified file, starting with the current one and +ignoring deleted messages. + +The two commands differ mainly in how much to copy: @kbd{o} copies the +full message headers, even if they are not all visible, while +@kbd{C-o} copies exactly the headers currently displayed and no more. +@xref{Rmail Display}. In addition, @kbd{o} converts the message to +Babyl format (used by Rmail in Emacs version 22 and before) if the +file is in Babyl format; @kbd{C-o} cannot output to Babyl files at +all. @c FIXME remove BABYL mention in some future version? If the output file is currently visited in an Emacs buffer, the @@ -565,17 +570,29 @@ second says which files in that directory to offer (all those that match the regular expression). If no files match, you cannot select this menu item. -@vindex rmail-delete-after-output Copying a message with @kbd{o} or @kbd{C-o} gives the original copy of the message the @samp{filed} attribute, so that @samp{filed} appears in the mode line when such a message is current. +@vindex rmail-delete-after-output If you like to keep just a single copy of every mail message, set the variable @code{rmail-delete-after-output} to @code{t}; then the @kbd{o}, @kbd{C-o} and @kbd{w} commands delete the original message after copying it. (You can undelete it afterward if you wish, see @ref{Rmail Deletion}.) +@vindex rmail-output-reset-deleted-flag + By default, @kbd{o} will leave the deleted status of a message it +outputs as it was on the original message; thus, a message deleted +before it was output will appear as deleted in the output file. +Setting the variable @code{rmail-output-reset-deleted-flag} to a +non-@code{nil} value countermands that: the copy of the message will +have its deleted status reset, so the message will appear as undeleted +in the output file. In addition, when this variable is +non-@code{nil}, specifying a positive argument to @kbd{o} will not +ignore deleted messages when looking for consecutive messages to +output. + @vindex rmail-output-file-alist The variable @code{rmail-output-file-alist} lets you specify intelligent defaults for the output file, based on the contents of the @@ -753,7 +770,7 @@ Try sending a bounced message a second time (@code{rmail-retry-failure}). to the message you are reading. To do this, type @kbd{r} (@code{rmail-reply}). This displays a mail composition buffer in another window, much like @kbd{C-x 4 m}, but preinitializes the -@samp{Subject}, @samp{To}, @samp{CC}, @samp{In-reply-to} and +@samp{Subject}, @samp{To}, @samp{CC}, @samp{In-Reply-To} and @samp{References} header fields based on the message you are replying to. The @samp{To} field starts out as the address of the person who sent the message you received, and the @samp{CC} field starts out with diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi index ae22a90a16b..25f0cc4183e 100644 --- a/doc/emacs/search.texi +++ b/doc/emacs/search.texi @@ -253,6 +253,13 @@ character or word at point to the search string. This is an easy way to search for another occurrence of the text at point. (The decision of whether to copy a character or a word is heuristic.) +@kindex C-M-w @r{(Incremental search)} +@findex isearch-yank-symbol-or-char + @kbd{C-M-w} (@code{isearch-yank-symbol-or-char}) appends the next +character or symbol at point to the search string. This is an easy way +to search for another occurrence of the symbol at point. (The decision +of whether to copy a character or a symbol is heuristic.) + @kindex M-s C-e @r{(Incremental search)} @findex isearch-yank-line Similarly, @kbd{M-s C-e} (@code{isearch-yank-line}) appends the rest @@ -274,11 +281,11 @@ appended text with an earlier kill, similar to the usual @kbd{M-y} in the echo area appends the current X selection (@pxref{Primary Selection}) to the search string (@code{isearch-yank-x-selection}). -@kindex C-M-w @r{(Incremental search)} +@kindex C-M-d @r{(Incremental search)} @kindex C-M-y @r{(Incremental search)} @findex isearch-del-char @findex isearch-yank-char - @kbd{C-M-w} (@code{isearch-del-char}) deletes the last character + @kbd{C-M-d} (@code{isearch-del-char}) deletes the last character from the search string, and @kbd{C-M-y} (@code{isearch-yank-char}) appends the character after point to the search string. An alternative method to add the character after point is to enter the @@ -308,7 +315,7 @@ string that failed to match is highlighted using the face At this point, there are several things you can do. If your string was mistyped, use @key{DEL} to cancel a previous input item -(@pxref{Basic Isearch}), @kbd{C-M-w} to erase one character at a time, +(@pxref{Basic Isearch}), @kbd{C-M-d} to erase one character at a time, or @kbd{M-e} to edit it. If you like the place you have found, you can type @key{RET} to remain there. Or you can type @kbd{C-g}, which removes from the search string the characters that could not be found @@ -468,7 +475,7 @@ of the keymap @code{isearch-mode-map} (@pxref{Keymaps}). This subsection describes how to control whether typing a command not specifically meaningful in searches exits the search before executing -the command. It also describes two categories of commands which you +the command. It also describes three categories of commands which you can type without exiting the current incremental search, even though they are not themselves part of incremental search. @@ -477,7 +484,7 @@ they are not themselves part of incremental search. search exits the search before executing the command. Thus, the command operates on the buffer from which you invoked the search. However, if you customize the variable @code{search-exit-option} to -@code{nil}, the characters which you type that are not interpreted by +@code{append}, the characters which you type that are not interpreted by the incremental search are simply appended to the search string. This is so you could include in the search string control characters, such as @kbd{C-a}, that would normally exit the search and invoke the @@ -538,6 +545,18 @@ change point, the buffer contents, the match data, the current buffer, or the selected window and frame. The command must not itself attempt an incremental search. This feature is disabled if @code{isearch-allow-scroll} is @code{nil} (which it is by default). + +@item Motion Commands +@cindex motion commands, during incremental search +When @code{isearch-yank-on-move} is customized to @code{shift}, +you can extend the search string by holding down the shift key while +typing cursor motion commands. It will yank text that ends at the new +position after moving point in the current buffer. + +When @code{isearch-yank-on-move} is @code{t}, you can extend the +search string without using the shift key for cursor motion commands, +but it applies only for certain motion command that have the +@code{isearch-move} property on their symbols. @end table @node Isearch Minibuffer @@ -1817,7 +1836,7 @@ In the @file{*Occur*} buffer, you can click on each entry, or move point there and type @key{RET}, to visit the corresponding position in the buffer that was searched. @kbd{o} and @kbd{C-o} display the match in another window; @kbd{C-o} does not select it. Alternatively, you -can use the @kbd{C-x `} (@code{next-error}) command to visit the +can use the @kbd{M-g M-n} (@code{next-error}) command to visit the occurrences one by one (@pxref{Compilation Mode}). @cindex Occur Edit mode diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi index f5d69abf279..c6b8912e2e3 100644 --- a/doc/emacs/sending.texi +++ b/doc/emacs/sending.texi @@ -70,7 +70,7 @@ or using some other method. @xref{Mail Sending}, for details. @example To: subotai@@example.org -Cc: mongol.soldier@@example.net, rms@@gnu.org +CC: mongol.soldier@@example.net, rms@@gnu.org Subject: Re: What is best in life? From: conan@@example.org --text follows this line-- @@ -170,14 +170,14 @@ writes in Babyl format. If an Rmail buffer is visiting the file, Emacs updates it accordingly. To specify more than one file, use several @samp{FCC} fields, with one file name in each field. -@item Reply-to +@item Reply-To An address to which replies should be sent, instead of @samp{From}. This is used if, for some reason, your @samp{From} address cannot receive replies. -@item Mail-reply-to -This field takes precedence over @samp{Reply-to}. It is used because -some mailing lists set the @samp{Reply-to} field for their own +@item Mail-Reply-To +This field takes precedence over @samp{Reply-To}. It is used because +some mailing lists set the @samp{Reply-To} field for their own purposes (a somewhat controversial practice). @item Mail-Followup-To @@ -186,14 +186,14 @@ messages. This is typically used when you reply to a message from a mailing list that you are subscribed to, and want replies to go to the list without sending an extra copy to you. -@item In-reply-to +@item In-Reply-To An identifier for the message you are replying to. Most mail readers use this information to group related messages together. Normally, this header is filled in automatically when you reply to a message in any mail program built into Emacs. @item References -Identifiers for previous related messages. Like @samp{In-reply-to}, +Identifiers for previous related messages. Like @samp{In-Reply-To}, this is normally filled in automatically for you. @end table @@ -220,12 +220,12 @@ To: foo@@example.net, this@@example.net, You can direct Emacs to insert certain default headers into the mail buffer by setting the variable @code{mail-default-headers} to a string. Then @kbd{C-x m} inserts this string into the message -headers. For example, here is how to add a @samp{Reply-to} and +headers. For example, here is how to add a @samp{Reply-To} and @samp{FCC} header to each message: @smallexample (setq mail-default-headers - "Reply-to: foo@@example.com\nFCC: ~/Mail/sent") + "Reply-To: foo@@example.com\nFCC: ~/Mail/sent") @end smallexample @noindent @@ -293,7 +293,7 @@ alias definitions and include commands. Mail aliases expand as abbrevs---that is to say, as soon as you type a word-separator character after an alias (@pxref{Abbrevs}). This expansion takes place only within the @samp{To}, @samp{From}, -@samp{CC}, @samp{BCC}, and @samp{Reply-to} header fields (plus their +@samp{CC}, @samp{BCC}, and @samp{Reply-To} header fields (plus their @samp{Resent-} variants); it does not take place in other header fields, such as @samp{Subject}. @@ -422,7 +422,7 @@ Move to the @samp{CC} header (@code{message-goto-cc}). @item C-c C-f C-b Move to the @samp{BCC} header (@code{message-goto-bcc}). @item C-c C-f C-r -Move to the @samp{Reply-to} header (@code{message-goto-reply-to}). +Move to the @samp{Reply-To} header (@code{message-goto-reply-to}). @item C-c C-f C-f Move to the @samp{Mail-Followup-To} header field (@code{message-goto-followup-to}). diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi index e9b17dbb651..96492783b92 100644 --- a/doc/emacs/text.texi +++ b/doc/emacs/text.texi @@ -459,6 +459,13 @@ non-@code{nil}, and in programming-language strings if @code{nil} for @code{electric-quote-string} and @code{t} for the other variables. +@vindex electric-quote-replace-double + You can also set the option @code{electric-quote-replace-double} to +a non-@code{nil} value. Then, typing @t{"} insert an appropriate +curved double quote depending on context: @t{“} at the beginning of +the buffer or after a line break, whitespace, opening parenthesis, or +quote character, and @t{”} otherwise. + Electric Quote mode is disabled by default. To toggle it in a single buffer, use @kbd{M-x electric-quote-local-mode}. To toggle it globally, type @@ -631,8 +638,11 @@ line. If a function returns a non-@code{nil} value, Emacs will not break the line there. Functions you can use there include: @code{fill-single-word-nobreak-p} (don't break after the first word of a sentence or before the last); @code{fill-single-char-nobreak-p} -(don't break after a one-letter word); and @code{fill-french-nobreak-p} -(don't break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}). +(don't break after a one-letter word preceded by a whitespace +character); @code{fill-french-nobreak-p} (don't break after @samp{(} +or before @samp{)}, @samp{:} or @samp{?}); and +@code{fill-polish-nobreak-p} (don't break after a one letter word, +even if preceded by a non-whitespace character). @node Fill Prefix @subsection The Fill Prefix @@ -2406,11 +2416,13 @@ to the commands above. @subsection Setting Other Text Properties The Special Properties submenu of Text Properties has entries for -adding or removing three other text properties: @code{read-only}, +adding or removing four other text properties: @code{read-only}, (which disallows alteration of the text), @code{invisible} (which -hides text), and @code{intangible} (which disallows moving point -within the text). The @samp{Remove Special} menu item removes all of -these special properties from the text in the region. +hides text), @code{intangible} (which disallows moving point within +the text), and @code{charset} (which is important for selecting a +proper font to display a character). The @samp{Remove Special} menu +item removes all of these special properties from the text in the +region. The @code{invisible} and @code{intangible} properties are not saved. diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi index 27077ff9ec1..4e6e7e399b4 100644 --- a/doc/emacs/windows.texi +++ b/doc/emacs/windows.texi @@ -157,7 +157,9 @@ this option is @code{nil}. @item C-x o Select another window (@code{other-window}). @item C-M-v -Scroll the next window (@code{scroll-other-window}). +Scroll the next window upward (@code{scroll-other-window}). +@item C-M-S-v +Scroll the next window downward (@code{scroll-other-window-down}). @item mouse-1 @kbd{mouse-1}, in the text area of a window, selects the window and moves point to the position clicked. Clicking in the mode line @@ -181,13 +183,18 @@ back and finish supplying the minibuffer argument that is requested. @kindex C-M-v @findex scroll-other-window +@kindex C-M-S-v +@findex scroll-other-window-down The usual scrolling commands (@pxref{Display}) apply to the selected -window only, but there is one command to scroll the next window. +window only, but there are also commands to scroll the next window. @kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that -@kbd{C-x o} would select. It takes arguments, positive and negative, -like @kbd{C-v}. (In the minibuffer, @kbd{C-M-v} scrolls the help -window associated with the minibuffer, if any, rather than the next -window in the standard cyclic order; @pxref{Minibuffer Edit}.) +@kbd{C-x o} would select. In other respects, the command behaves like +@kbd{C-v}; both move the buffer text upward relative to the window, and +take positive and negative arguments. (In the minibuffer, @kbd{C-M-v} +scrolls the help window associated with the minibuffer, if any, rather +than the next window in the standard cyclic order; @pxref{Minibuffer +Edit}.) @kbd{C-M-S-v} (@code{scroll-other-window-down}) scrolls the +next window downward in a similar way. @vindex mouse-autoselect-window If you set @code{mouse-autoselect-window} to a non-@code{nil} value, @@ -352,7 +359,7 @@ various help commands (@pxref{Help}), work by calling Other commands do the same as @code{display-buffer}, and additionally select the displaying window so that you can begin -editing its buffer. The command @kbd{C-x `} (@code{next-error}) is +editing its buffer. The command @kbd{M-g M-n} (@code{next-error}) is one example (@pxref{Compilation Mode}). Such commands work by calling the function @code{pop-to-buffer} internally. @xref{Switching Buffers,,Switching to a Buffer in a Window, elisp, The Emacs Lisp diff --git a/doc/lispintro/Makefile.in b/doc/lispintro/Makefile.in index efe5a1e0046..37fffb8a0f2 100644 --- a/doc/lispintro/Makefile.in +++ b/doc/lispintro/Makefile.in @@ -109,8 +109,8 @@ emacs-lisp-intro.ps: emacs-lisp-intro.dvi .PHONY: mostlyclean clean distclean bootstrap-clean maintainer-clean infoclean mostlyclean: - rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \ - *.op *.ops *.pg *.pgs *.tp *.tps *.vr *.vrs + rm -f ./*.aux ./*.log ./*.toc ./*.cp ./*.cps ./*.fn ./*.fns ./*.ky ./*.kys \ + ./*.op ./*.ops ./*.pg ./*.pgs ./*.tp ./*.tps ./*.vr ./*.vrs clean: mostlyclean rm -f $(DVI_TARGETS) $(HTML_TARGETS) $(PDF_TARGETS) $(PS_TARGETS) diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 3305f5b3add..f292a1759fc 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -11070,9 +11070,8 @@ The @code{dotimes} macro is similar to @code{dolist}, except that it loops a specific number of times. The first argument to @code{dotimes} is assigned the numbers 0, 1, 2 -and so forth each time around the loop, and the value of the third -argument is returned. You need to provide the value of the second -argument, which is how many times the macro loops. +and so forth each time around the loop. You need to provide the value +of the second argument, which is how many times the macro loops. @need 1250 For example, the following binds the numbers from 0 up to, but not @@ -11084,17 +11083,18 @@ three numbers in all, starting with zero as the first number.) @smallexample @group (let (value) ; otherwise a value is a void variable - (dotimes (number 3 value) - (setq value (cons number value)))) + (dotimes (number 3) + (setq value (cons number value))) + value) @result{} (2 1 0) @end group @end smallexample @noindent -@code{dotimes} returns @code{value}, so the way to use -@code{dotimes} is to operate on some expression @var{number} number of -times and then return the result, either as a list or an atom. +The way to use @code{dotimes} is to operate on some expression +@var{number} number of times and then return the result, either as +a list or an atom. @need 1250 Here is an example of a @code{defun} that uses @code{dotimes} to add @@ -11105,8 +11105,9 @@ up the number of pebbles in a triangle. (defun triangle-using-dotimes (number-of-rows) "Using `dotimes', add up the number of pebbles in a triangle." (let ((total 0)) ; otherwise a total is a void variable - (dotimes (number number-of-rows total) - (setq total (+ total (1+ number)))))) + (dotimes (number number-of-rows) + (setq total (+ total (1+ number)))) + total)) (triangle-using-dotimes 4) @end group @@ -15598,7 +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 @@ -16798,7 +16799,7 @@ It will look like this: ;; If you edit it by hand, you could mess it up, so be careful. ;; Your init file should contain only one such instance. ;; If there is more than one, they won't work right. - '(text-mode-hook (quote (turn-on-auto-fill text-mode-hook-identify)))) + '(text-mode-hook '(turn-on-auto-fill text-mode-hook-identify))) @end group @end smallexample diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in index 74e3878a37e..5de04a7784c 100644 --- a/doc/lispref/Makefile.in +++ b/doc/lispref/Makefile.in @@ -167,8 +167,8 @@ elisp.ps: elisp.dvi ## [12] stuff is from two-volume.make. mostlyclean: - rm -f *.aux *.log *.toc *.cp *.cps *.fn *.fns *.ky *.kys \ - *.op *.ops *.pg *.pgs *.tp *.tps *.vr *.vrs + rm -f ./*.aux ./*.log ./*.toc ./*.cp ./*.cps ./*.fn ./*.fns ./*.ky ./*.kys \ + ./*.op ./*.ops ./*.pg ./*.pgs ./*.tp ./*.tps ./*.vr ./*.vrs rm -f elisp[12]* vol[12].tmp clean: mostlyclean diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi index ce1ab693672..b92d3701ec9 100644 --- a/doc/lispref/abbrevs.texi +++ b/doc/lispref/abbrevs.texi @@ -232,7 +232,8 @@ Emacs commands to offer to save your abbrevs. Save all abbrev definitions (except system abbrevs), for all abbrev tables listed in @code{abbrev-table-name-list}, in the file @var{filename}, in the form of a Lisp program that when loaded will -define the same abbrevs. If @var{filename} is @code{nil} or omitted, +define the same abbrevs. Tables that do not have any abbrevs to save +are omitted. If @var{filename} is @code{nil} or omitted, @code{abbrev-file-name} is used. This function returns @code{nil}. @end deffn diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 8d8fc97a60f..29f542b685b 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -648,16 +648,13 @@ file should not be done. @defun visited-file-modtime This function returns the current buffer's recorded last file -modification time, as a list of the form @code{(@var{high} @var{low} -@var{microsec} @var{picosec})}. (This is the same format that -@code{file-attributes} uses to return time values; @pxref{File -Attributes}.) +modification time, as a Lisp timestamp (@pxref{Time of Day}). If the buffer has no recorded last modification time, this function returns zero. This case occurs, for instance, if the buffer is not visiting a file or if the time has been explicitly cleared by @code{clear-visited-file-modtime}. Note, however, that -@code{visited-file-modtime} returns a list for some non-file buffers +@code{visited-file-modtime} returns a timestamp for some non-file buffers too. For instance, in a Dired buffer listing a directory, it returns the last modification time of that directory, as recorded by Dired. @@ -671,9 +668,8 @@ is not @code{nil}, and otherwise to the last modification time of the visited file. If @var{time} is neither @code{nil} nor an integer flag returned -by @code{visited-file-modtime}, it should have the form -@code{(@var{high} @var{low} @var{microsec} @var{picosec})}, -the format used by @code{current-time} (@pxref{Time of Day}). +by @code{visited-file-modtime}, it should be a Lisp time value +(@pxref{Time of Day}). This function is useful if the buffer was not read from the file normally, or if the file itself has been changed for some known benign @@ -830,7 +826,7 @@ regardless of which frames they were displayed on. @group ;; @r{Note that the name of the minibuffer} ;; @r{begins with a space!} -(mapcar (function buffer-name) (buffer-list)) +(mapcar #'buffer-name (buffer-list)) @result{} ("buffers.texi" " *Minibuf-1*" "buffer.c" "*Help*" "TAGS") @end group diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 3ffe8f7fb9d..5d4184e3fb4 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -1095,12 +1095,10 @@ Matches if @var{expval} is a vector of length @var{m} whose @item @var{symbol} @itemx @var{keyword} -@itemx @var{integer} +@itemx @var{number} @itemx @var{string} Matches if the corresponding element of @var{expval} is @code{equal} to the specified literal object. -Note that, aside from @var{symbol}, this is the same set of -self-quoting literal objects that are acceptable as a core pattern. @item ,@var{pattern} Matches if the corresponding element of @var{expval} @@ -1355,7 +1353,8 @@ This construct executes @var{body} once for each integer from 0 (inclusive) to @var{count} (exclusive), binding the variable @var{var} to the integer for the current iteration. Then it returns the value of evaluating @var{result}, or @code{nil} if @var{result} is omitted. -Here is an example of using @code{dotimes} to do something 100 times: +Use of @var{result} is deprecated. Here is an example of using +@code{dotimes} to do something 100 times: @example (dotimes (i 100) @@ -1986,9 +1985,10 @@ error occurs during @var{protected-form}. Each of the @var{handlers} is a list of the form @code{(@var{conditions} @var{body}@dots{})}. Here @var{conditions} is an error condition name to be handled, or a list of condition names (which can include @code{debug} -to allow the debugger to run before the handler); @var{body} is one or more -Lisp expressions to be executed when this handler handles an error. -Here are examples of handlers: +to allow the debugger to run before the handler). A condition name of +@code{t} matches any condition. @var{body} is one or more Lisp +expressions to be executed when this handler handles an error. Here +are examples of handlers: @example @group diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 2576fbe39d7..9e433433107 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -81,7 +81,8 @@ debugger recursively. @xref{Recursive Editing}. * Function Debugging:: Entering it when a certain function is called. * Variable Debugging:: Entering it when a variable is modified. * Explicit Debug:: Entering it at a certain point in the program. -* Using Debugger:: What the debugger does; what you see while in it. +* Using Debugger:: What the debugger does. +* Backtraces:: What you see while in the debugger. * Debugger Commands:: Commands used while in the debugger. * Invoking the Debugger:: How to call the function @code{debug}. * Internals of Debugger:: Subroutines of the debugger, and global variables. @@ -392,32 +393,82 @@ this is not what you want, you can either set @code{eval-expression-debug-on-error} to @code{nil}, or set @code{debug-on-error} to @code{nil} in @code{debugger-mode-hook}. + The debugger itself must be run byte-compiled, since it makes +assumptions about the state of the Lisp interpreter. These +assumptions are false if the debugger is running interpreted. + +@node Backtraces +@subsection Backtraces +@cindex backtrace buffer + +Debugger mode is derived from Backtrace mode, which is also used to +show backtraces by Edebug and ERT. (@pxref{Edebug}, and @ref{Top,the +ERT manual,, ert, ERT: Emacs Lisp Regression Testing}.) + +@cindex stack frame +The backtrace buffer shows you the functions that are executing and +their argument values. When a backtrace buffer is created, it shows +each stack frame on one, possibly very long, line. (A stack frame is +the place where the Lisp interpreter records information about a +particular invocation of a function.) The most recently called +function will be at the top. + @cindex current stack frame - The backtrace buffer shows you the functions that are executing and -their argument values. It also allows you to specify a stack frame by -moving point to the line describing that frame. (A stack frame is the -place where the Lisp interpreter records information about a particular -invocation of a function.) The frame whose line point is on is -considered the @dfn{current frame}. Some of the debugger commands -operate on the current frame. If a line starts with a star, that means -that exiting that frame will call the debugger again. This is useful -for examining the return value of a function. - - If a function name is underlined, that means the debugger knows -where its source code is located. You can click with the mouse on -that name, or move to it and type @key{RET}, to visit the source code. +In a backtrace you can specify a stack frame by moving point to a line +describing that frame. The frame whose line point is on is considered +the @dfn{current frame}. + +If a function name is underlined, that means Emacs knows where its +source code is located. You can click with the mouse on that name, or +move to it and type @key{RET}, to visit the source code. You can also +type @key{RET} while point is on any name of a function or variable +which is not underlined, to see help information for that symbol in a +help buffer, if any exists. The @code{xref-find-definitions} command, +bound to @key{M-.}, can also be used on any identifier in a backtrace +(@pxref{Looking Up Identifiers,,,emacs, The GNU Emacs Manual}). + +In backtraces, the tails of long lists and the ends of long strings, +vectors or structures, as well as objects which are deeply nested, +will be printed as underlined ``...''. You can click with the mouse +on a ``...'', or type @key{RET} while point is on it, to show the part +of the object that was hidden. To control how much abbreviation is +done, customize @code{backtrace-line-length}. + +Here is a list of commands for navigating and viewing backtraces: - The debugger itself must be run byte-compiled, since it makes -assumptions about how many stack frames are used for the debugger -itself. These assumptions are false if the debugger is running -interpreted. +@table @kbd +@item v +Toggle the display of local variables of the current stack frame. + +@item p +Move to the beginning of the frame, or to the beginning +of the previous frame. + +@item n +Move to the beginning of the next frame. + +@item + +Add line breaks and indentation to the top-level Lisp form at point to +make it more readable. + +@item - +Collapse the top-level Lisp form at point back to a single line. + +@item # +Toggle @code{print-circle} for the frame at point. + +@item . +Expand all the forms abbreviated with ``...'' in the frame at point. + +@end table @node Debugger Commands @subsection Debugger Commands @cindex debugger command list The debugger buffer (in Debugger mode) provides special commands in -addition to the usual Emacs commands. The most important use of +addition to the usual Emacs commands and to the Backtrace mode commands +described in the previous section. The most important use of debugger commands is for stepping through code, so that you can see how control flows. The debugger can step through the control structures of an interpreted function, but cannot do so in a @@ -427,6 +478,11 @@ the same function. (To do this, visit the source for the function and type @kbd{C-M-x} on its definition.) You cannot use the Lisp debugger to step through a primitive function. +Some of the debugger commands operate on the current frame. If a +frame starts with a star, that means that exiting that frame will call the +debugger again. This is useful for examining the return value of a +function. + @c FIXME: Add @findex for the following commands? --xfq Here is a list of Debugger mode commands: @@ -502,8 +558,6 @@ Display a list of functions that will invoke the debugger when called. This is a list of functions that are set to break on entry by means of @code{debug-on-entry}. -@item v -Toggle the display of local variables of the current stack frame. @end table @node Invoking the Debugger @@ -624,20 +678,19 @@ of @code{debug} (@pxref{Invoking the Debugger}). @cindex run time stack @cindex call stack This function prints a trace of Lisp function calls currently active. -This is the function used by @code{debug} to fill up the -@file{*Backtrace*} buffer. It is written in C, since it must have access -to the stack to determine which function calls are active. The return -value is always @code{nil}. +The trace is identical to the one that @code{debug} would show in the +@file{*Backtrace*} buffer. The return value is always nil. In the following example, a Lisp expression calls @code{backtrace} explicitly. This prints the backtrace to the stream @code{standard-output}, which, in this case, is the buffer @samp{backtrace-output}. -Each line of the backtrace represents one function call. The line shows -the values of the function's arguments if they are all known; if they -are still being computed, the line says so. The arguments of special -forms are elided. +Each line of the backtrace represents one function call. The line +shows the function followed by a list of the values of the function's +arguments if they are all known; if they are still being computed, the +line consists of a list containing the function and its unevaluated +arguments. Long lists or deeply nested structures may be elided. @smallexample @group @@ -654,10 +707,10 @@ forms are elided. @group ----------- Buffer: backtrace-output ------------ backtrace() - (list ...computing arguments...) + (list 'testing (backtrace)) @end group (progn ...) - eval((progn (1+ var) (list (quote testing) (backtrace)))) + eval((progn (1+ var) (list 'testing (backtrace)))) (setq ...) (save-excursion ...) (let ...) @@ -685,10 +738,10 @@ example would look as follows: @group ----------- Buffer: backtrace-output ------------ (backtrace) - (list ...computing arguments...) + (list 'testing (backtrace)) @end group (progn ...) - (eval (progn (1+ var) (list (quote testing) (backtrace)))) + (eval (progn (1+ var) (list 'testing (backtrace)))) (setq ...) (save-excursion ...) (let ...) diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index b3ce7fbf6af..19424ecc7e6 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -469,19 +469,54 @@ never print it, there are many good reasons for this not to happen. Secondly, @samp{done} is more explicit. @end defun -@defmac dotimes-with-progress-reporter (var count [result]) message body@dots{} +@defmac dotimes-with-progress-reporter (var count [result]) reporter-or-message body@dots{} This is a convenience macro that works the same way as @code{dotimes} does, but also reports loop progress using the functions described -above. It allows you to save some typing. +above. It allows you to save some typing. The argument +@var{reporter-or-message} can be either a string or a progress +reporter object. -You can rewrite the example in the beginning of this node using -this macro this way: +You can rewrite the example in the beginning of this subsection using +this macro as follows: @example +@group (dotimes-with-progress-reporter (k 500) "Collecting some mana for Emacs..." (sit-for 0.01)) +@end group +@end example + +Using a reporter object as the @var{reporter-or-message} argument is +useful if you want to specify the optional arguments in +@var{make-progress-reporter}. For instance, you can write the +previous example as follows: + +@example +@group +(dotimes-with-progress-reporter + (k 500) + (make-progress-reporter "Collecting some mana for Emacs..." 0 500 0 1 1.5) + (sit-for 0.01)) +@end group +@end example +@end defmac + +@defmac dolist-with-progress-reporter (var count [result]) reporter-or-message body@dots{} +This is another convenience macro that works the same way as @code{dolist} +does, but also reports loop progress using the functions described +above. As in @code{dotimes-with-progress-reporter}, +@code{reporter-or-message} can be a progress reporter or a string. +You can rewrite the previous example with this macro as follows: + +@example +@group +(dolist-with-progress-reporter + (k (number-sequence 0 500)) + "Collecting some mana for Emacs..." + (sit-for 0.01)) +@end group @end example @end defmac @@ -2939,7 +2974,13 @@ the remapped face---it replaces the normal definition of @var{face}, instead of modifying it. If @code{face-remapping-alist} is buffer-local, its local value takes -effect only within that buffer. +effect only within that buffer. If @code{face-remapping-alist} +includes faces applicable only to certain windows, by using the +@w{@code{(:filtered (:window @var{param} @var{val}) @var{spec})}}, +that face takes effect only in windows that match the filter +conditions (@pxref{Special Properties}). To turn off face filtering +temporarily, bind @code{face-filters-always-match} to a non-@code{nil} +value, then all face filters will match any window. Note: face remapping is non-recursive. If @var{remapping} references the same face name @var{face}, either directly or via the @@ -4129,10 +4170,10 @@ Used to indicate continued lines. @item @code{right-triangle}, @code{left-triangle} The former is used by overlay arrows. The latter is unused. -@item @code{up-arrow}, @code{down-arrow}, @code{top-left-angle} @code{top-right-angle} +@item @code{up-arrow}, @code{down-arrow} @itemx @code{bottom-left-angle}, @code{bottom-right-angle} -@itemx @code{top-right-angle}, @code{top-left-angle} -@itemx @code{left-bracket}, @code{right-bracket}, @code{top-right-angle}, @code{top-left-angle} +@itemx @code{top-left-angle}, @code{top-right-angle} +@itemx @code{left-bracket}, @code{right-bracket} Used to indicate buffer boundaries. @item @code{filled-rectangle}, @code{hollow-rectangle} @@ -4140,7 +4181,7 @@ Used to indicate buffer boundaries. @itemx @code{vertical-bar}, @code{horizontal-bar} Used for different types of fringe cursors. -@item @code{empty-line}, @code{exclamation-mark}, @code{question-mark}, @code{exclamation-mark} +@item @code{empty-line}, @code{exclamation-mark}, @code{question-mark} Not used by core Emacs features. @end table diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index e674280a83d..2c0ee3969b9 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -442,8 +442,18 @@ Redisplay the most recently known expression result in the echo area Display a backtrace, excluding Edebug's own functions for clarity (@code{edebug-backtrace}). -You cannot use debugger commands in the backtrace buffer in Edebug as -you would in the standard debugger. +@xref{Backtraces}, for a description of backtraces +and the commands which work on them. + +@findex edebug-backtrace-show-instrumentation +@findex edebug-backtrace-hide-instrumentation +If you would like to see Edebug's functions in the backtrace, +use @kbd{M-x edebug-backtrace-show-instrumentation}. To hide them +again use @kbd{M-x edebug-backtrace-hide-instrumentation}. + +If a backtrace frame starts with @samp{>} that means that Edebug knows +where the source code for the frame is located. Use @kbd{s} to jump +to the source code for the current frame. The backtrace buffer is killed automatically when you continue execution. @@ -1711,3 +1721,33 @@ Whether or not to pause for @code{edebug-sit-for-seconds} on reaching a breakpoint. Set to @code{nil} to prevent the pause, non-@code{nil} to allow it. @end defopt + +@defopt edebug-behavior-alist +By default, this alist contains one entry with the key @code{edebug} +and a list of three functions, which are the default implementations +of the functions inserted in instrumented code: @code{edebug-enter}, +@code{edebug-before} and @code{edebug-after}. To change Edebug's +behavior globally, modify the default entry. + +Edebug's behavior may also be changed on a per-definition basis by +adding an entry to this alist, with a key of your choice and three +functions. Then set the @code{edebug-behavior} symbol property of an +instrumented definition to the key of the new entry, and Edebug will +call the new functions in place of its own for that definition. +@end defopt + +@defopt edebug-new-definition-function +A function run by Edebug after it wraps the body of a definition +or closure. After Edebug has initialized its own data, this function +is called with one argument, the symbol associated with the +definition, which may be the actual symbol defined or one generated by +Edebug. This function may be used to set the @code{edebug-behavior} +symbol property of each definition instrumented by Edebug. +@end defopt + +@defopt edebug-after-instrumentation-function +To inspect or modify Edebug's instrumentation before it is used, set +this variable to a function which takes one argument, an instrumented +top-level form, and returns either the same or a replacement form, +which Edebug will then use as the final result of instrumentation. +@end defopt diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index a2b03da5abc..e18759654d9 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -455,6 +455,7 @@ Evaluation the program). * Backquote:: Easier construction of list structure. * Eval:: How to invoke the Lisp interpreter explicitly. +* Deferred Eval:: Deferred and lazy evaluation of forms. Kinds of Forms @@ -654,7 +655,8 @@ The Lisp Debugger * Function Debugging:: Entering it when a certain function is called. * Variable Debugging:: Entering it when a variable is modified. * Explicit Debug:: Entering it at a certain point in the program. -* Using Debugger:: What the debugger does; what you see while in it. +* Using Debugger:: What the debugger does. +* Backtraces:: What you see while in the debugger. * Debugger Commands:: Commands used while in the debugger. * Invoking the Debugger:: How to call the function @code{debug}. * Internals of Debugger:: Subroutines of the debugger, and global variables. @@ -1354,6 +1356,7 @@ Threads * Basic Thread Functions:: Basic thread functions. * Mutexes:: Mutexes allow exclusive access to data. * Condition Variables:: Inter-thread events. +* The Thread List:: Show the active threads. Processes @@ -1398,7 +1401,6 @@ Packing and Unpacking Byte Arrays * Bindat Spec:: Describing data layout. * Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! Emacs Display diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index c794028b5e6..aa99b2b1a98 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -159,6 +159,11 @@ The message is @samp{No catch for tag}. @xref{Catch and Throw}. The message is @samp{Attempt to modify a protected file}. @end ignore +@item range-error +The message is @code{Arithmetic range error}. +This can happen with integers exceeding the @code{integer-width} limit. +@xref{Integer Basics}. + @item scan-error The message is @samp{Scan error}. This happens when certain syntax-parsing functions find invalid syntax or mismatched @@ -223,9 +228,6 @@ The message is @samp{Arithmetic domain error}. The message is @samp{Arithmetic overflow error}. This is a subcategory of @code{domain-error}. -@item range-error -The message is @code{Arithmetic range error}. - @item singularity-error The message is @samp{Arithmetic singularity error}. This is a subcategory of @code{domain-error}. diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index 4bf70d247b6..db42dfb6373 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -20,11 +20,12 @@ function @code{eval}. @ifnottex @menu -* Intro Eval:: Evaluation in the scheme of things. -* Forms:: How various sorts of objects are evaluated. -* Quoting:: Avoiding evaluation (to put constants in the program). -* Backquote:: Easier construction of list structure. -* Eval:: How to invoke the Lisp interpreter explicitly. +* Intro Eval:: Evaluation in the scheme of things. +* Forms:: How various sorts of objects are evaluated. +* Quoting:: Avoiding evaluation (to put constants in the program). +* Backquote:: Easier construction of list structure. +* Eval:: How to invoke the Lisp interpreter explicitly. +* Deferred Eval:: Deferred and lazy evaluation of forms. @end menu @node Intro Eval @@ -584,15 +585,15 @@ Here are some examples of expressions that use @code{quote}: @end group @group ''foo - @result{} (quote foo) + @result{} 'foo @end group @group '(quote foo) - @result{} (quote foo) + @result{} 'foo @end group @group ['foo] - @result{} [(quote foo)] + @result{} ['foo] @end group @end example @@ -883,3 +884,115 @@ particular elements, like this: @end group @end example @end defvar + +@node Deferred Eval +@section Deferred and Lazy Evaluation + +@cindex deferred evaluation +@cindex lazy evaluation + + + Sometimes it is useful to delay the evaluation of an expression, for +example if you want to avoid performing a time-consuming calculation +if it turns out that the result is not needed in the future of the +program. The @file{thunk} library provides the following functions +and macros to support such @dfn{deferred evaluation}: + +@cindex thunk +@defmac thunk-delay forms@dots{} +Return a @dfn{thunk} for evaluating the @var{forms}. A thunk is a +closure (@pxref{Closures}) that inherits the lexical environment of the +@code{thunk-delay} call. Using this macro requires +@code{lexical-binding}. +@end defmac + +@defun thunk-force thunk +Force @var{thunk} to perform the evaluation of the forms specified in +the @code{thunk-delay} that created the thunk. The result of the +evaluation of the last form is returned. The @var{thunk} also +``remembers'' that it has been forced: Any further calls of +@code{thunk-force} with the same @var{thunk} will just return the same +result without evaluating the forms again. +@end defun + +@defmac thunk-let (bindings@dots{}) forms@dots{} +This macro is analogous to @code{let} but creates ``lazy'' variable +bindings. Any binding has the form @w{@code{(@var{symbol} +@var{value-form})}}. Unlike @code{let}, the evaluation of any +@var{value-form} is deferred until the binding of the according +@var{symbol} is used for the first time when evaluating the +@var{forms}. Any @var{value-form} is evaluated at most once. Using +this macro requires @code{lexical-binding}. +@end defmac + +Example: + +@example +@group +(defun f (number) + (thunk-let ((derived-number + (progn (message "Calculating 1 plus 2 times %d" number) + (1+ (* 2 number))))) + (if (> number 10) + derived-number + number))) +@end group + +@group +(f 5) +@result{} 5 +@end group + +@group +(f 12) +@print{} Calculating 1 plus 2 times 12 +@result{} 25 +@end group + +@end example + +Because of the special nature of lazily bound variables, it is an error +to set them (e.g.@: with @code{setq}). + + +@defmac thunk-let* (bindings@dots{}) forms@dots{} +This is like @code{thunk-let} but any expression in @var{bindings} is allowed +to refer to preceding bindings in this @code{thunk-let*} form. Using +this macro requires @code{lexical-binding}. +@end defmac + +@example +@group +(thunk-let* ((x (prog2 (message "Calculating x...") + (+ 1 1) + (message "Finished calculating x"))) + (y (prog2 (message "Calculating y...") + (+ x 1) + (message "Finished calculating y"))) + (z (prog2 (message "Calculating z...") + (+ y 1) + (message "Finished calculating z"))) + (a (prog2 (message "Calculating a...") + (+ z 1) + (message "Finished calculating a")))) + (* z x)) + +@print{} Calculating z... +@print{} Calculating y... +@print{} Calculating x... +@print{} Finished calculating x +@print{} Finished calculating y +@print{} Finished calculating z +@result{} 8 + +@end group +@end example + +@code{thunk-let} and @code{thunk-let*} use thunks implicitly: their +expansion creates helper symbols and binds them to thunks wrapping the +binding expressions. All references to the original variables in the +body @var{forms} are then replaced by an expression that calls +@code{thunk-force} with the according helper variable as the argument. +So, any code using @code{thunk-let} or @code{thunk-let*} could be +rewritten to use thunks, but in many cases using these macros results +in nicer code than using thunks explicitly. diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 403a21b3365..5c99ea2781c 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -1299,36 +1299,34 @@ Alternate names, also known as hard links, can be created by using the @item The file's @acronym{UID}, normally as a string (@code{file-attribute-user-id}). However, if it does not correspond -to a named user, the value is a number. +to a named user, the value is an integer. @item The file's @acronym{GID}, likewise (@code{file-attribute-group-id}). @item -The time of last access, as a list of four integers -@code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})} -(@code{file-attribute-access-time}). (This is similar to the value of -@code{current-time}; see @ref{Time of Day}.) The value is truncated +The time of last access as a Lisp timestamp +(@code{file-attribute-status-change-time}). The timestamp is in the +style of @code{current-time} (@pxref{Time of Day}) and is truncated to that of the filesystem's timestamp resolution; for example, on some FAT-based filesystems, only the date of last access is recorded, so this time will always hold the midnight of the day of the last access. @cindex modification time of file @item -The time of last modification as a list of four integers (as above) +The time of last modification as a Lisp timestamp (@code{file-attribute-modification-time}). This is the last time when the file's contents were modified. @item -The time of last status change as a list of four integers (as above) +The time of last status change as a Lisp timestamp (@code{file-attribute-status-change-time}). This is the time of the last change to the file's access mode bits, its owner and group, and other information recorded in the filesystem for the file, beyond the file's contents. @item -The size of the file in bytes (@code{file-attribute-size}). This is -floating point if the size is too large to fit in a Lisp integer. +The size of the file in bytes (@code{file-attribute-size}). @item The file's modes, as a string of ten letters or dashes, as in @@ -1338,21 +1336,13 @@ The file's modes, as a string of ten letters or dashes, as in An unspecified value, present for backward compatibility. @item -The file's inode number (@code{file-attribute-inode-number}). If -possible, this is an integer. If the inode number is too large to be -represented as an integer in Emacs Lisp but dividing it by -@math{2^{16}} yields a representable integer, then the value has the -form @code{(@var{high} . @var{low})}, where @var{low} holds the low 16 -bits. If the inode number is too wide for even that, the value is of -the form @code{(@var{high} @var{middle} . @var{low})}, where -@code{high} holds the high bits, @var{middle} the middle 24 bits, and -@var{low} the low 16 bits. +The file's inode number (@code{file-attribute-inode-number}), +a nonnegative integer. @item The filesystem number of the device that the file is on -@code{file-attribute-device-number}). Depending on the magnitude of -the value, this can be either an integer or a cons cell, in the same -manner as the inode number. This element and the file's inode number +@code{file-attribute-device-number}), an integer. +This element and the file's inode number together give enough information to distinguish any two files on the system---no two files can have the same values for both of these numbers. @@ -1368,8 +1358,8 @@ For example, here are the file attributes for @file{files.texi}: (20000 23 0 0) (20614 64555 902289 872000) 122295 "-rw-rw-rw-" - t (5888 2 . 43978) - (15479 . 46724)) + t 6473924464520138 + 1014478468) @end group @end example @@ -1410,10 +1400,10 @@ has a mode of read and write access for the owner, group, and world. @item t is merely a placeholder; it carries no information. -@item (5888 2 . 43978) +@item 6473924464520138 has an inode number of 6473924464520138. -@item (15479 . 46724) +@item 1014478468 is on the file-system device whose number is 1014478468. @end table @end defun @@ -1567,13 +1557,16 @@ For compatibility, @var{predicate} can also be one of the symbols a list of one or more of these symbols. @end defun -@defun executable-find program +@defun executable-find program &optional remote This function searches for the executable file of the named @var{program} and returns the absolute file name of the executable, including its file-name extensions, if any. It returns @code{nil} if -the file is not found. The functions searches in all the directories +the file is not found. The function searches in all the directories in @code{exec-path}, and tries all the file-name extensions in @code{exec-suffixes} (@pxref{Subprocess Creation}). + +If @var{remote} is non-@code{nil}, and @code{default-directory} is a +remote directory, @var{program} is searched on the respective remote host. @end defun @node Changing Files @@ -2131,7 +2124,7 @@ Note that the @samp{.~3~} in the two last examples is the backup part, not an extension. @end defun -@defun file-name-base &optional filename +@defun file-name-base filename This function is the composition of @code{file-name-sans-extension} and @code{file-name-nondirectory}. For example, @@ -2139,8 +2132,6 @@ and @code{file-name-nondirectory}. For example, (file-name-base "/my/home/foo.c") @result{} "foo" @end example - -The @var{filename} argument defaults to @code{buffer-file-name}. @end defun @node Relative File Names @@ -2376,8 +2367,10 @@ start with @samp{~}.) Otherwise, the current buffer's value of @end example If the part of @var{filename} before the first slash is -@samp{~}, it expands to the value of the @env{HOME} environment -variable (usually your home directory). If the part before the first +@samp{~}, it expands to your home directory, which is typically +specified by the value of the @env{HOME} environment variable +(@pxref{General Variables,,, emacs, The GNU Emacs Manual}). +If the part before the first slash is @samp{~@var{user}} and if @var{user} is a valid login name, it expands to @var{user}'s home directory. If you do not want this expansion for a relative @var{filename} that @@ -2927,7 +2920,7 @@ are included. This is similar to @code{directory-files} in deciding which files to report on and how to report their names. However, instead of returning a list of file names, it returns for each file a -list @code{(@var{filename} @var{attributes})}, where @var{attributes} +list @code{(@var{filename} . @var{attributes})}, where @var{attributes} is what @code{file-attributes} returns for that file. The optional argument @var{id-format} has the same meaning as the corresponding argument to @code{file-attributes} (@pxref{Definition @@ -3004,10 +2997,16 @@ This command creates a directory named @var{dirname}. If @var{parents} is non-@code{nil}, as is always the case in an interactive call, that means to create the parent directories first, if they don't already exist. - @code{mkdir} is an alias for this. @end deffn +@deffn Command make-empty-file filename &optional parents +This command creates an empty file named @var{filename}. +As @code{make-directory}, this command creates parent directories +if @var{parents} is non-@code{nil}. +If @var{filename} already exists, this command signals an error. +@end deffn + @deffn Command copy-directory dirname newname &optional keep-time parents copy-contents This command copies the directory named @var{dirname} to @var{newname}. If @var{newname} is a directory name, @@ -3068,7 +3067,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 @@ -3139,8 +3138,8 @@ first, before handlers for jobs such as remote file access. @code{directory-file-name}, @code{directory-files}, @code{directory-files-and-attributes}, -@code{dired-compress-file}, @code{dired-uncache},@* -@code{expand-file-name}, +@code{dired-compress-file}, @code{dired-uncache}, +@code{exec-path}, @code{expand-file-name},@* @code{file-accessible-directory-p}, @code{file-acl}, @code{file-attributes}, @@ -3161,7 +3160,8 @@ first, before handlers for jobs such as remote file access. @code{file-ownership-preserved-p}, @code{file-readable-p}, @code{file-regular-p}, @code{file-remote-p}, @code{file-selinux-context}, -@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p}, +@code{file-symlink-p}, @code{file-system-info}, +@code{file-truename}, @code{file-writable-p}, @code{find-backup-file-name},@* @code{get-file-buffer}, @code{insert-directory}, @@ -3171,6 +3171,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}, @@ -3196,7 +3197,7 @@ first, before handlers for jobs such as remote file access. @code{directory-files}, @code{directory-files-and-at@discretionary{}{}{}tributes}, @code{dired-compress-file}, @code{dired-uncache}, -@code{expand-file-name}, +@code{exec-path}, @code{expand-file-name}, @code{file-accessible-direc@discretionary{}{}{}tory-p}, @code{file-acl}, @code{file-attributes}, @@ -3217,7 +3218,8 @@ first, before handlers for jobs such as remote file access. @code{file-ownership-pre@discretionary{}{}{}served-p}, @code{file-readable-p}, @code{file-regular-p}, @code{file-remote-p}, @code{file-selinux-context}, -@code{file-symlink-p}, @code{file-truename}, @code{file-writable-p}, +@code{file-symlink-p}, @code{file-system-info}, +@code{file-truename}, @code{file-writable-p}, @code{find-backup-file-name}, @code{get-file-buffer}, @code{insert-directory}, @@ -3226,6 +3228,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}, @@ -3353,8 +3356,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 @@ -3424,8 +3427,9 @@ between consecutive checks. For example: (let ((remote-file-name-inhibit-cache (- display-time-interval 5))) (and (file-exists-p file) - (< 0 (nth 7 (file-attributes - (file-chase-links file))))))) + (< 0 (file-attribute-size + (file-attributes + (file-chase-links file))))))) @end example @end defopt diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index b993f4932cd..8cb406cded3 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -181,6 +181,12 @@ the value of that parameter in the created frame to its value in the selected frame. @end defvar +@defopt server-after-make-frame-hook +A normal hook run when the Emacs server creates a client frame. When +this hook is called, the created frame is the selected one. +@xref{Emacs Server,,, emacs, The GNU Emacs Manual}. +@end defopt + @node Multiple Terminals @section Multiple Terminals @@ -2524,6 +2530,7 @@ it. @deffn Command delete-frame &optional frame force @vindex delete-frame-functions +@vindex after-delete-frame-functions This function deletes the frame @var{frame}. The argument @var{frame} must specify a live frame (see below) and defaults to the selected frame. @@ -2535,7 +2542,9 @@ performed recursively; so this step makes sure that no other frames with @var{frame} as their ancestor will exist. Then, unless @var{frame} specifies a tooltip, this function runs the hook @code{delete-frame-functions} (each function getting one argument, -@var{frame}) before actually killing the frame. +@var{frame}) before actually killing the frame. After actually killing +the frame and removing the frame from the frame list, @code{delete-frame} +runs @code{after-delete-frame-functions}. Note that a frame cannot be deleted as long as its minibuffer serves as surrogate minibuffer for another frame (@pxref{Minibuffers and Frames}). @@ -2696,14 +2705,22 @@ This function returns the selected frame. Some window systems and window managers direct keyboard input to the window object that the mouse is in; others require explicit clicks or commands to @dfn{shift the focus} to various window objects. Either -way, Emacs automatically keeps track of which frame has the focus. To +way, Emacs automatically keeps track of which frames have focus. To explicitly switch to a different frame from a Lisp function, call @code{select-frame-set-input-focus}. -Lisp programs can also switch frames temporarily by calling the -function @code{select-frame}. This does not alter the window system's -concept of focus; rather, it escapes from the window manager's control -until that control is somehow reasserted. +The plural ``frames'' in the previous paragraph is deliberate: while +Emacs itself has only one selected frame, Emacs can have frames on +many different terminals (recall that a connection to a window system +counts as a terminal), and each terminal has its own idea of which +frame has input focus. When you set the input focus to a frame, you +set the focus for that frame's terminal, but frames on other terminals +may still remain focused. + +Lisp programs can switch frames temporarily by calling the function +@code{select-frame}. This does not alter the window system's concept +of focus; rather, it escapes from the window manager's control until +that control is somehow reasserted. When using a text terminal, only one frame can be displayed at a time on the terminal, so after a call to @code{select-frame}, the next @@ -2714,11 +2731,11 @@ before the buffer name (@pxref{Mode Line Variables}). @defun select-frame-set-input-focus frame &optional norecord This function selects @var{frame}, raises it (should it happen to be -obscured by other frames) and tries to give it the X server's focus. -On a text terminal, the next redisplay displays the new frame on the -entire terminal screen. The optional argument @var{norecord} has the -same meaning as for @code{select-frame} (see below). The return value -of this function is not significant. +obscured by other frames) and tries to give it the window system's +focus. On a text terminal, the next redisplay displays the new frame +on the entire terminal screen. The optional argument @var{norecord} +has the same meaning as for @code{select-frame} (see below). +The return value of this function is not significant. @end defun Ideally, the function described next should focus a frame without also @@ -2766,17 +2783,35 @@ could switch to a different terminal without switching back when you're done. @end deffn -Emacs cooperates with the window system by arranging to select frames as -the server and window manager request. It does so by generating a -special kind of input event, called a @dfn{focus} event, when -appropriate. The command loop handles a focus event by calling -@code{handle-switch-frame}. @xref{Focus Events}. +@cindex text-terminal focus notification +Emacs cooperates with the window system by arranging to select frames +as the server and window manager request. When a window system +informs Emacs that one of its frames has been selected, Emacs +internally generates a @dfn{focus-in} event. When an Emacs frame is +displayed on a text-terminal emulator, such as @command{xterm}, which +supports reporting of focus-change notification, the focus-in and +focus-out events are available even for text-mode frames. Focus +events are normally handled by @code{handle-focus-in}. + +@deffn Command handle-focus-in event +This function handles focus-in events from window systems and +terminals that support explicit focus notifications. It updates the +per-frame focus flags that @code{frame-focus-state} queries and calls +@code{after-focus-change-function}. In addition, it generates a +@code{switch-frame} event in order to switch the Emacs notion of the +selected frame to the frame most recently focused in some terminal. +It's important to note that this switching of the Emacs selected frame +to the most recently focused frame does not mean that other frames do +not continue to have the focus in their respective terminals. Do not +invoke this function yourself: instead, attach logic to +@code{after-focus-change-function}. +@end deffn @deffn Command handle-switch-frame frame -This function handles a focus event by selecting frame @var{frame}. - -Focus events normally do their job by invoking this command. -Don't call it for any other reason. +This function handles a switch-frame event, which Emacs generates for +itself upon focus notification or under various other circumstances +involving an input event arriving at a different frame from the last +event. Do not invoke this function yourself. @end deffn @defun redirect-frame-focus frame &optional focus-frame @@ -2810,14 +2845,42 @@ The redirection lasts until @code{redirect-frame-focus} is called to change it. @end defun -@defvar focus-in-hook -This is a normal hook run when an Emacs frame gains input focus. The -frame gaining focus is selected when this hook is run. -@end defvar +@defun frame-focus-state frame +This function retrieves the last known focus state of @var{frame}. + +It returns @code{nil} if the frame is known not to be focused, +@code{t} if the frame is known to be focused, or @code{unknown} if +Emacs does not know the focus state of the frame. (You may see this +last state in TTY frames running on terminals that do not support +explicit focus notifications.) +@end defun -@defvar focus-out-hook -This is a normal hook run when an Emacs frame has lost input focus and -no other Emacs frame has gained input focus instead. +@defvar after-focus-change-function +This function is an extension point that code can use to receive a +notification that focus has changed. + +This function is called with no arguments when Emacs notices that the +set of focused frames may have changed. Code wanting to do something +when frame focus changes should use @code{add-function} to add a +function to this one, and in this added function, re-scan the set of +focused frames, calling @code{frame-focus-state} to retrieve the last +known focus state of each frame. Focus events are delivered +asynchronously, and frame input focus according to an external system +may not correspond to the notion of the Emacs selected frame. +Multiple frames may appear to have input focus simultaneously due to +focus event delivery differences, the presence of multiple Emacs +terminals, and other factors, and code should be robust in the face of +this situation. + +Depending on window system, focus events may also be delivered +repeatedly and with different focus states before settling to the +expected values. Code relying on focus notifications should +``debounce'' any user-visible updates arising from focus changes, +perhaps by deferring work until redisplay. + +This function may be called in arbitrary contexts, including from +inside @code{read-event}, so take the same care as you might when +writing a process filter. @end defvar @defopt focus-follows-mouse diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index d01804e4940..222f863c988 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -371,8 +371,8 @@ keyword @code{&rest} before one final argument. @example @group (@var{required-vars}@dots{} - @r{[}&optional @var{optional-vars}@dots{}@r{]} - @r{[}&rest @var{rest-var}@r{]}) + @r{[}&optional @r{[}@var{optional-vars}@dots{}@r{]}@r{]} + @r{[}&rest @r{[}@var{rest-var}@r{]}@r{]}) @end group @end example @@ -1242,7 +1242,7 @@ This form defines a method like @code{cl-defmethod} does. @end table @end defmac -@defmac cl-defmethod name [qualifier] arguments &rest [docstring] body +@defmac cl-defmethod name [qualifier] arguments [&context (expr spec)@dots{}] &rest [docstring] body This macro defines a particular implementation for the generic function called @var{name}. The implementation code is given by @var{body}. If present, @var{docstring} is the documentation string @@ -1269,15 +1269,20 @@ defined with @code{cl-defstruct} (@pxref{Structures,,, cl, Common Lisp Extensions for GNU Emacs Lisp}), or of one of its child classes. @end table -Alternatively, the argument specializer can be of the form -@code{&context (@var{expr} @var{spec})}, in which case the value of -@var{expr} must be compatible with the specializer provided by -@var{spec}; @var{spec} can be any of the forms described above. In -other words, this form of specializer uses the value of @var{expr} -instead of arguments for the decision whether the method is -applicable. For example, @code{&context (overwrite-mode (eql t))} -will make the method compatible only when @code{overwrite-mode} is -turned on. +Method definitions can make use of a new argument-list keyword, +@code{&context}, which introduces extra specializers that test the +environment at the time the method is run. This keyword should appear +after the list of required arguments, but before any @code{&rest} or +@code{&optional} keywords. The @code{&context} specializers look much +like regular argument specializers---(@var{expr} @var{spec})---except +that @var{expr} is an expression to be evaluated in the current +context, and the @var{spec} is a value to compare against. For +example, @code{&context (overwrite-mode (eql t))} will make the method +applicable only when @code{overwrite-mode} is turned on. The +@code{&context} keyword can be followed by any number of context +specializers. Because the context specializers are not part of the +generic function's argument signature, they may be omitted in methods +that don't require them. The type specializer, @code{(@var{arg} @var{type})}, can specify one of the @dfn{system types} in the following list. When a parent type diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi index d5c9948ca73..5aaf31247b4 100644 --- a/doc/lispref/hash.texi +++ b/doc/lispref/hash.texi @@ -300,8 +300,8 @@ the same integer. @defun sxhash-eql obj This function returns a hash code for Lisp object @var{obj} suitable for @code{eql} comparison. I.e. it reflects identity of @var{obj} -except for the case where the object is a float number, in which case -hash code is generated for the value. +except for the case where the object is a bignum or a float number, +in which case a hash code is generated for the value. If two objects @var{obj1} and @var{obj2} are @code{eql}, then @code{(sxhash-eql @var{obj1})} and @code{(sxhash-eql @var{obj2})} are diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi index 7c8748b5e48..71992464e09 100644 --- a/doc/lispref/hooks.texi +++ b/doc/lispref/hooks.texi @@ -66,6 +66,7 @@ not exactly a hook, but does a similar job. @item after-make-frame-functions @itemx before-make-frame-hook +@itemx server-after-make-frame-hook @xref{Creating Frames}. @c Not general enough? @@ -123,6 +124,7 @@ The command loop runs this soon after @code{post-command-hook} (q.v.). @xref{Input Focus}. @item delete-frame-functions +@itemx after-delete-frame-functions @xref{Deleting Frames}. @item delete-terminal-functions diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 38d84f149e0..d7c1fb7e422 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -247,8 +247,8 @@ of 8k bytes, and small vectors are packed into blocks of 4k bytes). @cindex vector-like objects, storage @cindex storage of vector-like Lisp objects - Beyond the basic vector, a lot of objects like window, buffer, and -frame are managed as if they were vectors. The corresponding C data + Beyond the basic vector, a lot of objects like markers, overlays and +buffers are managed as if they were vectors. The corresponding C data structures include the @code{union vectorlike_header} field whose @code{size} member contains the subtype enumerated by @code{enum pvec_type} and an information about how many @code{Lisp_Object} fields this structure @@ -319,7 +319,6 @@ future allocations. So an overall result is: @example ((@code{conses} @var{cons-size} @var{used-conses} @var{free-conses}) (@code{symbols} @var{symbol-size} @var{used-symbols} @var{free-symbols}) - (@code{miscs} @var{misc-size} @var{used-miscs} @var{free-miscs}) (@code{strings} @var{string-size} @var{used-strings} @var{free-strings}) (@code{string-bytes} @var{byte-size} @var{used-bytes}) (@code{vectors} @var{vector-size} @var{used-vectors}) @@ -335,7 +334,7 @@ Here is an example: @example (garbage-collect) @result{} ((conses 16 49126 8058) (symbols 48 14607 0) - (miscs 40 34 56) (strings 32 2942 2607) + (strings 32 2942 2607) (string-bytes 1 78607) (vectors 16 7247) (vector-slots 8 341609 29474) (floats 8 71 102) (intervals 56 27 26) (buffers 944 8) @@ -367,19 +366,6 @@ The number of symbols in use. The number of symbols for which space has been obtained from the operating system, but that are not currently being used. -@item misc-size -Internal size of a miscellaneous entity, i.e., -@code{sizeof (union Lisp_Misc)}, which is a size of the -largest type enumerated in @code{enum Lisp_Misc_Type}. - -@item used-miscs -The number of miscellaneous objects in use. These include markers -and overlays, plus certain objects not visible to users. - -@item free-miscs -The number of miscellaneous objects for which space has been obtained -from the operating system, but that are not currently being used. - @item string-size Internal size of a string header, i.e., @code{sizeof (struct Lisp_String)}. @@ -397,7 +383,7 @@ This is used for convenience and equals to @code{sizeof (char)}. The total size of all string data in bytes. @item vector-size -Internal size of a vector header, i.e., @code{sizeof (struct Lisp_Vector)}. +Size in bytes of a vector of length 1, including its header. @item used-vectors The number of vector headers allocated from the vector blocks. @@ -407,6 +393,8 @@ Internal size of a vector slot, always equal to @code{sizeof (Lisp_Object)}. @item used-slots The number of slots in all used vectors. +Slot counts might include some or all overhead from vector headers, +depending on the platform. @item free-slots The number of free slots in all vector blocks. @@ -508,10 +496,8 @@ function @code{memory-limit} provides information on the total amount of memory Emacs is currently using. @defun memory-limit -This function returns the address of the last byte Emacs has allocated, -divided by 1024. We divide the value by 1024 to make sure it fits in a -Lisp integer. - +This function returns an estimate of the total amount of bytes of +virtual memory that Emacs is currently using, divided by 1024. You can use this to get a general idea of how your actions affect the memory usage. @end defun @@ -596,6 +582,8 @@ in this Emacs session. @defvar vector-cells-consed The total number of vector cells that have been allocated so far in this Emacs session. +This includes vector-like objects such as markers and overlays, plus +certain objects not visible to users. @end defvar @defvar symbols-consed @@ -608,12 +596,6 @@ The total number of string characters that have been allocated so far in this session. @end defvar -@defvar misc-objects-consed -The total number of miscellaneous objects that have been allocated so -far in this session. These include markers and overlays, plus -certain objects not visible to users. -@end defvar - @defvar intervals-consed The total number of intervals that have been allocated so far in this Emacs session. @@ -760,6 +742,13 @@ names in the documentation string from the ones used in the C code. @samp{usage:} is required if the function has an unlimited number of arguments. +Some primitives have multiple definitions, one per platform (e.g., +@code{x-create-frame}). In such cases, rather than writing the +same documentation string in each definition, only one definition has +the actual documentation. The others have placeholders beginning with +@samp{SKIP}, which are ignored by the function that parses the +@file{DOC} file. + All the usual rules for documentation strings in Lisp code (@pxref{Documentation Tips}) apply to C code documentation strings too. @@ -1699,7 +1688,7 @@ a special type to represent the pointers to all of them, which is known as In C, the tagged pointer is an object of type @code{Lisp_Object}. Any initialized variable of such a type always holds the value of one of the following basic data types: integer, symbol, string, cons cell, float, -vectorlike or miscellaneous object. Each of these data types has the +or vectorlike object. Each of these data types has the corresponding tag value. All tags are enumerated by @code{enum Lisp_Type} and placed into a 3-bit bitfield of the @code{Lisp_Object}. The rest of the bits is the value itself. Integers are immediate, i.e., directly @@ -1731,18 +1720,13 @@ Symbol, the unique-named entity commonly used as an identifier. @item struct Lisp_Float Floating-point value. - -@item union Lisp_Misc -Miscellaneous kinds of objects which don't fit into any of the above. @end table These types are the first-class citizens of an internal type system. -Since the tag space is limited, all other types are the subtypes of either -@code{Lisp_Vectorlike} or @code{Lisp_Misc}. Vector subtypes are enumerated +Since the tag space is limited, all other types are the subtypes of +@code{Lisp_Vectorlike}. Vector subtypes are enumerated by @code{enum pvec_type}, and nearly all complex objects like windows, buffers, -frames, and processes fall into this category. The rest of special types, -including markers and overlays, are enumerated by @code{enum Lisp_Misc_Type} -and form the set of subtypes of @code{Lisp_Misc}. +frames, and processes fall into this category. Below there is a description of a few subtypes of @code{Lisp_Vectorlike}. Buffer object represents the text to display and edit. Window is the part diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index 2b5f7905258..2596e87939b 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi @@ -493,7 +493,7 @@ giving a prefix argument makes @var{here} non-@code{nil}. @defvar emacs-build-time The value of this variable indicates the time at which Emacs was -built. It is a list of four integers, like the value of +built. It uses the style of @code{current-time} (@pxref{Time of Day}), or is @code{nil} if the information is not available. @@ -530,6 +530,18 @@ directory (without cleaning). This is only of relevance when developing Emacs. @end defvar +@defvar emacs-repository-version +A string that gives the repository revision from which Emacs was +built. If Emacs was built outside revision control, the value is +@code{nil}. +@end defvar + +@defvar emacs-repository-branch +A string that gives the repository branch from which Emacs was built. +In the most cases this is @code{"master"}. If Emacs was built outside +revision control, the value is @code{nil}. +@end defvar + @node Acknowledgments @section Acknowledgments diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index ccc75a9c7af..cc0386c8fc7 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -1660,7 +1660,7 @@ to turn the character that follows into a Hyper character: (defun hyperify (prompt) (let ((e (read-event))) (vector (if (numberp e) - (logior (lsh 1 24) e) + (logior (ash 1 24) e) (if (memq 'hyper (event-modifiers e)) e (add-event-modifier "H-" e)))))) @@ -2443,7 +2443,7 @@ Next we define the menu items: @smallexample (define-key menu-bar-replace-menu [tags-repl-continue] - '(menu-item "Continue Replace" tags-loop-continue + '(menu-item "Continue Replace" multifile-continue :help "Continue last tags replace operation")) (define-key menu-bar-replace-menu [tags-repl] '(menu-item "Replace in tagged files" tags-query-replace diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 615f21581aa..746b4643c18 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -156,6 +156,22 @@ considered a list and @code{not} when it is considered a truth value @end example @end defun +@defun proper-list-p object +This function returns the length of @var{object} if it is a proper +list, @code{nil} otherwise (@pxref{Cons Cells}). In addition to +satisfying @code{listp}, a proper list is neither circular nor dotted. + +@example +@group +(proper-list-p '(a b c)) + @result{} 3 +@end group +@group +(proper-list-p '(a b . c)) + @result{} nil +@end group +@end example +@end defun @node List Elements @section Accessing Elements of Lists @@ -651,8 +667,20 @@ non-@code{nil}, it copies vectors too (and operates recursively on their elements). @end defun +@defun flatten-tree tree +This function returns a ``flattened'' copy of @var{tree}, that is, +a list containing all the non-@code{nil} terminal nodes, or leaves, of +the tree of cons cells rooted at @var{tree}. Leaves in the returned +list are in the same order as in @var{tree}. +@end defun + +@example +(flatten-tree '(1 (2 . 3) nil (4 5 (6)) 7)) + @result{}(1 2 3 4 5 6 7) +@end example + @defun number-sequence from &optional to separation -This returns a list of numbers starting with @var{from} and +This function returns a list of numbers starting with @var{from} and incrementing by @var{separation}, and ending at or just before @var{to}. @var{separation} can be positive or negative and defaults to 1. If @var{to} is @code{nil} or numerically equal to @var{from}, @@ -1144,7 +1172,7 @@ each time you run it! Here is what happens: @group (symbol-function 'add-foo) - @result{} (lambda (x) (nconc (quote (foo)) x)) + @result{} (lambda (x) (nconc '(foo) x)) @end group @group @@ -1162,7 +1190,7 @@ each time you run it! Here is what happens: @group (symbol-function 'add-foo) - @result{} (lambda (x) (nconc (quote (foo 1 2 3 4) x))) + @result{} (lambda (x) (nconc '(foo 1 2 3 4) x)) @end group @end smallexample @end defun @@ -1736,11 +1764,12 @@ alist @end example @end defun -@defun assoc-delete-all key alist -This function deletes from @var{alist} all the elements whose @sc{car} -is @code{equal} to @var{key}. It works like @code{assq-delete-all}, -except for the predicate used for comparing alist elements with -@var{key}. +@defun assoc-delete-all key alist &optional test +This function is like @code{assq-delete-all} except that it accepts +an optional argument @var{test}, a predicate function to compare the +keys in @var{alist}. If omitted or @code{nil}, @var{test} defaults to +@code{equal}. As @code{assq-delete-all}, this function often modifies +the original list structure of @var{alist}. @end defun @defun rassq-delete-all value alist diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index f0cc689d1f6..6f1213f097b 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -641,7 +641,7 @@ autoloading with a magic comment: Here's what that produces in @file{loaddefs.el}: @example -(autoload (quote doctor) "doctor" "\ +(autoload 'doctor "doctor" "\ Switch to *doctor* buffer and start giving psychotherapy. \(fn)" t nil) diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 0c0862160bf..766079d7bcd 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -634,6 +634,12 @@ A history list for arguments that are Lisp expressions to evaluate. A history list for arguments that are faces. @end defvar +@findex read-variable@r{, history list} +@defvar custom-variable-history +A history list for variable-name arguments read by +@code{read-variable}. +@end defvar + @c Less common: coding-system-history, input-method-history, @c command-history, grep-history, grep-find-history, @c read-envvar-name-history, setenv-history, yes-or-no-p-history. @@ -2240,7 +2246,7 @@ function @code{read-passwd}. @defun read-passwd prompt &optional confirm default This function reads a password, prompting with @var{prompt}. It does not echo the password as the user types it; instead, it echoes -@samp{.} for each character in the password. If you want to apply +@samp{*} for each character in the password. If you want to apply another character to hide the password, let-bind the variable @code{read-hide-char} with that character. @@ -2503,7 +2509,7 @@ locally inside the minibuffer (@pxref{Help Functions}). @anchor{Definition of minibuffer-scroll-window} If the value of this variable is non-@code{nil}, it should be a window object. When the function @code{scroll-other-window} is called in the -minibuffer, it scrolls this window. +minibuffer, it scrolls this window (@pxref{Textual Scrolling}). @end defvar @defun minibuffer-selected-window diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 9df1a69e907..143cc7c5827 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -197,6 +197,7 @@ from the buffer-local hook list instead of from the global hook list. @cindex major mode @cindex major mode command +@cindex suspend major mode temporarily Major modes specialize Emacs for editing or interacting with particular kinds of text. Each buffer has exactly one major mode at a time. Every major mode is associated with a @dfn{major mode command}, @@ -205,7 +206,8 @@ switching to that mode in the current buffer, by setting various buffer-local variables such as a local keymap. @xref{Major Mode Conventions}. Note that unlike minor modes there is no way to ``turn off'' a major mode, instead the buffer must be switched to a different -one. +one. However, you can temporarily @dfn{suspend} a major mode and later +@dfn{restore} the suspended mode, see below. The least specialized major mode is called @dfn{Fundamental mode}, which has no mode-specific definitions or variable settings. @@ -216,6 +218,24 @@ commands, it does @emph{not} run any mode hooks (@pxref{Major Mode Conventions}), since you are not supposed to customize this mode. @end deffn +@defun major-mode-suspend +This function works like @code{fundamental-mode}, in that it kills all +buffer-local variables, but it also records the major mode in effect, +so that it could subsequently be restored. This function and +@code{major-mode-restore} (described next) are useful when you need to +put a buffer under some specialized mode other than the one Emacs +chooses for it automatically (@pxref{Auto Major Mode}), but would also +like to be able to switch back to the original mode later. +@end defun + +@defun major-mode-restore &optional avoided-modes +This function restores the major mode recorded by +@code{major-mode-suspend}. If no major mode was recorded, this +function calls @code{normal-mode} (@pxref{Auto Major Mode, +normal-mode}), but tries to force it not to choose any modes in +@var{avoided-modes}, if that argument is non-@code{nil}. +@end defun + The easiest way to write a major mode is to use the macro @code{define-derived-mode}, which sets up the new mode as a variant of an existing major mode. @xref{Derived Modes}. We recommend using diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index ab15ea7d9b2..c734a994a07 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -829,18 +829,18 @@ two functions support these conversions. This function decodes a character that is assigned a @var{code-point} in @var{charset}, to the corresponding Emacs character, and returns it. If @var{charset} doesn't contain a character of that code point, -the value is @code{nil}. If @var{code-point} doesn't fit in a Lisp -integer (@pxref{Integer Basics, most-positive-fixnum}), it can be +the value is @code{nil}. + +For backward compatibility, if @var{code-point} doesn't fit in a Lisp +fixnum (@pxref{Integer Basics, most-positive-fixnum}), it can be specified as a cons cell @code{(@var{high} . @var{low})}, where @var{low} are the lower 16 bits of the value and @var{high} are the -high 16 bits. +high 16 bits. This usage is obsolescent. @end defun @defun encode-char char charset This function returns the code point assigned to the character -@var{char} in @var{charset}. If the result does not fit in a Lisp -integer, it is returned as a cons cell @code{(@var{high} . @var{low})} -that fits the second argument of @code{decode-char} above. If +@var{char} in @var{charset}. If @var{charset} doesn't have a codepoint for @var{char}, the value is @code{nil}. @end defun diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index e7beed0073d..cffc634169f 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -14,9 +14,9 @@ fractional parts, such as @minus{}4.5, 0.0, and 2.71828. They can also be expressed in exponential notation: @samp{1.5e2} is the same as @samp{150.0}; here, @samp{e2} stands for ten to the second power, and -that is multiplied by 1.5. Integer computations are exact, though -they may overflow. Floating-point computations often involve rounding -errors, as the numbers have a fixed amount of precision. +that is multiplied by 1.5. Integer computations are exact. +Floating-point computations often involve rounding errors, as the +numbers have a fixed amount of precision. @menu * Integer Basics:: Representation and range of integers. @@ -34,7 +34,23 @@ errors, as the numbers have a fixed amount of precision. @node Integer Basics @section Integer Basics - The range of values for an integer depends on the machine. The + Integers in Emacs Lisp are not limited to the machine word size. + + Under the hood, though, there are two kinds of integers: smaller +ones, called @dfn{fixnums}, and larger ones, called @dfn{bignums}. +Some functions in Emacs accept only fixnums. Also, while fixnums can +always be compared for numeric equality with @code{eq}, bignums +require more-heavyweight equality predicates like @code{eql}. + + The range of values for bignums is limited by the amount of main +memory, by machine characteristics such as the size of the word used +to represent a bignum's exponent, and by the @code{integer-width} +variable. These limits are typically much more generous than the +limits for fixnums. A bignum is never numerically equal to a fixnum; +if Emacs computes an integer in fixnum range, it represents the +integer as a fixnum, not a bignum. + + The range of values for a fixnum depends on the machine. The minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e., @ifnottex @minus{}2**29 @@ -49,21 +65,17 @@ to @tex @math{2^{29}-1}), @end tex -but many machines provide a wider range. Many examples in this -chapter assume the minimum integer width of 30 bits. -@cindex overflow +but many machines provide a wider range. - The Lisp reader reads an integer as a sequence of digits with optional -initial sign and optional final period. An integer that is out of the -Emacs range is treated as a floating-point number. + The Lisp reader reads an integer as a nonempty sequence +of decimal digits with optional initial sign and optional +final period. @example 1 ; @r{The integer 1.} 1. ; @r{The integer 1.} +1 ; @r{Also the integer 1.} -1 ; @r{The integer @minus{}1.} - 9000000000000000000 - ; @r{The floating-point number 9e18.} 0 ; @r{The integer 0.} -0 ; @r{The integer 0.} @end example @@ -74,14 +86,17 @@ Emacs range is treated as a floating-point number. @cindex hex numbers @cindex octal numbers @cindex reading numbers in hex, octal, and binary - The syntax for integers in bases other than 10 uses @samp{#} -followed by a letter that specifies the radix: @samp{b} for binary, -@samp{o} for octal, @samp{x} for hex, or @samp{@var{radix}r} to -specify radix @var{radix}. Case is not significant for the letter -that specifies the radix. Thus, @samp{#b@var{integer}} reads + The syntax for integers in bases other than 10 consists of @samp{#} +followed by a radix indication followed by one or more digits. The +radix indications are @samp{b} for binary, @samp{o} for octal, +@samp{x} for hex, and @samp{@var{radix}r} for radix @var{radix}. +Thus, @samp{#b@var{integer}} reads @var{integer} in binary, and @samp{#@var{radix}r@var{integer}} reads @var{integer} in radix @var{radix}. Allowed values of @var{radix} run -from 2 to 36. For example: +from 2 to 36, and allowed digits are the first @var{radix} characters +taken from @samp{0}--@samp{9}, @samp{A}--@samp{Z}. +Letter case is ignored and there is no initial sign or final period. +For example: @example #b101100 @result{} 44 @@ -94,26 +109,26 @@ from 2 to 36. For example: bitwise operators (@pxref{Bitwise Operations}), it is often helpful to view the numbers in their binary form. - In 30-bit binary, the decimal integer 5 looks like this: + In binary, the decimal integer 5 looks like this: @example -0000...000101 (30 bits total) +@dots{}000101 @end example @noindent -(The @samp{...} stands for enough bits to fill out a 30-bit word; in -this case, @samp{...} stands for twenty 0 bits. Later examples also -use the @samp{...} notation to make binary integers easier to read.) +(The ellipsis @samp{@dots{}} stands for a conceptually infinite number +of bits that match the leading bit; here, an infinite number of 0 +bits. Later examples also use this @samp{@dots{}} notation.) The integer @minus{}1 looks like this: @example -1111...111111 (30 bits total) +@dots{}111111 @end example @noindent @cindex two's complement -@minus{}1 is represented as 30 ones. (This is called @dfn{two's +@minus{}1 is represented as all ones. (This is called @dfn{two's complement} notation.) Subtracting 4 from @minus{}1 returns the negative integer @minus{}5. @@ -121,24 +136,7 @@ In binary, the decimal integer 4 is 100. Consequently, @minus{}5 looks like this: @example -1111...111011 (30 bits total) -@end example - - In this implementation, the largest 30-bit binary integer is -536,870,911 in decimal. In binary, it looks like this: - -@example -0111...111111 (30 bits total) -@end example - - Since the arithmetic functions do not check whether integers go -outside their range, when you add 1 to 536,870,911, the value is the -negative integer @minus{}536,870,912: - -@example -(+ 1 536870911) - @result{} -536870912 - @result{} 1000...000000 (30 bits total) +@dots{}111011 @end example Many of the functions described in this chapter accept markers for @@ -147,11 +145,11 @@ arguments to such functions may be either numbers or markers, we often give these arguments the name @var{number-or-marker}. When the argument value is a marker, its position value is used and its buffer is ignored. -@cindex largest Lisp integer -@cindex maximum Lisp integer +@cindex largest fixnum +@cindex maximum fixnum @defvar most-positive-fixnum -The value of this variable is the largest integer that Emacs Lisp can -handle. Typical values are +The value of this variable is the greatest ``small'' integer that Emacs +Lisp can handle. Typical values are @ifnottex 2**29 @minus{} 1 @end ifnottex @@ -168,11 +166,11 @@ on 32-bit and on 64-bit platforms. @end defvar -@cindex smallest Lisp integer -@cindex minimum Lisp integer +@cindex smallest fixnum +@cindex minimum fixnum @defvar most-negative-fixnum -The value of this variable is the smallest integer that Emacs Lisp can -handle. It is negative. Typical values are +The value of this variable is the numerically least ``small'' integer +that Emacs Lisp can handle. It is negative. Typical values are @ifnottex @minus{}2**29 @end ifnottex @@ -189,6 +187,26 @@ on 32-bit and on 64-bit platforms. @end defvar +@cindex bignum range +@cindex integer range +@cindex number of bignum bits, limit on +@defvar integer-width +The value of this variable is a nonnegative integer that is an upper +bound on the number of bits in a bignum. Integers outside the fixnum +range are limited to absolute values less than +@ifnottex +2**@var{n}, +@end ifnottex +@tex +@math{2^{n}}, +@end tex +where @var{n} is this variable's value. Attempts to create bignums outside +this range signal a range error. Setting this variable +to zero disables creation of bignums; setting it to a large number can +cause Emacs to consume large quantities of memory if a computation +creates huge integers. +@end defvar + In Emacs Lisp, text characters are represented by integers. Any integer between zero and the value of @code{(max-char)}, inclusive, is considered to be valid as a character. @xref{Character Codes}. @@ -213,7 +231,7 @@ least one digit after any decimal point in a floating-point number; @samp{1500.} is an integer, not a floating-point number. Emacs Lisp treats @code{-0.0} as numerically equal to ordinary zero -with respect to @code{equal} and @code{=}. This follows the +with respect to numeric comparisons like @code{=}. This follows the @acronym{IEEE} floating-point standard, which says @code{-0.0} and @code{0.0} are numerically equal even though other operations can distinguish them. @@ -227,8 +245,20 @@ infinity and negative infinity as floating-point values. It also provides for a class of values called NaN, or ``not a number''; numerical functions return such values in cases where there is no correct answer. For example, @code{(/ 0.0 0.0)} returns a NaN@. -Although NaN values carry a sign, for practical purposes there is no other -significant difference between different NaN values in Emacs Lisp. +A NaN is never numerically equal to any value, not even to itself. +NaNs carry a sign and a significand, and non-numeric functions treat +two NaNs as equal when their +signs and significands agree. Significands of NaNs are +machine-dependent, as are the digits in their string representation. + + When NaNs and signed zeros are involved, non-numeric functions like +@code{eql}, @code{equal}, @code{sxhash-eql}, @code{sxhash-equal} and +@code{gethash} determine whether values are indistinguishable, not +whether they are numerically equal. For example, when @var{x} and +@var{y} are the same NaN, @code{(equal x y)} returns @code{t} whereas +@code{(= x y)} uses numeric comparison and returns @code{nil}; +conversely, @code{(equal 0.0 -0.0)} returns @code{nil} whereas +@code{(= 0.0 -0.0)} returns @code{t}. Here are read syntaxes for these special floating-point values: @@ -305,6 +335,18 @@ use otherwise), but the @code{zerop} predicate requires a number as its argument. See also @code{integer-or-marker-p} and @code{number-or-marker-p}, in @ref{Predicates on Markers}. +@defun bignump object +This predicate tests whether its argument is a large integer, and +returns @code{t} if so, @code{nil} otherwise. Unlike small integers, +large integers can be @code{=} or @code{eql} even if they are not @code{eq}. +@end defun + +@defun fixnump object +This predicate tests whether its argument is a small integer, and +returns @code{t} if so, @code{nil} otherwise. Small integers can be +compared with @code{eq}. +@end defun + @defun floatp object This predicate tests whether its argument is floating point and returns @code{t} if so, @code{nil} otherwise. @@ -344,23 +386,27 @@ if so, @code{nil} otherwise. The argument must be a number. @cindex comparing numbers To test numbers for numerical equality, you should normally use -@code{=}, not @code{eq}. There can be many distinct floating-point -objects with the same numeric value. If you use @code{eq} to -compare them, then you test whether two values are the same -@emph{object}. By contrast, @code{=} compares only the numeric values -of the objects. - - In Emacs Lisp, each integer is a unique Lisp object. -Therefore, @code{eq} is equivalent to @code{=} where integers are -concerned. It is sometimes convenient to use @code{eq} for comparing -an unknown value with an integer, because @code{eq} does not report an +@code{=} instead of non-numeric comparison predicates like @code{eq}, +@code{eql} and @code{equal}. Distinct floating-point and large +integer objects can be numerically equal. If you use @code{eq} to +compare them, you test whether they are the same @emph{object}; if you +use @code{eql} or @code{equal}, you test whether their values are +@emph{indistinguishable}. In contrast, @code{=} uses numeric +comparison, and sometimes returns @code{t} when a non-numeric +comparison would return @code{nil} and vice versa. @xref{Float +Basics}. + + In Emacs Lisp, if two fixnums are numerically equal, they are the +same Lisp object. That is, @code{eq} is equivalent to @code{=} on +fixnums. It is sometimes convenient to use @code{eq} for comparing +an unknown value with a fixnum, because @code{eq} does not report an error if the unknown value is not a number---it accepts arguments of any type. By contrast, @code{=} signals an error if the arguments are not numbers or markers. However, it is better programming practice to use @code{=} if you can, even for comparing integers. - Sometimes it is useful to compare numbers with @code{equal}, which -treats two numbers as equal if they have the same data type (both + Sometimes it is useful to compare numbers with @code{eql} or @code{equal}, +which treat two numbers as equal if they have the same data type (both integers, or both floating point) and the same value. By contrast, @code{=} can treat an integer and a floating-point number as equal. @xref{Equality Predicates}. @@ -379,15 +425,6 @@ Here's a function to do this: fuzz-factor))) @end example -@cindex CL note---integers vrs @code{eq} -@quotation -@b{Common Lisp note:} Comparing numbers in Common Lisp always requires -@code{=} because Common Lisp implements multi-word integers, and two -distinct integer objects can have the same numeric value. Emacs Lisp -can have just one integer object for any given value because it has a -limited range of integers. -@end quotation - @defun = number-or-marker &rest number-or-markers This function tests whether all its arguments are numerically equal, and returns @code{t} if so, @code{nil} otherwise. @@ -397,7 +434,8 @@ and returns @code{t} if so, @code{nil} otherwise. This function acts like @code{eq} except when both arguments are numbers. It compares numbers by type and numeric value, so that @code{(eql 1.0 1)} returns @code{nil}, but @code{(eql 1.0 1.0)} and -@code{(eql 1 1)} both return @code{t}. +@code{(eql 1 1)} both return @code{t}. This can be used to compare +large integers as well as small ones. @end defun @defun /= number-or-marker1 number-or-marker2 @@ -557,10 +595,6 @@ Except for @code{%}, each of these functions accepts both integer and floating-point arguments, and returns a floating-point number if any argument is floating point. - Emacs Lisp arithmetic functions do not check for integer overflow. -Thus @code{(1+ 536870911)} may evaluate to -@minus{}536870912, depending on your hardware. - @defun 1+ number-or-marker This function returns @var{number-or-marker} plus 1. For example, @@ -814,181 +848,119 @@ Rounding a value equidistant between two integers returns the even integer. @cindex logical arithmetic In a computer, an integer is represented as a binary number, a -sequence of @dfn{bits} (digits which are either zero or one). A bitwise +sequence of @dfn{bits} (digits which are either zero or one). +Conceptually the bit sequence is infinite on the left, with the +most-significant bits being all zeros or all ones. A bitwise operation acts on the individual bits of such a sequence. For example, @dfn{shifting} moves the whole sequence left or right one or more places, reproducing the same pattern moved over. The bitwise operations in Emacs Lisp apply only to integers. -@defun lsh integer1 count -@cindex logical shift -@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the -bits in @var{integer1} to the left @var{count} places, or to the right -if @var{count} is negative, bringing zeros into the vacated bits. If -@var{count} is negative, @code{lsh} shifts zeros into the leftmost -(most-significant) bit, producing a positive result even if -@var{integer1} is negative. Contrast this with @code{ash}, below. +@defun ash integer1 count +@cindex arithmetic shift +@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} +to the left @var{count} places, or to the right if @var{count} is +negative. Left shifts introduce zero bits on the right; right shifts +discard the rightmost bits. Considered as an integer operation, +@code{ash} multiplies @var{integer1} by +@ifnottex +2**@var{count}, +@end ifnottex +@tex +@math{2^{count}}, +@end tex +and then converts the result to an integer by rounding downward, toward +minus infinity. -Here are two examples of @code{lsh}, shifting a pattern of bits one -place to the left. We show only the low-order eight bits of the binary -pattern; the rest are all zero. +Here are examples of @code{ash}, shifting a pattern of bits one place +to the left and to the right. These examples show only the low-order +bits of the binary pattern; leading bits all agree with the +highest-order bit shown. As you can see, shifting left by one is +equivalent to multiplying by two, whereas shifting right by one is +equivalent to dividing by two and then rounding toward minus infinity. @example @group -(lsh 5 1) - @result{} 10 -;; @r{Decimal 5 becomes decimal 10.} -00000101 @result{} 00001010 - -(lsh 7 1) - @result{} 14 +(ash 7 1) @result{} 14 ;; @r{Decimal 7 becomes decimal 14.} -00000111 @result{} 00001110 +@dots{}000111 + @result{} +@dots{}001110 @end group -@end example - -@noindent -As the examples illustrate, shifting the pattern of bits one place to -the left produces a number that is twice the value of the previous -number. - -Shifting a pattern of bits two places to the left produces results -like this (with 8-bit binary numbers): -@example @group -(lsh 3 2) - @result{} 12 -;; @r{Decimal 3 becomes decimal 12.} -00000011 @result{} 00001100 +(ash 7 -1) @result{} 3 +@dots{}000111 + @result{} +@dots{}000011 @end group -@end example -On the other hand, shifting one place to the right looks like this: - -@example @group -(lsh 6 -1) - @result{} 3 -;; @r{Decimal 6 becomes decimal 3.} -00000110 @result{} 00000011 +(ash -7 1) @result{} -14 +@dots{}111001 + @result{} +@dots{}110010 @end group @group -(lsh 5 -1) - @result{} 2 -;; @r{Decimal 5 becomes decimal 2.} -00000101 @result{} 00000010 +(ash -7 -1) @result{} -4 +@dots{}111001 + @result{} +@dots{}111100 @end group @end example -@noindent -As the example illustrates, shifting one place to the right divides the -value of a positive integer by two, rounding downward. +Here are examples of shifting left or right by two bits: -The function @code{lsh}, like all Emacs Lisp arithmetic functions, does -not check for overflow, so shifting left can discard significant bits -and change the sign of the number. For example, left shifting -536,870,911 produces @minus{}2 in the 30-bit implementation: - -@example -(lsh 536870911 1) ; @r{left shift} - @result{} -2 -@end example - -In binary, the argument looks like this: - -@example +@smallexample @group -;; @r{Decimal 536,870,911} -0111...111111 (30 bits total) + ; @r{ binary values} +(ash 5 2) ; 5 = @r{@dots{}000101} + @result{} 20 ; = @r{@dots{}010100} +(ash -5 2) ; -5 = @r{@dots{}111011} + @result{} -20 ; = @r{@dots{}101100} @end group -@end example - -@noindent -which becomes the following when left shifted: - -@example @group -;; @r{Decimal @minus{}2} -1111...111110 (30 bits total) +(ash 5 -2) + @result{} 1 ; = @r{@dots{}000001} @end group -@end example -@end defun - -@defun ash integer1 count -@cindex arithmetic shift -@code{ash} (@dfn{arithmetic shift}) shifts the bits in @var{integer1} -to the left @var{count} places, or to the right if @var{count} -is negative. - -@code{ash} gives the same results as @code{lsh} except when -@var{integer1} and @var{count} are both negative. In that case, -@code{ash} puts ones in the empty bit positions on the left, while -@code{lsh} puts zeros in those bit positions. - -Thus, with @code{ash}, shifting the pattern of bits one place to the right -looks like this: - -@example @group -(ash -6 -1) @result{} -3 -;; @r{Decimal @minus{}6 becomes decimal @minus{}3.} -1111...111010 (30 bits total) - @result{} -1111...111101 (30 bits total) +(ash -5 -2) + @result{} -2 ; = @r{@dots{}111110} @end group -@end example - -In contrast, shifting the pattern of bits one place to the right with -@code{lsh} looks like this: +@end smallexample +@end defun -@example -@group -(lsh -6 -1) @result{} 536870909 -;; @r{Decimal @minus{}6 becomes decimal 536,870,909.} -1111...111010 (30 bits total) - @result{} -0111...111101 (30 bits total) -@end group -@end example +@defun lsh integer1 count +@cindex logical shift +@code{lsh}, which is an abbreviation for @dfn{logical shift}, shifts the +bits in @var{integer1} to the left @var{count} places, or to the right +if @var{count} is negative, bringing zeros into the vacated bits. If +@var{count} is negative, then @var{integer1} must be either a fixnum +or a positive bignum, and @code{lsh} treats a negative fixnum as if it +were unsigned by subtracting twice @code{most-negative-fixnum} before +shifting, producing a nonnegative result. This quirky behavior dates +back to when Emacs supported only fixnums; nowadays @code{ash} is a +better choice. -Here are other examples: +As @code{lsh} behaves like @code{ash} except when @var{integer1} and +@var{count1} are both negative, the following examples focus on these +exceptional cases. These examples assume 30-bit fixnums. -@c !!! Check if lined up in smallbook format! XDVI shows problem -@c with smallbook but not with regular book! --rjc 16mar92 @smallexample @group - ; @r{ 30-bit binary values} - -(lsh 5 2) ; 5 = @r{0000...000101} - @result{} 20 ; = @r{0000...010100} + ; @r{ binary values} +(ash -7 -1) ; -7 = @r{@dots{}111111111111111111111111111001} + @result{} -4 ; = @r{@dots{}111111111111111111111111111100} +(lsh -7 -1) + @result{} 536870908 ; = @r{@dots{}011111111111111111111111111100} @end group @group -(ash 5 2) - @result{} 20 -(lsh -5 2) ; -5 = @r{1111...111011} - @result{} -20 ; = @r{1111...101100} -(ash -5 2) - @result{} -20 -@end group -@group -(lsh 5 -2) ; 5 = @r{0000...000101} - @result{} 1 ; = @r{0000...000001} -@end group -@group -(ash 5 -2) - @result{} 1 -@end group -@group -(lsh -5 -2) ; -5 = @r{1111...111011} - @result{} 268435454 - ; = @r{0011...111110} -@end group -@group -(ash -5 -2) ; -5 = @r{1111...111011} - @result{} -2 ; = @r{1111...111110} +(ash -5 -2) ; -5 = @r{@dots{}111111111111111111111111111011} + @result{} -2 ; = @r{@dots{}111111111111111111111111111110} +(lsh -5 -2) + @result{} 268435454 ; = @r{@dots{}001111111111111111111111111110} @end group @end smallexample @end defun @@ -1022,23 +994,23 @@ because its binary representation consists entirely of ones. If @smallexample @group - ; @r{ 30-bit binary values} + ; @r{ binary values} -(logand 14 13) ; 14 = @r{0000...001110} - ; 13 = @r{0000...001101} - @result{} 12 ; 12 = @r{0000...001100} +(logand 14 13) ; 14 = @r{@dots{}001110} + ; 13 = @r{@dots{}001101} + @result{} 12 ; 12 = @r{@dots{}001100} @end group @group -(logand 14 13 4) ; 14 = @r{0000...001110} - ; 13 = @r{0000...001101} - ; 4 = @r{0000...000100} - @result{} 4 ; 4 = @r{0000...000100} +(logand 14 13 4) ; 14 = @r{@dots{}001110} + ; 13 = @r{@dots{}001101} + ; 4 = @r{@dots{}000100} + @result{} 4 ; 4 = @r{@dots{}000100} @end group @group (logand) - @result{} -1 ; -1 = @r{1111...111111} + @result{} -1 ; -1 = @r{@dots{}111111} @end group @end smallexample @end defun @@ -1052,18 +1024,18 @@ passed just one argument, it returns that argument. @smallexample @group - ; @r{ 30-bit binary values} + ; @r{ binary values} -(logior 12 5) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - @result{} 13 ; 13 = @r{0000...001101} +(logior 12 5) ; 12 = @r{@dots{}001100} + ; 5 = @r{@dots{}000101} + @result{} 13 ; 13 = @r{@dots{}001101} @end group @group -(logior 12 5 7) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - ; 7 = @r{0000...000111} - @result{} 15 ; 15 = @r{0000...001111} +(logior 12 5 7) ; 12 = @r{@dots{}001100} + ; 5 = @r{@dots{}000101} + ; 7 = @r{@dots{}000111} + @result{} 15 ; 15 = @r{@dots{}001111} @end group @end smallexample @end defun @@ -1077,18 +1049,18 @@ result is 0, which is an identity element for this operation. If @smallexample @group - ; @r{ 30-bit binary values} + ; @r{ binary values} -(logxor 12 5) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - @result{} 9 ; 9 = @r{0000...001001} +(logxor 12 5) ; 12 = @r{@dots{}001100} + ; 5 = @r{@dots{}000101} + @result{} 9 ; 9 = @r{@dots{}001001} @end group @group -(logxor 12 5 7) ; 12 = @r{0000...001100} - ; 5 = @r{0000...000101} - ; 7 = @r{0000...000111} - @result{} 14 ; 14 = @r{0000...001110} +(logxor 12 5 7) ; 12 = @r{@dots{}001100} + ; 5 = @r{@dots{}000101} + ; 7 = @r{@dots{}000111} + @result{} 14 ; 14 = @r{@dots{}001110} @end group @end smallexample @end defun @@ -1101,9 +1073,27 @@ bit is one in the result if, and only if, the @var{n}th bit is zero in @example (lognot 5) @result{} -6 -;; 5 = @r{0000...000101} (30 bits total) +;; 5 = @r{@dots{}000101} ;; @r{becomes} -;; -6 = @r{1111...111010} (30 bits total) +;; -6 = @r{@dots{}111010} +@end example +@end defun + +@cindex popcount +@cindex Hamming weight +@cindex counting set bits +@defun logcount integer +This function returns the @dfn{Hamming weight} of @var{integer}: the +number of ones in the binary representation of @var{integer}. +If @var{integer} is negative, it returns the number of zero bits in +its two's complement binary representation. The result is always +nonnegative. + +@example +(logcount 43) ; 43 = @r{@dots{}000101011} + @result{} 4 +(logcount -43) ; -43 = @r{@dots{}111010101} + @result{} 3 @end example @end defun @@ -1189,8 +1179,8 @@ returns a NaN. @defun expt x y This function returns @var{x} raised to power @var{y}. If both -arguments are integers and @var{y} is positive, the result is an -integer; in this case, overflow causes truncation, so watch out. +arguments are integers and @var{y} is nonnegative, the result is an +integer; in this case, overflow signals an error, so watch out. If @var{x} is a finite negative number and @var{y} is a finite non-integer, @code{expt} returns a NaN. @end defun @@ -1241,11 +1231,10 @@ other strings to choose various seed values. This function returns a pseudo-random integer. Repeated calls return a series of pseudo-random integers. -If @var{limit} is a positive integer, the value is chosen to be +If @var{limit} is a positive fixnum, the value is chosen to be nonnegative and less than @var{limit}. Otherwise, the value might be -any integer representable in Lisp, i.e., an integer between -@code{most-negative-fixnum} and @code{most-positive-fixnum} -(@pxref{Integer Basics}). +any fixnum, i.e., any integer from @code{most-negative-fixnum} through +@code{most-positive-fixnum} (@pxref{Integer Basics}). If @var{limit} is @code{t}, it means to choose a new seed as if Emacs were restarting, typically from the system entropy. On systems diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 69b6c859f65..745baacc297 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -166,7 +166,10 @@ latter are unique to Emacs Lisp. @node Integer Type @subsection Integer Type - The range of values for an integer depends on the machine. The + Under the hood, there are two kinds of integers---small integers, +called @dfn{fixnums}, and large integers, called @dfn{bignums}. + + The range of values for a fixnum depends on the machine. The minimum range is @minus{}536,870,912 to 536,870,911 (30 bits; i.e., @ifnottex @minus{}2**29 @@ -182,8 +185,15 @@ to @math{2^{29}-1}) @end tex but many machines provide a wider range. -Emacs Lisp arithmetic functions do not check for integer overflow. Thus -@code{(1+ 536870911)} is @minus{}536,870,912 if Emacs integers are 30 bits. + + Bignums can have arbitrary precision. Operations that overflow a +fixnum will return a bignum instead. + + Fixnums can be compared with @code{eq}, but bignums require +@code{eql} or @code{=}. To test whether an integer is a fixnum or a +bignum, you can compare it to @code{most-negative-fixnum} and +@code{most-positive-fixnum}, or you can use the convenience predicates +@code{fixnump} and @code{bignump} on any object. The read syntax for integers is a sequence of (base ten) digits with an optional sign at the beginning and an optional period at the end. The @@ -200,11 +210,6 @@ leading @samp{+} or a final @samp{.}. @end example @noindent -As a special exception, if a sequence of digits specifies an integer -too large or too small to be a valid integer object, the Lisp reader -reads it as a floating-point number (@pxref{Floating-Point Type}). -For instance, if Emacs integers are 30 bits, @code{536870912} is read -as the floating-point number @code{536870912.0}. @xref{Numbers}, for more information. @@ -1895,6 +1900,9 @@ with references to further information. @item arrayp @xref{Array Functions, arrayp}. +@item bignump +@xref{Predicates on Numbers, floatp}. + @item bool-vector-p @xref{Bool-Vectors, bool-vector-p}. @@ -1928,6 +1936,9 @@ with references to further information. @item custom-variable-p @xref{Variable Definitions, custom-variable-p}. +@item fixnump +@xref{Predicates on Numbers, floatp}. + @item floatp @xref{Predicates on Numbers, floatp}. @@ -2083,6 +2094,10 @@ strings), two arguments with the same contents or elements are not necessarily @code{eq} to each other: they are @code{eq} only if they are the same object, meaning that a change in the contents of one will be reflected by the same change in the contents of the other. +For other types of objects whose contents cannot be changed (e.g., +floats), two arguments with the same contents might or might not be +the same object, and @code{eq} returns @code{t} or @code{nil} +depending on whether the Lisp interpreter created one object or two. @example @group @@ -2096,6 +2111,12 @@ be reflected by the same change in the contents of the other. @end group @group +(eq 3.0 3.0) + @result{} t @r{or} nil +;; @r{The result is implementation-dependent.} +@end group + +@group (eq "asdf" "asdf") @result{} nil @end group diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 65c57064a3d..6fae93717a2 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -95,6 +95,22 @@ if requested by environment variables such as @env{LANG}. @item It does some basic parsing of the command-line arguments. +@item +It loads your early init file (@pxref{Early Init File,,, emacs, The +GNU Emacs Manual}). This is not done if the options @samp{-q}, +@samp{-Q}, or @samp{--batch} were specified. If the @samp{-u} option +was specified, Emacs looks for the init file in that user's home +directory instead. + +@item +It calls the function @code{package-activate-all} to activate any +optional Emacs Lisp package that has been installed. @xref{Packaging +Basics}. However, Emacs doesn't activate the packages when +@code{package-enable-at-startup} is @code{nil} or when it's started +with one of the options @samp{-q}, @samp{-Q}, or @samp{--batch}. To +activate the packages in the latter case, @code{package-activate-all} +should be called explicitly (e.g., via the @samp{--funcall} option). + @vindex initial-window-system@r{, and startup} @findex window-system-initialization @item @@ -159,15 +175,6 @@ It loads your abbrevs from the file specified by (@pxref{Abbrev Files, abbrev-file-name}). This is not done if the option @samp{--batch} was specified. -@item -It calls the function @code{package-initialize} to activate any -optional Emacs Lisp package that has been installed. @xref{Packaging -Basics}. However, Emacs doesn't initialize packages when -@code{package-enable-at-startup} is @code{nil} or when it's started -with one of the options @samp{-q}, @samp{-Q}, or @samp{--batch}. To -initialize packages in the latter case, @code{package-initialize} -should be called explicitly (e.g., via the @samp{--funcall} option). - @vindex after-init-time @item It sets the variable @code{after-init-time} to the value of @@ -366,6 +373,7 @@ Equivalent to @samp{-q --no-site-file --no-splash}. @cindex init file @cindex @file{.emacs} @cindex @file{init.el} +@cindex @file{early-init.el} When you start Emacs, it normally attempts to load your @dfn{init file}. This is either a file named @file{.emacs} or @file{.emacs.el} @@ -389,6 +397,19 @@ file; this way, even if you have su'd, Emacs still loads your own init file. If those environment variables are absent, though, Emacs uses your user-id to find your home directory. +@cindex early init file + Emacs also attempts to load a second init file, called the +@dfn{early init file}, if it exists. This is a file named +@file{early-init.el} in your @file{~/.emacs.d} directory. The +difference between the early init file and the regular init file is +that the early init file is loaded much earlier during the startup +process, so you can use it to customize some things that are +initialized before loading the regular init file. For example, you +can customize the process of initializing the package system, by +setting variables such as @var{package-load-list} or +@var{package-enable-at-startup}. @xref{Package Installation,,, +emacs,The GNU Emacs Manual}. + @cindex default init file An Emacs installation may have a @dfn{default init file}, which is a Lisp library named @file{default.el}. Emacs finds this file through @@ -1181,24 +1202,19 @@ Titles}). @cindex UID @defun user-real-uid This function returns the real @acronym{UID} of the user. -The value may be floating point, in the (unlikely) event that -the UID is too large to fit in a Lisp integer. @end defun @defun user-uid This function returns the effective @acronym{UID} of the user. -The value may be floating point. @end defun @cindex GID @defun group-gid This function returns the effective @acronym{GID} of the Emacs process. -The value may be floating point. @end defun @defun group-real-gid This function returns the real @acronym{GID} of the Emacs process. -The value may be floating point. @end defun @defun system-users @@ -1214,6 +1230,11 @@ groups on the system. If Emacs cannot retrieve this information, the return value is @code{nil}. @end defun +@defun group-name gid +This function returns the group name that corresponds to the numeric +group ID @var{gid}, or @code{nil} if there is no such group. +@end defun + @node Time of Day @section Time of Day @@ -1222,11 +1243,44 @@ return value is @code{nil}. This section explains how to determine the current time and time zone. +@cindex Lisp timestamp +@cindex timestamp, Lisp + Many functions like @code{current-time} and @code{file-attributes} +return @dfn{Lisp timestamp} values that count seconds, and that can +represent absolute time by counting seconds since the @dfn{epoch} of +1970-01-01 00:00:00 UTC. + + Although traditionally Lisp timestamps were integer pairs, their +form has evolved and programs ordinarily should not depend on the +current default form. If your program needs a particular timestamp +form, you can use the @code{encode-time} function to convert it to the +needed form. @xref{Time Conversion}. + @cindex epoch - Most of these functions represent time as a list of four integers -@code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}. -This represents the number of seconds from the @dfn{epoch} (January -1, 1970 at 00:00 UTC), using the formula: + There are currently three forms of Lisp timestamps, each of +which represents a number of seconds: + +@itemize @bullet +@item +An integer. Although this is the simplest form, it cannot represent +subsecond timestamps. + +@item +A pair of integers @code{(@var{ticks} . @var{hz})}, where @var{hz} is +positive. This represents @var{ticks}/@var{hz} seconds, which is the +same time as plain @var{ticks} if @var{hz} is 1. A common value for +@var{hz} is 1000000000, for a nanosecond-resolution +clock.@footnote{Currently @var{hz} should be at least 65536 to avoid +compatibility warnings when the timestamp is passed to standard +functions, as previous versions of Emacs would interpret such a +timestamps differently due to backward-compatibility concerns. These +warnings are intended to be removed in a future Emacs version.} + +@item +A list of four integers @code{(@var{high} @var{low} @var{micro} +@var{pico})}, where 0 @leq{} @var{low} < 65536, 0 @leq{} @var{micro} < +1000000, and 0 @leq{} @var{pico} < 1000000. +This represents the number of seconds using the formula: @ifnottex @var{high} * 2**16 + @var{low} + @var{micro} * 10**@minus{}6 + @var{pico} * 10**@minus{}12. @@ -1234,21 +1288,23 @@ This represents the number of seconds from the @dfn{epoch} (January @tex $high*2^{16} + low + micro*10^{-6} + pico*10^{-12}$. @end tex -The return value of @code{current-time} represents time using this -form, as do the timestamps in the return values of other functions -such as @code{file-attributes} (@pxref{Definition of -file-attributes}). In some cases, functions may return two- or +In some cases, functions may default to returning two- or three-element lists, with omitted @var{microsec} and @var{picosec} components defaulting to zero. +On all current machines @var{picosec} is a multiple of 1000, but this +may change as higher-resolution clocks become available. +@end itemize @cindex time value Function arguments, e.g., the @var{time} argument to @code{current-time-string}, accept a more-general @dfn{time value} -format, which can be a list of integers as above, or a single number -for seconds since the epoch, or @code{nil} for the current time. You -can convert a time value into a human-readable string using -@code{current-time-string} and @code{format-time-string}, into a list -of integers using @code{seconds-to-time}, and into other forms using +format, which can be a Lisp timestamp, @code{nil} for the current +time, a single floating-point number for seconds, or a list +@code{(@var{high} @var{low} @var{micro})} or @code{(@var{high} +@var{low})} that is a truncated list timestamp with missing elements +taken to be zero. You can convert a time value into +a human-readable string using @code{format-time-string}, into a Lisp +timestamp using @code{encode-time}, and into other forms using @code{decode-time} and @code{float-time}. These functions are described in the following sections. @@ -1257,9 +1313,10 @@ This function returns the current time and date as a human-readable string. The format does not vary for the initial part of the string, which contains the day of week, month, day of month, and time of day in that order: the number of characters used for these fields is -always the same, so you can reliably -use @code{substring} to extract them. You should count -characters from the beginning of the string rather than from the end, +always the same, although (unless you require English weekday or +month abbreviations regardless of locale) it is typically more +convenient to use @code{format-time-string} than to extract +fields from the output of @code{current-time-string}, as the year might not have exactly four digits, and additional information may some day be added at the end. @@ -1276,12 +1333,7 @@ defaults to the current time zone rule. @xref{Time Zone Rules}. @end defun @defun current-time -This function returns the current time, represented as a list of four -integers @code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}. -These integers have trailing zeros on systems that return time with -lower resolutions. On all current machines @var{picosec} is a -multiple of 1000, but this may change as higher-resolution clocks -become available. +This function returns the current time as a Lisp timestamp. @end defun @defun float-time &optional time @@ -1295,13 +1347,6 @@ exact. Do not use this function if precise time stamps are required. @code{time-to-seconds} is an alias for this function. @end defun -@defun seconds-to-time time -This function converts a time value to list-of-integer form. -For example, if @var{time} is a number, @code{(time-to-seconds -(seconds-to-time @var{time}))} equals the number unless overflow -or rounding errors occur. -@end defun - @node Time Zone Rules @section Time Zone Rules @cindex time zone rules @@ -1412,7 +1457,8 @@ The year, an integer typically greater than 1900. The day of week, as an integer between 0 and 6, where 0 stands for Sunday. @item dst -@code{t} if daylight saving time is effect, otherwise @code{nil}. +@code{t} if daylight saving time is effect, @code{nil} if it is not +in effect, and @minus{}1 if this information is not available. @item utcoff An integer indicating the Universal Time offset in seconds, i.e., the number of seconds east of Greenwich. @@ -1422,32 +1468,63 @@ seconds east of Greenwich. @var{dow} and @var{utcoff}. @end defun -@defun encode-time seconds minutes hour day month year &optional zone -This function is the inverse of @code{decode-time}. It converts seven -items of calendrical data into a list-of-integer time value. For the -meanings of the arguments, see the table above under -@code{decode-time}. +@defun encode-time &optional time form &rest obsolescent-arguments +This function converts @var{time} to a Lisp timestamp. +It can act as the inverse of @code{decode-time}. + +The first argument can be a time value such as a number of seconds, a +pair @code{(@var{ticks} . @var{hz})}, a list @code{(@var{high} +@var{low} @var{micro} @var{pico})}, or @code{nil} (the default) for +the current time (@pxref{Time of Day}). It can also be a list +@code{(@var{second} @var{minute} @var{hour} @var{day} @var{month} +@var{year} @var{ignored} @var{dst} @var{zone})} that specifies a +decoded time in the style of @code{decode-time}, so that +@code{(encode-time (decode-time ...))} works. For the meanings of +these list members, see the table under @code{decode-time}. + +The optional @var{form} argument specifies the desired timestamp form +to be returned. If @var{form} is the symbol @code{integer}, this +function returns an integer count of seconds. If @var{form} is a +positive integer, it specifies a clock frequency and this function +returns an integer-pair timestamp @code{(@var{ticks} +. @var{form})}.@footnote{Currently a positive integer @var{form} +should be at least 65536 if the returned value is intended to be given +to standard functions expecting Lisp timestamps.} If @var{form} is +@code{t}, this function treats it as a positive integer suitable for +representing the timestamp; for example, it is treated as 1000000000 +if the platform timestamp has nanosecond resolution. If @var{form} is +@code{list}, this function returns an integer list @code{(@var{high} +@var{low} @var{micro} @var{pico})}. Although an omitted or @code{nil} +@var{form} currently acts like @code{list}, this is planned to change +in a future Emacs version, so callers requiring list timestamps should +pass @code{list} explicitly. + +As an obsolescent calling convention, this function can be given six +or more arguments. The first six arguments @var{second}, +@var{minute}, @var{hour}, @var{day}, @var{month}, and @var{year} +specify most of the components of a decoded time. If there are more +than six arguments the @emph{last} argument is used as @var{zone} and +any other extra arguments are ignored, so that @code{(apply +#\\='encode-time (decode-time ...))} works; otherwise @var{zone} defaults +to the current time zone rule (@pxref{Time Zone Rules}). The decoded +time's @var{dst} component is treated as if it was @minus{}1, and +@var{form} takes its default value. Year numbers less than 100 are not treated specially. If you want them to stand for years above 1900, or years above 2000, you must alter them yourself before you call @code{encode-time}. -The optional argument @var{zone} defaults to the current time zone rule. -@xref{Time Zone Rules}. - -If you pass more than seven arguments to @code{encode-time}, the first -six are used as @var{seconds} through @var{year}, the last argument is -used as @var{zone}, and the arguments in between are ignored. This -feature makes it possible to use the elements of a list returned by -@code{decode-time} as the arguments to @code{encode-time}, like this: +The @code{encode-time} function acts as a rough inverse to +@code{decode-time}. For example, you can pass the output of +the latter to the former as follows: @example -(apply 'encode-time (decode-time @dots{})) +(encode-time (decode-time @dots{})) @end example You can perform simple date arithmetic by using out-of-range values for -the @var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month} -arguments; for example, day 0 means the day preceding the given month. +@var{seconds}, @var{minutes}, @var{hour}, @var{day}, and @var{month}; +for example, day 0 means the day preceding the given month. The operating system puts limits on the range of possible time values; if you try to encode a time that is out of range, an error results. @@ -1462,12 +1539,12 @@ on others, years as early as 1901 do work. @cindex formatting time values These functions convert time values to text in a string, and vice versa. -Time values include @code{nil}, numbers, and lists of two to four -integers (@pxref{Time of Day}). +Time values include @code{nil}, numbers, and Lisp timestamps +(@pxref{Time of Day}). @defun date-to-time string This function parses the time-string @var{string} and returns the -corresponding time value. +corresponding Lisp timestamp. @end defun @defun format-time-string format-string &optional time zone @@ -1665,10 +1742,6 @@ You can also specify the field width by following the @samp{%} with a number; shorter numbers will be padded with blanks. An optional period before the width requests zero-padding instead. For example, @code{"%.3Y"} might produce @code{"004 years"}. - -@emph{Warning:} This function works only with values of @var{seconds} -that don't exceed @code{most-positive-fixnum} (@pxref{Integer Basics, -most-positive-fixnum}). @end defun @node Processor Run Time @@ -1693,10 +1766,8 @@ When called interactively, it prints the uptime in the echo area. @end deffn @defun get-internal-run-time -This function returns the processor run time used by Emacs as a list -of four integers: @code{(@var{sec-high} @var{sec-low} @var{microsec} -@var{picosec})}, using the same format as @code{current-time} -(@pxref{Time of Day}). +This function returns the processor run time used by Emacs, as a Lisp +timestamp (@pxref{Time of Day}). Note that the time returned by this function excludes the time Emacs was not using the processor, and if the Emacs process has several @@ -1721,26 +1792,36 @@ interactively, it prints the duration in the echo area. @cindex calendrical computations These functions perform calendrical computations using time values -(@pxref{Time of Day}). A value of @code{nil} for any of their +(@pxref{Time of Day}). As with any time value, a value of +@code{nil} for any of their time-value arguments stands for the current system time, and a single -integer number stands for the number of seconds since the epoch. +number stands for the number of seconds since the epoch. @defun time-less-p t1 t2 This returns @code{t} if time value @var{t1} is less than time value @var{t2}. +The result is @code{nil} if either argument is a NaN. +@end defun + +@defun time-equal-p t1 t2 +This returns @code{t} if @var{t1} and @var{t2} are equal time values. +The result is @code{nil} if either argument is a NaN. @end defun @defun time-subtract t1 t2 This returns the time difference @var{t1} @minus{} @var{t2} between -two time values, as a time value. If you need the difference in units +two time values, as a time value. However, the result is a float +if either argument is a float infinity or NaN@. +If you need the difference in units of elapsed seconds, use @code{float-time} (@pxref{Time of Day, float-time}) to convert the result into seconds. @end defun @defun time-add t1 t2 This returns the sum of two time values, as a time value. +However, the result is a float if either argument is a float infinity or NaN@. One argument should represent a time difference rather than a point in time, -either as a list or as a single number of elapsed seconds. +as a time value that is often just a single number of elapsed seconds. Here is how to add a number of seconds to a time value: @example @@ -1983,8 +2064,7 @@ the idleness time, as described below. @defun current-idle-time If Emacs is idle, this function returns the length of time Emacs has -been idle, as a list of four integers: @code{(@var{sec-high} -@var{sec-low} @var{microsec} @var{picosec})}, using the same format as +been idle, using the same format as @code{current-time} (@pxref{Time of Day}). When Emacs is not idle, @code{current-idle-time} returns @code{nil}. diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi index 39bdc01a75c..7244efbd8f7 100644 --- a/doc/lispref/package.texi +++ b/doc/lispref/package.texi @@ -22,6 +22,7 @@ user-level features of the packaging system. * Simple Packages:: How to package a single .el file. * Multi-file Packages:: How to package multiple files. * Package Archives:: Maintaining package archives. +* Archive Web Server:: Interfacing to an archive web server. @end menu @node Packaging Basics @@ -105,24 +106,36 @@ adds the package's content directory to @code{load-path}, and evaluates the autoload definitions in @file{@var{name}-autoloads.el}. Whenever Emacs starts up, it automatically calls the function -@code{package-initialize} to load installed packages. This is done -after loading the init file and abbrev file (if any) and before -running @code{after-init-hook} (@pxref{Startup Summary}). Automatic -package loading is disabled if the user option -@code{package-enable-at-startup} is @code{nil}. +@code{package-activate-all} to make installed packages available to the +current session. This is done after loading the early init file, but +before loading the regular init file (@pxref{Startup Summary}). +Packages are not automatically made available if the user option +@code{package-enable-at-startup} is set to @code{nil} in the early +init file. + +@defun package-activate-all +This function makes the packages available to the current session. +The user option @code{package-load-list} specifies which packages to +make available; by default, all installed packages are made available. +If called during startup, this function also sets +@code{package-enable-at-startup} to @code{nil}, to avoid accidentally +evaluating package autoloads more than once. @xref{Package +Installation,,, emacs, The GNU Emacs Manual}. + +In most cases, you should not need to call @code{package-activate-all}, +as this is done automatically during startup. Simply make sure to put +any code that should run before @code{package-activate-all} in the early +init file, and any code that should run after it in the primary init +file (@pxref{Init File,,, emacs, The GNU Emacs Manual}). +@end defun @deffn Command package-initialize &optional no-activate This function initializes Emacs' internal record of which packages are -installed, and loads them. The user option @code{package-load-list} -specifies which packages to load; by default, all installed packages -are loaded. If called during startup, this function also sets -@code{package-enable-at-startup} to @code{nil}, to avoid accidentally -loading the packages twice. @xref{Package Installation,,, emacs, The -GNU Emacs Manual}. +installed, and then calls @code{package-activate-all}. The optional argument @var{no-activate}, if non-@code{nil}, causes Emacs to update its record of installed packages without actually -loading them; it is for internal use only. +making them available. @end deffn @node Simple Packages @@ -237,7 +250,8 @@ dependency's version (a string). @end defun If the content directory contains a file named @file{README}, this -file is used as the long description. +file is used as the long description (overriding any @samp{;;; +Commentary:} section). If the content directory contains a file named @file{dir}, this is assumed to be an Info directory file made with @command{install-info}. @@ -299,8 +313,8 @@ access. Such local archives are mainly useful for testing. A package archive is simply a directory in which the package files, and associated files, are stored. If you want the archive to be -reachable via HTTP, this directory must be accessible to a web server. -How to accomplish this is beyond the scope of this manual. +reachable via HTTP, this directory must be accessible to a web server; +@xref{Archive Web Server}. A convenient way to set up and update a package archive is via the @code{package-x} library. This is included with Emacs, but not loaded @@ -381,3 +395,28 @@ manual. For more information on cryptographic keys and signing, @pxref{Top,, GnuPG, gnupg, The GNU Privacy Guard Manual}. Emacs comes with an interface to GNU Privacy Guard, @pxref{Top,, EasyPG, epa, Emacs EasyPG Assistant Manual}. + +@node Archive Web Server +@section Interfacing to an archive web server +@cindex archive web server + +A web server providing access to a package archive must support the +following queries: + +@table @asis +@item archive-contents +Return a lisp form describing the archive contents. The form is a list +of 'package-desc' structures (see @file{package.el}), except the first +element of the list is the archive version. + +@item <package name>-readme.txt +Return the long description of the package. + +@item <file name>.sig +Return the signature for the file. + +@item <file name> +Return the file. This will be the tarball for a multi-file +package, or the single file for a simple package. + +@end table diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index d2ab518e5eb..72b164c5d45 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -177,6 +177,14 @@ before starting Emacs. Trying to modify @code{exec-path} independently of @env{PATH} can lead to confusing results. @end defopt +@defun exec-path +This function is an extension of the variable @code{exec-path}. If +@code{default-directory} indicates a remote directory, this function +returns a list of directories used for searching programs on the +respective remote host. In case of a local @code{default-directory}, +the function returns just the value of the variable @code{exec-path}. +@end defun + @node Shell Arguments @section Shell Arguments @cindex arguments for shell commands @@ -415,27 +423,27 @@ be found in the definition of the @code{insert-directory} function: @defun process-file program &optional infile buffer display &rest args This function processes files synchronously in a separate process. It -is similar to @code{call-process}, but may invoke a file handler based -on the value of the variable @code{default-directory}, which specifies -the current working directory of the subprocess. +is similar to @code{call-process}, but may invoke a file name handler +based on the value of the variable @code{default-directory}, which +specifies the current working directory of the subprocess. The arguments are handled in almost the same way as for @code{call-process}, with the following differences: -Some file handlers may not support all combinations and forms of the +Some file name handlers may not support all combinations and forms of the arguments @var{infile}, @var{buffer}, and @var{display}. For example, -some file handlers might behave as if @var{display} were @code{nil}, +some file name handlers might behave as if @var{display} were @code{nil}, regardless of the value actually passed. As another example, some -file handlers might not support separating standard output and error +file name handlers might not support separating standard output and error output by way of the @var{buffer} argument. -If a file handler is invoked, it determines the program to run based +If a file name handler is invoked, it determines the program to run based on the first argument @var{program}. For instance, suppose that a handler for remote files is invoked. Then the path that is used for searching for the program might be different from @code{exec-path}. -The second argument @var{infile} may invoke a file handler. The file -handler could be different from the handler chosen for the +The second argument @var{infile} may invoke a file name handler. The file +name handler could be different from the handler chosen for the @code{process-file} function itself. (For example, @code{default-directory} could be on one remote host, and @var{infile} on a different remote host. Or @code{default-directory} @@ -462,7 +470,7 @@ remote files. By default, this variable is always set to @code{t}, meaning that a call of @code{process-file} could potentially change any file on a -remote host. When set to @code{nil}, a file handler could optimize +remote host. When set to @code{nil}, a file name handler could optimize its behavior with respect to remote file attribute caching. You should only ever change this variable with a let-binding; never @@ -686,7 +694,15 @@ a default sentinel will be used, which can be overridden later. @item :stderr @var{stderr} Associate @var{stderr} with the standard error of the process. A non-@code{nil} value should be either a buffer or a pipe process -created with @code{make-pipe-process}, described below. +created with @code{make-pipe-process}, described below. If +@var{stderr} is @code{nil}, standard error is mixed with standard +output, and both are sent to @var{buffer} or @var{filter}. + +@item :file-handler @var{file-handler} +If @var{file-handler} is non-@code{nil}, then look for a file name +handler for the current buffer's @code{default-directory}, and invoke +that file name handler to make the process. If there is no such +handler, proceed as if @var{file-handler} were @code{nil}. @end table The original argument list, modified with the actual connection @@ -694,9 +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 @@ -812,7 +837,7 @@ subprocess running @var{program} in it, and returns its process object. The difference from @code{start-process} is that this function may -invoke a file handler based on the value of @code{default-directory}. +invoke a file name handler based on the value of @code{default-directory}. This handler ought to run @var{program}, perhaps on the local host, perhaps on a remote host that corresponds to @code{default-directory}. In the latter case, the local part of @code{default-directory} becomes @@ -826,13 +851,13 @@ names relative to @code{default-directory}, or to names that identify the files locally on the remote host, by running them through @code{file-local-name}. -Depending on the implementation of the file handler, it might not be +Depending on the implementation of the file name handler, it might not be possible to apply @code{process-filter} or @code{process-sentinel} to the resulting process object. @xref{Filter Functions}, and @ref{Sentinels}. @c FIXME Can we find a better example (i.e., a more modern function @c that is actually documented). -Some file handlers may not support @code{start-file-process} (for +Some file name handlers may not support @code{start-file-process} (for example the function @code{ange-ftp-hook-function}). In such cases, this function does nothing and returns @code{nil}. @end defun @@ -2079,8 +2104,6 @@ attribute and @var{value} is the value of that attribute. The various attribute @var{key}s that this function can return are listed below. Not all platforms support all of these attributes; if an attribute is not supported, its association will not appear in the returned alist. -Values that are numbers can be either integer or floating point, -depending on the magnitude of the value. @table @code @item euid @@ -2164,19 +2187,17 @@ faults for all the child processes of the given process. @item utime Time spent by the process in the user context, for running the -application's code. The corresponding @var{value} is in the -@w{@code{(@var{high} @var{low} @var{microsec} @var{picosec})}} format, the same -format used by functions @code{current-time} (@pxref{Time of Day, -current-time}) and @code{file-attributes} (@pxref{File Attributes}). +application's code. The corresponding @var{value} is a Lisp +timestamp (@pxref{Time of Day}). @item stime Time spent by the process in the system (kernel) context, for -processing system calls. The corresponding @var{value} is in the same -format as for @code{utime}. +processing system calls. The corresponding @var{value} is a Lisp +timestamp. @item time The sum of @code{utime} and @code{stime}. The corresponding -@var{value} is in the same format as for @code{utime}. +@var{value} is a Lisp timestamp. @item cutime @itemx cstime @@ -2195,13 +2216,10 @@ nice values get scheduled more favorably.) The number of threads in the process. @item start -The time when the process was started, in the same -@code{(@var{high} @var{low} @var{microsec} @var{picosec})} format used by -@code{file-attributes} and @code{current-time}. +The time when the process was started, as a Lisp timestamp. @item etime -The time elapsed since the process started, in the format @code{(@var{high} -@var{low} @var{microsec} @var{picosec})}. +The time elapsed since the process started, as a Lisp timestamp. @item vsize The virtual memory size of the process, measured in kilobytes. @@ -2729,8 +2747,7 @@ Initialize the process filter to @var{filter}. @item :filter-multibyte @var{multibyte} If @var{multibyte} is non-@code{nil}, strings given to the process -filter are multibyte, otherwise they are unibyte. The default is the -default value of @code{enable-multibyte-characters}. +filter are multibyte, otherwise they are unibyte. The default is @code{t}. @item :sentinel @var{sentinel} Initialize the process sentinel to @var{sentinel}. @@ -3133,7 +3150,6 @@ direction is also known as @dfn{serializing} or @dfn{packing}. @menu * Bindat Spec:: Describing data layout. * Bindat Functions:: Doing the unpacking and packing. -* Bindat Examples:: Samples of what bindat.el can do for you! @end menu @node Bindat Spec @@ -3376,132 +3392,3 @@ dotted notation. @result{} "127.0.0.1" @end example @end defun - -@node Bindat Examples -@subsection Examples of Byte Unpacking and Packing -@c FIXME? This seems a very long example for something that is not used -@c very often. As of 25.2, gdb-mi.el is the only user of bindat.el in Emacs. -@c Maybe one or both of these examples should just be moved to the -@c commentary of bindat.el. - - Here are two complete examples that use bindat.el. -The first shows simple byte packing: - -@lisp -(require 'bindat) - -(defun rfc868-payload () - (bindat-pack - '((now-hi u16) - (now-lo u16)) - ;; Emacs uses Unix epoch, while RFC868 epoch - ;; is 1900-01-01 00:00:00, which is 2208988800 - ;; (or #x83aa7e80) seconds more. - (let ((now (time-add nil '(#x83aa #x7e80)))) - `((now-hi . ,(car now)) - (now-lo . ,(cadr now)))))) - -(let ((s (rfc868-payload))) - (list (multibyte-string-p s) - (mapconcat (lambda (byte) - (format "%02x" byte)) - s " ") - (current-time-string))) - @result{} (nil "dc 6d 17 01" "Fri Mar 10 13:13:53 2017") -@end lisp - -The following is an example of defining and unpacking a complex -structure. Consider the following C structures: - -@example -struct header @{ - unsigned long dest_ip; - unsigned long src_ip; - unsigned short dest_port; - unsigned short src_port; -@}; - -struct data @{ - unsigned char type; - unsigned char opcode; - unsigned short length; /* in network byte order */ - unsigned char id[8]; /* null-terminated string */ - unsigned char data[/* (length + 3) & ~3 */]; -@}; - -struct packet @{ - struct header header; - unsigned long counters[2]; /* in little endian order */ - unsigned char items; - unsigned char filler[3]; - struct data item[/* items */]; - -@}; -@end example - -The corresponding data layout specification is: - -@lisp -(setq header-spec - '((dest-ip ip) - (src-ip ip) - (dest-port u16) - (src-port u16))) - -(setq data-spec - '((type u8) - (opcode u8) - (length u16) ; network byte order - (id strz 8) - (data vec (length)) - (align 4))) - -(setq packet-spec - '((header struct header-spec) - (counters vec 2 u32r) ; little endian order - (items u8) - (fill 3) - (item repeat (items) - (struct data-spec)))) -@end lisp - -A binary data representation is: - -@lisp -(setq binary-data - [ 192 168 1 100 192 168 1 101 01 28 21 32 - 160 134 1 0 5 1 0 0 2 0 0 0 - 2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0 - 1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ]) -@end lisp - -The corresponding decoded structure is: - -@lisp -(setq decoded (bindat-unpack packet-spec binary-data)) - @result{} -((header - (dest-ip . [192 168 1 100]) - (src-ip . [192 168 1 101]) - (dest-port . 284) - (src-port . 5408)) - (counters . [100000 261]) - (items . 2) - (item ((data . [1 2 3 4 5]) - (id . "ABCDEF") - (length . 5) - (opcode . 3) - (type . 2)) - ((data . [6 7 8 9 10 11 12]) - (id . "BCDEFG") - (length . 7) - (opcode . 4) - (type . 1)))) -@end lisp - -An example of fetching data from this structure: - -@lisp -(bindat-get-field decoded 'item 1 'id) - @result{} "BCDEFG" -@end lisp diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index 7546863dde2..05fc3282053 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -642,10 +642,10 @@ is omitted, the minimum is 0; if @var{n} is omitted, there is no maximum. For both forms, @var{m} and @var{n}, if specified, may be no larger than @ifnottex -2**15 @minus{} 1 +2**16 @minus{} 1 @end ifnottex @tex -@math{2^{15}-1} +@math{2^{16}-1} @end tex . diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 5cf2e89644d..0c3c4e3b282 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -1308,9 +1308,9 @@ not evaluate or even examine the elements of the vector. @example @group (setq avector [1 two '(three) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] + @result{} [1 two '(three) "four" [five]] (eval avector) - @result{} [1 two (quote (three)) "four" [five]] + @result{} [1 two '(three) "four" [five]] (eq avector (eval avector)) @result{} t @end group @@ -1400,9 +1400,9 @@ list with the same elements: @example @group (setq avector [1 two (quote (three)) "four" [five]]) - @result{} [1 two (quote (three)) "four" [five]] + @result{} [1 two '(three) "four" [five]] (append avector nil) - @result{} (1 two (quote (three)) "four" [five]) + @result{} (1 two '(three) "four" [five]) @end group @end example @@ -1777,6 +1777,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 5aa49c2e954..600639f244f 100644 --- a/doc/lispref/streams.texi +++ b/doc/lispref/streams.texi @@ -809,6 +809,21 @@ when the output stream is a unibyte buffer or a marker pointing into one. @end defvar +@defvar print-charset-text-property +This variable controls printing of `charset' text property on printing +a string. The value should be @code{nil}, @code{t}, or +@code{default}. + +If the value is @code{nil}, @code{charset} text properties are never +printed. If @code{t}, they are always printed. + +If the value is @code{default}, only print @code{charset} text +properties if there is an ``unexpected'' @code{charset} property. For +ascii characters, all charsets are considered ``expected''. +Otherwise, the expected @code{charset} property of a character is +given by @code{char-charset}. +@end defvar + @defvar print-length @cindex printing limits The value of this variable is the maximum number of elements to print in diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 8420527f858..521f163663d 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -121,7 +121,7 @@ character (i.e., an integer), @code{nil} otherwise. The following functions create strings, either from scratch, or by putting strings together, or by taking them apart. -@defun make-string count character +@defun make-string count character &optional multibyte This function returns a string made up of @var{count} repetitions of @var{character}. If @var{count} is negative, an error is signaled. @@ -132,6 +132,13 @@ This function returns a string made up of @var{count} repetitions of @result{} "" @end example + Normally, if @var{character} is an @acronym{ASCII} character, the +result is a unibyte string. But if the optional argument +@var{multibyte} is non-@code{nil}, the function will produce a +multibyte string instead. This is useful when you later need to +concatenate the result with non-@acronym{ASCII} strings or replace +some of its characters with non-@acronym{ASCII} characters. + Other functions to compare with this one include @code{make-vector} (@pxref{Vectors}) and @code{make-list} (@pxref{Building Lists}). @end defun @@ -666,6 +673,28 @@ of the two strings. The sign is negative if @var{string1} (or its specified portion) is less. @end defun +@cindex Levenshtein distance +@cindex distance between strings +@cindex edit distance between strings +@defun string-distance string1 string2 &optional bytecompare +This function returns the @dfn{Levenshtein distance} between the +source string @var{string1} and the target string @var{string2}. The +Levenshtein distance is the number of single-character +changes---deletions, insertions, or replacements---required to +transform the source string into the target string; it is one possible +definition of the @dfn{edit distance} between strings. + +Letter-case of the strings is significant for the computed distance, +but their text properties are ignored. If the optional argument +@var{bytecompare} is non-@code{nil}, the function calculates the +distance in terms of bytes instead of characters. The byte-wise +comparison uses the internal Emacs representation of characters, so it +will produce inaccurate results for multibyte strings that include raw +bytes (@pxref{Text Representations}); make the strings unibyte by +encoding them (@pxref{Explicit Encoding}) if you need accurate results +with raw bytes. +@end defun + @defun assoc-string key alist &optional case-fold This function works like @code{assoc}, except that @var{key} must be a string or symbol, and comparison is done using @code{compare-strings}. @@ -893,18 +922,25 @@ Functions}). Thus, strings are enclosed in @samp{"} characters, and @item %o @cindex integer to octal Replace the specification with the base-eight representation of an -unsigned integer. +integer. Negative integers are formatted in a platform-dependent +way. The object can also be a nonnegative floating-point +number that is formatted as an integer, dropping any fraction, if the +integer does not exceed machine limits. @item %d Replace the specification with the base-ten representation of a signed -integer. +integer. The object can also be a floating-point number that is +formatted as an integer, dropping any fraction. @item %x @itemx %X @cindex integer to hexadecimal Replace the specification with the base-sixteen representation of an -unsigned integer. @samp{%x} uses lower case and @samp{%X} uses upper -case. +integer. Negative integers are formatted in a platform-dependent +way. @samp{%x} uses lower case and @samp{%X} uses upper +case. The object can also be a nonnegative floating-point number that +is formatted as an integer, dropping any fraction, if the integer does +not exceed machine limits. @item %c Replace the specification with the character which is the value given. @@ -981,17 +1017,17 @@ numbered or unnumbered format specifications but not both, except that After the @samp{%} and any field number, you can put certain @dfn{flag characters}. - The flag @samp{+} inserts a plus sign before a positive number, so + The flag @samp{+} inserts a plus sign before a nonnegative number, so that it always has a sign. A space character as flag inserts a space -before a positive number. (Otherwise, positive numbers start with the -first digit.) These flags are useful for ensuring that positive -numbers and negative numbers use the same number of columns. They are +before a nonnegative number. (Otherwise, nonnegative numbers start with the +first digit.) These flags are useful for ensuring that nonnegative +and negative numbers use the same number of columns. They are ignored except for @samp{%d}, @samp{%e}, @samp{%f}, @samp{%g}, and if both flags are used, @samp{+} takes precedence. The flag @samp{#} specifies an alternate form which depends on the format in use. For @samp{%o}, it ensures that the result begins -with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes the result +with a @samp{0}. For @samp{%x} and @samp{%X}, it prefixes nonzero results with @samp{0x} or @samp{0X}. For @samp{%e} and @samp{%f}, the @samp{#} flag means include a decimal point even if the precision is zero. For @samp{%g}, it always includes a decimal point, and also @@ -1074,6 +1110,17 @@ shows only the first three characters of the representation for precision is what the local library functions of the @code{printf} family produce. +@cindex formatting numbers for rereading later + If you plan to use @code{read} later on the formatted string to +retrieve a copy of the formatted value, use a specification that lets +@code{read} reconstruct the value. To format numbers in this +reversible way you can use @samp{%s} and @samp{%S}, to format just +integers you can also use @samp{%d}, and to format just nonnegative +integers you can also use @samp{#x%x} and @samp{#o%o}. Other formats +may be problematic; for example, @samp{%d} and @samp{%g} can mishandle +NaNs and can lose precision and type, and @samp{#x%x} and @samp{#o%o} +can mishandle negative integers. @xref{Input Functions}. + @node Case Conversion @section Case Conversion in Lisp @cindex upper case diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi index 90d380f5b84..a960eeac7e8 100644 --- a/doc/lispref/syntax.texi +++ b/doc/lispref/syntax.texi @@ -1014,13 +1014,13 @@ corresponds to each syntax flag. @item @i{Prefix} @tab @i{Flag} @tab @i{Prefix} @tab @i{Flag} @item -@samp{1} @tab @code{(lsh 1 16)} @tab @samp{p} @tab @code{(lsh 1 20)} +@samp{1} @tab @code{(ash 1 16)} @tab @samp{p} @tab @code{(ash 1 20)} @item -@samp{2} @tab @code{(lsh 1 17)} @tab @samp{b} @tab @code{(lsh 1 21)} +@samp{2} @tab @code{(ash 1 17)} @tab @samp{b} @tab @code{(ash 1 21)} @item -@samp{3} @tab @code{(lsh 1 18)} @tab @samp{n} @tab @code{(lsh 1 22)} +@samp{3} @tab @code{(ash 1 18)} @tab @samp{n} @tab @code{(ash 1 22)} @item -@samp{4} @tab @code{(lsh 1 19)} @tab @samp{c} @tab @code{(lsh 1 23)} +@samp{4} @tab @code{(ash 1 19)} @tab @samp{c} @tab @code{(ash 1 23)} @end multitable @defun string-to-syntax desc diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index fb5f56e9ddd..6dfd211d1a0 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -61,6 +61,8 @@ the character after point. * Checksum/Hash:: Computing cryptographic hashes. * GnuTLS Cryptography:: Cryptographic algorithms imported from GnuTLS. * Parsing HTML/XML:: Parsing HTML and XML. +* Parsing JSON:: Parsing and generating JSON values. +* JSONRPC:: JSON Remote Procedure Call protocol * Atomic Changes:: Installing several buffer changes atomically. * Change Hooks:: Supplying functions to be run when text is changed. @end menu @@ -498,14 +500,14 @@ after point. It leaves the mark after the inserted text. The value is @code{nil}. @end deffn -@deffn Command self-insert-command count +@deffn Command self-insert-command count &optional char @cindex character insertion @cindex self-insertion -This command inserts the last character typed; it does so @var{count} -times, before point, and returns @code{nil}. Most printing characters -are bound to this command. In routine use, @code{self-insert-command} -is the most frequently called function in Emacs, but programs rarely use -it except to install it on a keymap. +This command inserts the character @var{char} (the last character typed); +it does so @var{count} times, before point, and returns @code{nil}. +Most printing characters are bound to this command. In routine use, +@code{self-insert-command} is the most frequently called function in Emacs, +but programs rarely use it except to install it on a keymap. In an interactive call, @var{count} is the numeric prefix argument. @@ -1325,9 +1327,8 @@ elements follow immediately after this element. @item (t . @var{time-flag}) This kind of element indicates that an unmodified buffer became -modified. A @var{time-flag} of the form -@code{(@var{sec-high} @var{sec-low} @var{microsec} -@var{picosec})} represents the visited file's modification time as of +modified. A @var{time-flag} that is a non-integer Lisp timestamp +represents the visited file's modification time as of when it was previously visited or saved, using the same format as @code{current-time}; see @ref{Time of Day}. A @var{time-flag} of 0 means the buffer does not correspond to any file; @@ -3184,6 +3185,95 @@ buffer to scan. Positions are relative to @var{object}. The default for @var{object} is the current buffer. @end defun +@defun text-property-search-forward prop &optional value predicate not-current +Search for the next region that has text property @var{prop} set to +@var{value} according to @var{predicate}. + +This function is modelled after @code{search-forward} and friends in +that it moves point, but it returns a structure that describes the +match instead of returning it in @code{match-beginning} and friends. + +If the text property can't be found, the function returns @code{nil}. +If it's found, point is placed at the end of the region that has this +text property match, and a @code{prop-match} structure is returned. + +@var{predicate} can either be @code{t} (which is a synonym for +@code{equal}), @code{nil} (which means ``not equal''), or a predicate +that will be called with two parameters: The first is @var{value}, and +the second is the value of the text property we're inspecting. + +If @var{not-current}, if point is in a region where we have a match, +then skip past that and find the next instance instead. + +The @code{prop-match} structure has the following accessors: +@code{prop-match-beginning} (the start of the match), +@code{prop-match-end} (the end of the match), and +@code{prop-match-value} (the value of @var{property} at the start of +the match). + +In the examples below, imagine that you're in a buffer that looks like +this: + +@example +This is a bold and here's bolditalic and this is the end. +@end example + +That is, the ``bold'' words are the @code{bold} face, and the +``italic'' word is in the @code{italic} face. + +With point at the start: + +@lisp +(while (setq match (text-property-search-forward 'face 'bold t)) + (push (buffer-substring (prop-match-beginning match) + (prop-match-end match)) + words)) +@end lisp + +This will pick out all the words that use the @code{bold} face. + +@lisp +(while (setq match (text-property-search-forward 'face nil t)) + (push (buffer-substring (prop-match-beginning match) + (prop-match-end match)) + words)) +@end lisp + +This will pick out all the bits that have no face properties, which +will result in the list @samp{("This is a " "and here's " "and this is +the end")} (only reversed, since we used @code{push}). + +@lisp +(while (setq match (text-property-search-forward 'face nil nil)) + (push (buffer-substring (prop-match-beginning match) + (prop-match-end match)) + words)) +@end lisp + +This will pick out all the regions where @code{face} is set to +something, but this is split up into where the properties change, so +the result here will be @samp{("bold" "bold" "italic")}. + +For a more realistic example where you might use this, consider that +you have a buffer where certain sections represent URLs, and these are +tagged with @code{shr-url}. + +@lisp +(while (setq match (text-property-search-forward 'shr-url nil nil)) + (push (prop-match-value match) urls)) +@end lisp + +This will give you a list of all those URLs. + +@end defun + +@defun text-property-search-backward prop &optional value predicate not-current +This is just like @code{text-property-search-backward}, but searches +backward instead. Point is placed at the beginning of the matched +region instead of the end, though. +@end defun + + @node Special Properties @subsection Properties with Special Meanings @@ -3235,6 +3325,17 @@ foreground or background color, similar to @code{(:foreground @var{color-name})} or @code{(:background @var{color-name})}. This form is supported for backward compatibility only, and should be avoided. + +@item +A cons cell of the form @w{@code{(:filtered @var{filter} +@var{face-spec})}}, that specifies the face given by @var{face-spec}, +but only if @var{filter} matches when the face is used for display. +The @var{face-spec} can use any of the forms mentioned above. The +@var{filter} should be of the form @w{@code{(:window @var{param} +@var{value})}}, which matches for windows whose parameter @var{param} +is @code{eq} to @var{value}. If the variable +@code{face-filters-always-match} is non-@code{nil}, all face filters +are deemed to have matched. @end itemize Font Lock mode (@pxref{Font Lock Mode}) works in most buffers by @@ -3617,6 +3718,12 @@ string to display, which is passed through The GNU Emacs Manual}) provides an example. @end defvar +@defvar face-filters-always-match +If this variable is non-@code{nil}, face filters that specify +attributes applied only when certain conditions are met will be deemed +to match always. +@end defvar + @node Format Properties @subsection Formatted Text Properties @@ -4529,9 +4636,9 @@ It should be somewhat more efficient on larger buffers than @cindex symmetric cipher @cindex cipher, symmetric -If compiled with GnuTLS, Emacs offers built-in cryptographic support. -Following the GnuTLS API terminology, the available tools are digests, -MACs, symmetric ciphers, and AEAD ciphers. + If compiled with GnuTLS, Emacs offers built-in cryptographic +support. Following the GnuTLS API terminology, the available tools +are digests, MACs, symmetric ciphers, and AEAD ciphers. The terms used herein, such as IV (Initialization Vector), require some familiarity with cryptography and will not be defined in detail. @@ -4549,7 +4656,7 @@ structure of the GnuTLS library. @cindex format of gnutls cryptography inputs @cindex gnutls cryptography inputs format -The inputs to GnuTLS cryptographic functions can be specified in + The inputs to GnuTLS cryptographic functions can be specified in several ways, both as primitive Emacs Lisp types or as lists. The list form is currently similar to how @code{md5} and @@ -4716,8 +4823,15 @@ IV used. @section Parsing HTML and XML @cindex parsing html -When Emacs is compiled with libxml2 support, the following functions -are available to parse HTML or XML text into Lisp object trees. + Emacs can be compiled with built-in libxml2 support. + +@defun libxml-available-p +This function returns non-@code{nil} if built-in libxml2 support is +available in this Emacs session. +@end defun + +When libxml2 support is available, the following functions can be used +to parse HTML or XML text into Lisp object trees. @defun libxml-parse-html-region start end &optional base-url discard-comments This function parses the text between @var{start} and @var{end} as @@ -4729,7 +4843,10 @@ The optional argument @var{base-url}, if non-@code{nil}, should be a string specifying the base URL for relative URLs occurring in links. If the optional argument @var{discard-comments} is non-@code{nil}, -then the parse tree is created without any comments. +any top-level comment is discarded. (This argument is obsolete and +will be removed in future Emacs versions. To remove comments, use the +@code{xml-remove-comments} utility function on the data before you +call the parsing function.) In the parse tree, each HTML node is represented by a list in which the first element is a symbol representing the node name, the second @@ -4784,9 +4901,9 @@ about syntax). @cindex DOM @cindex Document Object Model -The @acronym{DOM} returned by @code{libxml-parse-html-region} (and the -other @acronym{XML} parsing functions) is a tree structure where each -node has a node name (called a @dfn{tag}), and optional key/value + The @acronym{DOM} returned by @code{libxml-parse-html-region} (and +the other @acronym{XML} parsing functions) is a tree structure where +each node has a node name (called a @dfn{tag}), and optional key/value @dfn{attribute} list, and then a list of @dfn{child nodes}. The child nodes are either strings or @acronym{DOM} objects. @@ -4904,6 +5021,319 @@ textual nodes that just contain white-space. @end table +@node Parsing JSON +@section Parsing and generating JSON values +@cindex JSON +@cindex JavaScript Object Notation + + When Emacs is compiled with @acronym{JSON} (@dfn{JavaScript Object +Notation}) support, it provides several functions to convert +between Lisp objects and JSON values. Any JSON value can be converted +to a Lisp object, but not vice versa. Specifically: + +@itemize +@item +JSON uses three keywords: @code{true}, @code{null}, @code{false}. +@code{true} is represented by the symbol @code{t}. By default, the +remaining two are represented, respectively, by the symbols +@code{:null} and @code{:false}. + +@item +JSON only has floating-point numbers. They can represent both Lisp +integers and Lisp floating-point numbers. + +@item +JSON strings are always Unicode strings encoded in UTF-8. Lisp +strings can contain non-Unicode characters. + +@item +JSON has only one sequence type, the array. JSON arrays are +represented using Lisp vectors. + +@item +JSON has only one map type, the object. JSON objects are represented +using Lisp hashtables, alists or plists. When an alist or plist +contains several elements with the same key, Emacs uses only the first +element for serialization, in accordance with the behavior of +@code{assq}. +@end itemize + +@noindent +Note that @code{nil}, being both a valid alist and a valid plist, +represents @code{@{@}}, the empty JSON object; not @code{null}, +@code{false}, or an empty array, all of which are different JSON +values. + + If some Lisp object can't be represented in JSON, the serialization +functions will signal an error of type @code{wrong-type-argument}. +The parsing functions can also signal the following errors: + +@table @code +@item json-end-of-file +Signaled when encountering a premature end of the input text. + +@item json-trailing-content +Signaled when encountering unexpected input after the first JSON +object parsed. + +@item json-parse-error +Signaled when encountering invalid JSON syntax. +@end table + + Only top-level values (arrays and objects) can be serialized to +JSON. The subobjects within these top-level values can be of any +type. Likewise, the parsing functions will only return vectors, +hashtables, alists, and plists. + +@defun json-serialize object &rest args +This function returns a new Lisp string which contains the JSON +representation of @var{object}. The argument @var{args} is a list of +keyword/argument pairs. The following keywords are accepted: + +@table @code +@item :null-object +The value decides which Lisp object to use to represent the JSON +keyword @code{null}. It defaults to the symbol @code{:null}. + +@item :false-object +The value decides which Lisp object to use to represent the JSON +keyword @code{false}. It defaults to the symbol @code{:false}. +@end table + +@end defun + +@defun json-insert object &rest args +This function inserts the JSON representation of @var{object} into the +current buffer before point. The argument @var{args} are interpreted +as in @code{json-parse-string}. +@end defun + +@defun json-parse-string string &rest args +This function parses the JSON value in @var{string}, which must be a +Lisp string. The argument @var{args} is a list of keyword/argument +pairs. The following keywords are accepted: + +@table @code +@item :object-type +The value decides which Lisp object to use for representing the +key-value mappings of a JSON object. It can be either +@code{hash-table}, the default, to make hashtables with strings as +keys; @code{alist} to use alists with symbols as keys; or @code{plist} +to use plists with keyword symbols as keys. + +@item :null-object +The value decides which Lisp object to use to represent the JSON +keyword @code{null}. It defaults to the symbol @code{:null}. + +@item :false-object +The value decides which Lisp object to use to represent the JSON +keyword @code{false}. It defaults to the symbol @code{:false}. +@end table + +@end defun + +@defun json-parse-buffer &rest args +This function reads the next JSON value from the current buffer, +starting at point. It moves point to the position immediately after +the value if a value could be read and converted to Lisp; otherwise it +doesn't move point. The arguments @var{args} are interpreted as in +@code{json-parse-string}. +@end defun + +@node JSONRPC +@section JSONRPC communication +@cindex JSON remote procedure call protocol + +The @code{jsonrpc} library implements the @acronym{JSONRPC} +specification, version 2.0, as it is described in +@uref{http://www.jsonrpc.org/}. As the name suggests, JSONRPC is a +generic @code{Remote Procedure Call} protocol designed around +@acronym{JSON} objects, which you can convert to and from Lisp objects +(@pxref{Parsing JSON}). + +@menu +* JSONRPC Overview:: +* Process-based JSONRPC connections:: +* JSONRPC JSON object format:: +* JSONRPC deferred requests:: +@end menu + +@node JSONRPC Overview +@subsection Overview + +Quoting from the @uref{http://www.jsonrpc.org/, spec}, JSONRPC "is +transport agnostic in that the concepts can be used within the same +process, over sockets, over http, or in many various message passing +environments." + +To model this agnosticism, the @code{jsonrpc} library uses objects of +a @code{jsonrpc-connection} class, which represent a connection the +remote JSON endpoint (for details on Emacs's object system, +@pxref{Top,EIEIO,,eieio,EIEIO}). In modern object-oriented parlance, +this class is ``abstract'', i.e. the actual class of a useful +connection object used is always a subclass of it. Nevertheless, we +can define two distinct API's around the @code{jsonrpc-connection} +class: + +@enumerate + +@item A user interface for building JSONRPC applications + +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 +@code{:notification-dispatcher} initargs, which are both functions of +3 arguments: the connection object; a symbol naming the JSONRPC method +invoked remotely; and a JSONRPC "params" object. + +The function passed as @code{:request-dispatcher} is responsible for +handling the remote endpoint's requests, which expect a reply from the +local endpoint (in this case, the program you're building). Inside +that function, you may either return locally (normally) or non-locally +(error). A local return value must be a Lisp object serializable as +JSON (@pxref{Parsing JSON}). This determines a success response, and +the object is forwarded to the server as the JSONRPC "result" object. +A non-local return, achieved by calling the function +@code{jsonrpc-error}, causes an error response to be sent to the +server. The details of the accompanying JSONRPC "error" are filled +out with whatever was passed to @code{jsonrpc-error}. A non-local +return triggered by an unexpected error of any other type also causes +an error response to be sent (unless you have set +@code{debug-on-error}, in which case this should land you in the +debugger, @pxref{Error Debugging}). + +@item A inheritance interface for building JSONRPC transport implementations + +In this scenario, @code{jsonrpc-connection} is subclassed to implement +a different underlying transport strategy (for details on how to +subclass, @pxref{Inheritance,Inheritance,,eieio}). Users of the +application-building interface can then instantiate objects of this +concrete class (using the @code{make-instance} function) and connect +to JSONRPC endpoints using that strategy. + +This API has mandatory and optional parts. + +To allow its users to initiate JSONRPC contacts (notifications or +requests) or reply to endpoint requests, the method +@code{jsonrpc-connection-send} must be implemented for the subclass. + +Likewise, for handling the three types of remote contacts (requests, +notifications and responses to local requests) the transport +implementation must arrange for the function +@code{jsonrpc-connection-receive} to be called after noticing a new +JSONRPC message on the wire (whatever that "wire" may be). + +Finally, and optionally, the @code{jsonrpc-connection} subclass should +implement @code{jsonrpc-shutdown} and @code{jsonrpc-running-p} if +these concepts apply to the transport. If they do, then any system +resources (e.g. processes, timers, etc..) used listen for messages on +the wire should be released in @code{jsonrpc-shutdown}, i.e. they +should only be needed while @code{jsonrpc-running-p} is non-nil. + +@end enumerate + +@node Process-based JSONRPC connections +@subsection Process-based JSONRPC connections + +For convenience, the @code{jsonrpc} library comes built-in with a +@code{jsonrpc-process-connection} transport implementation that can +talk to local subprocesses (using the standard input and standard +output); or TCP hosts (using sockets); or any other remote endpoint +that Emacs's process object can represent (@pxref{Processes}). + +Using this transport, the JSONRPC messages are encoded on the wire as +plain text and prefaced by some basic HTTP-style enveloping headers, +such as ``Content-Length''. + +For an example of an application using this transport scheme on top of +JSONRPC, see the +@uref{https://microsoft.github.io/language-server-protocol/specification, +Language Server Protocol}. + +Along with the mandatory @code{:request-dispatcher} and +@code{:notification-dispatcher} initargs, users of the +@code{jsonrpc-process-connection} class should pass the following +initargs as keyword-value pairs to @code{make-instance}: + +@table @code +@item :process +Value must be a live process object or a function of no arguments +producing one such object. If passed a process object, that is +expected to contain an pre-established connection; otherwise, the +function is called immediately after the object is made. + +@item :on-shutdown +Value must be a function of a single argument, the +@code{jsonrpc-process-connection} object. The function is called +after the underlying process object has been deleted (either +deliberately by @code{jsonrpc-shutdown} or unexpectedly, because of +some external cause). +@end table + +@node JSONRPC JSON object format +@subsection JSON object format + +JSON objects are exchanged as Lisp plists (@pxref{Parsing JSON}): +JSON-compatible plists are handed to the dispatcher functions and, +likewise, JSON-compatible plists should be given to +@code{jsonrpc-notify}, @code{jsonrpc-request} and +@code{jsonrpc-async-request}. + +To facilitate handling plists, this library make liberal use of +@code{cl-lib} library and suggests (but doesn't force) its clients to +do the same. A macro @code{jsonrpc-lambda} can be used to create a +lambda for destructuring a JSON-object like in this example: + +@example +(jsonrpc-async-request + myproc :frobnicate `(:foo "trix") + :success-fn (jsonrpc-lambda (&key bar baz &allow-other-keys) + (message "Server replied back with %s and %s!" + bar baz)) + :error-fn (jsonrpc-lambda (&key code message _data) + (message "Sadly, server reports %s: %s" + code message))) +@end example + +@node JSONRPC deferred requests +@subsection Deferred requests + +In many @acronym{RPC} situations, synchronization between the two +communicating endpoints is a matter of correctly designing the RPC +application: when synchronization is needed, requests (which are +blocking) should be used; when it isn't, notifications should suffice. +However, when Emacs acts as one of these endpoints, asynchronous +events (e.g. timer- or process-related) may be triggered while there +is still uncertainty about the state of the remote endpoint. +Furthermore, acting on these events may only sometimes demand +synchronization, depending on the event's specific nature. + +The @code{:deferred} keyword argument to @code{jsonrpc-request} and +@code{jsonrpc-async-request} is designed to let the caller indicate +that the specific request needs synchronization and its actual +issuance may be delayed to the future, until some condition is +satisfied. Specifying @code{:deferred} for a request doesn't mean it +@emph{will} be delayed, only that it @emph{can} be. If the request +isn't sent immediately, @code{jsonrpc} will make renewed efforts to +send it at certain key times during communication, such as when +receiving or sending other messages to the endpoint. + +Before any attempt to send the request, the application-specific +conditions are checked. Since the @code{jsonrpc} library can't known +what these conditions are, the programmer may use the +@code{jsonrpc-connection-ready-p} generic function (@pxref{Generic +Functions}) to specify them. The default method for this function +returns @code{t}, but you can add overriding methods that return +@code{nil} in some situations, based on the arguments passed to it, +which are the @code{jsonrpc-connection} object (@pxref{JSONRPC +Overview}) and whichever value you passed as the @code{:deferred} +keyword argument. + @node Atomic Changes @section Atomic Change Groups @cindex atomic changes @@ -5049,8 +5479,8 @@ making. When that happens, the arguments to individual changes are made, but won't necessarily be the minimal such region, and the arguments to each successive call of @code{after-change-functions} will then delimit the part of text being -changed exactly. In general, we advise to use either before- or the -after-change hooks, but not both. +changed exactly. In general, we advise using either the before- or +the after-change hook, but not both. @defmac combine-after-change-calls body@dots{} The macro executes @var{body} normally, but arranges to call the @@ -5074,6 +5504,30 @@ because it may lead to inefficient behavior for some change hook functions. @end defmac +@defmac combine-change-calls beg end body@dots{} +This executes @var{body} normally, except any buffer changes it makes +do not trigger the calls to @code{before-change-functions} and +@code{after-change-functions}. Instead there is a single call of each +of these hooks for the region enclosed by @var{beg} and @var{end}, the +parameters supplied to @code{after-change-functions} reflecting the +changes made to the size of the region by @var{body}. + +The result of this macro is the result returned by @var{body}. + +This macro is useful when a function makes a possibly large number of +repetitive changes to the buffer, and the change hooks would otherwise +take a long time to run, were they to be run for each individual +buffer modification. Emacs itself uses this macro, for example, in +the commands @code{comment-region} and @code{uncomment-region}. + +@strong{Warning:} You must not alter the values of +@code{before-change-functions} or @code{after-change-function} within +@var{body}. + +@strong{Warning:} You must not make any buffer changes outside of the +region specified by @var{beg} and @var{end}. +@end defmac + @defvar first-change-hook This variable is a normal hook that is run whenever a buffer is changed that was previously in the unmodified state. diff --git a/doc/lispref/threads.texi b/doc/lispref/threads.texi index 7b14ab5a730..db68f9192bd 100644 --- a/doc/lispref/threads.texi +++ b/doc/lispref/threads.texi @@ -45,6 +45,7 @@ closure are shared by any threads invoking the closure. * Basic Thread Functions:: Basic thread functions. * Mutexes:: Mutexes allow exclusive access to data. * Condition Variables:: Inter-thread events. +* The Thread List:: Show the active threads. @end menu @node Basic Thread Functions @@ -75,8 +76,8 @@ thread, @code{nil} otherwise. @defun thread-join thread Block until @var{thread} exits, or until the current thread is -signaled. If @var{thread} has already exited, this returns -immediately. +signaled. It returns the result of the @var{thread} function. If +@var{thread} has already exited, this returns immediately. @end defun @defun thread-signal thread error-symbol data @@ -87,6 +88,9 @@ thread, then this just calls @code{signal} immediately. Otherwise, If @var{thread} was blocked by a call to @code{mutex-lock}, @code{condition-wait}, or @code{thread-join}; @code{thread-signal} will unblock it. + +If @var{thread} is the main thread, the signal is not propagated +there. Instead, it is shown as message in the main thread. @end defun @defun thread-yield @@ -127,15 +131,21 @@ Return a list of all the live thread objects. A new list is returned by each invocation. @end defun +@defvar main-thread +This variable keeps the main thread Emacs is running, or @code{nil} if +Emacs is compiled without thread support. +@end defvar + When code run by a thread signals an error that is unhandled, the thread exits. Other threads can access the error form which caused the thread to exit using the following function. -@defun thread-last-error +@defun thread-last-error &optional cleanup This function returns the last error form recorded when a thread exited due to an error. Each thread that exits abnormally overwrites the form stored by the previous thread's error with a new value, so -only the last one can be accessed. +only the last one can be accessed. If @var{cleanup} is +non-@code{nil}, the stored form is reset to @code{nil}. @end defun @node Mutexes @@ -262,3 +272,53 @@ Return the name of @var{cond}, as passed to Return the mutex associated with @var{cond}. Note that the associated mutex cannot be changed. @end defun + +@node The Thread List +@section The Thread List + +@cindex thread list +@cindex list of threads +@findex list-threads +The @code{list-threads} command lists all the currently alive threads. +In the resulting buffer, each thread is identified either by the name +passed to @code{make-thread} (@pxref{Basic Thread Functions}), or by +its unique internal identifier if it was not created with a name. The +status of each thread at the time of the creation or last update of +the buffer is shown, in addition to the object the thread was blocked +on at the time, if it was blocked. + +@defvar thread-list-refresh-seconds +The @file{*Threads*} buffer will automatically update twice per +second. You can make the refresh rate faster or slower by customizing +this variable. +@end defvar + +Here are the commands available in the thread list buffer: + +@table @kbd + +@cindex backtrace of thread +@cindex thread backtrace +@item b +Show a backtrace of the thread at point. This will show where in its +code the thread had yielded or was blocked at the moment you pressed +@kbd{b}. Be aware that the backtrace is a snapshot; the thread could +have meanwhile resumed execution, and be in a different state, or +could have exited. + +You may use @kbd{g} in the thread's backtrace buffer to get an updated +backtrace, as backtrace buffers do not automatically update. +@xref{Backtraces}, for a description of backtraces and the other +commands which work on them. + +@item s +Signal the thread at point. After @kbd{s}, type @kbd{q} to send a +quit signal or @kbd{e} to send an error signal. Threads may implement +handling of signals, but the default behavior is to exit on any +signal. Therefore you should only use this command if you understand +how to restart the target thread, because your Emacs session may +behave incorrectly if necessary threads are killed. + +@item g +Update the list of threads and their statuses. +@end table diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 7f0fcffaaf1..3940dd89246 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -2263,6 +2263,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. @@ -2607,6 +2613,12 @@ suitable @code{window-height} or @code{window-width} entry, see above. If splitting the selected window fails and there is a non-dedicated window below the selected one showing some other buffer, this function tries to use that window for showing @var{buffer}. + +If @var{alist} contains a @code{window-min-height} entry, this +function ensures that the window used is or can become at least as +high as specified by that entry's value. Note that this is only a +guarantee. In order to actually resize the window used, @var{alist} +must also provide an appropriate @code{window-height} entry. @end defun @defun display-buffer-at-bottom buffer alist @@ -2790,6 +2802,22 @@ The value specifies an alist of window parameters to give the chosen window. All action functions that choose a window should process this entry. +@vindex window-min-height@r{, a buffer display action alist entry} +@item window-min-height +The value specifies a minimum height of the window used, in lines. If +a window is not or cannot be made as high as specified by this entry, +the window is not considered for use. The only client of this entry +is presently @code{display-buffer-below-selected}. + +Note that providing such an entry alone does not necessarily make the +window as tall as specified by its value. To actually resize an +existing window or make a new window as tall as specified by that +value, a @code{window-height} entry specifying that value should be +provided as well. Such a @code{window-height} entry can, however, +specify a completely different value or ask the window height to be +fit to that of its buffer in which case the @code{window-min-height} +entry provides the guaranteed minimum height of the window used. + @vindex window-height@r{, a buffer display action alist entry} @item window-height The value specifies whether and how to adjust the height of the chosen @@ -4850,6 +4878,13 @@ line reappears after the echo area momentarily displays the message @samp{End of buffer}. @end deffn +@deffn Command scroll-other-window-down &optional count +This function scrolls the text in another window downward @var{count} +lines. Negative values of @var{count}, or @code{nil}, are handled as +in @code{scroll-down}. In other respects, it behaves the same way as +@code{scroll-other-window} does. +@end deffn + @defvar other-window-scroll-buffer If this variable is non-@code{nil}, it tells @code{scroll-other-window} which buffer's window to scroll. @@ -4952,7 +4987,7 @@ beginning or end of the buffer (depending on scrolling direction); only if point is already on that position do they signal an error. @end defopt -@deffn Command recenter &optional count +@deffn Command recenter &optional count redisplay @cindex centering point This function scrolls the text in the selected window so that point is displayed at a specified vertical position within the window. It does @@ -4966,8 +5001,12 @@ line in the window. If @var{count} is @code{nil} (or a non-@code{nil} list), @code{recenter} puts the line containing point in the middle of the -window. If @var{count} is @code{nil}, this function may redraw the -frame, according to the value of @code{recenter-redisplay}. +window. If @var{count} is @code{nil} and @var{redisplay} is +non-@code{nil}, this function may redraw the frame, according to the +value of @code{recenter-redisplay}. Thus, omitting the second +argument can be used to countermand the effect of +@code{recenter-redisplay} being non-@code{nil}. Interactive calls +pass non-‘nil’ for @var{redisplay}. When @code{recenter} is called interactively, @var{count} is the raw prefix argument. Thus, typing @kbd{C-u} as the prefix sets the @@ -4995,8 +5034,9 @@ respect to the entire window group. @defopt recenter-redisplay If this variable is non-@code{nil}, calling @code{recenter} with a -@code{nil} argument redraws the frame. The default value is -@code{tty}, which means only redraw the frame if it is a tty frame. +@code{nil} @var{count} argument and non-@code{nil} @var{redisplay} +argument redraws the frame. The default value is @code{tty}, which +means only redraw the frame if it is a tty frame. @end defopt @deffn Command recenter-top-bottom &optional count @@ -5720,9 +5760,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} @@ -6016,6 +6057,14 @@ whether a specific window has changed size, compare the return values of @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 diff --git a/doc/man/emacsclient.1 b/doc/man/emacsclient.1 index 5aaa6d1f083..24ca1c9a468 100644 --- a/doc/man/emacsclient.1 +++ b/doc/man/emacsclient.1 @@ -94,6 +94,7 @@ open a new Emacs frame on the current terminal .TP .B \-s, \-\-socket-name=FILENAME use socket named FILENAME for communication. +This can also be specified via the EMACS_SOCKET_NAME environment variable. .TP .B \-V, \-\-version print version information and exit diff --git a/doc/man/etags.1 b/doc/man/etags.1 index 57120e78dda..7cc501cc496 100644 --- a/doc/man/etags.1 +++ b/doc/man/etags.1 @@ -145,7 +145,7 @@ May be used (only once) in place of a file name on the command line. \fBetags\fP will read from standard input and mark the produced tags as belonging to the file \fBFILE\fP. .TP -\fB \-Q, \-\-class\-qualify\fP +\fB\-Q, \-\-class\-qualify\fP Qualify tag names with their class name in C++, ObjC, Java, and Perl. This produces tag names of the form \fIclass\fP\fB::\fP\fImember\fP for C++ and Perl, diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index d02f42bbeb9..a03efaf8bef 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -224,13 +224,13 @@ ${buildinfodir}/tramp.info tramp.html: ${srcdir}/trampver.texi .PHONY: mostlyclean clean distclean bootstrap-clean maintainer-clean mostlyclean: - rm -f *.aux *.log *.toc *.c[mp] *.c[mp]s *.fn *.fns \ - *.ky *.kys *.op *.ops *.p[gj] *.p[gj]s *.sc *.scs *.ss \ - *.t[gp] *.t[gp]s *.vr *.vrs + rm -f ./*.aux ./*.log ./*.toc ./*.c[mp] ./*.c[mp]s ./*.fn ./*.fns \ + ./*.ky ./*.kys ./*.op ./*.ops ./*.p[gj] ./*.p[gj]s ./*.sc ./*.scs ./*.ss \ + ./*.t[gp] ./*.t[gp]s ./*.vr ./*.vrs rm -f gnustmp* clean: mostlyclean - rm -f *.dvi *.html *.pdf *.ps + rm -f ./*.dvi ./*.html ./*.pdf ./*.ps distclean: clean rm -f Makefile diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi index e467fc135f3..495d9f53e15 100644 --- a/doc/misc/auth.texi +++ b/doc/misc/auth.texi @@ -86,7 +86,7 @@ password (known as the secret). Similarly, the auth-source library supports multiple storage backend, currently either the classic ``netrc'' backend, examples of which you -can see later in this document, the Secret Service API, and pass, the +can see later in this document, JSON files, the Secret Service API, and pass, the standard unix password manager. This is done with EIEIO-based backends and you can write your own if you want. @@ -169,6 +169,9 @@ get fancy, the default and simplest configuration is: ;;; use pass (@file{~/.password-store}) ;;; (@pxref{The Unix password store}) (setq auth-sources '(password-store)) +;;; JSON data in format [@{ "machine": "SERVER", +;;; "login": "USER", "password": "PASSWORD" @}...] +(setq auth-sources '("~/.authinfo.json.gpg")) @end lisp By adding multiple entries to @code{auth-sources} with a particular @@ -235,6 +238,16 @@ don't use a port entry, you match any Tramp method, as explained earlier. Since Tramp has about 88 connection methods, this may be necessary if you have an unusual (see earlier comment on those) setup. +The netrc format is directly translated into JSON, if you are into +that sort of thing. Just point to a JSON file with entries like this: + +@example +[ + @{ "machine": "yourmachine.com", "port": "http", + "login": "testuser", "password": "testpass" @} +] +@end example + @node Multiple GMail accounts with Gnus @chapter Multiple GMail accounts with Gnus @@ -335,25 +348,36 @@ Returns all the item labels of @var{collection} as a list. @defun secrets-create-item collection item password &rest attributes This function creates a new item in @var{collection} with label -@var{item} and password @var{password}. @var{attributes} are -key-value pairs set for the created item. The keys are keyword -symbols, starting with a colon. Example: +@var{item} and password @var{password}. The label @var{item} does not +have to be unique in @var{collection}. @var{attributes} are key-value +pairs set for the created item. The keys are keyword symbols, +starting with a colon. Example: @example -;;; The session "session", the label is "my item" -;;; and the secret (password) is "geheim" +;;; The session is "session", the label is "my item" +;;; and the secret (password) is "geheim". (secrets-create-item "session" "my item" "geheim" :method "sudo" :user "joe" :host "remote-host") @end example + +The key @code{:xdg:schema} determines the scope of the item to be +generated, i.e.@: for which applications the item is intended for. +This is just a string like "org.freedesktop.NetworkManager.Mobile" or +"org.gnome.OnlineAccounts", the other required keys are determined by +this. If no @code{:xdg:schema} is given, +"org.freedesktop.Secret.Generic" is used by default. @end defun @defun secrets-get-secret collection item -Return the secret of item labeled @var{item} in @var{collection}. -If there is no such item, return @code{nil}. +Return the secret of item labeled @var{item} in @var{collection}. If +there are several items labeled @var{item}, it is undefined which one +is returned. If there is no such item, return @code{nil}. @end defun @defun secrets-delete-item collection item -This function deletes item @var{item} in @var{collection}. +This function deletes item @var{item} in @var{collection}. If there +are several items labeled @var{item}, it is undefined which one is +deleted. @end defun The lookup attributes, which are specified during creation of a @@ -363,18 +387,20 @@ from a given secret item and they can be used for searching of items. @defun secrets-get-attribute collection item attribute Returns the value of key @var{attribute} of item labeled @var{item} in -@var{collection}. If there is no such item, or the item doesn't own -this key, the function returns @code{nil}. +@var{collection}. If there are several items labeled @var{item}, it +is undefined which one is returned. If there is no such item, or the +item doesn't own this key, the function returns @code{nil}. @end defun @defun secrets-get-attributes collection item Return the lookup attributes of item labeled @var{item} in -@var{collection}. If there is no such item, or the item has no -attributes, it returns @code{nil}. Example: +@var{collection}. If there are several items labeled @var{item}, it +is undefined which one is returned. If there is no such item, or the +item has no attributes, it returns @code{nil}. Example: @example (secrets-get-attributes "session" "my item") - @result{} ((:user . "joe") (:host ."remote-host")) + @result{} ((:user . "joe") (:host . "remote-host")) @end example @end defun diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi index 59125771ac5..1981988501c 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -32717,7 +32717,7 @@ create an intermediate set. (while (> n 0) (if (oddp n) (setq count (1+ count))) - (setq n (lsh n -1))) + (setq n (ash n -1))) count)) @end smallexample @@ -32761,7 +32761,7 @@ routines are especially fast when dividing by an integer less than (let ((count 0)) (while (> n 0) (setq count (+ count (logand n 1)) - n (lsh n -1))) + n (ash n -1))) count)) @end smallexample @@ -32774,7 +32774,7 @@ uses. The @code{idivmod} function does an integer division, returning both the quotient and the remainder at once. Again, note that while it -might seem that @samp{(logand n 511)} and @samp{(lsh n -9)} are +might seem that @samp{(logand n 511)} and @samp{(ash n -9)} are more efficient ways to split off the bottom nine bits of @code{n}, actually they are less efficient because each operation is really a division by 512 in disguise; @code{idivmod} allows us to do the diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 6ce0b72aa5f..32b5076c902 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -784,7 +784,7 @@ default. Some examples: (cl-deftype null () '(satisfies null)) ; predefined (cl-deftype list () '(or null cons)) ; predefined (cl-deftype unsigned-byte (&optional bits) - (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits))))) + (list 'integer 0 (if (eq bits '*) bits (1- (ash 1 bits))))) (unsigned-byte 8) @equiv{} (integer 0 255) (unsigned-byte) @equiv{} (integer 0 *) unsigned-byte @equiv{} (integer 0 *) @@ -1709,9 +1709,9 @@ but surrounds the loop with an implicit @code{nil} block. The body is executed with @var{var} bound to the integers from zero (inclusive) to @var{count} (exclusive), in turn. Then @c FIXME lispref does not state this part explicitly, could move this there. -the @code{result} form is evaluated with @var{var} bound to the total +the @var{result} form is evaluated with @var{var} bound to the total number of iterations that were done (i.e., @code{(max 0 @var{count})}) -to get the return value for the loop form. +to get the return value for the loop form. Use of @var{result} is deprecated. @end defmac @defmac cl-do-symbols (var [obarray [result]]) forms@dots{} diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi index c2630e6be66..b6a9d23f7dc 100644 --- a/doc/misc/dired-x.texi +++ b/doc/misc/dired-x.texi @@ -92,7 +92,6 @@ For @file{dired-x.el} as distributed with GNU Emacs @value{EMACSVER}. * Introduction:: * Installation:: * Omitting Files in Dired:: -* Local Variables:: * Shell Command Guessing:: * Virtual Dired:: * Advanced Mark Commands:: @@ -478,77 +477,6 @@ Loading @file{dired-x.el} will install Dired Omit by putting call @code{dired-extra-startup}, which in turn calls @code{dired-omit-startup} in your @code{dired-mode-hook}. -@node Local Variables -@chapter Local Variables for Dired Directories - -@cindex Local Variables for Dired Directories -@vindex dired-local-variables-file -@vindex dired-enable-local-variables -@noindent -This Dired-X feature is obsolete as of Emacs 24.1. The standard Emacs -directory local variables mechanism (@pxref{Directory -Variables,,,emacs,The GNU Emacs manual}) replaces it. For an example of -the new mechanisms, @pxref{Omitting Variables}. - -When Dired visits a directory, it looks for a file whose name is the -value of variable @code{dired-local-variables-file} (default: @file{.dired}). -If such a file is found, Dired will temporarily insert it into the Dired -buffer and run @code{hack-local-variables}. - -@noindent -For example, if the user puts - -@example -Local Variables: -dired-actual-switches: "-lat" -dired-omit-mode: t -End: -@end example - -@noindent -into a file called @file{.dired} in a directory then when that directory is -viewed it will be - -@enumerate -@item -sorted by date -@item -omitted automatically -@end enumerate - -@noindent -You can set @code{dired-local-variables-file} to @code{nil} to suppress this. -The value of @code{dired-enable-local-variables} controls if and how these -local variables are read. This variable exists so that it may override the -default value of @code{enable-local-variables}. - -@noindent -Please see the GNU Emacs Manual to learn more about local variables. -@xref{File Variables,Local Variables in Files,Local Variables in -Files,emacs,The GNU Emacs Manual}. - -@noindent -The following variables affect Dired Local Variables - -@table @code -@vindex dired-local-variables-file -@item dired-local-variables-file -Default: @code{".dired"} - -If non-@code{nil}, file name for local variables for Dired. If Dired finds a -file with that name in the current directory, it will temporarily insert it -into the Dired buffer and run @code{hack-local-variables}. - -@vindex dired-enable-local-variables -@item dired-enable-local-variables -Default: @code{t} - -Controls the use of local-variables lists in Dired. This variable -temporarily overrides the value of @code{enable-local-variables} when -the Dired Local Variables are hacked. It takes the same values as that -variable. A value of @code{nil} means to ignore any Dired Local Variables. -@end table - @node Shell Command Guessing @chapter Shell Command Guessing @cindex Guessing shell commands for files. diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi index 513461d0e0f..6d5c1b93a94 100644 --- a/doc/misc/ede.texi +++ b/doc/misc/ede.texi @@ -1824,7 +1824,7 @@ This class implements the @code{ede-cpp-root} project type. @table @code @item :include-path Type: @code{list} @* -Default Value: @code{(quote ("/include" "../include/"))} +Default Value: @code{("/include" "../include/")} The default locate function expands filenames within a project. If a header file (.h, .hh, etc.)@: name is expanded, and @@ -2262,14 +2262,14 @@ The variable GNUSTEP_INSTALLATION_DOMAIN is set at this value. @item :preamble Type: @code{(or null list)} @* -Default Value: @code{(quote ("GNUmakefile.preamble"))} +Default Value: @code{("GNUmakefile.preamble")} The auxiliary makefile for additional variables. Included just before the specific target files. @item :postamble Type: @code{(or null list)} @* -Default Value: @code{(quote ("GNUmakefile.postamble"))} +Default Value: @code{("GNUmakefile.postamble")} The auxiliary makefile for additional rules. Included just after the specific target files. diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi index 443aae3dbd5..c4ef1da3158 100644 --- a/doc/misc/ediff.texi +++ b/doc/misc/ediff.texi @@ -1147,7 +1147,7 @@ file (unlike what the @code{patch} utility would usually do). Instead, the source file retains its name and the result of applying the patch is placed in a temporary file that has the suffix @file{_patched} attached. Generally, this applies to files that are handled using black magic, such -as special file handlers (ange-ftp and some compression and encryption +as special file name handlers (ange-ftp and some compression and encryption packages also use this method). Regular files are treated by the @code{patch} utility in the usual manner, diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi index 4c0d17f9a7b..485776e1c73 100644 --- a/doc/misc/efaq.texi +++ b/doc/misc/efaq.texi @@ -1570,38 +1570,68 @@ exhibits all the colors Emacs knows about on the current display. Syntax highlighting is on by default since version 22.1. +@cindex direct color in terminals Emacs 26.1 and later support direct color mode in terminals. If Emacs finds Terminfo capabilities @samp{setb24} and @samp{setf24}, 24-bit direct color mode is used. The capability strings are expected to take one 24-bit pixel value as argument and transform the pixel to a string that can be used to send 24-bit colors to the terminal. -There aren't yet any standard terminal type definitions that would -support the capabilities, but Emacs can be invoked with a custom -definition as shown below. +Standard terminal definitions don't support these capabilities and +therefore custom definition is needed. @example -$ cat terminfo-24bit.src +$ cat terminfo-custom.src -# Use colon separators. -xterm-24bit|xterm with 24-bit direct color mode, +xterm-emacs|xterm with 24-bit direct color mode for Emacs, use=xterm-256color, - setb24=\E[48:2:%p1%@{65536@}%/%d:%p1%@{256@}%/%@{255@}%&%d:%p1%@{255@}%&%dm, - setf24=\E[38:2:%p1%@{65536@}%/%d:%p1%@{256@}%/%@{255@}%&%d:%p1%@{255@}%&%dm, -# Use semicolon separators. -xterm-24bits|xterm with 24-bit direct color mode, - use=xterm-256color, - setb24=\E[48;2;%p1%@{65536@}%/%d;%p1%@{256@}%/%@{255@}%&%d;%p1%@{255@}%&%dm, - setf24=\E[38;2;%p1%@{65536@}%/%d;%p1%@{256@}%/%@{255@}%&%d;%p1%@{255@}%&%dm, + setb24=\E[48\:2\:\:%p1%@{65536@}%/%d\:%p1%@{256@}%/%@{255@}%&\ + %d\:%p1%@{255@}%&%dm, + setf24=\E[38\:2\:\:%p1%@{65536@}%/%d\:%p1%@{256@}%/%@{255@}%&\ + %d\:%p1%@{255@}%&%dm, + +$ tic -x -o ~/.terminfo terminfo-custom.src + +$ TERM=xterm-emacs emacs -nw +@end example + +@cindex 24-bit direct color mode +Emacs 27.1 and later support Terminfo capability @samp{RGB} for +detecting 24-bit direct color mode. Multiple standard terminal +definitions support this capability. + +@example +$ TERM=xterm-direct infocmp | grep seta[bf] + + setab=\E[%?%p1%@{8@}%<%t4%p1%d%e48\:2\:\:%p1%@{65536@}%/\ + %d\:%p1%@{256@}%/%@{255@}%&%d\:%p1%@{255@}%&%d%;m, + setaf=\E[%?%p1%@{8@}%<%t3%p1%d%e38\:2\:\:%p1%@{65536@}%/\ + %d\:%p1%@{256@}%/%@{255@}%&%d\:%p1%@{255@}%&%d%;m, + +$ TERM=xterm-direct emacs -nw +@end example + +If your terminal is incompatible with XTerm, you may have to use +another @env{TERM} definition. Any terminal whose name includes +@samp{direct} should be a candidate. The @command{toe} command can be +used to find out which of these are installed on your system: -$ tic -x -o ~/.terminfo terminfo-24bit.src +@example +$ toe | grep '\-direct' -$ TERM=xterm-24bit emacs -nw +konsole-direct konsole with direct-color indexing +vte-direct vte with direct-color indexing +st-direct st with direct-color indexing +xterm-direct2 xterm with direct-color indexing (old) +xterm-direct xterm with direct-color indexing @end example -Currently there's no standard way to determine whether a terminal -supports direct color mode. If such standard arises later on, support -for @samp{setb24} and @samp{setf24} may be removed. +Terminals with @samp{RGB} capability treat pixels #000001 - #000007 as +indexed colors to maintain backward compatibility with applications +that are unaware of direct color mode. Therefore the seven darkest +blue shades may not be available. If this is a problem, you can +always use custom terminal definition with @samp{setb24} and +@samp{setf24}. @node Debugging a customization file @section How do I debug a @file{.emacs} file? @@ -1975,9 +2005,18 @@ or by invoking @code{server-start} from @file{.emacs}: (if (@var{some conditions are met}) (server-start)) @end lisp -When this is done, Emacs creates a Unix domain socket named -@file{server} in @file{/tmp/emacs@var{userid}}. See -@code{server-socket-dir}. +When this is done, Emacs by default creates a Unix domain socket named +@file{server} in a well-known directory, typically +@file{$XDG_RUNTIME_DIR/emacs} if Emacs is running under an X Window System +desktop and @file{$TMPDIR/emacs@var{userid}} otherwise. See the variable +@code{server-socket-dir}. Traditionally, Emacs used +@file{$TMPDIR/emacs@var{userid}} even when running under an X desktop; +if you prefer this traditional (and less-secure) behavior, you +can set the environment variable @env{EMACS_SOCKET_NAME} to +@samp{$TMPDIR/emacs@var{userid}/server} before invoking Emacs and +@samp{emacsclient}, although it will be your responsibility to create +the directory @samp{$TMPDIR/emacs@var{userid}} with appropriate +ownership and permissions. To get your news reader, mail reader, etc., to invoke @samp{emacsclient}, try setting the environment variable @code{EDITOR} @@ -2958,7 +2997,7 @@ Emacs compiled on a 64-bit machine can handle much larger buffers. @cindex Shell buffer, echoed commands and @samp{^M} in @cindex Echoed commands in @code{shell-mode} -Try typing @kbd{M-x shell-strip-ctrl-m @key{RET}} while in @code{shell-mode} to +Try typing @kbd{M-x comint-strip-ctrl-m @key{RET}} while in @code{shell-mode} to make them go away. If that doesn't work, you have several options: For @code{tcsh}, put this in your @file{.cshrc} (or @file{.tcshrc}) @@ -3011,7 +3050,7 @@ characters from the buffer by adding this to your @file{.emacs} init file: @smalllisp -(add-hook 'comint-output-filter-functions 'shell-strip-ctrl-m) +(add-hook 'comint-output-filter-functions #'comint-strip-ctrl-m) @end smalllisp On a related note: if your shell is echoing your input line in the shell @@ -3733,7 +3772,7 @@ to bind the key is in the kill ring, and can be yanked into your command are required. For example, @lisp -(global-set-key (quote [f1]) (quote help-for-help)) +(global-set-key [f1] 'help-for-help) @end lisp @noindent @@ -3744,7 +3783,7 @@ For example, in TeX mode, a local binding might be @lisp (add-hook 'tex-mode-hook (lambda () - (local-set-key (quote [f1]) (quote help-for-help)))) + (local-set-key [f1] 'help-for-help))) @end lisp @@ -4538,7 +4577,7 @@ these systems, you should configure @code{movemail} to use @code{flock}. @c isaacson@@seas.upenn.edu Ron Isaacson says: When you hit -@kbd{r} to reply in Rmail, by default it CCs all of the original +@kbd{r} to reply in Rmail, by default it Ccs all of the original recipients (everyone on the original @samp{To} and @samp{CC} lists). With a prefix argument (i.e., typing @kbd{C-u} before @kbd{r}), it replies only to the sender. However, going through the whole diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi index 9eb18f92ca1..123375ce7a4 100644 --- a/doc/misc/emacs-mime.texi +++ b/doc/misc/emacs-mime.texi @@ -404,12 +404,12 @@ variable will cause @samp{text/html} parts to be treated as attachments. @item mm-text-html-renderer @vindex mm-text-html-renderer -This selects the function used to render @acronym{HTML}. The predefined -renderers are selected by the symbols @code{shr}, @code{gnus-w3m}, -@code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more -information about emacs-w3m}, @code{links}, @code{lynx}, -@code{w3m-standalone} or @code{html2text}. If @code{nil} use an -external viewer. You can also specify a function, which will be +This selects the function used to render @acronym{HTML}. The +predefined renderers are selected by the symbols @code{shr}, +@code{gnus-w3m}, @code{w3m}@footnote{See +@uref{http://emacs-w3m.namazu.org/} for more information about +emacs-w3m}, @code{links}, @code{lynx}, @code{w3m-standalone} or +@code{html2text}. You can also specify a function, which will be called with a @acronym{MIME} handle as the argument. @item mm-html-inhibit-images @@ -708,7 +708,7 @@ RFC822 date when the part was read (@code{Content-Disposition}). @item recipients Who to encrypt/sign the part to. This field is used to override any -auto-detection based on the To/CC headers. +auto-detection based on the To/Cc headers. @item sender Identity used to sign the part. This field is used to override the @@ -1524,45 +1524,54 @@ many mailers don't support it. @xref{rfc2231}. @section time-date While not really a part of the @acronym{MIME} library, it is convenient to -document this library here. It deals with parsing @code{Date} headers +document time conversion functions often used when parsing @code{Date} headers and manipulating time. (Not by using tesseracts, though, I'm sorry to say.) -These functions convert between five formats: A date string, an Emacs -time structure, a decoded time list, a second number, and a day number. +These functions convert between five formats: A date string, a Lisp +timestamp, a decoded time list, a second number, and a day number. Here's a bunch of time/date/second/day examples: @example (parse-time-string "Sat Sep 12 12:21:54 1998 +0200") -@result{} (54 21 12 12 9 1998 6 nil 7200) +@result{} (54 21 12 12 9 1998 6 -1 7200) -(date-to-time "Sat Sep 12 12:21:54 1998 +0200") -@result{} (13818 19266) +(encode-time (date-to-time "Sat Sep 12 12:21:54 1998 +0200") + 1000000) +@result{} (905595714000000 . 1000000) -(parse-iso8601-time-string "1998-09-12T12:21:54+0200") -@result{} (13818 19266) +(encode-time (parse-iso8601-time-string "1998-09-12T12:21:54+0200") + 1000000) +@result{} (905595714000000 . 1000000) -(float-time '(13818 19266)) +(float-time '(905595714000000 . 1000000)) @result{} 905595714.0 -(seconds-to-time 905595714.0) -@result{} (13818 19266 0 0) +(encode-time 905595714.0 1000000) +@result{} (905595714000000 . 1000000) -(time-to-days '(13818 19266)) +(time-to-days '(905595714000000 . 1000000)) @result{} 729644 -(days-to-time 729644) -@result{} (961933 512) +(encode-time (days-to-time 729644) 1000000) +@result{} (63041241600000000 . 1000000) -(time-since '(13818 19266)) -@result{} (6797 9607 984839 247000) +(encode-time (time-since '(905595714000000 . 1000000)) + 1000000) +@result{} (631963244775642171 . 1000000000) -(time-less-p '(13818 19266) '(13818 19145)) +(time-less-p '(905595714000000 . 1000000) + '(905595593000000000 . 1000000000)) @result{} nil -(time-subtract '(13818 19266) '(13818 19145)) -@result{} (0 121) +(time-equal-p '(905595593000000000 . 1000000000) + '(905595593000000 . 1000000 )) +@result{} t + +(time-subtract '(905595714000000 . 1000000) + '(905595593000000000 . 1000000000)) +@result{} (121000000000 . 1000000000) (days-between "Sat Sep 12 12:21:54 1998 +0200" "Sat Sep 07 12:21:54 1998 +0200") @@ -1571,13 +1580,13 @@ Here's a bunch of time/date/second/day examples: (date-leap-year-p 2000) @result{} t -(time-to-day-in-year '(13818 19266)) +(time-to-day-in-year '(905595714000000 . 1000000)) @result{} 255 (time-to-number-of-days (time-since (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT"))) -@result{} 4314.095589286675 +@result{} 6472.722661506652 @end example And finally, we have @code{safe-date-to-time}, which does the same as @@ -1592,22 +1601,24 @@ An RFC822 (or similar) date string. For instance: @code{"Sat Sep 12 12:21:54 1998 +0200"}. @item time -An internal Emacs time. For instance: @code{(13818 26466 0 0)}. +A Lisp timestamp. +For instance: @code{(905595714000000 . 1000000)}. @item seconds -A floating point representation of the internal Emacs time. For -instance: @code{905595714.0}. +An integer or floating point count of seconds. For instance: +@code{905595714.0}, @code{905595714}. @item days An integer number representing the number of days since 00000101. For instance: @code{729644}. @item decoded time -A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 t +A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 nil 7200)}. @end table -All the examples above represent the same moment. +All the examples above represent the same moment, except that +@var{days} represents the day containing the moment. These are the functions available: @@ -1618,8 +1629,9 @@ Take a date and return a time. @item float-time Take a time and return seconds. (This is a built-in function.) -@item seconds-to-time -Take seconds and return a time. +@item encode-time +Take seconds (and other ways to represent time, notably decoded time +lists), and return a time. @item time-to-days Take a time and return days. @@ -1641,6 +1653,10 @@ return a ``zero'' time. Take two times and say whether the first time is less (i.e., earlier) than the second time. (This is a built-in function.) +@item time-equal-p +Check whether two time values are equal. The time values need not be +in the same format. (This is a built-in function.) + @item time-since Take a time and return a time saying how long it was since that time. @@ -1845,11 +1861,23 @@ Interface functions: @table @code @item mailcap-parse-mailcaps @findex mailcap-parse-mailcaps +@vindex mailcap-prefer-mailcap-viewers Parse the @file{~/.mailcap} file. @item mailcap-mime-info Takes a @acronym{MIME} type as its argument and returns the matching viewer. +The @code{mailcap-prefer-mailcap-viewers} variable controls which +viewer is chosen. The default non-@code{nil} value means that +settings from @file{~/.mailcap} is preferred over system-wide or +Emacs-provided viewer settings. + +If @code{nil}, Emacs-provided viewer settings have precedence. Next, +the most specific viewer has precedence over less specific settings, +no matter if they're system-provided or private, so @samp{image/gif} +in @file{/etc/mailcap} will ``win'' over an @samp{image/*} setting in +@file{~/.mailcap}. + @end table diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi index d70eca81f9c..d2d86555e3c 100644 --- a/doc/misc/ert.texi +++ b/doc/misc/ert.texi @@ -273,9 +273,11 @@ moving point to it and typing @kbd{@key{RET}} jumps to its definition. @cindex backtrace of a failed test Pressing @kbd{r} re-runs the test near point on its own. Pressing @kbd{d} re-runs it with the debugger enabled. @kbd{.} jumps to the -definition of the test near point (@kbd{@key{RET}} has the same effect if -point is on the name of the test). On a failed test, @kbd{b} shows -the backtrace of the failure. +definition of the test near point (@kbd{@key{RET}} has the same effect +if point is on the name of the test). On a failed test, @kbd{b} shows +the backtrace of the failure. @xref{Debugging,, Backtraces, elisp, +GNU Emacs Lisp Reference Manual}, for more information about +backtraces. @kindex l@r{, in ert results buffer} @kbd{l} shows the list of @code{should} forms executed in the test. @@ -321,6 +323,20 @@ summary as shown below: emacs -batch -l ert -f ert-summarize-tests-batch-and-exit output.log @end example +@vindex ert-quiet +By default, ERT in batch mode is quite verbose, printing a line with +result after each test. This gives you progress information: how many +tests have been executed and how many there are. However, in some +cases this much output may be undesirable. In this case, set +@code{ert-quiet} variable to a non-nil value: + +@example +emacs -batch -l ert -l my-tests.el \ + --eval "(let ((ert-quiet t)) (ert-run-tests-batch-and-exit))" +@end example + +In quiet mode ERT prints only unexpected results and summary. + If ERT is not part of your Emacs distribution, you may need to use @code{-L /path/to/ert/} so that Emacs can find it. You may need additional @code{-L} flags to ensure that @code{my-tests.el} and all the diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index d2ea738f8db..dcb4aac2d89 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -330,7 +330,7 @@ List subprocesses of the Emacs process, if any, using the function @item kill @cmindex kill Kill processes. Takes a PID or a process object and an optional -signal specifier. +signal specifier which can either be a number or a signal name. @item listify @cmindex listify diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi index 0afbd4cb852..b299ea1fb77 100644 --- a/doc/misc/eww.texi +++ b/doc/misc/eww.texi @@ -262,6 +262,16 @@ contrast. If that is still too low for you, you can customize the variables @code{shr-color-visible-distance-min} and @code{shr-color-visible-luminance-min} to get a better contrast. +@vindex shr-discard-aria-hidden +@cindex @code{aria-hidden}, HTML attribute + The HTML attribute @code{aria-hidden} is meant to tell screen +readers to ignore a tag's contents. You can customize the variable +@code{shr-discard-aria-hidden} to tell @code{shr} to ignore such tags. +This can be useful when using a screen reader on the output of +@code{shr} (e.g., on EWW buffer text). It can be useful even when not +using a screen reader, since web authors often put this attribute on +non-essential decorative elements. + @cindex Desktop Support @cindex Saving Sessions In addition to maintaining the history at run-time, EWW will also diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi index 2689b5d8cd9..894203ca5a1 100644 --- a/doc/misc/flymake.texi +++ b/doc/misc/flymake.texi @@ -1,8 +1,8 @@ \input texinfo @c -*-texinfo; coding: utf-8 -*- @comment %**start of header @setfilename ../../info/flymake.info -@set VERSION 0.3 -@set UPDATED April 2004 +@set VERSION 1.0 +@set UPDATED June 2018 @settitle GNU Flymake @value{VERSION} @include docstyle.texi @syncodeindex pg cp @@ -37,7 +37,7 @@ modify this GNU manual.'' @titlepage @title GNU Flymake @subtitle for version @value{VERSION}, @value{UPDATED} -@author Pavel Kobiakov(@email{pk_at_work@@yahoo.com}) and João Távora. +@author João Távora and Pavel Kobiakov(@email{pk_at_work@@yahoo.com}). @page @vskip 0pt plus 1filll @insertcopying @@ -84,6 +84,10 @@ Syntax check is done ``on-the-fly''. It is started whenever @code{flymake-start-on-flymake-mode} is nil; @item +the buffer is saved, unless @code{flymake-start-on-save-buffer} is +nil; + +@item a newline character is added to the buffer, unless @code{flymake-start-syntax-check-on-newline} is nil; @@ -95,9 +99,15 @@ some changes were made to the buffer more than @code{0.5} seconds ago Syntax check can also be started manually by typing the @kbd{M-x flymake-start @key{RET}} command. +If the check detected errors or warnings, the respective buffer +regions are highlighted. You can place point on those regions and use +@kbd{C-h .} (@code{display-local-help}) to see what the specific +problem was. Alternatively, hovering the mouse on those regions +should also display a tool-tip with the same information. + @code{flymake-goto-next-error} and @code{flymake-goto-prev-error} are commands that allow easy navigation to the next/previous erroneous -line, respectively. If might be a good idea to map them to @kbd{M-n} +regions, respectively. If might be a good idea to map them to @kbd{M-n} and @kbd{M-p} in @code{flymake-mode}, by adding to your init file: @lisp @@ -220,6 +230,10 @@ after a newline character is inserted into the buffer. A boolean flag indicating whether to start syntax check immediately after enabling @code{flymake-mode}. +@item flymake-start-on-save-buffer +A boolean flag indicating whether to start syntax check after saving +the buffer. + @item flymake-error A custom face for highlighting regions for which an error has been reported. @@ -275,54 +289,61 @@ The following sections discuss each approach in detail. @cindex customizing error types @cindex error types, customization -@vindex flymake-diagnostic-types-alist -The variable @code{flymake-diagnostic-types-alist} is looked up by -Flymake every time an annotation for a diagnostic is created in the -buffer. Specifically, this variable holds a table of correspondence -between symbols designating diagnostic types and an additional -sub-table of properties pertaining to each diagnostic type. +To customize the appearance of error types, set properties on the +symbols associated with each diagnostic type. The standard diagnostic +symbols are @code{:error}, @code{:warning} and @code{:note} (though +the backend may define more, @pxref{Backend functions}). -Both tables are laid out in association list (@pxref{Association -Lists,,, elisp, The Emacs Lisp Reference Manual}) format, and thus can -be conveniently accessed with the functions of the @code{assoc} -family. - -You can use any symbol-value association in the properties sub-table, -but some symbols have special meaning as to where and how Flymake -presents the diagnostic: +The following properties can be set: @itemize @item @cindex bitmap of diagnostic -@code{bitmap}, an image displayed in the fringe according to +@code{flymake-bitmap}, an image displayed in the fringe according to @code{flymake-fringe-indicator-position}. The value actually follows the syntax of @code{flymake-error-bitmap} (@pxref{Customizable variables}). It is overridden by any @code{before-string} overlay property. @item -@cindex severity of diagnostic -@code{severity} is a non-negative integer specifying the diagnostic's -severity. The higher the value, the more serious is the error. If -the overlay property @code{priority} is not specified, @code{severity} -is used to set it and help sort overlapping overlays. +@code{flymake-overlay-control}, an alist ((@var{OVPROP} . @var{VALUE}) +@var{...}) of further properties used to affect the appearance of +Flymake annotations. With the exception of @code{category} and +@code{evaporate}, these properties are applied directly to the created +overlay (@pxref{Overlay Properties,,, elisp, The Emacs Lisp Reference +Manual}). -@item -Every property pertaining to overlays (@pxref{Overlay Properties,,, -elisp, The Emacs Lisp Reference Manual}), except @code{category} and -@code{evaporate}. These properties are used to affect the appearance -of Flymake annotations. +As an example, here's how to make diagnostics of the type @code{:note} +stand out more prominently: -As an example, here's how to make errors (diagnostics of the type -@code{:error}) stand out even more prominently in the buffer, by -raising the characters using a @code{display} overlay property. +@example +(push '(face . highlight) (get :note 'flymake-overlay-control)) +@end example + +If you push another alist entry in front, it overrides the previous +one. So this effectively removes the face from @code{:note} +diagnostics: @example -(push '(display . (raise 1.2)) - (cdr (assoc :error flymake-diagnostic-types-alist))) +(push '(face . nil) (get :note 'flymake-overlay-control)) @end example +To restore the original look for @code{:note} types, empty or remove +its @code{flymake-overlay-control} property: + +@example +(put :note 'flymake-overlay-control '()) +@end example + +@item +@cindex severity of diagnostic +@code{flymake-severity} is a non-negative integer specifying the +diagnostic's severity. The higher the value, the more serious is the +error. If the overlay property @code{priority} is not specified in +@code{flymake-overlay-control}, @code{flymake-severity} is used to set +it and help sort overlapping overlays. + @item @vindex flymake-category @code{flymake-category} is a symbol whose property list is considered @@ -333,32 +354,29 @@ the default for missing values of any other properties. @vindex flymake-error @vindex flymake-warning @vindex flymake-note -Three default diagnostic types, @code{:error}, @code{:warning} and -@code{:note} are predefined in -@code{flymake-diagnostic-types-alist}. By default each lists a single +Three default diagnostic types are predefined: @code{:error}, +@code{:warning}, and @code{:note}. By default, each one of them has a @code{flymake-category} property whose value is, respectively, the -symbols @code{flymake-error}, @code{flymake-warning} and +category symbol @code{flymake-error}, @code{flymake-warning} and @code{flymake-note}. -These category symbols' plists is where the values of customizable -variables and faces such as @code{flymake-error-bitmap} are found. -Thus, if you change their plists, Flymake may stop honoring these -user customizations. +These category symbols' plist is where the values of customizable +variables and faces (such as @code{flymake-error-bitmap}) are found. +Thus, if you change their plists, Flymake may stop honoring these user +customizations. -The @code{flymake-category} special property is also especially useful -for backends which create diagnostics objects with non-default -types that differ from an existing type by only a few properties -(@pxref{Flymake utility functions}). +The @code{flymake-category} special property is especially useful for +backends which create diagnostics objects with non-default types that +differ from an existing type by only a few properties (@pxref{Flymake +utility functions}). As an example, consider configuring a new diagnostic type -@code{:low-priority-note} that behaves much like the @code{:note} -priority but without an overlay face. +@code{:low-priority-note} that behaves much like @code{:note}, but +without an overlay face. @example -(add-to-list - 'flymake-diagnostic-types-alist - `(:low-priority-note . ((face . nil) - (flymake-category . flymake-note)))) +(put :low-priority-note 'flymake-overlay-control '((face . nil))) +(put :low-priority-note 'flymake-category 'flymake-note) @end example @vindex flymake-diagnostics @@ -389,20 +407,17 @@ Internet search for the text of a @code{:warning} or @code{:error}. (eww-browse-url (concat "https://duckduckgo.com/?q=" - (replace-regexp-in-string " " - "+" - (flymake-diagnostic-text topmost-diag))) + (replace-regexp-in-string + " " "+" (flymake-diagnostic-text topmost-diag))) t))) (dolist (type '(:warning :error)) - (let ((a (assoc type flymake-diagnostic-types-alist))) - (setf (cdr a) - (append `((mouse-face . highlight) - (keymap . ,(let ((map (make-sparse-keymap))) - (define-key map [mouse-2] - 'my-search-for-message) - map))) - (cdr a))))) + (push '(mouse-face . highlight) (get type 'flymake-overlay-control)) + (push `(keymap . ,(let ((map (make-sparse-keymap))) + (define-key map [mouse-2] + 'my-search-for-message) + map)) + (get type 'flymake-overlay-control))) @end example @node Backend functions @@ -428,18 +443,35 @@ calling convention: one for calls made by Flymake into the backend via the backend function, the other in the reverse direction via a callback. To be usable, backends must adhere to both. -Backend functions must accept an arbitrary number of arguments: +The first argument passed to a backend function is always +@var{report-fn}, a callback function detailed below. Beyond it, +functions must be prepared to accept (and possibly ignore) an +arbitrary number of keyword-value pairs of the form +@w{@code{(@var{:key} @var{value} @var{:key2} @var{value2}...)}}. + +Currently, Flymake may pass the following keywords and values to the +backend function: @itemize -@item -the first argument is always @var{report-fn}, a callback function -detailed below; -@item -the remaining arguments are keyword-value pairs of the -form @w{@code{(@var{:key} @var{value} @var{:key2} @var{value2}...)}}. Currently, -Flymake provides no such arguments, but backend functions must be -prepared to accept (and possibly ignore) any number of them. +@item @code{:recent-changes} +The value is a list recent changes since the last time the backend +function was called for the buffer. If the list is empty, this +indicates that no changes have been recorded. If it is the first time +that this backend function is called for this activation of +@code{flymake-mode}, then this argument isn't provided at all +(i.e. it's not merely nil). + +Each element is in the form (@var{beg} @var{end} @var{text}) where +@var{beg} and @var{end} are buffer positions, and @var{text} is a +string containing the text contained between those positions (if any), +after the change was performed. + +@item @code{:changes-start} and @code{:changes-end} +The value is, repectively, the minimum and maximum buffer positions +touched by the recent changes. These are provided for convenience and +only if @code{:recent-changes} is also provided. + @end itemize Whenever Flymake or the user decide to re-check the buffer, backend @@ -495,6 +527,11 @@ details of the situation encountered, if any. @code{:force}, whose value should be a boolean suggesting that Flymake consider the report even if it was somehow unexpected. + +@item +@code{:region}, a cons (@var{beg} . @var{end}) of buffer positions +indicating that the report applies to that region and that previous +reports targeting other parts of the buffer remain valid. @end itemize @menu @@ -512,9 +549,9 @@ by calling the function @code{flymake-make-diagnostic}. @deffn Function flymake-make-diagnostic buffer beg end type text Make a Flymake diagnostic for @var{buffer}'s region from @var{beg} to -@var{end}. @var{type} is a key to -@code{flymake-diagnostic-types-alist} and @var{text} is a description -of the problem detected in this region. +@var{end}. @var{type} is a diagnostic symbol (@pxref{Flymake error +types}), and @var{text} is a description of the problem detected in +this region. @end deffn @cindex access diagnostic object @@ -715,14 +752,13 @@ Patterns for error/warning messages in the form @code{(regexp file-idx line-idx col-idx err-text-idx)}. @xref{Parsing the output}. @item flymake-proc-diagnostic-type-pred -A function to classify a diagnostic text as particular type of -error. Should be a function taking an error text and returning one of -the symbols indexing @code{flymake-diagnostic-types-alist}. If non-nil -is returned but there is no such symbol in that table, a warning is -assumed. If nil is returned, an error is assumed. Can also be a -regular expression that should match only warnings. This variable -replaces the old @code{flymake-warning-re} and -@code{flymake-warning-predicate}. +A function to classify a diagnostic text as particular type of error. +Should be a function taking an error text and returning a diagnostic +symbol (@pxref{Flymake error types}). If non-nil is returned but +there is no such symbol in that table, a warning is assumed. If nil +is returned, an error is assumed. Can also be a regular expression +that should match only warnings. This variable replaces the old +@code{flymake-warning-re} and @code{flymake-warning-predicate}. @item flymake-proc-compilation-prevents-syntax-check A flag indicating whether compilation and syntax check of the same diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi index 55010d4e430..e8ec5020df2 100644 --- a/doc/misc/gnus-faq.texi +++ b/doc/misc/gnus-faq.texi @@ -1161,13 +1161,13 @@ from using them): @example (setq nnmail-split-methods '(("duplicates" "^Gnus-Warning:.*duplicate") - ("XEmacs-NT" "^\\(To:\\|CC:\\).*localpart@@xemacs.invalid.*") - ("Gnus-Tut" "^\\(To:\\|CC:\\).*localpart@@socha.invalid.*") - ("tcsh" "^\\(To:\\|CC:\\).*localpart@@mx.gw.invalid.*") - ("BAfH" "^\\(To:\\|CC:\\).*localpart@@.*uni-muenchen.invalid.*") - ("Hamster-src" "^\\(CC:\\|To:\\).*hamster-sourcen@@yahoogroups.\\(de\\|com\\).*") + ("XEmacs-NT" "^\\(To:\\|Cc:\\).*localpart@@xemacs.invalid.*") + ("Gnus-Tut" "^\\(To:\\|Cc:\\).*localpart@@socha.invalid.*") + ("tcsh" "^\\(To:\\|Cc:\\).*localpart@@mx.gw.invalid.*") + ("BAfH" "^\\(To:\\|Cc:\\).*localpart@@.*uni-muenchen.invalid.*") + ("Hamster-src" "^\\(Cc:\\|To:\\).*hamster-sourcen@@yahoogroups.\\(de\\|com\\).*") ("Tagesschau" "^From: tagesschau <localpart@@www.tagesschau.invalid>$") - ("Replies" "^\\(CC:\\|To:\\).*localpart@@Frank-Schmitt.invalid.*") + ("Replies" "^\\(Cc:\\|To:\\).*localpart@@Frank-Schmitt.invalid.*") ("EK" "^From:.*\\(localpart@@privateprovider.invalid\\|localpart@@workplace.invalid\\).*") ("Spam" "^Content-Type:.*\\(ks_c_5601-1987\\|EUC-KR\\|big5\\|iso-2022-jp\\).*") ("Spam" "^Subject:.*\\(This really work\\|XINGA\\|ADV:\\|XXX\\|adult\\|sex\\).*") @@ -1177,10 +1177,10 @@ from using them): ("Spam" "^From:.*\\(verizon\.net\\|prontomail\.com\\|money\\|ConsumerDirect\\).*") ("Spam" "^Delivered-To: GMX delivery to spamtrap@@gmx.invalid$") ("Spam" "^Received: from link2buy.com") - ("Spam" "^CC: .*azzrael@@t-online.invalid") + ("Spam" "^Cc: .*azzrael@@t-online.invalid") ("Spam" "^X-Mailer-Version: 1.50 BETA") - ("Uni" "^\\(CC:\\|To:\\).*localpart@@uni-koblenz.invalid.*") - ("Inbox" "^\\(CC:\\|To:\\).*\\(my\ name\\|address@@one.invalid\\|address@@two.invalid\\)") + ("Uni" "^\\(Cc:\\|To:\\).*localpart@@uni-koblenz.invalid.*") + ("Inbox" "^\\(Cc:\\|To:\\).*\\(my\ name\\|address@@one.invalid\\|address@@two.invalid\\)") ("Spam" ""))) @end example @noindent diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index 0ccd52f9d4f..2862264312c 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -3102,6 +3102,21 @@ interest in relation to the sieve parameter. The Sieve language is described in RFC 3028. @xref{Top, Emacs Sieve, Top, sieve, Emacs Sieve}. +@item match-list +@cindex match-list +If this parameter is set to @code{t} and @code{nnmail-split-method} is +set to @code{gnus-group-split}, Gnus will match @code{to-address}, +@code{to-list}, @code{extra-aliases} and @code{split-regexp} against +the @code{list} split abbreviation. The split regexp is modified to +match either a @code{@@} or a dot @code{.} in mail addresses to +conform to RFC2919 @code{List-ID}. + +See @code{nnmail-split-abbrev-alist} for the regular expression +matching mailing-list headers. + +See @pxref{Group Mail Splitting} to automatically split on group +parameters. + @item (agent parameters) If the agent has been enabled, you can set any of its parameters to control the behavior of the agent in individual groups. See Agent @@ -5577,7 +5592,7 @@ command uses the process/prefix convention. Mail a wide reply to the author of the current article (@code{gnus-summary-wide-reply}). A @dfn{wide reply} is a reply that goes out to all people listed in the @code{To}, @code{From} (or -@code{Reply-to}) and @code{Cc} headers. If @code{Mail-Followup-To} is +@code{Reply-To}) and @code{Cc} headers. If @code{Mail-Followup-To} is present, that's used instead. @item S W @@ -5601,7 +5616,7 @@ message to the mailing list, and include the original message Mail a very wide reply to the author of the current article (@code{gnus-summary-wide-reply}). A @dfn{very wide reply} is a reply that goes out to all people listed in the @code{To}, @code{From} (or -@code{Reply-to}) and @code{Cc} headers in all the process/prefixed +@code{Reply-To}) and @code{Cc} headers in all the process/prefixed articles. This command uses the process/prefix convention. @item S V @@ -5643,8 +5658,7 @@ as an rfc822 @acronym{MIME} section; if the prefix is 3, decode message and forward as an rfc822 @acronym{MIME} section; if the prefix is 4, forward message directly inline; otherwise, the message is forwarded as no prefix given but use the flipped value of (@code{message-forward-as-mime}). By -default, the message is decoded and forwarded as an rfc822 @acronym{MIME} -section. +default, the forwarded message is inlined into the mail. @item S m @itemx m @@ -5836,6 +5850,15 @@ buffer (@code{gnus-summary-yank-message}). This command prompts for what message buffer you want to yank into, and understands the process/prefix convention (@pxref{Process/Prefix}). +@item S A +@kindex S A @r{(Summary)} +@findex gnus-summary-attach-article +Attach the current article into an already existing Message +composition buffer (@code{gnus-summary-attach-message}). If no such +buffer exists, a new one is created. This command prompts for what +message buffer you want to yank into, and understands the +process/prefix convention (@pxref{Process/Prefix}). + @end table @@ -6657,7 +6680,8 @@ Limit the summary buffer to the unseen articles @kindex / v @r{(Summary)} @findex gnus-summary-limit-to-score Limit the summary buffer to articles that have a score at or above some -score (@code{gnus-summary-limit-to-score}). +score (@code{gnus-summary-limit-to-score}). If given a prefix, below +some score. @item / p @kindex / p @r{(Summary)} @@ -9791,9 +9815,6 @@ this command passes the @acronym{HTML} content to the browser without eliminating these ``web bugs'' you should only use it for mails from trusted senders. -If you always want to display @acronym{HTML} parts in the browser, set -@code{mm-text-html-renderer} to @code{nil}. - This command creates temporary files to pass @acronym{HTML} contents including images if any to the browser, and deletes them when exiting the group (if you want). @@ -13209,6 +13230,11 @@ Also @pxref{Formatting Variables}. @subsection Server Commands @cindex server commands +The following keybinding are available in the server buffer. Be aware +that some of the commands will only work on servers that you've added +through this interface (with @kbd{a}), not with servers you've defined +in your init files. + @table @kbd @item v @@ -14294,6 +14320,12 @@ fetch all textual parts, while leaving the rest on the server. If non-@code{nil}, record all @acronym{IMAP} commands in the @samp{"*imap log*"} buffer. +@item nnimap-use-namespaces +If non-@code{nil}, omit the IMAP namespace prefix in nnimap group +names. If your IMAP mailboxes are called something like @samp{INBOX} +and @samp{INBOX.Lists.emacs}, but you'd like the nnimap group names to +be @samp{INBOX} and @samp{Lists.emacs}, you should enable this option. + @end table @@ -15469,6 +15501,9 @@ Matches the @samp{To}, @samp{Cc}, @samp{Apparently-To}, @samp{Resent-To} and @samp{Resent-Cc} fields. @item any Is the union of the @code{from} and @code{to} entries. +@item list +Matches the @samp{List-ID}, @samp{List-Post}, @samp{X-Mailing-List}, +@samp{X-BeenThere} and @samp{X-Loop} fields. @end table @vindex nnmail-split-fancy-syntax-table @@ -18478,7 +18513,7 @@ something along the lines of the following: (defun my-article-old-p () "Say whether an article is old." (< (time-to-days (date-to-time (mail-header-date gnus-headers))) - (- (time-to-days (current-time)) gnus-agent-expire-days))) + (- (time-to-days nil) gnus-agent-expire-days))) @end lisp with the predicate then defined as: @@ -19466,8 +19501,8 @@ score file and edit it. @item V w @kindex V w @r{(Summary)} -@findex gnus-score-find-favourite-words -List words used in scoring (@code{gnus-score-find-favourite-words}). +@findex gnus-score-find-favorite-words +List words used in scoring (@code{gnus-score-find-favorite-words}). @item V R @kindex V R @r{(Summary)} @@ -21433,6 +21468,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 @@ -25854,13 +25901,13 @@ Reset: (setq spam-stat (make-hash-table :test 'equal)) Learn spam: (spam-stat-process-spam-directory "~/Mail/mail/spam") Learn non-spam: (spam-stat-process-non-spam-directory "~/Mail/mail/misc") Save table: (spam-stat-save) -File size: (nth 7 (file-attributes spam-stat-file)) +File size: (file-attribute-size (file-attributes spam-stat-file)) Number of words: (hash-table-count spam-stat) Test spam: (spam-stat-test-directory "~/Mail/mail/spam") Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc") Reduce table size: (spam-stat-reduce-size) Save table: (spam-stat-save) -File size: (nth 7 (file-attributes spam-stat-file)) +File size: (file-attribute-size (file-attributes spam-stat-file)) Number of words: (hash-table-count spam-stat) Test spam: (spam-stat-test-directory "~/Mail/mail/spam") Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc") diff --git a/doc/misc/message.texi b/doc/misc/message.texi index 21a57590066..addad99bdbc 100644 --- a/doc/misc/message.texi +++ b/doc/misc/message.texi @@ -162,7 +162,7 @@ header should be. If it does not, it should just return @code{nil}, and the normal methods for determining the To header will be used. Each list element should be a cons, where the @sc{car} should be the -name of a header (e.g., @code{Cc}) and the @sc{cdr} should be the header +name of a header (e.g., @code{CC}) and the @sc{cdr} should be the header value (e.g., @samp{larsi@@ifi.uio.no}). All these headers will be inserted into the head of the outgoing mail. @@ -174,7 +174,7 @@ inserted into the head of the outgoing mail. The @code{message-wide-reply} pops up a message buffer that's a wide reply to the message in the current buffer. A @dfn{wide reply} is a reply that goes out to all people listed in the @code{To}, @code{From} -(or @code{Reply-to}) and @code{Cc} headers. +(or @code{Reply-To}) and @code{CC} headers. @vindex message-wide-reply-to-function Message uses the normal methods to determine where wide replies are to go, @@ -185,7 +185,7 @@ but you can change the behavior to suit your needs by fiddling with the @vindex message-dont-reply-to-names Addresses that match the @code{message-dont-reply-to-names} regular expression (or list of regular expressions or a predicate function) -will be removed from the @code{Cc} header. A value of @code{nil} means +will be removed from the @code{CC} header. A value of @code{nil} means to exclude only your email address. @vindex message-prune-recipient-rules @@ -199,7 +199,7 @@ to match addresses to be pruned. It's complicated to explain, but it's easy to use. For instance, if you get an email from @samp{foo@@example.org}, but -@samp{foo@@zot.example.org} is also in the @code{Cc} list, then your +@samp{foo@@zot.example.org} is also in the @code{CC} list, then your wide reply will go out to both these addresses, since they are unique. To avoid this, do something like the following: @@ -316,7 +316,7 @@ when forwarding a message. @item message-forward-included-headers @vindex message-forward-included-headers In non-@code{nil}, only headers that match this regexp will be kept -when forwarding a message. +when forwarding a message. This can also be a list of regexps. @item message-make-forward-subject-function @vindex message-make-forward-subject-function @@ -345,10 +345,10 @@ constructed. The default value is @code{nil}. @item message-forward-as-mime @vindex message-forward-as-mime -If this variable is @code{t} (the default), forwarded messages are -included as inline @acronym{MIME} RFC822 parts. If it's @code{nil}, forwarded -messages will just be copied inline to the new message, like previous, -non @acronym{MIME}-savvy versions of Gnus would do. +If this variable is @code{t}, forwarded messages are included as +inline @acronym{MIME} RFC822 parts. If it's @code{nil} (the default), +forwarded messages will just be copied inline to the new message, like +previous, non @acronym{MIME}-savvy versions of Gnus would do. @item message-forward-before-signature @vindex message-forward-before-signature @@ -487,10 +487,10 @@ MFT field. If there is one, it is left alone. (Except if it's empty; in that case, the field is removed and is not replaced with an automatically generated one. This lets you disable MFT generation on a per-message basis.) If there is none, then the list of recipient -addresses (in the To: and Cc: headers) is checked to see if one of them +addresses (in the To: and CC: headers) is checked to see if one of them is a list address you are subscribed to. If none of them is a list address, then no MFT is generated; otherwise, a MFT is added to the -other headers and set to the value of all addresses in To: and Cc: +other headers and set to the value of all addresses in To: and CC: @kindex C-c C-f C-a @findex message-generate-unsubscribed-mail-followup-to @@ -516,7 +516,7 @@ header, Gnus' action will depend on the value of the variable @table @code @item use - Always honor MFTs. The To: and Cc: headers in your followup will be + Always honor MFTs. The To: and CC: headers in your followup will be derived from the MFT header of the original post. This is the default. @item nil @@ -593,17 +593,17 @@ in the key binding is for Originator.) @item C-c C-f C-b @kindex C-c C-f C-b @findex message-goto-bcc -Go to the @code{Bcc} header (@code{message-goto-bcc}). +Go to the @code{BCC} header (@code{message-goto-bcc}). @item C-c C-f C-w @kindex C-c C-f C-w @findex message-goto-fcc -Go to the @code{Fcc} header (@code{message-goto-fcc}). +Go to the @code{FCC} header (@code{message-goto-fcc}). @item C-c C-f C-c @kindex C-c C-f C-c @findex message-goto-cc -Go to the @code{Cc} header (@code{message-goto-cc}). +Go to the @code{CC} header (@code{message-goto-cc}). @item C-c C-f C-s @kindex C-c C-f C-s @@ -662,7 +662,7 @@ fetches the contents of the @samp{To:} header in the current mail buffer, and appends the current @code{user-mail-address}. If the optional argument @code{include-cc} is non-@code{nil}, the -addresses in the @samp{Cc:} header are also put into the +addresses in the @samp{CC:} header are also put into the @samp{Mail-Followup-To:} header. @end table @@ -696,7 +696,7 @@ or @code{Newsgroups} header of the article you're replying to @kindex C-c C-l @findex message-to-list-only Send a message to the list only. Remove all addresses but the list -address from @code{To:} and @code{Cc:} headers. +address from @code{To:} and @code{CC:} headers. @item C-c M-n @kindex C-c M-n @@ -746,13 +746,13 @@ by the @code{message-cross-post-note-function} variable. @item C-c C-f t @kindex C-c C-f t @findex message-reduce-to-to-cc -Replace contents of @samp{To} header with contents of @samp{Cc} -header (or the @samp{Bcc} header, if there is no @samp{Cc} header). +Replace contents of @samp{To} header with contents of @samp{CC} +header (or the @samp{BCC} header, if there is no @samp{CC} header). @item C-c C-f w @kindex C-c C-f w @findex message-insert-wide-reply -Insert @samp{To} and @samp{Cc} headers as if you were doing a wide +Insert @samp{To} and @samp{CC} headers as if you were doing a wide reply even if the message was not made for a wide reply first. @item C-c C-f a @@ -902,7 +902,7 @@ found in RFC 3490. Message is a @acronym{IDNA}-compliant posting agent. The user generally doesn't have to do anything to make the @acronym{IDNA} happen---Message will encode non-@acronym{ASCII} domain names in @code{From}, -@code{To}, and @code{Cc} headers automatically. +@code{To}, and @code{CC} headers automatically. Until @acronym{IDNA} becomes more well known, Message queries you whether @acronym{IDNA} encoding of the domain name really should @@ -1011,7 +1011,7 @@ and/or encrypted messages as explained in the following. * Passphrase caching:: How to cache passphrases * PGP Compatibility:: Compatibility with older implementations * Encrypt-to-self:: Reading your own encrypted messages -* Bcc Warning:: Do not use encryption with Bcc headers +* BCC Warning:: Do not use encryption with BCC headers @end menu @node Signing and encryption @@ -1300,7 +1300,7 @@ information about the problem.) @subsection Encrypt-to-self By default, messages are encrypted to all recipients (@code{To}, -@code{Cc}, @code{Bcc} headers). Thus, you will not be able to decrypt +@code{CC}, @code{BCC} headers). Thus, you will not be able to decrypt your own messages. To make sure that messages are also encrypted to your own key(s), several alternative solutions exist: @enumerate @@ -1318,17 +1318,17 @@ OpenPGP) or @code{mml-secure-smime-encrypt-to-self} (for @acronym{S/MIME} with EasyPG). @end enumerate -@node Bcc Warning -@subsection Bcc Warning +@node BCC Warning +@subsection BCC Warning -The @code{Bcc} header is meant to hide recipients of messages. +The @code{BCC} header is meant to hide recipients of messages. However, when encrypted messages are used, the e-mail addresses of all -@code{Bcc}-headers are given away to all recipients without +@code{BCC}-headers are given away to all recipients without warning, which is a bug. @vindex mml-secure-safe-bcc-list -But now Message got to warn if @code{Bcc} recipients are found in an +But now Message got to warn if @code{BCC} recipients are found in an encrypted message when you are just about to send it. If you are sure -those @code{Bcc} addresses are safe to expose, set the +those @code{BCC} addresses are safe to expose, set the @code{mml-secure-safe-bcc-list} variable, that is a list of e-mail addresses. See @uref{https://debbugs.gnu.org/cgi/bugreport.cgi?bug=18718}. @@ -1468,20 +1468,24 @@ alias ding "ding@@ifi.uio.no (ding mailing list)" @end example After adding lines like this to your @file{~/.mailrc} file, you should -be able to just write @samp{lmi} in the @code{To} or @code{Cc} (and so +be able to just write @samp{lmi} in the @code{To} or @code{CC} (and so on) headers and press @kbd{SPC} to expand the alias. No expansion will be performed upon sending of the message---all expansions have to be done explicitly. If you're using @code{ecomplete}, all addresses from @code{To} and -@code{Cc} headers will automatically be put into the +@code{CC} headers will automatically be put into the @file{~/.ecompleterc} file. When you enter text in the @code{To} and -@code{Cc} headers, @code{ecomplete} will check out the values stored +@code{CC} headers, @code{ecomplete} will check out the values stored there and ``electrically'' say what completions are possible. To choose one of these completions, use the @kbd{M-n} command to move -down to the list. Use @kbd{M-n} and @kbd{M-p} to move down and up the -list, and @kbd{RET} to choose a completion. +down to the list. Use @kbd{@key{DOWN}} or @kbd{M-n} and +@kbd{@key{UP}} or @kbd{M-p} to move down and up the list, and +@kbd{@key{RET}} to choose a completion. + +The @code{ecomplete-sort-predicate} variable controls how +@code{ecomplete} matches are sorted. @node Spelling @section Spelling @@ -1677,7 +1681,7 @@ trailing old subject. In this case, @item message-alternative-emails @vindex message-alternative-emails Regexp or predicate function matching alternative email addresses. -The first address in the To, Cc or From headers of the original +The first address in the To, CC or From headers of the original article matching this variable is used as the From field of outgoing messages, replacing the default From value. @@ -1697,7 +1701,7 @@ off @code{message-setup-hook}. @item message-allow-no-recipients @vindex message-allow-no-recipients Specifies what to do when there are no recipients other than -@code{Gcc} or @code{Fcc}. If it is @code{always}, the posting is +@code{Gcc} or @code{FCC}. If it is @code{always}, the posting is allowed. If it is @code{never}, the posting is not allowed. If it is @code{ask} (the default), you are prompted. @@ -1709,7 +1713,7 @@ hidden when composing a message. @lisp (setq message-hidden-headers - '(not "From" "Subject" "To" "Cc" "Newsgroups")) + '(not "From" "Subject" "To" "CC" "Newsgroups")) @end lisp Headers are hidden using narrowing, you can use @kbd{M-x widen} to @@ -1718,9 +1722,9 @@ expose them in the buffer. @item message-header-synonyms @vindex message-header-synonyms A list of lists of header synonyms. E.g., if this list contains a -member list with elements @code{Cc} and @code{To}, then +member list with elements @code{CC} and @code{To}, then @code{message-carefully-insert-headers} will not insert a @code{To} -header when the message is already @code{Cc}ed to the recipient. +header when the message is already @code{CC}ed to the recipient. @end table @@ -1738,7 +1742,7 @@ header when the message is already @code{Cc}ed to the recipient. @item message-ignored-mail-headers @vindex message-ignored-mail-headers Regexp of headers to be removed before mailing. The default is@* -@samp{^[GF]cc:\\|^Resent-Fcc:\\|^Xref:\\|^X-Draft-From:\\|@* +@samp{^[GF]cc:\\|^Resent-FCC:\\|^Xref:\\|^X-Draft-From:\\|@* ^X-Gnus-Agent-Meta-Information:}. @item message-default-mail-headers @@ -2052,7 +2056,7 @@ Check whether the @code{Newsgroups} header exists and is not empty. @item quoting-style Check whether text follows last quoted portion. @item repeated-newsgroups -Check whether the @code{Newsgroups} and @code{Followup-to} headers +Check whether the @code{Newsgroups} and @code{Followup-To} headers contains repeated group names. @item reply-to Check whether the @code{Reply-To} header looks ok. @@ -2065,7 +2069,7 @@ Check for the existence of version and sendsys commands. @item shoot Check whether the domain part of the @code{Message-ID} header looks ok. @item shorten-followup-to -Check whether to add a @code{Followup-to} header to shorten the number +Check whether to add a @code{Followup-To} header to shorten the number of groups to post to. @item signature Check the length of the signature. @@ -2076,7 +2080,7 @@ Check whether the @code{Subject} header exists and is not empty. @item subject-cmsg Check the subject for commands. @item valid-newsgroups -Check whether the @code{Newsgroups} and @code{Followup-to} headers +Check whether the @code{Newsgroups} and @code{Followup-To} headers are valid syntactically. @end table @@ -2087,7 +2091,7 @@ for which the check is disabled by default if @item message-ignored-news-headers @vindex message-ignored-news-headers Regexp of headers to be removed before posting. The default is@* -@samp{^NNTP-Posting-Host:\\|^Xref:\\|^[BGF]cc:\\|^Resent-Fcc:\\|@* +@samp{^NNTP-Posting-Host:\\|^Xref:\\|^[BGF]cc:\\|^Resent-FCC:\\|@* ^X-Draft-From:\\|^X-Gnus-Agent-Meta-Information:}. @item message-default-news-headers @@ -2467,7 +2471,7 @@ an article\\nthat has been posted to %s as well.\\n\\n"}. @item message-fcc-externalize-attachments @vindex message-fcc-externalize-attachments -If @code{nil}, attach files as normal parts in Fcc copies; if it is +If @code{nil}, attach files as normal parts in FCC copies; if it is non-@code{nil}, attach local files as external parts. @item message-interactive @@ -2622,13 +2626,13 @@ consulted, in turn: A @dfn{wide reply} is a mail response that includes @emph{all} entities mentioned in the message you are responding to. All mailboxes from the following headers will be concatenated to form the outgoing -@code{To}/@code{Cc} headers: +@code{To}/@code{CC} headers: @table @code @item From (unless there's a @code{Reply-To}, in which case that is used instead). -@item Cc +@item CC @item To @end table @@ -2652,7 +2656,7 @@ sent: @end table If a @code{Mail-Copies-To} header is present, it will be used as the -basis of the new @code{Cc} header, except if this header is +basis of the new @code{CC} header, except if this header is @samp{never}. @end table diff --git a/doc/misc/mh-e.texi b/doc/misc/mh-e.texi index 898b3418f8d..99070950026 100644 --- a/doc/misc/mh-e.texi +++ b/doc/misc/mh-e.texi @@ -847,9 +847,9 @@ sending the original message, like this: To: cc: Subject: Re: Test -In-reply-to: <31054.1142621351@@stop.mail-abuse.org> +In-Reply-To: <31054.1142621351@@stop.mail-abuse.org> References: <31054.1142621351@@stop.mail-abuse.org> -Comments: In-reply-to Bill Wohler <wohler@@stop.mail-abuse.org> +Comments: In-Reply-To Bill Wohler <wohler@@stop.mail-abuse.org> message dated "Fri, 17 Mar 2006 10:49:11 -0800." X-Mailer: MH-E 8.1; nmh 1.1; GNU Emacs 23.1 -------- @@ -2589,13 +2589,6 @@ centers the output and wraps long lines more than most. It does not always handle special characters like @samp{®} or @samp{–}. It does not download images. @c ------------------------- -@item @samp{nil} -This choice obviously requires an external browser. With this setting, -HTML messages have a button for the body part which you can view with -@kbd{K v} (@code{mh-folder-toggle-mime-part}). Rendering of special -characters and handling of remote images depends on your choice of -browser. -@c ------------------------- @item @samp{shr} @cindex @samp{shr} This choice does not require an external program, but it does require diff --git a/doc/misc/org.texi b/doc/misc/org.texi index 2be2707d95e..7862713f47a 100644 --- a/doc/misc/org.texi +++ b/doc/misc/org.texi @@ -891,9 +891,7 @@ org}. been visited, i.e., where no Org built-in function have been loaded. Otherwise autoload Org functions will mess up the installation. -Then, to make sure your Org configuration is taken into account, initialize -the package system with @code{(package-initialize)} in your Emacs init file -before setting any Org option. If you want to use Org's package repository, +If you want to use Org's package repository, check out the @uref{https://orgmode.org/elpa.html, Org ELPA page}. @subsubheading Downloading Org as an archive @@ -18168,7 +18166,7 @@ Suggested Org crypt settings in Emacs init file: @lisp (require 'org-crypt) (org-crypt-use-before-save-magic) -(setq org-tags-exclude-from-inheritance (quote ("crypt"))) +(setq org-tags-exclude-from-inheritance '("crypt")) (setq org-crypt-key nil) ;; GPG key to use for encryption @@ -19707,8 +19705,8 @@ mentioned in the manual. For a complete list, use @kbd{M-x org-customize @c Local variables: @c fill-column: 77 @c indent-tabs-mode: nil -@c paragraph-start: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$" -@c paragraph-separate: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$" +@c paragraph-start: "^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$" +@c paragraph-separate: "^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$" @c End: diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex index f2be62ce47b..5840aff4d7c 100644 --- a/doc/misc/texinfo.tex +++ b/doc/misc/texinfo.tex @@ -3,10 +3,12 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2017-12-26.21} +\def\texinfoversion{2018-09-21.20} % -% Copyright 1985-1986, 1988, 1990-2017, 2019 Free Software Foundation, -% Inc. +% 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. % % 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 @@ -1526,6 +1528,9 @@ output) for that.)} \startlink attr{/Border [0 0 0]}% user{/Subtype /Link /A << /S /URI /URI (#1) >>}% \endgroup} + % \pdfgettoks - Surround page numbers in #1 with @pdflink. #1 may + % be a simple number, or a list of numbers in the case of an index + % entry. \def\pdfgettoks#1.{\setbox\boxA=\hbox{\toksA={#1.}\toksB={}\maketoks}} \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks} \def\adn#1{\addtokens{\toksC}{#1}\global\countA=1\let\next=\maketoks} @@ -2233,6 +2238,20 @@ end \font\smallersy=cmsy8 \def\smallerecsize{0800} +% Fonts for math mode superscripts (7pt). +\def\sevennominalsize{7pt} +\setfont\sevenrm\rmshape{7}{1000}{OT1} +\setfont\seventt\ttshape{10}{700}{OT1TT} +\setfont\sevenbf\bfshape{10}{700}{OT1} +\setfont\sevenit\itshape{7}{1000}{OT1IT} +\setfont\sevensl\slshape{10}{700}{OT1} +\setfont\sevensf\sfshape{10}{700}{OT1} +\setfont\sevensc\scshape{10}{700}{OT1} +\setfont\seventtsl\ttslshape{10}{700}{OT1TT} +\font\seveni=cmmi7 +\font\sevensy=cmsy7 +\def\sevenecsize{0700} + % Fonts for title page (20.4pt): \def\titlenominalsize{20pt} \setfont\titlerm\rmbshape{12}{\magstep3}{OT1} @@ -2367,6 +2386,20 @@ end \font\smallersy=cmsy8 \def\smallerecsize{0800} +% Fonts for math mode superscripts (7pt). +\def\sevennominalsize{7pt} +\setfont\sevenrm\rmshape{7}{1000}{OT1} +\setfont\seventt\ttshape{10}{700}{OT1TT} +\setfont\sevenbf\bfshape{10}{700}{OT1} +\setfont\sevenit\itshape{7}{1000}{OT1IT} +\setfont\sevensl\slshape{10}{700}{OT1} +\setfont\sevensf\sfshape{10}{700}{OT1} +\setfont\sevensc\scshape{10}{700}{OT1} +\setfont\seventtsl\ttslshape{10}{700}{OT1TT} +\font\seveni=cmmi7 +\font\sevensy=cmsy7 +\def\sevenecsize{0700} + % Fonts for title page (20.4pt): \def\titlenominalsize{20pt} \setfont\titlerm\rmbshape{12}{\magstep3}{OT1} @@ -2501,13 +2534,20 @@ end % In order for the font changes to affect most math symbols and letters, -% we have to define the \textfont of the standard families. We don't -% bother to reset \scriptfont and \scriptscriptfont; awaiting user need. +% we have to define the \textfont of the standard families. +% We don't bother to reset \scriptscriptfont; awaiting user need. % \def\resetmathfonts{% \textfont0=\rmfont \textfont1=\ifont \textfont2=\syfont \textfont\itfam=\itfont \textfont\slfam=\slfont \textfont\bffam=\bffont \textfont\ttfam=\ttfont \textfont\sffam=\sffont + % + % Fonts for superscript. Note that the 7pt fonts are used regardless + % of the current font size. + \scriptfont0=\sevenrm \scriptfont1=\seveni \scriptfont2=\sevensy + \scriptfont\itfam=\sevenit \scriptfont\slfam=\sevensl + \scriptfont\bffam=\sevenbf \scriptfont\ttfam=\seventt + \scriptfont\sffam=\sevensf } % @@ -2517,6 +2557,9 @@ end % to also set the current \fam for math mode. Our \STYLE (e.g., \rm) % commands hardwire \STYLEfont to set the current font. % +% The fonts used for \ifont are for "math italics" (\itfont is for italics +% in regular text). \syfont is also used in math mode only. +% % Each font-changing command also sets the names \lsize (one size lower) % and \lllsize (three sizes lower). These relative commands are used % in, e.g., the LaTeX logo and acronyms. @@ -7961,6 +8004,7 @@ end \gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} \gdef\magicamp{\let&=\amprm} } +\let\ampchar\& \newcount\parencount @@ -11675,7 +11719,7 @@ directory should work if nowhere else does.} @markupsetuprqdefault @c Local variables: -@c eval: (add-hook 'write-file-hooks 'time-stamp) +@c eval: (add-hook 'before-save-hook 'time-stamp) @c page-delimiter: "^\\\\message\\|emacs-page" @c time-stamp-start: "def\\\\texinfoversion{" @c time-stamp-format: "%:y-%02m-%02d.%02H" diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index bfb6d748f24..7587059f393 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -12,16 +12,6 @@ @c This is *so* much nicer :) @footnotestyle end -@c Macro for formatting a file name according to the respective -@c syntax. Macro arguments should not have any leading or trailing -@c whitespace. Not very elegant, but I don't know it better. - -@macro trampfn {method, userhost, localname} -@value{prefix}@c -\method\@value{postfixhop}@c -\userhost\@value{postfix}\localname\ -@end macro - @copying Copyright @copyright{} 1999--2019 Free Software Foundation, Inc. @@ -83,9 +73,9 @@ Savannah Project Page}. @end ifhtml There is a mailing list for @value{tramp}, available at -@email{tramp-devel@@gnu.org}, and archived at -@uref{https://lists.gnu.org/r/tramp-devel/, the -@value{tramp} Mail Archive}. +@email{@value{tramp-bug-report-address}}, and archived at +@uref{https://lists.gnu.org/r/tramp-devel/, the @value{tramp} Mail +Archive}. @page @insertcopying @@ -96,7 +86,6 @@ There is a mailing list for @value{tramp}, available at For the end user: * Obtaining @value{tramp}:: How to obtain @value{tramp}. -* History:: History of @value{tramp}. @ifset installchapter * Installation:: Installing @value{tramp} with your Emacs. @end ifset @@ -122,8 +111,11 @@ For the developer: --- The Detailed Node Listing --- @c @ifset installchapter + Installing @value{tramp} with your Emacs +* System Requirements:: Prerequisites for :@value{tramp} installation. +* Basic Installation:: Installation steps.: * Installation parameters:: Parameters in order to control installation. * Testing:: A test suite for @value{tramp}. * Load paths:: How to plug-in @value{tramp} into your environment. @@ -162,6 +154,7 @@ Using @value{tramp} * Ad-hoc multi-hops:: Declaring multiple hops in the file name. * Remote processes:: Integration with other Emacs packages. * Cleanup remote connections:: Cleanup remote connections. +* Archive file names:: Access to files in file archives. How file names, directories and localnames are mangled and managed @@ -385,31 +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}. - -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 @@ -463,13 +431,13 @@ this case it is written as @code{host#port}. @anchor{Quick Start Guide: @option{ssh} and @option{plink} methods} @section Using @option{ssh} and @option{plink} -@cindex method ssh -@cindex ssh method -@cindex method plink -@cindex plink method +@cindex method @option{ssh} +@cindex @option{ssh} method +@cindex method @option{plink} +@cindex @option{plink} method If your local host runs an SSH client, and the remote host runs an SSH -server, the most simple remote file name is +server, the simplest remote file name is @file{@trampfn{ssh,user@@host,/path/to/file}}. The remote file name @file{@trampfn{ssh,,}} opens a remote connection to yourself on the local host, and is taken often for testing @value{tramp}. @@ -482,12 +450,12 @@ an @command{ssh} server: @anchor{Quick Start Guide: @option{su}, @option{sudo} and @option{sg} methods} @section Using @option{su}, @option{sudo} and @option{sg} -@cindex method su -@cindex su method -@cindex method sudo -@cindex sudo method -@cindex method sg -@cindex sg method +@cindex method @option{su} +@cindex @option{su} method +@cindex method @option{sudo} +@cindex @option{sudo} method +@cindex method @option{sg} +@cindex @option{sg} method Sometimes, it is necessary to work on your local host under different permissions. For this, you could use the @option{su} or @option{sudo} @@ -500,12 +468,25 @@ 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 smb -@cindex smb method -@cindex ms windows (with smb method) -@cindex smbclient +@cindex method @option{smb} +@cindex @option{smb} method +@cindex ms windows (with @option{smb} method) +@cindex @command{smbclient} In order to access a remote MS Windows host or Samba server, the @command{smbclient} client is used. The remote file name syntax is @@ -518,39 +499,48 @@ of the local file name is the share exported by the remote host, @section Using GVFS-based methods @cindex methods, gvfs @cindex gvfs based methods -@cindex method sftp -@cindex sftp method -@cindex method afp -@cindex afp method -@cindex method dav -@cindex method davs -@cindex dav method -@cindex davs method - -On systems, which have installed the virtual file system for the Gnome -Desktop (GVFS), its offered methods could be used by @value{tramp}. -Examples are @file{@trampfn{sftp,user@@host,/path/to/file}}, +@cindex method @option{sftp} +@cindex @option{sftp} method +@cindex method @option{afp} +@cindex @option{afp} method +@cindex method @option{dav} +@cindex method @option{davs} +@cindex @option{dav} method +@cindex @option{davs} method + +On systems, which have installed the virtual file system for the +@acronym{GNOME} Desktop (GVFS), its offered methods could be used by +@value{tramp}. Examples are +@file{@trampfn{sftp,user@@host,/path/to/file}}, @file{@trampfn{afp,user@@host,/path/to/file}} (accessing Apple's AFP file system), @file{@trampfn{dav,user@@host,/path/to/file}} and @file{@trampfn{davs,user@@host,/path/to/file}} (for WebDAV shares). -@anchor{Quick Start Guide: Google Drive} -@section Using Google Drive -@cindex method gdrive -@cindex gdrive method +@anchor{Quick Start Guide: GNOME Online Accounts based methods} +@section Using @acronym{GNOME} Online Accounts based methods +@cindex @acronym{GNOME} Online Accounts +@cindex method @option{gdrive} +@cindex @option{gdrive} method @cindex google drive +@cindex method @option{nextcloud} +@cindex @option{nextcloud} method +@cindex owncloud -Another GVFS-based method allows to access a Google Drive file system. -The file name syntax is here always -@file{@trampfn{gdrive,john.doe@@gmail.com,/path/to/file}}. -@samp{john.doe@@gmail.com} stands here for your Google Drive account. +GVFS-based methods include also @acronym{GNOME} Online Accounts, which +support the @option{Files} service. These are the Google Drive file +system, and the OwnCloud/NextCloud file system. The file name syntax +is here always +@file{@trampfn{gdrive,john.doe@@gmail.com,/path/to/file}} +(@samp{john.doe@@gmail.com} stands here for your Google Drive +account), or @file{@trampfn{nextcloud,user@@host#8081,/path/to/file}} +(@samp{8081} stands for the port number) for OwnCloud/NextCloud files. @anchor{Quick Start Guide: Android} @section Using Android -@cindex method adb -@cindex adb method +@cindex method @option{adb} +@cindex @option{adb} method @cindex android An Android device, which is connected via USB to your local host, can @@ -558,6 +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 @@ -654,8 +656,8 @@ Inline methods can work in situations where an external transfer program is unavailable. Inline methods also work when transferring files between different @emph{user identities} on the same host. -@cindex uuencode -@cindex mimencode +@cindex @command{uuencode} +@cindex @command{mimencode} @cindex base-64 encoding @value{tramp} checks the remote host for the availability and @@ -676,15 +678,15 @@ such optimization. @table @asis @item @option{rsh} -@cindex method rsh -@cindex rsh method +@cindex method @option{rsh} +@cindex @option{rsh} method @command{rsh} is an option for connecting to hosts within local networks since @command{rsh} is not as secure as other methods. @item @option{ssh} -@cindex method ssh -@cindex ssh method +@cindex method @option{ssh} +@cindex @option{ssh} method @command{ssh} is a more secure option than others to connect to a remote host. @@ -695,15 +697,15 @@ host name, a hash sign, then a port number). It is the same as passing @samp{-p 42} to the @command{ssh} command. @item @option{telnet} -@cindex method telnet -@cindex telnet method +@cindex method @option{telnet} +@cindex @option{telnet} method Connecting to a remote host with @command{telnet} is as insecure as the @option{rsh} method. @item @option{su} -@cindex method su -@cindex su method +@cindex method @option{su} +@cindex @option{su} method Instead of connecting to a remote host, @command{su} program allows editing as another user. The host can be either @samp{localhost} or @@ -711,21 +713,27 @@ the host returned by the function @command{(system-name)}. See @ref{Multi-hops} for an exception to this behavior. @item @option{sudo} -@cindex method sudo -@cindex sudo method +@cindex method @option{sudo} +@cindex @option{sudo} method Similar to @option{su} method, @option{sudo} uses @command{sudo}. @command{sudo} must have sufficient rights to start a shell. +For security reasons, a @option{sudo} connection is disabled after a +predefined timeout (5 minutes per default). This can be changed, see +@ref{Predefined connection information}. + @item @option{doas} -@cindex method doas -@cindex doas method +@cindex method @option{doas} +@cindex @option{doas} method -This method is used on OpenBSD like the @command{sudo} command. +This method is used on OpenBSD like the @command{sudo} command. Like +the @option{sudo} method, a @option{doas} connection is disabled after +a predefined timeout. @item @option{sg} -@cindex method sg -@cindex sg method +@cindex method @option{sg} +@cindex @option{sg} method The @command{sg} program allows editing as different group. The host can be either @samp{localhost} or the host returned by the function @@ -734,8 +742,8 @@ denotes a group name. See @ref{Multi-hops} for an exception to this behavior. @item @option{sshx} -@cindex method sshx -@cindex sshx method +@cindex method @option{sshx} +@cindex @option{sshx} method Works like @option{ssh} but without the extra authentication prompts. @option{sshx} uses @samp{ssh -t -t @var{host} -l @var{user} /bin/sh} @@ -755,23 +763,23 @@ missing shell prompts that confuses @value{tramp}. @option{sshx} supports the @samp{-p} argument. @item @option{krlogin} -@cindex method krlogin -@cindex krlogin method -@cindex kerberos (with krlogin method) +@cindex method @option{krlogin} +@cindex @option{krlogin} method +@cindex kerberos (with @option{krlogin} method) This method is also similar to @option{ssh}. It uses the @command{krlogin -x} command only for remote host login. @item @option{ksu} -@cindex method ksu -@cindex ksu method -@cindex kerberos (with ksu method) +@cindex method @option{ksu} +@cindex @option{ksu} method +@cindex kerberos (with @option{ksu} method) This is another method from the Kerberos suite. It behaves like @option{su}. @item @option{plink} -@cindex method plink -@cindex plink method +@cindex method @option{plink} +@cindex @option{plink} method @option{plink} method is for MS Windows users with the PuTTY implementation of SSH@. It uses @samp{plink -ssh} to log in to the @@ -783,8 +791,8 @@ session. @option{plink} method supports the @samp{-P} argument. @item @option{plinkx} -@cindex method plinkx -@cindex plinkx method +@cindex method @option{plinkx} +@cindex @option{plinkx} method Another method using PuTTY on MS Windows with session names instead of host names. @option{plinkx} calls @samp{plink -load @var{session} @@ -814,10 +822,9 @@ methods. @table @asis @item @option{rcp} -@cindex method rcp -@cindex rcp method -@cindex rcp (with rcp method) -@cindex rsh (with rcp method) +@cindex method @option{rcp} +@cindex @option{rcp} method +@cindex @command{rsh} (with @option{rcp} method) This method uses the @command{rsh} and @command{rcp} commands to connect to the remote host and transfer files. This is the fastest @@ -827,10 +834,9 @@ The alternative method @option{remcp} uses the @command{remsh} and @command{rcp} commands. @item @option{scp} -@cindex method scp -@cindex scp method -@cindex scp (with scp method) -@cindex ssh (with scp method) +@cindex method @option{scp} +@cindex @option{scp} method +@cindex @command{ssh} (with @option{scp} method) Using a combination of @command{ssh} to connect and @command{scp} to transfer is the most secure. While the performance is good, it is @@ -844,10 +850,9 @@ argument list to @command{ssh}, and @samp{-P 42} in the argument list to @command{scp}. @item @option{rsync} -@cindex method rsync -@cindex rsync method -@cindex rsync (with rsync method) -@cindex ssh (with rsync method) +@cindex method @option{rsync} +@cindex @option{rsync} method +@cindex @command{ssh} (with @option{rsync} method) @command{ssh} command to connect in combination with @command{rsync} command to transfer is similar to the @option{scp} method. @@ -859,10 +864,9 @@ is lost if the file exists only on one side of the connection. This method supports the @samp{-p} argument. @item @option{scpx} -@cindex method scpx -@cindex scpx method -@cindex scp (with scpx method) -@cindex ssh (with scpx method) +@cindex method @option{scpx} +@cindex @option{scpx} method +@cindex @command{ssh} (with @option{scpx} method) @option{scpx} is useful to avoid login shell questions. It is similar in performance to @option{scp}. @option{scpx} uses @samp{ssh -t -t @@ -876,16 +880,14 @@ This method supports the @samp{-p} argument. @item @option{pscp} @item @option{psftp} -@cindex method pscp -@cindex pscp method -@cindex pscp (with pscp method) -@cindex plink (with pscp method) -@cindex putty (with pscp method) -@cindex method psftp -@cindex psftp method -@cindex pscp (with psftp method) -@cindex plink (with psftp method) -@cindex putty (with psftp method) +@cindex method @option{pscp} +@cindex @option{pscp} method +@cindex @command{plink} (with @option{pscp} method) +@cindex @command{putty} (with @option{pscp} method) +@cindex method @option{psftp} +@cindex @option{psftp} method +@cindex @command{plink} (with @option{psftp} method) +@cindex @command{putty} (with @option{psftp} method) These methods are similar to @option{scp} or @option{sftp}, but they use the @command{plink} command to connect to the remote host, and @@ -898,10 +900,9 @@ session. These methods support the @samp{-P} argument. @item @option{fcp} -@cindex method fcp -@cindex fcp method -@cindex fsh (with fcp method) -@cindex fcp (with fcp method) +@cindex method @option{fcp} +@cindex @option{fcp} method +@cindex @command{fsh} (with @option{fcp} method) This method is similar to @option{scp}, but uses @command{fsh} to connect and @command{fcp} to transfer files. @command{fsh/fcp}, a @@ -913,18 +914,17 @@ benefits. The command used for this connection is: @samp{fsh @var{host} -l @var{user} /bin/sh -i} -@cindex method fsh -@cindex fsh method +@cindex method @option{fsh} +@cindex @option{fsh} method @option{fsh} has no inline method since the multiplexing it offers is not useful for @value{tramp}. @command{fsh} connects to remote host and @value{tramp} keeps that one connection open. @item @option{nc} -@cindex method nc -@cindex nc method -@cindex nc (with nc method) -@cindex telnet (with nc method) +@cindex method @option{nc} +@cindex @option{nc} method +@cindex @command{telnet} (with @option{nc} method) Using @command{telnet} to connect and @command{nc} to transfer files is sometimes the only combination suitable for accessing routers or @@ -932,19 +932,43 @@ NAS hosts. These dumb devices have severely restricted local shells, such as the @command{busybox} and do not host any other encode or decode programs. +@item @option{sudoedit} +@cindex method @option{sudoedit} +@cindex @option{sudoedit} method + +The @option{sudoedit} method allows to edit a file as a different user +on the local host. You could regard this as @value{tramp}'s +implementation of the @command{sudoedit}. Contrary to the +@option{sudo} method, all magic file name functions are implemented by +single @command{sudo @dots{}} commands. The purpose is to make +editing such a file as secure as possible; there must be no session +running in the Emacs background which could be attacked from inside +Emacs. + +Consequently, external processes are not implemented. + +The host name of such remote file names must represent the local host. +Since the default value is already proper, it is recommended not to +use any host name in the remote file name, like +@file{@trampfn{sudoedit,,/path/to/file}} or +@file{@trampfn{sudoedit,user@@,/path/to/file}}. + +Like the @option{sudo} method, a @option{sudoedit} password expires +after a predefined timeout. + @item @option{ftp} -@cindex method ftp -@cindex ftp method +@cindex method @option{ftp} +@cindex @option{ftp} method When @value{tramp} uses @option{ftp}, it forwards requests to whatever ftp program is specified by Ange FTP. This external program must be capable of servicing requests from @value{tramp}. @item @option{smb} -@cindex method smb -@cindex smb method -@cindex ms windows (with smb method) -@cindex smbclient +@cindex method @option{smb} +@cindex @option{smb} method +@cindex ms windows (with @option{smb} method) +@cindex @command{smbclient} This non-native @value{tramp} method connects via the Server Message Block (SMB) networking protocol to hosts running file servers that are @@ -1015,9 +1039,9 @@ can. @item @option{adb} -@cindex method adb -@cindex adb method -@cindex android (with adb method) +@cindex method @option{adb} +@cindex @option{adb} method +@cindex android (with @option{adb} method) @vindex tramp-adb-program @vindex PATH@r{, environment variable} @@ -1052,6 +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 @@ -1061,7 +1127,7 @@ numbers are not applicable to Android devices connected through USB@. @cindex gvfs based methods @cindex dbus -GVFS is the virtual file system for the Gnome Desktop, +GVFS is the virtual file system for the @acronym{GNOME} Desktop, @uref{https://en.wikipedia.org/wiki/GVFS}. Remote files on GVFS are mounted locally through FUSE and @value{tramp} uses this locally mounted directory internally. @@ -1072,8 +1138,8 @@ D-Bus, dbus}. @table @asis @item @option{afp} -@cindex method afp -@cindex afp method +@cindex method @option{afp} +@cindex @option{afp} method This method is for connecting to remote hosts with the Apple Filing Protocol for accessing files on macOS volumes. @value{tramp} access @@ -1082,10 +1148,10 @@ syntax requires a leading volume (share) name, for example: @item @option{dav} @item @option{davs} -@cindex method dav -@cindex method davs -@cindex dav method -@cindex davs method +@cindex method @option{dav} +@cindex method @option{davs} +@cindex @option{dav} method +@cindex @option{davs} method @option{dav} method provides access to WebDAV files and directories based on standard protocols, such as HTTP@. @option{davs} does the same @@ -1093,11 +1159,11 @@ but with SSL encryption. Both methods support the port numbers. Paths being part of the WebDAV volume to be mounted by GVFS, as it is common for OwnCloud or NextCloud file names, are not supported by -these methods. +these methods. See method @option{nextcloud} for handling them. @item @option{gdrive} -@cindex method gdrive -@cindex gdrive method +@cindex method @option{gdrive} +@cindex @option{gdrive} method @cindex google drive Via the @option{gdrive} method it is possible to access your Google @@ -1111,36 +1177,36 @@ Since Google Drive uses cryptic blob file names internally, could produce unexpected behavior in case two files in the same directory have the same @code{display-name}, such a situation must be avoided. -@item @option{obex} -@cindex method obex -@cindex obex method +@item @option{nextcloud} +@cindex @acronym{GNOME} Online Accounts +@cindex method @option{nextcloud} +@cindex @option{nextcloud} method +@cindex owncloud -OBEX is an FTP-like access protocol for cell phones and similar simple -devices. @value{tramp} supports OBEX over Bluetooth. +As the name indicates, the method @option{nextcloud} allows you to +access OwnCloud or NextCloud hosted files and directories. Like the +@option{gdrive} method, your credentials must be populated in your +@command{Online Accounts} application outside Emacs. The method +supports port numbers. @item @option{sftp} -@cindex method sftp -@cindex sftp method +@cindex method @option{sftp} +@cindex @option{sftp} method This method uses @command{sftp} in order to securely access remote hosts. @command{sftp} is a more secure option for connecting to hosts that for security reasons refuse @command{ssh} connections. -@item @option{synce} -@cindex method synce -@cindex synce method - -@option{synce} method allows connecting to MS Windows Mobile devices. -It uses GVFS for mounting remote files and directories via FUSE and -requires the SYNCE-GVFS plugin. - @end table @defopt tramp-gvfs-methods This user option is a list of external methods for GVFS@. By default, this list includes @option{afp}, @option{dav}, @option{davs}, -@option{gdrive}, @option{obex}, @option{sftp} and @option{synce}. -Other methods to include are: @option{ftp} and @option{smb}. +@option{gdrive}, @option{nextcloud} and @option{sftp}. Other methods +to include are @option{ftp}, @option{http}, @option{https} and +@option{smb}. These methods are not intended to be used directly as +GVFS based method. Instead, they are added here for the benefit of +@ref{Archive file names}. @end defopt @@ -1378,7 +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 @@ -1395,8 +1462,10 @@ Opening @file{@trampfn{sudo,randomhost.your.domain,}} first connects to @samp{randomhost.your.domain} via @code{ssh} under your account name, and then performs @code{sudo -u root} on that host. -It is key for the sudo method in the above example to be applied on -the host after reaching it and not on the local host. +It is key for the @option{sudo} method in the above example to be +applied on the host after reaching it and not on the local host. +@value{tramp} checks therefore, that the host name for such hops +matches the host name of the previous hop. @var{host}, @var{user} and @var{proxy} can also take Lisp forms. These forms when evaluated must return either a string or @code{nil}. @@ -1492,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 @@ -1641,7 +1778,7 @@ the need. The package @file{auth-source.el}, originally developed for No Gnus, reads passwords from different sources, @xref{Help for users, , auth-source, auth}. The default authentication file is -@file{~/.authinfo.gpg}, but this can be changed via the variable +@file{~/.authinfo.gpg}, but this can be changed via the user option @code{auth-sources}. @noindent @@ -1660,9 +1797,26 @@ file name syntax, must be appended to the machine and login items: machine melancholia#4711 port davs login daniel%BIZARRE password geheim @end example +@vindex auth-source-save-behavior +If there doesn't exist a proper entry, the password is read +interactively. After successful login (verification of the password), +it is offered to save a corresponding entry for further use by +@code{auth-source} backends which support this. This could be changed +by setting the user option @code{auth-source-save-behavior} to @code{nil}. + @vindex auth-source-debug Set @code{auth-source-debug} to @code{t} to debug messages. +@vindex ange-ftp-netrc-filename +@strong{Note} that @file{auth-source.el} is not used for @option{ftp} +connections, because @value{tramp} passes the work to Ange FTP@. If +you want, for example, use your @file{~/.authinfo.gpg} authentication +file, you must customize @code{ange-ftp-netrc-filename}: + +@lisp +(customize-set-variable 'ange-ftp-netrc-filename "~/.authinfo.gpg") +@end lisp + @anchor{Caching passwords} @subsection Caching passwords @@ -1742,6 +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}. @@ -1808,9 +1980,9 @@ shell supports the login argument @samp{-l}. @end defopt When remote search paths are changed, local @value{tramp} caches must -be recomputed. To force @value{tramp} to recompute afresh, exit -Emacs, remove the persistent file (@pxref{Connection caching}), and -restart Emacs. +be recomputed. To force @value{tramp} to recompute afresh, call +@kbd{M-x tramp-cleanup-this-connection @key{RET}} or friends +(@pxref{Cleanup remote connections}). @node Remote shell setup @@ -2019,10 +2191,10 @@ shell-specific config files. For example, bash can use parsing. This redefinition affects the looks of a prompt in an interactive remote shell through commands, such as @kbd{M-x shell @key{RET}}. Such prompts, however, can be reset to something more -readable and recognizable using these @value{tramp} variables. +readable and recognizable using these environment variables. -@value{tramp} sets the @env{INSIDE_EMACS} variable in the startup -script file @file{~/.emacs_SHELLNAME}. +@value{tramp} sets the @env{INSIDE_EMACS} environment variable in the +startup script file @file{~/.emacs_SHELLNAME}. @env{SHELLNAME} is @code{bash} or equivalent shell names. Change it by setting the environment variable @env{ESHELL} in the @file{.emacs} as @@ -2048,8 +2220,8 @@ fi @end ifinfo @item @command{busybox} / @command{nc} -@cindex unix command nc -@cindex nc unix command +@cindex unix command @command{nc} +@cindex @command{nc} unix command @value{tramp}'s @option{nc} method uses the @command{nc} command to install and execute a listener as follows (see @code{tramp-methods}): @@ -2267,8 +2439,8 @@ to direct all auto saves to that location. This section is incomplete. Please share your solutions. -@cindex method sshx with cygwin -@cindex sshx method with cygwin +@cindex method @option{sshx} with cygwin +@cindex @option{sshx} method with cygwin Cygwin's @command{ssh} works only with a Cygwin version of Emacs. To check for compatibility: type @kbd{M-x eshell @key{RET}}, and start @@ -2290,8 +2462,8 @@ On @uref{https://www.emacswiki.org/emacs/SshWithNTEmacs, the Emacs Wiki} it is explained how to use the helper program @command{fakecygpty} to fix this problem. -@cindex method scpx with cygwin -@cindex scpx method with cygwin +@cindex method @option{scpx} with cygwin +@cindex @option{scpx} method with cygwin When using the @option{scpx} access method, Emacs may call @command{scp} with MS Windows file naming, such as @code{c:/foo}. But @@ -2347,6 +2519,7 @@ is a feature of Emacs that may cause missed prompts when using * Ad-hoc multi-hops:: Declaring multiple hops in the file name. * Remote processes:: Integration with other Emacs packages. * Cleanup remote connections:: Cleanup remote connections. +* Archive file names:: Access to files in file archives. @end menu @@ -2453,9 +2626,10 @@ and @code{user@@} parts are optional. @defvar tramp-file-name-regexp This variable keeps a regexp which matches the selected remote file -name syntax. However, it is not recommended to use this variable in -external packages, a call of @code{file-remote-p} is much more -appropriate. +name syntax. Its value changes after every call of +@code{tramp-change-syntax}. However, it is not recommended to use +this variable in external packages, a call of @code{file-remote-p} is +much more appropriate. @ifinfo @pxref{Magic File Names, , , elisp} @end ifinfo @@ -2531,6 +2705,14 @@ names on that host. When the configuration (@pxref{Customizing Completion}) includes user names, then the completion lists will account for the user names as well. +@vindex tramp-completion-use-auth-sources +Results from @code{auth-sources} search (@pxref{Using an +authentication file}) are added to the completion candidates. This +search could be annoying, for example due to a passphrase request of +the @file{~/.authinfo.gpg} authentication file. The user option +@code{tramp-completion-use-auth-sources} controls, whether such a +search is performed during completion. + Remote hosts previously visited or hosts whose connections are kept persistently (@pxref{Connection caching}) will be included in the completion lists. @@ -2553,7 +2735,7 @@ Example: @print{} @trampfn{ssh,melancholia,/etc} @kbd{C-x C-f @trampfn{ssh,melancholia,//etc} @key{TAB}} - @print{} /etc + @print{} @trampfn{ssh,melancholia,/etc} @kbd{C-x C-f @trampfn{ssh,melancholia,/usr/local/bin///etc} @key{TAB}} @print{} /etc @@ -2579,9 +2761,9 @@ directory contents. @cindex multi-hop, ad-hoc @cindex proxy hosts, ad-hoc -@value{tramp} file name syntax can accommodate ad hoc specification of +@value{tramp} file name syntax can accommodate ad-hoc specification of multiple proxies without using @code{tramp-default-proxies-alist} -configuration setup(@pxref{Multi-hops}). +configuration setup (@pxref{Multi-hops}). Each proxy is specified using the same syntax as the remote host specification minus the file name part. Each hop is separated by a @@ -2596,13 +2778,14 @@ proxy @samp{bird@@bastion} to a remote file on @samp{you@@remotehost}: Each involved method must be an inline method (@pxref{Inline methods}). -Proxies can take patterns @code{%h} or @code{%u}. - @value{tramp} adds the ad-hoc definitions on the fly to -@code{tramp-default-proxies-alist} and is available for re-use -during that Emacs session. Subsequent @value{tramp} connections to -the same remote host can then use the shortcut form: -@samp{@trampfn{ssh,you@@remotehost,/path}}. +@code{tramp-default-proxies-alist} and is available for re-use during +that Emacs session. Subsequent @value{tramp} connections to the same +remote host can then use the shortcut form: +@samp{@trampfn{ssh,you@@remotehost,/path}}. Ad-hoc definitions are +removed from @code{tramp-default-proxies-alist} via the command +@kbd{M-x tramp-cleanup-all-connections @key{RET}} (@pxref{Cleanup +remote connections}). @defopt tramp-save-ad-hoc-proxies For ad-hoc definitions to be saved automatically in @@ -2614,6 +2797,17 @@ For ad-hoc definitions to be saved automatically in @end lisp @end defopt +Ad-hoc proxies can take patterns @code{%h} or @code{%u} like in +@code{tramp-default-proxies-alist}. The following file name expands +to user @code{root} on host @code{remotehost}, starting with an +@option{ssh} session on host @code{remotehost}: +@samp{@value{prefix}ssh@value{postfixhop}%h|su@value{postfixhop}remotehost@value{postfix}}. + +On the other hand, if a trailing hop does not specifiy a host name, +the host name of the previous hop is reused. Therefore, the following +file name is equivalent to the previous example: +@samp{@value{prefix}ssh@value{postfixhop}remotehost|su@value{postfixhop}@value{postfix}}. + @node Remote processes @section Integration with other Emacs packages @@ -2877,7 +3071,7 @@ uid=0(root) gid=0(root) groups=0(root) @anchor{Running a debugger on a remote host} @subsection Running a debugger on a remote host -@cindex @code{gud} +@cindex @file{gud.el} @cindex @code{gdb} @cindex @code{perldb} @@ -2982,16 +3176,254 @@ as in @code{tramp-cleanup-connection}. @deffn Command tramp-cleanup-all-connections Flushes all active remote connection objects, the same as in -@code{tramp-cleanup-connection}. +@code{tramp-cleanup-connection}. This command removes also ad-hoc +proxy definitions (@pxref{Ad-hoc multi-hops}). + @end deffn @deffn Command tramp-cleanup-all-buffers Just as for @code{tramp-cleanup-all-connections}, all remote -connections are cleaned up in addition to killing buffers related to -that remote connection. +connections and ad-hoc proxy definition are cleaned up in addition to +killing buffers related to that remote connection. @end deffn +@node Archive file names +@section Archive file names +@cindex file archives +@cindex archive file names +@cindex method archive +@cindex archive method + +@value{tramp} offers also transparent access to files inside file +archives. This is possible only on machines which have installed the +virtual file system for the @acronym{GNOME} Desktop (GVFS), @ref{GVFS +based methods}. Internally, file archives are mounted via the GVFS +@option{archive} method. + +A file archive is a regular file of kind @file{/path/to/dir/file.EXT}. +The extension @samp{.EXT} identifies the type of the file archive. A +file inside a file archive, called archive file name, has the name +@file{/path/to/dir/file.EXT/dir/file}. + +Most of the @ref{Magic File Names, , magic file name operations, +elisp}, are implemented for archive file names, exceptions are all +operations which write into a file archive, and process related +operations. Therefore, functions like + +@lisp +(copy-file "/path/to/dir/file.tar/dir/file" "/somewhere/else") +@end lisp + +@noindent +work out of the box. This is also true for file name completion, and +for libraries like @code{dired} or @code{ediff}, which accept archive +file names as well. + +@vindex tramp-archive-suffixes +File archives are identified by the file name extension @samp{.EXT}. +Since GVFS uses internally the library @code{libarchive(3)}, all +suffixes, which are accepted by this library, work also for archive +file names. Accepted suffixes are listed in the constant +@code{tramp-archive-suffixes}. They are + +@itemize +@item @samp{.7z} --- +7-Zip archives +@cindex @file{7z} file archive suffix +@cindex file archive suffix @file{7z} + +@item @samp{.apk} --- +Android package kits +@cindex @file{apk} file archive suffix +@cindex file archive suffix @file{apk} + +@item @samp{.ar} --- +UNIX archiver formats +@cindex @file{ar} file archive suffix +@cindex file archive suffix @file{ar} + +@item @samp{.cab}, @samp{.CAB} --- +Microsoft Windows cabinets +@cindex @file{cab} file archive suffix +@cindex @file{CAB} file archive suffix +@cindex file archive suffix @file{cab} +@cindex file archive suffix @file{CAB} + +@item @samp{.cpio} --- +CPIO archives +@cindex @file{cpio} file archive suffix +@cindex file archive suffix @file{cpio} + +@item @samp{.deb} --- +Debian packages +@cindex @file{deb} file archive suffix +@cindex file archive suffix @file{deb} + +@item @samp{.depot} --- +HP-UX SD depots +@cindex @file{depot} file archive suffix +@cindex file archive suffix @file{depot} + +@item @samp{.exe} --- +Self extracting Microsoft Windows EXE files +@cindex @file{exe} file archive suffix +@cindex file archive suffix @file{exe} + +@item @samp{.iso} --- +ISO 9660 images +@cindex @file{iso} file archive suffix +@cindex file archive suffix @file{iso} + +@item @samp{.jar} --- +Java archives +@cindex @file{jar} file archive suffix +@cindex file archive suffix @file{jar} + +@item @samp{.lzh}, @samp{.LZH} --- +Microsoft Windows compressed LHA archives +@cindex @file{lzh} file archive suffix +@cindex @file{LZH} file archive suffix +@cindex file archive suffix @file{lzh} +@cindex file archive suffix @file{LZH} + +@item @samp{.msu}, @samp{.MSU} --- +Microsoft Windows Update packages +@cindex @file{msu} file archive suffix +@cindex @file{MSU} file archive suffix +@cindex file archive suffix @file{msu} +@cindex file archive suffix @file{MSU} + +@item @samp{.mtree} --- +BSD mtree format +@cindex @file{mtree} file archive suffix +@cindex file archive suffix @file{mtree} + +@item @samp{.odb}, @samp{.odf}, @samp{.odg}, @samp{.odp}, @samp{.ods}, +@samp{.odt} --- +OpenDocument formats +@cindex @file{odb} file archive suffix +@cindex @file{odf} file archive suffix +@cindex @file{odg} file archive suffix +@cindex @file{odp} file archive suffix +@cindex @file{ods} file archive suffix +@cindex @file{odt} file archive suffix +@cindex file archive suffix @file{odb} +@cindex file archive suffix @file{odf} +@cindex file archive suffix @file{odg} +@cindex file archive suffix @file{odp} +@cindex file archive suffix @file{ods} +@cindex file archive suffix @file{odt} + +@item @samp{.pax} --- +Posix archives +@cindex @file{pax} file archive suffix +@cindex file archive suffix @file{pax} + +@item @samp{.rar} --- +RAR archives +@cindex @file{rar} file archive suffix +@cindex file archive suffix @file{rar} + +@item @samp{.rpm} --- +Red Hat packages +@cindex @file{rpm} file archive suffix +@cindex file archive suffix @file{rpm} + +@item @samp{.shar} --- +Shell archives +@cindex @file{shar} file archive suffix +@cindex file archive suffix @file{shar} + +@item @samp{.tar}, @samp{.tbz}, @samp{.tgz}, @samp{.tlz}, @samp{.txz} --- +(Compressed) tape archives +@cindex @file{tar} file archive suffix +@cindex @file{tbz} file archive suffix +@cindex @file{tgz} file archive suffix +@cindex @file{tlz} file archive suffix +@cindex @file{txz} file archive suffix +@cindex file archive suffix @file{tar} +@cindex file archive suffix @file{tbz} +@cindex file archive suffix @file{tgz} +@cindex file archive suffix @file{tlz} +@cindex file archive suffix @file{txz} + +@item @samp{.warc} --- +Web archives +@cindex @file{warc} file archive suffix +@cindex file archive suffix @file{warc} + +@item @samp{.xar} --- +macOS XAR archives +@cindex @file{xar} file archive suffix +@cindex file archive suffix @file{xar} + +@item @samp{.xpi} --- +XPInstall Mozilla addons +@cindex @file{xpi} file archive suffix +@cindex file archive suffix @file{xpi} + +@item @samp{.xps} --- +Open XML Paper Specification (OpenXPS) documents +@cindex @file{xps} file archive suffix +@cindex file archive suffix @file{xps} + +@item @samp{.zip}, @samp{.ZIP} --- +ZIP archives +@cindex @file{zip} file archive suffix +@cindex @file{ZIP} file archive suffix +@cindex file archive suffix @file{zip} +@cindex file archive suffix @file{ZIP} +@end itemize + +@vindex tramp-archive-compression-suffixes +File archives could also be compressed, identified by an additional +compression suffix. Valid compression suffixes are listed in the +constant @code{tramp-archive-compression-suffixes}. They are +@samp{.bz2}, @samp{.gz}, @samp{.lrz}, @samp{.lz}, @samp{.lz4}, +@samp{.lzma}, @samp{.lzo}, @samp{.uu}, @samp{.xz} and @samp{.Z}. A +valid archive file name would be +@file{/path/to/dir/file.tar.gz/dir/file}. Even several suffixes in a +row are possible, like @file{/path/to/dir/file.tar.gz.uu/dir/file}. + +@vindex tramp-archive-all-gvfs-methods +An archive file name could be a remote file name, as in +@file{/ftp:anonymous@@ftp.gnu.org:/gnu/tramp/tramp-2.3.2.tar.gz/INSTALL}. +Since all file operations are mapped internally to GVFS operations, +remote file names supported by @code{tramp-gvfs} perform better, +because no local copy of the file archive must be downloaded first. +For example, @samp{/sftp:user@@host:...} performs better than the +similar @samp{/scp:user@@host:...}. See the constant +@code{tramp-archive-all-gvfs-methods} for a complete list of +@code{tramp-gvfs} supported method names. + +If @code{url-handler-mode} is enabled, archives could be visited via +URLs, like +@file{https://ftp.gnu.org/gnu/tramp/tramp-2.3.2.tar.gz/INSTALL}. This +allows complex file operations like + +@lisp +@group +(progn + (url-handler-mode 1) + (ediff-directories + "https://ftp.gnu.org/gnu/tramp/tramp-2.3.1.tar.gz/tramp-2.3.1" + "https://ftp.gnu.org/gnu/tramp/tramp-2.3.2.tar.gz/tramp-2.3.2" "")) +@end group +@end lisp + +It is even possible to access file archives in file archives, as + +@lisp +@group +(progn + (url-handler-mode 1) + (find-file + "http://ftp.debian.org/debian/pool/main/c/coreutils/coreutils_8.28-1_amd64.deb/control.tar.gz/control")) +@end group +@end lisp + + @node Bug Reports @chapter Reporting Bugs and Problems @cindex bug reports @@ -3007,9 +3439,9 @@ discussing, and general discussions about @value{tramp}. post for moderator approval. Sometimes this approval step may take as long as 48 hours due to public holidays. -@email{tramp-devel@@gnu.org} is the mailing list. Messages sent to -this address go to all the subscribers. This is @emph{not} the -address to send subscription requests to. +@email{@value{tramp-bug-report-address}} is the mailing list. +Messages sent to this address go to all the subscribers. This is +@emph{not} the address to send subscription requests to. To subscribe to the mailing list, visit: @uref{https://lists.gnu.org/mailman/listinfo/tramp-devel/, the @@ -3043,7 +3475,9 @@ When including @value{tramp}'s messages in the bug report, increase the verbosity level to 6 (@pxref{Traces and Profiles, Traces}) in the @file{~/.emacs} file before repeating steps to the bug. Include the contents of the @file{*tramp/foo*} and @file{*debug tramp/foo*} -buffers with the bug report. +buffers with the bug report. Both buffers could contain +non-@acronym{ASCII} characters which are relevant for analysis, append +the buffers as attachments to the bug report. @strong{Note} that a verbosity level greater than 6 is not necessary at this stage. Also note that a verbosity level of 6 or greater, the @@ -3076,7 +3510,8 @@ Where is the latest @value{tramp}? @item Which systems does it work on? -The package works successfully on Emacs 24, Emacs 25, and Emacs 26. +The package works successfully on Emacs 24, Emacs 25, Emacs 26, and +Emacs 27. While Unix and Unix-like systems are the primary remote targets, @value{tramp} has equal success connecting to other platforms, such as @@ -3099,6 +3534,7 @@ Keep the file @code{tramp-persistency-file-name}, which is where @value{tramp} caches remote information about hosts and files. Caching is enabled by default. Don't disable it. +@vindex remote-file-name-inhibit-cache Set @code{remote-file-name-inhibit-cache} to @code{nil} if remote files are not independently updated outside @value{tramp}'s control. That cache cleanup will be necessary if the remote directories or @@ -3251,6 +3687,16 @@ first saving to a temporary file. @item +@value{tramp} fails in a chrooted environment + +@vindex tramp-local-host-regexp +When connecting to a local host, @value{tramp} uses some internal +optimizations. They fail, when there is a chrooted environment. In +order to disable those optimizations, set user option +@code{tramp-local-host-regexp} to @code{nil}. + + +@item @value{tramp} does not recognize if a @command{ssh} session hangs @command{ssh} sessions on the local host hang when the network is @@ -3410,7 +3856,7 @@ 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} @env{HISTSIZE} are set to 0. +@env{HISTFILESIZE} and @env{HISTSIZE} are set to 0. Alternatively, @code{tramp-histfile-override} could be a string. Environment variable @env{HISTFILE} is set to this file name then. Be @@ -3763,6 +4209,15 @@ export EDITOR=/path/to/emacsclient.sh @item +How to determine whether a buffer is remote? + +The buffer-local variable @code{default-directory} tells this. If the +form @code{(file-remote-p default-directory)} returns non-@code{nil}, +the buffer is remote. See the optional arguments of +@code{file-remote-p} for determining details of the remote connection. + + +@item How to disable other packages from calling @value{tramp}? There are packages that call @value{tramp} without the user ever @@ -3804,6 +4259,7 @@ in @file{.emacs}: @end lisp @item +@vindex tramp-mode To disable both @value{tramp} (and Ange FTP), set @code{tramp-mode} to @code{nil} in @file{.emacs}. @strong{Note}, that we don't use @code{customize-set-variable}, in order to avoid loading @value{tramp}. @@ -3813,6 +4269,21 @@ To disable both @value{tramp} (and Ange FTP), set @code{tramp-mode} to @end lisp @item +@vindex tramp-ignored-file-name-regexp +To deactivate @value{tramp} for some look-alike remote file names, set +@code{tramp-ignored-file-name-regexp} to a proper regexp in +@file{.emacs}. @strong{Note}, that we don't use +@code{customize-set-variable}, in order to avoid loading +@value{tramp}. + +@lisp +(setq tramp-ignored-file-name-regexp "\\`/ssh:example\\.com:") +@end lisp + +This is needed, if you mount for example a virtual file system on your +local host's root directory as @file{/ssh:example.com:}. + +@item To unload @value{tramp}, type @kbd{M-x tramp-unload-tramp @key{RET}}. Unloading @value{tramp} resets Ange FTP plugins also. @end itemize @@ -3821,7 +4292,7 @@ Unloading @value{tramp} resets Ange FTP plugins also. @c For the developer @node Files directories and localnames -@chapter How file names, directories and localnames are mangled and managed. +@chapter How file names, directories and localnames are mangled and managed @menu * Localname deconstruction:: Splitting a localname into its component parts. @@ -3847,6 +4318,7 @@ handlers. @section Integrating with external Lisp packages @subsection File name completion. +@vindex non-essential Sometimes, it is not convenient to open a new connection to a remote host, including entering the password and alike. For example, this is nasty for packages providing file name completion. Such a package diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index aecbbe261c8..f5cc2bae179 100644 --- a/doc/misc/trampver.texi +++ b/doc/misc/trampver.texi @@ -5,12 +5,12 @@ @c Copyright (C) 2003-2019 Free Software Foundation, Inc. @c See file doclicense.texi for copying conditions. -@c In the Tramp GIT, the version number is auto-frobbed from -@c configure.ac, so you should edit that file and run -@c "autoconf && ./configure" to change the version number. -@set trampver 2.3.4.26.2 +@c In the Tramp GIT, the version number is auto-frobbed from tramp.el, +@c and the bug report address is auto-frobbed from configure.ac. +@set trampver 2.4.1 +@set tramp-bug-report-address tramp-devel@@gnu.org -@c Other flags from configuration +@c Other flags from configuration. @set instprefix /usr/local @set lispdir /usr/local/share/emacs/site-lisp @set infodir /usr/local/share/info @@ -44,3 +44,17 @@ @set ipv6prefix @set ipv6postfix @end ifset + +@c Macro for formatting a file name according to the respective +@c syntax. trampver.texi is included several times in tramp.texi and +@c trampinst.texi. Redefining the macro is reported as warning for +@c creating the dvi and pdf files, so we declare the macro only the +@c first time this file is included. +@ifclear trampfndefined +@set trampfndefined +@macro trampfn {method, userhost, localname} +@value{prefix}@c +\method\@value{postfixhop}@c +\userhost\@value{postfix}\localname\ +@end macro +@end ifclear diff --git a/doc/misc/url.texi b/doc/misc/url.texi index b190c58c023..0cdfcac24e8 100644 --- a/doc/misc/url.texi +++ b/doc/misc/url.texi @@ -571,13 +571,6 @@ if it has the file suffix @file{.z}, @file{.gz}, @file{.Z}, hard-coded, and cannot be altered by customizing @code{jka-compr-compression-info-list}.) -@defopt url-directory-index-file -This option specifies the filename to look for when a @code{file} or -@code{ftp} URL specifies a directory. The default is -@file{index.html}. If this file exists and is readable, it is viewed. -Otherwise, Emacs visits the directory using Dired. -@end defopt - @node info @section info @cindex Info @@ -1291,6 +1284,20 @@ It may also be a list of the types of messages to be logged. @end defopt @defopt url-privacy-level @end defopt +@defopt url-lastloc-privacy-level +Provided @code{lastloc} is not prohibited by @code{url-privacy-level}, +this determines who we send our last location to. @code{none} means +we include our last location in every outgoing request. +@code{domain-match} means we send it only if the domain of our last +location matches the domain of the URI we are requesting. +@code{host-match} means we only send our last location back to the +same host. The default is @code{domain-match}. + +Using @code{domain-match} for this option requires emacs to make one +or more DNS requests each time a new host is contacted, to determine +the domain of the host. Results of these lookups are cached, so +repeated visits do not require repeated domain lookups. +@end defopt @defopt url-uncompressor-alist @end defopt @defopt url-passwd-entry-func |