diff options
Diffstat (limited to 'doc')
72 files changed, 4490 insertions, 2021 deletions
diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi index 2eb837f1510..c70e583b9ed 100644 --- a/doc/emacs/buffers.texi +++ b/doc/emacs/buffers.texi @@ -411,6 +411,18 @@ Remove all flags from the current line, and move down @kindex DEL @r{(Buffer Menu)} Move to the previous line and remove all flags on that line (@code{Buffer-menu-backup-unmark}). + +@item M-@key{DEL} +@findex Buffer-menu-unmark-all-buffers +@kindex M-DEL @r{(Buffer Menu)} +Remove a particular flag from all lines +(@code{Buffer-menu-unmark-all-buffers}). + +@item U +@findex Buffer-menu-unmark-all +@kindex U @r{(Buffer Menu)} +Remove all flags from all the lines +(@code{Buffer-menu-unmark-all}). @end table @noindent diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index df0764ee6b7..a416734d40e 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -382,6 +382,14 @@ use of this feature by setting @code{grep-highlight-matches} to @code{t}. When displaying a match in the source buffer, the exact match will be highlighted, instead of the entire source line. + The @command{grep} commands will offer to save buffers before +running. This is controlled by the @code{grep-save-buffers} variable. +The possible values are either @code{nil} (don't save), @code{ask} +(ask before saving), a function which will be used as a predicate (and +is called with the file name as the parameter and should return +non-nil if the buffer is to be saved), and any other non-@code{nil} +value means that all buffers should be saved without asking. + @findex grep-find @findex find-grep The command @kbd{M-x grep-find} (also available as @kbd{M-x diff --git a/doc/emacs/cal-xtra.texi b/doc/emacs/cal-xtra.texi index 2dff8c9b869..842c0792eda 100644 --- a/doc/emacs/cal-xtra.texi +++ b/doc/emacs/cal-xtra.texi @@ -62,11 +62,6 @@ uses @code{calendar-today-marker} to mark today's date. By default, the calendar uses faces named @code{holiday}, @code{diary}, and @code{calendar-today} for these purposes. -@vindex calendar-load-hook - The variable @code{calendar-load-hook} is a normal hook run when the -calendar package is first loaded (before actually starting to display -the calendar). - @vindex calendar-initial-window-hook Starting the calendar runs the normal hook @code{calendar-initial-window-hook}. Recomputation of the calendar diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi index 8db2ea12c89..524cd8dd268 100644 --- a/doc/emacs/cmdargs.texi +++ b/doc/emacs/cmdargs.texi @@ -283,6 +283,13 @@ which will invoke Emacs with @samp{--script} and supply the name of the script file as @var{file}. Emacs Lisp then treats the @samp{#!} on this first line as a comment delimiter. +@item --no-build-details +@opindex --no-build-details +@cindex build details +@cindex deterministic build +Omit details like system name and build time from the Emacs executable, +so that builds are more deterministic. + @item -q @opindex -q @itemx --no-init-file @@ -329,12 +336,16 @@ setting @code{inhibit-x-resources} to @code{t} (@pxref{Resources}). @opindex -daemon @itemx --daemon[=@var{name}] @opindex --daemon +@itemx --old-daemon[=@var{name}] +@itemx --new-daemon[=@var{name}] Start Emacs as a daemon---after Emacs starts up, it starts the Emacs -server and disconnects from the terminal without opening any frames. +server without opening any frames. (Optionally, you can specify an explicit @var{name} for the server.) You can then use the @command{emacsclient} command to connect to Emacs for editing. @xref{Emacs Server}, for information about using Emacs -as a daemon. +as a daemon. An ``old-style'' daemon disconnects from the terminal +and runs in the background (@samp{--daemon} is an alias for +@samp{--old-daemon}). @item --no-desktop @opindex --no-desktop diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index 771633623f5..01637ae98ad 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -1037,9 +1037,10 @@ explicitly. For example, here's how to obtain the default value of @cindex file local variables A file can specify local variable values to use when editing the -file with Emacs. Visiting the file checks for local variable -specifications; it automatically makes these variables local to the -buffer, and sets them to the values specified in the file. +file with Emacs. Visiting the file or setting a major mode checks for +local variable specifications; it automatically makes these variables +local to the buffer, and sets them to the values specified in the +file. @menu * Specifying File Variables:: Specifying file local variables. @@ -1298,7 +1299,11 @@ accomplished with @dfn{directory-local variables}. named @file{.dir-locals.el}@footnote{ On MS-DOS, the name of this file should be @file{_dir-locals.el}, due to limitations of the DOS filesystems. If the filesystem is limited to 8+3 file names, the name -of the file will be truncated by the OS to @file{_dir-loc.el}. } in a +of the file will be truncated by the OS to @file{_dir-loc.el}. +}@footnote{ You can also use @file{.dir-locals-2.el}, which +is loaded in addition. This is useful when @file{.dir-locals.el} is +under version control in a shared repository and can't be used for +personal customizations. } in a directory. Whenever Emacs visits any file in that directory or any of its subdirectories, it will apply the directory-local variables specified in @file{.dir-locals.el}, as though they had been defined as @@ -1340,6 +1345,12 @@ be applied in the current directory, not in any subdirectories. Finally, it specifies a different @file{ChangeLog} file name for any file in the @file{src/imported} subdirectory. +You can specify the variables @code{mode}, @code{eval}, and +@code{unibyte} in your @file{.dir-locals.el}, and they have the same +meanings as they would have in file local variables. @code{coding} +cannot be specified as a directory local variable. @xref{File +Variables}. + @findex add-dir-local-variable @findex delete-dir-local-variable @findex copy-file-locals-to-dir-locals diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi index 1b10ebc8758..2cda51a82fa 100644 --- a/doc/emacs/dired.texi +++ b/doc/emacs/dired.texi @@ -550,13 +550,16 @@ Mark (with @samp{*}) all files whose @emph{contents} contain a match for the regular expression @var{regexp} (@code{dired-mark-files-containing-regexp}). This command is like @kbd{% m}, except that it searches the file contents instead of the file -name. Note that if a file is visited in an Emacs buffer, this command -will look in the buffer without revisiting the file, so the results +name. Note that if a file is visited in an Emacs buffer, +and @code{dired-always-read-filesystem} is @code{nil} (the default), this +command will look in the buffer without revisiting the file, so the results might be inconsistent with the file on disk if its contents has changed since it was last visited. If you don't want this, you may wish reverting the files you have visited in your buffers, or turning on the @code{auto-revert} mode in those buffers, before invoking this -command. @xref{Reverting}. +command. @xref{Reverting}. If you prefer that this command always revisit +the file, without having to revert the file or enable @code{auto-revert} +mode, you might want to set @code{dired-always-read-filesystem} to non-@code{nil}. @item C-/ @itemx C-x u @@ -1314,6 +1317,10 @@ relative). To mark a file for deletion, delete the entire file name. To change the target of a symbolic link, edit the link target name which appears next to the link name. + If you edit the file names to create a new subdirectory, Wdired will +automatically create these new directories. To inhibit this behavior, +set @code{wdired-create-parent-directories} to @code{nil}. + The rest of the text in the buffer, such as the file sizes and modification dates, is marked read-only, so you can't edit it. However, if you set @code{wdired-allow-to-change-permissions} to @@ -1438,6 +1445,13 @@ names into arguments for other Emacs commands. It also displays what it added to the kill ring, so you can use it to display the list of currently marked files in the echo area. +@kindex W @r{(Dired)} +@findex browse-url-of-dired-file + If you have an HTML file in the file listing, it can be useful to +view that file with a browser. The @kbd{W} +(@code{browse-url-of-dired-file}) command will use the standard +configured browser to view that file. + @kindex ( @r{(Dired)} @findex dired-hide-details-mode @vindex dired-hide-details-hide-symlink-targets diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index 391e1a0ed58..492dfc6afd5 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -657,9 +657,16 @@ Whitespace}). @item escape-glyph The face for displaying control characters and escape sequences (@pxref{Text Display}). +@item homoglyph +The face for displaying lookalike characters, i.e., characters that +look like but are not the characters being represented +(@pxref{Text Display}). @item nobreak-space The face for displaying no-break space characters (@pxref{Text Display}). +@item nobreak-hyphen +The face for displaying no-break hyphen characters (@pxref{Text +Display}). @end table The following faces control the appearance of parts of the Emacs @@ -1490,7 +1497,7 @@ characters. To deal with this problem, Emacs displays such characters specially: it displays @code{U+00A0} (no-break space) with the @code{nobreak-space} face, and it displays @code{U+00AD} (soft hyphen), @code{U+2010} (hyphen), and @code{U+2011} (non-breaking -hyphen) with the @code{escape-glyph} face. To disable this, change +hyphen) with the @code{nobreak-hyphen} face. To disable this, change the variable @code{nobreak-char-display} to @code{nil}. If you give this variable a non-@code{nil} and non-@code{t} value, Emacs instead displays such characters as a highlighted backslash followed by a @@ -1517,12 +1524,12 @@ for details. @cindex curly quotes @cindex curved quotes -@cindex escape-glyph face +@cindex homoglyph face If the curved quotes @samp{‘}, @samp{’}, @samp{“}, and @samp{”} are known to look just like @acronym{ASCII} characters, they are shown -with the @code{escape-glyph} face. Curved quotes that cannot be +with the @code{homoglyph} face. Curved quotes that cannot be displayed are shown as their @acronym{ASCII} approximations @samp{`}, -@samp{'}, and @samp{"} with the @code{escape-glyph} face. +@samp{'}, and @samp{"} with the @code{homoglyph} face. @node Cursor Display @section Displaying the Cursor diff --git a/doc/emacs/entering.texi b/doc/emacs/entering.texi index d6cb3cb8b09..7f186cfafe5 100644 --- a/doc/emacs/entering.texi +++ b/doc/emacs/entering.texi @@ -133,6 +133,11 @@ run. One convenient function to use as the value of @code{confirm-kill-emacs} is the function @code{yes-or-no-p}. The default value of @code{confirm-kill-emacs} is @code{nil}. +@vindex confirm-kill-processes + If the value of the variable @code{confirm-kill-processes} is +@code{nil}, @kbd{C-x C-c} does not ask for confirmation before killing +subprocesses started by Emacs. The value is @code{t} by default. + To further customize what happens when Emacs is exiting, see @ref{Killing Emacs,,, elisp, The GNU Emacs Lisp Reference Manual}. diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index 264154be66f..eca41af7a18 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -1560,8 +1560,8 @@ delete-file}. @xref{VC Delete/Rename}. @findex copy-file @cindex copying files - @kbd{M-x copy-file} reads the file @var{old} and writes a new file -named @var{new} with the same contents. + @kbd{M-x copy-file} copies the contents of the file @var{old} to the +file @var{new}. @findex copy-directory @kbd{M-x copy-directory} copies directories, similar to the @@ -1876,6 +1876,11 @@ prevent it from being treated as a remote file name. Thus, if you have a directory named @file{/foo:} and a file named @file{bar} in it, you can refer to that file in Emacs as @samp{/:/foo:/bar}. + If you want to quote only special characters in the local part of a +remote file name, you can quote just the local part. +@samp{/baz:/:/foo:/bar} refers to the file @file{bar} of directory +@file{/foo:} on the host @file{baz}. + @samp{/:} can also prevent @samp{~} from being treated as a special character for a user's home directory. For example, @file{/:/tmp/~hack} refers to a file whose name is @file{~hack} in directory @file{/tmp}. @@ -1974,6 +1979,9 @@ point. Partial Completion mode offers other features extending major mode, you can type @kbd{C-c C-c} (@code{image-toggle-display}) to toggle between displaying the file as an image in the Emacs buffer, and displaying its underlying text (or raw byte) representation. +Additionally you can type @kbd{C-c C-x} (@code{image-toggle-hex-display}) +to toggle between displaying the file as an image in the Emacs buffer, +and displaying it in hex representation. Displaying the file as an image works only if Emacs is compiled with support for displaying such images. If the displayed image is wider or taller than the frame, the usual point motion keys (@kbd{C-f}, diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index 99926dc47be..082de3796c1 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -97,7 +97,8 @@ ring; on a second click, kill it (@code{mouse-save-then-kill}). invoked by clicking with the left mouse button, @kbd{mouse-1}, in the text area of a window. This moves point to the position where you clicked. If that window was not the selected window, it becomes the -selected window. +selected window. You can also activate a region by double-clicking +mouse-1 (@pxref{Word and Line Mouse}). @vindex x-mouse-click-focus-ignore-position Normally, if the frame you clicked in was not the selected frame, it @@ -215,7 +216,7 @@ also copied to the kill ring. @table @kbd @item Double-mouse-1 -Select the text around the word which you click on. +Select the text around the word or character which you click on. Double-clicking on a character with symbol syntax (such as underscore, in C mode) selects the symbol surrounding that character. @@ -226,6 +227,17 @@ ends. Double-clicking on a character with string-delimiter syntax constant (Emacs uses heuristics to figure out whether that character is the beginning or the end of it). +Double-clicking on the beginning of a parenthetical grouping or +beginning string-delimiter moves point to the end of the region, +scrolling the buffer display forward if necessary to show the new +location of point. Double-clicking on the end of a parenthetical +grouping or end string-delimiter keeps point at the end of the region +by default, so the beginning of the region will not be visible if it +is above the top of the window; setting the user option +@code{mouse-select-region-move-to-beginning} to non-nil changes this +to move point to the beginning of the region, scrolling the display +backward if necessary. + @item Double-Drag-mouse-1 Select the text you drag across, in the form of whole words. diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi index bce97dacee2..d6489390ea5 100644 --- a/doc/emacs/glossary.texi +++ b/doc/emacs/glossary.texi @@ -338,8 +338,8 @@ or by rebinding key sequences (@pxref{Keymaps}). @item Daemon A daemon is a standard term for a system-level process that runs in the background. Daemons are often started when the system first starts up. -When Emacs runs in daemon-mode, it runs in the background and does not -open a display. You can then connect to it with the +When Emacs runs in daemon-mode, it does not +open a display. You connect to it with the @command{emacsclient} program. @xref{Emacs Server}. @item Default Argument diff --git a/doc/emacs/m-x.texi b/doc/emacs/m-x.texi index 9e5f50b5e91..4b1165a1130 100644 --- a/doc/emacs/m-x.texi +++ b/doc/emacs/m-x.texi @@ -69,11 +69,13 @@ number, in which case Emacs will show the binding for that many seconds before removing it from display. The default behavior is to display the binding for 2 seconds. +@vindex extended-command-suggest-shorter Commands that don't have key bindings, can still be invoked after typing less than their full name at the @samp{M-x} prompt. Emacs mentions such shorthands in the echo area if they are significantly -shorter than the full command name. The setting of -@code{suggest-key-bindings} affects these hints as well. +shorter than the full command name, and +@code{extended-command-suggest-shorter} is non-@code{nil}. The +setting of @code{suggest-key-bindings} affects these hints as well. In this manual, when we speak of running a command by name, we often omit the @key{RET} that terminates the name. Thus we might say diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index acb6b8c8039..66781ad2bea 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -1590,6 +1590,13 @@ also creates a new item for the current file. For many languages, it can even guess the name of the function or other object that was changed. +@c Not worth it. +@c @vindex change-log-directory-files +To find the change log file, Emacs searches up the directory tree from +the file you are editing. By default, it stops if it finds a +directory that seems to be the root of a version-control repository. +To change this, customize @code{change-log-directory-files}. + @vindex add-log-keep-changes-together When the variable @code{add-log-keep-changes-together} is non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file @@ -2545,10 +2552,10 @@ directory as the default. @vindex tags-file-name Emacs does not actually read in the tags table contents until you try to use them; all @code{visit-tags-table} does is store the file -name in the variable @code{tags-file-name}, and setting the variable -yourself is just as good. The variable's initial value is @code{nil}; -that value tells all the commands for working with tags tables that -they must ask for a tags table file name to use. +name in the variable @code{tags-file-name}, and not much more. The +variable's initial value is @code{nil}; that value tells all the +commands for working with tags tables that they must ask for a tags +table file name to use. Using @code{visit-tags-table} when a tags table is already loaded gives you a choice: you can add the new tags table to the current list diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index a1f611cfb23..2290dec31e2 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -771,6 +771,14 @@ the output buffer. But if you change the value of the variable @code{shell-command-default-error-buffer} to a string, error output is inserted into a buffer of that name. +@vindex shell-command-dont-erase-buffer + By default, the output buffer is erased between shell commands. +If you change the value of the variable +@code{shell-command-dont-erase-buffer} to a non-@code{nil} value, +the output buffer is not erased. This variable also controls where to +set the point in the output buffer after the command completes; see the +documentation of the variable for details. + @node Interactive Shell @subsection Interactive Subshell @@ -1562,7 +1570,7 @@ process. You can solve this problem by setting up Emacs as an @dfn{edit server}, so that it ``listens'' for external edit requests and acts -accordingly. There are two ways to start an Emacs server: +accordingly. There are various ways to start an Emacs server: @itemize @findex server-start @@ -1575,15 +1583,51 @@ dies with the Emacs process. @cindex daemon, Emacs @item -Run Emacs as a @dfn{daemon}, using the @samp{--daemon} command-line -option. @xref{Initial Options}. When Emacs is started this way, it -calls @code{server-start} after initialization, and returns control to -the calling terminal instead of opening an initial frame; it then -waits in the background, listening for edit requests. +Run Emacs as a @dfn{daemon}, using one of the @samp{--daemon} command-line +options. @xref{Initial Options}. When Emacs is started this way, it +calls @code{server-start} after initialization and does not open an +initial frame. It then waits for edit requests from clients. + +@cindex systemd unit file +@item +If your operating system uses @command{systemd} to manage startup, +you can automatically start Emacs in daemon mode when you login +using the supplied @dfn{systemd unit file}. To activate this: +@example +systemctl --user enable emacs +@end example +(If your Emacs was installed into a non-standard location, you may +need to copy the @file{emacs.service} file to a standard directory +such as @file{~/.config/systemd/user/}.) + +@cindex socket activation, systemd, Emacs +@item +An external process can invoke the Emacs server when a connection +event occurs upon a specified socket and pass the socket to the new +Emacs server process. An instance of this is the socket functionality +of @command{systemd}: the @command{systemd} service creates a socket and +listens for connections on it; when @command{emacsclient} connects to +it for the first time, @command{systemd} can launch the Emacs server +and hand over the socket to it for servicing @command{emacsclient} +connections. A setup to use this functionality could be: + +@file{~/.config/systemd/user/emacs.socket}: +@example +[Socket] +ListenStream=/path/to/.emacs.socket + +[Install] +WantedBy=sockets.target +@end example + +(The @file{emacs.service} file described above must also be installed.) + +The @code{ListenStream} path will be the path that Emacs listens for +connections from @command{emacsclient}; this is a file of your choice. @end itemize @cindex @env{TEXEDIT} environment variable - Either way, once an Emacs server is started, you can use a shell + Once an Emacs server is started, you can use a shell command called @command{emacsclient} to connect to the Emacs process and tell it to visit a file. You can then set the @env{EDITOR} environment variable to @samp{emacsclient}, so that external programs diff --git a/doc/emacs/msdos.texi b/doc/emacs/msdos.texi index d0e9ab45c25..eb0fb17ddd1 100644 --- a/doc/emacs/msdos.texi +++ b/doc/emacs/msdos.texi @@ -507,32 +507,64 @@ the variable @code{w32-alt-is-meta} to a @code{nil} value. @findex w32-register-hot-key @findex w32-unregister-hot-key MS-Windows reserves certain key combinations, such as -@kbd{@key{Alt}-@key{TAB}}, for its own use. These key combinations are -intercepted by the system before Emacs can see them. You can use the -@code{w32-register-hot-key} function to allow a key sequence to be -seen by Emacs instead of being grabbed by Windows. This function -registers a key sequence as a @dfn{hot key}, overriding the special -meaning of that key sequence for Windows. (MS-Windows is told that -the key sequence is a hot key only when one of the Emacs windows has -focus, so that the special keys still have their usual meaning for -other Windows applications.) - - The argument to @code{w32-register-hot-key} must be a single key, -with or without modifiers, in vector form that would be acceptable to -@code{define-key}. The meta modifier is interpreted as the @key{Alt} -key if @code{w32-alt-is-meta} is @code{t} (the default), and the hyper -modifier is always interpreted as the Windows key (usually labeled -with @key{start} and the Windows logo). If the function succeeds in -registering the key sequence, it returns the hotkey ID, a number; -otherwise it returns @code{nil}. +@kbd{@key{Alt}-@key{TAB}} and a number of Windows key combinations, +for its own use. These key combinations are intercepted by the system +before Emacs can see them. Also, on Windows 10, all Windows key +combinations are reserved by the system in such a way that they are +never propagated to applications, even if the system does not +currently define a hotkey on the specific combination. You can use +the @code{w32-register-hot-key} function to allow a key sequence to be +seen by Emacs instead of being grabbed by Windows. When registered as +a hot key, the key combination is pulled out of the system's input +queue before it is handled by Windows, effectively overriding the +special meaning of that key sequence for Windows. The override is +only effective when Emacs is active; with other applications on the +foreground the keys behave normally. + + The argument to @code{w32-register-hot-key} must be a single key with a +single modifier, in vector form that would be acceptable to +@code{define-key}. The control and shift modifiers have no effect on the +argument. The meta modifier is interpreted as the @key{Alt} key if +@code{w32-alt-is-meta} is @code{t} (the default), and the super and hyper +modifiers are interpreted according to the bindings of +@code{w32-lwindow-modifier} and @code{w32-rwindow-modifier}. Additionally, a +modifier with the trailing dash but with no key indicates that all +Windows defined hotkeys for that modifier are to be overridden in the +favor of Emacs. @kindex M-TAB@r{, (MS-Windows)} @cindex @kbd{M-@key{TAB}} vs @kbd{@key{Alt}-@key{TAB}} (MS-Windows) @cindex @kbd{@key{Alt}-@key{TAB}} vs @kbd{M-@key{TAB}} (MS-Windows) For example, @code{(w32-register-hot-key [M-tab])} lets you use -@kbd{M-@key{TAB}} normally in Emacs; for instance, to complete the word or -symbol at point at top level, or to complete the current search string -against previously sought strings during incremental search. +@kbd{M-@key{TAB}} normally in Emacs; for instance, to complete the +word or symbol at point at top level, or to complete the current +search string against previously sought strings during incremental +search. @code{(w32-register-hot-key [s-])} with +@code{w32-lwindow-modifier} bound to @code{super} disables all the +Windows' own Windows key based shortcuts.@footnote{There is one known +exception: The combination @kbd{@key{Windows}-@key{L}} that locks the +workstation is handled by the system on a lower level. For this +reason, @code{w32-register-hot-key} cannot override this key +combination - it always locks the computer.} + + Note that @code{w32-register-hot-key} checks the +@code{w32-[lr]window-modifier} values at the time of the function +call. Thus, you can set @code{w32-lwindow-modifier} as @code{super}, +then call @code{(w32-register-hot-key [s-r])}, and finally set +@code{w32-rwindow-modifier} as @code{super} as well. The result is +that the left Windows key together with @key{R} invokes whichever +function you have bound for the combination in Emacs, and the right +Windows key and @key{R} opens the Windows @code{Run} dialog. + + The hotkey registrations always also include all the shift and +control modifier combinations for the given hotkey; that is, +registering @kbd{s-@key{a}} as a hotkey gives you @kbd{S-s-@key{a}}, +@kbd{C-s-@key{a}} and @kbd{C-S-s-@key{a}} as well. + + On Windows 98 and ME, the hotkey registration is more restricted. +The desired hotkey must always be fully specified, and +@code{w32-phantom-key-code} can be customized to achieve desired +results. The function @code{w32-unregister-hot-key} reverses the effect of @code{w32-register-hot-key} for its argument key sequence. @@ -611,12 +643,7 @@ keys are passed to Windows or swallowed by Emacs. If the value is otherwise it is passed to Windows. The default is @code{t} for both of these variables. Passing each of these keys to Windows produces its normal effect: for example, @kbd{@key{Lwindow}} opens the -@code{Start} menu, etc.@footnote{ -Some combinations of the ``Windows'' keys with other keys are caught -by Windows at a low level in a way that Emacs currently cannot prevent. -For example, @kbd{@key{Lwindow} r} always pops up the Windows -@samp{Run} dialog. Customizing the value of -@code{w32-phantom-key-code} might help in some cases, though.} +@code{Start} menu, etc. @vindex w32-recognize-altgr @kindex AltGr @r{(MS-Windows)} diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi index f28488e4545..6c513c9a607 100644 --- a/doc/emacs/text.texi +++ b/doc/emacs/text.texi @@ -412,6 +412,7 @@ beginning of a line. @cindex mode, Electric Quote @cindex curly quotes @cindex curved quotes +@cindex guillemets @findex electric-quote-mode One common way to quote is the typewriter convention, which quotes using straight apostrophes @t{'like this'} or double-quotes @t{"like @@ -420,9 +421,15 @@ left and right single or double quotation marks @t{‘like this’} or @t{“like this”}. In text files, typewriter quotes are simple and portable; curved quotes are less ambiguous and typically look nicer. +@vindex electric-quote-chars Electric Quote mode makes it easier to type curved quotes. As you type characters it optionally converts @t{`} to @t{‘}, @t{'} to @t{’}, -@t{``} to @t{“}, and @t{''} to @t{”}. +@t{``} to @t{“}, and @t{''} to @t{”}. It's possible to change the +default quotes listed above, by customizing the variable +@code{electric-quote-chars}, a list of four characters, where the +items correspond to the left single quote, the right single quote, the +left double quote and the right double quote, respectively, whose +default value is @code{'(?‘ ?’ ?“ ?”)}. @vindex electric-quote-paragraph @vindex electric-quote-comment @@ -443,7 +450,10 @@ type @kbd{C-q `} or @kbd{C-q '} instead of @kbd{`} or @kbd{'}. To insert a curved quote even when Electric Quote is disabled or inactive, you can type @kbd{C-x 8 [} for @t{‘}, @kbd{C-x 8 ]} for @t{’}, @kbd{C-x 8 @{} for @t{“}, and @kbd{C-x 8 @}} for @t{”}. -@xref{Inserting Text}. +@xref{Inserting Text}. Note that the value of +@code{electric-quote-chars} does not affect these keybindings, they +are not keybindings of @code{electric-quote-mode} but bound in +@code{global-map}. @node Filling @section Filling Text diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi index 7a5defabf09..fbd13c8a58a 100644 --- a/doc/emacs/trouble.texi +++ b/doc/emacs/trouble.texi @@ -417,19 +417,22 @@ first @kbd{C-g} properly, then the second one will get you back to the shell. When you resume Emacs after a suspension caused by emergency escape, -it asks two questions before going back to what it had been doing: +it reports the resumption and asks a question or two before going back +to what it had been doing: @example +Emacs is resuming after an emergency escape. Auto-save? (y or n) Abort (and dump core)? (y or n) @end example @noindent -Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}. +Answer each question with @kbd{y} or @kbd{n} followed by @key{RET}. Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of all modified buffers in which auto-saving is enabled. Saying @kbd{n} -skips this. +skips this. This question is omitted if Emacs is in a state where +auto-saving cannot be done safely. Saying @kbd{y} to @samp{Abort (and dump core)?} causes Emacs to crash, dumping core. This is to enable a wizard to figure out why diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 86c8da0e461..0a6b775ead1 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -17584,11 +17584,10 @@ file that set values: @group ;; Set calendar highlighting colors -(add-hook 'calendar-load-hook - (lambda () - (set-face-foreground 'diary-face "skyblue") - (set-face-background 'holiday-face "slate blue") - (set-face-foreground 'holiday-face "white"))) +(with-eval-after-load 'calendar + (set-face-foreground 'diary "skyblue") + (set-face-background 'holiday "slate blue") + (set-face-foreground 'holiday "white")) @end group @end smallexample @@ -17647,7 +17646,7 @@ Set the shape and color of the mouse cursor: (setq mpointer "132")) ; top_left_arrow @end group @group - (setq x-pointer-shape (string-to-int mpointer)) + (setq x-pointer-shape (string-to-number mpointer)) (set-mouse-color "white")) @end group @end smallexample diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in index 7aadee7adea..5bf6e99d587 100644 --- a/doc/lispref/Makefile.in +++ b/doc/lispref/Makefile.in @@ -125,6 +125,7 @@ srcs = \ $(srcdir)/symbols.texi \ $(srcdir)/syntax.texi \ $(srcdir)/text.texi \ + $(srcdir)/threads.texi \ $(srcdir)/tips.texi \ $(srcdir)/variables.texi \ $(srcdir)/windows.texi \ diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi index b9e6466c871..35a18651488 100644 --- a/doc/lispref/backups.texi +++ b/doc/lispref/backups.texi @@ -41,6 +41,11 @@ You can alternatively request numbered backups; then each new backup file gets a new name. You can delete old numbered backups when you don't want them any more, or Emacs can delete them automatically. + For performance, the operating system may not write the backup +file's contents to secondary storage immediately, or may alias the +backup data with the original until one or the other is later +modified. @xref{Files and Storage}. + @menu * Making Backups:: How Emacs makes backup files, and when. * Rename or Copy:: Two alternatives: renaming the old file or copying it. diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index 740d7cfd8a1..e4ef4d5db6e 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -669,8 +669,9 @@ reason. This function is used to ask a user how to proceed after an attempt to modify an buffer visiting file @var{filename} when the file is newer than the buffer text. Emacs detects this because the modification -time of the file on disk is newer than the last save-time of the -buffer. This means some other program has probably altered the file. +time of the file on disk is newer than the last save-time and its contents +have changed. +This means some other program has probably altered the file. @kindex file-supersession Depending on the user's answer, the function may return normally, in diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 6e83659f635..c4de5299ce9 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -2618,6 +2618,31 @@ causes it to evaluate @code{help-form} and display the result. It then continues to wait for a valid input character, or keyboard-quit. @end defun +@defun read-multiple-choice prompt choices +Ask user a multiple choice question. @var{prompt} should be a string +that will be displayed as the prompt. + +@var{choices} is an alist where the first element in each entry is a +character to be entered, the second element is a short name for the +entry to be displayed while prompting (if there's room, it might be +shortened), and the third, optional entry is a longer explanation that +will be displayed in a help buffer if the user requests more help. + +The return value is the matching value from @var{choices}. + +@lisp +(read-multiple-choice + "Continue connecting?" + '((?a "always" "Accept this certificate this session and for all future sessions.") + (?s "session only" "Accept this certificate this session only.") + (?n "no" "Refuse to use this certificate, and close the connection."))) +@end lisp + +The @code{read-multiple-choice-face} face is used to highlight the +matching characters in the name string on graphical terminals. + +@end defun + @node Event Mod @subsection Modifying and Translating Input Events @cindex modifiers of events @@ -2892,6 +2917,12 @@ like this: @end example @end defmac +@defvar while-no-input-ignore-events +This variable allow setting which special events @code{while-no-input} +should ignore. It is a list of symbols. + +@end defvar + @defun discard-input @cindex flushing input @cindex discarding input diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 371934377a8..8fb663d2aee 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -69,6 +69,7 @@ debugger recursively. @xref{Recursive Editing}. * Error Debugging:: Entering the debugger when an error happens. * Infinite Loops:: Stopping and debugging a program that doesn't exit. * 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. * Debugger Commands:: Commands used while in the debugger. @@ -290,6 +291,36 @@ Calling @code{cancel-debug-on-entry} does nothing to a function which is not currently set up to break on entry. @end deffn +@node Variable Debugging +@subsection Entering the debugger when a variable is modified +@cindex variable write debugging +@cindex debugging changes to variables + +Sometimes a problem with a function is due to a wrong setting of a +variable. Setting up the debugger to trigger whenever the variable is +changed is a quick way to find the origin of the setting. + +@deffn Command debug-on-variable-change variable +This function arranges for the debugger to be called whenever +@var{variable} is modified. + +It is implemented using the watchpoint mechanism, so it inherits the +same characteristics and limitations: all aliases of @var{variable} +will be watched together, only dynamic variables can be watched, and +changes to the objects referenced by variables are not detected. For +details, see @ref{Watching Variables}. +@end deffn + +@deffn Command cancel-debug-on-variable-change &optional variable +This function undoes the effect of @code{debug-on-variable-change} on +@var{variable}. When called interactively, it prompts for +@var{variable} in the minibuffer. If @var{variable} is omitted or +@code{nil}, it cancels break-on-change for all variables. Calling +@code{cancel-debug-on-variable-change} does nothing to a variable +which is not currently set up to break on change. +@end deffn + + @node Explicit Debug @subsection Explicit Entry to the Debugger @cindex debugger, explicit entry @@ -630,6 +661,37 @@ forms are elided. @end smallexample @end deffn +@defvar debugger-stack-frame-as-list +If this variable is non-@code{nil}, every stack frame of the backtrace +is displayed as a list. This aims at improving the backtrace +readability at the cost of special forms no longer being visually +different from regular function calls. + +With @code{debugger-stack-frame-as-list} non-@code{nil}, the above +example would look as follows: + +@smallexample +@group +----------- Buffer: backtrace-output ------------ + (backtrace) + (list ...computing arguments...) +@end group + (progn ...) + (eval (progn (1+ var) (list (quote testing) (backtrace)))) + (setq ...) + (save-excursion ...) + (let ...) + (with-output-to-temp-buffer ...) + (eval (with-output-to-temp-buffer ...)) + (eval-last-sexp-1 nil) +@group + (eval-last-sexp nil) + (call-interactively eval-last-sexp) +----------- Buffer: backtrace-output ------------ +@end group +@end smallexample +@end defvar + @defvar debug-on-next-call @cindex @code{eval}, and debugging @cindex @code{apply}, and debugging @@ -665,7 +727,7 @@ invocation. This variable is obsolete and will be removed in future versions. @end defvar -@defun backtrace-frame frame-number +@defun backtrace-frame frame-number &optional base The function @code{backtrace-frame} is intended for use in Lisp debuggers. It returns information about what computation is happening in the stack frame @var{frame-number} levels down. @@ -682,10 +744,31 @@ In the return value, @var{function} is whatever was supplied as the case of a macro call. If the function has a @code{&rest} argument, that is represented as the tail of the list @var{arg-values}. +If @var{base} is specified, @var{frame-number} counts relative to +the topmost frame whose @var{function} is @var{base}. + If @var{frame-number} is out of range, @code{backtrace-frame} returns @code{nil}. @end defun +@defun mapbacktrace function &optional base +The function @code{mapbacktrace} calls @var{function} once for each +frame in the backtrace, starting at the first frame whose function is +@var{base} (or from the top if @var{base} is omitted or @code{nil}). + +@var{function} is called with four arguments: @var{evald}, @var{func}, +@var{args}, and @var{flags}. + +If a frame has not evaluated its arguments yet or is a special form, +@var{evald} is @code{nil} and @var{args} is a list of forms. + +If a frame has evaluated its arguments and called its function +already, @var{evald} is @code{t} and @var{args} is a list of values. +@var{flags} is a plist of properties of the current frame: currently, +the only supported property is @code{:debug-on-exit}, which is +@code{t} if the stack frame's @code{debug-on-exit} flag is set. +@end defun + @include edebug.texi @node Syntax Errors diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index fbdc574c658..945a701fcb2 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -2101,7 +2101,7 @@ is equivalent to a Lisp symbol with the same name.}. Named faces are defined using the @code{defface} macro (@pxref{Defining Faces}). Emacs comes with several standard named faces (@pxref{Basic Faces}). - Many parts of Emacs required named faces, and do not accept + Many parts of Emacs require named faces, and do not accept anonymous faces. These include the functions documented in @ref{Attribute Functions}, and the variable @code{font-lock-keywords} (@pxref{Search-based Fontification}). Unless otherwise stated, we @@ -4779,8 +4779,8 @@ displayed (@pxref{Display Feature Testing}). * Image Descriptors:: How to specify an image for use in @code{:display}. * XBM Images:: Special features for XBM format. * XPM Images:: Special features for XPM format. -* PostScript Images:: Special features for PostScript format. * ImageMagick Images:: Special features available through ImageMagick. +* SVG Images:: Creating and manipulating SVG images. * Other Image Types:: Various other formats are supported. * Defining Images:: Convenient ways to define an image for later use. * Showing Images:: Convenient ways to display an image once it is defined. @@ -4803,12 +4803,12 @@ to modify the set of known names for these dynamic libraries. Supported image formats (and the required support libraries) include PBM and XBM (which do not depend on support libraries and are always available), XPM (@code{libXpm}), GIF (@code{libgif} or -@code{libungif}), PostScript (@code{gs}), JPEG (@code{libjpeg}), TIFF +@code{libungif}), JPEG (@code{libjpeg}), TIFF (@code{libtiff}), PNG (@code{libpng}), and SVG (@code{librsvg}). Each of these image formats is associated with an @dfn{image type symbol}. The symbols for the above formats are, respectively, -@code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, @code{postscript}, +@code{pbm}, @code{xbm}, @code{xpm}, @code{gif}, @code{jpeg}, @code{tiff}, @code{png}, and @code{svg}. Furthermore, if you build Emacs with ImageMagick @@ -5121,39 +5121,12 @@ the name of a color as it appears in the image file, and @var{color} specifies the actual color to use for displaying that name. @end table -@node PostScript Images -@subsection PostScript Images -@cindex postscript images - - To use PostScript for an image, specify image type @code{postscript}. -This works only if you have Ghostscript installed. You must always use -these three properties: - -@table @code -@item :pt-width @var{width} -The value, @var{width}, specifies the width of the image measured in -points (1/72 inch). @var{width} must be an integer. - -@item :pt-height @var{height} -The value, @var{height}, specifies the height of the image in points -(1/72 inch). @var{height} must be an integer. - -@item :bounding-box @var{box} -The value, @var{box}, must be a list or vector of four integers, which -specifying the bounding box of the PostScript image, analogous to the -@samp{BoundingBox} comment found in PostScript files. - -@example -%%BoundingBox: 22 171 567 738 -@end example -@end table - @node ImageMagick Images @subsection ImageMagick Images @cindex ImageMagick images @cindex images, support for more formats - If you build Emacs with ImageMagick support, you can use the + If your Emacs build has ImageMagick support, you can use the ImageMagick library to load many image formats (@pxref{File Conveniences,,, emacs, The GNU Emacs Manual}). The image type symbol for images loaded via ImageMagick is @code{imagemagick}, regardless of @@ -5224,6 +5197,16 @@ and if @code{:height} is set it will have precedence over wish. @code{:max-width} and @code{:max-height} will always preserve the aspect ratio. +@item :scale @var{scale} +This should be a number, where values higher than 1 means to increase +the size, and lower means to decrease the size. For instance, a value +of 0.25 will make the image a quarter size of what it originally was. +If the scaling makes the image larger than specified by +@code{:max-width} or @code{:max-height}, the resulting size will not +exceed those two values. If both @code{:scale} and +@code{:height}/@code{:width} are specified, the height/width will be +adjusted by the specified scaling factor. + @item :format @var{type} The value, @var{type}, should be a symbol specifying the type of the image data, as found in @code{image-format-suffixes}. This is used @@ -5238,6 +5221,163 @@ Specifies a rotation angle in degrees. @xref{Multi-Frame Images}. @end table +@node SVG Images +@subsection SVG Images +@cindex SVG images + +SVG (Scalable Vector Graphics) is an XML format for specifying images. +If your Emacs build has with SVG support, you can create and manipulate +these images with the following commands. + +@defun svg-create width height &rest args +Create a new, empty SVG image with the specified dimensions. +@var{args} is an argument plist with you can specify following: + +@table @code +@item :stroke-width +The default width (in pixels) of any lines created. + +@item :stroke +The default stroke color on any lines created. +@end table + +This function returns an SVG structure, and all the following commands +work on that structure. +@end defun + +@defun svg-gradient svg id type stops +Create a gradient in @var{svg} with identifier @var{id}. @var{type} +specifies the gradient type, and can be either @code{linear} or +@code{radial}. @var{stops} is a list of percentage/color pairs. + +The following will create a linear gradient that goes from red at the +start, to green 25% of the way, to blue at the end: + +@lisp +(svg-gradient svg "gradient1" 'linear + '((0 . "red") (25 . "green") (100 . "blue"))) +@end lisp + +The gradient created (and inserted into the SVG object) can later be +used by all functions that create shapes. +@end defun + +All the following functions take an optional list of keyword +parameters that alter the various attributes from their default +values. Valid attributes include: + +@table @code +@item :stroke-width +The width (in pixels) of lines drawn, and outlines around solid +shapes. + +@item :stroke-color +The color of lines drawn, and outlines around solid shapes. + +@item :fill-color +The color used for solid shapes. + +@item :id +The identified of the shape. + +@item :gradient +If given, this should be the identifier of a previously defined +gradient object. +@end table + +@defun svg-rectangle svg x y width height &rest args +Add a rectangle to @var{svg} where the upper left corner is at +position @var{x}/@var{y} and is of size @var{width}/@var{height}. + +@lisp +(svg-rectangle svg 100 100 500 500 :gradient "gradient1") +@end lisp +@end defun + +@defun svg-circle svg x y radius &rest args +Add a circle to @var{svg} where the center is at @var{x}/@var{y} +and the radius is @var{radius}. +@end defun + +@defun svg-ellipse svg x y x-radius y-radius &rest args +Add a circle to @var{svg} where the center is at @var{x}/@var{y} and +the horizontal radius is @var{x-radius} and the vertical radius is +@var{y-radius}. +@end defun + +@defun svg-line svg x1 y1 x2 y2 &rest args +Add a line to @var{svg} that starts at @var{x1}/@var{y1} and extends +to @var{x2}/@var{y2}. +@end defun + +@defun svg-polyline svg points &rest args +Add a multiple segment line to @var{svg} that goes through +@var{points}, which is a list of X/Y position pairs. + +@lisp +(svg-polyline svg '((200 . 100) (500 . 450) (80 . 100)) + :stroke-color "green") +@end lisp +@end defun + +@defun svg-polygon svg points &rest args +Add a polygon to @var{svg} where @var{points} is a list of X/Y pairs +that describe the outer circumference of the polygon. + +@lisp +(svg-polygon svg '((100 . 100) (200 . 150) (150 . 90)) + :stroke-color "blue" :fill-color "red"") +@end lisp +@end defun + +@defun svg-text svg text &rest args +Add a text to @var{svg}. + +@lisp +(svg-text + svg "This is a text" + :font-size "40" + :font-weight "bold" + :stroke "black" + :fill "white" + :font-family "impact" + :letter-spacing "4pt" + :x 300 + :y 400 + :stroke-width 1) +@end lisp +@end defun + +@defun svg-embed svg image image-type datap &rest args +Add an embedded (raster) image to @var{svg}. If @var{datap} is +@code{nil}, @var{IMAGE} should be a file name; if not, it should be a +binary string containing the image data. @var{image-type} should be a +@acronym{MIME} image type, for instance @samp{"image/jpeg"}. + +@lisp +(svg-embed svg "~/rms.jpg" "image/jpeg" nil + :width "100px" :height "100px" + :x "50px" :y "75px") +@end lisp +@end defun + +@defun svg-remove svg id +Remove the element with identifier @code{id} from the @code{svg}. +@end defun + +Finally, the @code{svg-image} takes an SVG object as its parameter and +returns an image object suitable for use in functions like +@code{insert-image}. Here's a complete example that creates and +inserts an image with a circle: + +@lisp +(let ((svg (svg-create 400 400 :stroke-width 10))) + (svg-gradient svg "gradient1" 'linear '((0 . "red") (100 . "blue"))) + (svg-circle svg 200 200 100 :gradient "gradient1" :stroke-color "green") + (insert-image (svg-image svg))) +@end lisp + + @node Other Image Types @subsection Other Image Types @cindex PBM @@ -5274,9 +5414,6 @@ Image type @code{jpeg}. @item PNG Image type @code{png}. -@item SVG -Image type @code{svg}. - @item TIFF Image type @code{tiff}. Supports the @code{:index} property. @xref{Multi-Frame Images}. @@ -5340,6 +5477,12 @@ If none of the alternatives will work, then @var{symbol} is defined as @code{nil}. @end defmac +@defun image-property image property +Return the value of @var{property} in @var{image}. Properties can be +set by using @code{setf}. Setting a property to @code{nil} will +remove the property from the image. +@end defun + @defun find-image specs This function provides a convenient way to find an image satisfying one of a list of image specifications @var{specs}. @@ -5410,6 +5553,13 @@ Here is an example of using @code{image-load-path-for-library}: @end example @end defun +@vindex image-scaling-factor +Images are automatically scaled when created based on the +@code{image-scaling-factor} variable. The value is either a floating +point number (where numbers higher than 1 means to increase the size +and lower means to shrink the size), or the symbol @code{auto}, which +will compute a scaling factor based on the font pixel size. + @node Showing Images @subsection Showing Images @cindex show image @@ -5519,6 +5669,26 @@ cache, it can always be displayed, even if the value of @code{max-image-size} is subsequently changed (@pxref{Image Cache}). @end defvar +Images inserted with the insertion functions above also get a local +keymap installed in the text properties (or overlays) that span the +displayed image. This keymap defines the following commands: + +@table @kbd +@item + +Increase the image size (@code{image-increase-size}). A prefix value +of @samp{4} means to increase the size by 40%. The default is 20%. + +@item - +Decrease the image size (@code{image-increase-size}). A prefix value +of @samp{4} means to decrease the size by 40%. The default is 20%. + +@item r +Rotate the image by 90 degrees (@code{image-rotate}). + +@item o +Save the image to a file (@code{image-save}). +@end table + @node Multi-Frame Images @subsection Multi-Frame Images @cindex multi-frame images @@ -6969,7 +7139,7 @@ Emacs is displaying the frame on a character-based terminal. @defvar initial-window-system This variable holds the value of @code{window-system} used for the first frame created by Emacs during startup. (When Emacs is invoked -with the @option{--daemon} option, it does not create any initial +as a daemon, it does not create any initial frames, so @code{initial-window-system} is @code{nil}, except on MS-Windows, where it is still @code{w32}. @xref{Initial Options, daemon,, emacs, The GNU Emacs Manual}.) diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index 47fe02a4a57..65ccb646909 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -384,6 +384,11 @@ now, it returns from the function and then stops. In other words, this command does not exit the currently executing function unless you are positioned after the last sexp. +Normally, the @kbd{h}, @kbd{f}, and @kbd{o} commands display ``Break'' +and pause for @code{edebug-sit-for-seconds} before showing the result +of the form just evaluated. You can avoid this pause by setting +@code{edebug-sit-on-break} to @code{nil}. @xref{Edebug Options}. + The @kbd{i} command steps into the function or macro called by the list form after point, and stops at its first stop point. Note that the form need not be the one about to be evaluated. But if the form is a @@ -1543,6 +1548,14 @@ Use the command @kbd{M-x edebug-all-forms} to toggle the value of this option. @xref{Instrumenting}. @end defopt +@defopt edebug-eval-macro-args +When this is non-@code{nil}, all macro arguments will be instrumented +in the generated code. For any macro, an @code{edebug-form-spec} +overrides this option. So to specify exceptions for macros that have +some arguments evaluated and some not, use @code{def-edebug-spec} to +specify an @code{edebug-form-spec}. +@end defopt + @defopt edebug-save-windows If this is non-@code{nil}, Edebug saves and restores the window configuration. That takes some time, so if your program does not care @@ -1601,6 +1614,21 @@ debugged. @xref{Edebug Execution Modes}. @end defopt +@defopt edebug-print-length +If non-@code{nil}, the default value of @code{print-length} for +printing results in Edebug. @xref{Output Variables}. +@end defopt + +@defopt edebug-print-level +If non-@code{nil}, the default value of @code{print-level} for +printing results in Edebug. @xref{Output Variables}. +@end defopt + +@defopt edebug-print-circle +If non-@code{nil}, the default value of @code{print-circle} for +printing results in Edebug. @xref{Output Variables}. +@end defopt + @defopt edebug-unwrap-results If non-@code{nil}, Edebug tries to remove any of its own instrumentation when showing the results of expressions. This is @@ -1647,3 +1675,14 @@ If non-@code{nil}, an expression to test for at every stop point. If the result is non-@code{nil}, then break. Errors are ignored. @xref{Global Break Condition}. @end defopt + +@defopt edebug-sit-for-seconds +Number of seconds to pause when a breakpoint is reached and the execution +mode is trace or continue. @xref{Edebug Execution Modes}. +@end defopt + +@defopt edebug-sit-on-break +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 diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 3297e5308ae..494e8fcb6c3 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -219,6 +219,7 @@ To view this manual in other formats, click * Syntax Tables:: The syntax table controls word and list parsing. * Abbrevs:: How Abbrev mode works, and its data structures. +* Threads:: Concurrency in Emacs Lisp. * Processes:: Running and communicating with subprocesses. * Display:: Features for controlling the screen display. * System Interface:: Getting the user id, system type, environment @@ -348,6 +349,9 @@ Editing Types * Window Configuration Type:: Recording the way a frame is subdivided. * Frame Configuration Type:: Recording the status of all frames. * Process Type:: A subprocess of Emacs running on the underlying OS. +* Thread Type:: A thread of Emacs Lisp execution. +* Mutex Type:: An exclusive lock for thread synchronization. +* Condition Variable Type:: Condition variable for thread synchronization. * Stream Type:: Receive or send characters. * Keymap Type:: What function a keystroke invokes. * Overlay Type:: How an overlay is represented. @@ -498,11 +502,13 @@ Variables * Accessing Variables:: Examining values of variables whose names are known only at run time. * Setting Variables:: Storing new values in variables. +* Watching Variables:: Running a function when a variable is changed. * Variable Scoping:: How Lisp chooses among local and global values. * Buffer-Local Variables:: Variable values in effect only in one buffer. * File Local Variables:: Handling local variable lists in files. * Directory Local Variables:: Local variables common to all files in a directory. +* Connection Local Variables:: Local variables common for remote connections. * Variable Aliases:: Variables that are aliases for other variables. * Variables with Restricted Values:: Non-constant variables whose value can @emph{not} be an arbitrary Lisp object. @@ -641,6 +647,7 @@ The Lisp Debugger * Error Debugging:: Entering the debugger when an error happens. * Infinite Loops:: Stopping and debugging a program that doesn't exit. * 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. * Debugger Commands:: Commands used while in the debugger. @@ -1038,6 +1045,8 @@ Windows a specific window. * Quitting Windows:: How to restore the state prior to displaying a buffer. +* Side Windows:: Special windows on a frame's sides. +* Atomic Windows:: Preserving parts of the window layout. * Window Point:: Each window has its own location of point. * Window Start and End:: Buffer positions indicating which text is on-screen in a window. @@ -1051,6 +1060,14 @@ Windows redisplay going past a certain point, or window configuration changes. +Side Windows + +* Displaying Buffers in Side Windows:: An action function for displaying + buffers in side windows. +* Side Window Options and Functions:: Further tuning of side windows. +* Frame Layouts with Side Windows:: Setting up frame layouts with side + windows. + Frames * Creating Frames:: Creating additional frames. @@ -1309,6 +1326,12 @@ Abbrevs and Abbrev Expansion * Abbrev Table Properties:: How to read and set abbrev table properties. Which properties have which effect. +Threads + +* Basic Thread Functions:: Basic thread functions. +* Mutexes:: Mutexes allow exclusive access to data. +* Condition Variables:: Inter-thread events. + Processes * Subprocess Creation:: Functions that start subprocesses. @@ -1449,7 +1472,6 @@ Images * Image Descriptors:: How to specify an image for use in @code{:display}. * XBM Images:: Special features for XBM format. * XPM Images:: Special features for XPM format. -* PostScript Images:: Special features for PostScript format. * ImageMagick Images:: Special features available through ImageMagick. * Other Image Types:: Various other formats are supported. * Defining Images:: Convenient ways to define an image for later use. @@ -1615,6 +1637,7 @@ Object Internals @include searching.texi @include syntax.texi @include abbrevs.texi +@include threads.texi @include processes.texi @include display.texi diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index 03aea4ef445..4a0e38c782f 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -107,6 +107,11 @@ the error-strings are not very relevant. However, these error symbols do have @code{error-message} properties, and if no data is provided, the @code{error-message} property @emph{is} used. @xref{Files}. +@item file-missing +This is a subcategory of @code{file-error}. It occurs when an +operation attempts to act on a file that is missing. @xref{Changing +Files}. + @c jka-compr.el @item compression-error This is a subcategory of @code{file-error}, which results from diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 85c80d76f73..906cd562612 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -41,6 +41,7 @@ to locale @code{system-messages-locale}, and decoded using coding system simultaneous editing by two people. * Information about Files:: Testing existence, accessibility, size of files. * Changing Files:: Renaming files, changing permissions, etc. +* Files and Storage:: Surviving power and media failures * File Names:: Decomposing and expanding file names. * Contents of Directories:: Getting a list of the files in a directory. * Create/Delete Dirs:: Creating and Deleting Directories. @@ -660,6 +661,15 @@ feature is useful for programs that use files for internal purposes, files that the user does not need to know about. @end deffn +@defvar write-region-inhibit-fsync +If this variable's value is @code{nil}, @code{write-region} uses the +@code{fsync} system call after writing a file. Although this slows +Emacs down, it lessens the risk of data loss after power failure. If +the value is @code{t}, Emacs does not use @code{fsync}. The default +value is @code{nil} when Emacs is interactive, and @code{t} when Emacs +runs in batch mode. @xref{Files and Storage}. +@end defvar + @defmac with-temp-file file body@dots{} @anchor{Definition of with-temp-file} The @code{with-temp-file} macro evaluates the @var{body} forms with a @@ -1130,6 +1140,25 @@ appropriate manner. If @var{file1} or @var{file2} does not exist, the return value is unspecified. @end defun +@defun file-name-case-insensitive-p filename +Sometimes file names or their parts need to be compared as strings, in +which case it's important to know whether the underlying filesystem is +case-insensitive. This function returns @code{t} if file +@var{filename} is on a case-insensitive filesystem. It always returns +@code{t} on MS-DOS and MS-Windows. On Cygwin and Mac OS X, +filesystems may or may not be case-insensitive, and the function tries +to determine case-sensitivity by a runtime test. If the test is +inconclusive, the function returns @code{t} on Cygwin and @code{nil} +on Mac OS X. + +Currently this function always returns @code{nil} on platforms other +than MS-DOS, MS-Windows, Cygwin, and Mac OS X. It does not detect +case-insensitivity of mounted filesystems, such as Samba shares or +NFS-mounted Windows volumes. On remote hosts, it assumes @code{t} for +the @samp{smb} method. For all other connection methods, runtime +tests are performed. +@end defun + @defun file-in-directory-p file dir This function returns @code{t} if @var{file} is a file in directory @var{dir}, or in a subdirectory of @var{dir}. It also returns @@ -1210,73 +1239,83 @@ the default, but we plan to change that, so you should specify a non-@code{nil} value for @var{id-format} if you use the returned @acronym{UID} or @acronym{GID}. +Accessor functions are provided to access the elements in this list. +The accessors are mentioned along with the descriptions of the +elements below. + The elements of the list, in order, are: @enumerate 0 @item @code{t} for a directory, a string for a symbolic link (the name -linked to), or @code{nil} for a text file. +linked to), or @code{nil} for a text file +(@code{file-attribute-type}). @c Wordy so as to prevent an overfull hbox. --rjc 15mar92 @item -The number of names the file has. Alternate names, also known as hard -links, can be created by using the @code{add-name-to-file} function -(@pxref{Changing Files}). +The number of names the file has (@code{file-attribute-link-number}). +Alternate names, also known as hard links, can be created by using the +@code{add-name-to-file} function (@pxref{Changing Files}). @item -The file's @acronym{UID}, normally as a string. However, if it does -not correspond to a named user, the value is a number. +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. @item -The file's @acronym{GID}, likewise. +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})}. (This is similar to the -value of @code{current-time}; see @ref{Time of Day}.) Note that 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 last access. +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}.) Note that 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 last access. @cindex modification time of file @item -The time of last modification as a list of four integers (as above). -This is the last time when the file's contents were modified. +The time of last modification as a list of four integers (as above) +(@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). -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. +The time of last status change as a list of four integers (as above) +(@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. 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}). This is +floating point if the size is too large to fit in a Lisp integer. @item -The file's modes, as a string of ten letters or dashes, -as in @samp{ls -l}. +The file's modes, as a string of ten letters or dashes, as in +@samp{ls -l} (@code{file-attribute-modes}). @item An unspecified value, present for backward compatibility. @item -The file's 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 +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. +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. @item -The filesystem number of the device that the file is on. 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 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. +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 +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. @end enumerate For example, here are the file attributes for @file{files.texi}: @@ -1496,10 +1535,15 @@ in @code{exec-path}, and tries all the file-name extensions in @cindex setting modes of files The functions in this section rename, copy, delete, link, and set -the modes (permissions) of files. They all signal a @code{file-error} -error if they fail to perform their function, reporting the -system-dependent error message that describes the reason for the -failure. +the modes (permissions) of files. Typically, they signal a +@code{file-error} error if they fail to perform their function, +reporting the system-dependent error message that describes the reason +for the failure. If they fail because a file is missing, they signal +a @code{file-missing} error instead. + + For performance, the operating system may cache or alias changes +made by these functions instead of writing them immediately to +secondary storage. @xref{Files and Storage}. In the functions that have an argument @var{newname}, if a file by the name of @var{newname} already exists, the actions taken depend on the @@ -1799,6 +1843,28 @@ The function returns @code{t} if it successfully sets the ACL of @var{filename}, @code{nil} otherwise. @end defun +@node Files and Storage +@section Files and Secondary Storage +@cindex secondary storage + +After Emacs changes a file, there are two reasons the changes might +not survive later failures of power or media, both having to do with +efficiency. First, the operating system might alias written data with +data already stored elsewhere on secondary storage until one file or +the other is later modified; this will lose both files if the only +copy on secondary storage is lost due to media failure. Second, the +operating system might not write data to secondary storage +immediately, which will lose the data if power is lost. + +@findex write-region +Although both sorts of failures can largely be avoided by a suitably +configured file system, such systems are typically more expensive or +less efficient. In more-typical systems, to survive media failure you +can copy the file to a different device, and to survive a power +failure you can use the @code{write-region} function with the +@code{write-region-inhibit-fsync} variable set to @code{nil}. +@xref{Writing to Files}. + @node File Names @section File Names @cindex file names @@ -2336,6 +2402,47 @@ through the immediately preceding @samp{/}). @end defun + Sometimes, it is not desired to expand file names. In such cases, +the file name can be quoted to suppress the expansion, and to handle +the file name literally. Quoting happens by prefixing the file name +with @samp{/:}. + +@defmac file-name-quote name +This macro adds the quotation prefix @samp{/:} to the file @var{name}. +For a local file @var{name}, it prefixes @var{name} with @samp{/:}. +If @var{name} is a remote file name, the local part of @var{name} is +quoted. If @var{name} is already a quoted file name, @var{name} is +returned unchanged. + +@example +@group +(substitute-in-file-name (file-name-quote "bar/~/foo")) + @result{} "/:bar/~/foo" +@end group + +@group +(substitute-in-file-name (file-name-quote "/ssh:host:bar/~/foo")) + @result{} "/ssh:host:/:bar/~/foo" +@end group +@end example + +The macro cannot be used to suppress file name handlers from magic +file names (@pxref{Magic File Names}). +@end defmac + +@defmac file-name-unquote name +This macro removes the quotation prefix @samp{/:} from the file +@var{name}, if any. If @var{name} is a remote file name, the local +part of @var{name} is unquoted. +@end defmac + +@defmac file-name-quoted-p name +This macro returns non-@code{nil}, when @var{name} is quoted with the +prefix @samp{/:}. If @var{name} is a remote file name, the local part +of @var{name} is checked. +@end defmac + + @node Unique File Names @subsection Generating Unique File Names @cindex unique file names @@ -2446,6 +2553,43 @@ condition, between the @code{make-temp-name} call and the creation of the file, which in some cases may cause a security hole. @end defun +Sometimes, it is necessary to create a temporary file on a remote host +or a mounted directory. The following two functions support this. + +@defun make-nearby-temp-file prefix &optional dir-flag suffix +This function is similar to @code{make-temp-file}, but it creates a +temporary file as close as possible to @code{default-directory}. If +@var{prefix} is a relative file name, and @code{default-directory} is +a remote file name or located on a mounted file systems, the temporary +file is created in the directory returned by the function +@code{temporary-file-directory}. Otherwise, the function +@code{make-temp-file} is used. @var{prefix}, @var{dir-flag} and +@var{suffix} have the same meaning as in @code{make-temp-file}. + +@example +@group +(let ((default-directory "/ssh:remotehost:")) + (make-nearby-temp-file "foo")) + @result{} "/ssh:remotehost:/tmp/foo232J6v" +@end group +@end example +@end defun + +@defun temporary-file-directory +The directory for writing temporary files via +@code{make-nearby-temp-file}. In case of a remote +@code{default-directory}, this is a directory for temporary files on +that remote host. If such a directory does not exist, or +@code{default-directory} ought to be located on a mounted file system +(see @code{mounted-file-systems}), the function returns +@code{default-directory}. For a non-remote and non-mounted +@code{default-directory}, the value of the variable +@code{temporary-file-directory} is returned. +@end defun + +In order to extract the local part of the path name from a temporary +file, @code{file-local-name} could be used. + @node File Name Completion @subsection File Name Completion @cindex file name completion subroutines @@ -2781,6 +2925,9 @@ This command deletes the directory named @var{dirname}. The function must use @code{delete-directory} for them. If @var{recursive} is @code{nil}, and the directory contains any files, @code{delete-directory} signals an error. +If recursive is non-@code{nil}, there is no error merely because the +directory or its files are deleted by some other process before +@code{delete-directory} gets to them. @code{delete-directory} only follows symbolic links at the level of parent directories. @@ -2890,6 +3037,7 @@ first, before handlers for jobs such as remote file access. @code{file-local-copy}, @code{file-modes}, @code{file-name-all-completions}, @code{file-name-as-directory}, +@code{file-name-case-insensitive-p}, @code{file-name-completion}, @code{file-name-directory}, @code{file-name-nondirectory}, @@ -2900,8 +3048,7 @@ first, before handlers for jobs such as remote file access. @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{find-backup-file-name}, -@c Not sure why it was here: @code{find-file-noselect},@* +@code{find-backup-file-name},@* @code{get-file-buffer}, @code{insert-directory}, @code{insert-file-contents},@* @@ -2909,6 +3056,7 @@ first, before handlers for jobs such as remote file access. @code{make-auto-save-file-name}, @code{make-directory}, @code{make-directory-internal}, +@code{make-nearby-temp-file}, @code{make-symbolic-link},@* @code{process-file}, @code{rename-file}, @code{set-file-acl}, @code{set-file-modes}, @@ -2916,6 +3064,7 @@ first, before handlers for jobs such as remote file access. @code{set-visited-file-modtime}, @code{shell-command}, @code{start-file-process}, @code{substitute-in-file-name},@* +@code{temporary-file-directory}, @code{unhandled-file-name-directory}, @code{vc-registered}, @code{verify-visited-file-modtime},@* @@ -2944,6 +3093,7 @@ first, before handlers for jobs such as remote file access. @code{file-local-copy}, @code{file-modes}, @code{file-name-all-completions}, @code{file-name-as-directory}, +@code{file-name-case-insensitive-p}, @code{file-name-completion}, @code{file-name-directory}, @code{file-name-nondirec@discretionary{}{}{}tory}, @@ -2955,7 +3105,6 @@ first, before handlers for jobs such as remote file access. @code{file-remote-p}, @code{file-selinux-context}, @code{file-symlink-p}, @code{file-truename}, @code{file-writable-p}, @code{find-backup-file-name}, -@c Not sure why it was here: @code{find-file-noselect}, @code{get-file-buffer}, @code{insert-directory}, @code{insert-file-contents}, @@ -3119,6 +3268,13 @@ non-magic directory to serve as its current directory, and this function is a good way to come up with one. @end defun +@defun file-local-name filename +This function returns the local part of file @var{filename}. For a +remote @var{filename}, it returns a file name which could be used +directly as argument of a remote process. If @var{filename} is local, +this function returns the file name. +@end defun + @defopt remote-file-name-inhibit-cache The attributes of remote files can be cached for better performance. If they are changed outside of Emacs's control, the cached values become @@ -3244,7 +3400,9 @@ end position. One responsibility of @var{from-fn} is to make sure that the beginning of the file no longer matches @var{regexp}. Otherwise it is likely to -get called again. +get called again. Also, @var{from-fn} must not involve buffers or +files other than the one being decoded, otherwise the internal buffer +used for formatting might be overwritten. @item to-fn A shell command or function to encode data in this format---that is, to @@ -3275,6 +3433,10 @@ file, it intermixes the specified annotations at the corresponding positions. All this takes place without modifying the buffer. @end itemize +@var{to-fn} must not involve buffers or files other than the one being +encoded, otherwise the internal buffer used for formatting might be +overwritten. + @item modify A flag, @code{t} if the encoding function modifies the buffer, and @code{nil} if it works by returning a list of annotations. diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index ec344c726ce..dc1c524653d 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -1539,6 +1539,13 @@ prevent hanging with those window managers. If non-@code{nil}, the frame is visible on all virtual desktops on systems with virtual desktops. +@vindex inhibit-double-buffering, a frame parameter +@item inhibit-double-buffering +If non-@code{nil}, the frame is drawn to the screen without double buffering. +Emacs normally attempts to use double buffering, where available, to +reduce flicker. Set this property if you experience display bugs or +pine for that retro, flicker-y feeling. + @ignore @vindex parent-id, a frame parameter @item parent-id @@ -1904,10 +1911,11 @@ to it. @deffn Command delete-frame &optional frame force @vindex delete-frame-functions -This function deletes the frame @var{frame}. Unless @var{frame} is a -tooltip, it first runs the hook @code{delete-frame-functions} (each -function gets one argument, @var{frame}). By default, @var{frame} is -the selected frame. +This function deletes the frame @var{frame}. The argument @var{frame} +must specify a live frame (see below) and defaults to the selected +frame. Unless @var{frame} specifies a tooltip, this function first runs +the hook @code{delete-frame-functions} (each function getting one +argument, @var{frame}). A frame cannot be deleted as long as its minibuffer serves as surrogate minibuffer for another frame (@pxref{Minibuffers and Frames}). @@ -1916,9 +1924,9 @@ but if @var{force} is non-@code{nil}, then you are allowed to do so. @end deffn @defun frame-live-p frame -The function @code{frame-live-p} returns non-@code{nil} if the frame -@var{frame} has not been deleted. The possible non-@code{nil} return -values are like those of @code{framep}. @xref{Frames}. +This function returns non-@code{nil} if the frame @var{frame} has not +been deleted. The possible non-@code{nil} return values are like those +of @code{framep}. @xref{Frames}. @end defun Some window managers provide a command to delete a window. These work @@ -1927,6 +1935,15 @@ When Emacs gets one of these commands, it generates a @code{delete-frame} event, whose normal definition is a command that calls the function @code{delete-frame}. @xref{Misc Events}. +@deffn Command delete-other-frames &optional frame +This command deletes all frames on @var{frame}'s terminal, except +@var{frame}. If @var{frame} uses another frame's minibuffer, that +minibuffer frame is left untouched. The argument @var{frame} must +specify a live frame and defaults to the selected frame. Internally, +this command works by calling @code{delete-frame} with @var{force} +@code{nil} for all frames that shall be deleted. +@end deffn + @node Finding All Frames @section Finding All Frames @cindex frames, scanning all @@ -1946,11 +1963,11 @@ visible, even though only the selected one is actually displayed. @end defun @defun next-frame &optional frame minibuf -This function lets you cycle conveniently through all the frames on -the current display from an arbitrary starting point. It returns the -next frame after @var{frame} in the cycle. If @var{frame} is -omitted or @code{nil}, it defaults to the selected frame (@pxref{Input -Focus}). +This function lets you cycle conveniently through all the frames on a +specific terminal from an arbitrary starting point. It returns the +frame following @var{frame}, in the list of all live frames, on +@var{frame}'s terminal. The argument @var{frame} must specify a live +frame and defaults to the selected frame. The second argument, @var{minibuf}, says which frames to consider: @@ -2200,6 +2217,12 @@ window manager. This happens below the level at which Emacs can exert any control, but Emacs does provide events that you can use to keep track of such changes. @xref{Misc Events}. +@defun x-double-buffered-p &optional frame +This function returns non-@code{nil} if @var{frame} is currently +being rendered with double buffering. @var{frame} defaults to the +selected frame. +@end defun + @node Raising and Lowering @section Raising and Lowering Frames diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index bc04beeebca..8dff1a70f75 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -143,6 +143,37 @@ function, i.e., can be passed to @code{funcall}. Note that and returns @code{nil} for special forms. @end defun + It is also possible to find out how many arguments an arbitrary +function expects: + +@defun func-arity function +This function provides information about the argument list of the +specified @var{function}. The returned value is a cons cell of the +form @w{@code{(@var{min} . @var{max})}}, where @var{min} is the +minimum number of arguments, and @var{max} is either the maximum +number of arguments, or the symbol @code{many} for functions with +@code{&rest} arguments, or the symbol @code{unevalled} if +@var{function} is a special form. + +Note that this function might return inaccurate results in some +situations, such as the following: + +@itemize @minus +@item +Functions defined using @code{apply-partially} (@pxref{Calling +Functions, apply-partially}). + +@item +Functions that are advised using @code{advice-add} (@pxref{Advising +Named Functions}). + +@item +Functions that determine the argument list dynamically, as part of +their code. +@end itemize + +@end defun + @noindent Unlike @code{functionp}, the next three functions do @emph{not} treat a symbol as its function definition. @@ -176,12 +207,9 @@ function. For example: @end defun @defun subr-arity subr -This function provides information about the argument list of a -primitive, @var{subr}. The returned value is a pair -@code{(@var{min} . @var{max})}. @var{min} is the minimum number of -args. @var{max} is the maximum number or the symbol @code{many}, for a -function with @code{&rest} arguments, or the symbol @code{unevalled} if -@var{subr} is a special form. +This works like @code{func-arity}, but only for built-in functions and +without symbol indirection. It signals an error for non-built-in +functions. We recommend to use @code{func-arity} instead. @end defun @node Lambda Expressions @@ -2145,44 +2173,48 @@ Byte-compiling a file often produces warnings about functions that the compiler doesn't know about (@pxref{Compiler Errors}). Sometimes this indicates a real problem, but usually the functions in question are defined in other files which would be loaded if that code is run. For -example, byte-compiling @file{fortran.el} used to warn: +example, byte-compiling @file{simple.el} used to warn: @example -In end of data: -fortran.el:2152:1:Warning: the function ‘gud-find-c-expr’ is not - known to be defined. +simple.el:8727:1:Warning: the function ‘shell-mode’ is not known to be + defined. @end example -In fact, @code{gud-find-c-expr} is only used in the function that -Fortran mode uses for the local value of -@code{gud-find-expr-function}, which is a callback from GUD; if it is -called, the GUD functions will be loaded. When you know that such a -warning does not indicate a real problem, it is good to suppress the -warning. That makes new warnings which might mean real problems more -visible. You do that with @code{declare-function}. +In fact, @code{shell-mode} is used only in a function that executes +@code{(require 'shell)} before calling @code{shell-mode}, so +@code{shell-mode} will be defined properly at run-time. When you know +that such a warning does not indicate a real problem, it is good to +suppress the warning. That makes new warnings which might mean real +problems more visible. You do that with @code{declare-function}. All you need to do is add a @code{declare-function} statement before the first use of the function in question: @example -(declare-function gud-find-c-expr "gud.el" nil) +(declare-function shell-mode "shell" ()) @end example -This says that @code{gud-find-c-expr} is defined in @file{gud.el} (the +This says that @code{shell-mode} is defined in @file{shell.el} (the @samp{.el} can be omitted). The compiler takes for granted that that file really defines the function, and does not check. The optional third argument specifies the argument list of -@code{gud-find-c-expr}. In this case, it takes no arguments +@code{shell-mode}. In this case, it takes no arguments (@code{nil} is different from not specifying a value). In other cases, this might be something like @code{(file &optional overwrite)}. You don't have to specify the argument list, but if you do the byte compiler can check that the calls match the declaration. @defmac declare-function function file &optional arglist fileonly -Tell the byte compiler to assume that @var{function} is defined, with -arguments @var{arglist}, and that the definition should come from the -file @var{file}. @var{fileonly} non-@code{nil} means only check that +Tell the byte compiler to assume that @var{function} is defined in the +file @var{file}. The optional third argument @var{arglist} is either +@code{t}, meaning the argument list is unspecified, or a list of +formal parameters in the same style as @code{defun}. An omitted +@var{arglist} defaults to @code{t}, not @code{nil}; this is atypical +behavior for omitted arguments, and it means that to supply a fourth +but not third argument one must specify @code{t} for the third-argument +placeholder instead of the usual @code{nil}. The optional fourth +argument @var{fileonly} non-@code{nil} means check only that @var{file} exists, not that it actually defines @var{function}. @end defmac diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi index 8389c214707..4607bb0a0d1 100644 --- a/doc/lispref/hash.texi +++ b/doc/lispref/hash.texi @@ -268,18 +268,43 @@ under the property @code{hash-table-test}; the property value's form is @code{(@var{test-fn} @var{hash-fn})}. @end defun -@defun sxhash obj +@defun sxhash-equal obj This function returns a hash code for Lisp object @var{obj}. This is an integer which reflects the contents of @var{obj} and the other Lisp objects it points to. -If two objects @var{obj1} and @var{obj2} are equal, then @code{(sxhash -@var{obj1})} and @code{(sxhash @var{obj2})} are the same integer. +If two objects @var{obj1} and @var{obj2} are @code{equal}, then +@code{(sxhash-equal @var{obj1})} and @code{(sxhash-equal @var{obj2})} +are the same integer. -If the two objects are not equal, the values returned by @code{sxhash} -are usually different, but not always; once in a rare while, by luck, -you will encounter two distinct-looking objects that give the same -result from @code{sxhash}. +If the two objects are not @code{equal}, the values returned by +@code{sxhash-equal} are usually different, but not always; once in a +rare while, by luck, you will encounter two distinct-looking objects +that give the same result from @code{sxhash-equal}. + +@b{Common Lisp note:} In Common Lisp a similar function is called +@code{sxhash}. Emacs provides this name as a compatibility alias for +@code{sxhash-equal}. +@end defun + +@defun sxhash-eq obj +This function returns a hash code for Lisp object @var{obj}. Its +result reflects identity of @var{obj}, but not its contents. + +If two objects @var{obj1} and @var{obj2} are @code{eq}, then +@code{(xhash @var{obj1})} and @code{(xhash @var{obj2})} are the same +integer. +@end defun + +@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. + +If two objects @var{obj1} and @var{obj2} are @code{eql}, then +@code{(xhash @var{obj1})} and @code{(xhash @var{obj2})} are the same +integer. @end defun This example creates a hash table whose keys are strings that are @@ -289,7 +314,7 @@ compared case-insensitively. (defun case-fold-string= (a b) (eq t (compare-strings a nil nil b nil nil t))) (defun case-fold-string-hash (a) - (sxhash (upcase a))) + (sxhash-equal (upcase a))) (define-hash-table-test 'case-fold 'case-fold-string= 'case-fold-string-hash) @@ -302,7 +327,7 @@ predefined test value @code{equal}. The keys can be any Lisp object, and equal-looking objects are considered the same key. @example -(define-hash-table-test 'contents-hash 'equal 'sxhash) +(define-hash-table-test 'contents-hash 'equal 'sxhash-equal) (make-hash-table :test 'contents-hash) @end example diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index b945e438f55..1bb2c7c4d08 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -332,15 +332,13 @@ stands for no text itself. It is used only for a side effect: it specifies @var{mapvar}'s value as the keymap for any following @samp{\[@var{command}]} sequences in this documentation string. -@item ‘ -@itemx ` -(left single quotation mark and grave accent) both stand for a left quote. +@item ` +(grave accent) stands for a left quote. This generates a left single quotation mark, an apostrophe, or a grave accent depending on the value of @code{text-quoting-style}. -@item ’ -@itemx ' -(right single quotation mark and apostrophe) both stand for a right quote. +@item ' +(apostrophe) stands for a right quote. This generates a right single quotation mark or an apostrophe depending on the value of @code{text-quoting-style}. @@ -361,7 +359,8 @@ should use for single quotes in the wording of help and messages. If the variable's value is @code{curve}, the style is @t{‘like this’} with curved single quotes. If the value is @code{straight}, the style is @t{'like this'} with straight -apostrophes. If the value is @code{grave}, the style is @t{`like +apostrophes. If the value is @code{grave}, +quotes are not translated and the style is @t{`like this'} with grave accent and apostrophe, the standard style before Emacs version 25. The default value @code{nil} acts like @code{curve} if curved single quotes are displayable, and diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 41064df5a28..fedef3d7f46 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -66,6 +66,16 @@ into the dumped Emacs. If you port Emacs to a new operating system, and are not able to implement dumping, then Emacs must load @file{loadup.el} each time it starts. +@cindex build details +@cindex deterministic build +@cindex @option{--disable-build-details} option to @command{configure} + By default the dumped @file{emacs} executable records details such +as the build time and host name. Use the +@option{--disable-build-details} option of @command{configure} to +suppress these details, so that building and installing Emacs twice +from the same sources is more likely to result in identical copies of +Emacs. + @cindex @file{site-load.el} You can specify additional files to preload by writing a library named @file{site-load.el} that loads them. You may need to rebuild Emacs diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index 0f42d4d8a7f..2f84aeee39e 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi @@ -494,7 +494,8 @@ 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 -@code{current-time} (@pxref{Time of Day}). +@code{current-time} (@pxref{Time of Day}), or is @code{nil} +if the information is not available. @example @group diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 2641ad0b6aa..29f2c422cb2 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -350,7 +350,21 @@ lots of bindings; for just a few, the sparse keymap is better. @end defun @defun copy-keymap keymap -This function returns a copy of @var{keymap}. Any keymaps that +This function returns a copy of @var{keymap}. This is almost never +needed. If you want a keymap that's like another yet with a few +changes, you should use map inheritance rather than copying. +I.e., something like: + +@example +@group +(let ((map (make-sparse-keymap))) + (set-keymap-parent map <theirmap>) + (define-key map ...) + ...) +@end group +@end example + +When performing @code{copy-keymap}, any keymaps that appear directly as bindings in @var{keymap} are also copied recursively, and so on to any number of levels. However, recursive copying does not take place when the definition of a character is a symbol whose function diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index 1468603e508..44ce719bc1f 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -161,8 +161,8 @@ load was done for the sake of @code{autoload}, any function definitions made during the loading are undone. @kindex file-error -If @code{load} can't find the file to load, then normally it signals the -error @code{file-error} (with @samp{Cannot open load file +If @code{load} can't find the file to load, then normally it signals a +@code{file-error} (with @samp{Cannot open load file @var{filename}}). But if @var{missing-ok} is non-@code{nil}, then @code{load} just returns @code{nil}. diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 1fa2536db4e..8d5347556e4 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -170,6 +170,23 @@ non-@code{nil}, then the string that is returned includes whatever text properties were present in the minibuffer. Otherwise all the text properties are stripped when the value is returned. +@vindex minibuffer-prompt-properties +The text properties in @code{minibuffer-prompt-properties} are applied +to the prompt. By default, this property list defines a face to use +for the prompt. This face, if present, is applied to the end of the +face list and merged before display. + +If the user wants to completely control the look of the prompt, the +most convenient way to do that is to specify the @code{default} face +at the end of all face lists. For instance: + +@lisp +(read-from-minibuffer + (concat + (propertize "Bold" 'face '(bold default)) + (propertize " and normal: " 'face '(default)))) +@end lisp + If the argument @var{inherit-input-method} is non-@code{nil}, then the minibuffer inherits the current input method (@pxref{Input Methods}) and the setting of @code{enable-multibyte-characters} (@pxref{Text diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 7bbb5e6f583..3d3122a68ea 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -445,7 +445,8 @@ other packages would interfere with them. Each major mode should have a normal @dfn{mode hook} named @code{@var{modename}-mode-hook}. The very last thing the major mode command should do is to call @code{run-mode-hooks}. This runs the normal -hook @code{change-major-mode-after-body-hook}, the mode hook, +hook @code{change-major-mode-after-body-hook}, the mode hook, the +function @code{hack-local-variables} (when the buffer is visiting a file), and then the normal hook @code{after-change-major-mode-hook}. @xref{Mode Hooks}. @@ -525,11 +526,12 @@ the buffer based on information in the file name or in the file itself. It also processes local variables specified in the file text. @deffn Command normal-mode &optional find-file -This function establishes the proper major mode and buffer-local variable -bindings for the current buffer. First it calls @code{set-auto-mode} -(see below), then it runs @code{hack-local-variables} to parse, and -bind or evaluate as appropriate, the file's local variables -(@pxref{File Local Variables}). +This function establishes the proper major mode and buffer-local +variable bindings for the current buffer. It calls +@code{set-auto-mode} (see below). As of Emacs 26.1, it no longer +runs @code{hack-local-variables}, this now being done in +@code{run-mode-hooks} at the initialization of major modes +(@pxref{Mode Hooks}). If the @var{find-file} argument to @code{normal-mode} is non-@code{nil}, @code{normal-mode} assumes that the @code{find-file} function is calling @@ -543,9 +545,9 @@ If you run @code{normal-mode} interactively, the argument @var{find-file} is normally @code{nil}. In this case, @code{normal-mode} unconditionally processes any file local variables. -The function calls @code{set-auto-mode} to choose a major mode. If this -does not specify a mode, the buffer stays in the major mode determined -by the default value of @code{major-mode} (see below). +The function calls @code{set-auto-mode} to choose and set a major +mode. If this does not specify a mode, the buffer stays in the major +mode determined by the default value of @code{major-mode} (see below). @cindex file mode specification error @code{normal-mode} uses @code{condition-case} around the call to the @@ -555,16 +557,17 @@ mode specification error}, followed by the original error message. @defun set-auto-mode &optional keep-mode-if-same @cindex visited file mode - This function selects the major mode that is appropriate for the -current buffer. It bases its decision (in order of precedence) on the -@w{@samp{-*-}} line, on any @samp{mode:} local variable near the end of -a file, on the @w{@samp{#!}} line (using @code{interpreter-mode-alist}), -on the text at the beginning of the buffer (using -@code{magic-mode-alist}), and finally on the visited file name (using -@code{auto-mode-alist}). @xref{Choosing Modes, , How Major Modes are -Chosen, emacs, The GNU Emacs Manual}. If @code{enable-local-variables} -is @code{nil}, @code{set-auto-mode} does not check the @w{@samp{-*-}} -line, or near the end of the file, for any mode tag. + This function selects and sets the major mode that is appropriate +for the current buffer. It bases its decision (in order of +precedence) on the @w{@samp{-*-}} line, on any @samp{mode:} local +variable near the end of a file, on the @w{@samp{#!}} line (using +@code{interpreter-mode-alist}), on the text at the beginning of the +buffer (using @code{magic-mode-alist}), and finally on the visited +file name (using @code{auto-mode-alist}). @xref{Choosing Modes, , How +Major Modes are Chosen, emacs, The GNU Emacs Manual}. If +@code{enable-local-variables} is @code{nil}, @code{set-auto-mode} does +not check the @w{@samp{-*-}} line, or near the end of the file, for +any mode tag. @vindex inhibit-local-variables-regexps There are some file types where it is not appropriate to scan the file @@ -749,7 +752,8 @@ The new mode has its own abbrev table, kept in the variable @item The new mode has its own mode hook, @code{@var{variant}-hook}. It runs this hook, after running the hooks of its ancestor modes, with -@code{run-mode-hooks}, as the last thing it does. @xref{Mode Hooks}. +@code{run-mode-hooks}, as the last thing it does, apart from running +any @code{:after-hook} form it may have. @xref{Mode Hooks}. @end itemize In addition, you can specify how to override other aspects of @@ -773,8 +777,9 @@ about the mode's hook, followed by the mode's keymap, at the end of this documentation string. If you omit @var{docstring}, @code{define-derived-mode} generates a documentation string. -The @var{keyword-args} are pairs of keywords and values. The values -are evaluated. The following keywords are currently supported: +The @var{keyword-args} are pairs of keywords and values. The values, +except for @code{:after-hook}'s, are evaluated. The following +keywords are currently supported: @table @code @item :syntax-table @@ -797,6 +802,15 @@ If this is specified, the value should be the customization group for this mode. (Not all major modes have one.) The command @code{customize-mode} uses this. @code{define-derived-mode} does @emph{not} automatically define the specified customization group. + +@item :after-hook +This optional keyword specifies a single Lisp form to evaluate as the +final act of the mode function, after the mode hooks have been run. +It should not be quoted. Since the form might be evaluated after the +mode function has terminated, it should not access any element of the +mode function's local state. An @code{:after-hook} form is useful for +setting up aspects of the mode which depend on the user's settings, +which in turn may have been changed in a mode hook. @end table Here is a hypothetical example: @@ -906,11 +920,15 @@ use the following functions to handle these conventions automatically. @defun run-mode-hooks &rest hookvars Major modes should run their mode hook using this function. It is similar to @code{run-hooks} (@pxref{Hooks}), but it also runs -@code{change-major-mode-after-body-hook} and -@code{after-change-major-mode-hook}. +@code{change-major-mode-after-body-hook}, @code{hack-local-variables} +(when the buffer is visiting a file) (@pxref{File Local Variables}), +and @code{after-change-major-mode-hook}. The last thing it does is to +evaluate any @code{:after-hook} forms declared by parent modes +(@pxref{Derived Modes}). When this function is called during the execution of a -@code{delay-mode-hooks} form, it does not run the hooks immediately. +@code{delay-mode-hooks} form, it does not run the hooks or +@code{hack-local-variables} or evaluate the forms immediately. Instead, it arranges for the next call to @code{run-mode-hooks} to run them. @end defun diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index e4581b3d68e..9f805c2c1d9 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -420,6 +420,18 @@ codepoint can have. @end example @end defun +@defun char-from-name string &optional ignore-case +This function returns the character whose Unicode name is @var{string}. +If @var{ignore-case} is non-@code{nil}, case is ignored in @var{string}. +This function returns @code{nil} if @var{string} does not name a character. + +@example +;; U+03A3 +(= (char-from-name "GREEK CAPITAL LETTER SIGMA") #x03A3) + @result{} t +@end example +@end defun + @defun get-byte &optional pos string This function returns the byte at character position @var{pos} in the current buffer. If the current buffer is unibyte, this is literally @@ -622,18 +634,21 @@ This function returns the value of @var{char}'s @var{propname} property. @result{} Nd @end group @group -;; U+2084 SUBSCRIPT FOUR -(get-char-code-property ?\u2084 'digit-value) +;; U+2084 +(get-char-code-property ?\N@{SUBSCRIPT FOUR@} + 'digit-value) @result{} 4 @end group @group -;; U+2155 VULGAR FRACTION ONE FIFTH -(get-char-code-property ?\u2155 'numeric-value) +;; U+2155 +(get-char-code-property ?\N@{VULGAR FRACTION ONE FIFTH@} + 'numeric-value) @result{} 0.2 @end group @group -;; U+2163 ROMAN NUMERAL FOUR -(get-char-code-property ?\u2163 'numeric-value) +;; U+2163 +(get-char-code-property ?\N@{ROMAN NUMERAL FOUR@} + 'numeric-value) @result{} 4 @end group @group diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 324593068d5..5e608bcc093 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -353,25 +353,32 @@ following text.) control characters, Emacs provides several types of escape syntax that you can use to specify non-@acronym{ASCII} text characters. +@enumerate +@item @cindex @samp{\} in character constant @cindex backslash in character constants @cindex unicode character escape - Firstly, you can specify characters by their Unicode values. -@code{?\u@var{nnnn}} represents a character with Unicode code point -@samp{U+@var{nnnn}}, where @var{nnnn} is (by convention) a hexadecimal -number with exactly four digits. The backslash indicates that the -subsequent characters form an escape sequence, and the @samp{u} -specifies a Unicode escape sequence. - - There is a slightly different syntax for specifying Unicode -characters with code points higher than @code{U+@var{ffff}}: -@code{?\U00@var{nnnnnn}} represents the character with code point -@samp{U+@var{nnnnnn}}, where @var{nnnnnn} is a six-digit hexadecimal -number. The Unicode Standard only defines code points up to -@samp{U+@var{10ffff}}, so if you specify a code point higher than -that, Emacs signals an error. - - Secondly, you can specify characters by their hexadecimal character +You can specify characters by their Unicode names, if any. +@code{?\N@{@var{NAME}@}} represents the Unicode character named +@var{NAME}. Thus, @samp{?\N@{LATIN SMALL LETTER A WITH GRAVE@}} is +equivalent to @code{?à} and denotes the Unicode character U+00E0. To +simplify entering multi-line strings, you can replace spaces in the +names by non-empty sequences of whitespace (e.g., newlines). + +@item +You can specify characters by their Unicode values. +@code{?\N@{U+@var{X}@}} represents a character with Unicode code point +@var{X}, where @var{X} is a hexadecimal number. Also, +@code{?\u@var{xxxx}} and @code{?\U@var{xxxxxxxx}} represent code +points @var{xxxx} and @var{xxxxxxxx}, respectively, where each @var{x} +is a single hexadecimal digit. For example, @code{?\N@{U+E0@}}, +@code{?\u00e0} and @code{?\U000000E0} are all equivalent to @code{?à} +and to @samp{?\N@{LATIN SMALL LETTER A WITH GRAVE@}}. The Unicode +Standard defines code points only up to @samp{U+@var{10ffff}}, so if +you specify a code point higher than that, Emacs signals an error. + +@item +You can specify characters by their hexadecimal character codes. A hexadecimal escape sequence consists of a backslash, @samp{x}, and the hexadecimal character code. Thus, @samp{?\x41} is the character @kbd{A}, @samp{?\x1} is the character @kbd{C-a}, and @@ -379,14 +386,17 @@ the character @kbd{A}, @samp{?\x1} is the character @kbd{C-a}, and You can use any number of hex digits, so you can represent any character code in this way. +@item @cindex octal character code - Thirdly, you can specify characters by their character code in +You can specify characters by their character code in octal. An octal escape sequence consists of a backslash followed by up to three octal digits; thus, @samp{?\101} for the character @kbd{A}, @samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the character @kbd{C-b}. Only characters up to octal code 777 can be specified this way. +@end enumerate + These escape sequences may also be used in strings. @xref{Non-ASCII in Strings}. @@ -1400,6 +1410,9 @@ editing. * Window Configuration Type:: Recording the way a frame is subdivided. * Frame Configuration Type:: Recording the status of all frames. * Process Type:: A subprocess of Emacs running on the underlying OS. +* Thread Type:: A thread of Emacs Lisp execution. +* Mutex Type:: An exclusive lock for thread synchronization. +* Condition Variable Type:: Condition variable for thread synchronization. * Stream Type:: Receive or send characters. * Keymap Type:: What function a keystroke invokes. * Overlay Type:: How an overlay is represented. @@ -1615,6 +1628,63 @@ giving the name of the process: return information about, send input or signals to, and receive output from processes. +@node Thread Type +@subsection Thread Type + + A @dfn{thread} in Emacs represents a separate thread of Emacs Lisp +execution. It runs its own Lisp program, has its own current buffer, +and can have subprocesses locked to it, i.e.@: subprocesses whose +output only this thread can accept. @xref{Threads}. + + Thread objects have no read syntax. They print in hash notation, +giving the name of the thread (if it has been given a name) or its +address in core: + +@example +@group +(all-threads) + @result{} (#<thread 0176fc40>) +@end group +@end example + +@node Mutex Type +@subsection Mutex Type + + A @dfn{mutex} is an exclusive lock that threads can own and disown, +in order to synchronize between them. @xref{Mutexes}. + + Mutex objects have no read syntax. They print in hash notation, +giving the name of the mutex (if it has been given a name) or its +address in core: + +@example +@group +(make-mutex "my-mutex") + @result{} #<mutex my-mutex> +(make-mutex) + @result{} #<mutex 01c7e4e0> +@end group +@end example + +@node Condition Variable Type +@subsection Condition Variable Type + + A @dfn{condition variable} is a device for a more complex thread +synchronization than the one supported by a mutex. A thread can wait +on a condition variable, to be woken up when some other thread +notifies the condition. + + Condition variable objects have no read syntax. They print in hash +notation, giving the name of the condition variable (if it has been +given a name) or its address in core: + +@example +@group +(make-condition-variable (make-mutex)) + @result{} #<condvar 01c45ae8> +@end group +@end example + @node Stream Type @subsection Stream Type @@ -1820,6 +1890,9 @@ with references to further information. @item commandp @xref{Interactive Call, commandp}. +@item condition-variable-p +@xref{Condition Variables, condition-variable-p}. + @item consp @xref{List-related Predicates, consp}. @@ -1865,6 +1938,9 @@ with references to further information. @item markerp @xref{Predicates on Markers, markerp}. +@item mutexp +@xref{Mutexes, mutexp}. + @item wholenump @xref{Predicates on Numbers, wholenump}. @@ -1898,6 +1974,9 @@ with references to further information. @item syntax-table-p @xref{Syntax Tables, syntax-table-p}. +@item threadp +@xref{Basic Thread Functions, threadp}. + @item vectorp @xref{Vectors, vectorp}. @@ -1915,6 +1994,15 @@ with references to further information. @item string-or-null-p @xref{Predicates for Strings, string-or-null-p}. + +@item threadp +@xref{Basic Thread Functions, threadp}. + +@item mutexp +@xref{Mutexes, mutexp}. + +@item condition-variable-p +@xref{Condition Variables, condition-variable-p}. @end table The most general way to check the type of an object is to call the @@ -1928,11 +2016,12 @@ types. In most cases, it is more convenient to use type predicates than This function returns a symbol naming the primitive type of @var{object}. The value is one of the symbols @code{bool-vector}, @code{buffer}, @code{char-table}, @code{compiled-function}, -@code{cons}, @code{finalizer}, @code{float}, @code{font-entity}, -@code{font-object}, @code{font-spec}, @code{frame}, @code{hash-table}, -@code{integer}, @code{marker}, @code{overlay}, @code{process}, -@code{string}, @code{subr}, @code{symbol}, @code{vector}, -@code{window}, or @code{window-configuration}. +@code{condition-variable}, @code{cons}, @code{finalizer}, +@code{float}, @code{font-entity}, @code{font-object}, +@code{font-spec}, @code{frame}, @code{hash-table}, @code{integer}, +@code{marker}, @code{mutex}, @code{overlay}, @code{process}, +@code{string}, @code{subr}, @code{symbol}, @code{thread}, +@code{vector}, @code{window}, or @code{window-configuration}. @example (type-of 1) diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 9fa27113d04..1a45eac04e3 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -112,8 +112,8 @@ compiled into the Emacs executable when it was built. It runs the normal hook @code{before-init-hook}. @item -If appropriate, it creates a graphical frame. This is not done if the -options @samp{--batch} or @samp{--daemon} were specified. +If appropriate, it creates a graphical frame. This is not done in +batch (noninteractive) or daemon mode. @item It initializes the initial frame's faces, and sets up the menu bar @@ -256,10 +256,10 @@ options were specified. @c last few bits of command-line-1 are not done in batch mode. @item -If the option @code{--daemon} was specified, it calls -@code{server-start}, and on Posix systems also detaches from the -controlling terminal. @xref{Emacs Server,,, emacs, The GNU Emacs -Manual}. +If a daemon was requested, it calls @code{server-start}. +(On Posix systems, if a background daemon was requested, it then +detaches from the controlling terminal.) @xref{Emacs +Server,,, emacs, The GNU Emacs Manual}. @item If started by the X session manager, it calls @@ -337,7 +337,10 @@ Do not display a splash screen. Run without an interactive terminal. @xref{Batch Mode}. @item --daemon -Do not initialize any display; just start a server in the background. +@itemx --old-daemon +@itemx --new-daemon +Do not initialize any display; just start a server. +(An ``old-style'' daemon automatically runs in the background.) @item --no-init-file @itemx -q @@ -904,9 +907,6 @@ A GNU (glibc-based) system with a FreeBSD kernel. @item hpux Hewlett-Packard HPUX operating system. -@item irix -Silicon Graphics Irix system. - @item nacl Google Native Client (@acronym{NaCl}) sandboxing system. @@ -1333,7 +1333,13 @@ omitted or @code{nil}, the conversion uses Emacs's default time zone. If it is @code{t}, the conversion uses Universal Time. If it is @code{wall}, the conversion uses the system wall clock time. If it is a string, the conversion uses the time zone rule equivalent to setting -@env{TZ} to that string. +@env{TZ} to that string. If it is an integer @var{offset}, the +conversion uses a fixed time zone with the given offset and a numeric +abbreviation on POSIX-compatible platforms and an unspecified abbreviation +on MS-Windows. If it is a list (@var{offset} @var{abbr}), where +@var{offset} is an integer number of seconds east of Universal Time +and @var{abbr} is a string, the conversion uses a fixed time zone with +the given offset and abbreviation. @defun current-time-zone &optional time zone @cindex time zone, current @@ -1431,10 +1437,6 @@ yourself before you call @code{encode-time}. The optional argument @var{zone} defaults to the current time zone rule. @xref{Time Zone Rules}. -In addition to the usual time zone rule values, it can also be a list -(as you would get from @code{current-time-zone}) or an integer (as -from @code{decode-time}), applied without any further alteration for -daylight saving time. 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 @@ -1530,6 +1532,8 @@ fewer digits, use @samp{%3N} for milliseconds, @samp{%6N} for microseconds, etc. Any excess digits are discarded, without rounding. @item %p This stands for @samp{AM} or @samp{PM}, as appropriate. +@item %q +This stands for the calendar quarter (1--4). @item %r This is a synonym for @samp{%I:%M:%S %p}. @item %R @@ -1889,6 +1893,12 @@ one of these functions; the arrival of the specified time will not cause anything special to happen. @end defun +@findex timer-list +The @code{timer-list} command lists all the currently active timers. +There's only one command available in the buffer displayed: @kbd{c} +(@code{timer-list-cancel}) that will cancel the timer on the line +under point. + @node Idle Timers @section Idle Timers @cindex idle timers @@ -2265,14 +2275,16 @@ The variable is always local to the current terminal, and cannot be buffer-local. @xref{Multiple Terminals}. @end defvar -You can specify which keysyms Emacs should use for the Meta, Alt, Hyper, and Super modifiers by setting these variables: +You can specify which keysyms Emacs should use for the Control, Meta, +Alt, Hyper, and Super modifiers by setting these variables: -@defvar x-alt-keysym +@defvar x-ctrl-keysym +@defvarx x-alt-keysym @defvarx x-meta-keysym @defvarx x-hyper-keysym @defvarx x-super-keysym -The name of the keysym that should stand for the Alt modifier -(respectively, for Meta, Hyper, and Super). For example, here is +The name of the keysym that should stand for the Control modifier +(respectively, for Alt, Meta, Hyper, and Super). For example, here is how to swap the Meta and Alt modifiers within Emacs: @lisp (setq x-alt-keysym 'meta) diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index b6133dc7e2d..a56ab5ef307 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -593,10 +593,12 @@ any buffer, whether or not it is currently displayed in some window. @deffn Command move-to-window-line count This function moves point with respect to the text currently displayed in the selected window. It moves point to the beginning of the screen -line @var{count} screen lines from the top of the window. If -@var{count} is negative, that specifies a position -@w{@minus{}@var{count}} lines from the bottom (or the last line of the -buffer, if the buffer ends above the specified screen position). +line @var{count} screen lines from the top of the window; zero means +the topmost line. If @var{count} is negative, that specifies a +position @w{@minus{}@var{count}} lines from the bottom (or the last +line of the buffer, if the buffer ends above the specified screen +position); thus, @var{count} of -1 specifies the last fully visible +screen line of the window. If @var{count} is @code{nil}, then point moves to the beginning of the line in the middle of the window. If the absolute value of @var{count} @@ -607,8 +609,8 @@ location onto the screen. In an interactive call, @var{count} is the numeric prefix argument. -The value returned is the window line number point has moved to, with -the top line in the window numbered 0. +The value returned is the screen line number point has moved to, +relative to the top line of the window. @end deffn @vindex move-to-window-group-line-function diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 950dc9c6d49..064934cc662 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -512,20 +512,17 @@ inputinput@point{} @end smallexample For example, the @code{shell-command-on-region} command uses -@code{call-process-region} in a manner similar to this: +@code{call-shell-region} in a manner similar to this: @smallexample @group -(call-process-region +(call-shell-region start end - shell-file-name ; @r{name of program} + command ; @r{shell command} nil ; @r{do not delete region} - buffer ; @r{send output to @code{buffer}} - nil ; @r{no redisplay during output} - "-c" command) ; @r{arguments for the shell} + buffer) ; @r{send output to @code{buffer}} @end group @end smallexample -@c It actually uses shell-command-switch, but no need to mention that here. @end defun @defun call-process-shell-command command &optional infile destination display @@ -545,6 +542,15 @@ convention allowed passing any number of additional arguments after supported, but strongly discouraged. @end defun +@defun call-shell-region start end command &optional delete destination +This function sends the text from @var{start} to @var{end} as +standard input to an inferior shell running @var{command}. This function +is similar than @code{call-process-region}, with process being a shell. +The arguments @code{delete}, @code{destination} and the return value +are like in @code{call-process-region}. +Note that this function doesn't accept additional arguments. +@end defun + @defun shell-command-to-string command This function executes @var{command} (a string) as a shell command, then returns the command's output as a string. @@ -1394,6 +1400,7 @@ Emacs tries to read it. * Filter Functions:: Filter functions accept output from the process. * Decoding Output:: Filters can get unibyte or multibyte strings. * Accepting Output:: How to wait until process output arrives. +* Processes and Threads:: How processes and threads interact. @end menu @node Process Buffers @@ -1785,6 +1792,35 @@ got output from @var{process}, or from any process if @var{process} is arrived. @end defun +@node Processes and Threads +@subsection Processes and Threads +@cindex processes, threads + + Because threads were a relatively late addition to Emacs Lisp, and +due to the way dynamic binding was sometimes used in conjunction with +@code{accept-process-output}, by default a process is locked to the +thread that created it. When a process is locked to a thread, output +from the process can only be accepted by that thread. + + A Lisp program can specify to which thread a process is to be +locked, or instruct Emacs to unlock a process, in which case its +output can be processed by any thread. Only a single thread will wait +for output from a given process at one time---once one thread begins +waiting for output, the process is temporarily locked until +@code{accept-process-output} or @code{sit-for} returns. + + If the thread exits, all the processes locked to it are unlocked. + +@defun process-thread process +Return the thread to which @var{process} is locked. If @var{process} +is unlocked, return @code{nil}. +@end defun + +@defun set-process-thread process thread +Set the locking thread of @var{process} to @var{thread}. @var{thread} +may be @code{nil}, in which case the process is unlocked. +@end defun + @node Sentinels @section Sentinels: Detecting Process Status Changes @cindex process sentinel @@ -1964,6 +2000,13 @@ shell process to avoid querying: @end smallexample @end defun +@defopt confirm-kill-processes +If this user option is set to @code{t} (the default), then Emacs asks +for confirmation before killing processes on exit. If it is +@code{nil}, Emacs kills processes without confirmation, i.e., the +query flag of all processes is ignored. +@end defopt + @node System Processes @section Accessing Other Processes @cindex system processes @@ -2288,7 +2331,8 @@ associated with any buffer. The arguments @var{host} and @var{service} specify where to connect to; @var{host} is the host name (a string), and @var{service} is the name of -a defined network service (a string) or a port number (an integer). +a defined network service (a string) or a port number (an integer like +@code{80} or an integer string like @code{"80"}). The remaining arguments @var{parameters} are keyword/argument pairs that are mainly relevant to encrypted connections: @@ -2512,8 +2556,9 @@ connecting to that address will be accepted. @item :service @var{service} @var{service} specifies a port number to connect to; or, for a server, -the port number to listen on. It should be a service name that -translates to a port number, or an integer specifying the port number +the port number to listen on. It should be a service name like +@samp{"http"} that translates to a port number, or an integer like @samp{80} +or an integer string like @samp{"80"} that specifies the port number directly. For a server, it can also be @code{t}, which means to let the system select an unused port number. @@ -2525,6 +2570,12 @@ automatically for the given @var{host} and @var{service}. ignored. @code{ipv4} and @code{ipv6} specify to use IPv4 and IPv6, respectively. +@item :use-external-socket @var{use-external-socket} +If @var{use-external-socket} is non-@code{nil} use any sockets passed +to Emacs on invocation instead of allocating one. This is used by the +Emacs server code to allow on-demand socket activation. If Emacs +wasn't passed a socket, this option is silently ignored. + @item :local @var{local-address} For a server process, @var{local-address} is the address to listen on. It overrides @var{family}, @var{host} and @var{service}, so you @@ -2575,8 +2626,33 @@ without waiting for the connection to complete. When the connection succeeds or fails, Emacs will call the sentinel function, with a second argument matching @code{"open"} (if successful) or @code{"failed"}. The default is to block, so that -@code{make-network-process} does not return until the connection -has succeeded or failed. +@code{make-network-process} does not return until the connection has +succeeded or failed. + +If you're setting up an asynchronous TLS connection, you have to also +provide the @code{:tls-parameters} parameter (see below). + +Depending on the capabilities of Emacs, how asynchronous +@code{:nowait} is may vary. The three elements that may (or may not) +be done asynchronously are domain name resolution, socket setup, and +(for TLS connections) TLS negotiation. + +Many functions that interact with process objects, (for instance, +@code{process-datagram-address}) rely on them at least having a socket +before they can return a useful value. These functions will block +until the socket has achieved the desired status. The recommended way +of interacting with asynchronous sockets is to place a sentinel on the +process, and not try to interact with it before it has changed status +to @samp{"run"}. That way, none of these functions will block. + +@item :tls-parameters +When opening a TLS connection, this should be where the first element +is the TLS type (which should either be @code{gnutls-x509pki} or +@code{gnutls-anon}, and the remaining elements should form a keyword +list acceptable for @code{gnutls-boot}. (This keyword list can be +obtained from the @code{gnutls-boot-parameters} function.) The TLS +connection will then be negotiated after completing the connection to +the host. @item :stop @var{stopped} If @var{stopped} is non-@code{nil}, start the network connection or diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index 579460f3227..4b97aae8cac 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -1838,6 +1838,14 @@ Answer this question and all subsequent questions in the series with @item backup Move back to the previous place that a question was asked about. +@item undo +Undo last replacement and move back to the place where that +replacement was performed. + +@item undo-all +Undo all replacements and move back to the place where the first +replacement was performed. + @item edit Enter a recursive edit to deal with this question---instead of any other action that would normally be taken. diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 920399586c5..421308665db 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -576,6 +576,21 @@ element of @var{sequence}. The returned value is a list. @end example @end defun +@defun seq-map-indexed function sequence + This function returns the result of applying @var{function} to each +element of @var{sequence} and its index within @var{seq}. The +returned value is a list. + +@example +@group +(seq-map-indexed (lambda (elt idx) + (list idx elt)) + '(a b c)) +@result{} ((0 a) (b 1) (c 2)) +@end group +@end example +@end defun + @defun seq-mapn function &rest sequences This function returns the result of applying @var{function} to each element of @var{sequences}. The arity (@pxref{What Is a Function, @@ -748,6 +763,18 @@ according to @var{function}, a function of two arguments that returns non-@code{nil} if the first argument should sort before the second. @end defun +@defun seq-sort-by function predicate sequence + This function is similar to @code{seq-sort}, but the elements of +@var{sequence} are transformed by applying @var{function} on them +before being sorted. @var{function} is a function of one argument. + +@example +(seq-sort-by #'seq-length #'> ["a" "ab" "abc"]) +@result{} ["abc" "ab" "a"] +@end example +@end defun + + @defun seq-contains sequence elt &optional function This function returns the first element in @var{sequence} that is equal to @var{elt}. If the optional argument @var{function} is non-@code{nil}, @@ -1010,6 +1037,26 @@ followed by a variable name to be bound to the rest of @end example @end defmac +@defun seq-random-elt sequence + This function returns an element of @var{sequence} taken at random. + +@example +@group +(seq-random-elt [1 2 3 4]) +@result{} 3 +(seq-random-elt [1 2 3 4]) +@result{} 2 +(seq-random-elt [1 2 3 4]) +@result{} 4 +(seq-random-elt [1 2 3 4]) +@result{} 2 +(seq-random-elt [1 2 3 4]) +@result{} 1 +@end group +@end example + + If @var{sequence} is empty, this function signals an error. +@end defun @node Arrays @section Arrays diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi index 41bc71e6aea..757e0e831be 100644 --- a/doc/lispref/streams.texi +++ b/doc/lispref/streams.texi @@ -639,7 +639,7 @@ spacing between calls. This function outputs a newline to @var{stream}. The name stands for ``terminate print''. If @var{ensure} is non-@code{nil} no newline is printed if @var{stream} is already at the beginning of a line. Note in this -case @var{stream} can not be a function and an error is signalled if +case @var{stream} can not be a function and an error is signaled if it is. This function returns @code{t} if a newline is printed. @end defun diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 3c764da4e2b..ff108511f23 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -620,6 +620,14 @@ If your system does not support a locale environment, this function behaves like @code{string-lessp}. @end defun +@defun string-version-lessp string1 string2 +This function compares strings lexicographically, except it treats +sequences of numerical characters as if they comprised a base-ten +number, and then compares the numbers. So @samp{foo2.png} is +``smaller'' than @samp{foo12.png} according to this predicate, even if +@samp{12} is lexicographically ``smaller'' than @samp{2}. +@end defun + @defun string-prefix-p string1 string2 &optional ignore-case This function returns non-@code{nil} if @var{string1} is a prefix of @var{string2}; i.e., if @var{string2} starts with @var{string1}. If @@ -813,16 +821,16 @@ arguments @var{objects} are the computed values to be formatted. The characters in @var{string}, other than the format specifications, are copied directly into the output, including their text properties, -if any. +if any. Any text properties of the format specifications are copied +to the produced string representations of the argument @var{objects}. @end defun @defun format-message string &rest objects @cindex curved quotes @cindex curly quotes This function acts like @code{format}, except it also converts any -curved single quotes in @var{string} as per the value of -@code{text-quoting-style}, and treats grave accent (@t{`}) and -apostrophe (@t{'}) as if they were curved single quotes. +grave accents (@t{`}) and apostrophes (@t{'}) in @var{string} as per the +value of @code{text-quoting-style}. A format that quotes with grave accents and apostrophes @t{`like this'} typically generates curved quotes @t{‘like this’}. In diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi index 19782d0fbde..f81c1643c21 100644 --- a/doc/lispref/syntax.texi +++ b/doc/lispref/syntax.texi @@ -331,10 +331,10 @@ alternative ``c'' comment style. For a two-character comment delimiter, @samp{c} on either character makes it of style ``c''. @item -@samp{n} on a comment delimiter character specifies -that this kind of comment can be nested. For a two-character -comment delimiter, @samp{n} on either character makes it -nestable. +@samp{n} on a comment delimiter character specifies that this kind of +comment can be nested. Inside such a comment, only comments of the +same style will be recognized. For a two-character comment delimiter, +@samp{n} on either character makes it nestable. @cindex comment style Emacs supports several comment styles simultaneously in any one syntax @@ -791,10 +791,10 @@ Hooks}). @subsection Parser State @cindex parser state - A @dfn{parser state} is a list of ten elements describing the state -of the syntactic parser, after it parses the text between a specified -starting point and a specified end point in the buffer. Parsing -functions such as @code{syntax-ppss} + A @dfn{parser state} is a list of (currently) eleven elements +describing the state of the syntactic parser, after it parses the text +between a specified starting point and a specified end point in the +buffer. Parsing functions such as @code{syntax-ppss} @ifnottex (@pxref{Position Parse}) @end ifnottex @@ -851,15 +851,20 @@ position where the string began. When outside of strings and comments, this element is @code{nil}. @item -Internal data for continuing the parsing. The meaning of this -data is subject to change; it is used if you pass this list -as the @var{state} argument to another call. +The list of the positions of the currently open parentheses, starting +with the outermost. + +@item +When the last buffer position scanned was the (potential) first +character of a two character construct (comment delimiter or +escaped/char-quoted character pair), the @var{syntax-code} +(@pxref{Syntax Table Internals}) of that position. Otherwise +@code{nil}. @end enumerate Elements 1, 2, and 6 are ignored in a state which you pass as an -argument to continue parsing, and elements 8 and 9 are used only in -trivial cases. Those elements are mainly used internally by the -parser code. +argument to continue parsing. Elements 9 and 10 are mainly used +internally by the parser code. One additional piece of useful information is available from a parser state using this function: @@ -898,10 +903,11 @@ The depth starts at 0, or at whatever is given in @var{state}. If the fourth argument @var{stop-before} is non-@code{nil}, parsing stops when it comes to any character that starts a sexp. If -@var{stop-comment} is non-@code{nil}, parsing stops when it comes to the -start of a comment. If @var{stop-comment} is the symbol -@code{syntax-table}, parsing stops after the start of a comment or a -string, or the end of a comment or a string, whichever comes first. +@var{stop-comment} is non-@code{nil}, parsing stops after the start of +an unnested comment. If @var{stop-comment} is the symbol +@code{syntax-table}, parsing stops after the start of an unnested +comment or a string, or after the end of an unnested comment or a +string, whichever comes first. If @var{state} is @code{nil}, @var{start} is assumed to be at the top level of parenthesis structure, such as the beginning of a function diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index b6635ddb0a0..0da34d14f24 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -2364,6 +2364,83 @@ already indented, it calls @code{completion-at-point} to complete the text at point (@pxref{Completion in Buffers}). @end defopt +@cindex literate programming +@cindex multi-mode indentation + Some major modes need to support embedded regions of text whose +syntax belongs to a different major mode. Examples include +@dfn{literate programming} source files that combine documentation and +snippets of source code, Yacc/Bison programs that include snippets of +plain C code, etc. To correctly indent the embedded chunks, the major +mode needs to delegate the indentation to another mode's indentation +engine (e.g., call @code{c-indent-defun} for C code or +@code{python-indent-line} for Python), while providing it with some +context to guide the indentation. The following facilities support +such multi-mode indentation. + +@defvar prog-indentation-context +This variable, when non-@code{nil}, holds the indentation context for +the sub-mode's indentation engine provided by the superior major mode. +The value should be a list of the form @code{(@var{first-column} +@w{(@var{start} . @var{end})} @code{prev-chunk})}. The members of the +list have the following meaning: + +@table @var +@item first-column +The column to be used for top-level constructs. This replaces the +default value of the top-level column used by the sub-mode, usually +zero. +@item start +@itemx end +The region of the code chunk to be indented by the sub-mode. The +value of @var{end} can be @code{nil}, which stands for the value of +@code{point-max}. +@item prev-chunk +If this is non-@code{nil}, it should provide the sub-mode's +indentation engine with a virtual context of the code chunk. Valid +values include: + +@itemize @minus +@item +A string whose contents is the text the sub-mode's indentation engine +should consider to precede the code chunk. The sub-mode's indentation +engine can add text properties to that string, to be reused in +repeated calls with the same string, thus using it as a cache. An +example where this is useful is code chunks that need to be indented +as function bodies, but lack the function's preamble---the string +could then include that missing preamble. +@item +A function. It is expected to be called with the start position of +the current chunk, and should return a cons cell +@w{@code{(@var{prev-start} . @var{prev-end})}} that specifies the +region of the previous code chunk, or @code{nil} if there is no previous +chunk. This is useful in literate-programming sources, where code is +split into chunks, and correct indentation needs to access previous +chunks. +@end itemize +@end table +@end defvar + +The following convenience functions should be used by major mode's +indentation engine in support of invocations as sub-modes of another +major mode. + +@defun prog-first-column +Call this function instead of using a literal value (usually, zero) of +the column number for indenting top-level program constructs. The +function's value is the column number to use for top-level constructs. +When no superior mode is in effect, this function returns zero. +@end defun + +@defun prog-widen +Call this function instead of @code{widen} to remove any restrictions +imposed by the mode's indentation engine and restore the restrictions +recorded in @code{prog-indentation-context}. This prevents the +indentation engine of a sub-mode from inadvertently operating on text +outside of the chunk it was supposed to indent, and preserves the +restriction imposed by the superior mode. When no superior mode is in +effect, this function just calls @code{widen}. +@end defun + @node Region Indent @subsection Indenting an Entire Region @@ -4396,6 +4473,20 @@ using the specified or chosen coding system. However, if coding instead. @end defun +@defun buffer-hash &optional buffer-or-name +Return a hash of @var{buffer-or-name}. If @code{nil}, this defaults +to the current buffer. As opposed to @code{secure-hash}, this +function computes the hash based on the internal representation of the +buffer, disregarding any coding systems. It's therefore only useful +when comparing two buffers running in the same Emacs, and is not +guaranteed to return the same hash between different Emacs versions. +It should be somewhat more efficient on larger buffers than +@code{secure-hash} is, and should not allocate more memory. +@c Note that we do not document what hashing function we're using, or +@c even whether it's a cryptographic hash, since that may change +@c according to what we find useful. +@end defun + @node Parsing HTML/XML @section Parsing HTML and XML @cindex parsing html @@ -4527,6 +4618,9 @@ to be inserted between the textual elements. @item dom-parent @var{dom} @var{node} Return the parent of @var{node} in @var{dom}. + +@item dom-remove @var{dom} @var{node} +Remove @var{node} from @var{dom}. @end table The following are functions for altering the @acronym{DOM}. diff --git a/doc/lispref/threads.texi b/doc/lispref/threads.texi new file mode 100644 index 00000000000..de1c27bf186 --- /dev/null +++ b/doc/lispref/threads.texi @@ -0,0 +1,253 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 2012-2016 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@node Threads +@chapter Threads +@cindex threads +@cindex concurrency + + Emacs Lisp provides a limited form of concurrency, called +@dfn{threads}. All the threads in a given instance of Emacs share the +same memory. Concurrency in Emacs Lisp is ``mostly cooperative'', +meaning that Emacs will only switch execution between threads at +well-defined times. However, the Emacs thread support has been +designed in a way to later allow more fine-grained concurrency, and +correct programs should not rely on cooperative threading. + + Currently, thread switching will occur upon explicit request via +@code{thread-yield}, when waiting for keyboard input or for process +output (e.g., during @code{accept-process-output}), or during blocking +operations relating to threads, such as mutex locking or +@code{thread-join}. + + Emacs Lisp provides primitives to create and control threads, and +also to create and control mutexes and condition variables, useful for +thread synchronization. + + While global variables are shared among all Emacs Lisp threads, +local variables are not---a dynamic @code{let} binding is local. Each +thread also has its own current buffer (@pxref{Current Buffer}) and +its own match data (@pxref{Match Data}). + + Note that @code{let} bindings are treated specially by the Emacs +Lisp implementation. There is no way to duplicate this unwinding and +rewinding behavior other than by using @code{let}. For example, a +manual implementation of @code{let} written using +@code{unwind-protect} cannot arrange for variable values to be +thread-specific. + + In the case of lexical bindings (@pxref{Variable Scoping}), a +closure is an object like any other in Emacs Lisp, and bindings in a +closure are shared by any threads invoking the closure. + +@menu +* Basic Thread Functions:: Basic thread functions. +* Mutexes:: Mutexes allow exclusive access to data. +* Condition Variables:: Inter-thread events. +@end menu + +@node Basic Thread Functions +@section Basic Thread Functions + + Threads can be created and waited for. A thread cannot be exited +directly, but the current thread can be exited implicitly, and other +threads can be signaled. + +@defun make-thread function &optional name +Create a new thread of execution which invokes @var{function}. When +@var{function} returns, the thread exits. + +The new thread is created with no local variable bindings in effect. +The new thread's current buffer is inherited from the current thread. + +@var{name} can be supplied to give a name to the thread. The name is +used for debugging and informational purposes only; it has no meaning +to Emacs. If @var{name} is provided, it must be a string. + +This function returns the new thread. +@end defun + +@defun threadp object +This function returns @code{t} if @var{object} represents an Emacs +thread, @code{nil} otherwise. +@end defun + +@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. +@end defun + +@defun thread-signal thread error-symbol data +Like @code{signal} (@pxref{Signaling Errors}), but the signal is +delivered in the thread @var{thread}. If @var{thread} is the current +thread, then this just calls @code{signal} immediately. Otherwise, +@var{thread} will receive the signal as soon as it becomes current. +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. +@end defun + +@defun thread-yield +Yield execution to the next runnable thread. +@end defun + +@defun thread-name thread +Return the name of @var{thread}, as specified to @code{make-thread}. +@end defun + +@defun thread-alive-p thread +Return @code{t} if @var{thread} is alive, or @code{nil} if it is not. +A thread is alive as long as its function is still executing. +@end defun + +@defun thread--blocker thread +Return the object that @var{thread} is waiting on. This function is +primarily intended for debugging, and is given a ``double hyphen'' +name to indicate that. + +If @var{thread} is blocked in @code{thread-join}, this returns the +thread for which it is waiting. + +If @var{thread} is blocked in @code{mutex-lock}, this returns the mutex. + +If @var{thread} is blocked in @code{condition-wait}, this returns the +condition variable. + +Otherwise, this returns @code{nil}. +@end defun + +@defun current-thread +Return the current thread. +@end defun + +@defun all-threads +Return a list of all the live thread objects. A new list is returned +by each invocation. +@end defun + +@node Mutexes +@section Mutexes + + A @dfn{mutex} is an exclusive lock. At any moment, zero or one +threads may own a mutex. If a thread attempts to acquire a mutex, and +the mutex is already owned by some other thread, then the acquiring +thread will block until the mutex becomes available. + + Emacs Lisp mutexes are of a type called @dfn{recursive}, which means +that a thread can re-acquire a mutex it owns any number of times. A +mutex keeps a count of how many times it has been acquired, and each +acquisition of a mutex must be paired with a release. The last +release by a thread of a mutex reverts it to the unowned state, +potentially allowing another thread to acquire the mutex. + +@defun mutexp object +This function returns @code{t} if @var{object} represents an Emacs +mutex, @code{nil} otherwise. +@end defun + +@defun make-mutex &optional name +Create a new mutex and return it. If @var{name} is specified, it is a +name given to the mutex. It must be a string. The name is for +debugging purposes only; it has no meaning to Emacs. +@end defun + +@defun mutex-name mutex +Return the name of @var{mutex}, as specified to @code{make-mutex}. +@end defun + +@defun mutex-lock mutex +This will block until this thread acquires @var{mutex}, or until this +thread is signaled using @code{thread-signal}. If @var{mutex} is +already owned by this thread, this simply returns. +@end defun + +@defun mutex-unlock mutex +Release @var{mutex}. If @var{mutex} is not owned by this thread, this +will signal an error. +@end defun + +@defmac with-mutex mutex body@dots{} +This macro is the simplest and safest way to evaluate forms while +holding a mutex. It acquires @var{mutex}, invokes @var{body}, and +then releases @var{mutex}. It returns the result of @var{body}. +@end defmac + +@node Condition Variables +@section Condition Variables + + A @dfn{condition variable} is a way for a thread to block until some +event occurs. A thread can wait on a condition variable, to be woken +up when some other thread notifies the condition. + + A condition variable is associated with a mutex and, conceptually, +with some condition. For proper operation, the mutex must be +acquired, and then a waiting thread must loop, testing the condition +and waiting on the condition variable. For example: + +@example +(with-mutex mutex + (while (not global-variable) + (condition-wait cond-var))) +@end example + + The mutex ensures atomicity, and the loop is for robustness---there +may be spurious notifications. + + Similarly, the mutex must be held before notifying the condition. +The typical, and best, approach is to acquire the mutex, make the +changes associated with this condition, and then notify it: + +@example +(with-mutex mutex + (setq global-variable (some-computation)) + (condition-notify cond-var)) +@end example + +@defun make-condition-variable mutex &optional name +Make a new condition variable associated with @var{mutex}. If +@var{name} is specified, it is a name given to the condition variable. +It must be a string. The name is for debugging purposes only; it has +no meaning to Emacs. +@end defun + +@defun condition-variable-p object +This function returns @code{t} if @var{object} represents a condition +variable, @code{nil} otherwise. +@end defun + +@defun condition-wait cond +Wait for another thread to notify @var{cond}, a condition variable. +This function will block until the condition is notified, or until a +signal is delivered to this thread using @code{thread-signal}. + +It is an error to call @code{condition-wait} without holding the +condition's associated mutex. + +@code{condition-wait} releases the associated mutex while waiting. +This allows other threads to acquire the mutex in order to notify the +condition. +@end defun + +@defun condition-notify cond &optional all +Notify @var{cond}. The mutex with @var{cond} must be held before +calling this. Ordinarily a single waiting thread is woken by +@code{condition-notify}; but if @var{all} is not @code{nil}, then all +threads waiting on @var{cond} are notified. + +@code{condition-notify} releases the associated mutex while waiting. +This allows other threads to acquire the mutex in order to wait on the +condition. +@c why bother? +@end defun + +@defun condition-name cond +Return the name of @var{cond}, as passed to +@code{make-condition-variable}. +@end defun + +@defun condition-mutex cond +Return the mutex associated with @var{cond}. Note that the associated +mutex cannot be changed. +@end defun diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index 1ba9ad9701f..b45e68d0d56 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -679,8 +679,7 @@ which quotes symbols with grave accent @t{`} and apostrophe @t{'}: @t{`like-this'} rather than @t{‘like-this’}. This older convention was designed for now-obsolete displays in which grave accent and apostrophe were mirror images. - -Documentation using either convention is converted to the user's +Documentation using this convention is converted to the user's preferred format when it is copied into a help buffer. @xref{Keys in Documentation}. diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 887643196cc..4936f7a921a 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -34,10 +34,12 @@ representing the variable. * Accessing Variables:: Examining values of variables whose names are known only at run time. * Setting Variables:: Storing new values in variables. +* Watching Variables:: Running a function when a variable is changed. * Variable Scoping:: How Lisp chooses among local and global values. * Buffer-Local Variables:: Variable values in effect only in one buffer. * File Local Variables:: Handling local variable lists in files. * Directory Local Variables:: Local variables common to all files in a directory. +* Connection Local Variables:: Local variables common for remote connections. * Variable Aliases:: Variables that are aliases for other variables. * Variables with Restricted Values:: Non-constant variables whose value can @emph{not} be an arbitrary Lisp object. @@ -777,6 +779,66 @@ error is signaled. @end example @end defun +@node Watching Variables +@section Running a function when a variable is changed. +@cindex variable watchpoints +@cindex watchpoints for Lisp variables + +It is sometimes useful to take some action when a variable changes its +value. The watchpoint facility provides the means to do so. Some +possible uses for this feature include keeping display in sync with +variable settings, and invoking the debugger to track down unexpected +changes to variables (@pxref{Variable Debugging}). + +The following functions may be used to manipulate and query the watch +functions for a variable. + +@defun add-variable-watcher symbol watch-function +This function arranges for @var{watch-function} to be called whenever +@var{symbol} is modified. Modifications through aliases +(@pxref{Variable Aliases}) will have the same effect. + +@var{watch-function} will be called with 4 arguments: (@var{symbol} +@var{newval} @var{operation} @var{where}). + +@var{symbol} is the variable being changed. +@var{newval} is the value it will be changed to. +@var{operation} is a symbol representing the kind of change, one of: +`set', `let', `unlet', `makunbound', and `defvaralias'. +@var{where} is a buffer if the buffer-local value of the variable is +being changed, nil otherwise. +@end defun + +@defun remove-variable-watch symbol watch-function +This function removes @var{watch-function} from @var{symbol}'s list of +watchers. +@end defun + +@defun get-variable-watchers symbol +This function returns the list of @var{symbol}'s active watcher +functions. +@end defun + +@subsection Limitations + +There are a couple of ways in which a variable could be modified (or at +least appear to be modified) without triggering a watchpoint. + +Since watchpoints are attached to symbols, modification to the +objects contained within variables (e.g., by a list modification +function @pxref{Modifying Lists}) is not caught by this mechanism. + +Additionally, C code can modify the value of variables directly, +bypassing the watchpoint mechanism. + +A minor limitation of this feature, again because it targets symbols, +is that only variables of dynamic scope may be watched. This poses +little difficulty, since modifications to lexical variables can be +discovered easily by inspecting the code within the scope of the +variable (unlike dynamic variables, which can be modified by any code +at all, @pxref{Variable Scoping}). + + @node Variable Scoping @section Scoping Rules for Variable Bindings @cindex scoping rule @@ -1666,7 +1728,7 @@ any form of file-local variable. For examples of why you might want to use this, @pxref{Auto Major Mode}. @end defvar -@defun hack-local-variables &optional mode-only +@defun hack-local-variables &optional handle-mode This function parses, and binds or evaluates as appropriate, any local variables specified by the contents of the current buffer. The variable @code{enable-local-variables} has its effect here. However, this @@ -1683,11 +1745,15 @@ is non-@code{nil}; it always calls the other hook. This function ignores a @samp{mode} element if it specifies the same major mode as the buffer already has. -If the optional argument @var{mode-only} is non-@code{nil}, then all -this function does is return a symbol specifying the major mode, -if the @w{@samp{-*-}} line or the local variables list specifies one, -and @code{nil} otherwise. It does not set the mode nor any other -file-local variable. +If the optional argument @var{handle-mode} is @code{t}, then all this +function does is return a symbol specifying the major mode, if the +@w{@samp{-*-}} line or the local variables list specifies one, and +@code{nil} otherwise. It does not set the mode or any other +file-local variable. If @var{handle-mode} has any value other than +@code{nil} or @code{t}, any settings of @samp{mode} in the +@w{@samp{-*-}} line or the local variables list are ignored, and the +other settings are applied. If @var{handle-mode} is @code{nil}, all +the file local variables are set. @end defun @defvar file-local-variables-alist @@ -1909,6 +1975,170 @@ may be useful for modes that want to ignore directory-locals while still respecting file-local variables (@pxref{File Local Variables}). @end defvar +@node Connection Local Variables +@section Connection Local Variables +@cindex connection local variables + + Connection-local variables provide a general mechanism for +different variable settings in buffers with a remote default +directory. They are bound and set depending on the remote connection +a buffer is dedicated to. Per default, they are set in all process +buffers for a remote connection, but they could be applied also in +other buffers with a remote directory. + +@defun connection-local-set-class-variables class variables +This function defines a set of variable settings for the named +@var{class}, which is a symbol. You can later assign the class to one +or more remote connections, and Emacs will apply those variable +settings to all process buffers for those connections. The list in +@var{variables} is an alist of the form @code{(@var{name} +. @var{value})}. Example: + +@example +@group +(connection-local-set-class-variables + 'remote-bash + '((shell-file-name . "/bin/bash") + (shell-command-switch . "-c") + (shell-interactive-switch . "-i") + (shell-login-switch . "-l"))) +@end group + +@group +(connection-local-set-class-variables + 'remote-ksh + '((shell-file-name . "/bin/ksh") + (shell-command-switch . "-c") + (shell-interactive-switch . "-i") + (shell-login-switch . "-l"))) +@end group + +@group +(connection-local-set-class-variables + 'remote-null-device + '((null-device . "/dev/null"))) +@end group +@end example +@end defun + +@defvar connection-local-class-alist +This alist holds the class symbols and the associated variable +settings. It is updated by @code{connection-local-set-class-variables}. +@end defvar + +@defun connection-local-set-classes criteria &rest classes +This function assigns @var{classes}, which are symbols, to all remote +connections identified by @var{criteria}. @var{criteria} is either a +regular expression identifying a remote server, or a function with one +argument @var{identification}, which must return non-nil when a remote +server shall apply @var{classes} variables, or @code{nil}. + +If @var{criteria} is a regexp, is must match the result of +@code{(file-remote-p default-directory)} of a buffer in order to apply +the variables setting. Example: + +@example +@group +(connection-local-set-classes + "^/ssh:" 'remote-bash 'remote-null-device) +@end group + +@group +(connection-local-set-classes + "^/sudo:" 'remote-ksh 'remote-null-device) +@end group +@end example + + If @var{criteria} is nil, it applies for all remote connections. +Therefore, the example above would be equivalent to + +@example +(connection-local-set-classes "^/ssh:" 'remote-bash) +(connection-local-set-classes "^/sudo:" 'remote-ksh) +(connection-local-set-classes nil 'remote-null-device) +@end example + + If @var{criteria} is a lambda function it must accept one parameter, +the identification. The example above could be rewritten as + +@example +@group +(connection-local-set-classes + (lambda (identification) + (string-equal (file-remote-p identification 'method) "ssh")) + 'remote-bash) +@end group + +@group +(connection-local-set-classes + (lambda (identification) + (string-equal (file-remote-p identification 'method) "sudo")) + 'remote-ksh) +@end group + +@group +(connection-local-set-classes + (lambda (identification) t) + 'remote-null-device) +@end group +@end example + + Thereafter, all the variable settings specified for @var{classes} +will be applied to any buffer with a matching remote directory, when +activated by @code{hack-connection-local-variables-apply}. Any class +of @var{classes} must have been already defined by +@code{connection-local-set-class-variables}. +@end defun + +@defvar connection-local-criteria-alist +This alist contains remote server identifications and their assigned +class names. The function @code{connection-local-set-classes} updates +this list. +@end defvar + +@defun hack-connection-local-variables +This function collects applicable connection-local variables in +@code{connection-local-variables-alist} that is local to the buffer, +without applying them. Whether a connection-local variable is +applicable is specified by the remote identifier of a buffer, +evaluated by @code{(file-remote-p default-directory)}. +@end defun + +@defun hack-connection-local-variables-apply +This function looks for connection-local variables, and immediately +applies them in the current buffer. It is called per default for +every process-buffer related to a remote connection. For other remote +buffers, it could be called by any mode. +@end defun + +@defmac with-connection-local-classes classes &rest body +All connection-local variables, which are specified by a class in +@var{classes}, are applied. An implicit binding of the classes to the +remote connection is enabled. + +After that, @var{body} is executed, and the connection-local variables +are unwound. Example: + +@example +@group +(connection-local-set-class-variables + 'remote-perl + '((perl-command-name . "/usr/local/bin/perl") + (perl-command-switch . "-e %s"))) +@end group + +@group +(with-connection-local-classes '(remote-perl) + do something useful) +@end group +@end example +@end defmac + +@defvar enable-connection-local-variables +If @code{nil}, connection-local variables are ignored. This variable +shall be changed temporarily only in special modes. +@end defvar + @node Variable Aliases @section Variable Aliases @cindex variable aliases diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 042e0cc35b6..4dc671c41f3 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -33,6 +33,8 @@ is displayed in windows. a specific window. * Quitting Windows:: How to restore the state prior to displaying a buffer. +* Side Windows:: Special windows on a frame's sides. +* Atomic Windows:: Preserving parts of the window layout. * Window Point:: Each window has its own location of point. * Window Start and End:: Buffer positions indicating which text is on-screen in a window. @@ -545,6 +547,12 @@ its pixel height is the pixel height of the screen areas spanned by its children. @end defun +@defun window-pixel-height-before-size-change &optional Lisp_Object &optional window +This function returns the height of window @var{window} in pixels at the +time @code{window-size-change-functions} was run for the last time on +@var{window}'s frame (@pxref{Window Hooks}). +@end defun + @cindex window pixel width @cindex pixel width of a window @cindex total pixel width of a window @@ -559,6 +567,12 @@ If @var{window} is an internal window, its pixel width is the width of the screen areas spanned by its children. @end defun +@defun window-pixel-width-before-size-change &optional Lisp_Object &optional window +This function returns the width of window @var{window} in pixels at the +time @code{window-size-change-functions} was run for the last time on +@var{window}'s frame (@pxref{Window Hooks}). +@end defun + @cindex full-width window @cindex full-height window The following functions can be used to determine whether a given @@ -1263,9 +1277,12 @@ Configurations}). @deffn Command delete-window &optional window This function removes @var{window} from display and returns @code{nil}. If @var{window} is omitted or @code{nil}, it defaults to -the selected window. If deleting the window would leave no more -windows in the window tree (e.g., if it is the only live window in the -frame), an error is signaled. +the selected window. + +If deleting the window would leave no more windows in the window tree +(e.g., if it is the only live window in the frame) or all remaining +windows on @var{window}'s frame are side windows (@pxref{Side Windows}), +an error is signaled. By default, the space taken up by @var{window} is given to one of its adjacent sibling windows, if any. However, if the variable @@ -1273,33 +1290,34 @@ adjacent sibling windows, if any. However, if the variable proportionally distributed among any remaining windows in the same window combination. @xref{Recombining Windows}. -The behavior of this function may be altered by the window parameters -of @var{window}, so long as the variable -@code{ignore-window-parameters} is @code{nil}. If the value of -the @code{delete-window} window parameter is @code{t}, this function -ignores all other window parameters. Otherwise, if the value of the -@code{delete-window} window parameter is a function, that function is -called with the argument @var{window}, in lieu of the usual action of -@code{delete-window}. Otherwise, this function obeys the -@code{window-atom} or @code{window-side} window parameter, if any. -@xref{Window Parameters}. +The behavior of this function may be altered by the window parameters of +@var{window}, so long as the variable @code{ignore-window-parameters} is +@code{nil}. If the value of the @code{delete-window} window parameter +is @code{t}, this function ignores all other window parameters. +Otherwise, if the value of the @code{delete-window} window parameter is +a function, that function is called with the argument @var{window}, in +lieu of the usual action of @code{delete-window}. @xref{Window +Parameters}. @end deffn @deffn Command delete-other-windows &optional window -This function makes @var{window} fill its frame, by deleting other -windows as necessary. If @var{window} is omitted or @code{nil}, it -defaults to the selected window. The return value is @code{nil}. - -The behavior of this function may be altered by the window parameters -of @var{window}, so long as the variable -@code{ignore-window-parameters} is @code{nil}. If the value of -the @code{delete-other-windows} window parameter is @code{t}, this -function ignores all other window parameters. Otherwise, if the value -of the @code{delete-other-windows} window parameter is a function, -that function is called with the argument @var{window}, in lieu of the -usual action of @code{delete-other-windows}. Otherwise, this function -obeys the @code{window-atom} or @code{window-side} window parameter, -if any. @xref{Window Parameters}. +This function makes @var{window} fill its frame, deleting other windows +as necessary. If @var{window} is omitted or @code{nil}, it defaults to +the selected window. An error is signaled if @var{window} is a side +window (@pxref{Side Windows}). The return value is @code{nil}. + +The behavior of this function may be altered by the window parameters of +@var{window}, so long as the variable @code{ignore-window-parameters} is +@code{nil}. If the value of the @code{delete-other-windows} window +parameter is @code{t}, this function ignores all other window +parameters. Otherwise, if the value of the @code{delete-other-windows} +window parameter is a function, that function is called with the +argument @var{window}, in lieu of the usual action of +@code{delete-other-windows}. @xref{Window Parameters}. + +Also, if @code{ignore-window-parameters} is @code{nil}, this function +does not delete any window whose @code{no-delete-other-window} parameter +is non-@code{nil}. @end deffn @deffn Command delete-windows-on &optional buffer-or-name frame @@ -2159,8 +2177,9 @@ This option does not affect non-interactive calls of @code{switch-to-buffer}. @end defopt -By default, @code{switch-to-buffer} shows the buffer at its position of -@code{point}. This behavior can be tuned using the following option. +By default, @code{switch-to-buffer} tries to preserve +@code{window-point}. This behavior can be tuned using the following +option. @defopt switch-to-buffer-preserve-window-point If this variable is @code{nil}, @code{switch-to-buffer} displays the @@ -2220,15 +2239,15 @@ This function makes @var{buffer-or-name} the current buffer and displays it in some window, preferably not the window currently selected. It then selects the displaying window. If that window is on a different graphical frame, that frame is given input focus if -possible (@pxref{Input Focus}). The return value is the buffer that -was switched to. +possible (@pxref{Input Focus}). If @var{buffer-or-name} is @code{nil}, it defaults to the buffer returned by @code{other-buffer} (@pxref{Buffer List}). If @var{buffer-or-name} is a string that is not the name of any existing buffer, this function creates a new buffer with that name; the new buffer's major mode is determined by the variable @code{major-mode} -(@pxref{Major Modes}). +(@pxref{Major Modes}). In any case, that buffer is made current and +returned, even when no suitable window was found to display it. If @var{action} is non-@code{nil}, it should be a display action to pass to @code{display-buffer} (@pxref{Choosing Window}). @@ -2403,6 +2422,23 @@ visible and, unless @var{alist} contains an @code{inhibit-switch-frame} entry (@pxref{Choosing Window Options}), raises that frame if necessary. @end defun +@defun display-buffer-reuse-mode-window buffer alist +This function tries to display @var{buffer} by finding a window +that is displaying a buffer in a given mode. + +If @var{alist} contains a @code{mode} entry, its value is a major mode +(a symbol) or a list of major modes. If @var{alist} contains no +@code{mode} entry, the current major mode of @var{buffer} is used. A +window is a candidate if it displays a buffer that derives from one of +the given modes. + +The behavior is also controlled by entries for +@code{inhibit-same-window}, @code{reusable-frames} and +@code{inhibit-switch-frame} as is done in the function +@code{display-buffer-reuse-window}. + +@end defun + @defun display-buffer-pop-up-frame buffer alist This function creates a new frame, and displays the buffer in that frame's window. It actually performs the frame creation by calling @@ -2494,10 +2530,17 @@ parameter; @pxref{Buffer Parameters}). @defun display-buffer-below-selected buffer alist This function tries to display @var{buffer} in a window below the -selected window. This means to either split the selected window or use -the window below the selected one. If it does create a new window, it -will also adjust its size provided @var{alist} contains a suitable +selected window. If there is a window below the selected one and that +window already displays @var{buffer}, it reuses that window. + +If there is no such window, this function tries to create a new window +by splitting the selected one and display @var{buffer} there. It will +also adjust that window's size provided @var{alist} contains a suitable @code{window-height} or @code{window-width} entry, see above. + +If splitting the selected window fails and there is a non-dedicated +window below the selected one showing some other buffer, it uses that +window for showing @var{buffer}. @end defun @defun display-buffer-in-previous-window buffer alist @@ -2537,7 +2580,12 @@ assumed that when the caller specifies a non-@code{nil} from @code{display-buffer} in this case. @end defun -To illustrate the use of action functions, consider the following +If the @var{alist} argument of any of these functions contains a +@code{window-parameters} entry, @code{display-buffer} assigns the +elements of the associated value as window parameters of the chosen +window. + + To illustrate the use of action functions, consider the following example. @example @@ -3031,6 +3079,428 @@ other frame on the same terminal. @end defopt +@node Side Windows +@section Side Windows +@cindex side windows +@cindex main window +@cindex main window of a frame + +Side windows are special windows positioned at any of the four sides of +a frame's root window (@pxref{Windows and Frames}). In practice, this +means that the area of the frame's root window is subdivided into a main +window and a number of side windows surrounding that main window. The +main window is either a ``normal'' live window or specifies the area +containing all the normal windows. + + In their most simple form of use, side windows allow to display +specific buffers always in the same area of a frame. Hence they can be +regarded as a generalization of the concept provided by +@code{display-buffer-at-bottom} (@pxref{Display Action Functions}) to +the remaining sides of a frame. With suitable customizations, however, +side windows can be also used to provide frame layouts similar to those +found in so-called integrated development environments (IDEs). + +@menu +* Displaying Buffers in Side Windows:: An action function for displaying + buffers in side windows. +* Side Window Options and Functions:: Further tuning of side windows. +* Frame Layouts with Side Windows:: Setting up frame layouts with side + windows. +@end menu + + +@node Displaying Buffers in Side Windows +@subsection Displaying Buffers in Side Windows + +The following action function for @code{display-buffer} (@pxref{Display +Action Functions}) creates or reuses a side window for displaying the +specified buffer. + +@defun display-buffer-in-side-window buffer alist +This function displays @var{buffer} in a side window of the selected +frame. It returns the window used for displaying @var{buffer}, +@code{nil} if no such window can be found or created. + +@var{alist} is an association list of symbols and values as for +@code{display-buffer}. The following symbols in @var{alist} are special +for this function: + +@table @code +@item side +Denotes the side of the frame where the window shall be located. Valid +values are @code{left}, @code{top}, @code{right} and @code{bottom}. If +unspecified, the window is located at the bottom of the frame. + +@item slot +Denotes a slot at the specified side where to locate the window. A +value of zero means to preferably position the window in the middle of +the specified side. A negative value means to use a slot preceding +(that is, above or on the left of) the middle slot. A positive value +means to use a slot following (that is, below or on the right of) the +middle slot. Hence, all windows on a specific side are ordered by their +@code{slot} value. If unspecified, the window is located in the middle +of the specified side. +@end table + +If you specify the same slot on the same side for two or more different +buffers, the buffer displayed last is shown in the corresponding window. +Hence, slots can be used for sharing the same side window between +buffers. + +This function installs the @code{window-side} and @code{window-slot} +parameters (@pxref{Window Parameters}) and makes them persistent. It +does not install any other window parameters unless they have been +explicitly provided via a @code{window-parameters} entry in @var{alist}. +@end defun + +By default, side windows cannot be split via @code{split-window} +(@pxref{Splitting Windows}). Also, a side window is not reused or split +by any buffer display action (@pxref{Display Action Functions}) unless +it is explicitly specified as target of that action. Note also that +@code{delete-other-windows} cannot make a side window the only window on +its frame (@pxref{Deleting Windows}). + + Once set up, side windows also change the behavior of the commands +@code{switch-to-prev-buffer} and @code{switch-to-next-buffer} +(@pxref{Window History}). In particular, these commands will refrain +from showing, in a side window, buffers that have not been displayed in +that window before. They will also refrain from having a normal, +non-side window show a buffer that has been already displayed in a side +window. A notable exception to the latter rule occurs when an +application, after displaying a buffer, resets that buffer's local +variables. + + +@node Side Window Options and Functions +@subsection Side Window Options and Functions + +The following options provide additional control over the placement of +side windows. + +@defopt window-sides-vertical +If non-@code{nil}, the side windows on the left and right of a frame +occupy the frame's full height. Otherwise, the side windows on the top +and bottom of the frame occupy the frame's full width. +@end defopt + +@defopt window-sides-slots +This option specifies the maximum number of side windows on each side of +a frame. The value is a list of four elements specifying the number of +side window slots on (in this order) the left, top, right and bottom of +each frame. If an element is a number, it means to display at most that +many windows on the corresponding side. If an element is @code{nil}, it +means there's no bound on the number of slots on that side. + +If any of the specified values is zero, no window can be created on the +corresponding side. @code{display-buffer-in-side-window} will not +signal an error in that case, but will return @code{nil}. If a specified +value just forbids the creation of an additional side window, the most +suitable window on that side is reused and may have its +@code{window-slot} parameter changed accordingly. +@end defopt + +@defopt window-sides-reversed +This option specifies whether top/bottom side windows should appear in +reverse order. When this is @code{nil}, side windows on the top and +bottom of a frame are always drawn from left to right with increasing +slot values. When this is @code{t}, the drawing order is reversed and +side windows on the top and bottom of a frame are drawn from right to +left with increasing slot values. + +When this is @code{bidi}, the drawing order is reversed if and only if +the value of @code{bidi-paragraph-direction} (@pxref{Bidirectional +Display}) is @code{right-to-left} in the buffer displayed in the window +most recently selected within the main window area of this frame. +Sometimes that window may be hard to find, so heuristics are used to +avoid that the drawing order changes inadvertently when another window +gets selected. + +The layout of side windows on the left or right of a frame is not +affected by the value of this variable. +@end defopt + +When a frame has side windows, the following function returns the main +window of that frame. + +@defun window-main-window &optional frame +This function returns the main window of the specified @var{frame}. The +optional argument @var{frame} must be a live frame and defaults to the +selected one. + +If @var{frame} has no side windows, it returns @var{frame}'s root +window. Otherwise, it returns either an internal non-side window such +that all other non-side windows on @var{frame} descend from it, or the +single live non-side window of @var{frame}. Note that the main window +of a frame cannot be deleted via @code{delete-window}. +@end defun + +The following command is handy to toggle the appearance of all side +windows on a specified frame. + +@deffn Command window-toggle-side-windows &optional frame +This command toggles side windows on the specified @var{frame}. The +optional argument @var{frame} must be a live frame and defaults to the +selected one. + +If @var{frame} has at least one side window, this command saves the +state of @var{frame}'s root window in the @var{frame}'s +@code{window-state} frame parameter and deletes all side windows on +@var{frame} afterwards. + +If @var{frame} has no side windows, but does have a @code{window-state} +parameter, this command uses that parameter's value to restore the side +windows on @var{frame} leaving @var{frame}'s main window alone. + +An error is signaled if @var{frame} has no side windows and no saved +state is found for it. +@end deffn + + +@node Frame Layouts with Side Windows +@subsection Frame Layouts with Side Windows + +Side windows can be used to create more complex frame layouts like those +provided by integrated development environments (IDEs). In such +layouts, the area of the main window is where the normal editing +activities take place. Side windows are not conceived for editing in +the usual sense. Rather, they are supposed to display information +complementary to the current editing activity, like lists of files, tags +or buffers, help information, search or grep results or shell output. + + The layout of such a frame might appear as follows: + +@smallexample +@group + ___________________________________ + | *Buffer List* | + |___________________________________| + | | | | + | * | | * | + | d | | T | + | i | | a | + | r | Main Window Area | g | + | e | | s | + | d | | * | + | * | | | + |_____|_______________________|_____| + | *help*/*grep*/ | *shell*/ | + | *Completions* | *compilation* | + |_________________|_________________| + | Echo Area | + |___________________________________| + + +@end group +@end smallexample + +The following example illustrates how window parameters (@pxref{Window +Parameters}) can be used with @code{display-buffer-in-side-window} +(@pxref{Displaying Buffers in Side Windows}) to set up code for +producing the frame layout sketched above. + +@example +@group +(defvar parameters + '(window-parameters . ((no-other-window . t) (no-delete-other-window . t)))) + +(setq fit-window-to-buffer-horizontally t) +(setq window-resize-pixelwise t) + +(setq + display-buffer-alist + `(("\\*Buffer List\\*" display-buffer-in-side-window + (side . top) (slot . 0) (window-height . fit-window-to-buffer) + (preserve-size . (nil . t)) ,parameters) + ("\\*Tags List\\*" display-buffer-in-side-window + (side . right) (slot . 0) (window-width . fit-window-to-buffer) + (preserve-size . (t . nil)) ,parameters) + ("\\*\\(?:help\\|grep\\|Completions\\)\\*" display-buffer-in-side-window + (side . bottom) (slot . -1) (preserve-size . (nil . t)) ,parameters) + ("\\*\\(?:shell\\|compilation\\)\\*" display-buffer-in-side-window + (side . bottom) (slot . 1) (preserve-size . (nil . t)) ,parameters))) +@end group +@end example + +This specifies @code{display-buffer-alist} entries (@pxref{Choosing +Window}) for buffers with fixed names. In particular, it asks for +showing @file{*Buffer List*} with adjustable height at the top of the +frame and @file{*Tags List*} with adjustable width on the frame's right. +It also asks for having the @file{*help*}, @file{*grep*} and +@file{*Completions*} buffers share a window on the bottom left side of +the frame and the @file{*shell*} and @file{*compilation*} buffers appear +in a window on the bottom right side of the frame. + + Note that the option @code{fit-window-to-buffer-horizontally} must +have a non-@code{nil} value in order to allow horizontal adjustment of +windows. Entries are also added that ask for preserving the height of +side windows at the top and bottom of the frame and the width of side +windows at the left or right of the frame. To assure that side windows +retain their respective sizes when maximizing the frame, the variable +@code{window-resize-pixelwise} is set to a non-@code{nil} value. +@xref{Resizing Windows}. + + The last form also makes sure that none of the created side windows +are accessible via @kbd{C-x o} by installing the @code{no-other-window} +parameter for each of these windows. In addition, it makes sure that +side windows are not deleted via @kbd{C-x 1} by installing the +@code{no-delete-other-window} parameter for each of these windows. + + Since @code{dired} buffers have no fixed names, we use a special +function @code{dired-default-directory-on-left} in order to display a +lean directory buffer on the left side of the frame. + +@example +@group +(defun dired-default-directory-on-left () + "Display `default-directory' in side window on left, hiding details." + (interactive) + (let ((buffer (dired-noselect default-directory))) + (with-current-buffer buffer (dired-hide-details-mode t)) + (display-buffer-in-side-window + buffer `((side . left) (slot . 0) + (window-width . fit-window-to-buffer) + (preserve-size . (t . nil)) ,parameters)))) +@end group +@end example + +Evaluating the preceding forms and typing, in any order, @w{@kbd{M-x +list-buffers}}, @kbd{C-h f}, @kbd{M-x shell}, @w{@kbd{M-x list-tags}}, +and @kbd{M-x dired-default-directory-on-left} should now reproduce the +frame layout sketched above. + + +@node Atomic Windows +@section Atomic Windows +@cindex atomic windows + +Atomic windows are rectangular compositions of at least two live +windows. They have the following distinctive characteristics: + +@itemize @bullet +@item +The function @code{split-window} (@pxref{Splitting Windows}), when +applied to a constituent of an atomic window, will try to create the new +window outside of the atomic window. + +@item +The function @code{delete-window} (@pxref{Deleting Windows}), when +applied to a constituent of an atomic window, will try to delete the +entire atomic window instead. + +@item +The function @code{delete-other-windows} (@pxref{Deleting Windows}), +when applied to a constituent of an atomic window, will try to make the +atomic window fill its frame or main window (@pxref{Side Windows}). +@end itemize + +This means that the basic groups of functions that alter the window +structure treat an atomic window like a live one, thus preserving the +internal structure of the atomic window. + + Atomic windows are useful to construct and preserve window layouts +that are meaningful only when all involved buffers are shown +simultaneously in a specific manner, such as when showing differences +between file revisions, or the same text in different languages or +markups. They can also be used to permanently display information +pertinent to a specific window in bars on that window's sides. + +@cindex root window of atomic window + Atomic windows are implemented with the help of the reserved +@code{window-atom} window parameter (@pxref{Window Parameters}) and an +internal window (@pxref{Basic Windows}) called the root window of the +atomic window. All windows that are part of the same atomic window have +this root window as their common ancestor and are assigned a +non-@code{nil} @code{window-atom} parameter. + + The following function returns the root of the atomic window a +specified window is part of: + +@defun window-atom-root &optional window +This functions returns the root of the atomic window @var{window} is a +part of. The specified @var{window} must be a valid window and defaults +to the selected one. It returns @code{nil} if @var{window} is not part +of an atomic window. +@end defun + +The most simple approach to make a new atomic window is to take an +existing internal window and apply the following function: + +@defun window-make-atom window +This function converts @var{window} into an atomic window. The +specified @var{window} must be an internal window. All this function +does is to set the @code{window-atom} parameter of each descendant of +@var{window} to @code{t}. +@end defun + +To create a new atomic window from an existing live window or to add a +new window to an existing atomic window, the following buffer display +action function (@pxref{Display Action Functions}) can be used: + +@defun display-buffer-in-atom-window buffer alist +This function tries to display @var{buffer} in a new window that will be +combined with an existing window to form an atomic window. If the +existing window is already part of an atomic window, it adds the new +window to that atomic window. + +The specified @var{alist} is an association list of symbols and values. +The following symbols have a special meaning: + +@table @code +@item window +The value of such an element specifies an existing window the new window +shall be combined with. If it specifies an internal window, all +children of that window become part of the atomic window too. If no +window is specified, the new window becomes a sibling of the selected +window. The @code{window-atom} parameter of the existing window is set +to @code{main} provided that window is live and its @code{window-atom} +parameter was not already set. + +@item side +The value of such an element denotes the side of the existing window +where the new window shall be located. Valid values are @code{below}, +@code{right}, @code{above} and @code{left}. The default is +@code{below}. The @code{window-atom} parameter of the new window is set +to this value. +@end table + +The return value is the new window, @code{nil} when creating that window +failed. +@end defun + +Note that the value of the @code{window-atom} parameter does not really +matter as long as it is non-@code{nil}. The values assigned by +@code{display-buffer-in-atom-window} just allow for easy retrieval of +the original and the new window after that function has been applied. +Note also that the @code{window-atom} parameter is the only window +parameter assigned by @code{display-buffer-in-atom-window}. Further +parameters have to be set by the application explicitly via a +@code{window-parameters} entry in @var{alist}. + + The following code snippet, when applied to a single-window frame, +first splits the selected window and makes the selected and the new +window constituents of an atomic window with their parent as root. It +then displays the buffer @file{*Messages*} in a new window at the +frame's bottom and makes that new window part of the atomic window just +created. + +@example +@group +(let ((window (split-window-right))) + (window-make-atom (window-parent window)) + (display-buffer-in-atom-window + (get-buffer-create "*Messages*") + `((window . ,(window-parent window)) (window-height . 5)))) +@end group +@end example + +At this moment typing @w{@kbd{C-x 2}} in any window of that frame +produces a new window at the bottom of the frame. Typing @w{@kbd{C-x +3}} instead will put the new window at the frame's right. In either +case, typing now @w{@kbd{C-x 1}} in any window of the atomic window will +remove the new window only. Typing @w{@kbd{C-x 0}} in any window of the +atomic window will make that new window fill the frame. + + @node Window Point @section Windows and Point @cindex window position @@ -4093,11 +4563,11 @@ was created for. The argument @var{configuration} must be a value that was previously returned by @code{current-window-configuration}. The configuration is restored in the frame from which @var{configuration} was made, whether -that frame is selected or not. This always counts as a window size -change and triggers execution of the @code{window-size-change-functions} -(@pxref{Window Hooks}), because @code{set-window-configuration} doesn't -know how to tell whether the new configuration actually differs from the -old one. +that frame is selected or not. In some rare cases this may trigger +execution of the @code{window-size-change-functions} (@pxref{Window +Hooks}) even if the size of windows did not change at all. The +@code{window-configuration-change-hook} functions will be called if and +only if at least one window was added to or deleted from the frame. If the frame from which @var{configuration} was saved is dead, all this function does is restore the three variables @code{window-min-height}, @@ -4205,6 +4675,25 @@ is @code{safe}, this means windows can get as small as one line and/or two columns. @end defun +The functions @code{window-state-get} and @code{window-state-put} also +allow to exchange the contents of two live windows. The following +function does precisely that: + +@deffn Command window-swap-states &optional window-1 window-2 size +This command swaps the states of the two live windows @var{window-1} and +@var{window-2}. @var{window-1} must specify a live window and defaults +to the selected one. @var{window-2} must specify a live window and +defaults to the window following @var{window-1} in the cyclic ordering +of windows, excluding minibuffer windows and including live windows on +all visible frames. + +Optional argument @var{size} non-@code{nil} means to try swapping the +sizes of @var{window-1} and @var{window-2} as well. A value of +@code{height} means to swap heights only, a value of @code{width} +means to swap widths only, while @code{t} means to swap both widths +and heights, if possible. Frames are not resized by this function. +@end deffn + @node Window Parameters @section Window Parameters @@ -4242,6 +4731,7 @@ earlier by @code{window-state-get}, all cloned windows have their parameters reset to @code{nil}. The following variable allows you to override the standard behavior: +@cindex persistent window parameters @defvar window-persistent-parameters This variable is an alist specifying which parameters get saved by @code{current-window-configuration} and @code{window-state-get}, and @@ -4271,9 +4761,10 @@ may fail with an @code{invalid-read-syntax} error. @end defvar Some functions (notably @code{delete-window}, -@code{delete-other-windows} and @code{split-window}), may behave specially -when their @var{window} argument has a parameter set. You can override -such special behavior by binding the following variable to a +@code{delete-other-windows} and @code{split-window}), may behave +specially when the window specified by their @var{window} argument has +a parameter whose name is equal to the function's name. You can +override such special behavior by binding the following variable to a non-@code{nil} value: @defvar ignore-window-parameters @@ -4300,6 +4791,10 @@ This parameter affects the execution of @code{delete-window} This parameter affects the execution of @code{delete-other-windows} (@pxref{Deleting Windows}). +@item @code{no-delete-other-window} +This parameter marks the window as not deletable by +@code{delete-other-windows} (@pxref{Deleting Windows}). + @item @code{split-window} This parameter affects the execution of @code{split-window} (@pxref{Splitting Windows}). @@ -4350,6 +4845,14 @@ The fourth element is the buffer whose display caused the creation of this parameter. @code{quit-restore-window} deletes the specified window only if it still shows that buffer. +@item @code{window-side} @code{window-slot} +These parameters are used for implementing side windows (@pxref{Side +Windows}). + +@item @code{window-atom} +This parameter is used for implementing atomic windows, see @ref{Atomic +Windows}. + @item @code{min-margins} The value of this parameter is a cons cell whose @sc{car} and @sc{cdr}, if non-@code{nil}, specify the minimum values (in columns) for the left @@ -4372,8 +4875,7 @@ applications. It might be replaced by an improved solution in future versions of Emacs. @end table -There are additional parameters @code{window-atom} and @code{window-side}; -these are reserved and should not be used by applications. +The @code{window-atom} parameter is used for implementing atomic windows. @node Window Hooks @@ -4405,33 +4907,38 @@ work. @end defvar @defvar window-size-change-functions -This variable holds a list of functions to be called if the size of -any window changes for any reason. The functions are called at the -beginning of a redisplay cycle, and just once for each frame on which -size changes have occurred. - -Each function receives the frame as its sole argument. There is no -direct way to find out which windows on that frame have changed size, or -precisely how. However, if a size-change function records, at each -call, the existing windows and their sizes, it can also compare the -present sizes and the previous sizes. - -Creating or deleting windows counts as a size change, and therefore -causes these functions to be called. Changing the frame size also -counts, because it changes the sizes of the existing windows. +This variable holds a list of functions to be called if the size of any +window changes for any reason. The functions are called once per +redisplay, and once for each frame on which size changes have occurred. + +Each function receives the frame as its sole argument. To find out +whether a specific window has changed size, compare the return values of +@code{window-pixel-width-before-size-change} and +@code{window-pixel-width} respectively +@code{window-pixel-height-before-size-change} and +@code{window-pixel-height} for that window (@pxref{Window Sizes}). + +These function are usually only called when at least one window was +added or has changed size since the last time this hook was run for the +associated frame. In some rare cases this hook also runs when a window +that was added intermittently has been deleted afterwards. In these +cases none of the windows on the frame will appear to have changed its +size. You may use @code{save-selected-window} in these functions (@pxref{Selecting Windows}). However, do not use @code{save-window-excursion} (@pxref{Window Configurations}); exiting -that macro counts as a size change, which would cause these functions -to be called over and over. +that macro counts as a size change, which would cause these functions to +be called again. @end defvar @defvar window-configuration-change-hook -A normal hook that is run every time you change the window configuration -of an existing frame. This includes splitting or deleting windows, -changing the sizes of windows, or displaying a different buffer in a -window. +A normal hook that is run every time the window configuration of a frame +changes. Window configuration changes include splitting and deleting +windows and the display of a different buffer in a window. Resizing the +frame or individual windows do not count as configuration changes. Use +@code{window-size-change-functions}, see above, when you want to track +size changes that are not caused by the deletion or creation of windows. The buffer-local part of this hook is run once for each window on the affected frame, with the relevant window selected and its buffer diff --git a/doc/man/emacs.1.in b/doc/man/emacs.1.in index 3b1566f6caa..73bc38d7984 100644 --- a/doc/man/emacs.1.in +++ b/doc/man/emacs.1.in @@ -123,11 +123,13 @@ Use specified as the terminal instead of using stdin/stdout. This must be the first argument specified in the command line. .TP -.B \-\-daemon +.BI \-\-daemon "\fR[=\fPname\fR]" Start Emacs as a daemon, enabling the Emacs server and disconnecting -from the terminal. You can then use the emacsclient command to -connect to the server (see -.BR emacsclient (1)). +from the terminal. You can then use the emacsclient (see +.BR emacsclient (1)) +command to +connect to the server (with optional +.IR name ")." .TP .B \-\-version Display diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index 4dffeafb1d2..eca74a0c645 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -218,7 +218,6 @@ gnus.pdf: $(gnus_deps) cp gnustmppdf.pdf $@ rm gnustmppdf.* -${buildinfodir}/tramp.info tramp.html: EXTRA_OPTS = -D emacs ${buildinfodir}/tramp.info tramp.html: ${srcdir}/trampver.texi diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index 2d95fb824fc..4f7711184d0 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -338,14 +338,15 @@ Line-Up Functions * Comment Line-Up:: * Misc Line-Up:: + Customizing Macros * Macro Backslashes:: * Macros with ;:: +* Noise Macros:: @end detailmenu @end menu - @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @node Introduction, Overview, Top, Top @comment node-name, next, previous, up @@ -6657,15 +6658,18 @@ Because a macro can expand into anything at all, near where one is invoked @ccmode{} can only indent and fontify code heuristically. Sometimes it gets it wrong. Usually you should try to design your macros so that they ''look like ordinary code'' when you invoke them. -However, one situation is so common that @ccmode{} handles it +However, two situations are so common that @ccmode{} handles them specially: that is when certain macros needn't (or mustn't) be -followed by a @samp{;}. You need to configure @ccmode{} to handle -these macros properly, see @ref{Macros with ;}. +followed by a @samp{;}, and when certain macros (or compiler +directives) expand to nothing. You need to configure @ccmode{} to +handle these macros properly, see @ref{Macros with ;} and @ref{Noise +Macros}. @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @menu * Macro Backslashes:: * Macros with ;:: +* Noise Macros:: @end menu @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @@ -6717,7 +6721,7 @@ get aligned only when you explicitly invoke the command @end defopt @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -@node Macros with ;, , Macro Backslashes, Custom Macros +@node Macros with ;, Noise Macros, Macro Backslashes, Custom Macros @comment node-name, next, previous, up @section Macros with semicolons @cindex macros with semicolons @@ -6726,9 +6730,11 @@ Macros which needn't (or mustn't) be followed by a semicolon when you invoke them, @dfn{macros with semicolons}, are very common. These can cause @ccmode{} to parse the next line wrongly as a @code{statement-cont} (@pxref{Function Symbols}) and thus mis-indent -it. +it. At the top level, a macro invocation before a defun start can +cause, for example, @code{c-beginning-of-defun} (@kbd{C-M-a}) not to +find the correct start of the current function. -You can prevent this by specifying which macros have semicolons. It +You can prevent these by specifying which macros have semicolons. It doesn't matter whether or not such a macro has a parameter list: @defopt c-macro-names-with-semicolon @@ -6766,10 +6772,65 @@ example: @defun c-make-macro-with-semi-re @findex make-macro-with-semi-re (c-) Call this (non-interactive) function, which sets internal variables, -each time you change the value of -@code{c-macro-names-with-semicolon}. It takes no arguments, and its +each time you change the value of @code{c-macro-names-with-semicolon} +after the major mode function has run. It takes no arguments, and its return value has no meaning. This function is called by @ccmode{}'s -initialization code. +initialization code, after the mode hooks have run. +@end defun + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Noise Macros, , Macros with ;, Custom Macros +@comment node-name, next, previous, up +@section Noise Macros +@cindex noise macros +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +In @ccmode{}, @dfn{noise macros} are macros which expand to nothing, +or compiler directives (such as GCC's @code{__attribute__}) which play +no part in the syntax of the C (etc.) language. Some noise macros are +followed by arguments in parentheses (possibly optionally), others +are not. + +Noise macros can easily confuse @ccmode{}'s analysis of function +headers, causing them to be mis-fontified, or even mis-indented. You +can prevent this confusion by specifying the identifiers which +constitute noise macros. + +@defopt c-noise-macro-names +@vindex noise-macro-names (c-) +This variable is a list of names of noise macros which never have +parenthesized arguments. Each element is a string, and must be a +valid identifier. An element in @code{c-noise-macro-names} must not +also be in @code{c-noise-macro-with-parens-names}. Such an element is +treated as whitespace by @ccmode{}. +@end defopt + +@defopt c-noise-macro-with-parens-names +@vindex noise-macro-with-parens-names (c-) +This variable is a list of names of noise macros which optionally have +arguments in parentheses. Each element of the list is a string, and +must be a valid identifier. An element in +@code{c-noise-macro-with-parens-names} must not also be in +@code{c-noise-macro-names}. For performance reasons, such an element, +together with the optional parenthesized arguments, is specially +handled, but it is only handled when used in declaration +contexts@footnote{If this restriction causes your project +difficulties, please get in touch with @email{bug-cc-mode@@gnu.org}.}. + +The two compiler directives @code{__attribute__} and @code{__declspec} +have traditionally been handled specially in @ccmode{}; for example +they are fontified with font-lock-keyword-face. You don't need to +include these directives in @code{c-noise-macro-with-parens-names}, +but doing so is OK. +@end defopt + +@defun c-make-noise-macro-regexps +@findex make-noise-macro-regexps (c-) +Call this (non-interactive) function, which sets internal variables, +on changing the value of @code{c-noise-macro-names} or +@code{c-noise-macro-with-parens-names} after the major mode's function +has run. This function is called by @ccmode{}'s initialization code, +after the mode hooks have run. @end defun @comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 75a83602fa3..5af41a4465e 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -1491,7 +1491,7 @@ for a description of type specifiers. For example, (cl-typecase x (integer (munch-integer x)) (float (munch-float x)) - (string (munch-integer (string-to-int x))) + (string (munch-integer (string-to-number x))) (t (munch-anything x))) @end example diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi index 474dd0a5208..7ac5bc6b53b 100644 --- a/doc/misc/dired-x.texi +++ b/doc/misc/dired-x.texi @@ -369,6 +369,18 @@ and @code{dired-texinfo-unclean-extensions}. If non-@code{nil}, a list of extensions (strings) to omit from Dired listings. Its format is the same as that of @code{completion-ignored-extensions}. +@vindex dired-omit-case-fold +@item dired-omit-case-fold + +Default: @code{filesystem} + +By default, when @code{dired-omit-case-fold} is set to @code{filesystem}, +@code{dired-omit-mode} will match filenames and extensions +case-sensitively on Dired buffers visiting case-sensitive filesystems, +and case-insensitively on case-insensitive filesystems. Set it to +@code{nil} to be always case-sensitive, and to @code{t} to be always +case-insensitive. + @vindex dired-omit-localp @item dired-omit-localp @@ -711,6 +723,9 @@ variable @code{window-min-height}. Mark all files with a certain extension for use in later commands. A @samp{.} is not automatically prepended to the string entered, you must type it explicitly. +If invoked with prefix argument @kbd{C-u}, this command unmark files instead. +If called with the @kbd{C-u C-u} prefix, asks for a character to use +as the marker, and marks files with it. When called from Lisp, @var{extension} may also be a list of extensions and an optional argument @var{marker-char} specifies the marker used. diff --git a/doc/misc/emacs-gnutls.texi b/doc/misc/emacs-gnutls.texi index 1a850c68235..9d52508b644 100644 --- a/doc/misc/emacs-gnutls.texi +++ b/doc/misc/emacs-gnutls.texi @@ -173,7 +173,7 @@ Just use @code{open-protocol-stream} or @code{open-network-stream} You should not have to use the @file{gnutls.el} functions directly. But you can test them with @code{open-gnutls-stream}. -@defun open-gnutls-stream name buffer host service +@defun open-gnutls-stream name buffer host service &optional nowait This function creates a buffer connected to a specific @var{host} and @var{service} (port number or service name). The parameters and their syntax are the same as those given to @code{open-network-stream} @@ -181,6 +181,10 @@ syntax are the same as those given to @code{open-network-stream} Manual}). The connection process is called @var{name} (made unique if necessary). This function returns the connection process. +The @var{nowait} parameter means that the socket should be +asynchronous, and the connection process will be returned to the +caller before TLS negotiation has happened. + @lisp ;; open a HTTPS connection (open-gnutls-stream "tls" "tls-buffer" "yourserver.com" "https") @@ -191,6 +195,12 @@ necessary). This function returns the connection process. @end defun +@findex gnutls-asynchronous-parameters +If called with @var{nowait}, the process is returned immediately +(before connecting to the server). In that case, the process object +is told what parameters to use when negotiating the connection +by using the @code{gnutls-asynchronous-parameters} function. + The function @code{gnutls-negotiate} is not generally useful and it may change as needed, so please see @file{gnutls.el} for the details. diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi index 4d68246bba4..9389435faf1 100644 --- a/doc/misc/emacs-mime.texi +++ b/doc/misc/emacs-mime.texi @@ -1536,6 +1536,9 @@ Here's a bunch of time/date/second/day examples: (date-to-time "Sat Sep 12 12:21:54 1998 +0200") @result{} (13818 19266) +(parse-iso8601-time-string "1998-09-12T12:21:54+0200") +@result{} (13818 19266) + (float-time '(13818 19266)) @result{} 905595714.0 @@ -1826,6 +1829,11 @@ matching types. @vindex mailcap-mime-data This variable is an alist of alists containing backup viewing rules. +@item mailcap-user-mime-data +@vindex mailcap-user-mime-data +A customizable list of viewers that take preference over +@code{mailcap-mime-data}. + @end table Interface functions: diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi index 7726a8d3dc4..ea258634301 100644 --- a/doc/misc/eww.texi +++ b/doc/misc/eww.texi @@ -97,6 +97,12 @@ and the web page is rendered in it. You can leave EWW by pressing web page hit @kbd{g} (@code{eww-reload}). Pressing @kbd{w} (@code{eww-copy-page-url}) will copy the current URL to the kill ring. +@findex eww-open-in-new-buffer +@kindex M-RET + The @kbd{M-RET} command (@code{eww-open-in-new-buffer}) opens the +URL at point in a new EWW buffer, akin to opening a link in a new +``tab'' in other browsers. + @findex eww-readable @kindex R The @kbd{R} command (@code{eww-readable}) will attempt to determine @@ -109,6 +115,12 @@ only display this part. This usually gets rid of menus and the like. The @kbd{F} command (@code{eww-toggle-fonts}) toggles whether to use variable-pitch fonts or not. This sets the @code{shr-use-fonts} variable. +@findex eww-toggle-colors +@findex shr-use-colors +@kindex F + The @kbd{C} command (@code{eww-toggle-colors}) toggles whether to use +HTML-specified colors or not. This sets the @code{shr-use-colors} variable. + @findex eww-download @vindex eww-download-directory @kindex d @@ -158,12 +170,16 @@ You can view stored bookmarks with @kbd{B} (@code{eww-list-bookmarks}). This will open the bookmark buffer @file{*eww bookmarks*}. +@findex eww-switch-to-buffer @findex eww-list-buffers +@kindex s @kindex S @cindex Multiple Buffers To get summary of currently opened EWW buffers, press @kbd{S} (@code{eww-list-buffers}). The @file{*eww buffers*} buffer allows you -to quickly kill, flip through and switch to specific EWW buffer. +to quickly kill, flip through and switch to specific EWW buffer. To +switch EWW buffers through a minibuffer prompt, press @kbd{s} +(@code{eww-switch-to-buffer}). @findex eww-browse-with-external-browser @vindex shr-external-browser diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi index 1c4644bba14..6cece30a986 100644 --- a/doc/misc/flymake.texi +++ b/doc/misc/flymake.texi @@ -323,12 +323,6 @@ file cannot be run simultaneously. If any changes are made to the buffer, syntax check is automatically started after @code{flymake-no-changes-timeout} seconds. -@item flymake-gui-warnings-enabled -A boolean flag indicating whether Flymake will show message boxes for -non-recoverable errors. If @code{flymake-gui-warnings-enabled} is -@code{nil}, these errors will only be logged to the @file{*Messages*} -buffer. - @item flymake-start-syntax-check-on-newline A boolean flag indicating whether to start syntax check after a newline character is added to the buffer. @@ -697,7 +691,8 @@ The command line (command name and the list of arguments) for launching a proces initialization function. Flymake then just calls @code{start-process} to start an asynchronous process and configures a process filter and sentinel, which are used for processing the output of the syntax check -tool. +tool. When exiting Emacs, running Flymake processes will be killed +without prompting the user. @node Parsing the output @section Parsing the output diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index 11f9f35227d..393787c33a3 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -828,6 +828,7 @@ Various * Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email. * Spam Package:: A package for filtering and processing spam. * The Gnus Registry:: A package for tracking messages by Message-ID. +* The Gnus Cloud:: A package for synchronizing Gnus marks. * Other modes:: Interaction with other modes. * Various Various:: Things that are really various. @@ -5042,11 +5043,12 @@ access the @code{X-Newsreader} header: @item @vindex gnus-ignored-from-addresses -The @code{gnus-ignored-from-addresses} variable says when the @samp{%f} -summary line spec returns the @code{To}, @code{Newsreader} or -@code{From} header. If this regexp matches the contents of the -@code{From} header, the value of the @code{To} or @code{Newsreader} -headers are used instead. +The @code{gnus-ignored-from-addresses} variable says when the +@samp{%f} summary line spec returns the @code{To}, @code{Newsreader} +or @code{From} header. The variable may be a regexp or a predicate +function. If this matches the contents of the @code{From} +header, the value of the @code{To} or @code{Newsreader} headers are +used instead. To distinguish regular articles from those where the @code{From} field has been swapped, a string is prefixed to the @code{To} or @@ -14654,7 +14656,7 @@ an additional mail source for a particular group by including the @code{group} mail specifier in @code{mail-sources}, and setting a @code{mail-source} group parameter (@pxref{Group Parameters}) specifying a single mail source. When this is used, @code{mail-sources} is -typically just @code{(group)}; the @code{mail-source} parameter for a +typically just @code{((group))}; the @code{mail-source} parameter for a group might look like this: @lisp @@ -22207,6 +22209,7 @@ to you, using @kbd{G b u} and updating the group will usually fix this. * Thwarting Email Spam:: Simple ways to avoid unsolicited commercial email. * Spam Package:: A package for filtering and processing spam. * The Gnus Registry:: A package for tracking messages by Message-ID. +* The Gnus Cloud:: A package for synchronizing Gnus marks. * Other modes:: Interaction with other modes. * Various Various:: Things that are really various. @end menu @@ -26165,6 +26168,100 @@ default this is just @code{(marks)} so the custom registry marks are precious. @end defvar +@node The Gnus Cloud +@section The Gnus Cloud +@cindex cloud +@cindex gnus-cloud +@cindex synchronization +@cindex sync +@cindex synch + +The Gnus Cloud is a way to synchronize marks and general files and +data across multiple machines. + +Very often, you want all your marks (what articles you've read, which +ones were important, and so on) to be synchronized between several +machines. With IMAP, that's built into the protocol, so you can read +nnimap groups from many machines and they are automatically +synchronized. But NNTP, nnrss, and many other backends do not store +marks, so you have to do it locally. + +The Gnus Cloud package stores the marks, plus any files you choose, on +an IMAP server in a special folder. It's like a +DropTorrentSyncBoxOakTree(TM). + +@menu +* Gnus Cloud Setup:: +* Gnus Cloud Usage:: +@end menu + +@node Gnus Cloud Setup +@subsection Gnus Cloud Setup + +Setting up the Gnus Cloud takes less than a minute. From the Group +buffer: + +Press @kbd{^} to go to the Server buffer. Here you'll see all the +servers that Gnus knows. @xref{Server Buffer}. + +Then press @kbd{i} to mark any servers as cloud-synchronized (their marks are synchronized). + +Then press @kbd{I} to mark a single server as the cloud host (it must +be an IMAP server, and will host a special IMAP folder with all the +synchronization data). This will set the variable +@code{gnus-cloud-method} (using the Customize facilities), then ask +you to optionally upload your first CloudSynchronizationDataPack(TM). + +@node Gnus Cloud Usage +@subsection Gnus Cloud Usage + +After setting up, you can use these shortcuts from the Group buffer: + +@table @kbd +@item ~ RET +@item ~ d +@findex gnus-cloud-download-all-data +@cindex cloud, download +Download the latest Gnus Cloud data. + +@item ~ u +@item ~ ~ +@findex gnus-cloud-upload-all-data +@cindex cloud, download +Upload the local Gnus Cloud data. Creates a new +CloudSynchronizationDataPack(TM). + +@end table + +But wait, there's more. Of course there's more. So much more. You can +customize all of the following. + +@defvar gnus-cloud-synced-files +These are the files that will be part of every +CloudSynchronizationDataPack(TM). They are included in every upload, +so don't synchronize a lot of large files. Files under 100Kb are best. +@end defvar + +@defvar gnus-cloud-storage-method +This is a choice from several storage methods. It's highly recommended +to use the EPG facilities. It will be automatic if have GnuPG +installed and EPG loaded. Otherwise, you could use Base64+gzip, +Base64, or no encoding. +@end defvar + +@defvar gnus-cloud-interactive +When this is set, and by default it is, the Gnus Cloud package will +ask you for confirmation here and there. Leave it on until you're +comfortable with the package. +@end defvar + + +@defvar gnus-cloud-method +The name of the IMAP server to store the +CloudSynchronizationDataPack(TM)s. It's easiest to set this from the +Server buffer (@pxref{Gnus Cloud Setup}). +@end defvar + @node Other modes @section Interaction with other modes diff --git a/doc/misc/htmlfontify.texi b/doc/misc/htmlfontify.texi index 20cde7124d1..9cb1d6f4317 100644 --- a/doc/misc/htmlfontify.texi +++ b/doc/misc/htmlfontify.texi @@ -126,7 +126,8 @@ entities, so you should even be able to do html-within-html fontified display. You should, however, note that random control or non-ASCII characters -such as ^L (\x0c) or ¤ (\xa4) won't get mapped yet. +such as ^L (U+000C FORM FEED (FF)) or ¤ (U+00A4 CURRENCY SIGN) won't +get mapped yet. If the @var{srcdir} and @var{file} arguments are set, lookup etags derived entries in the @ref{hfy-tags-cache} and add html anchors diff --git a/doc/misc/message.texi b/doc/misc/message.texi index 0b82f343d71..6ec761506d0 100644 --- a/doc/misc/message.texi +++ b/doc/misc/message.texi @@ -67,7 +67,6 @@ Message mode buffers. * Interface:: Setting up message buffers. * Commands:: Commands you can execute in message mode buffers. * Variables:: Customizing the message buffers. -* Compatibility:: Making Message backwards compatible. * Appendices:: More technical things. * GNU Free Documentation License:: The license for this documentation. * Index:: Variable, function and concept index. @@ -185,8 +184,9 @@ 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) will be removed from the -@code{Cc} header. A value of @code{nil} means exclude your name only. +expression (or list of regular expressions or a predicate function) +will be removed from the @code{Cc} header. A value of @code{nil} means +exclude your name only. @vindex message-prune-recipient-rules @code{message-prune-recipient-rules} is used to prune the addresses @@ -1678,10 +1678,10 @@ trailing old subject. In this case, @item message-alternative-emails @vindex message-alternative-emails -Regexp matching alternative email addresses. 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. +Regexp or predicate function matching alternative email addresses. +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. For example, if you have two secondary email addresses john@@home.net and john.doe@@work.com and want to use them in the From field when @@ -2592,22 +2592,6 @@ An @dfn{action} can be either: a normal function, or a list where the a form to be @code{eval}ed. -@node Compatibility -@chapter Compatibility -@cindex compatibility - -Message uses virtually only its own variables---older @code{mail-} -variables aren't consulted. To force Message to take those variables -into account, you can put the following in your @file{.emacs} file: - -@lisp -(require 'messcompat) -@end lisp - -This will initialize many Message variables from the values in the -corresponding mail variables. - - @node Appendices @chapter Appendices diff --git a/doc/misc/sc.texi b/doc/misc/sc.texi index 1f7b73dd73b..80512292c32 100644 --- a/doc/misc/sc.texi +++ b/doc/misc/sc.texi @@ -775,18 +775,6 @@ MUA calls @code{sc-cite-original} at the right time. As mentioned above, some MUAs handle this differently. Read the sections that follow pertaining to the MUAs you are using. -@vindex sc-load-hook -@vindex load-hook (sc-) -@vindex sc-pre-hook -@vindex pre-hook (sc-) -One final note. After Supercite is loaded into your Emacs session, it -runs the hook @code{sc-load-hook}. You can put any customizations into -this hook since it is only run once. This will not work, however, if -your Emacs maintainer has put Supercite into your dumped Emacs image. -In that case, you can use the @code{sc-pre-hook} variable, but this will -get executed every time @code{sc-cite-original} is called. @xref{Reply -Buffer Initialization}. - @node Replying and Yanking @chapter Replying and Yanking @@ -964,8 +952,6 @@ reset certain variables set in @code{sc-pre-hook}. @cindex gin-mode @findex sc-setup-filladapt @findex setup-filladapt (sc-) -@vindex sc-load-hook -@vindex load-hook (sc-) Supercite will automatically fill newly cited text from the original message unless the variable @code{sc-auto-fill-region-p} has a @@ -979,7 +965,8 @@ two best known are @dfn{filladapt} and @dfn{gin-mode}. Both work well with Supercite and both are available at the normal Emacs Lisp archive sites. @dfn{gin-mode} works pretty well out of the box, but if you use @dfn{filladapt}, you may want to run the function -@code{sc-setup-filladapt} from your @code{sc-load-hook}. This simply +@code{sc-setup-filladapt} after loading @file{supercite} +(e.g., using @code{with-eval-after-load}). This simply makes @dfn{filladapt} a little more Supercite savvy than its default setup. diff --git a/doc/misc/ses.texi b/doc/misc/ses.texi index 58f9ba8ccf3..ba10be9bfa5 100644 --- a/doc/misc/ses.texi +++ b/doc/misc/ses.texi @@ -187,6 +187,14 @@ the end-points, e.g.: (The @code{apply} is necessary because @code{ses-range} produces a @emph{list} of values. This allows for more complex possibilities.) +Alternatively you can use the @code{!} modifier of @code{ses-range} to +remove blank cells from the returned list, which allows to use +@code{+} instead of @code{ses+}: + +@lisp +(apply '+ (ses-range A2 A5 !)) +@end lisp + @c =================================================================== @node The Basics @@ -374,26 +382,62 @@ Undo previous action (@code{(undo)}). @cindex printer functions @cindex cell formatting @cindex formatting cells -@findex ses-read-cell-printer -@findex ses-read-column-printer -@findex ses-read-default-printer -@findex ses-define-local-printer -@findex ses-center -@findex ses-center-span -@findex ses-dashfill -@findex ses-dashfill-span -@findex ses-tildefill-span - Printer functions convert binary cell values into the print forms that Emacs will display on the screen. -A printer can be a format string, like @samp{"$%.2f"}. The result +@menu +* Various kinds of printer functions:: +* Configuring what printer function applies:: +* Standard printer functions:: +* Local printer functions:: +* Writing a lambda printer function:: +@end menu + +@node Various kinds of printer functions +@subsection Various kinds of printer functions + +When configuring what printer function applies (@pxref{Configuring +what printer function applies}), you can enter a printer function as +one of the following: + +@itemize +@item +A format string, like @samp{"$%.2f"}. The result string is right-aligned within the print cell. To get left-alignment, -use parentheses: @samp{("$%.2f")}. A printer can also be a -one-argument function (a symbol or a lambda), whose result is a string -(right-aligned) or list of one string (left-aligned). While typing in -a lambda, you can use @kbd{M-@key{TAB}} to complete the names of symbols. +use parentheses: @samp{("$%.2f")}. +@item +A printer can also be a one-argument function, the result of which is +a string (right-aligned) or list of one string (left-aligned). Such a +function can be in turn configured as: +@itemize +@item +A lambda expression, for instance: + +@lisp +(lambda (x) + (cond + ((null x) "") + ((numberp x) (format "%.2f" x)) + (t (ses-center-span x ?# 'ses-prin1)))) +@end lisp + +While typing in a lambda, you can use @kbd{M-@key{TAB}} to complete +the names of symbols. +@item +A symbol referring to a standard printer function (@pxref{Standard +printer functions}). +@item +A symbol referring to a local printer function (@pxref{Local printer +functions}). +@end itemize + + +@end itemize + + +@node Configuring what printer function applies +@subsection Configuring what printer function applies Each cell has a printer. If @code{nil}, the column-printer for the cell's column is used. If that is also @code{nil}, the default-printer for the @@ -401,25 +445,35 @@ spreadsheet is used. @table @kbd @item p +@findex ses-read-cell-printer Enter a printer for current cell or range (@code{ses-read-cell-printer}). @item M-p +@findex ses-read-column-printer Enter a printer for the current column (@code{ses-read-column-printer}). @item C-c C-p +@findex ses-read-default-printer Enter the default printer for the spreadsheet (@code{ses-read-default-printer}). @end table -The @code{ses-read-@r{XXX}-printer} commands have their own minibuffer -history, which is preloaded with the set of all printers used in this -spreadsheet, plus the standard printers. +The @code{ses-read-@var{xxx}-printer} commands have their own +minibuffer history, which is preloaded with the set of all printers +used in this spreadsheet, plus the standard printers (@pxref{Standard +printer functions}) and the local printers (@pxref{Local printer +functions}). -The standard printers are suitable only for cells, not columns or -default, because they format the value using the column-printer (or -default-printer if @code{nil}) and then center the result: +@node Standard printer functions +@subsection Standard printer functions -@table @code + +Except for @code{ses-prin1}, the other standard printers are suitable +only for cells, not columns or default, because they format the value +using the column-printer (or default-printer if @code{nil}) and then +center the result: + +@ftable @code @item ses-center Just centering. @@ -434,8 +488,16 @@ Centering with dashes and spill-over. @item ses-tildefill-span Centering with tildes (~) and spill-over. -@end table +@item ses-prin1 +This is the fallback printer, used when calling the configured printer +throws some error. +@end ftable + +@node Local printer functions +@subsection Local printer functions + +@findex ses-define-local-printer You can define printer function local to a sheet with the command @code{ses-define-local-printer}. For instance, define a printer @samp{foo} to @code{"%.2f"}, and then use symbol @samp{foo} as a @@ -444,6 +506,113 @@ printer function. Then, if you call again @code{"%.3f"}, all the cells using printer @samp{foo} will be reprinted accordingly. +Sometimes there are local printers that you want to define or +re-define automatically every time you open a sheet. For instance +imagine that you want to define/re-define automatically a local +printer @code{euro} to display a number like an amount of euros, that +is to say number @code{3.1} would be displayed as +@code{3.10@dmn{}@euro{}}. To do so in any non read-only SES buffer, +you can add some code like this to your @file{.emacs} init file: + +@lisp +(defun my-ses-mode-hook () + (unless buffer-read-only + (ses-define-local-printer + 'euro + (lambda (x) + (cond + ((null x) "") + ((numberp x) (format "%.2f€" x)) + (t (ses-center-span x ?# 'ses-prin1))))))) +(add-hook 'ses-mode-hook 'my-ses-mode-hook) +@end lisp + +If you replace command @code{ses-define-local-printer} by function +@code{ses-define-if-new-local-printer} +@findex ses-define-if-new-local-printer +the definition will occur only if a local printer with the same name +in not already defined. + + +@node Writing a lambda printer function +@subsection Writing a lambda printer function + +You can write a printer function with a lambda expression taking one +argument in two cases: + +@itemize +@item +when you configure the printer function applying to a cell or column, or +@item +when you define a local printer function with command +@code{ses-define-local-printer}. +@end itemize + +When doing so, please take care that the returned value is a string, +or a list containing a string, even when the input argument has an +unexpected value. Here is an example: + +@example +(lambda (val) + (cond + ((null val) "") + ((and (numberp val) (>= val 0)) (format "%.1f" val)) + (t (ses-center-span val ?# 'ses-prin1)))) +@end example + +This example will: + +@itemize +@item +When the cell is empty (ie.@: when @code{val} is @code{nil}), print an +empty string @code{""} +@item +When the cell value is a non negative number, format the the value in +fixed-point notation with one decimal after point +@item +Otherwise, handle the value as erroneous by printing it as an +s-expression (using @code{ses-prin1}), centered and surrounded by +@code{#} filling. +@end itemize + +Another precaution to take is to avoid stack overflow due to a +printer function calling itself indefinitely. This mistake can +happen when you use a local printer as a column printer, +and this local printer implicitly calls the current column printer, so it +will call itself recursively. Imagine for instance that you want to +create some local printer @code{=fill} that would center the content +of a cell and surround it by equal signs @code{=}, and you do it this +way: + +@lisp +(lambda (x) + (cond + ((null x) "") + (t (ses-center x 0 ?=)))) +@end lisp + +Because @code{=fill} uses the standard printer @code{ses-center} without +explicitly passing any printer to it, @code{ses-center} will call the +current column printer if any, or the spreadsheet default printer +otherwise. So using @code{=fill} as a column printer will result in a +stack overflow in this column. SES does not check for that; +you just have to be careful. For instance, re-write @code{=fill} like +this: + +@lisp +(lambda (x) + (cond + ((null x) "") + ((stringp x) (ses-center x 0 ?= " %s ")) + (t (ses-center-span x ?# 'ses-prin1)))) +@end lisp + +The code above applies the @code{=} filling only to strings; it also +surrounds the string by one space on each side before filling with +@code{=} signs. So the string @samp{Foo} will be displayed like @samp{@w{=== +Foo ===}} in an 11 character wide column. Anything other than an empty cell +or a non-string is displayed as an error by using @code{#} filling. + @node Clearing cells @section Clearing cells @cindex clearing commands @@ -595,8 +764,8 @@ Pops up a menu to set the current row as the header, or revert to column letters. @item M-x ses-rename-cell @findex ses-rename-cell -Rename a cell from a standard A1-like name to any -string. +Rename a cell from a standard A1-like name to any string that can be a +valid local variable name (See also @ref{Nonrelocatable references}). @item M-x ses-repair-cell-reference-all @findex ses-repair-cell-reference-all When you interrupt a cell formula update by clicking @kbd{C-g}, then @@ -791,8 +960,17 @@ are some useful functions to call from your formulas: @table @code @item (ses-delete-blanks &rest @var{args}) -Returns a list from which all blank cells (value is either @code{nil} or -'*skip*) have been deleted. +Returns a list from which all blank cells (value is either @code{nil} +or '*skip*) have been deleted. Order of args is reverted. Please note +that @code{ses-range} has a @code{!} modifier that allows to remove +blanks, so it is possible to write: +@lisp +(ses-range A1 A5 !) +@end lisp +instead of +@lisp +(apply 'ses-delete-blanks (ses-range A1 A5 <)) +@end lisp @item (ses+ &rest @var{args}) Sum of non-blank arguments. @@ -842,9 +1020,10 @@ this to undo the effect of @kbd{t}. @end table When a printer function signals an error, the fallback printer -@samp{"%s"} is substituted. This is useful when your column printer +@findex ses-prin1 +@code{ses-prin1} is substituted. This is useful when your column printer is numeric-only and you use a string as a cell value. Note that the -standard default printer is ``%.7g'' which is numeric-only, so cells +standard default printer is @samp{"%.7g"} which is numeric-only, so cells that are empty of contain strings will use the fallback printer. @kbd{c} on such cells will display ``Format specifier doesn't match argument type''. @@ -986,7 +1165,18 @@ can type ahead without worrying about the glitch. @kbd{C-u C-y} relocates none of the cell-references. What about mixed cases? -You can use +The best way is to rename cells that you do not want to be relocatable +by using @code{ses-rename-cell}. +@findex ses-rename-cell +Cells that do not have an A1-like name style are not relocated on +yank. Using this method, the concerned cells won't be relocated +whatever formula they appear in. Please note however that when a +formula contains some range @code{(ses-range @var{cell1} @var{cell2})} +then in the yanked formula each range bound @var{cell1} and +@var{cell2} are relocated, or not, independently, depending on whether +they are A1-like or renamed. + +An alternative method is to use @lisp (symbol-value 'B3) @end lisp @@ -994,7 +1184,8 @@ to make an @dfn{absolute reference}. The formula relocator skips over quoted things, so this will not be relocated when pasted or when rows/columns are inserted/deleted. However, B3 will not be recorded as a dependency of this cell, so this cell will not be updated -automatically when B3 is changed. +automatically when B3 is changed, this is why using +@code{ses-rename-cell} is most of the time preferable. The variables @code{row} and @code{col} are dynamically bound while a cell formula is being evaluated. You can use @@ -1011,12 +1202,13 @@ kind of dependency is also not recorded. @findex ses-reconstruct-all Begins with an 014 character, followed by sets of cell-definition -macros for each row, followed by column-widths, column-printers, +macros for each row, followed by the set of local printer +definitions, followed by column-widths, column-printers, default-printer, and header-row. Then there's the global parameters -(file-format ID, numrows, numcols) and the local variables (specifying -@acronym{SES} mode for the buffer, etc.). +(file-format ID, row count, column count, local printer count) and the +local variables (specifying @acronym{SES} mode for the buffer, etc.). -When a @acronym{SES} file is loaded, first the numrows and numcols values are +When a @acronym{SES} file is loaded, first the global parameters are loaded, then the entire data area is @code{eval}ed, and finally the local variables are processed. diff --git a/doc/misc/speedbar.texi b/doc/misc/speedbar.texi index d43c521f76a..27b57c0a03a 100644 --- a/doc/misc/speedbar.texi +++ b/doc/misc/speedbar.texi @@ -1030,7 +1030,7 @@ it is not provided, you can derive it like this: (progn (beginning-of-line) (looking-at "^\\([0-9]+\\):") - (setq depth (string-to-int (match-string 1))))) + (setq depth (string-to-number (match-string 1))))) @end example @noindent diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex index 37e2de896ec..c8913ab918e 100644 --- a/doc/misc/texinfo.tex +++ b/doc/misc/texinfo.tex @@ -3,7 +3,7 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2016-04-14.07} +\def\texinfoversion{2016-09-18.18} % % Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, @@ -67,6 +67,10 @@ \everyjob{\message{[Texinfo version \texinfoversion]}% \catcode`+=\active \catcode`\_=\active} +% LaTeX's \typeout. This ensures that the messages it is used for +% are identical in format to the corresponding ones from latex/pdflatex. +\def\typeout{\immediate\write17}% + \chardef\other=12 % We never want plain's \outer definition of \+ in Texinfo. @@ -858,36 +862,6 @@ where each line of input produces a line of output.} \temp } -% @| inserts a changebar to the left of the current line. It should -% surround any changed text. This approach does *not* work if the -% change spans more than two lines of output. To handle that, we would -% have adopt a much more difficult approach (putting marks into the main -% vertical list for the beginning and end of each change). This command -% is not documented, not supported, and doesn't work. -% -\def\|{% - % \vadjust can only be used in horizontal mode. - \leavevmode - % - % Append this vertical mode material after the current line in the output. - \vadjust{% - % We want to insert a rule with the height and depth of the current - % leading; that is exactly what \strutbox is supposed to record. - \vskip-\baselineskip - % - % \vadjust-items are inserted at the left edge of the type. So - % the \llap here moves out into the left-hand margin. - \llap{% - % - % For a thicker or thinner bar, change the `1pt'. - \vrule height\baselineskip width1pt - % - % This is the space between the bar and the text. - \hskip 12pt - }% - }% -} - % @include FILE -- \input text of FILE. % \def\include{\parseargusing\filenamecatcodes\includezzz} @@ -1104,9 +1078,14 @@ where each line of input produces a line of output.} % For LuaTeX % +\newif\iftxiuseunicodedestname +\txiuseunicodedestnamefalse % For pdfTeX etc. + \ifx\luatexversion\thisisundefined \else - % Escape PDF strings UTF-8 to UTF-16 + % Use Unicode destination names + \txiuseunicodedestnametrue + % Escape PDF strings with converting UTF-16 from UTF-8 \begingroup \catcode`\%=12 \directlua{ @@ -1134,7 +1113,24 @@ where each line of input produces a line of output.} end } \endgroup - \def\pdfescapestring#1{\directlua{UTF16oct('\luaescapestring{#1}')}} + \def\pdfescapestrutfsixteen#1{\directlua{UTF16oct('\luaescapestring{#1}')}} + % Escape PDF strings without converting + \begingroup + \directlua{ + function PDFescstr(str) + for c in string.bytes(str) do + if c <= 0x20 or c >= 0x80 or c == 0x28 or c == 0x29 or c == 0x5c then + tex.sprint( + string.format(string.char(0x5c) .. string.char(0x25) .. '03o', + c)) + else + tex.sprint(string.char(c)) + end + end + end + } + \endgroup + \def\pdfescapestring#1{\directlua{PDFescstr('\luaescapestring{#1}')}} \ifnum\luatexversion>84 % For LuaTeX >= 0.85 \def\pdfdest{\pdfextension dest} @@ -1188,12 +1184,21 @@ where each line of input produces a line of output.} \ifx\pdfescapestring\thisisundefined % No primitive available; should we give a warning or log? % Many times it won't matter. + \xdef#1{#1}% \else % The expandable \pdfescapestring primitive escapes parentheses, % backslashes, and other special chars. \xdef#1{\pdfescapestring{#1}}% \fi } +\def\txiescapepdfutfsixteen#1{% + \ifx\pdfescapestrutfsixteen\thisisundefined + % No UTF-16 converting macro available. + \txiescapepdf{#1}% + \else + \xdef#1{\pdfescapestrutfsixteen{#1}}% + \fi +} \newhelp\nopdfimagehelp{Texinfo supports .png, .jpg, .jpeg, and .pdf images with PDF output, and none of those formats could be found. (.eps cannot @@ -1303,17 +1308,77 @@ output) for that.)} \pdfrefximage \pdflastximage \fi} % - \def\pdfmkdest#1{{% + \def\setpdfdestname#1{{% % We have to set dummies so commands such as @code, and characters % such as \, aren't expanded when present in a section title. \indexnofonts - \turnoffactive \makevalueexpandable + \turnoffactive + \iftxiuseunicodedestname + \ifx \declaredencoding \latone + % Pass through Latin-1 characters. + % LuaTeX with byte wise I/O converts Latin-1 characters to Unicode. + \else + \ifx \declaredencoding \utfeight + % Pass through Unicode characters. + \else + % Use ASCII approximations in destination names. + \passthroughcharsfalse + \fi + \fi + \else + % Use ASCII approximations in destination names. + \passthroughcharsfalse + \fi \def\pdfdestname{#1}% \txiescapepdf\pdfdestname - \safewhatsit{\pdfdest name{\pdfdestname} xyz}% }} % + \def\setpdfoutlinetext#1{{% + \indexnofonts + \makevalueexpandable + \turnoffactive + \ifx \declaredencoding \latone + % The PDF format can use an extended form of Latin-1 in bookmark + % strings. See Appendix D of the PDF Reference, Sixth Edition, for + % the "PDFDocEncoding". + \passthroughcharstrue + % Pass through Latin-1 characters. + % LuaTeX: Convert to Unicode + % pdfTeX: Use Latin-1 as PDFDocEncoding + \def\pdfoutlinetext{#1}% + \else + \ifx \declaredencoding \utfeight + \ifx\luatexversion\thisisundefined + % For pdfTeX with UTF-8. + % TODO: the PDF format can use UTF-16 in bookmark strings, + % but the code for this isn't done yet. + % Use ASCII approximations. + \passthroughcharsfalse + \def\pdfoutlinetext{#1}% + \else + % For LuaTeX with UTF-8. + % Pass through Unicode characters for title texts. + \passthroughcharstrue + \def\pdfoutlinetext{#1}% + \fi + \else + % For non-Latin-1 or non-UTF-8 encodings. + % Use ASCII approximations. + \passthroughcharsfalse + \def\pdfoutlinetext{#1}% + \fi + \fi + % LuaTeX: Convert to UTF-16 + % pdfTeX: Use Latin-1 as PDFDocEncoding + \txiescapepdfutfsixteen\pdfoutlinetext + }} + % + \def\pdfmkdest#1{% + \setpdfdestname{#1}% + \safewhatsit{\pdfdest name{\pdfdestname} xyz}% + } + % % used to mark target names; must be expandable. \def\pdfmkpgn#1{#1} % @@ -1341,23 +1406,13 @@ output) for that.)} % page number. We could generate a destination for the section % text in the case where a section has no node, but it doesn't % seem worth the trouble, since most documents are normally structured. - { - \ifx\luatexversion\thisisundefined \else - \turnoffactive % LuaTeX can use Unicode strings for PDF - \fi - \edef\pdfoutlinedest{#3}% - \ifx\pdfoutlinedest\empty - \def\pdfoutlinedest{#4}% - \else - \txiescapepdf\pdfoutlinedest - \fi - % - % Also escape PDF chars in the display string. - \edef\pdfoutlinetext{#1}% - \txiescapepdf\pdfoutlinetext - % - \pdfoutline goto name{\pdfmkpgn{\pdfoutlinedest}}#2{\pdfoutlinetext}% - } + \setpdfoutlinetext{#1} + \setpdfdestname{#3} + \ifx\pdfdestname\empty + \def\pdfdestname{#4}% + \fi + % + \pdfoutline goto name{\pdfmkpgn{\pdfdestname}}#2{\pdfoutlinetext}% } % \def\pdfmakeoutlines{% @@ -1515,72 +1570,132 @@ output) for that.)} % % For XeTeX % -\newif\iftxiuseunicodedestname \ifx\XeTeXrevision\thisisundefined \else % % XeTeX version check % - \ifnum\strcmp{\the\XeTeXversion\XeTeXrevision}{0.99995}>-1 - % XeTeX 0.99995+ contains xdvipdfmx 20160307+. - % It can handle Unicode destination name for PDF. + \ifnum\strcmp{\the\XeTeXversion\XeTeXrevision}{0.99996}>-1 + % TeX Live 2016 contains XeTeX 0.99996 and xdvipdfmx 20160307. + % It can use the `dvipdfmx:config' special (from TeX Live SVN r40941). + % For avoiding PDF destination name replacement, we use this special + % instead of xdvipdfmx's command line option `-C 0x0010'. + \special{dvipdfmx:config C 0x0010} + % XeTeX 0.99995+ comes with xdvipdfmx 20160307+. + % It can handle Unicode destination names for PDF. \txiuseunicodedestnametrue \else - % XeTeX < 0.99995 can not handle Unicode destination name for PDF - % because xdvipdfmx 20150315 has UTF-16 convert issue. - % It fixed by xdvipdfmx 20160106 (TeX Live SVN r39753). + % XeTeX < 0.99996 (TeX Live < 2016) cannot use the + % `dvipdfmx:config' special. + % So for avoiding PDF destination name replacement, + % xdvipdfmx's command line option `-C 0x0010' is necessary. + % + % XeTeX < 0.99995 can not handle Unicode destination names for PDF + % because xdvipdfmx 20150315 has a UTF-16 conversion issue. + % It is fixed by xdvipdfmx 20160106 (TeX Live SVN r39753). \txiuseunicodedestnamefalse \fi % + % Color support + % + \def\rgbDarkRed{0.50 0.09 0.12} + \def\rgbBlack{0 0 0} + % + \def\pdfsetcolor#1{\special{pdf:scolor [#1]}} + % + % Set color, and create a mark which defines \thiscolor accordingly, + % so that \makeheadline knows which color to restore. + \def\setcolor#1{% + \xdef\lastcolordefs{\gdef\noexpand\thiscolor{#1}}% + \domark + \pdfsetcolor{#1}% + } + % + \def\maincolor{\rgbBlack} + \pdfsetcolor{\maincolor} + \edef\thiscolor{\maincolor} + \def\lastcolordefs{} + % + \def\makefootline{% + \baselineskip24pt + \line{\pdfsetcolor{\maincolor}\the\footline}% + } + % + \def\makeheadline{% + \vbox to 0pt{% + \vskip-22.5pt + \line{% + \vbox to8.5pt{}% + % Extract \thiscolor definition from the marks. + \getcolormarks + % Typeset the headline with \maincolor, then restore the color. + \pdfsetcolor{\maincolor}\the\headline\pdfsetcolor{\thiscolor}% + }% + \vss + }% + \nointerlineskip + } + % % PDF outline support % - \pdfmakepagedesttrue \relax - % Emulate the primitive of pdfTeX + % Emulate pdfTeX primitive \def\pdfdest name#1 xyz{% - \special{pdf:dest (name#1) [@thispage /XYZ @xpos @ypos]}% + \special{pdf:dest (#1) [@thispage /XYZ @xpos @ypos null]}% } - \def\pdfmkdest#1{{% + % + \def\setpdfdestname#1{{% % We have to set dummies so commands such as @code, and characters % such as \, aren't expanded when present in a section title. \indexnofonts + \makevalueexpandable + \turnoffactive \iftxiuseunicodedestname - \def\pdfdestname{#1}% Pass through Unicode characters. + % Pass through Unicode characters. \else - \edef\pdfdestname{#1}% Replace Unicode characters to ASCII. + % Use ASCII approximations in destination names. + \passthroughcharsfalse \fi - \turnoffactive - \makevalueexpandable + \def\pdfdestname{#1}% \txiescapepdf\pdfdestname - \safewhatsit{\pdfdest name{\pdfdestname} xyz}% }} % + \def\setpdfoutlinetext#1{{% + \turnoffactive + % Always use Unicode characters in title texts. + \def\pdfoutlinetext{#1}% + % For XeTeX, xdvipdfmx converts to UTF-16. + % So we do not convert. + \txiescapepdf\pdfoutlinetext + }} + % + \def\pdfmkdest#1{% + \setpdfdestname{#1}% + \safewhatsit{\pdfdest name{\pdfdestname} xyz}% + } + % + % by default, use black for everything. + \def\urlcolor{\rgbBlack} + \def\linkcolor{\rgbBlack} + \def\endlink{\setcolor{\maincolor}\pdfendlink} + % \def\dopdfoutline#1#2#3#4{% - \iftxiuseunicodedestname - \def\pdfoutlinedest{#3}% Pass through Unicode characters. - \else - \edef\pdfoutlinedest{#3}% Replace Unicode characters to ASCII. - \fi - \ifx\pdfoutlinedest\empty - \def\pdfoutlinedest{#4}% + \setpdfoutlinetext{#1} + \setpdfdestname{#3} + \ifx\pdfdestname\empty + \def\pdfdestname{#4}% \fi - { - \turnoffactive - \txiescapepdf\pdfoutlinedest - \edef\pdfoutlinetext{#1}% - \txiescapepdf\pdfoutlinetext - % - \special{pdf:out [-] #2 << /Title (\pdfoutlinetext) /A - << /S /GoTo /D (name\pdfoutlinedest) >> >> }% - } + % + \special{pdf:out [-] #2 << /Title (\pdfoutlinetext) /A + << /S /GoTo /D (\pdfdestname) >> >> }% } % \def\pdfmakeoutlines{% \begingroup % - % In the case of XeTeX, counts of subentries is not necesary. - % Therefore, read toc only once. + % For XeTeX, counts of subentries are not necessary. + % Therefore, we read toc only once. % - % We use the node names as the destinations. + % We use node names as destinations. \def\partentry##1##2##3##4{}% ignore parts in the outlines \def\numchapentry##1##2##3##4{% \dopdfoutline{##1}{1}{##3}{##4}}% @@ -1600,7 +1715,7 @@ output) for that.)} \let\unnsubsecentry\numsubsecentry% \let\unnsubsubsecentry\numsubsubsecentry% % - % In the case of XeTeX, xdvipdfmx converts strings to UTF-16. + % For XeTeX, xdvipdfmx converts strings to UTF-16. % Therefore, the encoding and the language may not be considered. % \indexnofonts @@ -1622,9 +1737,9 @@ output) for that.)} \special{pdf:docview << /PageMode /UseOutlines >> } % ``\special{pdf:tounicode ...}'' is not necessary % because xdvipdfmx converts strings from UTF-8 to UTF-16 without it. - % However, due to UTF-16 convert issue of xdvipdfmx 20150315, - % ``\special{pdf:dest ...}'' can not handle non-ASCII strings. - % It fixed by xdvipdfmx 20160106 (TeX Live SVN r39753). + % However, due to a UTF-16 conversion issue of xdvipdfmx 20150315, + % ``\special{pdf:dest ...}'' cannot handle non-ASCII strings. + % It is fixed by xdvipdfmx 20160106 (TeX Live SVN r39753). % \def\skipspaces#1{\def\PP{#1}\def\D{|}% \ifx\PP\D\let\nextsp\relax @@ -1684,7 +1799,7 @@ output) for that.)} {\noexpand\pdflink{\the\toksC}}\toksC={}\global\countA=0} \def\pdflink#1{% \special{pdf:bann << /Border [0 0 0] - /Type /Annot /Subtype /Link /A << /S /GoTo /D (name#1) >> >>}% + /Type /Annot /Subtype /Link /A << /S /GoTo /D (#1) >> >>}% \setcolor{\linkcolor}#1\endlink} \def\done{\edef\st{\global\noexpand\toksA={\the\toksB}}\st} % @@ -1696,7 +1811,7 @@ output) for that.)} \def\xeteximagewidth{#2}\setbox0 = \hbox{\ignorespaces #2}% \def\xeteximageheight{#3}\setbox2 = \hbox{\ignorespaces #3}% % - % XeTeX (and the PDF format) support .pdf, .png, .jpg (among + % XeTeX (and the PDF format) supports .pdf, .png, .jpg (among % others). Let's try in that order, PDF first since if % someone has a scalable image, presumably better to use that than a % bitmap. @@ -1740,40 +1855,9 @@ output) for that.)} } \fi -\message{fonts,} - -% Change the current font style to #1, remembering it in \curfontstyle. -% For now, we do not accumulate font styles: @b{@i{foo}} prints foo in -% italics, not bold italics. -% -\def\setfontstyle#1{% - \def\curfontstyle{#1}% not as a control sequence, because we are \edef'd. - \csname ten#1\endcsname % change the current font -} -% Select #1 fonts with the current style. % -\def\selectfonts#1{\csname #1fonts\endcsname \csname\curfontstyle\endcsname} - -\def\rm{\fam=0 \setfontstyle{rm}} -\def\it{\fam=\itfam \setfontstyle{it}} -\def\sl{\fam=\slfam \setfontstyle{sl}} -\def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf} -\def\tt{\fam=\ttfam \setfontstyle{tt}} - -% Unfortunately, we have to override this for titles and the like, since -% in those cases "rm" is bold. Sigh. -\def\rmisbold{\rm\def\curfontstyle{bf}} - -% Texinfo sort of supports the sans serif font style, which plain TeX does not. -% So we set up a \sf. -\newfam\sffam -\def\sf{\fam=\sffam \setfontstyle{sf}} -\let\li = \sf % Sometimes we call it \li, not \sf. - -% We don't need math for this font style. -\def\ttsl{\setfontstyle{ttsl}} - +\message{fonts,} % Set the baselineskip to #1, and the lineskip and strut size % correspondingly. There is no deep meaning behind these magic numbers @@ -2124,8 +2208,8 @@ end \setfont\deftt\ttshape{10}{\magstep1}{OT1TT} \setfont\defsl\slshape{10}{\magstep1}{OT1TT} \setfont\defttsl\ttslshape{10}{\magstep1}{OT1TT} -\def\df{\let\tentt=\deftt \let\tenbf = \defbf -\let\tenttsl=\defttsl \let\tensl=\defsl \bf} +\def\df{\let\ttfont=\deftt \let\bffont = \defbf +\let\ttslfont=\defttsl \let\slfont=\defsl \bf} % Fonts for indices, footnotes, small examples (9pt). \def\smallnominalsize{9pt} @@ -2212,7 +2296,7 @@ end \font\ssecsy=cmsy10 scaled 1315 \def\ssececsize{1200} -% Reduced fonts for @acro in text (10pt). +% Reduced fonts for @acronym in text (10pt). \def\reducednominalsize{10pt} \setfont\reducedrm\rmshape{10}{1000}{OT1} \setfont\reducedtt\ttshape{10}{1000}{OT1TT} @@ -2258,8 +2342,8 @@ end \setfont\deftt\ttshape{10}{\magstephalf}{OT1TT} \setfont\defsl\slshape{10}{\magstephalf}{OT1TT} \setfont\defttsl\ttslshape{10}{\magstephalf}{OT1TT} -\def\df{\let\tentt=\deftt \let\tenbf = \defbf -\let\tensl=\defsl \let\tenttsl=\defttsl \bf} +\def\df{\let\ttfont=\deftt \let\bffont = \defbf +\let\slfont=\defsl \let\ttslfont=\defttsl \bf} % Fonts for indices, footnotes, small examples (9pt). \def\smallnominalsize{9pt} @@ -2345,7 +2429,7 @@ end \font\ssecsy=cmsy10 \def\ssececsize{1000} -% Reduced fonts for @acro in text (9pt). +% Reduced fonts for @acronym in text (9pt). \def\reducednominalsize{9pt} \setfont\reducedrm\rmshape{9}{1000}{OT1} \setfont\reducedtt\ttshape{9}{1000}{OT1TT} @@ -2365,6 +2449,12 @@ end \rm } % end of 10pt text font size definitions, \definetextfontsizex +% Fonts for short table of contents. +\setfont\shortcontrm\rmshape{12}{1000}{OT1} +\setfont\shortcontbf\bfshape{10}{\magstep1}{OT1} % no cmb12 +\setfont\shortcontsl\slshape{12}{1000}{OT1} +\setfont\shortconttt\ttshape{12}{1000}{OT1TT} + % We provide the user-level command % @fonttextsize 10 @@ -2391,20 +2481,47 @@ end \endgroup } +% +% Change the current font style to #1, remembering it in \curfontstyle. +% For now, we do not accumulate font styles: @b{@i{foo}} prints foo in +% italics, not bold italics. +% +\def\setfontstyle#1{% + \def\curfontstyle{#1}% not as a control sequence, because we are \edef'd. + \csname #1font\endcsname % change the current font +} + +\def\rm{\fam=0 \setfontstyle{rm}} +\def\it{\fam=\itfam \setfontstyle{it}} +\def\sl{\fam=\slfam \setfontstyle{sl}} +\def\bf{\fam=\bffam \setfontstyle{bf}}\def\bfstylename{bf} +\def\tt{\fam=\ttfam \setfontstyle{tt}} + +% Texinfo sort of supports the sans serif font style, which plain TeX does not. +% So we set up a \sf. +\newfam\sffam +\def\sf{\fam=\sffam \setfontstyle{sf}} + +% We don't need math for this font style. +\def\ttsl{\setfontstyle{ttsl}} + + % 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. % \def\resetmathfonts{% - \textfont0=\tenrm \textfont1=\teni \textfont2=\tensy - \textfont\itfam=\tenit \textfont\slfam=\tensl \textfont\bffam=\tenbf - \textfont\ttfam=\tentt \textfont\sffam=\tensf + \textfont0=\rmfont \textfont1=\ifont \textfont2=\syfont + \textfont\itfam=\itfont \textfont\slfam=\slfont \textfont\bffam=\bffont + \textfont\ttfam=\ttfont \textfont\sffam=\sffont } -% The font-changing commands redefine the meanings of \tenSTYLE, instead -% of just \STYLE. We do this because \STYLE needs to also set the -% current \fam for math mode. Our \STYLE (e.g., \rm) commands hardwire -% \tenSTYLE to set the current font. +% + +% The font-changing commands (all called \...fonts) redefine the meanings +% of \STYLEfont, instead of just \STYLE. We do this because \STYLE needs +% to also set the current \fam for math mode. Our \STYLE (e.g., \rm) +% commands hardwire \STYLEfont to set the current font. % % Each font-changing command also sets the names \lsize (one size lower) % and \lllsize (three sizes lower). These relative commands are used @@ -2412,78 +2529,63 @@ end % % This all needs generalizing, badly. % -\def\textfonts{% - \let\tenrm=\textrm \let\tenit=\textit \let\tensl=\textsl - \let\tenbf=\textbf \let\tentt=\texttt \let\smallcaps=\textsc - \let\tensf=\textsf \let\teni=\texti \let\tensy=\textsy - \let\tenttsl=\textttsl - \def\curfontsize{text}% - \def\lsize{reduced}\def\lllsize{smaller}% - \resetmathfonts \setleading{\textleading}} -\def\titlefonts{% - \let\tenrm=\titlerm \let\tenit=\titleit \let\tensl=\titlesl - \let\tenbf=\titlebf \let\tentt=\titlett \let\smallcaps=\titlesc - \let\tensf=\titlesf \let\teni=\titlei \let\tensy=\titlesy - \let\tenttsl=\titlettsl - \def\curfontsize{title}% - \def\lsize{chap}\def\lllsize{subsec}% - \resetmathfonts \setleading{27pt}} -\def\titlefont#1{{\titlefonts\rmisbold #1}} -\def\chapfonts{% - \let\tenrm=\chaprm \let\tenit=\chapit \let\tensl=\chapsl - \let\tenbf=\chapbf \let\tentt=\chaptt \let\smallcaps=\chapsc - \let\tensf=\chapsf \let\teni=\chapi \let\tensy=\chapsy - \let\tenttsl=\chapttsl - \def\curfontsize{chap}% - \def\lsize{sec}\def\lllsize{text}% - \resetmathfonts \setleading{19pt}} -\def\secfonts{% - \let\tenrm=\secrm \let\tenit=\secit \let\tensl=\secsl - \let\tenbf=\secbf \let\tentt=\sectt \let\smallcaps=\secsc - \let\tensf=\secsf \let\teni=\seci \let\tensy=\secsy - \let\tenttsl=\secttsl - \def\curfontsize{sec}% - \def\lsize{subsec}\def\lllsize{reduced}% - \resetmathfonts \setleading{17pt}} -\def\subsecfonts{% - \let\tenrm=\ssecrm \let\tenit=\ssecit \let\tensl=\ssecsl - \let\tenbf=\ssecbf \let\tentt=\ssectt \let\smallcaps=\ssecsc - \let\tensf=\ssecsf \let\teni=\sseci \let\tensy=\ssecsy - \let\tenttsl=\ssecttsl - \def\curfontsize{ssec}% - \def\lsize{text}\def\lllsize{small}% - \resetmathfonts \setleading{15pt}} -\let\subsubsecfonts = \subsecfonts -\def\reducedfonts{% - \let\tenrm=\reducedrm \let\tenit=\reducedit \let\tensl=\reducedsl - \let\tenbf=\reducedbf \let\tentt=\reducedtt \let\reducedcaps=\reducedsc - \let\tensf=\reducedsf \let\teni=\reducedi \let\tensy=\reducedsy - \let\tenttsl=\reducedttsl - \def\curfontsize{reduced}% - \def\lsize{small}\def\lllsize{smaller}% - \resetmathfonts \setleading{10.5pt}} -\def\smallfonts{% - \let\tenrm=\smallrm \let\tenit=\smallit \let\tensl=\smallsl - \let\tenbf=\smallbf \let\tentt=\smalltt \let\smallcaps=\smallsc - \let\tensf=\smallsf \let\teni=\smalli \let\tensy=\smallsy - \let\tenttsl=\smallttsl - \def\curfontsize{small}% - \def\lsize{smaller}\def\lllsize{smaller}% - \resetmathfonts \setleading{10.5pt}} -\def\smallerfonts{% - \let\tenrm=\smallerrm \let\tenit=\smallerit \let\tensl=\smallersl - \let\tenbf=\smallerbf \let\tentt=\smallertt \let\smallcaps=\smallersc - \let\tensf=\smallersf \let\teni=\smalleri \let\tensy=\smallersy - \let\tenttsl=\smallerttsl - \def\curfontsize{smaller}% - \def\lsize{smaller}\def\lllsize{smaller}% - \resetmathfonts \setleading{9.5pt}} -% Fonts for short table of contents. -\setfont\shortcontrm\rmshape{12}{1000}{OT1} -\setfont\shortcontbf\bfshape{10}{\magstep1}{OT1} % no cmb12 -\setfont\shortcontsl\slshape{12}{1000}{OT1} -\setfont\shortconttt\ttshape{12}{1000}{OT1TT} +\def\assignfonts#1{% + \expandafter\let\expandafter\rmfont\csname #1rm\endcsname + \expandafter\let\expandafter\itfont\csname #1it\endcsname + \expandafter\let\expandafter\slfont\csname #1sl\endcsname + \expandafter\let\expandafter\bffont\csname #1bf\endcsname + \expandafter\let\expandafter\ttfont\csname #1tt\endcsname + \expandafter\let\expandafter\smallcaps\csname #1sc\endcsname + \expandafter\let\expandafter\sffont \csname #1sf\endcsname + \expandafter\let\expandafter\ifont \csname #1i\endcsname + \expandafter\let\expandafter\syfont \csname #1sy\endcsname + \expandafter\let\expandafter\ttslfont\csname #1ttsl\endcsname +} + +\newif\ifrmisbold + +% Select smaller font size with the current style. Used to change font size +% in, e.g., the LaTeX logo and acronyms. If we are using bold fonts for +% normal roman text, also use bold fonts for roman text in the smaller size. +\def\switchtolllsize{% + \expandafter\assignfonts\expandafter{\lllsize}% + \ifrmisbold + \let\rmfont\bffont + \fi + \csname\curfontstyle\endcsname +}% + +\def\switchtolsize{% + \expandafter\assignfonts\expandafter{\lsize}% + \ifrmisbold + \let\rmfont\bffont + \fi + \csname\curfontstyle\endcsname +}% + +\def\definefontsetatsize#1#2#3#4#5{% +\expandafter\def\csname #1fonts\endcsname{% + \def\curfontsize{#1}% + \def\lsize{#2}\def\lllsize{#3}% + \csname rmisbold#5\endcsname + \assignfonts{#1}% + \resetmathfonts + \setleading{#4}% +}} + +\definefontsetatsize{text} {reduced}{smaller}{\textleading}{false} +\definefontsetatsize{title} {chap} {subsec} {27pt} {true} +\definefontsetatsize{chap} {sec} {text} {19pt} {true} +\definefontsetatsize{sec} {subsec} {reduced}{17pt} {true} +\definefontsetatsize{ssec} {text} {small} {15pt} {true} +\definefontsetatsize{reduced}{small} {smaller}{10.5pt}{false} +\definefontsetatsize{small} {smaller}{smaller}{10.5pt}{false} +\definefontsetatsize{smaller}{smaller}{smaller}{9.5pt} {false} + +\def\titlefont#1{{\titlefonts\rm #1}} +\let\subsecfonts = \ssecfonts +\let\subsubsecfonts = \ssecfonts % Define these just so they can be easily changed for other fonts. \def\angleleft{$\langle$} @@ -3108,7 +3210,7 @@ end % \def\acronym#1{\doacronym #1,,\finish} \def\doacronym#1,#2,#3\finish{% - {\selectfonts\lsize #1}% + {\switchtolsize #1}% \def\temp{#2}% \ifx\temp\empty \else \space ({\unsepspaces \ignorespaces \temp \unskip})% @@ -3201,10 +3303,10 @@ end % fix it (significant additions to font machinery) until someone notices. % \def\sub{\ifmmode \expandafter\sb \else \expandafter\finishsub\fi} -\def\finishsub#1{$\sb{\hbox{\selectfonts\lllsize #1}}$}% +\def\finishsub#1{$\sb{\hbox{\switchtolllsize #1}}$}% % \def\sup{\ifmmode \expandafter\ptexsp \else \expandafter\finishsup\fi} -\def\finishsup#1{$\ptexsp{\hbox{\selectfonts\lllsize #1}}$}% +\def\finishsup#1{$\ptexsp{\hbox{\switchtolllsize #1}}$}% % @inlinefmt{FMTNAME,PROCESSED-TEXT} and @inlineraw{FMTNAME,RAW-TEXT}. % Ignore unless FMTNAME == tex; then it is like @iftex and @tex, @@ -3268,23 +3370,10 @@ end \let\atchar=\@ % @{ @} @lbracechar{} @rbracechar{} all generate brace characters. -% Unless we're in typewriter, use \ecfont because the CM text fonts do -% not have braces, and we don't want to switch into math. -\def\mylbrace{{\ifmonospace\else\ecfont\fi \char123}} -\def\myrbrace{{\ifmonospace\else\ecfont\fi \char125}} -\let\{=\mylbrace \let\lbracechar=\{ -\let\}=\myrbrace \let\rbracechar=\} -\begingroup - % Definitions to produce \{ and \} commands for indices, - % and @{ and @} for the aux/toc files. - \catcode`\{ = \other \catcode`\} = \other - \catcode`\[ = 1 \catcode`\] = 2 - \catcode`\! = 0 \catcode`\\ = \other - !gdef!lbracecmd[\{]% - !gdef!rbracecmd[\}]% - !gdef!lbraceatcmd[@{]% - !gdef!rbraceatcmd[@}]% -!endgroup +\def\lbracechar{{\ifmonospace\char123\else\ensuremath\lbrace\fi}} +\def\rbracechar{{\ifmonospace\char125\else\ensuremath\rbrace\fi}} +\let\{=\lbracechar +\let\}=\rbracechar % @comma{} to avoid , parsing problems. \let\comma = , @@ -3302,8 +3391,8 @@ end % Plain TeX defines: @AA @AE @O @OE @L (plus lowercase versions) @ss. \def\questiondown{?`} \def\exclamdown{!`} -\def\ordf{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{a}}} -\def\ordm{\leavevmode\raise1ex\hbox{\selectfonts\lllsize \underbar{o}}} +\def\ordf{\leavevmode\raise1ex\hbox{\switchtolllsize \underbar{a}}} +\def\ordm{\leavevmode\raise1ex\hbox{\switchtolllsize \underbar{o}}} % Dotless i and dotless j, used for accents. \def\imacro{i} @@ -3332,12 +3421,12 @@ end {\setbox0=\hbox{T}% \vbox to \ht0{\hbox{% \ifx\textnominalsize\xwordpt - % for 10pt running text, \lllsize (8pt) is too small for the A in LaTeX. + % for 10pt running text, lllsize (8pt) is too small for the A in LaTeX. % Revert to plain's \scriptsize, which is 7pt. \count255=\the\fam $\fam\count255 \scriptstyle A$% \else % For 11pt, we can use our lllsize. - \selectfonts\lllsize A% + \switchtolllsize A% \fi }% \vss @@ -3403,7 +3492,7 @@ end % \newbox\errorbox % -{\tentt \global\dimen0 = 3em}% Width of the box. +{\ttfont \global\dimen0 = 3em}% Width of the box. \dimen2 = .55pt % Thickness of rules % The text. (`r' is open on the right, `e' somewhat less so on the left.) \setbox0 = \hbox{\kern-.75pt \reducedsf \putworderror\kern-1.5pt} @@ -3554,7 +3643,7 @@ end % Adapted from the plain.tex definition of \copyright. % \def\registeredsymbol{% - $^{{\ooalign{\hfil\raise.07ex\hbox{\selectfonts\lllsize R}% + $^{{\ooalign{\hfil\raise.07ex\hbox{\switchtolllsize R}% \hfil\crcr\Orb}}% }$% } @@ -3648,12 +3737,11 @@ end % Settings used for typesetting titles: no hyphenation, no indentation, % don't worry much about spacing, ragged right. This should be used -% inside a \vbox, and fonts need to be set appropriately first. Because -% it is always used for titles, nothing else, we call \rmisbold. \par -% should be specified before the end of the \vbox, since a vbox is a group. +% inside a \vbox, and fonts need to be set appropriately first. \par should +% be specified before the end of the \vbox, since a vbox is a group. % \def\raggedtitlesettings{% - \rmisbold + \rm \hyphenpenalty=10000 \parindent=0pt \tolerance=5000 @@ -3662,7 +3750,7 @@ end % Macros to be used within @titlepage: -\let\subtitlerm=\tenrm +\let\subtitlerm=\rmfont \def\subtitlefont{\subtitlerm \normalbaselineskip = 13pt \normalbaselines} \parseargdef\title{% @@ -3688,7 +3776,7 @@ end \else \checkenv\titlepage \ifseenauthor\else \vskip 0pt plus 1filll \seenauthortrue \fi - {\secfonts\rmisbold \leftline{#1}}% + {\secfonts\rm \leftline{#1}}% \fi } @@ -4603,6 +4691,31 @@ end \fi } +% Like \expandablevalue, but completely expandable (the \message in the +% definition above operates at the execution level of TeX). Used when +% writing to auxiliary files, due to the expansion that \write does. +% If flag is undefined, pass through an unexpanded @value command: maybe it +% will be set by the time it is read back in. +% +% NB flag names containing - or _ may not work here. +\def\dummyvalue#1{% + \expandafter\ifx\csname SET#1\endcsname\relax + \noexpand\value{#1}% + \else + \csname SET#1\endcsname + \fi +} + +% Used for @value's in index entries to form the sort key: expand the @value +% if possible, otherwise sort late. +\def\indexnofontsvalue#1{% + \expandafter\ifx\csname SET#1\endcsname\relax + ZZZZZZZ + \else + \csname SET#1\endcsname + \fi +} + % @ifset VAR ... @end ifset reads the `...' iff VAR has been defined % with @set. % @@ -4727,14 +4840,7 @@ end % #1 is \doindex or \docodeindex, #2 the index getting redefined (foo), % #3 the target index (bar). \def\dosynindex#1#2#3{% - % Only do \closeout if we haven't already done it, else we'll end up - % closing the target index. - \expandafter \ifx\csname donesynindex#2\endcsname \relax - % The \closeout helps reduce unnecessary open files; the limit on the - % Acorn RISC OS is a mere 16 files. - \expandafter\closeout\csname#2indfile\endcsname - \expandafter\let\csname donesynindex#2\endcsname = 1 - \fi + \requireopenindexfile{#3}% % redefine \fooindfile: \expandafter\let\expandafter\temp\expandafter=\csname#3indfile\endcsname \expandafter\let\csname#2indfile\endcsname=\temp @@ -4744,7 +4850,7 @@ end % Define \doindex, the driver for all index macros. % Argument #1 is generated by the calling \fooindex macro, -% and it the two-letter name of the index. +% and it is the two-letter name of the index. \def\doindex#1{\edef\indexname{#1}\parsearg\doindexxxx} \def\doindexxxx #1{\doind{\indexname}{#1}} @@ -4753,63 +4859,61 @@ end \def\docodeindex#1{\edef\indexname{#1}\parsearg\docodeindexxxx} \def\docodeindexxxx #1{\doind{\indexname}{\code{#1}}} -% Used when writing an index entry out to an index file, to prevent + +% Used when writing an index entry out to an index file to prevent % expansion of Texinfo commands that can appear in an index entry. % \def\indexdummies{% \escapechar = `\\ % use backslash in output files. - \def\@{@}% change to @@ when we switch to @ as escape char in index files. - \def\ {\realbackslash\space }% - % - % Need these unexpandable (because we define \tt as a dummy) - % definitions when @{ or @} appear in index entry text. Also, more - % complicated, when \tex is in effect and \{ is a \delimiter again. - % We can't use \lbracecmd and \rbracecmd because texindex assumes - % braces and backslashes are used only as delimiters. Perhaps we - % should use @lbracechar and @rbracechar? - \def\{{{\tt\char123}}% - \def\}{{\tt\char125}}% + \definedummyletter\@% + \definedummyletter\ % + % + % For texindex which always views { and } as separators. + \def\{{\lbracechar{}}% + \def\}{\rbracechar{}}% % % Do the redefinitions. - \commondummies + \definedummies } -% For the aux and toc files, @ is the escape character. So we want to -% redefine everything using @ as the escape character (instead of -% \realbackslash, still used for index files). When everything uses @, -% this will be simpler. +% Used for the aux and toc files, where @ is the escape character. % \def\atdummies{% - \def\@{@@}% - \def\ {@ }% - \let\{ = \lbraceatcmd - \let\} = \rbraceatcmd + \definedummyletter\@% + \definedummyletter\ % + \definedummyletter\{% + \definedummyletter\}% % % Do the redefinitions. - \commondummies + \definedummies \otherbackslash } -% Called from \indexdummies and \atdummies. +% \definedummyword defines \#1 as \string\#1\space, thus effectively +% preventing its expansion. This is used only for control words, +% not control letters, because the \space would be incorrect for +% control characters, but is needed to separate the control word +% from whatever follows. % -\def\commondummies{% - % \definedummyword defines \#1 as \string\#1\space, thus effectively - % preventing its expansion. This is used only for control words, - % not control letters, because the \space would be incorrect for - % control characters, but is needed to separate the control word - % from whatever follows. - % - % For control letters, we have \definedummyletter, which omits the - % space. - % - % These can be used both for control words that take an argument and - % those that do not. If it is followed by {arg} in the input, then - % that will dutifully get written to the index (or wherever). - % - \def\definedummyword ##1{\def##1{\string##1\space}}% - \def\definedummyletter##1{\def##1{\string##1}}% - \let\definedummyaccent\definedummyletter +% These can be used both for control words that take an argument and +% those that do not. If it is followed by {arg} in the input, then +% that will dutifully get written to the index (or wherever). +% +% For control letters, we have \definedummyletter, which omits the +% space. +% +\def\definedummyword #1{\def#1{\string#1\space}}% +\def\definedummyletter#1{\def#1{\string#1}}% +\let\definedummyaccent\definedummyletter + +% Called from \indexdummies and \atdummies, to effectively prevent +% the expansion of commands. +% +\def\definedummies{% % + \let\commondummyword\definedummyword + \let\commondummyletter\definedummyletter + \let\commondummyaccent\definedummyaccent \commondummiesnofonts % \definedummyletter\_% @@ -4850,6 +4954,7 @@ end \definedummyword\TeX % % Assorted special characters. + \definedummyword\atchar \definedummyword\arrow \definedummyword\bullet \definedummyword\comma @@ -4889,85 +4994,82 @@ end % % We want to disable all macros so that they are not expanded by \write. \macrolist + \let\value\dummyvalue % \normalturnoffactive - % - % Handle some cases of @value -- where it does not contain any - % (non-fully-expandable) commands. - \makevalueexpandable } -% \commondummiesnofonts: common to \commondummies and \indexnofonts. -% Define \definedumyletter, \definedummyaccent and \definedummyword before -% using. +% \commondummiesnofonts: common to \definedummies and \indexnofonts. +% Define \commondummyletter, \commondummyaccent and \commondummyword before +% using. Used for accents, font commands, and various control letters. % \def\commondummiesnofonts{% % Control letters and accents. - \definedummyletter\!% - \definedummyaccent\"% - \definedummyaccent\'% - \definedummyletter\*% - \definedummyaccent\,% - \definedummyletter\.% - \definedummyletter\/% - \definedummyletter\:% - \definedummyaccent\=% - \definedummyletter\?% - \definedummyaccent\^% - \definedummyaccent\`% - \definedummyaccent\~% - \definedummyword\u - \definedummyword\v - \definedummyword\H - \definedummyword\dotaccent - \definedummyword\ogonek - \definedummyword\ringaccent - \definedummyword\tieaccent - \definedummyword\ubaraccent - \definedummyword\udotaccent - \definedummyword\dotless + \commondummyletter\!% + \commondummyaccent\"% + \commondummyaccent\'% + \commondummyletter\*% + \commondummyaccent\,% + \commondummyletter\.% + \commondummyletter\/% + \commondummyletter\:% + \commondummyaccent\=% + \commondummyletter\?% + \commondummyaccent\^% + \commondummyaccent\`% + \commondummyaccent\~% + \commondummyword\u + \commondummyword\v + \commondummyword\H + \commondummyword\dotaccent + \commondummyword\ogonek + \commondummyword\ringaccent + \commondummyword\tieaccent + \commondummyword\ubaraccent + \commondummyword\udotaccent + \commondummyword\dotless % % Texinfo font commands. - \definedummyword\b - \definedummyword\i - \definedummyword\r - \definedummyword\sansserif - \definedummyword\sc - \definedummyword\slanted - \definedummyword\t + \commondummyword\b + \commondummyword\i + \commondummyword\r + \commondummyword\sansserif + \commondummyword\sc + \commondummyword\slanted + \commondummyword\t % % Commands that take arguments. - \definedummyword\abbr - \definedummyword\acronym - \definedummyword\anchor - \definedummyword\cite - \definedummyword\code - \definedummyword\command - \definedummyword\dfn - \definedummyword\dmn - \definedummyword\email - \definedummyword\emph - \definedummyword\env - \definedummyword\file - \definedummyword\image - \definedummyword\indicateurl - \definedummyword\inforef - \definedummyword\kbd - \definedummyword\key - \definedummyword\math - \definedummyword\option - \definedummyword\pxref - \definedummyword\ref - \definedummyword\samp - \definedummyword\strong - \definedummyword\tie - \definedummyword\U - \definedummyword\uref - \definedummyword\url - \definedummyword\var - \definedummyword\verb - \definedummyword\w - \definedummyword\xref + \commondummyword\abbr + \commondummyword\acronym + \commondummyword\anchor + \commondummyword\cite + \commondummyword\code + \commondummyword\command + \commondummyword\dfn + \commondummyword\dmn + \commondummyword\email + \commondummyword\emph + \commondummyword\env + \commondummyword\file + \commondummyword\image + \commondummyword\indicateurl + \commondummyword\inforef + \commondummyword\kbd + \commondummyword\key + \commondummyword\math + \commondummyword\option + \commondummyword\pxref + \commondummyword\ref + \commondummyword\samp + \commondummyword\strong + \commondummyword\tie + \commondummyword\U + \commondummyword\uref + \commondummyword\url + \commondummyword\var + \commondummyword\verb + \commondummyword\w + \commondummyword\xref } % For testing: output @{ and @} in index sort strings as \{ and \}. @@ -5023,11 +5125,11 @@ end % \def\indexnofonts{% % Accent commands should become @asis. - \def\definedummyaccent##1{\let##1\asis}% + \def\commondummyaccent##1{\let##1\asis}% % We can just ignore other control letters. - \def\definedummyletter##1{\let##1\empty}% + \def\commondummyletter##1{\let##1\empty}% % All control words become @asis by default; overrides below. - \let\definedummyword\definedummyaccent + \let\commondummyword\commondummyaccent \commondummiesnofonts % % Don't no-op \tt, since it isn't a user-level command @@ -5069,37 +5171,40 @@ end \def\LaTeX{LaTeX}% \def\TeX{TeX}% % - % Assorted special characters. - % (The following {} will end up in the sort string, but that's ok.) - \def\arrow{->}% - \def\bullet{bullet}% - \def\comma{,}% - \def\copyright{copyright}% - \def\dots{...}% - \def\enddots{...}% - \def\equiv{==}% - \def\error{error}% - \def\euro{euro}% - \def\expansion{==>}% - \def\geq{>=}% - \def\guillemetleft{<<}% - \def\guillemetright{>>}% - \def\guilsinglleft{<}% - \def\guilsinglright{>}% - \def\leq{<=}% - \def\minus{-}% - \def\point{.}% - \def\pounds{pounds}% - \def\print{-|}% - \def\quotedblbase{"}% - \def\quotedblleft{"}% - \def\quotedblright{"}% - \def\quoteleft{`}% - \def\quoteright{'}% - \def\quotesinglbase{,}% - \def\registeredsymbol{R}% - \def\result{=>}% - \def\textdegree{o}% + % Assorted special characters. \defglyph gives the control sequence a + % definition that removes the {} that follows its use. + \defglyph\atchar{@}% + \defglyph\arrow{->}% + \defglyph\bullet{bullet}% + \defglyph\comma{,}% + \defglyph\copyright{copyright}% + \defglyph\dots{...}% + \defglyph\enddots{...}% + \defglyph\equiv{==}% + \defglyph\error{error}% + \defglyph\euro{euro}% + \defglyph\expansion{==>}% + \defglyph\geq{>=}% + \defglyph\guillemetleft{<<}% + \defglyph\guillemetright{>>}% + \defglyph\guilsinglleft{<}% + \defglyph\guilsinglright{>}% + \defglyph\leq{<=}% + \defglyph\lbracechar{\{}% + \defglyph\minus{-}% + \defglyph\point{.}% + \defglyph\pounds{pounds}% + \defglyph\print{-|}% + \defglyph\quotedblbase{"}% + \defglyph\quotedblleft{"}% + \defglyph\quotedblright{"}% + \defglyph\quoteleft{`}% + \defglyph\quoteright{'}% + \defglyph\quotesinglbase{,}% + \defglyph\rbracechar{\}}% + \defglyph\registeredsymbol{R}% + \defglyph\result{=>}% + \defglyph\textdegree{o}% % % We need to get rid of all macros, leaving only the arguments (if present). % Of course this is not nearly correct, but it is the best we can do for now. @@ -5112,7 +5217,11 @@ end % goes to end-of-line is not handled. % \macrolist + \let\value\indexnofontsvalue } +\def\defglyph#1#2{\def#1##1{#2}} % see above + + \let\SETmarginindex=\relax % put index entries in margin (undocumented)? @@ -5159,9 +5268,10 @@ end \ifx\suffix\indexisfl\def\suffix{f1}\fi % Open the file \immediate\openout\csname#1indfile\endcsname \jobname.\suffix - % Using \immediate here prevents an object entering into the current box, - % which could confound checks such as those in \safewhatsit for preceding - % skips. + % Using \immediate above here prevents an object entering into the current + % box, which could confound checks such as those in \safewhatsit for + % preceding skips. + \typeout{Writing index file \jobname.\suffix}% \fi} \def\indexisfl{fl} @@ -5359,7 +5469,7 @@ end % \initial {@} % as its first line, TeX doesn't complain about mismatched braces % (because it thinks @} is a control sequence). - \catcode`\@ = 11 + \catcode`\@ = 12 % See comment in \requireopenindexfile. \def\indexname{#1}\ifx\indexname\indexisfl\def\indexname{f1}\fi \openin 1 \jobname.\indexname s @@ -5369,6 +5479,7 @@ end % index. The easiest way to prevent this problem is to make sure % there is some text. \putwordIndexNonexistent + \typeout{No file \jobname.\indexname s.}% \else \catcode`\\ = 0 % @@ -5386,7 +5497,7 @@ end \let\indexlbrace\{ % Likewise, set these sequences for braces \let\indexrbrace\} % used in the sort key. \begindoublecolumns - \let\entryorphanpenalty=\indexorphanpenalty + \let\entrywidowpenalty=\indexwidowpenalty % % Read input from the index file line by line. \loopdo @@ -5487,6 +5598,12 @@ end \def\entry{% \begingroup % + % For pdfTeX and XeTeX. + % The redefinition of \domark stops marks being added in \pdflink to + % preserve coloured links across page boundaries. Otherwise the marks + % would get in the way of \lastbox in \insertindexentrybox. + \let\domark\relax + % % Start a new paragraph if necessary, so our assignments below can't % affect previous text. \par @@ -5500,10 +5617,6 @@ end \def\*{\unskip\space\ignorespaces}% \def\entrybreak{\hfil\break}% An undocumented command % - % A bit of stretch before each entry for the benefit of balancing - % columns. - \vskip 0pt plus0.5pt - % % Swallow the left brace of the text (first parameter): \afterassignment\doentry \let\temp = @@ -5537,20 +5650,13 @@ end % \ifpdf \pdfgettoks#1.% - \bgroup\let\domark\relax - \hskip\skip\thinshrinkable\the\toksA - \egroup - % The redefinion of \domark stops marks being added in \pdflink to - % preserve coloured links across page boundaries. Otherwise the marks - % would get in the way of \lastbox in \insertindexentrybox. + \hskip\skip\thinshrinkable\the\toksA \else \ifx\XeTeXrevision\thisisundefined \hskip\skip\thinshrinkable #1% \else \pdfgettoks#1.% - \bgroup\let\domark\relax - \hskip\skip\thinshrinkable\the\toksA - \egroup + \hskip\skip\thinshrinkable\the\toksA \fi \fi \fi @@ -5559,11 +5665,10 @@ end \global\setbox\entryindexbox=\vbox{\unhbox\boxA}% \else \global\setbox\entryindexbox=\vbox\bgroup - \prevdepth=\entrylinedepth - \noindent % We want the text of the entries to be aligned to the left, and the % page numbers to be aligned to the right. % + \parindent = 0pt \advance\leftskip by 0pt plus 1fil \advance\leftskip by 0pt plus -1fill \rightskip = 0pt plus -1fil @@ -5572,8 +5677,6 @@ end % if the list of page numbers is long, to be aligned to the right. \parfillskip=0pt plus -1fill % - \hangindent=1em - % \advance\rightskip by \entryrightmargin % Determine how far we can stretch into the margin. % This allows, e.g., "Appendix H GNU Free Documentation License" to @@ -5593,17 +5696,21 @@ end \ifdim\dimen@ > 0.8\dimen@ii % due to long index text \dimen@ = 0.7\dimen@ % Try to split the text roughly evenly \dimen@ii = \hsize - \advance \dimen@ii by -1em \ifnum\dimen@>\dimen@ii % If the entry is too long, use the whole line \dimen@ = \dimen@ii \fi \advance\leftskip by 0pt plus 1fill % ragged right \advance \dimen@ by 1\rightskip - \parshape = 2 0pt \dimen@ 1em \dimen@ii - % Ideally we'd add a finite glue at the end of the first line only, but - % TeX doesn't seem to provide a way to do such a thing. + \parshape = 2 0pt \dimen@ 0em \dimen@ii + % Ideally we'd add a finite glue at the end of the first line only, + % instead of using \parshape with explicit line lengths, but TeX + % doesn't seem to provide a way to do such a thing. + % + \leftskip = 1em + \parindent = -1em \fi\fi + \indent % start paragraph \unhbox\boxA % % Do not prefer a separate line ending with a hyphen to fewer lines. @@ -5621,7 +5728,7 @@ end \endgroup % delay text of entry until after penalty \bgroup\aftergroup\insertindexentrybox - \entryorphanpenalty + \entrywidowpenalty }} \newskip\thinshrinkable @@ -5629,40 +5736,43 @@ end \newbox\entryindexbox \def\insertindexentrybox{% - \copy\entryindexbox - % The following gets the depth of the last box. This is for even - % line spacing when entries span several lines. - \setbox\dummybox\vbox{% - \unvbox\entryindexbox - \nointerlineskip - \lastbox - \global\entrylinedepth=\prevdepth + \ourunvbox\entryindexbox +} + +% Use \lastbox to take apart vbox box by box, and add each sub-box +% to the current vertical list. +\def\ourunvbox#1{% +\bgroup % for local binding of \delayedbox + % Remove the last box from box #1 + \global\setbox#1=\vbox{% + \unvbox#1% + \unskip % remove any glue + \unpenalty + \global\setbox\interbox=\lastbox }% - % Note that we couldn't simply \unvbox\entryindexbox followed by - % \nointerlineskip\lastbox to remove the last box and then reinstate it, - % because this resets how far the box has been \moveleft'ed to 0. \unvbox - % doesn't affect \prevdepth either. + \setbox\delayedbox=\box\interbox + \ifdim\ht#1=0pt\else + \ourunvbox#1 % Repeat on what's left of the box + \nobreak + \fi + \box\delayedbox +\egroup } -\newdimen\entrylinedepth +\newbox\delayedbox +\newbox\interbox % Default is no penalty -\let\entryorphanpenalty\egroup +\let\entrywidowpenalty\egroup % Used from \printindex. \firsttoken should be the first token % after the \entry. If it's not another \entry, we are at the last % line of a group of index entries, so insert a penalty to discourage -% orphaned index entries. -\long\def\indexorphanpenalty{% +% widowed index entries. +\long\def\indexwidowpenalty{% \def\isentry{\entry}% \ifx\firsttoken\isentry \else - \unskip\penalty 9000 - % The \unskip here stops breaking before the glue. It relies on the - % \vskip above being there, otherwise there is an error - % "You can't use `\unskip' in vertical mode". There has to be glue - % in the current vertical list that hasn't been added to the - % "current page". See Chapter 24 of the TeXbook. This contradicts - % Section 8.3.7 in "TeX by Topic," though. + \penalty 9000 \fi \egroup % now comes the box added with \aftergroup } @@ -5702,8 +5812,6 @@ end \newbox\partialpage \newdimen\doublecolumnhsize -\newdimen\doublecolumntopgap -\doublecolumntopgap = 0pt % Use inside an output routine to save \topmark and \firstmark \def\savemarks{% @@ -5786,12 +5894,10 @@ end % % Double the \vsize as well. (We don't need a separate register here, % since nobody clobbers \vsize.) - \global\doublecolumntopgap = \topskip - \global\advance\doublecolumntopgap by -1\baselineskip - \advance\vsize by -1\doublecolumntopgap \vsize = 2\vsize - \topskip=0pt - \global\entrylinedepth=0pt\relax + % + % For the benefit of balancing columns + \advance\baselineskip by 0pt plus 0.5pt } % The double-column output routine for all double-column pages except @@ -5821,9 +5927,7 @@ end % \hsize = \doublecolumnhsize \wd0=\hsize \wd2=\hsize - \vbox{% - \vskip\doublecolumntopgap - \hbox to\txipagewidth{\box0\hfil\box2}}% + \hbox to\txipagewidth{\box0\hfil\box2}% } @@ -5890,38 +5994,45 @@ end \dimen@ = \ht0 \advance\dimen@ by \topskip \advance\dimen@ by-\baselineskip - \ifdim\dimen@<14\baselineskip + \ifdim\dimen@<5\baselineskip % Don't split a short final column in two. \setbox2=\vbox{}% \else \divide\dimen@ by 2 % target to split to \dimen@ii = \dimen@ \splittopskip = \topskip - % Loop until the second column is no higher than the first + % Loop until left column is at least as high as the right column. {% \vbadness = 10000 \loop \global\setbox3 = \copy0 \global\setbox1 = \vsplit3 to \dimen@ - % Remove glue from bottom of first column to - % make sure it is higher than the second. - \global\setbox1 = \vbox{\unvbox1\unpenalty\unskip}% - \ifdim\ht3>\ht1 + \ifdim\ht1<\ht3 \global\advance\dimen@ by 1pt \repeat }% - \multiply\dimen@ii by 4 - \divide\dimen@ii by 5 - \ifdim\ht3<\dimen@ii - % Column heights are too different, so don't make their bottoms - % flush with each other. The glue at the end of the second column - % allows a second column to stretch, reducing the difference in - % height between the two. - \setbox0=\vbox to\dimen@{\unvbox1\vfill}% - \setbox2=\vbox to\dimen@{\unvbox3\vskip 0pt plus 0.3\ht0}% + % Now the left column is in box 1, and the right column in box 3. + % Check whether the left column has come out higher than the page itself. + % (Note that we have doubled \vsize for the double columns, so + % the actual height of the page is 0.5\vsize). + \ifdim2\ht1>\vsize + % Just split the last of the double column material roughly in half. + \setbox2=\box0 + \setbox0 = \vsplit2 to \dimen@ii + \setbox0=\vbox to \dimen@ii {\unvbox0\vfill}% + \setbox2=\vbox to \dimen@ii {\unvbox2\vfill}% \else - \setbox0=\vbox to\dimen@{\unvbox1}% - \setbox2=\vbox to\dimen@{\unvbox3}% + % Compare the heights of the two columns. + \ifdim4\ht1>5\ht3 + % Column heights are too different, so don't make their bottoms + % flush with each other. + \setbox2=\vbox to \ht1 {\unvbox3\vfill}% + \setbox0=\vbox to \ht1 {\unvbox1\vfill}% + \else + % Make column bottoms flush with each other. + \setbox2=\vbox to\ht1{\unvbox3\unskip}% + \setbox0=\vbox to\ht1{\unvbox1\unskip}% + \fi \fi \fi % @@ -5940,7 +6051,7 @@ end \null \vskip.3\vsize % move it down on the page a bit \begingroup - \noindent \titlefonts\rmisbold #1\par % the text + \noindent \titlefonts\rm #1\par % the text \let\lastnode=\empty % no node to associate with \writetocentry{part}{#1}{}% but put it in the toc \headingsoff % no headline or footline on the part page @@ -6426,7 +6537,7 @@ end \domark % {% - \chapfonts \rmisbold + \chapfonts \rm \let\footnote=\errfootnoteheading % give better error message % % Have to define \lastsection before calling \donoderef, because the @@ -6518,7 +6629,7 @@ end \let\footnote=\errfootnoteheading % % Switch to the right set of fonts. - \csname #2fonts\endcsname \rmisbold + \csname #2fonts\endcsname \rm % % Insert first mark before the heading break (see notes for \domark). \let\prevsectiondefs=\lastsectiondefs @@ -6682,7 +6793,14 @@ end % 1 and 2 (the page numbers aren't printed), and so are the first % two pages of the document. Thus, we'd have two destinations named % `1', and two named `2'. - \ifpdf \global\pdfmakepagedesttrue \fi + \ifpdf + \global\pdfmakepagedesttrue + \else + \ifx\XeTeXrevision\thisisundefined + \else + \global\pdfmakepagedesttrue + \fi + \fi } @@ -7784,7 +7902,7 @@ end \fi % no return type #3% output function name }% - {\rm\enskip}% hskip 0.5 em of \tenrm + {\rm\enskip}% hskip 0.5 em of \rmfont % \boldbrax % arguments will be output next, if any. @@ -7963,7 +8081,7 @@ end \newif\ifrecursive % Is it recursive? % List of all defined macros in the form -% \definedummyword\macro1\definedummyword\macro2... +% \commondummyword\macro1\commondummyword\macro2... % Currently is also contains all @aliases; the list can be split % if there is a need. \def\macrolist{} @@ -7971,7 +8089,7 @@ end % Add the macro to \macrolist \def\addtomacrolist#1{\expandafter \addtomacrolistxxx \csname#1\endcsname} \def\addtomacrolistxxx#1{% - \toks0 = \expandafter{\macrolist\definedummyword#1}% + \toks0 = \expandafter{\macrolist\commondummyword#1}% \xdef\macrolist{\the\toks0}% } @@ -8112,7 +8230,7 @@ end % Remove the macro name from \macrolist: \begingroup \expandafter\let\csname#1\endcsname \relax - \let\definedummyword\unmacrodo + \let\commondummyword\unmacrodo \xdef\macrolist{\macrolist}% \endgroup \else @@ -8127,7 +8245,7 @@ end \ifx #1\relax % remove this \else - \noexpand\definedummyword \noexpand#1% + \noexpand\commondummyword \noexpand#1% \fi } @@ -8402,8 +8520,7 @@ end % its parameters, looking like "\xeatspaces{\hash 1}". % \paramno is the number of parameters % \paramlist is a TeX parameter text, e.g. "#1,#2,#3," -% There are eight cases: recursive and nonrecursive macros of zero, one, -% up to nine, and many arguments. +% There are four cases: macros of zero, one, up to nine, and many arguments. % \xdef is used so that macro definitions will survive the file % they're defined in: @include reads the file inside a group. % @@ -8418,91 +8535,48 @@ end \else \let\xeatspaces\relax % suppress expansion \fi - \ifrecursive %%%%%%%%%%%%%% Recursive %%%%%%%%%%%%%%%%%%%%%%%%%%%%% - \ifcase\paramno - % 0 - \expandafter\xdef\csname\the\macname\endcsname{% - \noexpand\scanmacro{\macrobody}}% - \or % 1 + \ifcase\paramno + % 0 + \expandafter\xdef\csname\the\macname\endcsname{% + \noexpand\scanmacro{\macrobody}}% + \or % 1 + \expandafter\xdef\csname\the\macname\endcsname{% + \bgroup + \noexpand\braceorline + \expandafter\noexpand\csname\the\macname @@@\endcsname}% + \expandafter\xdef\csname\the\macname @@@\endcsname##1{% + \egroup + \noexpand\scanmacro{\macrobody}% + }% + \else % at most 9 + \ifnum\paramno<10\relax + % @MACNAME sets the context for reading the macro argument + % @MACNAME@@ gets the argument, processes backslashes and appends a + % comma. + % @MACNAME@@@ removes braces surrounding the argument list. + % @MACNAME@@@@ scans the macro body with arguments substituted. \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup - \noexpand\braceorline - \expandafter\noexpand\csname\the\macname @@@\endcsname}% + \bgroup + \noexpand\expandafter % This \expandafter skip any spaces after the + \noexpand\macroargctxt % macro before we change the catcode of space. + \noexpand\expandafter + \expandafter\noexpand\csname\the\macname @@\endcsname}% + \expandafter\xdef\csname\the\macname @@\endcsname##1{% + \noexpand\passargtomacro + \expandafter\noexpand\csname\the\macname @@@\endcsname{##1,}}% \expandafter\xdef\csname\the\macname @@@\endcsname##1{% - \egroup - \noexpand\scanmacro{\macrobody}% - }% - \else - \ifnum\paramno<10\relax % at most 9 - % See non-recursive section below for comments - \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup - \noexpand\expandafter - \noexpand\macroargctxt - \noexpand\expandafter - \expandafter\noexpand\csname\the\macname @@\endcsname}% - \expandafter\xdef\csname\the\macname @@\endcsname##1{% - \noexpand\passargtomacro - \expandafter\noexpand\csname\the\macname @@@\endcsname{##1,}}% - \expandafter\xdef\csname\the\macname @@@\endcsname##1{% - \expandafter\noexpand\csname\the\macname @@@@\endcsname ##1}% - \expandafter\expandafter - \expandafter\xdef - \expandafter\expandafter - \csname\the\macname @@@@\endcsname\paramlist{% - \egroup\noexpand\scanmacro{\macrobody}}% - \else % 10 or more - \expandafter\xdef\csname\the\macname\endcsname{% - \noexpand\getargvals@{\the\macname}{\argl}% - }% - \global\expandafter\let\csname mac.\the\macname .body\endcsname\macrobody - \global\expandafter\let\csname mac.\the\macname .recurse\endcsname\gobble - \fi - \fi - \else %%%%%%%%%%%%%%%%%%%%%% Non-recursive %%%%%%%%%%%%%%%%%%%%%%%%%% - \ifcase\paramno - % 0 - \expandafter\xdef\csname\the\macname\endcsname{% - \noexpand\scanmacro{\macrobody}}% - \or % 1 + \expandafter\noexpand\csname\the\macname @@@@\endcsname ##1}% + \expandafter\expandafter + \expandafter\xdef + \expandafter\expandafter + \csname\the\macname @@@@\endcsname\paramlist{% + \egroup\noexpand\scanmacro{\macrobody}}% + \else % 10 or more: \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup - \noexpand\braceorline - \expandafter\noexpand\csname\the\macname @@@\endcsname}% - \expandafter\xdef\csname\the\macname @@@\endcsname##1{% - \egroup - \noexpand\scanmacro{\macrobody}% - }% - \else % at most 9 - \ifnum\paramno<10\relax - % @MACNAME sets the context for reading the macro argument - % @MACNAME@@ gets the argument, processes backslashes and appends a - % comma. - % @MACNAME@@@ removes braces surrounding the argument list. - % @MACNAME@@@@ scans the macro body with arguments substituted. - \expandafter\xdef\csname\the\macname\endcsname{% - \bgroup - \noexpand\expandafter % This \expandafter skip any spaces after the - \noexpand\macroargctxt % macro before we change the catcode of space. - \noexpand\expandafter - \expandafter\noexpand\csname\the\macname @@\endcsname}% - \expandafter\xdef\csname\the\macname @@\endcsname##1{% - \noexpand\passargtomacro - \expandafter\noexpand\csname\the\macname @@@\endcsname{##1,}}% - \expandafter\xdef\csname\the\macname @@@\endcsname##1{% - \expandafter\noexpand\csname\the\macname @@@@\endcsname ##1}% - \expandafter\expandafter - \expandafter\xdef - \expandafter\expandafter - \csname\the\macname @@@@\endcsname\paramlist{% - \egroup\noexpand\scanmacro{\macrobody}}% - \else % 10 or more: - \expandafter\xdef\csname\the\macname\endcsname{% - \noexpand\getargvals@{\the\macname}{\argl}% - }% - \global\expandafter\let\csname mac.\the\macname .body\endcsname\macrobody - \global\expandafter\let\csname mac.\the\macname .recurse\endcsname\norecurse - \fi + \noexpand\getargvals@{\the\macname}{\argl}% + }% + \global\expandafter\let\csname mac.\the\macname .body\endcsname\macrobody + \global\expandafter\let\csname mac.\the\macname .recurse\endcsname\gobble \fi \fi} @@ -8698,6 +8772,8 @@ end {% \requireauxfile \atdummies % preserve commands, but don't expand them + % match definition in \xrdef, \refx, \xrefX. + \def\value##1{##1}% \edef\writexrdef##1##2{% \write\auxfile{@xrdef{#1-% #1 of \setref, expanded by the \edef ##1}{##2}}% these are parameters of \writexrdef @@ -8790,8 +8866,8 @@ end \ifpdf % For pdfTeX and LuaTeX {\indexnofonts - \turnoffactive \makevalueexpandable + \turnoffactive % This expands tokens, so do it after making catcode changes, so _ % etc. don't get their TeX definitions. This ignores all spaces in % #4, including (wrongly) those in the middle of the filename. @@ -8799,19 +8875,18 @@ end % % This (wrongly) does not take account of leading or trailing % spaces in #1, which should be ignored. - \edef\pdfxrefdest{#1}% - \ifx\pdfxrefdest\empty - \def\pdfxrefdest{Top}% no empty targets - \else - \txiescapepdf\pdfxrefdest % escape PDF special chars + \setpdfdestname{#1}% + % + \ifx\pdfdestname\empty + \def\pdfdestname{Top}% no empty targets \fi % \leavevmode \startlink attr{/Border [0 0 0]}% \ifnum\filenamelength>0 - goto file{\the\filename.pdf} name{\pdfxrefdest}% + goto file{\the\filename.pdf} name{\pdfdestname}% \else - goto name{\pdfmkpgn{\pdfxrefdest}}% + goto name{\pdfmkpgn{\pdfdestname}}% \fi }% \setcolor{\linkcolor}% @@ -8820,8 +8895,8 @@ end \else % For XeTeX {\indexnofonts - \turnoffactive \makevalueexpandable + \turnoffactive % This expands tokens, so do it after making catcode changes, so _ % etc. don't get their TeX definitions. This ignores all spaces in % #4, including (wrongly) those in the middle of the filename. @@ -8829,29 +8904,27 @@ end % % This (wrongly) does not take account of leading or trailing % spaces in #1, which should be ignored. - \iftxiuseunicodedestname - \def\pdfxrefdest{#1}% Pass through Unicode characters. - \else - \edef\pdfxrefdest{#1}% Replace Unicode characters to ASCII. - \fi - \ifx\pdfxrefdest\empty - \def\pdfxrefdest{Top}% no empty targets - \else - \txiescapepdf\pdfxrefdest % escape PDF special chars + \setpdfdestname{#1}% + % + \ifx\pdfdestname\empty + \def\pdfdestname{Top}% no empty targets \fi % \leavevmode \ifnum\filenamelength>0 - % By the default settings, + % With default settings, % XeTeX (xdvipdfmx) replaces link destination names with integers. % In this case, the replaced destination names of - % remote PDF cannot be known. In order to avoid replacement, - % you can use commandline option `-C 0x0010' for xdvipdfmx. + % remote PDFs are no longer known. In order to avoid a replacement, + % you can use xdvipdfmx's command line option `-C 0x0010'. + % If you use XeTeX 0.99996+ (TeX Live 2016+), + % this command line option is no longer necessary + % because we can use the `dvipdfmx:config' special. \special{pdf:bann << /Border [0 0 0] /Type /Annot /Subtype /Link /A - << /S /GoToR /F (\the\filename.pdf) /D (name\pdfxrefdest) >> >>}% + << /S /GoToR /F (\the\filename.pdf) /D (\pdfdestname) >> >>}% \else \special{pdf:bann << /Border [0 0 0] /Type /Annot /Subtype /Link /A - << /S /GoTo /D (name\pdfxrefdest) >> >>}% + << /S /GoTo /D (\pdfdestname) >> >>}% \fi }% \setcolor{\linkcolor}% @@ -8862,6 +8935,7 @@ end % include an _ in the xref name, etc. \indexnofonts \turnoffactive + \def\value##1{##1}% \expandafter\global\expandafter\let\expandafter\Xthisreftitle \csname XR#1-title\endcsname }% @@ -9002,14 +9076,14 @@ end \fi\fi\fi } -% Define \refx{NAME}{SUFFIX} to reference a cross-reference string named NAME. -% If its value is nonempty, SUFFIX is output afterward. -% +% \refx{NAME}{SUFFIX} - reference a cross-reference string named NAME. SUFFIX +% is output afterwards if non-empty. \def\refx#1#2{% \requireauxfile {% \indexnofonts \otherbackslash + \def\value##1{##1}% \expandafter\global\expandafter\let\expandafter\thisrefX \csname XR#1\endcsname }% @@ -9034,16 +9108,18 @@ end #2% Output the suffix in any case. } -% This is the macro invoked by entries in the aux file. Usually it's -% just a \def (we prepend XR to the control sequence name to avoid -% collisions). But if this is a float type, we have more work to do. +% This is the macro invoked by entries in the aux file. Define a control +% sequence for a cross-reference target (we prepend XR to the control sequence +% name to avoid collisions). The value is the page number. If this is a float +% type, we have more work to do. % \def\xrdef#1#2{% - {% The node name might contain 8-bit characters, which in our current - % implementation are changed to commands like @'e. Don't let these - % mess up the control sequence name. + {% Expand the node or anchor name to remove control sequences. + % \turnoffactive stops 8-bit characters being changed to commands + % like @'e. \refx does the same to retrieve the value in the definition. \indexnofonts \turnoffactive + \def\value##1{##1}% \xdef\safexrefname{#1}% }% % @@ -9755,9 +9831,9 @@ directory should work if nowhere else does.} \global\righthyphenmin = #3\relax } -% XeTeX and LuaTeX can handle native Unicode. -% Their default I/O is UTF-8 sequence instead of byte-wise. -% Other TeX engine (pdfTeX etc.) I/O is byte-wise. +% XeTeX and LuaTeX can handle Unicode natively. +% Their default I/O uses UTF-8 sequences instead of a byte-wise operation. +% Other TeX engines' I/O (pdfTeX, etc.) is byte-wise. % \newif\iftxinativeunicodecapable \newif\iftxiusebytewiseio @@ -9881,14 +9957,15 @@ directory should work if nowhere else does.} % \else \ifx \declaredencoding \utfeight \iftxinativeunicodecapable - % For native Unicode (XeTeX and LuaTeX) + % For native Unicode handling (XeTeX and LuaTeX) \nativeunicodechardefs \else - % For UTF-8 byte sequence (TeX, eTeX and pdfTeX) + % For treating UTF-8 as byte sequences (TeX, eTeX and pdfTeX) \setnonasciicharscatcode\active % since we already invoked \utfeightchardefs at the top level - % (below), do not re-invoke it, then our check for duplicated - % definitions triggers. Making non-ascii chars active is enough. + % (below), do not re-invoke it, otherwise our check for duplicated + % definitions gets triggered. Making non-ascii chars active is + % sufficient. \fi % \else @@ -9899,6 +9976,18 @@ directory should work if nowhere else does.} \fi % latone \fi % lattwo \fi % ascii + % + \ifx\XeTeXrevision\thisisundefined + \else + \ifx \declaredencoding \utfeight + \else + \ifx \declaredencoding \ascii + \else + \message{Warning: XeTeX with non-UTF-8 encodings cannot handle % + non-ASCII characters in auxiliary files.}% + \fi + \fi + \fi } % emacs-page @@ -9930,18 +10019,18 @@ directory should work if nowhere else does.} \gdefchar^^a0{\tie} \gdefchar^^a1{\exclamdown} \gdefchar^^a2{{\tcfont \char162}} % cent - \gdefchar^^a3{\pounds} + \gdefchar^^a3{\pounds{}} \gdefchar^^a4{{\tcfont \char164}} % currency \gdefchar^^a5{{\tcfont \char165}} % yen \gdefchar^^a6{{\tcfont \char166}} % broken bar \gdefchar^^a7{\S} \gdefchar^^a8{\"{}} - \gdefchar^^a9{\copyright} + \gdefchar^^a9{\copyright{}} \gdefchar^^aa{\ordf} - \gdefchar^^ab{\guillemetleft} + \gdefchar^^ab{\guillemetleft{}} \gdefchar^^ac{\ensuremath\lnot} \gdefchar^^ad{\-} - \gdefchar^^ae{\registeredsymbol} + \gdefchar^^ae{\registeredsymbol{}} \gdefchar^^af{\={}} % \gdefchar^^b0{\textdegree} @@ -9955,7 +10044,7 @@ directory should work if nowhere else does.} \gdefchar^^b8{\cedilla\ } \gdefchar^^b9{$^1$} \gdefchar^^ba{\ordm} - \gdefchar^^bb{\guillemetright} + \gdefchar^^bb{\guillemetright{}} \gdefchar^^bc{$1\over4$} \gdefchar^^bd{$1\over2$} \gdefchar^^be{$3\over4$} @@ -10035,7 +10124,7 @@ directory should work if nowhere else does.} % Encoding is almost identical to Latin1. \latonechardefs % - \gdefchar^^a4{\euro} + \gdefchar^^a4{\euro{}} \gdefchar^^a6{\v S} \gdefchar^^a8{\v s} \gdefchar^^b4{\v Z} @@ -10064,7 +10153,7 @@ directory should work if nowhere else does.} \gdefchar^^ae{\v Z} \gdefchar^^af{\dotaccent Z} % - \gdefchar^^b0{\textdegree} + \gdefchar^^b0{\textdegree{}} \gdefchar^^b1{\ogonek{a}} \gdefchar^^b2{\ogonek{ }} \gdefchar^^b3{\l} @@ -10200,7 +10289,7 @@ directory should work if nowhere else does.} \countUTFx = "80 \countUTFy = "C2 \def\UTFviiiTmp{% - \gdef~{ + \gdef~{% \ifpassthroughchars $\fi}}% \UTFviiiLoop @@ -10236,8 +10325,9 @@ directory should work if nowhere else does.} \def\U#1{% \expandafter\ifx\csname uni:#1\endcsname \relax \iftxinativeunicodecapable - % Any Unicode characters can be used by native Unicode. - % However, if the font does not have the glyph, the letter will miss. + % All Unicode characters can be used if native Unicode handling is + % active. However, if the font does not have the glyph, + % letters are missing. \begingroup \uccode`\.="#1\relax \uppercase{.} @@ -10251,9 +10341,18 @@ directory should work if nowhere else does.} \fi } -% For UTF-8 byte sequence (TeX, e-TeX and pdfTeX) -% Definition macro to replace the Unicode character -% Definition macro that is used by @U command +% These macros are used here to construct the name of a control +% sequence to be defined. +\def\UTFviiiTwoOctetsName#1#2{% + \csname u8:#1\string #2\endcsname}% +\def\UTFviiiThreeOctetsName#1#2#3{% + \csname u8:#1\string #2\string #3\endcsname}% +\def\UTFviiiFourOctetsName#1#2#3#4{% + \csname u8:#1\string #2\string #3\string #4\endcsname}% + +% For UTF-8 byte sequences (TeX, e-TeX and pdfTeX), +% provide a definition macro to replace a Unicode character; +% this gets used by the @U command % \begingroup \catcode`\"=12 @@ -10267,17 +10366,18 @@ directory should work if nowhere else does.} \countUTFz = "#1\relax \begingroup \parseXMLCharref + + % Give \u8:... its definition. The sequence of seven \expandafter's + % expands after the \gdef three times, e.g. % - % Access definitions of characters given UTF-8 sequences - \def\UTFviiiTwoOctets##1##2{% - \csname u8:##1\string ##2\endcsname}% - \def\UTFviiiThreeOctets##1##2##3{% - \csname u8:##1\string ##2\string ##3\endcsname}% - \def\UTFviiiFourOctets##1##2##3##4{% - \csname u8:##1\string ##2\string ##3\string ##4\endcsname}% - \expandafter\expandafter\expandafter\expandafter - \expandafter\expandafter\expandafter - \gdef\UTFviiiTmp{#2}% + % 1. \UTFviiTwoOctetsName B1 B2 + % 2. \csname u8:B1 \string B2 \endcsname + % 3. \u8: B1 B2 (a single control sequence token) + % + \expandafter\expandafter + \expandafter\expandafter + \expandafter\expandafter + \expandafter\gdef \UTFviiiTmp{#2}% % \expandafter\ifx\csname uni:#1\endcsname \relax \else \message{Internal error, already defined: #1}% @@ -10287,45 +10387,61 @@ directory should work if nowhere else does.} \expandafter\globallet\csname uni:#1\endcsname \UTFviiiTmp \endgroup} % - % Given the value in \countUTFz as a Unicode code point, set \UTFviiiTmp. + % Given the value in \countUTFz as a Unicode code point, set \UTFviiiTmp + % to the corresponding UTF-8 sequence. \gdef\parseXMLCharref{% \ifnum\countUTFz < "A0\relax \errhelp = \EMsimple \errmessage{Cannot define Unicode char value < 00A0}% \else\ifnum\countUTFz < "800\relax \parseUTFviiiA,% - \parseUTFviiiB C\UTFviiiTwoOctets.,% + \parseUTFviiiB C\UTFviiiTwoOctetsName.,% \else\ifnum\countUTFz < "10000\relax \parseUTFviiiA;% \parseUTFviiiA,% - \parseUTFviiiB E\UTFviiiThreeOctets.{,;}% + \parseUTFviiiB E\UTFviiiThreeOctetsName.{,;}% \else \parseUTFviiiA;% \parseUTFviiiA,% \parseUTFviiiA!% - \parseUTFviiiB F\UTFviiiFourOctets.{!,;}% + \parseUTFviiiB F\UTFviiiFourOctetsName.{!,;}% \fi\fi\fi } + % Extract a byte from the end of the UTF-8 representation of \countUTFx. + % It must be a non-initial byte in the sequence. + % Change \uccode of #1 for it to be used in \parseUTFviiiB as one + % of the bytes. \gdef\parseUTFviiiA#1{% \countUTFx = \countUTFz \divide\countUTFz by 64 - \countUTFy = \countUTFz + \countUTFy = \countUTFz % Save to be the future value of \countUTFz. \multiply\countUTFz by 64 + + % \countUTFz is now \countUTFx with the last 5 bits cleared. Subtract + % in order to get the last five bits. \advance\countUTFx by -\countUTFz + + % Convert this to the byte in the UTF-8 sequence. \advance\countUTFx by 128 \uccode `#1\countUTFx \countUTFz = \countUTFy} - % Used to set \UTFviiiTmp to a UTF-8 byte sequence + % Used to put a UTF-8 byte sequence into \UTFviiiTmp + % #1 is the increment for \countUTFz to yield a the first byte of the UTF-8 + % sequence. + % #2 is one of the \UTFviii*OctetsName macros. + % #3 is always a full stop (.) + % #4 is a template for the other bytes in the sequence. The values for these + % bytes is substituted in here with \uppercase using the \uccode's. \gdef\parseUTFviiiB#1#2#3#4{% \advance\countUTFz by "#10\relax \uccode `#3\countUTFz \uppercase{\gdef\UTFviiiTmp{#2#3#4}}} \endgroup -% For native Unicode (XeTeX and LuaTeX) -% Definition macro that is set catcode other non global +% For native Unicode handling (XeTeX and LuaTeX), +% provide a definition macro that sets a catcode to `other' non-globally % \def\DeclareUnicodeCharacterNativeOther#1#2{% \catcode"#1=\other @@ -10349,18 +10465,18 @@ directory should work if nowhere else does.} \DeclareUnicodeCharacter{00A0}{\tie}% \DeclareUnicodeCharacter{00A1}{\exclamdown}% \DeclareUnicodeCharacter{00A2}{{\tcfont \char162}}% 0242=cent - \DeclareUnicodeCharacter{00A3}{\pounds}% + \DeclareUnicodeCharacter{00A3}{\pounds{}}% \DeclareUnicodeCharacter{00A4}{{\tcfont \char164}}% 0244=currency \DeclareUnicodeCharacter{00A5}{{\tcfont \char165}}% 0245=yen \DeclareUnicodeCharacter{00A6}{{\tcfont \char166}}% 0246=brokenbar \DeclareUnicodeCharacter{00A7}{\S}% \DeclareUnicodeCharacter{00A8}{\"{ }}% - \DeclareUnicodeCharacter{00A9}{\copyright}% + \DeclareUnicodeCharacter{00A9}{\copyright{}}% \DeclareUnicodeCharacter{00AA}{\ordf}% - \DeclareUnicodeCharacter{00AB}{\guillemetleft}% + \DeclareUnicodeCharacter{00AB}{\guillemetleft{}}% \DeclareUnicodeCharacter{00AC}{\ensuremath\lnot}% \DeclareUnicodeCharacter{00AD}{\-}% - \DeclareUnicodeCharacter{00AE}{\registeredsymbol}% + \DeclareUnicodeCharacter{00AE}{\registeredsymbol{}}% \DeclareUnicodeCharacter{00AF}{\={ }}% % \DeclareUnicodeCharacter{00B0}{\ringaccent{ }}% @@ -10374,7 +10490,7 @@ directory should work if nowhere else does.} \DeclareUnicodeCharacter{00B8}{\cedilla{ }}% \DeclareUnicodeCharacter{00B9}{$^1$}% \DeclareUnicodeCharacter{00BA}{\ordm}% - \DeclareUnicodeCharacter{00BB}{\guillemetright}% + \DeclareUnicodeCharacter{00BB}{\guillemetright{}}% \DeclareUnicodeCharacter{00BC}{$1\over4$}% \DeclareUnicodeCharacter{00BD}{$1\over2$}% \DeclareUnicodeCharacter{00BE}{$3\over4$}% @@ -10846,36 +10962,36 @@ directory should work if nowhere else does.} % Punctuation \DeclareUnicodeCharacter{2013}{--}% \DeclareUnicodeCharacter{2014}{---}% - \DeclareUnicodeCharacter{2018}{\quoteleft}% - \DeclareUnicodeCharacter{2019}{\quoteright}% - \DeclareUnicodeCharacter{201A}{\quotesinglbase}% - \DeclareUnicodeCharacter{201C}{\quotedblleft}% - \DeclareUnicodeCharacter{201D}{\quotedblright}% - \DeclareUnicodeCharacter{201E}{\quotedblbase}% + \DeclareUnicodeCharacter{2018}{\quoteleft{}}% + \DeclareUnicodeCharacter{2019}{\quoteright{}}% + \DeclareUnicodeCharacter{201A}{\quotesinglbase{}}% + \DeclareUnicodeCharacter{201C}{\quotedblleft{}}% + \DeclareUnicodeCharacter{201D}{\quotedblright{}}% + \DeclareUnicodeCharacter{201E}{\quotedblbase{}}% \DeclareUnicodeCharacter{2020}{\ensuremath\dagger}% \DeclareUnicodeCharacter{2021}{\ensuremath\ddagger}% - \DeclareUnicodeCharacter{2022}{\bullet}% + \DeclareUnicodeCharacter{2022}{\bullet{}}% \DeclareUnicodeCharacter{202F}{\thinspace}% - \DeclareUnicodeCharacter{2026}{\dots}% - \DeclareUnicodeCharacter{2039}{\guilsinglleft}% - \DeclareUnicodeCharacter{203A}{\guilsinglright}% + \DeclareUnicodeCharacter{2026}{\dots{}}% + \DeclareUnicodeCharacter{2039}{\guilsinglleft{}}% + \DeclareUnicodeCharacter{203A}{\guilsinglright{}}% % - \DeclareUnicodeCharacter{20AC}{\euro}% + \DeclareUnicodeCharacter{20AC}{\euro{}}% % - \DeclareUnicodeCharacter{2192}{\expansion}% - \DeclareUnicodeCharacter{21D2}{\result}% + \DeclareUnicodeCharacter{2192}{\expansion{}}% + \DeclareUnicodeCharacter{21D2}{\result{}}% % % Mathematical symbols \DeclareUnicodeCharacter{2200}{\ensuremath\forall}% \DeclareUnicodeCharacter{2203}{\ensuremath\exists}% \DeclareUnicodeCharacter{2208}{\ensuremath\in}% - \DeclareUnicodeCharacter{2212}{\minus}% + \DeclareUnicodeCharacter{2212}{\minus{}}% \DeclareUnicodeCharacter{2217}{\ast}% \DeclareUnicodeCharacter{221E}{\ensuremath\infty}% \DeclareUnicodeCharacter{2225}{\ensuremath\parallel}% \DeclareUnicodeCharacter{2227}{\ensuremath\wedge}% \DeclareUnicodeCharacter{2229}{\ensuremath\cap}% - \DeclareUnicodeCharacter{2261}{\equiv}% + \DeclareUnicodeCharacter{2261}{\equiv{}}% \DeclareUnicodeCharacter{2264}{\ensuremath\leq}% \DeclareUnicodeCharacter{2265}{\ensuremath\geq}% \DeclareUnicodeCharacter{2282}{\ensuremath\subset}% @@ -11031,8 +11147,8 @@ directory should work if nowhere else does.} \newif\ifpassthroughchars \passthroughcharsfalse -% For native Unicode (XeTeX and LuaTeX) -% Definition macro to replace / pass-through the Unicode character +% For native Unicode handling (XeTeX and LuaTeX), +% provide a definition macro to replace/pass-through a Unicode character % \def\DeclareUnicodeCharacterNative#1#2{% \catcode"#1=\active @@ -11055,21 +11171,22 @@ directory should work if nowhere else does.} \endgroup } -% Native Unicode (XeTeX and LuaTeX) character replacing definitions -% It makes the setting that replace the Unicode characters. +% Native Unicode handling (XeTeX and LuaTeX) character replacing definition. +% It activates the setting that replaces Unicode characters. \def\nativeunicodechardefs{% \let\DeclareUnicodeCharacter\DeclareUnicodeCharacterNative \unicodechardefs } -% For native Unicode (XeTeX and LuaTeX). Make the character token expand +% For native Unicode handling (XeTeX and LuaTeX), +% make the character token expand % to the sequences given in \unicodechardefs for printing. \def\DeclareUnicodeCharacterNativeAtU#1#2{% \def\UTFAtUTmp{#2} \expandafter\globallet\csname uni:#1\endcsname \UTFAtUTmp } -% Native Unicode (XeTeX and LuaTeX) @U command definitions +% @U command definitions for native Unicode handling (XeTeX and LuaTeX). \def\nativeunicodechardefsatu{% \let\DeclareUnicodeCharacter\DeclareUnicodeCharacterNativeAtU \unicodechardefs @@ -11080,7 +11197,7 @@ directory should work if nowhere else does.} \relax } -% define all the unicode characters we know about, for the sake of @U. +% define all Unicode characters we know about, for the sake of @U. \iftxinativeunicodecapable \nativeunicodechardefsatu \else @@ -11556,7 +11673,4 @@ directory should work if nowhere else does.} @c vim:sw=2: -@ignore - arch-tag: e1b36e32-c96e-4135-a41a-0b2efa2ea115 -@end ignore @enablebackslashhack diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index dae514033f8..1ba22e0b594 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -12,14 +12,11 @@ @c configure.ac, so you should edit that file and run @c "autoconf && ./configure" to change the version number. -@c Additionally, flags are set with respect to the Emacs flavor; and -@c depending whether Tramp is packaged into (X)Emacs, or standalone. - @include trampver.texi -@c Macro for formatting a file name according to the respective syntax. -@c Macro arguments should not have any leading or -@c trailing whitespace. Not very elegant, but I don't know it better. +@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 @@ -51,56 +48,39 @@ copy and modify this GNU manual.'' @end copying @c Entries for @command{install-info} to use -@dircategory @value{emacsname} network features +@dircategory Emacs network features @direntry * TRAMP: (tramp). Transparent Remote Access, Multiple Protocol - @value{emacsname} remote file access via ssh and scp. + Emacs remote file access via ssh and scp. @end direntry @titlepage @title @value{tramp} version @value{trampver} User Manual @author by Daniel Pittman @author based on documentation by Kai Großjohann -@page -@insertcopying @end titlepage @contents -@ifnottex @node Top, Overview, (dir), (dir) @top @value{tramp} version @value{trampver} User Manual This file documents @value{tramp} version @value{trampver}, a remote file -editing package for @value{emacsname}. +editing package for Emacs. @value{tramp} stands for ``Transparent Remote (file) Access, Multiple Protocol''. This package provides remote file editing, similar to -@value{ftppackagename}. +Ange FTP. -The difference is that @value{ftppackagename} uses FTP to transfer -files between the local and the remote host, whereas @value{tramp} uses a -combination of @command{rsh} and @command{rcp} or other work-alike -programs, such as @command{ssh}/@command{scp}. +The difference is that Ange FTP uses FTP to transfer files between the +local and the remote host, whereas @value{tramp} uses a combination of +@command{rsh} and @command{rcp} or other work-alike programs, such as +@command{ssh}/@command{scp}. You can find the latest version of this document on the web at @uref{http://www.gnu.org/software/tramp/}. -@c Pointer to the other Emacs flavor is necessary only in case of -@c standalone installation. -@ifset installchapter -The manual has been generated for @value{emacsname}. -@ifinfo -If you want to read the info pages for @value{emacsothername}, you -should read in @ref{Installation} how to create them. -@end ifinfo -@ifhtml -If you're using the other Emacs flavor, you should read the -@uref{@value{emacsotherfilename}, @value{emacsothername}} pages. -@end ifhtml -@end ifset - @ifhtml The latest release of @value{tramp} is available for @uref{ftp://ftp.gnu.org/gnu/tramp/, download}, or you may see @@ -115,20 +95,10 @@ There is a mailing list for @value{tramp}, available at @email{tramp-devel@@gnu.org}, and archived at @uref{http://lists.gnu.org/archive/html/tramp-devel/, the @value{tramp} Mail Archive}. -@ifhtml -Older archives are located at -@uref{http://sourceforge.net/mailarchive/forum.php?forum=tramp-devel, -SourceForge Mail Archive} and -@uref{http://www.mail-archive.com/emacs-rcp@@ls6.cs.uni-dortmund.de/, -The Mail Archive}. -@c in HTML output, there's no new paragraph. -@*@* -@end ifhtml +@page @insertcopying -@end ifnottex - @menu * Overview:: What @value{tramp} can and cannot do. @@ -137,7 +107,7 @@ For the end user: * Obtaining Tramp:: How to obtain @value{tramp}. * History:: History of @value{tramp}. @ifset installchapter -* Installation:: Installing @value{tramp} with your @value{emacsname}. +* Installation:: Installing @value{tramp} with your Emacs. @end ifset * Configuration:: Configuring @value{tramp} for use. * Usage:: An overview of the operation of @value{tramp}. @@ -150,7 +120,6 @@ For the developer: How file names, directories and localnames are mangled and managed. * Traces and Profiles:: How to Customize Traces. -* Issues:: Debatable Issues and What Was Decided. * GNU Free Documentation License:: The license for this documentation. * Function Index:: @value{tramp} functions. @@ -161,7 +130,7 @@ For the developer: --- The Detailed Node Listing --- @c @ifset installchapter -Installing @value{tramp} with your @value{emacsname} +Installing @value{tramp} with your Emacs * Installation parameters:: Parameters in order to control installation. * Load paths:: How to plug-in @value{tramp} into your environment. @@ -173,16 +142,12 @@ Configuring @value{tramp} for use * Connection types:: Types of connections to remote hosts. * Inline methods:: Inline methods. * External methods:: External methods. -@ifset emacsgvfs * GVFS based methods:: GVFS based external methods. -@end ifset -@ifset emacsgw -* Gateway methods:: Gateway methods. -@end ifset * Default Method:: Selecting a default method. * Default User:: Selecting a default user. * Default Host:: Selecting a default host. * Multi-hops:: Connecting to a remote host using multiple hops. +* Firewalls:: Passing firewalls. * Customizing Methods:: Using Non-Standard Methods. * Customizing Completion:: Selecting config files for user/host name completion. * Password handling:: Reusing passwords for several connections. @@ -200,15 +165,13 @@ Using @value{tramp} * File name Syntax:: @value{tramp} file name conventions. * File name completion:: File name completion. * Ad-hoc multi-hops:: Declaring multiple hops in the file name. -* Remote processes:: Integration with other @value{emacsname} packages. +* Remote processes:: Integration with other Emacs packages. * Cleanup remote connections:: Cleanup remote connections. How file names, directories and localnames are mangled and managed * Localname deconstruction:: Breaking a localname into its components. -@ifset emacs * External packages:: Integration with external Lisp packages. -@end ifset @end detailmenu @end menu @@ -219,10 +182,9 @@ How file names, directories and localnames are mangled and managed @cindex overview @value{tramp} is for transparently accessing remote files from within -@value{emacsname}. @value{tramp} enables an easy, convenient, and -consistent interface to remote files as if they are local files. -@value{tramp}'s transparency extends to editing, version control, and -@code{dired}. +Emacs. @value{tramp} enables an easy, convenient, and consistent +interface to remote files as if they are local files. @value{tramp}'s +transparency extends to editing, version control, and @code{dired}. @value{tramp} can access remote hosts using any number of access methods, such as @command{rsh}, @command{rlogin}, @command{telnet}, @@ -245,7 +207,7 @@ and transparent access. @value{tramp} temporarily transfers a remote file's contents to the local host editing and related operations. @value{tramp} can also transfer files between hosts using standard Emacs interfaces, a -benefit of direct integration of @value{tramp} in @value{emacsname}. +benefit of direct integration of @value{tramp} in Emacs. @value{tramp} can transfer files using any number of available host programs for remote files, such as @command{rcp}, @command{scp}, @@ -279,8 +241,7 @@ first time connection to that host, here's what happens: @value{tramp} invokes @samp{telnet @var{host}} or @samp{rsh @var{host} -l @var{user}} and establishes an external process to connect to the remote host. @value{tramp} communicates with the process through an -@value{emacsname} buffer, which also shows output from the remote -host. +Emacs buffer, which also shows output from the remote host. @item The remote host may prompt for a login name (for @command{telnet}, for @@ -358,7 +319,7 @@ behind the scenes when you open a file with @value{tramp}. @c For the end user @node Obtaining Tramp -@chapter Obtaining Tramp. +@chapter Obtaining @value{tramp} @cindex obtaining Tramp @value{tramp} is included as part of Emacs (since Emacs version 22.1). @@ -380,16 +341,20 @@ navigation bar at the top. Another way is to follow the terminal session below: @example -] @strong{cd ~/@value{emacsdir}} +@group +] @strong{cd ~/emacs} ] @strong{git clone git://git.savannah.gnu.org/tramp.git} +@end group @end example @noindent From behind a firewall: @example +@group ] @strong{git config --global http.proxy http://user:pwd@@proxy.server.com:8080} ] @strong{git clone http://git.savannah.gnu.org/r/tramp.git} +@end group @end example @noindent @@ -400,15 +365,17 @@ Tramp developers: @end example @noindent -After one of the above commands, @file{~/@value{emacsdir}/tramp} will +After one of the above commands, @file{~/emacs/tramp} will containing the latest version of @value{tramp}. @noindent To fetch updates from the repository, use git pull: @example -] @strong{cd ~/@value{emacsdir}/tramp} +@group +] @strong{cd ~/emacs/tramp} ] @strong{git pull} +@end group @end example @noindent @@ -416,8 +383,10 @@ Run @command{autoconf} as follows to generate an up-to-date @file{configure} script: @example -] @strong{cd ~/@value{emacsdir}/tramp} +@group +] @strong{cd ~/emacs/tramp} ] @strong{autoconf} +@end group @end example @@ -436,23 +405,14 @@ 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. -@ifset emacsgw -Support for gateways since April 2007. -@end ifset -@ifset emacsgvfs -GVFS integration started in February 2009. -@end ifset -@ifset emacs -Remote commands on Windows hosts since September 2011. -@end ifset -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}. - -In December 2001, XEmacs package repository adds @value{tramp}. +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 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 has been stopped in January 2016. @c Installation chapter is necessary only in case of standalone @c installation. Text taken from trampinst.texi. @@ -469,21 +429,23 @@ In December 2001, XEmacs package repository adds @value{tramp}. @value{tramp} is initially configured to use the @command{scp} program to connect to the remote host. Just type @kbd{C-x C-f} and then enter file name @file{@trampf{user@@host,/path/to.file}}. For details, -see @xref{Default Method}. +@xref{Default Method}, @xref{Default User}, @xref{Default Host}. -For problems related to the behavior of remote shell, see @ref{Remote -shell setup} for details. +For problems related to the behavior of the remote shell, @xref{Remote +shell setup}. For changing the connection type and file access method from the -defaults to one of several other options, see (@pxref{Connection -types}). +defaults to one of several other options, @xref{Connection types}. -@strong{Note} that some user options and variables described in these -examples are not auto loaded by @value{emacsname}. All examples -require @value{tramp} is installed and loaded: +@strong{Note} that some user options described in these examples are +not auto loaded by Emacs. All examples require @value{tramp} is +installed and loaded: @lisp -(require 'tramp) +@group +(custom-set-variables + '(tramp-verbose 6 nil (tramp) "Enable remote command traces")) +@end group @end lisp @@ -491,12 +453,7 @@ require @value{tramp} is installed and loaded: * Connection types:: Types of connections to remote hosts. * Inline methods:: Inline methods. * External methods:: External methods. -@ifset emacsgvfs * GVFS based methods:: GVFS based external methods. -@end ifset -@ifset emacsgw -* Gateway methods:: Gateway methods. -@end ifset * Default Method:: Selecting a default method. Here we also try to help those who don't have the foggiest which method @@ -504,6 +461,7 @@ require @value{tramp} is installed and loaded: * Default User:: Selecting a default user. * Default Host:: Selecting a default host. * Multi-hops:: Connecting to a remote host using multiple hops. +* Firewalls:: Passing firewalls. * Customizing Methods:: Using Non-Standard Methods. * Customizing Completion:: Selecting config files for user/host name completion. * Password handling:: Reusing passwords for several connections. @@ -529,11 +487,6 @@ they differ in the file access methods. Choosing the right method becomes important for editing files, transferring large files, or operating on a large number of files. -@cindex inline methods -@cindex external methods -@cindex methods, inline -@cindex methods, external - The performance of the external methods is generally better than that of the inline methods, at least for large files. This is caused by the need to encode and decode the data when transferring inline. @@ -561,7 +514,7 @@ Inline methods use the same login connection to transfer file contents. Inline methods are quick and easy for small files. They depend on the availability of suitable encoding and decoding programs on the remote host. For local source and destination, @value{tramp} -may use built-in equivalents of such programs in @value{emacsname}. +may use built-in equivalents of such programs in Emacs. Inline methods can work in situations where an external transfer program is unavailable. Inline methods also work when transferring @@ -582,8 +535,9 @@ unavailable, @value{tramp} first transfers a small Perl program to the remote host, and then tries that program for encoding and decoding. To increase transfer speeds for large text files, use compression -before encoding. The variable @var{tramp-inline-compress-start-size} -specifies the file size for such optimization. +before encoding. The user option +@option{tramp-inline-compress-start-size} specifies the file size for +such optimization. @table @asis @item @option{rsh} @@ -593,7 +547,6 @@ specifies the file size for such optimization. @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 @@ -604,7 +557,7 @@ remote host. @command{ssh} can also take extra parameters as port numbers. For example, a host on port 42 is specified as @file{host#42} (the real host name, a hash sign, then a port number). It is the same as passing -@code{-p 42} to the @command{ssh} command. +@samp{-p 42} to the @command{ssh} command. @item @option{telnet} @cindex method telnet @@ -613,7 +566,6 @@ host name, a hash sign, then a port number). It is the same as passing 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 @@ -630,6 +582,22 @@ the host returned by the function @command{(system-name)}. See Similar to @option{su} method, @option{sudo} uses @command{sudo}. @command{sudo} must have sufficient rights to start a shell. +@item @option{doas} +@cindex method doas +@cindex doas method + +This method is used on OpenBSD like the @command{sudo} command. + +@item @option{sg} +@cindex method sg +@cindex 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 +@command{(system-name)}. The user name must be specified, but it +denotes a group name. See @ref{Multi-hops} for an exception to this +behavior. + @item @option{sshx} @cindex method sshx @cindex sshx method @@ -666,7 +634,6 @@ This method is also similar to @option{ssh}. It uses the This is another method from the Kerberos suite. It behaves like @option{su}. - @item @option{plink} @cindex method plink @cindex plink method @@ -680,7 +647,6 @@ session. @option{plink} method supports the @samp{-P} argument. - @item @option{plinkx} @cindex method plinkx @cindex plinkx method @@ -712,7 +678,7 @@ files smaller than @var{tramp-copy-size-limit} still use inline methods. @table @asis -@item @option{rcp}---@command{rsh} and @command{rcp} +@item @option{rcp} @cindex method rcp @cindex rcp method @cindex rcp (with rcp method) @@ -725,7 +691,7 @@ access method available. The alternative method @option{remcp} uses the @command{remsh} and @command{rcp} commands. -@item @option{scp}---@command{ssh} and @command{scp} +@item @option{scp} @cindex method scp @cindex scp method @cindex scp (with scp method) @@ -742,7 +708,7 @@ port numbers. For example, @file{host#42} passes @samp{-p 42} in the argument list to @command{ssh}, and @samp{-P 42} in the argument list to @command{scp}. -@item @option{rsync}---@command{ssh} and @command{rsync} +@item @option{rsync} @cindex method rsync @cindex rsync method @cindex rsync (with rsync method) @@ -757,8 +723,7 @@ is lost if the file exists only on one side of the connection. This method supports the @samp{-p} argument. - -@item @option{scpx}---@command{ssh} and @command{scp} +@item @option{scpx} @cindex method scpx @cindex scpx method @cindex scp (with scpx method) @@ -768,15 +733,14 @@ This method supports the @samp{-p} argument. in performance to @option{scp}. @option{scpx} uses @samp{ssh -t -t @var{host} -l @var{user} /bin/sh} to open a connection. -@option{sshx} is useful for Windows users when @command{ssh} triggers +@option{scpx} is useful for Windows users when @command{ssh} triggers an error about allocating a pseudo tty. This happens due to missing shell prompts that confuses @value{tramp}. This method supports the @samp{-p} argument. - -@item @option{pscp}---@command{plink} and @command{pscp} -@item @option{psftp}---@command{plink} and @command{psftp} +@item @option{pscp} +@item @option{psftp} @cindex method pscp @cindex pscp method @cindex pscp (with pscp method) @@ -798,8 +762,7 @@ session. These methods support the @samp{-P} argument. - -@item @option{fcp}---@command{fsh} and @command{fcp} +@item @option{fcp} @cindex method fcp @cindex fcp method @cindex fsh (with fcp method) @@ -822,7 +785,7 @@ The command used for this connection is: @samp{fsh @var{host} -l not useful for @value{tramp}. @command{fsh} connects to remote host and @value{tramp} keeps that one connection open. -@item @option{nc}---@command{telnet} and @command{nc} +@item @option{nc} @cindex method nc @cindex nc method @cindex nc (with nc method) @@ -839,15 +802,10 @@ decode programs. @cindex ftp method When @value{tramp} uses @option{ftp}, it forwards requests to whatever -ftp program is specified by @value{ftppackagename}. This external -program must be capable of servicing requests from @value{tramp}. - -@ifset xemacs -This method works only for unified file names, see @ref{Issues}. -@end ifset - +ftp program is specified by Ange FTP. This external program must be +capable of servicing requests from @value{tramp}. -@item @option{smb}---@command{smbclient} +@item @option{smb} @cindex method smb @cindex smb method @@ -866,7 +824,7 @@ Since SMB shares end in the @code{$} character, @value{tramp} must use substitutions. When @value{tramp} is not specific about the share name or uses the -generic remote directory @code{/}, @command{smbclient} returns all +generic remote directory @file{/}, @command{smbclient} returns all available shares. Since SMB authentication is based on each SMB share, @value{tramp} @@ -905,9 +863,9 @@ uses the anonymous user (without prompting for password). This behavior is unlike other @value{tramp} methods, where local user name is substituted. -The @option{smb} method is unavailable if @value{emacsname} is run under a -local user authentication context in MS Windows. However such users -can still access remote files using UNC file names instead of @value{tramp}: +The @option{smb} method is unavailable if Emacs is run under a local +user authentication context in MS Windows. However such users can +still access remote files using UNC file names instead of @value{tramp}: @example //melancholia/daniel$$/.emacs @@ -925,20 +883,20 @@ can. This method uses Android Debug Bridge program for accessing Android devices. The Android Debug Bridge must be installed locally for @value{tramp} to work. Some GNU/Linux distributions provide Android -Debug Bridge as an installation package. Alternatively, the program is -installed as part of the Android SDK@. @value{tramp} finds the +Debug Bridge as an installation package. Alternatively, the program +is installed as part of the Android SDK@. @value{tramp} finds the @command{adb} program either via the @env{PATH} environment variable -or the absolute path set in the variable @var{tramp-adb-program}. +or the absolute path set in the user option @option{tramp-adb-program}. @value{tramp} connects to Android devices with @option{adb} only when -the custom option @option{tramp-adb-connect-if-not-connected} is not +the user option @option{tramp-adb-connect-if-not-connected} is not @code{nil}. Otherwise, the connection must be established outside -@value{emacsname}. +Emacs. @value{tramp} does not require a host name part of the remote file name when a single Android device is connected to @command{adb}. -@value{tramp} instead uses @file{@trampfn{adb,,}} as the default -name. @command{adb devices} shows available host names. +@value{tramp} instead uses @file{@trampfn{adb,,}} as the default name. +@command{adb devices} shows available host names. @option{adb} method normally does not need user name to authenticate on the Android device because it runs under the @command{adbd} @@ -955,7 +913,6 @@ numbers are not applicable to Android devices connected through USB@. @end table -@ifset emacsgvfs @node GVFS based methods @section GVFS based external methods @cindex methods, gvfs @@ -967,9 +924,9 @@ GVFS is the virtual file system for the Gnome Desktop, mounted locally through FUSE and @value{tramp} uses this locally mounted directory internally. -@value{emacsname} uses the D-Bus mechanism to communicate with GVFS@. -@value{emacsname} must have the message bus system, D-Bus integration -active, @pxref{Top, , D-Bus, dbus}. +Emacs uses the D-Bus mechanism to communicate with GVFS@. Emacs must +have the message bus system, D-Bus integration active, @pxref{Top, , +D-Bus, dbus}. @table @asis @item @option{afp} @@ -992,6 +949,22 @@ syntax requires a leading volume (share) name, for example: based on standard protocols, such as HTTP@. @option{davs} does the same but with SSL encryption. Both methods support the port numbers. +@item @option{gdrive} +@cindex method gdrive +@cindex gdrive method +@cindex Google Drive + +Via the @option{gdrive} method it is possible to access your Google +Drive online storage. User and host name of the remote file name are +your email address of the Google Drive credentials, like +@file{@trampfn{gdrive,john.doe@@gmail.com,/}}. These credentials must +be populated in your @command{Online Accounts} application outside Emacs. + +Since Google Drive uses cryptic blob file names internally, +@value{tramp} works with the @code{display-name} of the files. This +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 @@ -999,7 +972,6 @@ but with SSL encryption. Both methods support the port numbers. OBEX is an FTP-like access protocol for cell phones and similar simple devices. @value{tramp} supports OBEX over Bluetooth. - @item @option{sftp} @cindex method sftp @cindex sftp method @@ -1019,81 +991,32 @@ requires the SYNCE-GVFS plugin. @end table @defopt tramp-gvfs-methods -@vindex tramp-gvfs-methods -This custom option is a list of external methods for GVFS@. By -default, this list includes @option{afp}, @option{dav}, @option{davs}, -@option{obex}, @option{sftp} and @option{synce}. Other methods to -include are: @option{ftp} and @option{smb}. +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}. @end defopt -@end ifset - - -@ifset emacsgw -@node Gateway methods -@section Gateway methods -@cindex methods, gateway -@cindex gateway methods - -Gateway methods are for proxy host declarations (@pxref{Multi-hops}) -so as to pass through firewalls and proxy servers. They are not like -the other methods that declare direct connections to a remote host. - -A gateway method always comes with a port setting. @value{tramp} -targets the port number with the gateway method -@file{localhost#random_port} from where the firewall or proxy server -is accessed. - -Gateway methods support user name and password declarations for -authenticating the corresponding firewall or proxy server. Such -authentication can be passed through only if granted access by system -administrators. - -@table @asis -@item @option{tunnel} -@cindex method tunnel -@cindex tunnel method - -This method implements an HTTP tunnel via the @command{CONNECT} -command (conforming to RFC 2616, 2817 specifications). Proxy servers -using HTTP version 1.1 or later protocol support this command. - -For authentication, this protocol uses only @option{Basic -Authentication} (see RFC 2617). When no port number is specified, this -protocol defaults to @option{8080}. - - -@item @option{socks} -@cindex method socks -@cindex socks method - -The @option{socks} method connects to SOCKSv5 servers (see RFC 1928) -and supports @option{Username/Password Authentication}. - -The default port number for the socks server is @option{1080}, if not -specified otherwise. - -@end table -@end ifset @node Default Method @section Selecting a default method @cindex default method -@vindex tramp-default-method -@vindex tramp-default-method-alist -Default method is for transferring files. The variable -@code{tramp-default-method} sets it. @value{tramp} uses this variable -to determine the default method for tramp file names that do not have -one specified. +@defopt tramp-default-method +Default method is for transferring files. The user option +@option{tramp-default-method} sets it. @value{tramp} uses this user +option to determine the default method for remote file names that do +not have one specified. @lisp -(setq tramp-default-method "ssh") +(custom-set-variables '(tramp-default-method "ssh" nil (tramp))) @end lisp +@end defopt +@defopt tramp-default-method-alist Default methods for transferring files can be customized for specific -user and host combinations through the alist variable -@code{tramp-default-method-alist}. +user and host combinations through the user option +@option{tramp-default-method-alist}. For example, the following two lines specify to use the @option{ssh} method for all user names matching @samp{john} and the @option{rsync} @@ -1102,22 +1025,18 @@ specifies to use the @option{su} method for the user @samp{root} on the host @samp{localhost}. @lisp +@group (add-to-list 'tramp-default-method-alist '("" "john" "ssh")) (add-to-list 'tramp-default-method-alist '("lily" "" "rsync")) (add-to-list 'tramp-default-method-alist '("\\`localhost\\'" "\\`root\\'" "su")) +@end group @end lisp +@end defopt @noindent -See the documentation for the variable -@code{tramp-default-method-alist} for details. - -@noindent -External methods performance faster for large files. - -@noindent -@xref{Inline methods}. -@xref{External methods}. +External methods performance faster for large files. @pxref{Inline +methods}. @pxref{External methods}. Choosing the access method also depends on the security environment. For example, @option{rsh} and @option{telnet} methods that use clear @@ -1169,85 +1088,91 @@ improvement is not always true. @node Default User @section Selecting a default user @cindex default user -@vindex tramp-default-user -@vindex tramp-default-user-alist +@defopt tramp-default-user @value{tramp} file name can omit the user name part since @value{tramp} substitutes the currently logged-in user name. However -this substitution can be overridden with @code{tramp-default-user}. +this substitution can be overridden with @option{tramp-default-user}. For example: @lisp -(setq tramp-default-user "root") +(custom-set-variables'(tramp-default-user "root" nil (tramp))) @end lisp +@end defopt -Instead of a single default user, @code{tramp-default-user-alist} +@defopt tramp-default-user-alist +Instead of a single default user, @option{tramp-default-user-alist} allows multiple default user values based on access method or host name combinations. The alist can hold multiple values. For example, to use the @samp{john} as the default user for the domain @samp{somewhere.else} only: @lisp +@group (add-to-list 'tramp-default-user-alist '("ssh" ".*\\.somewhere\\.else\\'" "john")) +@end group @end lisp -@noindent -See the documentation for the variable @code{tramp-default-user-alist} -for more details. - A Caution: @value{tramp} will override any default user specified in -the configuration files outside @value{emacsname}, such as -@file{~/.ssh/config}. To stop @value{tramp} from applying the default -value, set the corresponding alist entry to nil: +the configuration files outside Emacs, such as @file{~/.ssh/config}. +To stop @value{tramp} from applying the default value, set the +corresponding alist entry to nil: @lisp +@group (add-to-list 'tramp-default-user-alist '("ssh" "\\`here\\.somewhere\\.else\\'" nil)) +@end group @end lisp -The last entry in @code{tramp-default-user-alist} should be reserved +The last entry in @option{tramp-default-user-alist} should be reserved for catch-all or most often used login. @lisp +@group (add-to-list 'tramp-default-user-alist '(nil nil "jonas") t) +@end group @end lisp +@end defopt @node Default Host @section Selecting a default host @cindex default host -@vindex tramp-default-host -@vindex tramp-default-host-alist +@defopt tramp-default-host When host name is omitted, @value{tramp} substitutes the value from -the @code{tramp-default-host} variable. It is initially populated with -the local hostname where @value{emacsname} is running. Both the +the @option{tramp-default-host} user option. It is initially +populated with the local hostname where Emacs is running. Both the default user and default host can be overridden as follows: @lisp -(setq tramp-default-user "john" - tramp-default-host "target") +@group +(custom-set-variables + '(tramp-default-user "john" nil (tramp)) + '(tramp-default-host "target" nil (tramp))) +@end group @end lisp With both defaults set, @samp{@trampfn{ssh,,}} will connect -@value{tramp} to John's home directory on target. +@value{tramp} to John's home directory on @code{target}. -@ifset emacs @strong{Note} @samp{/::} won't work, because @samp{/:} is the prefix for quoted file names. -@end ifset +@ifinfo +@pxref{Quoted File Names, , , emacs}. +@end ifinfo +@end defopt -Instead of a single default host, @code{tramp-default-host-alist} +@defopt tramp-default-host-alist +Instead of a single default host, @option{tramp-default-host-alist} allows multiple default host values based on access method or user name combinations. The alist can hold multiple values. While -@code{tramp-default-host} is sufficient in most cases, some methods, +@option{tramp-default-host} is sufficient in most cases, some methods, like @option{adb}, require defaults overwritten. - -@noindent -See the documentation for the variable @code{tramp-default-host-alist} -for more details. +@end defopt @node Multi-hops @@ -1263,10 +1188,9 @@ hop kind, where the start and end points of the connection did not have intermediate check points. @defopt tramp-default-proxies-alist -@vindex tramp-default-proxies-alist @option{tramp-default-proxies-alist} specifies proxy hosts to pass -through. This variable is list of triples consisting of (@var{host} -@var{user} @var{proxy}). +through. This user option is list of triples consisting of +@code{(@var{host} @var{user} @var{proxy})}. The first match is the proxy host through which passes the file name and the target host matching @var{user}@@@var{host}. @var{host} and @@ -1276,24 +1200,20 @@ regular expression which always matches. @var{proxy} is a literal @value{tramp} file name whose local name part is ignored, and the method and user name parts are optional. -@ifset emacsgw -The method must be an inline or gateway method (@pxref{Inline -methods}, @pxref{Gateway methods}). -@end ifset -@ifclear emacsgw -The method must be an inline method (@pxref{Inline methods}). -@end ifclear -If @var{proxy} is @code{nil}, no additional hop is required reaching +The method must be an inline method (@pxref{Inline methods}). If +@var{proxy} is @code{nil}, no additional hop is required reaching @var{user}@@@var{host}. For example, to pass through the host @samp{bastion.your.domain} as user @samp{bird} to reach remote hosts outside the local domain: @lisp +@group (add-to-list 'tramp-default-proxies-alist '("\\." nil "@trampfn{ssh,bird@@bastion.your.domain,}")) (add-to-list 'tramp-default-proxies-alist '("\\.your\\.domain\\'" nil nil)) +@end group @end lisp @strong{Note}: @code{add-to-list} adds elements at the beginning of a @@ -1304,10 +1224,12 @@ called @samp{jump.your.domain}, which is the only host allowed to connect to @samp{bastion.your.domain}, then: @lisp +@group (add-to-list 'tramp-default-proxies-alist '("\\`bastion\\.your\\.domain\\'" "\\`bird\\'" "@trampfn{ssh,jump.your.domain,}")) +@end group @end lisp @var{proxy} can take patterns @code{%h} or @code{%u} for @var{host} or @@ -1318,13 +1240,15 @@ To login as @samp{root} on remote hosts in the domain access, then use this alist entry: @lisp +@group (add-to-list 'tramp-default-proxies-alist '("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh,%h,}")) +@end group @end lisp -Opening @file{@trampfn{sudo,randomhost.your.domain,}} first -connects to @samp{randomhost.your.domain} via @code{ssh} under your -account name, and then perform @code{sudo -u root} on that host. +Opening @file{@trampfn{sudo,randomhost.your.domain,}} first connects +to @samp{randomhost.your.domain} via @code{ssh} under your account +name, and then perform @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. @@ -1337,37 +1261,13 @@ local one, first connect via @command{ssh}, and then apply @command{sudo -u root}: @lisp +@group (add-to-list 'tramp-default-proxies-alist '(nil "\\`root\\'" "@trampfn{ssh,%h,}")) (add-to-list 'tramp-default-proxies-alist '((regexp-quote (system-name)) nil nil)) +@end group @end lisp - -The above configuration allows @value{tramp} connection as @samp{root} -to remote Ubuntu hosts. - -@ifset emacsgw -@code{tramp-default-proxies-alist} is also used for passing through -firewalls or proxy servers. - -For example, the local host @samp{proxy.your.domain} on port 3128 -serves as HTTP proxy to the outer world. User has access rights to -another proxy server on @samp{host.other.domain}.@footnote{HTTP tunnels -are intended for secure SSL/TLS communication. Therefore, many proxy -servers restrict the tunnels to related target ports. You might need -to run your ssh server on your target host @samp{host.other.domain} on -such a port, like 443 (https). See -@uref{http://savannah.gnu.org/maintenance/CvsFromBehindFirewall} for -discussion of ethical issues.} Then the configuration is: - -@lisp -(add-to-list 'tramp-default-proxies-alist - '("\\`host\\.other\\.domain\\'" nil - "@trampfn{tunnel,proxy.your.domain#3128,}")) -@end lisp - -Gateway methods in a multiple hop chain can be declared only as the first hop. -@end ifset @end defopt Passing through hops involves dealing with restricted shells, such as @@ -1375,7 +1275,6 @@ Passing through hops involves dealing with restricted shells, such as them for proxies only. @defopt tramp-restricted-shell-hosts-alist -@vindex tramp-restricted-shell-hosts-alist An alist of regular expressions of hosts running restricted shells, such as @command{rbash}. @value{tramp} will then use them only as proxies. @@ -1384,12 +1283,58 @@ To specify the bastion host from the example above as running a restricted shell: @lisp +@group (add-to-list 'tramp-restricted-shell-hosts-alist "\\`bastion\\.your\\.domain\\'") +@end group @end lisp @end defopt +@node Firewalls +@section Passing firewalls +@cindex HTTP tunnel +@cindex proxy hosts, HTTP tunnel + +Sometimes, it is not possible to reach a remote host directly. A +firewall might be in the way, which could be passed via a proxy +server. + +Both ssh and PuTTY support such proxy settings, using an HTTP tunnel +via the @command{CONNECT} command (conforming to RFC 2616, 2817 +specifications). Proxy servers using HTTP version 1.1 or later +protocol support this command. + +@subsection Tunneling with ssh + +With ssh, you could use the @code{ProxyCommand} entry in the +@file{~/.ssh/config}: + +@example +@group +Host host.other.domain + ProxyCommand nc -X connect -x proxy.your.domain:3128 %h %p +@end group +@end example + +@code{nc} is BSD's netcat program, which establishes HTTP tunnels. Any +other program with such a feature could be used as well. + +In the example, opening @file{@trampfn{ssh,host.your.domain,}} passes +the HTTP proxy server @samp{proxy.your.domain} on port 3128. + +@subsection Tunneling with PuTTY + +PuTTY does not need an external program, HTTP tunnel support is +built-in. In the PuTTY config program, create a session for +@samp{host.your.domain}. In the @option{Connection/Data} entry, +select the @option{HTTP} option, and add @samp{proxy.your.domain} as +@option{Proxy hostname}, and 3128 as @option{Port}. + +Opening @file{@trampfn{plinkx,host.your.domain,}} passes the HTTP +proxy server @samp{proxy.your.domain} on port 3128. + + @node Customizing Methods @section Using Non-Standard Methods @cindex customizing methods @@ -1424,10 +1369,12 @@ This function returns the list of completion functions for @var{method}. Example: @example +@group (tramp-get-completion-function "rsh") @result{} ((tramp-parse-rhosts "/etc/hosts.equiv") (tramp-parse-rhosts "~/.rhosts")) +@end group @end example @end defun @@ -1437,12 +1384,14 @@ for @var{method}. Example: @example +@group (tramp-set-completion-function "ssh" '((tramp-parse-sconfig "/etc/ssh_config") (tramp-parse-sconfig "~/.ssh/config"))) @result{} ((tramp-parse-sconfig "/etc/ssh_config") (tramp-parse-sconfig "~/.ssh/config")) +@end group @end example @end defun @@ -1464,7 +1413,7 @@ This function parses files which are syntactical equivalent to in such files, it can return host names only. @item @code{tramp-parse-sconfig} -@findex tramp-parse-shosts +@findex tramp-parse-sconfig This function returns the host nicknames defined by @code{Host} entries in @file{~/.ssh/config} style files. @@ -1478,7 +1427,7 @@ SSH2 parsing of directories @file{/etc/ssh2/hostkeys/*} and are always @code{nil}. @item @code{tramp-parse-sknownhosts} -@findex tramp-parse-shostkeys +@findex tramp-parse-sknownhosts Another SSH2 style parsing of directories like @file{/etc/ssh2/knownhosts/*} and @file{~/ssh2/knownhosts/*}. This @@ -1495,6 +1444,11 @@ A function dedicated to @file{/etc/hosts} for host names. A function which parses @file{/etc/passwd} files for user names. +@item @code{tramp-parse-etc-group} +@findex tramp-parse-etc-group + +A function which parses @file{/etc/group} files for group names. + @item @code{tramp-parse-netrc} @findex tramp-parse-netrc @@ -1513,9 +1467,11 @@ taken as candidates for completion for user and host names. Example: @example +@group (my-tramp-parse "~/.my-tramp-hosts") @result{} ((nil "toto") ("daniel" "melancholia")) +@end group @end example @end defun @@ -1563,27 +1519,14 @@ Setting @code{auth-source-debug} to @code{t} to debug messages. the same user or host name independent of the access method. @vindex password-cache-expiry - @code{password-cache-expiry} sets the duration (in seconds) the passwords are remembered. Passwords are never saved permanently nor -can they extend beyond the lifetime of the current @value{emacsname} -session. Set @code{password-cache-expiry} to @code{nil} to disable -expiration. +can they extend beyond the lifetime of the current Emacs session. Set +@code{password-cache-expiry} to @code{nil} to disable expiration. @vindex password-cache - Set @code{password-cache} to @code{nil} to disable password caching. -@strong{Implementation Note}: password caching depends on -@file{password-cache.el} package. @value{tramp} activates password -caching only if @value{tramp} can discover, while @value{emacsname} is -loading, the package through @code{load-path}. - -@ifset installchapter -@file{password.el} is available from No Gnus or from the @value{tramp} -@file{contrib} directory, see @ref{Installation parameters}. -@end ifset - @node Connection caching @section Reusing connection related information @@ -1591,22 +1534,17 @@ loading, the package through @code{load-path}. @vindex tramp-persistency-file-name For faster initial connection times, @value{tramp} stores previous -connection properties in a file specified by the variable -@code{tramp-persistency-file-name}. +connection properties in a file specified by the user option +@option{tramp-persistency-file-name}. -The default file name for @code{tramp-persistency-file-name} is: -@ifset emacs +The default file name for @option{tramp-persistency-file-name} is @file{~/.emacs.d/tramp}. -@end ifset -@ifset xemacs -@file{~/.xemacs/tramp}. -@end ifset -@value{tramp} reads this file during @value{emacsname} startup, and -writes to it when exiting @value{emacsname}. Delete this file for -@value{tramp} to recreate a new one on next @value{emacsname} startup. +@value{tramp} reads this file during Emacs startup, and writes to it +when exiting Emacs. Delete this file for @value{tramp} to recreate a +new one on next Emacs startup. -Set @code{tramp-persistency-file-name} to @code{nil} to disable +Set @option{tramp-persistency-file-name} to @code{nil} to disable storing connections persistently. To reuse connection information from the persistent list, @@ -1633,11 +1571,12 @@ connection related information for that host and creates a new entry. For more precise customization, parameters specified by @code{tramp-methods} can be overwritten manually. -Set @code{tramp-connection-properties} to manually override +Set @option{tramp-connection-properties} to manually override @code{tramp-methods}. Properties in this list are in the form -@code{(@var{regexp} @var{property} @var{value})}. @var{regexp} matches -remote file names. Use @code{nil} to match all. @var{property} is the -property's name, and @var{value} is the property's value. +@code{(@var{regexp} @var{property} @var{value})}. @var{regexp} +matches remote file names. Use @code{nil} to match all. +@var{property} is the property's name, and @var{value} is the +property's value. @var{property} is any method specific parameter contained in @code{tramp-methods}. The parameter key in @code{tramp-methods} is a @@ -1646,12 +1585,17 @@ string @samp{<foo>} for @var{property}. For example, this changes the remote shell: @lisp +@group (add-to-list 'tramp-connection-properties (list (regexp-quote "@trampfn{ssh,user@@randomhost.your.domain,}") "remote-shell" "/bin/ksh")) +@end group + +@group (add-to-list 'tramp-connection-properties (list (regexp-quote "@trampfn{ssh,user@@randomhost.your.domain,}") "remote-shell-login" '("-"))) +@end group @end lisp The parameters @code{tramp-remote-shell} and @@ -1659,15 +1603,17 @@ The parameters @code{tramp-remote-shell} and values for the remote host. @var{property} could also be any property found in -@code{tramp-persistency-file-name}. +@option{tramp-persistency-file-name}. To get around how restricted shells randomly drop connections, set the special property @samp{busybox}. For example: @lisp +@group (add-to-list 'tramp-connection-properties (list (regexp-quote "@trampfn{ssh,user@@randomhost.your.domain,}") "busybox" t)) +@end group @end lisp @@ -1686,12 +1632,10 @@ To improve performance and accuracy of remote file access, @command{grep} when available. @defopt tramp-remote-path -@vindex tramp-remote-path -@vindex tramp-default-remote-path -@vindex tramp-own-remote-path @option{tramp-remote-path} specifies which remote directory paths @value{tramp} can search for @ref{Remote programs}. +@vindex tramp-default-remote-path @value{tramp} uses standard defaults, such as @file{/bin} and @file{/usr/bin}, which are reasonable for most hosts. To accommodate differences in hosts and paths, for example, @file{/bin:/usr/bin} on @@ -1708,21 +1652,25 @@ shown below for @value{tramp} to use when connecting. (add-to-list 'tramp-remote-path "/usr/local/perl/bin") @end lisp +@vindex tramp-own-remote-path Another way to find the remote path is to use the path assigned to the remote user by the remote host. @value{tramp} does not normally retain -this remote path after logging. However, @code{tramp-own-remote-path} +this remote path after login. However, @code{tramp-own-remote-path} preserves the path value, which can be used to update -@code{tramp-remote-path}. +@option{tramp-remote-path}. @lisp (add-to-list 'tramp-remote-path 'tramp-own-remote-path) @end lisp + +@strong{Note} that this works only if your remote @command{/bin/sh} +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 -@value{emacsname}, remove the persistent file (@pxref{Connection -caching}), and restart @value{emacsname}. +Emacs, remove the persistent file (@pxref{Connection caching}), and +restart Emacs. @node Remote shell setup @@ -1753,42 +1701,47 @@ login security, especially not the exotic ones. However, @value{tramp} provides a few tweaks to address the most common ones. @table @asis -@item @var{tramp-shell-prompt-pattern} +@item @option{tramp-shell-prompt-pattern} @vindex tramp-shell-prompt-pattern -@code{tramp-shell-prompt-pattern} is for remote login shell prompt, +@option{tramp-shell-prompt-pattern} is for remote login shell prompt, which may not be the same as the local login shell prompt, @code{shell-prompt-pattern}. Since most hosts use identical prompts, @value{tramp} sets a similar default value for both prompts. -@item @var{tramp-password-prompt-regexp} -@item @var{tramp-wrong-passwd-regexp} +@item @option{tramp-password-prompt-regexp} +@item @option{tramp-wrong-passwd-regexp} @vindex tramp-password-prompt-regexp @vindex tramp-wrong-passwd-regexp -@value{tramp} uses @var{tramp-password-prompt-regexp} to distinguish -between prompts for passwords and prompts for passphrases. By default, -@var{tramp-password-prompt-regexp} handles the detection in English -language environments. See a localization example below: +@value{tramp} uses @option{tramp-password-prompt-regexp} to +distinguish between prompts for passwords and prompts for passphrases. +By default, @option{tramp-password-prompt-regexp} handles the +detection in English language environments. See a localization +example below: @lisp -(setq - tramp-password-prompt-regexp - (concat - "^.*" - (regexp-opt - '("passphrase" "Passphrase" - ;; English - "password" "Password" - ;; Deutsch - "passwort" "Passwort" - ;; Français - "mot de passe" "Mot de passe") t) - ".*:\0? *")) +@group +(custom-set-variables + '(tramp-password-prompt-regexp + (concat + "^.*" + (regexp-opt + '("passphrase" "Passphrase" + ;; English + "password" "Password" + ;; Deutsch + "passwort" "Passwort" + ;; Français + "mot de passe" "Mot de passe") + t) + ".*:\0? *") + nil (tramp))) +@end group @end lisp Similar localization may be necessary for handling wrong password -prompts, for which @value{tramp} uses @var{tramp-wrong-passwd-regexp}. +prompts, for which @value{tramp} uses @option{tramp-wrong-passwd-regexp}. @item @command{tset} and other questions @cindex Unix command tset @@ -1797,8 +1750,8 @@ prompts, for which @value{tramp} uses @var{tramp-wrong-passwd-regexp}. To suppress inappropriate prompts for terminal type, @value{tramp} sets the @env{TERM} to @code{dumb} before the remote login process -begins via the variable @code{tramp-terminal-type}. This will silence -common @command{tset} related prompts. +begins via the user option @option{tramp-terminal-type}. This will +silence common @command{tset} related prompts. @value{tramp}'s strategy for handling such prompts (commonly triggered from login scripts on remote hosts) is to set the environment @@ -1806,26 +1759,31 @@ variables so that no prompts interrupt the shell initialization process. @vindex tramp-actions-before-shell - An alternative approach is to configure @value{tramp} with strings that can identify such questions using @code{tramp-actions-before-shell}. Example: @lisp +@group (defconst my-tramp-prompt-regexp (concat (regexp-opt '("Enter the birth date of your mother:") t) "\\s-*") "Regular expression matching my login prompt question.") +@end group +@group (defun my-tramp-action (proc vec) "Enter \"19000101\" in order to give a correct answer." (save-window-excursion (with-current-buffer (tramp-get-connection-buffer vec) (tramp-message vec 6 "\n%s" (buffer-string)) (tramp-send-string vec "19000101")))) +@end group +@group (add-to-list 'tramp-actions-before-shell '(my-tramp-prompt-regexp my-tramp-action)) +@end group @end lisp @@ -1886,16 +1844,16 @@ follows: Then re-set the prompt string in @file{~/.emacs_SHELLNAME} as follows: @example +@group # Reset the prompt for remote Tramp shells. if [ "$@{INSIDE_EMACS/*tramp*/tramp@}" == "tramp" ] ; then PS1="[\u@@\h \w]$ " fi +@end group @end example @ifinfo -@ifset emacs -@xref{Interactive Shell, , , @value{emacsdir}}. -@end ifset +@xref{Interactive Shell, , , emacs}. @end ifinfo @item @command{busybox} / @command{nc} @@ -1910,13 +1868,16 @@ install and execute a listener as follows (see @code{tramp-methods}): @end example The above command-line syntax has changed with @command{busybox} -versions. If @command{nc} refuses the @command{-p} parameter, then +versions. If @command{nc} refuses the @samp{-p} parameter, then overwrite as follows: @lisp +@group (add-to-list 'tramp-connection-properties - `(,(regexp-quote "192.168.0.1") "remote-copy-args" (("-l") ("%r")))) + `(,(regexp-quote "192.168.0.1") + "remote-copy-args" (("-l") ("%r")))) +@end group @end lisp @noindent @@ -1938,13 +1899,15 @@ Applications such as @code{SSHDroid} that run @command{sshd} process on the Android device can accept any @option{ssh}-based methods provided these settings are adjusted: -@code{sh} must be specified for remote shell since Android devices do -not provide @code{/bin/sh}. @code{sh} will then invoke whatever shell is -installed on the device with this setting: +@command{sh} must be specified for remote shell since Android devices +do not provide @command{/bin/sh}. @command{sh} will then invoke +whatever shell is installed on the device with this setting: @lisp +@group (add-to-list 'tramp-connection-properties (list (regexp-quote "192.168.0.26") "remote-shell" "sh")) +@end group @end lisp @noindent @@ -1956,8 +1919,10 @@ user settings. Android devices prefer @file{/system/xbin} path over @file{/system/bin}. Both of these are set as follows: @lisp +@group (add-to-list 'tramp-remote-path 'tramp-own-remote-path) (add-to-list 'tramp-remote-path "/system/xbin") +@end group @end lisp @noindent @@ -1970,17 +1935,19 @@ directory for temporary files: @noindent Open a remote connection with the command @kbd{C-x C-f -@trampfn{ssh,192.168.0.26#2222,}}, where @command{sshd} is listening on port -@samp{2222}. +@trampfn{ssh,192.168.0.26#2222,}}, where @command{sshd} is listening +on port @samp{2222}. To add a corresponding entry to the @file{~/.ssh/config} file (recommended), use this: @example +@group Host android HostName 192.168.0.26 User root Port 2222 +@end group @end example @noindent @@ -1988,8 +1955,10 @@ To use the host name @samp{android} instead of the IP address shown in the previous example, fix the connection properties as follows: @lisp +@group (add-to-list 'tramp-connection-properties (list (regexp-quote "android") "remote-shell" "sh")) +@end group @end lisp @noindent @@ -2001,64 +1970,40 @@ Open a remote connection with a more concise command @kbd{C-x C-f @section Auto-save and Backup configuration @cindex auto-save @cindex backup -@ifset emacs @vindex backup-directory-alist -@end ifset -@ifset xemacs -@vindex bkup-backup-directory-info -@end ifset -To avoid @value{tramp} from saving backup files owned by root to -locations accessible to others, default backup settings in -@ifset emacs -@code{backup-directory-alist} -@end ifset -@ifset xemacs -@code{bkup-backup-directory-info} -@end ifset -have to be altered. +To avoid @value{tramp} from saving backup files owned by @samp{root} +to locations accessible to others, default backup settings in +@option{backup-directory-alist} have to be altered. -Here's a scenario where files could be inadvertently -exposed. @value{emacsname} by default writes backup files to the same -directory as the original files unless changed to another location, -such as @file{~/.emacs.d/backups/}. Such a directory will also be used -by default by @value{tramp} when using, say, a restricted file +Here's a scenario where files could be inadvertently exposed. Emacs +by default writes backup files to the same directory as the original +files unless changed to another location, such as +@file{~/.emacs.d/backups/}. Such a directory will also be used by +default by @value{tramp} when using, say, a restricted file @file{@trampfn{su,root@@localhost,/etc/secretfile}}. The backup file -of the secretfile is now owned by the user logged in from tramp and -not root. +of the secretfile is now owned by the user logged in from +@value{tramp} and not @samp{root}. -When -@ifset emacs -@code{backup-directory-alist} -@end ifset -@ifset xemacs -@code{bkup-backup-directory-info} -@end ifset -is @code{nil} (the default), such problems do not occur. +When @option{backup-directory-alist} is @code{nil} (the default), such +problems do not occur. To ``turn off'' the backup feature for @value{tramp} files and stop @value{tramp} from saving to the backup directory, use this: -@ifset emacs @lisp +@group (add-to-list 'backup-directory-alist (cons tramp-file-name-regexp nil)) +@end group @end lisp -@end ifset -@ifset xemacs -@lisp -(require 'backup-dir) -(add-to-list 'bkup-backup-directory-info - (list tramp-file-name-regexp "")) -@end lisp -@end ifset -@ifset emacs @noindent Disabling backups can be targeted to just the @option{su} and @option{sudo} methods: @lisp +@group (setq backup-enable-predicate (lambda (name) (and (normal-backup-enable-predicate name) @@ -2066,27 +2011,15 @@ Disabling backups can be targeted to just the @option{su} and (let ((method (file-remote-p name 'method))) (when (stringp method) (member method '("su" "sudo")))))))) +@end group @end lisp -@end ifset Another option is to create better backup file naming with user and host names prefixed to the file name. For example, transforming @file{/etc/secretfile} to @file{~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile}, set the -@value{tramp} variable -@ifset emacs -@code{tramp-backup-directory-alist} -@end ifset -@ifset xemacs -@code{tramp-bkup-backup-directory-info} -@end ifset -from the existing variable -@ifset emacs -@code{backup-directory-alist}. -@end ifset -@ifset xemacs -@code{bkup-backup-directory-info}. -@end ifset +@value{tramp} user option @option{tramp-backup-directory-alist} from +the existing user option @option{backup-directory-alist}. Then @value{tramp} backs up to a file name that is transformed with a prefix consisting of the DIRECTORY name. This file name prefixing @@ -2095,51 +2028,38 @@ happens only when the DIRECTORY is an absolute local file name. @noindent Example: -@ifset emacs @lisp +@group (add-to-list 'backup-directory-alist (cons "." "~/.emacs.d/backups/")) -(setq tramp-backup-directory-alist backup-directory-alist) -@end lisp -@end ifset -@ifset xemacs -@lisp -(require 'backup-dir) -(add-to-list 'bkup-backup-directory-info - (list "." "~/.emacs.d/backups/" 'full-path)) -(setq tramp-bkup-backup-directory-info bkup-backup-directory-info) +(custom-set-variables + '(tramp-backup-directory-alist backup-directory-alist 6 nil (tramp))) +@end group @end lisp -@end ifset @noindent The backup file name of @file{@trampfn{su,root@@localhost,/etc/secretfile}} would be -@ifset emacs +@ifset unified @file{@trampfn{su,root@@localhost,~/.emacs.d/backups/!su:root@@localhost:!etc!secretfile~}} @end ifset -@ifset xemacs +@ifset separate @file{@trampfn{su,root@@localhost,~/.emacs.d/backups/![su!root@@localhost]!etc!secretfile~}} @end ifset Just as for backup files, similar issues of file naming affect -auto-saving @value{tramp} files. -@ifset emacs -Auto-saved files are saved in the directory specified by the variable -@code{auto-save-file-name-transforms}. By default this is set to the -local temporary directory. But in some versions of Debian GNU/Linux, -this points to the source directory where the @value{emacsname} was -compiled. Reset such values to a valid directory. - -Set @code{auto-save-file-name-transforms} to @code{nil} to save +auto-saving @value{tramp} files. Auto-saved files are saved in the +directory specified by the user option +@option{auto-save-file-name-transforms}. By default this is set to +the local temporary directory. But in some versions of Debian +GNU/Linux, this points to the source directory where the Emacs was +compiled. Reset such values to a valid directory. + +Set @option{auto-save-file-name-transforms} to @code{nil} to save auto-saved files to the same directory as the original file. -Alternatively, set the variable @code{tramp-auto-save-directory} to -direct all auto saves to that location. -@end ifset -@ifset xemacs -@code{auto-save-directory} can also be used here instead of other -locations specified above. -@end ifset +Alternatively, set the user option @option{tramp-auto-save-directory} +to direct all auto saves to that location. @node Windows setup hints @section Issues with Cygwin ssh @@ -2150,9 +2070,9 @@ This section is incomplete. Please share your solutions. @cindex method sshx with Cygwin @cindex sshx method with Cygwin -Cygwin's @command{ssh} works only with a Cygwin version of -@value{emacsname}. To check for compatibility: type @kbd{M-x eshell}, and -start @kbd{ssh test.host}. Incompatibilities trigger this message: +Cygwin's @command{ssh} works only with a Cygwin version of Emacs. To +check for compatibility: type @kbd{M-x eshell}, and start @kbd{ssh +test.host}. Incompatibilities trigger this message: @example Pseudo-terminal will not be allocated because stdin is not a terminal. @@ -2162,11 +2082,17 @@ Some older versions of Cygwin's @command{ssh} work with the @option{sshx} access method. Consult Cygwin's FAQ at @uref{http://cygwin.com/faq/} for details. +@cindex Cygwin and fakecygpty +@cindex fakecygpty and Cygwin + +On @uref{https://www.emacswiki.org/emacs/SshWithNTEmacs, the Emacs +Wiki} it is explained how to use the helper program @code{fakecygpty} +to fix this problem. @cindex method scpx with Cygwin @cindex scpx method with Cygwin -When using the @option{scpx} access method, @value{emacsname} may call +When using the @option{scpx} access method, Emacs may call @command{scp} with Windows file naming, such as @code{c:/foo}. But the version of @command{scp} that is installed with Cygwin does not know about Windows file naming, which causes it to incorrectly look @@ -2176,18 +2102,17 @@ A workaround: write a wrapper script for @option{scp} to convert Windows file names to Cygwin file names. @cindex Cygwin and ssh-agent -@cindex SSH_AUTH_SOCK and @value{emacsname} on Windows +@cindex SSH_AUTH_SOCK and Emacs on Windows When using the @command{ssh-agent} on Windows for password-less interaction, @option{ssh} methods depend on the environment variable -@env{SSH_AUTH_SOCK}. But this variable is not set when -@value{emacsname} is started from a Desktop shortcut and -authentication fails. +@env{SSH_AUTH_SOCK}. But this variable is not set when Emacs is +started from a Desktop shortcut and authentication fails. One workaround is to use a Windows based SSH Agent, such as Pageant. It is part of the Putty Suite of tools. -The fallback is to start @value{emacsname} from a shell. +The fallback is to start Emacs from a shell. @node Usage @@ -2198,27 +2123,24 @@ The fallback is to start @value{emacsname} from a shell. they are local. However, @value{tramp} employs a formalized remote file naming syntax to perform its functions transparently. This syntax consists of many parts specifying access methods, -authentication, host names, and file names. -@ifset emacs -@value{ftppackagename} uses a similar syntax. -@end ifset +authentication, host names, and file names. Ange FTP uses a similar +syntax. @cindex type-ahead -Unlike opening local files in @value{emacsname}, which are -instantaneous, opening remote files in @value{tramp} is slower at -first. Sometimes there is a noticeable delay before the prompts for -passwords or authentication appear in the minibuffer. Hitting -@kbd{@key{RET}} or other keys during this gap will be processed by -@value{emacsname}. This type-ahead facility is a feature of -@value{emacsname} that may cause missed prompts when using +Unlike opening local files in Emacs, which are instantaneous, opening +remote files in @value{tramp} is slower at first. Sometimes there is +a noticeable delay before the prompts for passwords or authentication +appear in the minibuffer. Hitting @kbd{@key{RET}} or other keys +during this gap will be processed by Emacs. This type-ahead facility +is a feature of Emacs that may cause missed prompts when using @value{tramp}. @menu * File name Syntax:: @value{tramp} file name conventions. * File name completion:: File name completion. * Ad-hoc multi-hops:: Declaring multiple hops in the file name. -* Remote processes:: Integration with other @value{emacsname} packages. +* Remote processes:: Integration with other Emacs packages. * Cleanup remote connections:: Cleanup remote connections. @end menu @@ -2228,9 +2150,9 @@ passwords or authentication appear in the minibuffer. Hitting @cindex file name syntax @cindex file name examples -@file{@trampf{host,localfilename}} -opens file @var{localfilename} on the remote host @var{host}, using -the default method. @xref{Default Method}. +@file{@trampf{host,localfilename}} opens file @var{localfilename} on +the remote host @var{host}, using the default method. @xref{Default +Method}. @table @file @item @value{prefix}melancholia@value{postfix}.emacs @@ -2257,7 +2179,7 @@ For the file @file{/etc/squid.conf} on the host @code{melancholia}. @var{host} can take IPv4 or IPv6 address, as in @file{@trampf{127.0.0.1,.emacs}} or @file{@trampf{@value{ipv6prefix}::1@value{ipv6postfix},.emacs}}. -@ifset emacs +@ifset unified For syntactical reasons, IPv6 addresses must be embedded in square brackets @file{@value{ipv6prefix}} and @file{@value{ipv6postfix}}. @end ifset @@ -2270,24 +2192,16 @@ name using the proper syntax will override this default behavior: @trampf{user@@host,path/to.file} @end example -@file{@trampf{daniel@@melancholia,.emacs}} is for file -@file{.emacs} in @code{daniel}'s home directory on the host, -@code{melancholia}. +@file{@trampf{daniel@@melancholia,.emacs}} is for file @file{.emacs} +in @code{daniel}'s home directory on the host, @code{melancholia}. Specify other file access methods (@pxref{Inline methods}, @pxref{External methods}) as part of the file name. -@ifset emacs Method name comes before user name, as in @file{@value{prefix}@var{method}@value{postfixhop}} (Note the trailing -colon). -@end ifset -@ifset xemacs -This is done by replacing the initial @file{@value{prefix}} with -@file{@value{prefix}@var{method}@value{postfixhop}} (Note the trailing -slash!). -@end ifset -The syntax specifications for user, host, and file do not change. +colon). The syntax specifications for user, host, and file do not +change. To connect to the host @code{melancholia} as @code{daniel}, using @option{ssh} method for @file{.emacs} in @code{daniel}'s home @@ -2307,44 +2221,38 @@ name. For example: @file{@trampfn{ssh,daniel@@melancholia#42,.emacs}}. @value{tramp} can complete the following @value{tramp} file name components: method names, user names, host names, and file names -located on remote hosts. -@ifset emacs -Enable this by activating partial completion in @file{.emacs}. +located on remote hosts. Enable this by activating partial completion +in @file{.emacs}. @ifinfo -@xref{Completion Options, , , @value{emacsdir}}. +@xref{Completion Options, , , emacs}. @end ifinfo -@end ifset For example, type @kbd{C-x C-f @value{prefix}t @key{TAB}}, @value{tramp} completion choices show up as @example +@group @c @multitable {@trampfn{telnet,melancholia.danann.net,}} {@trampfn{telnet,192.168.0.1,}} @multitable @columnfractions .5 .5 -@ifset emacs @item @value{prefixhop}telnet@value{postfixhop} @tab tmp/ @item @value{prefixhop}toto@value{postfix} @tab -@end ifset -@ifset xemacs -@item @value{prefixhop}telnet@value{postfixhop} @tab @value{prefixhop}toto@value{postfix} -@end ifset @end multitable +@end group @end example -@samp{@value{prefixhop}telnet@value{postfixhop}} -is a possible completion for the respective method, -@ifset emacs -@samp{tmp/} stands for the directory @file{/tmp} on your local host, -@end ifset -and @samp{@value{prefixhop}toto@value{postfix}} -might be a host @value{tramp} has detected in your @file{~/.ssh/known_hosts} -file (when using @option{ssh} as default method). +@samp{@value{prefixhop}telnet@value{postfixhop}} is a possible +completion for the respective method, @samp{tmp/} stands for the +directory @file{/tmp} on your local host, and +@samp{@value{prefixhop}toto@value{postfix}} might be a host +@value{tramp} has detected in your @file{~/.ssh/known_hosts} file +(when using @option{ssh} as default method). Type @kbd{e @key{TAB}} for the minibuffer completion to @samp{@value{prefix}telnet@value{postfixhop}}. Typing @kbd{@key{TAB}} shows host names @value{tramp} from @file{/etc/hosts} file, for example. @example +@group @multitable @columnfractions .5 .5 @c @multitable {@trampfn{telnet,melancholia.danann.net,}} {@trampfn{telnet,192.168.0.1,}} @item @trampfn{telnet,127.0.0.1,} @tab @trampfn{telnet,192.168.0.1,} @@ -2352,6 +2260,7 @@ shows host names @value{tramp} from @file{/etc/hosts} file, for example. @item @value{prefix}telnet@value{postfixhop}@value{ipv6prefix}::1@value{ipv6postfix}@value{postfix} @tab @trampfn{telnet,localhost,} @item @trampfn{telnet,melancholia.danann.net,} @tab @trampfn{telnet,melancholia,} @end multitable +@end group @end example Choose a host from the above list and then continue to complete file @@ -2365,21 +2274,19 @@ persistently (@pxref{Connection caching}) will be included in the completion lists. After remote host name completion comes completion of file names on -the remote host. It works the same as with local host file completion, +the remote host. It works the same as with local host file completion except that killing with double-slash @file{//} kills only the file -name part of the @value{tramp} file name syntax. -@ifset emacs -A triple-slash stands for the default behavior. -@end ifset +name part of the @value{tramp} file name syntax. A triple-slash +stands for the default behavior. @ifinfo -@xref{Minibuffer File, , , @value{emacsdir}}. +@xref{Minibuffer File, , , emacs}. @end ifinfo @noindent Example: @example -@ifset emacs +@group @kbd{C-x C-f @trampfn{telnet,melancholia,/usr/local/bin//etc} @key{TAB}} @print{} @trampfn{telnet,melancholia,/etc} @@ -2388,28 +2295,20 @@ Example: @kbd{C-x C-f @trampfn{telnet,melancholia,/usr/local/bin///etc} @key{TAB}} @print{} /etc -@end ifset - -@ifset xemacs -@kbd{C-x C-f @trampfn{telnet,melancholia,/usr/local/bin//}} - @print{} @trampfn{telnet,melancholia,/} - -@kbd{C-x C-f @trampfn{telnet,melancholia,//}} - @print{} / -@end ifset +@end group @end example During file name completion, remote directory contents are re-read regularly to account for any changes in the filesystem that may affect the completion candidates. Such re-reads can account for changes to -the file system by applications outside @value{emacsname} -(@pxref{Connection caching}). +the file system by applications outside Emacs (@pxref{Connection +caching}). @defopt tramp-completion-reread-directory-timeout -@vindex tramp-completion-reread-directory-timeout The timeout is number of seconds since last remote command for -rereading remote directory contents. 0 re-reads immediately during -file name completion, @code{nil} uses cached directory contents. +rereading remote directory contents. A value of 0 re-reads +immediately during file name completion, @code{nil} uses cached +directory contents. @end defopt @@ -2419,7 +2318,7 @@ file name completion, @code{nil} uses cached directory contents. @cindex proxy hosts, ad-hoc @value{tramp} file name syntax can accommodate ad hoc specification of -multiple proxies without using @code{tramp-default-proxies-alist} +multiple proxies without using @option{tramp-default-proxies-alist} configuration setup(@pxref{Multi-hops}). Each proxy is specified using the same syntax as the remote host @@ -2436,32 +2335,30 @@ proxy @samp{bird@@bastion} to a remote file on @samp{you@@remotehost}: 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 @value{emacsname} session. Subsequent @value{tramp} connections -to the same remote host can then use the shortcut form: +@option{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}}. @defopt tramp-save-ad-hoc-proxies -@vindex tramp-save-ad-hoc-proxies For ad-hoc definitions to be saved automatically in -@option{tramp-default-proxies-alist} for future @value{emacsname} -sessions, set @option{tramp-save-ad-hoc-proxies}. +@option{tramp-default-proxies-alist} for future Emacs sessions, set +@option{tramp-save-ad-hoc-proxies} to non-@code{nil}. @lisp -(setq tramp-save-ad-hoc-proxies t) +(custom-set-variables '(tramp-save-ad-hoc-proxies t nil (tramp))) @end lisp @end defopt @node Remote processes -@section Integration with other @value{emacsname} packages +@section Integration with other Emacs packages @cindex compile @cindex recompile @value{tramp} supports starting new running processes on the remote -host for discovering remote file names. @value{emacsname} packages on -the remote host need no specific modifications for @value{tramp}'s -use. +host for discovering remote file names. Emacs packages on the remote +host need no specific modifications for @value{tramp}'s use. This type of integration does not work with the @option{ftp} method, and does not support the pty association as specified in @@ -2471,17 +2368,16 @@ and does not support the pty association as specified in host when the variable @code{default-directory} is remote: @lisp +@group (let ((default-directory "/ssh:remote.host:")) (start-file-process "grep" (get-buffer-create "*grep*") "/bin/sh" "-c" "grep -e tramp *")) +@end group @end lisp - -@ifset emacsgvfs Remote processes do not apply to GVFS (see @ref{GVFS based methods}) because the remote file system is mounted on the local host and @value{tramp} just accesses by changing the @code{default-directory}. -@end ifset @value{tramp} starts a remote process when a command is executed in a remote file or directory buffer. As of now, these packages have been @@ -2492,22 +2388,24 @@ like @code{compile} and @code{grep}) and @file{gud.el} (@code{gdb} or For @value{tramp} to find the command on the remote, it must be accessible through the default search path as setup by @value{tramp} upon first connection. Alternatively, use an absolute path or extend -@code{tramp-remote-path} (see @ref{Remote programs}): +@option{tramp-remote-path} (see @ref{Remote programs}): @lisp +@group (add-to-list 'tramp-remote-path "~/bin") (add-to-list 'tramp-remote-path "/appli/pub/bin") +@end group @end lisp -Customize @code{tramp-remote-process-environment} to suit the remote -program's environment for the remote host. -@code{tramp-remote-process-environment} is a list of strings +Customize user option @option{tramp-remote-process-environment} to +suit the remote program's environment for the remote host. +@option{tramp-remote-process-environment} is a list of strings structured similar to @code{process-environment}, where each element is a string of the form @samp{ENVVARNAME=VALUE}. -To avoid any conflicts with local host variables set through local -configuration files, such as @file{~/.profile}, use @samp{ENVVARNAME=} -to unset them for the remote environment. +To avoid any conflicts with local host environment variables set +through local configuration files, such as @file{~/.profile}, use +@samp{ENVVARNAME=} to unset them for the remote environment. @noindent Use @code{add-to-list} to add entries: @@ -2517,17 +2415,31 @@ Use @code{add-to-list} to add entries: @end lisp Modifying or deleting already existing values in the -@code{tramp-remote-process-environment} list may not be feasible on +@option{tramp-remote-process-environment} list may not be feasible on restricted remote hosts. For example, some system administrators -disallow changing @env{HISTORY} variable. To accommodate such -restrictions when using @value{tramp}, fix the -@code{tramp-remote-process-environment} by the following code in the +disallow changing @env{HISTORY} environment variable. To accommodate +such restrictions when using @value{tramp}, fix the +@option{tramp-remote-process-environment} by the following code in the local @file{.emacs} file: @lisp +@group (let ((process-environment tramp-remote-process-environment)) (setenv "HISTORY" nil) (setq tramp-remote-process-environment process-environment)) +@end group +@end lisp + +Setting the @env{ENV} environment variable instructs some shells to +read an initialization file. Per default, @value{tramp} has disabled +this. You could overwrite this behavior by evaluating + +@lisp +@group +(let ((process-environment tramp-remote-process-environment)) + (setenv "ENV" "$HOME/.profile") + (setq tramp-remote-process-environment process-environment)) +@end group @end lisp @value{tramp} does not use the defaults specified in @@ -2537,15 +2449,17 @@ local @file{.emacs} file: them as follows: @lisp +@group (let ((process-environment (cons "HGPLAIN=1" process-environment))) (process-file @dots{})) +@end group @end lisp This works only for environment variables not already set in the @code{process-environment}. -For integrating other @value{emacsname} packages so @value{tramp} can -execute remotely, please file a bug report. @xref{Bug Reports}. +For integrating other Emacs packages so @value{tramp} can execute +remotely, please file a bug report. @xref{Bug Reports}. @subsection Running remote programs that create local X11 windows @@ -2555,8 +2469,10 @@ set the @env{DISPLAY} environment variable for the remote host as follows in the local @file{.emacs} file: @lisp +@group (add-to-list 'tramp-remote-process-environment (format "DISPLAY=%s" (getenv "DISPLAY"))) +@end group @end lisp @noindent @@ -2580,11 +2496,9 @@ when using @value{tramp} between two hosts with different operating systems, such as @samp{windows-nt} and @samp{gnu/linux}. This option ensures the correct name of the remote shell program. -@ifset emacs Starting with Emacs 24, when @option{explicit-shell-file-name} is equal to @code{nil}, calling @code{shell} interactively will prompt for a shell name. -@end ifset @subsection Running @code{shell-command} on a remote host @@ -2595,16 +2509,16 @@ on remote hosts and displays output in buffers on the local host. Example: @example +@group @kbd{C-x C-f @trampfn{sudo,,} @key{RET}} @kbd{M-! tail -f /var/log/syslog.log & @key{RET}} +@end group @end example @command{tail} command outputs continuously to the local buffer, @file{*Async Shell Command*} -@ifset emacs @kbd{M-x auto-revert-tail-mode} runs similarly showing continuous output. -@end ifset @subsection Running @code{eshell} on a remote host @@ -2617,6 +2531,7 @@ You must add the module @code{eshell-tramp} to @kbd{M-x eshell} on a remote host: @example +@group @b{~ $} cd @trampfn{sudo,,/etc} @key{RET} @b{@trampfn{sudo,root@@host,/etc} $} hostname @key{RET} host @@ -2625,28 +2540,31 @@ uid=0(root) gid=0(root) groups=0(root) @b{@trampfn{sudo,root@@host,/etc} $} find-file shadow @key{RET} #<buffer shadow> @b{@trampfn{sudo,root@@host,/etc} $} +@end group @end example -@ifset emacs -@code{eshell} in @value{emacsname} 23.2 added custom @code{su} and -@code{sudo} commands that set the default directory correctly for the +@code{eshell} in Emacs 23.2 added custom @code{su} and @code{sudo} +commands that set the default directory correctly for the @file{*eshell*} buffer. @value{tramp} silently updates -@code{tramp-default-proxies-alist} with an entry for this directory +@option{tramp-default-proxies-alist} with an entry for this directory (@pxref{Multi-hops}): @example +@group @b{~ $} cd @trampfn{ssh,user@@remotehost,/etc} @key{RET} @b{@trampfn{ssh,user@@remotehost,/etc} $} find-file shadow @key{RET} File is not readable: @trampfn{ssh,user@@remotehost,/etc/shadow} @b{@trampfn{ssh,user@@remotehost,/etc} $} sudo find-file shadow @key{RET} #<buffer shadow> +@end group +@group @b{@trampfn{ssh,user@@remotehost,/etc} $} su - @key{RET} @b{@trampfn{su,root@@remotehost,/root} $} id @key{RET} uid=0(root) gid=0(root) groups=0(root) @b{@trampfn{su,root@@remotehost,/root} $} +@end group @end example -@end ifset @anchor{Running a debugger on a remote host} @@ -2656,26 +2574,36 @@ uid=0(root) gid=0(root) groups=0(root) @cindex perldb @file{gud.el} provides a unified interface to symbolic debuggers -@ifset emacs @ifinfo -(@ref{Debuggers, , , @value{emacsdir}}). +(@ref{Debuggers, , , emacs}). @end ifinfo -@end ifset @value{tramp} can run debug on remote hosts by calling @code{gdb} with a remote file name: @example +@group @kbd{M-x gdb @key{RET}} -@b{Run gdb (like this):} gdb --annotate=3 @trampfn{ssh,host,~/myprog} @key{RET} +@b{Run gdb (like this):} gdb -i=mi @trampfn{ssh,host,~/myprog} @key{RET} +@end group +@end example + +Since the remote @code{gdb} and @code{gdb-inferior} processes do not +belong to the same process group on the remote host, there will be a +warning, which can be ignored: + +@example +&"warning: GDB: Failed to set controlling terminal: Operation not permitted\n" @end example Relative file names are based on the remote default directory. When -@file{myprog.pl} exists in @file{@trampfn{ssh,host,/home/user}}, -valid calls include: +@file{myprog.pl} exists in @file{@trampfn{ssh,host,/home/user}}, valid +calls include: @example +@group @kbd{M-x perldb @key{RET}} @b{Run perldb (like this):} perl -d myprog.pl @key{RET} +@end group @end example Just the local part of a remote file name, such as @kbd{perl -d @@ -2702,16 +2630,20 @@ be set properly so @kbd{M-x shell} can open a proper remote shell on a Windows host. To open @command{cmd}, set it as follows: @lisp +@group (setq explicit-shell-file-name "cmd" explicit-cmd-args '("/q")) +@end group @end lisp @noindent To open @command{powershell} as a remote shell, use this: @lisp +@group (setq explicit-shell-file-name "powershell" explicit-powershell-args '("-file" "-")) +@end group @end lisp @@ -2727,9 +2659,8 @@ the internal representation of a remote connection. When called interactively, this command lists active remote connections in the minibuffer. Each connection is of the format @file{@trampfn{method,user@@host,}}. Flushing remote connections also -cleans the password -cache (@pxref{Password handling}), file cache, connection cache -(@pxref{Connection caching}), and connection buffers. +cleans the password cache (@pxref{Password handling}), file cache, +connection cache (@pxref{Connection caching}), and connection buffers. @end deffn @deffn Command tramp-cleanup-this-connection @@ -2772,11 +2703,9 @@ To subscribe to the mailing list, visit: @uref{http://lists.gnu.org/mailman/listinfo/tramp-devel/, the @value{tramp} Mail Subscription Page}. -@ifset emacs @ifset installchapter Before sending a bug report, run the test suite first @ref{Testing}. @end ifset -@end ifset @findex tramp-bug Check if the bug or problem is already addressed in @xref{Frequently @@ -2835,8 +2764,7 @@ Where is the latest @value{tramp}? @item Which systems does it work on? -The package works successfully on Emacs 22, Emacs 23, Emacs 24, Emacs -25, XEmacs 21 (starting with 21.4), and SXEmacs 22. +The package works successfully on Emacs 23, Emacs 24, and Emacs 25. While Unix and Unix-like systems are the primary remote targets, @value{tramp} has equal success connecting to other platforms, such as @@ -2855,7 +2783,7 @@ responsiveness slows down. Some suggestions within the scope of Use an external method, such as @option{scp}, which are faster than internal methods. -Keep the file @code{tramp-persistency-file-name}, which is where +Keep the file @option{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. @@ -2864,16 +2792,18 @@ files are not independently updated outside @value{tramp}'s control. That cache cleanup will be necessary if the remote directories or files are updated independent of @value{tramp}. -Set @code{tramp-completion-reread-directory-timeout} to @code{nil} to +Set @option{tramp-completion-reread-directory-timeout} to @code{nil} to speed up completions, @ref{File name completion}. Disable version control to avoid delays: @lisp +@group (setq vc-ignore-dir-regexp (format "\\(%s\\)\\|\\(%s\\)" vc-ignore-dir-regexp tramp-file-name-regexp)) +@end group @end lisp Disable excessive traces. Set @code{tramp-verbose} to 3 or lower, @@ -2918,6 +2848,7 @@ When using fish shell on remote hosts, disable fancy formatting by adding the following to @file{~/.config/fish/config.fish}: @example +@group function fish_prompt if test $TERM = "dumb" echo "\$ " @@ -2925,10 +2856,24 @@ function fish_prompt @dots{} end end +@end group @end example -When using WinSSHD on remote hosts, @value{tramp} do not recognize the -strange prompt settings. +When using WinSSHD on remote hosts, @value{tramp} does not recognize +the strange prompt settings. + +A similar problem exist with the iTerm2 shell integration, which sends +proprietary escape codes when starting a shell. This can be +suppressed by changing the respective integration snippet in your +@file{~/.profile} like this: + +@example +@group +[ $TERM = "dumb" ] || \ +test -e "$@{HOME@}/.iterm2_shell_integration.bash" && \ +source "$@{HOME@}/.iterm2_shell_integration.bash" +@end group +@end example @item Echoed characters after login @@ -2956,11 +2901,13 @@ first saving to a temporary file. @end ifinfo @lisp +@group (add-hook 'find-file-hook (lambda () (when (file-remote-p default-directory) (set (make-local-variable 'file-precious-flag) t)))) +@end group @end lisp @end itemize @@ -2974,8 +2921,10 @@ configuration for @command{ssh} can be configured to kill such hangs with the following command in the @file{~/.ssh/config}: @example +@group Host * ServerAliveInterval 5 +@end group @end example @@ -2984,30 +2933,37 @@ Host * @value{tramp} overwrites @code{ControlPath} settings when initiating @command{ssh} sessions. @value{tramp} does this to fend off a stall -if a master session opened outside the @value{emacsname} session is no -longer open. That is why @value{tramp} prompts for the password again -even if there is an @command{ssh} already open. +if a master session opened outside the Emacs session is no longer +open. That is why @value{tramp} prompts for the password again even +if there is an @command{ssh} already open. +@vindex tramp-ssh-controlmaster-options Some @command{ssh} versions support a @code{ControlPersist} option, which allows you to set the @code{ControlPath} provided the variable @code{tramp-ssh-controlmaster-options} is customized as follows: @lisp +@group (setq tramp-ssh-controlmaster-options (concat "-o ControlPath=/tmp/ssh-ControlPath-%%r@@%%h:%%p " "-o ControlMaster=auto -o ControlPersist=yes")) +@end group @end lisp Note how "%r", "%h" and "%p" must be encoded as "%%r", "%%h" and "%%p". +@vindex tramp-use-ssh-controlmaster-options If the @file{~/.ssh/config} is configured appropriately for the above behavior, then any changes to @command{ssh} can be suppressed with this @code{nil} setting: @lisp -(setq tramp-use-ssh-controlmaster-options nil) +@group +(custom-set-variables + '(tramp-use-ssh-controlmaster-options nil nil (tramp))) +@end group @end lisp @@ -3021,9 +2977,9 @@ To test if this is the case, open a remote shell and check if the output of @command{ls} is in color. To disable @acronym{ANSI} escape sequences from the remote hosts, -disable @option{--color=yes} or @option{--color=auto} in the remote -host's @file{.bashrc} or @file{.profile}. Turn this alias on and off -to see if file name completion works. +disable @samp{--color=yes} or @samp{--color=auto} in the remote host's +@file{.bashrc} or @file{.profile}. Turn this alias on and off to see +if file name completion works. @item File name completion does not work in directories with large number of @@ -3036,7 +2992,7 @@ shell's limit on length of command lines and hang. @value{tramp} uses globbing. To test if globbing hangs, open a shell on the remote host and then -run @samp{ls -d * ..?* > /dev/null}. +run @command{ls -d * ..?* > /dev/null}. When testing, ensure the remote shell is the same shell (@command{/bin/sh}, @command{ksh} or @command{bash}), that @@ -3046,117 +3002,62 @@ When testing, ensure the remote shell is the same shell @item How to get notified after @value{tramp} completes file transfers? -Make @value{emacsname} beep after reading from or writing to the -remote host with the following code in @file{~/.emacs} file. +Make Emacs beep after reading from or writing to the remote host with +the following code in @file{~/.emacs} file. @lisp +@group (defadvice tramp-handle-write-region (after tramp-write-beep-advice activate) "Make tramp beep after writing a file." (interactive) (beep)) +@end group +@group (defadvice tramp-handle-do-copy-or-rename-file (after tramp-copy-beep-advice activate) "Make tramp beep after copying a file." (interactive) (beep)) +@end group +@group (defadvice tramp-handle-insert-file-contents (after tramp-insert-beep-advice activate) "Make tramp beep after inserting a file." (interactive) (beep)) +@end group @end lisp -@ifset emacs -@item -How to get a Visual Warning when working with @samp{root} privileges - -Get a modeline indication when working with @samp{root} privileges -with the following code (tested with @value{emacsname} 22.1) in -@file{~/.emacs} file: - -@lisp -(defun my-mode-line-function () - (when (string-match "^/su\\(do\\)?:" default-directory) - (setq mode-line-format - (format-mode-line mode-line-format 'font-lock-warning-face)))) - -(add-hook 'find-file-hook 'my-mode-line-function) -(add-hook 'dired-mode-hook 'my-mode-line-function) -@end lisp -@end ifset - - -@ifset emacs @item -How to get host indication in the mode line? - -The following code (tested with @value{emacsname} 22.1) in -@file{~/.emacs} file shows it: - -@lisp -(defconst my-mode-line-buffer-identification - (list - '(:eval - (let ((host-name - (if (file-remote-p default-directory) - (tramp-file-name-host - (tramp-dissect-file-name default-directory)) - (system-name)))) - (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name) - (substring host-name 0 (match-beginning 1)) - host-name))) - ": %12b")) - -(setq-default - mode-line-buffer-identification - my-mode-line-buffer-identification) - -(add-hook - 'dired-mode-hook - (lambda () - (setq - mode-line-buffer-identification - my-mode-line-buffer-identification))) -@end lisp - -The mode line in @value{emacsname} 23.1 and later versions now -contains an indication if @code{default-directory} for the current -buffer is on a remote host. Moreover, the corresponding tool-tip -shows the remote host name. The above @code{:eval} clause can also be -simplified to show the host name in the mode line: +How to get a Visual Warning when working with @samp{root} privileges? +Host indication in the mode line? -@lisp - '(:eval - (let ((host-name - (or (file-remote-p default-directory 'host) - (system-name)))) - (if (string-match "^[^0-9][^.]*\\(\\..*\\)" host-name) - (substring host-name 0 (match-beginning 1)) - host-name))) -@end lisp -@end ifset +Install @file{tramp-theme} from GNU ELPA via Emacs' Package Manager. +Enable it via @kbd{M-x load-theme @key{RET} tramp}. Further +customization is explained in user option +@option{tramp-theme-face-remapping-alist}. -@ifset emacs @item Remote host does not understand default options for directory listing -@value{emacsname} computes the @command{dired} options based on the -local host but if the remote host cannot understand the same -@command{ls} command, then set them with a hook as follows: +Emacs computes the @command{dired} options based on the local host but +if the remote host cannot understand the same @command{ls} command, +then set them with a hook as follows: @lisp +@group (add-hook 'dired-before-readin-hook (lambda () (when (file-remote-p default-directory) (setq dired-actual-switches "-al")))) +@end group @end lisp -@end ifset @item @@ -3168,6 +3069,7 @@ turn off saving history by putting this shell code in the @file{.kshrc} file: @example +@group if [ -f $HOME/.sh_history ] ; then /bin/rm $HOME/.sh_history fi @@ -3177,6 +3079,7 @@ fi if [ "$@{HISTSIZE-unset@}" != "unset" ] ; then unset HISTSIZE fi +@end group @end example For @option{ssh}-based method, add the following line to your @@ -3202,8 +3105,11 @@ You can define default methods and user names for hosts, (@pxref{Default Method}, @pxref{Default User}): @lisp -(setq tramp-default-method "ssh" - tramp-default-user "news") +@group +(custom-set-variables + '(tramp-default-method "ssh" nil (tramp)) + '(tramp-default-user "news" nil (tramp))) +@end group @end lisp The reduced typing: @kbd{C-x C-f @trampf{news.my.domain,/opt/news/etc}}. @@ -3220,9 +3126,11 @@ Programs used for access methods already offer powerful configurations file @file{~/.ssh/config}: @example +@group Host xy HostName news.my.domain User news +@end group @end example The reduced typing: @kbd{C-x C-f @trampfn{ssh,xy,/opt/news/etc}}. @@ -3235,8 +3143,8 @@ completion can further reduce key strokes: @kbd{C-x C-f Use environment variables to expand long strings For long file names, set up environment variables that are expanded in -the minibuffer. Environment variables are set either outside -@value{emacsname} or inside @value{emacsname} with Lisp: +the minibuffer. Environment variables are set either outside Emacs or +inside Emacs with Lisp: @lisp (setenv "xy" "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}") @@ -3250,9 +3158,10 @@ minibuffer. @item Define own keys: -Redefine another key sequence in @value{emacsname} for @kbd{C-x C-f}: +Redefine another key sequence in Emacs for @kbd{C-x C-f}: @lisp +@group (global-set-key [(control x) (control y)] (lambda () @@ -3261,13 +3170,14 @@ Redefine another key sequence in @value{emacsname} for @kbd{C-x C-f}: (read-file-name "Find Tramp file: " "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}")))) +@end group @end lisp Simply typing @kbd{C-x C-y} would prepare minibuffer editing of file name. -See @uref{http://www.emacswiki.org/cgi-bin/wiki/TrampMode, the Emacs -Wiki} for a more comprehensive example. +See @uref{https://www.emacswiki.org/emacs/TrampMode, the Emacs Wiki} +for a more comprehensive example. @item Define own abbreviation (1): @@ -3275,9 +3185,11 @@ Define own abbreviation (1): Abbreviation list expansion can be used to reduce typing long file names: @lisp +@group (add-to-list 'directory-abbrev-alist '("^/xy" . "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}")) +@end group @end lisp The reduced typing: @kbd{C-x C-f /xy @key{RET}}. @@ -3293,23 +3205,31 @@ The @code{abbrev-mode} gives additional flexibility for editing in the minibuffer: @lisp +@group (define-abbrev-table 'my-tramp-abbrev-table '(("xy" "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}"))) +@end group +@group (add-hook 'minibuffer-setup-hook (lambda () (abbrev-mode 1) (setq local-abbrev-table my-tramp-abbrev-table))) +@end group +@group (defadvice minibuffer-complete (before my-minibuffer-complete activate) (expand-abbrev)) +@end group +@group ;; If you use partial-completion-mode (defadvice PC-do-completion (before my-PC-do-completion activate) (expand-abbrev)) +@end group @end lisp The reduced typing: @kbd{C-x C-f xy @key{TAB}}. @@ -3320,157 +3240,118 @@ The minibuffer expands for further editing. Use bookmarks to save Tramp file names. @ifinfo -@pxref{Bookmarks, , , @value{emacsdir}}. +@pxref{Bookmarks, , , emacs}. @end ifinfo Upon visiting a location with @value{tramp}, save it as a bookmark with -@ifset emacs @kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{set}}. -@end ifset -@ifset xemacs -@kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{set}}. -@end ifset To revisit that bookmark: -@ifset emacs @kbd{@key{menu-bar} @key{edit} @key{bookmarks} @key{jump}}. -@end ifset -@ifset xemacs -@kbd{@key{menu-bar} @key{view} @key{bookmarks} @key{jump}}. -@end ifset @item Use recent files: -@ifset emacs -@file{recentf} -@end ifset -@ifset xemacs -@file{recent-files} -@end ifset -remembers visited places. +@file{recentf} remembers visited places. @ifinfo -@ifset emacs -@pxref{File Conveniences, , , @value{emacsdir}}. -@end ifset -@ifset xemacs -@pxref{recent-files, , , edit-utils}. -@end ifset +@pxref{File Conveniences, , , emacs}. @end ifinfo Keep remote file names in the recent list without have to check for their accessibility through remote access: @lisp -@ifset emacs (recentf-mode 1) -@end ifset -@ifset xemacs -(recent-files-initialize) -(add-hook - 'find-file-hook - (lambda () - (when (file-remote-p (buffer-file-name)) - (recent-files-make-permanent))) - 'append) -@end ifset @end lisp -Reaching recently opened files: -@ifset emacs -@kbd{@key{menu-bar} @key{file} @key{Open Recent}}. -@end ifset -@ifset xemacs -@kbd{@key{menu-bar} @key{Recent Files}}. -@end ifset +Reaching recently opened files: @kbd{@key{menu-bar} @key{file} +@key{Open Recent}}. -@ifset emacs @item Use filecache: Since @file{filecache} remembers visited places, add the remote directory to the cache: @lisp +@group @c `with-eval-after-load' has been introduced with Emacs 24.4. Shall @c be used when appropriate. (eval-after-load "filecache" '(file-cache-add-directory "@trampfn{ssh,news@@news.my.domain,/opt/news/etc/}")) +@end group @end lisp Then use directory completion in the minibuffer with @kbd{C-x C-f C-@key{TAB}}. -@end ifset -@ifset emacs @item Use bbdb: -@file{bbdb} has a built-in feature for @value{ftppackagename} files, -which also works for @value{tramp} file names. +@file{bbdb} has a built-in feature for Ange FTP files, which also +works for @value{tramp} file names. @ifinfo @pxref{bbdb-ftp, Storing FTP sites in the BBDB, , bbdb}. @end ifinfo -Load @file{bbdb} in @value{emacs}: +Load @file{bbdb} in Emacs: @lisp +@group (require 'bbdb) (bbdb-initialize) +@end group @end lisp Create a BBDB entry with @kbd{M-x bbdb-create-ftp-site}. Then specify a method and user name where needed. Examples: @example +@group @kbd{M-x bbdb-create-ftp-site @key{RET}} @b{Ftp Site:} news.my.domain @key{RET} @b{Ftp Directory:} /opt/news/etc/ @key{RET} @b{Ftp Username:} ssh@value{postfixhop}news @key{RET} @b{Company:} @key{RET} @b{Additional Comments:} @key{RET} +@end group @end example In BBDB buffer, access an entry by pressing the key @key{F}. -@end ifset @end enumerate Thanks to @value{tramp} users for contributing to these recipes. @item -Why saved multi-hop file names do not work in a new @value{emacsname} -session? +Why saved multi-hop file names do not work in a new Emacs session? When saving ad-hoc multi-hop @value{tramp} file names (@pxref{Ad-hoc -multi-hops}) via bookmarks, recent files, -@ifset emacs -filecache, bbdb, -@end ifset -or another package, use the full ad-hoc file name including all hops, -like +multi-hops}) via bookmarks, recent files, filecache, bbdb, or another +package, use the full ad-hoc file name including all hops, like @file{@trampfn{ssh,bird@@bastion|ssh@value{postfixhop}news.my.domain,/opt/news/etc}}. Alternatively, when saving abbreviated multi-hop file names -@file{@trampfn{ssh,news@@news.my.domain,/opt/news/etc}}, the custom -option @code{tramp-save-ad-hoc-proxies} must be set non-@code{nil} +@file{@trampfn{ssh,news@@news.my.domain,/opt/news/etc}}, the user +option @option{tramp-save-ad-hoc-proxies} must be set non-@code{nil} value. -@ifset emacs @item -How to connect to a remote @value{emacsname} session using @value{tramp}? +How to connect to a remote Emacs session using @value{tramp}? Configure Emacs Client @ifinfo -(@pxref{Emacs Server, , , @value{emacsdir}}). +(@pxref{Emacs Server, , , emacs}). @end ifinfo Then on the remote host, start the Emacs Server: @lisp +@group (require 'server) (setq server-host (system-name) server-use-tcp t) (server-start) +@end group @end lisp If @code{(system-name)} of the remote host cannot be resolved on the @@ -3492,8 +3373,10 @@ To make Emacs Client an editor for other programs, use a wrapper script @file{emacsclient.sh}: @example +@group #!/bin/sh emacsclient @trampfn{ssh,$(whoami)@@$(hostname --fqdn),$1} +@end group @end example Then change the environment variable @env{EDITOR} to point to the @@ -3502,7 +3385,6 @@ wrapper script: @example export EDITOR=/path/to/emacsclient.sh @end example -@end ifset @item @@ -3520,8 +3402,7 @@ disable such features. Disable @value{tramp} file name completion: @lisp -(custom-set-variables - '(ido-enable-tramp-completion nil)) +(custom-set-variables '(ido-enable-tramp-completion nil)) @end lisp @item @@ -3539,35 +3420,25 @@ Disable remote directory tracking mode: How to disable @value{tramp}? @itemize @minus -@ifset emacs @item -To keep @value{ftppackagename} as default the remote files access -package, set this in @file{.emacs}: +To keep Ange FTP as default the remote files access package, set this +in @file{.emacs}: @lisp -(setq tramp-default-method "ftp") +(custom-set-variables '(tramp-default-method "ftp" nil (tramp))) @end lisp -@end ifset @item -To disable both -@ifset emacs -@value{tramp} (and @value{ftppackagename}), -@end ifset -@ifset xemacs -@value{tramp}, -@end ifset -set @code{tramp-mode} to @code{nil} in @file{.emacs}. +To disable both @value{tramp} (and Ange FTP), set @code{tramp-mode} to +@code{nil} in @file{.emacs}. @lisp -(setq tramp-mode nil) +(custom-set-variables '(tramp-mode nil nil (tramp))) @end lisp @item -To unload @value{tramp}, type @kbd{M-x tramp-unload-tramp}. -@ifset emacs -Unloading @value{tramp} resets @value{ftppackagename} plugins also. -@end ifset +To unload @value{tramp}, type @kbd{M-x tramp-unload-tramp}. Unloading +@value{tramp} resets Ange FTP plugins also. @end itemize @end itemize @@ -3578,9 +3449,7 @@ Unloading @value{tramp} resets @value{ftppackagename} plugins also. @menu * Localname deconstruction:: Splitting a localname into its component parts. -@ifset emacs * External packages:: Integrating with external Lisp packages. -@end ifset @end menu @@ -3598,7 +3467,6 @@ file name. By relying on the original handlers for localnames, handlers. -@ifset emacs @node External packages @section Integrating with external Lisp packages @subsection File name completion. @@ -3617,8 +3485,10 @@ the variable @code{non-essential} temporarily and bind it to non-@code{nil} value. @lisp +@group (let ((non-essential t)) @dots{}) +@end group @end lisp @@ -3636,8 +3506,10 @@ situations where callers to @code{process-file} know there are no file attribute changes. The let-bind form to accomplish this: @lisp +@group (let (process-file-side-effects) @dots{}) +@end group @end lisp For asynchronous processes, @value{tramp} uses a process sentinel to @@ -3649,14 +3521,15 @@ sentinel is overwritten. The caller can still flush the file attributes cache in its process sentinel with this code: @lisp +@group (unless (memq (process-status proc) '(run open)) (dired-uncache remote-directory)) +@end group @end lisp Since @value{tramp} traverses subdirectories starting with the root-directory, it is most likely sufficient to make the @code{default-directory} of the process buffer as the root directory. -@end ifset @node Traces and Profiles @@ -3687,7 +3560,7 @@ set the @code{tramp-verbose} level to 6 (@pxref{Bug Reports}). The debug buffer is in @ifinfo -@ref{Outline Mode, , , @value{emacsdir}}. +@ref{Outline Mode, , , emacs}. @end ifinfo @ifnotinfo Outline Mode. @@ -3696,88 +3569,34 @@ In this buffer, messages can be filtered by their level. To see messages up to verbosity level 5, enter @kbd{C-u 6 C-c C-q}. @ifinfo Other navigation keys are described in -@ref{Outline Visibility, , , @value{emacsdir}}. +@ref{Outline Visibility, , , emacs}. @end ifinfo @value{tramp} handles errors internally. But to get a Lisp backtrace, both the error and the signal have to be set as follows: @lisp +@group (setq debug-on-error t debug-on-signal t) +@end group @end lisp To enable stepping through @value{tramp} function call traces, they have to be specifically enabled as shown in this code: @lisp +@group (require 'trace) (dolist (elt (all-completions "tramp-" obarray 'functionp)) (trace-function-background (intern elt))) (untrace-function 'tramp-read-passwd) -(untrace-function 'tramp-gw-basic-authentication) +@end group @end lisp The buffer @file{*trace-output*} contains the output from the function -call traces. Disable @code{tramp-read-passwd} and -@code{tramp-gw-basic-authentication} to stop password strings from -being written to @file{*trace-output*}. - - -@node Issues -@chapter Debatable Issues and What Was Decided - -@itemize @bullet -@item The uuencode method does not always work. - -@command{uudecode} on some systems cannot write to stdout, but -@value{tramp} depends on encoding and decoding programs to be able to -read from stdin and write to stdout. - -We can find ways to circumvent @command{uudecode}'s ability to write -to stdout, such as writing to a temporary file and then piping that to -stdout. - -But I have decided not to implement workarounds as they are too -fragile to work reliably. Some on systems, @value{tramp} will not have -uuencode method. - -@item The @value{tramp} file name syntax differs between Emacs and XEmacs. - -The Emacs maintainers wish to use a unified file name syntax for -Ange-FTP and @value{tramp} so that users don't have to learn yet -another syntax though it is okay to learn new extensions. - -For the XEmacs maintainers, the disruption from a unified file name -syntax are not worth the gains. Firstly, the XEmacs package system -relies on EFS for downloading new packages and therefore is already -installed. On the other hand, @value{tramp} is not installed by -default in XEmacs. Unifying will require @value{tramp} installed from -the start. - -@ifset xemacs -@strong{Note:} To make the syntax similar to @value{ftppackagename}, -make this change to the init file: - -@lisp -(setq tramp-unified-filenames t) -(require 'tramp) -@end lisp - -To disable auto loading @value{emacsname} @value{tramp} package, set -file permissions of -@file{@dots{}/xemacs-packages/lisp/tramp/auto-autoloads.el*} to -@code{000}. - -When using unified file names, @value{emacsname} download sites are -added to @code{tramp-default-method-alist} with default method of -@option{ftp} @xref{Default Method} for proper working of the -@value{emacsname} package system. - -The syntax for unified file names is described in the @value{tramp} manual -for @value{emacsothername}. -@end ifset -@end itemize +call traces. Disable @code{tramp-read-passwd} to stop password +strings from being written to @file{*trace-output*}. @node GNU Free Documentation License diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index b12614bae53..2677672444e 100644 --- a/doc/misc/trampver.texi +++ b/doc/misc/trampver.texi @@ -8,7 +8,7 @@ @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.2.13.25.2 +@set trampver 2.3.1 @c Other flags from configuration @set instprefix /usr/local @@ -16,54 +16,29 @@ @set infodir /usr/local/share/info @c Formatting of the tramp program name consistent. -@set tramp @sc{tramp} +@set tramp @sc{Tramp} -@c Whether or not describe GVFS integration. -@ifclear noemacsgvfs -@set emacsgvfs -@end ifclear - -@c Whether or not describe gateway methods. -@ifclear noemacsgw -@set emacsgw -@end ifclear - -@c Some flags which make the text independent on the (X)Emacs flavor. -@c "emacs" resp "xemacs" are set in the Makefile. Default is "emacs". -@ifclear emacs -@ifclear xemacs -@set emacs +@c Some flags which define the remote file name syntax. +@ifclear unified +@ifclear separate +@set unified @end ifclear @end ifclear -@c Emacs values. -@ifset emacs -@set emacsname Emacs -@set emacsdir emacs -@set ftppackagename Ange-FTP +@ifset unified @set prefix / @set prefixhop @set postfix : @set postfixhop : @set ipv6prefix [ @set ipv6postfix ] -@set emacsothername XEmacs -@set emacsotherdir xemacs -@set emacsotherfilename tramp-xemacs.html @end ifset -@c XEmacs counterparts. -@ifset xemacs -@set emacsname XEmacs -@set emacsdir xemacs -@set ftppackagename EFS +@ifset separate @set prefix /[ @set prefixhop [ @set postfix ] @set postfixhop / @set ipv6prefix @set ipv6postfix -@set emacsothername Emacs -@set emacsotherdir emacs -@set emacsotherfilename tramp-emacs.html @end ifset diff --git a/doc/misc/url.texi b/doc/misc/url.texi index 91cb6b54a84..06d2e559c38 100644 --- a/doc/misc/url.texi +++ b/doc/misc/url.texi @@ -289,7 +289,7 @@ string or a parsed URL structure. If it is a string, that string is passed through @code{url-encode-url} before using it, to ensure that it is properly URI-encoded (@pxref{URI Encoding}). -@defun url-retrieve-synchronously url silent no-cookies +@defun url-retrieve-synchronously url &optional silent no-cookies timeout This function synchronously retrieves the data specified by @var{url}, and returns a buffer containing the data. The return value is @code{nil} if there is no data associated with the URL (as is the case @@ -297,7 +297,9 @@ for @code{dired}, @code{info}, and @code{mailto} URLs). If the optional argument @var{silent} is non-@code{nil}, progress messages are suppressed. If the optional argument @var{no-cookies} is -non-@code{nil}, cookies are not stored or sent. +non-@code{nil}, cookies are not stored or sent. If the optional +argument @var{timeout} is non-@code{nil}, it should be a number that +says (in seconds) how long to wait for a response before giving up. @end defun @defun url-retrieve url callback &optional cbargs silent no-cookies @@ -421,6 +423,12 @@ cookies, if there are any. You can remove a cookie using the @kbd{C-k} (@code{url-cookie-delete}) command. @end defun +@defun url-cookie-delete-cookies &optional regexp +This function takes a regular expression as its parameters and deletes +all cookies from that domain. If @var{regexp} is @code{nil}, delete +all cookies. +@end defun + @defopt url-cookie-file The file in which cookies are stored, defaulting to @file{cookies} in the directory specified by @code{url-configuration-directory}. @@ -1335,10 +1343,16 @@ Connect directly. @end defopt @defopt url-user-agent -The User Agent string used for sending HTTP/HTTPS requests. The value -should be a string or a function of no arguments that returns a -string. The default value is @w{@samp{User-Agent: @var{package-name} -URL/Emacs}}, where @var{package-name} is the value of +The User Agent string used for sending @acronym{HTTP}/@acronym{HTTPS} +requests. The value should be @code{nil}, which means that no +@samp{User-Agent} header is generated, @code{default}, which means +that a string is generated based on the setting of +@code{url-privacy-leve}, a string or a function of no arguments that +returns a string. + +The default is @code{default}, which means that the +@w{@samp{User-Agent: @var{package-name} URL/Emacs}} string will be +generated, where @var{package-name} is the value of @code{url-package-name} and its version, if they are non-@code{nil}. @end defopt |