diff options
Diffstat (limited to 'doc')
49 files changed, 2129 insertions, 1249 deletions
diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index df0764ee6b..a416734d40 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/cmdargs.texi b/doc/emacs/cmdargs.texi index f0f686f855..444d30527f 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 diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index c109335375..01637ae98a 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 @@ -1396,7 +1407,7 @@ init file (@pxref{Init Rebinding}). * Minibuffer Maps:: The minibuffer uses its own local keymaps. * Rebinding:: How to redefine one key's meaning conveniently. * Init Rebinding:: Rebinding keys with your initialization file. -* Modifier Keys:: Using modifier keys in key bindings. +* Modifier Keys:: Using modifier keys. * Function Keys:: Rebinding terminal function keys. * Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. * Mouse Buttons:: Rebinding mouse buttons in Emacs. diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi index 1b10ebc875..2cda51a82f 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 56b643becf..738d72d046 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -613,6 +613,9 @@ This face underlines text. This face forces use of a fixed-width font. It's reasonable to customize this face to use a different fixed-width font, if you like, but you should not make it a variable-width font. +@item fixed-pitch-serif +This face is like @code{fixed-pitch}, except the font has serifs and +looks more like traditional typewriting. @cindex variable-pitch face @item variable-pitch This face forces use of a variable-width font. @@ -657,6 +660,9 @@ The face for displaying control characters and escape sequences @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 @@ -1487,7 +1493,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 diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index fc46ef7879..f195a41d54 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -1968,6 +1968,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 7e6006262c..03172b62cf 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/m-x.texi b/doc/emacs/m-x.texi index 9e5f50b5e9..4b1165a113 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 aca29910b7..1037bd1fdd 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 diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index 853b978492..94e1f198f2 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -1580,6 +1580,44 @@ 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. + +@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 @command{systemd}'s +socket functionality: 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.service}: +@example +[Unit] +Description=Emacs + +[Service] +Type=forking +ExecStart=/path/to/emacs --daemon +ExecStop=/path/to/emacsclient --eval "(kill-emacs)" +Restart=always + +[Install] +WantedBy=default.target +@end example + +@file{~/.config/systemd/user/emacs.socket}: +@example +[Socket] +ListenStream=/path/to/.emacs.socket + +[Install] +WantedBy=sockets.target +@end example + +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 diff --git a/doc/emacs/msdos.texi b/doc/emacs/msdos.texi index 6ad12d646a..a87561ccf1 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. @@ -607,12 +639,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/trouble.texi b/doc/emacs/trouble.texi index 7a5defabf0..fbd13c8a58 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/lispref/commands.texi b/doc/lispref/commands.texi index 6e83659f63..46756d0ddd 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 diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 0d0ec671f7..b7a6b570eb 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -3020,6 +3020,7 @@ attribute on this face (@pxref{Face Attributes}). @itemx bold-italic @itemx underline @itemx fixed-pitch +@itemx fixed-pitch-serif @itemx variable-pitch These have the attributes indicated by their names (e.g., @code{bold} has a bold @code{:weight} attribute), with all other attributes @@ -4772,6 +4773,7 @@ displayed (@pxref{Display Feature Testing}). * 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. @@ -5144,12 +5146,18 @@ specifying the bounding box of the PostScript image, analogous to the @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 the actual underlying image format. +To check for ImageMagick support, use the following: + +@lisp +(image-type-available-p 'imagemagick) +@end lisp + @defun imagemagick-types This function returns a list of image file extensions supported by the current ImageMagick installation. Each list element is a symbol @@ -5209,6 +5217,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 @@ -5223,6 +5241,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 @@ -5259,9 +5434,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}. @@ -5325,6 +5497,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}. @@ -5395,6 +5573,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 @@ -5504,6 +5689,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 diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index 47fe02a4a5..65ccb64690 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/files.texi b/doc/lispref/files.texi index 6b7ee19d5f..ea9d53b0ea 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -1195,73 +1195,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}: @@ -3228,7 +3238,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 @@ -3259,6 +3271,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/functions.texi b/doc/lispref/functions.texi index a2e94c34b6..fff4ac0ee8 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 @@ -2144,44 +2172,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 8389c21470..4607bb0a0d 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 b945e438f5..1bb2c7c4d0 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 41064df5a2..fedef3d7f4 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 0f42d4d8a7..2f84aeee39 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 f5d3811fae..35d9d0c965 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -341,7 +341,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/minibuf.texi b/doc/lispref/minibuf.texi index 1fa2536db4..8d5347556e 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 32baa27147..368d882a4b 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 from Emacs 25.2, 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 9cf3b5750f..fd2ce3248f 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 324593068d..54894b8e24 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}. diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index ec14b014e5..08c69d37c5 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -904,9 +904,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. @@ -1332,7 +1329,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 @@ -1430,10 +1433,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 @@ -1866,6 +1865,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 diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index 1d748b8752..796a06615a 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -590,10 +590,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} @@ -604,8 +606,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 b4542f65cc..cd1201276e 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -2185,7 +2185,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: @@ -2409,8 +2410,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. @@ -2422,6 +2424,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 @@ -2472,8 +2480,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 1243d720bc..644716a95c 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -1805,6 +1805,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 a54ab104ab..08e5e3ae35 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}, diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index ca700a29a9..4e4c239291 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -633,6 +633,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 @@ -826,16 +834,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 19782d0fbd..f81c1643c2 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 7791c261e3..4dc943f868 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -2362,6 +2362,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 @@ -4392,6 +4469,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 @@ -4523,6 +4614,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/tips.texi b/doc/lispref/tips.texi index d12de7aee2..a8589df031 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 a2d64815d9..418a4161a7 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1615,7 +1615,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 @@ -1632,11 +1632,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 diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 55d90bd5d0..ad0c3237e6 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -545,6 +545,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 +565,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 @@ -2159,8 +2171,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 @@ -2403,6 +2416,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 @@ -4093,11 +4123,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}, @@ -4384,33 +4414,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/misc/Makefile.in b/doc/misc/Makefile.in index 4dffeafb1d..eca74a0c64 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 459369ed9c..f311ec8a3a 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 @@ -6654,15 +6655,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 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @@ -6714,7 +6718,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 @@ -6723,9 +6727,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 @@ -6763,10 +6769,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/emacs-gnutls.texi b/doc/misc/emacs-gnutls.texi index 1a850c6823..9d52508b64 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 4d68246bba..2b935870da 100644 --- a/doc/misc/emacs-mime.texi +++ b/doc/misc/emacs-mime.texi @@ -1826,6 +1826,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 7726a8d3dc..81f97a9db8 100644 --- a/doc/misc/eww.texi +++ b/doc/misc/eww.texi @@ -109,6 +109,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 +164,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/gnus.texi b/doc/misc/gnus.texi index 08067b0c73..2473d26cc1 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 @@ -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/message.texi b/doc/misc/message.texi index 761fb772f4..048990d53a 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 @@ -1672,10 +1672,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 @@ -2586,22 +2586,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/ses.texi b/doc/misc/ses.texi index 58f9ba8ccf..84d2cc77c0 100644 --- a/doc/misc/ses.texi +++ b/doc/misc/ses.texi @@ -374,26 +374,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 +437,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 +480,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 +498,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 diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex index 37e2de896e..5a1f728da4 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-08-03.13} % % 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. @@ -1188,6 +1192,7 @@ 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. @@ -1307,8 +1312,10 @@ output) for that.)} % 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 + % Use ASCII approximations in destination names. + \passthroughcharsfalse \def\pdfdestname{#1}% \txiescapepdf\pdfdestname \safewhatsit{\pdfdest name{\pdfdestname} xyz}% @@ -1353,8 +1360,21 @@ output) for that.)} \fi % % Also escape PDF chars in the display string. - \edef\pdfoutlinetext{#1}% - \txiescapepdf\pdfoutlinetext + \bgroup + \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 + \fi + \ifx \declaredencoding \utfeight + % TODO: the PDF format can use UTF-16 in bookmark strings, but the + % code for this isn't done yet. + \fi + \globaldefs=1 + \edef\pdfoutlinetext{#1}% + \txiescapepdf\pdfoutlinetext + \egroup % \pdfoutline goto name{\pdfmkpgn{\pdfoutlinedest}}#2{\pdfoutlinetext}% } @@ -1521,23 +1541,72 @@ output) for that.)} % % 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{{% % We have to set dummies so commands such as @code, and characters @@ -1546,7 +1615,7 @@ output) for that.)} \iftxiuseunicodedestname \def\pdfdestname{#1}% Pass through Unicode characters. \else - \edef\pdfdestname{#1}% Replace Unicode characters to ASCII. + \edef\pdfdestname{#1}% Replace Unicode characters with ASCII. \fi \turnoffactive \makevalueexpandable @@ -1554,11 +1623,16 @@ output) for that.)} \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. + \edef\pdfoutlinedest{#3}% Replace Unicode characters with ASCII. \fi \ifx\pdfoutlinedest\empty \def\pdfoutlinedest{#4}% @@ -1570,17 +1644,17 @@ output) for that.)} \txiescapepdf\pdfoutlinetext % \special{pdf:out [-] #2 << /Title (\pdfoutlinetext) /A - << /S /GoTo /D (name\pdfoutlinedest) >> >> }% + << /S /GoTo /D (\pdfoutlinedest) >> >> }% } } % \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 +1674,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 +1696,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 +1758,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 +1770,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. @@ -3268,23 +3342,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 = , @@ -4603,6 +4664,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 +4813,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 +4823,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 +4832,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\_% @@ -4889,85 +4966,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 +5097,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 @@ -5112,8 +5186,11 @@ end % goes to end-of-line is not handled. % \macrolist + \let\value\indexnofontsvalue } + + \let\SETmarginindex=\relax % put index entries in margin (undocumented)? @@ -5159,9 +5236,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 +5437,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 +5447,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 % @@ -5890,38 +5969,49 @@ 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. + % Remove glue from bottom of columns to compare + % apparent heights. \global\setbox1 = \vbox{\unvbox1\unpenalty\unskip}% - \ifdim\ht3>\ht1 + \global\setbox3 = \vbox{\unvbox3\unpenalty\unskip}% + \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}% + \setbox2=\vbox to\dimen@ii{\unvbox2}% \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. + \setbox0=\vbox to\dimen@{\unvbox1}% + \setbox2=\vbox to\dimen@{\unvbox3}% + \fi \fi \fi % @@ -6682,7 +6772,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 } @@ -7963,7 +8060,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 +8068,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 +8209,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 +8224,7 @@ end \ifx #1\relax % remove this \else - \noexpand\definedummyword \noexpand#1% + \noexpand\commondummyword \noexpand#1% \fi } @@ -8402,8 +8499,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 +8514,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 +8751,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,16 +8845,21 @@ end \ifpdf % For pdfTeX and LuaTeX {\indexnofonts - \turnoffactive \makevalueexpandable + % + % This (wrongly) does not take account of leading or trailing + % spaces in #1, which should be ignored. + \ifx\luatexversion\thisisundefined + \edef\pdfxrefdest{#1}% pdfTeX: Replace Unicode characters with ASCII. + \else + \def\pdfxrefdest{#1}% LuaTeX: Pass through Unicode characters. + \fi + \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. \getfilename{#4}% % - % 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 @@ -8820,20 +8880,21 @@ end \else % For XeTeX {\indexnofonts - \turnoffactive \makevalueexpandable - % 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. - \getfilename{#4}% % % 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. + \edef\pdfxrefdest{#1}% Replace Unicode characters with ASCII. \fi + \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. + \getfilename{#4}% + % \ifx\pdfxrefdest\empty \def\pdfxrefdest{Top}% no empty targets \else @@ -8842,16 +8903,19 @@ end % \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 (\pdfxrefdest) >> >>}% \else \special{pdf:bann << /Border [0 0 0] /Type /Annot /Subtype /Link /A - << /S /GoTo /D (name\pdfxrefdest) >> >>}% + << /S /GoTo /D (\pdfxrefdest) >> >>}% \fi }% \setcolor{\linkcolor}% @@ -8862,6 +8926,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 +9067,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 +9099,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 +9822,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 +9948,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 +9967,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 auxiallity files.}% + \fi + \fi + \fi } % emacs-page @@ -10200,7 +10280,7 @@ directory should work if nowhere else does.} \countUTFx = "80 \countUTFy = "C2 \def\UTFviiiTmp{% - \gdef~{ + \gdef~{% \ifpassthroughchars $\fi}}% \UTFviiiLoop @@ -10236,8 +10316,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 +10332,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 +10357,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 +10378,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 @@ -11031,8 +11138,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 +11162,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 +11188,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 diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 5ce10d298c..2c41dddd1b 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -17,9 +17,9 @@ @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,10 +51,10 @@ 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 @@ -68,39 +68,25 @@ copy and modify this GNU manual.'' @contents -@ifnottex @node Top, Overview, (dir), (dir) @top @value{tramp} version @value{trampver} User Manual +@ifnottex 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 @@ -126,7 +112,6 @@ The Mail Archive}. @end ifhtml @insertcopying - @end ifnottex @menu @@ -137,7 +122,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 +135,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 +145,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,12 +157,8 @@ 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. @@ -200,15 +180,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 +197,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 +222,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 +256,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 +334,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,7 +356,7 @@ navigation bar at the top. Another way is to follow the terminal session below: @example -] @strong{cd ~/@value{emacsdir}} +] @strong{cd ~/emacs} ] @strong{git clone git://git.savannah.gnu.org/tramp.git} @end example @@ -400,14 +376,14 @@ 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} +] @strong{cd ~/emacs/tramp} ] @strong{git pull} @end example @@ -416,7 +392,7 @@ Run @command{autoconf} as follows to generate an up-to-date @file{configure} script: @example -] @strong{cd ~/@value{emacsdir}/tramp} +] @strong{cd ~/emacs/tramp} ] @strong{autoconf} @end example @@ -436,23 +412,13 @@ 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. 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. @@ -468,8 +434,8 @@ 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}. +file name @file{@trampf{user@@host,/path/to.file}}. For details, see +@xref{Default Method}. For problems related to the behavior of remote shell, see @ref{Remote shell setup} for details. @@ -479,8 +445,8 @@ defaults to one of several other options, see (@pxref{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: +examples are not auto loaded by Emacs. All examples require +@value{tramp} is installed and loaded: @lisp (require 'tramp) @@ -491,12 +457,8 @@ 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 @@ -561,7 +523,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 @@ -593,7 +555,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 +565,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 +574,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 +590,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 +642,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 +655,6 @@ session. @option{plink} method supports the @samp{-P} argument. - @item @option{plinkx} @cindex method plinkx @cindex plinkx method @@ -757,7 +731,6 @@ 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} @cindex method scpx @cindex scpx method @@ -774,7 +747,6 @@ 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} @cindex method pscp @@ -798,7 +770,6 @@ session. These methods support the @samp{-P} argument. - @item @option{fcp}---@command{fsh} and @command{fcp} @cindex method fcp @cindex fcp method @@ -839,13 +810,8 @@ 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} @cindex method smb @@ -866,7 +832,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 +871,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 @@ -933,12 +899,12 @@ or the absolute path set in the variable @var{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 @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 +921,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 +932,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 +957,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 +980,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 @@ -1022,13 +1002,11 @@ requires the SYNCE-GVFS plugin. @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}. +@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 @@ -1061,7 +1039,6 @@ 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 @@ -1073,7 +1050,6 @@ The default port number for the socks server is @option{1080}, if not specified otherwise. @end table -@end ifset @node Default Method @@ -1197,9 +1173,9 @@ 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 (add-to-list 'tramp-default-user-alist @@ -1222,9 +1198,9 @@ for catch-all or most often used login. @vindex tramp-default-host-alist 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 -default user and default host can be overridden as follows: +the @code{tramp-default-host} variable. 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" @@ -1234,10 +1210,8 @@ default user and default host can be overridden as follows: With both defaults set, @samp{@trampfn{ssh,,}} will connect @value{tramp} to John's home directory on target. -@ifset emacs @strong{Note} @samp{/::} won't work, because @samp{/:} is the prefix for quoted file names. -@end ifset Instead of a single default host, @code{tramp-default-host-alist} allows multiple default host values based on access method or user @@ -1276,13 +1250,8 @@ 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 @var{user}@@@var{host}. @@ -1322,9 +1291,9 @@ access, then use this alist entry: '("\\.your\\.domain\\'" "\\`root\\'" "@trampfn{ssh,%h,}")) @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. @@ -1346,7 +1315,6 @@ local one, first connect via @command{ssh}, and then apply 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. @@ -1367,7 +1335,6 @@ discussion of ethical issues.} Then the configuration is: @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 @@ -1495,6 +1462,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 @@ -1566,24 +1538,13 @@ the same user or host name independent of the access method. @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 @@ -1594,17 +1555,12 @@ For faster initial connection times, @value{tramp} stores previous connection properties in a file specified by the variable @code{tramp-persistency-file-name}. -The default file name for @code{tramp-persistency-file-name} is: -@ifset emacs +The default file name for @code{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 storing connections persistently. @@ -1710,19 +1666,22 @@ shown below for @value{tramp} to use when connecting. 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}. @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 @@ -1893,9 +1852,7 @@ fi @end example @ifinfo -@ifset emacs -@xref{Interactive Shell, , , @value{emacsdir}}. -@end ifset +@xref{Interactive Shell, , , emacs}. @end ifinfo @item @command{busybox} / @command{nc} @@ -1910,7 +1867,7 @@ 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 @@ -1938,9 +1895,9 @@ 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 (add-to-list 'tramp-connection-properties @@ -1970,8 +1927,8 @@ 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: @@ -2001,59 +1958,32 @@ 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 +@code{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 @code{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 (add-to-list 'backup-directory-alist (cons tramp-file-name-regexp nil)) @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: @@ -2067,26 +1997,13 @@ Disabling backups can be targeted to just the @option{su} and (when (stringp method) (member method '("su" "sudo")))))))) @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} variable @code{tramp-backup-directory-alist} from the +existing variable @code{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 +2012,35 @@ happens only when the DIRECTORY is an absolute local file name. @noindent Example: -@ifset emacs @lisp (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) -@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 +auto-saving @value{tramp} files. 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. +this points to the source directory where the Emacs was compiled. +Reset such values to a valid directory. Set @code{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 @node Windows setup hints @section Issues with Cygwin ssh @@ -2150,9 +2051,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. @@ -2166,7 +2067,7 @@ Some older versions of Cygwin's @command{ssh} work with the @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 +2077,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 +2098,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 +2125,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 +2154,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 +2167,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,13 +2196,11 @@ 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 @@ -2321,24 +2208,17 @@ For example, type @kbd{C-x C-f @value{prefix}t @key{TAB}}, @example @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 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}} @@ -2365,21 +2245,18 @@ 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 @kbd{C-x C-f @trampfn{telnet,melancholia,/usr/local/bin//etc} @key{TAB}} @print{} @trampfn{telnet,melancholia,/etc} @@ -2388,22 +2265,13 @@ 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 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 @@ -2437,15 +2305,15 @@ 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: +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}. @lisp (setq tramp-save-ad-hoc-proxies t) @@ -2454,14 +2322,13 @@ sessions, set @option{tramp-save-ad-hoc-proxies}. @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 @@ -2476,12 +2343,9 @@ host when the variable @code{default-directory} is remote: "/bin/sh" "-c" "grep -e tramp *")) @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 @@ -2544,8 +2408,8 @@ them as follows: 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 @@ -2580,11 +2444,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 @@ -2602,9 +2464,7 @@ host. 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 @@ -2627,9 +2487,8 @@ uid=0(root) gid=0(root) groups=0(root) @b{@trampfn{sudo,root@@host,/etc} $} @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 (@pxref{Multi-hops}): @@ -2646,7 +2505,6 @@ File is not readable: @trampfn{ssh,user@@remotehost,/etc/shadow} uid=0(root) gid=0(root) groups=0(root) @b{@trampfn{su,root@@remotehost,/root} $} @end example -@end ifset @anchor{Running a debugger on a remote host} @@ -2656,11 +2514,9 @@ 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: @@ -2670,8 +2526,8 @@ with a remote file name: @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 @kbd{M-x perldb @key{RET}} @@ -2727,9 +2583,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 +2627,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 +2688,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 @@ -2984,9 +2836,9 @@ 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. Some @command{ssh} versions support a @code{ControlPersist} option, which allows you to set the @code{ControlPath} provided the variable @@ -3021,9 +2873,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 +2888,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,8 +2898,8 @@ 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 (defadvice tramp-handle-write-region @@ -3070,84 +2922,22 @@ remote host with the following code in @file{~/.emacs} file. @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: +How to get a Visual Warning when working with @samp{root} privileges? +Host indication in the mode line? -@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)))) +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 variable +@code{tramp-theme-face-remapping-alist}. -(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: - -@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 - - -@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 (add-hook @@ -3156,7 +2946,6 @@ local host but if the remote host cannot understand the same (when (file-remote-p default-directory) (setq dired-actual-switches "-al")))) @end lisp -@end ifset @item @@ -3235,8 +3024,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,7 +3039,7 @@ 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 (global-set-key @@ -3320,70 +3109,32 @@ 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 @@ -3399,18 +3150,16 @@ directory to the cache: 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 (require 'bbdb) @@ -3430,23 +3179,17 @@ a method and user name where needed. Examples: @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 @@ -3455,13 +3198,12 @@ option @code{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: @@ -3502,7 +3244,6 @@ wrapper script: @example export EDITOR=/path/to/emacsclient.sh @end example -@end ifset @item @@ -3539,35 +3280,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") @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) @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 +3309,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 +3327,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. @@ -3656,7 +3384,6 @@ attributes cache in its process sentinel with this code: 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 +3414,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,7 +3423,7 @@ 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, @@ -3724,62 +3451,6 @@ call traces. Disable @code{tramp-read-passwd} and 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 - - @node GNU Free Documentation License @appendix GNU Free Documentation License @include doclicense.texi diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index 0cdf08daee..3101dc0de8 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.1 +@set trampver 2.3.1-pre @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 91cb6b54a8..06d2e559c3 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 |