diff options
Diffstat (limited to 'doc/misc')
| -rw-r--r-- | doc/misc/Makefile.in | 8 | ||||
| -rw-r--r-- | doc/misc/auth.texi | 54 | ||||
| -rw-r--r-- | doc/misc/calc.texi | 6 | ||||
| -rw-r--r-- | doc/misc/cl.texi | 6 | ||||
| -rw-r--r-- | doc/misc/dired-x.texi | 72 | ||||
| -rw-r--r-- | doc/misc/ede.texi | 6 | ||||
| -rw-r--r-- | doc/misc/ediff.texi | 2 | ||||
| -rw-r--r-- | doc/misc/efaq.texi | 91 | ||||
| -rw-r--r-- | doc/misc/emacs-mime.texi | 98 | ||||
| -rw-r--r-- | doc/misc/ert.texi | 22 | ||||
| -rw-r--r-- | doc/misc/eshell.texi | 2 | ||||
| -rw-r--r-- | doc/misc/eww.texi | 10 | ||||
| -rw-r--r-- | doc/misc/flymake.texi | 202 | ||||
| -rw-r--r-- | doc/misc/gnus-faq.texi | 18 | ||||
| -rw-r--r-- | doc/misc/gnus.texi | 73 | ||||
| -rw-r--r-- | doc/misc/message.texi | 100 | ||||
| -rw-r--r-- | doc/misc/mh-e.texi | 11 | ||||
| -rw-r--r-- | doc/misc/org.texi | 10 | ||||
| -rw-r--r-- | doc/misc/texinfo.tex | 56 | ||||
| -rw-r--r-- | doc/misc/tramp.texi | 904 | ||||
| -rw-r--r-- | doc/misc/trampver.texi | 24 | ||||
| -rw-r--r-- | doc/misc/url.texi | 21 |
22 files changed, 1229 insertions, 567 deletions
diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index d02f42bbeb9..a03efaf8bef 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -224,13 +224,13 @@ ${buildinfodir}/tramp.info tramp.html: ${srcdir}/trampver.texi .PHONY: mostlyclean clean distclean bootstrap-clean maintainer-clean mostlyclean: - rm -f *.aux *.log *.toc *.c[mp] *.c[mp]s *.fn *.fns \ - *.ky *.kys *.op *.ops *.p[gj] *.p[gj]s *.sc *.scs *.ss \ - *.t[gp] *.t[gp]s *.vr *.vrs + rm -f ./*.aux ./*.log ./*.toc ./*.c[mp] ./*.c[mp]s ./*.fn ./*.fns \ + ./*.ky ./*.kys ./*.op ./*.ops ./*.p[gj] ./*.p[gj]s ./*.sc ./*.scs ./*.ss \ + ./*.t[gp] ./*.t[gp]s ./*.vr ./*.vrs rm -f gnustmp* clean: mostlyclean - rm -f *.dvi *.html *.pdf *.ps + rm -f ./*.dvi ./*.html ./*.pdf ./*.ps distclean: clean rm -f Makefile diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi index e467fc135f3..495d9f53e15 100644 --- a/doc/misc/auth.texi +++ b/doc/misc/auth.texi @@ -86,7 +86,7 @@ password (known as the secret). Similarly, the auth-source library supports multiple storage backend, currently either the classic ``netrc'' backend, examples of which you -can see later in this document, the Secret Service API, and pass, the +can see later in this document, JSON files, the Secret Service API, and pass, the standard unix password manager. This is done with EIEIO-based backends and you can write your own if you want. @@ -169,6 +169,9 @@ get fancy, the default and simplest configuration is: ;;; use pass (@file{~/.password-store}) ;;; (@pxref{The Unix password store}) (setq auth-sources '(password-store)) +;;; JSON data in format [@{ "machine": "SERVER", +;;; "login": "USER", "password": "PASSWORD" @}...] +(setq auth-sources '("~/.authinfo.json.gpg")) @end lisp By adding multiple entries to @code{auth-sources} with a particular @@ -235,6 +238,16 @@ don't use a port entry, you match any Tramp method, as explained earlier. Since Tramp has about 88 connection methods, this may be necessary if you have an unusual (see earlier comment on those) setup. +The netrc format is directly translated into JSON, if you are into +that sort of thing. Just point to a JSON file with entries like this: + +@example +[ + @{ "machine": "yourmachine.com", "port": "http", + "login": "testuser", "password": "testpass" @} +] +@end example + @node Multiple GMail accounts with Gnus @chapter Multiple GMail accounts with Gnus @@ -335,25 +348,36 @@ Returns all the item labels of @var{collection} as a list. @defun secrets-create-item collection item password &rest attributes This function creates a new item in @var{collection} with label -@var{item} and password @var{password}. @var{attributes} are -key-value pairs set for the created item. The keys are keyword -symbols, starting with a colon. Example: +@var{item} and password @var{password}. The label @var{item} does not +have to be unique in @var{collection}. @var{attributes} are key-value +pairs set for the created item. The keys are keyword symbols, +starting with a colon. Example: @example -;;; The session "session", the label is "my item" -;;; and the secret (password) is "geheim" +;;; The session is "session", the label is "my item" +;;; and the secret (password) is "geheim". (secrets-create-item "session" "my item" "geheim" :method "sudo" :user "joe" :host "remote-host") @end example + +The key @code{:xdg:schema} determines the scope of the item to be +generated, i.e.@: for which applications the item is intended for. +This is just a string like "org.freedesktop.NetworkManager.Mobile" or +"org.gnome.OnlineAccounts", the other required keys are determined by +this. If no @code{:xdg:schema} is given, +"org.freedesktop.Secret.Generic" is used by default. @end defun @defun secrets-get-secret collection item -Return the secret of item labeled @var{item} in @var{collection}. -If there is no such item, return @code{nil}. +Return the secret of item labeled @var{item} in @var{collection}. If +there are several items labeled @var{item}, it is undefined which one +is returned. If there is no such item, return @code{nil}. @end defun @defun secrets-delete-item collection item -This function deletes item @var{item} in @var{collection}. +This function deletes item @var{item} in @var{collection}. If there +are several items labeled @var{item}, it is undefined which one is +deleted. @end defun The lookup attributes, which are specified during creation of a @@ -363,18 +387,20 @@ from a given secret item and they can be used for searching of items. @defun secrets-get-attribute collection item attribute Returns the value of key @var{attribute} of item labeled @var{item} in -@var{collection}. If there is no such item, or the item doesn't own -this key, the function returns @code{nil}. +@var{collection}. If there are several items labeled @var{item}, it +is undefined which one is returned. If there is no such item, or the +item doesn't own this key, the function returns @code{nil}. @end defun @defun secrets-get-attributes collection item Return the lookup attributes of item labeled @var{item} in -@var{collection}. If there is no such item, or the item has no -attributes, it returns @code{nil}. Example: +@var{collection}. If there are several items labeled @var{item}, it +is undefined which one is returned. If there is no such item, or the +item has no attributes, it returns @code{nil}. Example: @example (secrets-get-attributes "session" "my item") - @result{} ((:user . "joe") (:host ."remote-host")) + @result{} ((:user . "joe") (:host . "remote-host")) @end example @end defun diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi index 59125771ac5..1981988501c 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -32717,7 +32717,7 @@ create an intermediate set. (while (> n 0) (if (oddp n) (setq count (1+ count))) - (setq n (lsh n -1))) + (setq n (ash n -1))) count)) @end smallexample @@ -32761,7 +32761,7 @@ routines are especially fast when dividing by an integer less than (let ((count 0)) (while (> n 0) (setq count (+ count (logand n 1)) - n (lsh n -1))) + n (ash n -1))) count)) @end smallexample @@ -32774,7 +32774,7 @@ uses. The @code{idivmod} function does an integer division, returning both the quotient and the remainder at once. Again, note that while it -might seem that @samp{(logand n 511)} and @samp{(lsh n -9)} are +might seem that @samp{(logand n 511)} and @samp{(ash n -9)} are more efficient ways to split off the bottom nine bits of @code{n}, actually they are less efficient because each operation is really a division by 512 in disguise; @code{idivmod} allows us to do the diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 6ce0b72aa5f..32b5076c902 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -784,7 +784,7 @@ default. Some examples: (cl-deftype null () '(satisfies null)) ; predefined (cl-deftype list () '(or null cons)) ; predefined (cl-deftype unsigned-byte (&optional bits) - (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits))))) + (list 'integer 0 (if (eq bits '*) bits (1- (ash 1 bits))))) (unsigned-byte 8) @equiv{} (integer 0 255) (unsigned-byte) @equiv{} (integer 0 *) unsigned-byte @equiv{} (integer 0 *) @@ -1709,9 +1709,9 @@ but surrounds the loop with an implicit @code{nil} block. The body is executed with @var{var} bound to the integers from zero (inclusive) to @var{count} (exclusive), in turn. Then @c FIXME lispref does not state this part explicitly, could move this there. -the @code{result} form is evaluated with @var{var} bound to the total +the @var{result} form is evaluated with @var{var} bound to the total number of iterations that were done (i.e., @code{(max 0 @var{count})}) -to get the return value for the loop form. +to get the return value for the loop form. Use of @var{result} is deprecated. @end defmac @defmac cl-do-symbols (var [obarray [result]]) forms@dots{} diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi index c2630e6be66..b6a9d23f7dc 100644 --- a/doc/misc/dired-x.texi +++ b/doc/misc/dired-x.texi @@ -92,7 +92,6 @@ For @file{dired-x.el} as distributed with GNU Emacs @value{EMACSVER}. * Introduction:: * Installation:: * Omitting Files in Dired:: -* Local Variables:: * Shell Command Guessing:: * Virtual Dired:: * Advanced Mark Commands:: @@ -478,77 +477,6 @@ Loading @file{dired-x.el} will install Dired Omit by putting call @code{dired-extra-startup}, which in turn calls @code{dired-omit-startup} in your @code{dired-mode-hook}. -@node Local Variables -@chapter Local Variables for Dired Directories - -@cindex Local Variables for Dired Directories -@vindex dired-local-variables-file -@vindex dired-enable-local-variables -@noindent -This Dired-X feature is obsolete as of Emacs 24.1. The standard Emacs -directory local variables mechanism (@pxref{Directory -Variables,,,emacs,The GNU Emacs manual}) replaces it. For an example of -the new mechanisms, @pxref{Omitting Variables}. - -When Dired visits a directory, it looks for a file whose name is the -value of variable @code{dired-local-variables-file} (default: @file{.dired}). -If such a file is found, Dired will temporarily insert it into the Dired -buffer and run @code{hack-local-variables}. - -@noindent -For example, if the user puts - -@example -Local Variables: -dired-actual-switches: "-lat" -dired-omit-mode: t -End: -@end example - -@noindent -into a file called @file{.dired} in a directory then when that directory is -viewed it will be - -@enumerate -@item -sorted by date -@item -omitted automatically -@end enumerate - -@noindent -You can set @code{dired-local-variables-file} to @code{nil} to suppress this. -The value of @code{dired-enable-local-variables} controls if and how these -local variables are read. This variable exists so that it may override the -default value of @code{enable-local-variables}. - -@noindent -Please see the GNU Emacs Manual to learn more about local variables. -@xref{File Variables,Local Variables in Files,Local Variables in -Files,emacs,The GNU Emacs Manual}. - -@noindent -The following variables affect Dired Local Variables - -@table @code -@vindex dired-local-variables-file -@item dired-local-variables-file -Default: @code{".dired"} - -If non-@code{nil}, file name for local variables for Dired. If Dired finds a -file with that name in the current directory, it will temporarily insert it -into the Dired buffer and run @code{hack-local-variables}. - -@vindex dired-enable-local-variables -@item dired-enable-local-variables -Default: @code{t} - -Controls the use of local-variables lists in Dired. This variable -temporarily overrides the value of @code{enable-local-variables} when -the Dired Local Variables are hacked. It takes the same values as that -variable. A value of @code{nil} means to ignore any Dired Local Variables. -@end table - @node Shell Command Guessing @chapter Shell Command Guessing @cindex Guessing shell commands for files. diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi index 513461d0e0f..6d5c1b93a94 100644 --- a/doc/misc/ede.texi +++ b/doc/misc/ede.texi @@ -1824,7 +1824,7 @@ This class implements the @code{ede-cpp-root} project type. @table @code @item :include-path Type: @code{list} @* -Default Value: @code{(quote ("/include" "../include/"))} +Default Value: @code{("/include" "../include/")} The default locate function expands filenames within a project. If a header file (.h, .hh, etc.)@: name is expanded, and @@ -2262,14 +2262,14 @@ The variable GNUSTEP_INSTALLATION_DOMAIN is set at this value. @item :preamble Type: @code{(or null list)} @* -Default Value: @code{(quote ("GNUmakefile.preamble"))} +Default Value: @code{("GNUmakefile.preamble")} The auxiliary makefile for additional variables. Included just before the specific target files. @item :postamble Type: @code{(or null list)} @* -Default Value: @code{(quote ("GNUmakefile.postamble"))} +Default Value: @code{("GNUmakefile.postamble")} The auxiliary makefile for additional rules. Included just after the specific target files. diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi index 443aae3dbd5..c4ef1da3158 100644 --- a/doc/misc/ediff.texi +++ b/doc/misc/ediff.texi @@ -1147,7 +1147,7 @@ file (unlike what the @code{patch} utility would usually do). Instead, the source file retains its name and the result of applying the patch is placed in a temporary file that has the suffix @file{_patched} attached. Generally, this applies to files that are handled using black magic, such -as special file handlers (ange-ftp and some compression and encryption +as special file name handlers (ange-ftp and some compression and encryption packages also use this method). Regular files are treated by the @code{patch} utility in the usual manner, diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi index 4c0d17f9a7b..485776e1c73 100644 --- a/doc/misc/efaq.texi +++ b/doc/misc/efaq.texi @@ -1570,38 +1570,68 @@ exhibits all the colors Emacs knows about on the current display. Syntax highlighting is on by default since version 22.1. +@cindex direct color in terminals Emacs 26.1 and later support direct color mode in terminals. If Emacs finds Terminfo capabilities @samp{setb24} and @samp{setf24}, 24-bit direct color mode is used. The capability strings are expected to take one 24-bit pixel value as argument and transform the pixel to a string that can be used to send 24-bit colors to the terminal. -There aren't yet any standard terminal type definitions that would -support the capabilities, but Emacs can be invoked with a custom -definition as shown below. +Standard terminal definitions don't support these capabilities and +therefore custom definition is needed. @example -$ cat terminfo-24bit.src +$ cat terminfo-custom.src -# Use colon separators. -xterm-24bit|xterm with 24-bit direct color mode, +xterm-emacs|xterm with 24-bit direct color mode for Emacs, use=xterm-256color, - setb24=\E[48:2:%p1%@{65536@}%/%d:%p1%@{256@}%/%@{255@}%&%d:%p1%@{255@}%&%dm, - setf24=\E[38:2:%p1%@{65536@}%/%d:%p1%@{256@}%/%@{255@}%&%d:%p1%@{255@}%&%dm, -# Use semicolon separators. -xterm-24bits|xterm with 24-bit direct color mode, - use=xterm-256color, - setb24=\E[48;2;%p1%@{65536@}%/%d;%p1%@{256@}%/%@{255@}%&%d;%p1%@{255@}%&%dm, - setf24=\E[38;2;%p1%@{65536@}%/%d;%p1%@{256@}%/%@{255@}%&%d;%p1%@{255@}%&%dm, + setb24=\E[48\:2\:\:%p1%@{65536@}%/%d\:%p1%@{256@}%/%@{255@}%&\ + %d\:%p1%@{255@}%&%dm, + setf24=\E[38\:2\:\:%p1%@{65536@}%/%d\:%p1%@{256@}%/%@{255@}%&\ + %d\:%p1%@{255@}%&%dm, + +$ tic -x -o ~/.terminfo terminfo-custom.src + +$ TERM=xterm-emacs emacs -nw +@end example + +@cindex 24-bit direct color mode +Emacs 27.1 and later support Terminfo capability @samp{RGB} for +detecting 24-bit direct color mode. Multiple standard terminal +definitions support this capability. + +@example +$ TERM=xterm-direct infocmp | grep seta[bf] + + setab=\E[%?%p1%@{8@}%<%t4%p1%d%e48\:2\:\:%p1%@{65536@}%/\ + %d\:%p1%@{256@}%/%@{255@}%&%d\:%p1%@{255@}%&%d%;m, + setaf=\E[%?%p1%@{8@}%<%t3%p1%d%e38\:2\:\:%p1%@{65536@}%/\ + %d\:%p1%@{256@}%/%@{255@}%&%d\:%p1%@{255@}%&%d%;m, + +$ TERM=xterm-direct emacs -nw +@end example + +If your terminal is incompatible with XTerm, you may have to use +another @env{TERM} definition. Any terminal whose name includes +@samp{direct} should be a candidate. The @command{toe} command can be +used to find out which of these are installed on your system: -$ tic -x -o ~/.terminfo terminfo-24bit.src +@example +$ toe | grep '\-direct' -$ TERM=xterm-24bit emacs -nw +konsole-direct konsole with direct-color indexing +vte-direct vte with direct-color indexing +st-direct st with direct-color indexing +xterm-direct2 xterm with direct-color indexing (old) +xterm-direct xterm with direct-color indexing @end example -Currently there's no standard way to determine whether a terminal -supports direct color mode. If such standard arises later on, support -for @samp{setb24} and @samp{setf24} may be removed. +Terminals with @samp{RGB} capability treat pixels #000001 - #000007 as +indexed colors to maintain backward compatibility with applications +that are unaware of direct color mode. Therefore the seven darkest +blue shades may not be available. If this is a problem, you can +always use custom terminal definition with @samp{setb24} and +@samp{setf24}. @node Debugging a customization file @section How do I debug a @file{.emacs} file? @@ -1975,9 +2005,18 @@ or by invoking @code{server-start} from @file{.emacs}: (if (@var{some conditions are met}) (server-start)) @end lisp -When this is done, Emacs creates a Unix domain socket named -@file{server} in @file{/tmp/emacs@var{userid}}. See -@code{server-socket-dir}. +When this is done, Emacs by default creates a Unix domain socket named +@file{server} in a well-known directory, typically +@file{$XDG_RUNTIME_DIR/emacs} if Emacs is running under an X Window System +desktop and @file{$TMPDIR/emacs@var{userid}} otherwise. See the variable +@code{server-socket-dir}. Traditionally, Emacs used +@file{$TMPDIR/emacs@var{userid}} even when running under an X desktop; +if you prefer this traditional (and less-secure) behavior, you +can set the environment variable @env{EMACS_SOCKET_NAME} to +@samp{$TMPDIR/emacs@var{userid}/server} before invoking Emacs and +@samp{emacsclient}, although it will be your responsibility to create +the directory @samp{$TMPDIR/emacs@var{userid}} with appropriate +ownership and permissions. To get your news reader, mail reader, etc., to invoke @samp{emacsclient}, try setting the environment variable @code{EDITOR} @@ -2958,7 +2997,7 @@ Emacs compiled on a 64-bit machine can handle much larger buffers. @cindex Shell buffer, echoed commands and @samp{^M} in @cindex Echoed commands in @code{shell-mode} -Try typing @kbd{M-x shell-strip-ctrl-m @key{RET}} while in @code{shell-mode} to +Try typing @kbd{M-x comint-strip-ctrl-m @key{RET}} while in @code{shell-mode} to make them go away. If that doesn't work, you have several options: For @code{tcsh}, put this in your @file{.cshrc} (or @file{.tcshrc}) @@ -3011,7 +3050,7 @@ characters from the buffer by adding this to your @file{.emacs} init file: @smalllisp -(add-hook 'comint-output-filter-functions 'shell-strip-ctrl-m) +(add-hook 'comint-output-filter-functions #'comint-strip-ctrl-m) @end smalllisp On a related note: if your shell is echoing your input line in the shell @@ -3733,7 +3772,7 @@ to bind the key is in the kill ring, and can be yanked into your command are required. For example, @lisp -(global-set-key (quote [f1]) (quote help-for-help)) +(global-set-key [f1] 'help-for-help) @end lisp @noindent @@ -3744,7 +3783,7 @@ For example, in TeX mode, a local binding might be @lisp (add-hook 'tex-mode-hook (lambda () - (local-set-key (quote [f1]) (quote help-for-help)))) + (local-set-key [f1] 'help-for-help))) @end lisp @@ -4538,7 +4577,7 @@ these systems, you should configure @code{movemail} to use @code{flock}. @c isaacson@@seas.upenn.edu Ron Isaacson says: When you hit -@kbd{r} to reply in Rmail, by default it CCs all of the original +@kbd{r} to reply in Rmail, by default it Ccs all of the original recipients (everyone on the original @samp{To} and @samp{CC} lists). With a prefix argument (i.e., typing @kbd{C-u} before @kbd{r}), it replies only to the sender. However, going through the whole diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi index 9eb18f92ca1..123375ce7a4 100644 --- a/doc/misc/emacs-mime.texi +++ b/doc/misc/emacs-mime.texi @@ -404,12 +404,12 @@ variable will cause @samp{text/html} parts to be treated as attachments. @item mm-text-html-renderer @vindex mm-text-html-renderer -This selects the function used to render @acronym{HTML}. The predefined -renderers are selected by the symbols @code{shr}, @code{gnus-w3m}, -@code{w3m}@footnote{See @uref{http://emacs-w3m.namazu.org/} for more -information about emacs-w3m}, @code{links}, @code{lynx}, -@code{w3m-standalone} or @code{html2text}. If @code{nil} use an -external viewer. You can also specify a function, which will be +This selects the function used to render @acronym{HTML}. The +predefined renderers are selected by the symbols @code{shr}, +@code{gnus-w3m}, @code{w3m}@footnote{See +@uref{http://emacs-w3m.namazu.org/} for more information about +emacs-w3m}, @code{links}, @code{lynx}, @code{w3m-standalone} or +@code{html2text}. You can also specify a function, which will be called with a @acronym{MIME} handle as the argument. @item mm-html-inhibit-images @@ -708,7 +708,7 @@ RFC822 date when the part was read (@code{Content-Disposition}). @item recipients Who to encrypt/sign the part to. This field is used to override any -auto-detection based on the To/CC headers. +auto-detection based on the To/Cc headers. @item sender Identity used to sign the part. This field is used to override the @@ -1524,45 +1524,54 @@ many mailers don't support it. @xref{rfc2231}. @section time-date While not really a part of the @acronym{MIME} library, it is convenient to -document this library here. It deals with parsing @code{Date} headers +document time conversion functions often used when parsing @code{Date} headers and manipulating time. (Not by using tesseracts, though, I'm sorry to say.) -These functions convert between five formats: A date string, an Emacs -time structure, a decoded time list, a second number, and a day number. +These functions convert between five formats: A date string, a Lisp +timestamp, a decoded time list, a second number, and a day number. Here's a bunch of time/date/second/day examples: @example (parse-time-string "Sat Sep 12 12:21:54 1998 +0200") -@result{} (54 21 12 12 9 1998 6 nil 7200) +@result{} (54 21 12 12 9 1998 6 -1 7200) -(date-to-time "Sat Sep 12 12:21:54 1998 +0200") -@result{} (13818 19266) +(encode-time (date-to-time "Sat Sep 12 12:21:54 1998 +0200") + 1000000) +@result{} (905595714000000 . 1000000) -(parse-iso8601-time-string "1998-09-12T12:21:54+0200") -@result{} (13818 19266) +(encode-time (parse-iso8601-time-string "1998-09-12T12:21:54+0200") + 1000000) +@result{} (905595714000000 . 1000000) -(float-time '(13818 19266)) +(float-time '(905595714000000 . 1000000)) @result{} 905595714.0 -(seconds-to-time 905595714.0) -@result{} (13818 19266 0 0) +(encode-time 905595714.0 1000000) +@result{} (905595714000000 . 1000000) -(time-to-days '(13818 19266)) +(time-to-days '(905595714000000 . 1000000)) @result{} 729644 -(days-to-time 729644) -@result{} (961933 512) +(encode-time (days-to-time 729644) 1000000) +@result{} (63041241600000000 . 1000000) -(time-since '(13818 19266)) -@result{} (6797 9607 984839 247000) +(encode-time (time-since '(905595714000000 . 1000000)) + 1000000) +@result{} (631963244775642171 . 1000000000) -(time-less-p '(13818 19266) '(13818 19145)) +(time-less-p '(905595714000000 . 1000000) + '(905595593000000000 . 1000000000)) @result{} nil -(time-subtract '(13818 19266) '(13818 19145)) -@result{} (0 121) +(time-equal-p '(905595593000000000 . 1000000000) + '(905595593000000 . 1000000 )) +@result{} t + +(time-subtract '(905595714000000 . 1000000) + '(905595593000000000 . 1000000000)) +@result{} (121000000000 . 1000000000) (days-between "Sat Sep 12 12:21:54 1998 +0200" "Sat Sep 07 12:21:54 1998 +0200") @@ -1571,13 +1580,13 @@ Here's a bunch of time/date/second/day examples: (date-leap-year-p 2000) @result{} t -(time-to-day-in-year '(13818 19266)) +(time-to-day-in-year '(905595714000000 . 1000000)) @result{} 255 (time-to-number-of-days (time-since (date-to-time "Mon, 01 Jan 2001 02:22:26 GMT"))) -@result{} 4314.095589286675 +@result{} 6472.722661506652 @end example And finally, we have @code{safe-date-to-time}, which does the same as @@ -1592,22 +1601,24 @@ An RFC822 (or similar) date string. For instance: @code{"Sat Sep 12 12:21:54 1998 +0200"}. @item time -An internal Emacs time. For instance: @code{(13818 26466 0 0)}. +A Lisp timestamp. +For instance: @code{(905595714000000 . 1000000)}. @item seconds -A floating point representation of the internal Emacs time. For -instance: @code{905595714.0}. +An integer or floating point count of seconds. For instance: +@code{905595714.0}, @code{905595714}. @item days An integer number representing the number of days since 00000101. For instance: @code{729644}. @item decoded time -A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 t +A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 nil 7200)}. @end table -All the examples above represent the same moment. +All the examples above represent the same moment, except that +@var{days} represents the day containing the moment. These are the functions available: @@ -1618,8 +1629,9 @@ Take a date and return a time. @item float-time Take a time and return seconds. (This is a built-in function.) -@item seconds-to-time -Take seconds and return a time. +@item encode-time +Take seconds (and other ways to represent time, notably decoded time +lists), and return a time. @item time-to-days Take a time and return days. @@ -1641,6 +1653,10 @@ return a ``zero'' time. Take two times and say whether the first time is less (i.e., earlier) than the second time. (This is a built-in function.) +@item time-equal-p +Check whether two time values are equal. The time values need not be +in the same format. (This is a built-in function.) + @item time-since Take a time and return a time saying how long it was since that time. @@ -1845,11 +1861,23 @@ Interface functions: @table @code @item mailcap-parse-mailcaps @findex mailcap-parse-mailcaps +@vindex mailcap-prefer-mailcap-viewers Parse the @file{~/.mailcap} file. @item mailcap-mime-info Takes a @acronym{MIME} type as its argument and returns the matching viewer. +The @code{mailcap-prefer-mailcap-viewers} variable controls which +viewer is chosen. The default non-@code{nil} value means that +settings from @file{~/.mailcap} is preferred over system-wide or +Emacs-provided viewer settings. + +If @code{nil}, Emacs-provided viewer settings have precedence. Next, +the most specific viewer has precedence over less specific settings, +no matter if they're system-provided or private, so @samp{image/gif} +in @file{/etc/mailcap} will ``win'' over an @samp{image/*} setting in +@file{~/.mailcap}. + @end table diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi index d70eca81f9c..d2d86555e3c 100644 --- a/doc/misc/ert.texi +++ b/doc/misc/ert.texi @@ -273,9 +273,11 @@ moving point to it and typing @kbd{@key{RET}} jumps to its definition. @cindex backtrace of a failed test Pressing @kbd{r} re-runs the test near point on its own. Pressing @kbd{d} re-runs it with the debugger enabled. @kbd{.} jumps to the -definition of the test near point (@kbd{@key{RET}} has the same effect if -point is on the name of the test). On a failed test, @kbd{b} shows -the backtrace of the failure. +definition of the test near point (@kbd{@key{RET}} has the same effect +if point is on the name of the test). On a failed test, @kbd{b} shows +the backtrace of the failure. @xref{Debugging,, Backtraces, elisp, +GNU Emacs Lisp Reference Manual}, for more information about +backtraces. @kindex l@r{, in ert results buffer} @kbd{l} shows the list of @code{should} forms executed in the test. @@ -321,6 +323,20 @@ summary as shown below: emacs -batch -l ert -f ert-summarize-tests-batch-and-exit output.log @end example +@vindex ert-quiet +By default, ERT in batch mode is quite verbose, printing a line with +result after each test. This gives you progress information: how many +tests have been executed and how many there are. However, in some +cases this much output may be undesirable. In this case, set +@code{ert-quiet} variable to a non-nil value: + +@example +emacs -batch -l ert -l my-tests.el \ + --eval "(let ((ert-quiet t)) (ert-run-tests-batch-and-exit))" +@end example + +In quiet mode ERT prints only unexpected results and summary. + If ERT is not part of your Emacs distribution, you may need to use @code{-L /path/to/ert/} so that Emacs can find it. You may need additional @code{-L} flags to ensure that @code{my-tests.el} and all the diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index d2ea738f8db..dcb4aac2d89 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -330,7 +330,7 @@ List subprocesses of the Emacs process, if any, using the function @item kill @cmindex kill Kill processes. Takes a PID or a process object and an optional -signal specifier. +signal specifier which can either be a number or a signal name. @item listify @cmindex listify diff --git a/doc/misc/eww.texi b/doc/misc/eww.texi index 0afbd4cb852..b299ea1fb77 100644 --- a/doc/misc/eww.texi +++ b/doc/misc/eww.texi @@ -262,6 +262,16 @@ contrast. If that is still too low for you, you can customize the variables @code{shr-color-visible-distance-min} and @code{shr-color-visible-luminance-min} to get a better contrast. +@vindex shr-discard-aria-hidden +@cindex @code{aria-hidden}, HTML attribute + The HTML attribute @code{aria-hidden} is meant to tell screen +readers to ignore a tag's contents. You can customize the variable +@code{shr-discard-aria-hidden} to tell @code{shr} to ignore such tags. +This can be useful when using a screen reader on the output of +@code{shr} (e.g., on EWW buffer text). It can be useful even when not +using a screen reader, since web authors often put this attribute on +non-essential decorative elements. + @cindex Desktop Support @cindex Saving Sessions In addition to maintaining the history at run-time, EWW will also diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi index 2689b5d8cd9..894203ca5a1 100644 --- a/doc/misc/flymake.texi +++ b/doc/misc/flymake.texi @@ -1,8 +1,8 @@ \input texinfo @c -*-texinfo; coding: utf-8 -*- @comment %**start of header @setfilename ../../info/flymake.info -@set VERSION 0.3 -@set UPDATED April 2004 +@set VERSION 1.0 +@set UPDATED June 2018 @settitle GNU Flymake @value{VERSION} @include docstyle.texi @syncodeindex pg cp @@ -37,7 +37,7 @@ modify this GNU manual.'' @titlepage @title GNU Flymake @subtitle for version @value{VERSION}, @value{UPDATED} -@author Pavel Kobiakov(@email{pk_at_work@@yahoo.com}) and João Távora. +@author João Távora and Pavel Kobiakov(@email{pk_at_work@@yahoo.com}). @page @vskip 0pt plus 1filll @insertcopying @@ -84,6 +84,10 @@ Syntax check is done ``on-the-fly''. It is started whenever @code{flymake-start-on-flymake-mode} is nil; @item +the buffer is saved, unless @code{flymake-start-on-save-buffer} is +nil; + +@item a newline character is added to the buffer, unless @code{flymake-start-syntax-check-on-newline} is nil; @@ -95,9 +99,15 @@ some changes were made to the buffer more than @code{0.5} seconds ago Syntax check can also be started manually by typing the @kbd{M-x flymake-start @key{RET}} command. +If the check detected errors or warnings, the respective buffer +regions are highlighted. You can place point on those regions and use +@kbd{C-h .} (@code{display-local-help}) to see what the specific +problem was. Alternatively, hovering the mouse on those regions +should also display a tool-tip with the same information. + @code{flymake-goto-next-error} and @code{flymake-goto-prev-error} are commands that allow easy navigation to the next/previous erroneous -line, respectively. If might be a good idea to map them to @kbd{M-n} +regions, respectively. If might be a good idea to map them to @kbd{M-n} and @kbd{M-p} in @code{flymake-mode}, by adding to your init file: @lisp @@ -220,6 +230,10 @@ after a newline character is inserted into the buffer. A boolean flag indicating whether to start syntax check immediately after enabling @code{flymake-mode}. +@item flymake-start-on-save-buffer +A boolean flag indicating whether to start syntax check after saving +the buffer. + @item flymake-error A custom face for highlighting regions for which an error has been reported. @@ -275,54 +289,61 @@ The following sections discuss each approach in detail. @cindex customizing error types @cindex error types, customization -@vindex flymake-diagnostic-types-alist -The variable @code{flymake-diagnostic-types-alist} is looked up by -Flymake every time an annotation for a diagnostic is created in the -buffer. Specifically, this variable holds a table of correspondence -between symbols designating diagnostic types and an additional -sub-table of properties pertaining to each diagnostic type. +To customize the appearance of error types, set properties on the +symbols associated with each diagnostic type. The standard diagnostic +symbols are @code{:error}, @code{:warning} and @code{:note} (though +the backend may define more, @pxref{Backend functions}). -Both tables are laid out in association list (@pxref{Association -Lists,,, elisp, The Emacs Lisp Reference Manual}) format, and thus can -be conveniently accessed with the functions of the @code{assoc} -family. - -You can use any symbol-value association in the properties sub-table, -but some symbols have special meaning as to where and how Flymake -presents the diagnostic: +The following properties can be set: @itemize @item @cindex bitmap of diagnostic -@code{bitmap}, an image displayed in the fringe according to +@code{flymake-bitmap}, an image displayed in the fringe according to @code{flymake-fringe-indicator-position}. The value actually follows the syntax of @code{flymake-error-bitmap} (@pxref{Customizable variables}). It is overridden by any @code{before-string} overlay property. @item -@cindex severity of diagnostic -@code{severity} is a non-negative integer specifying the diagnostic's -severity. The higher the value, the more serious is the error. If -the overlay property @code{priority} is not specified, @code{severity} -is used to set it and help sort overlapping overlays. +@code{flymake-overlay-control}, an alist ((@var{OVPROP} . @var{VALUE}) +@var{...}) of further properties used to affect the appearance of +Flymake annotations. With the exception of @code{category} and +@code{evaporate}, these properties are applied directly to the created +overlay (@pxref{Overlay Properties,,, elisp, The Emacs Lisp Reference +Manual}). -@item -Every property pertaining to overlays (@pxref{Overlay Properties,,, -elisp, The Emacs Lisp Reference Manual}), except @code{category} and -@code{evaporate}. These properties are used to affect the appearance -of Flymake annotations. +As an example, here's how to make diagnostics of the type @code{:note} +stand out more prominently: -As an example, here's how to make errors (diagnostics of the type -@code{:error}) stand out even more prominently in the buffer, by -raising the characters using a @code{display} overlay property. +@example +(push '(face . highlight) (get :note 'flymake-overlay-control)) +@end example + +If you push another alist entry in front, it overrides the previous +one. So this effectively removes the face from @code{:note} +diagnostics: @example -(push '(display . (raise 1.2)) - (cdr (assoc :error flymake-diagnostic-types-alist))) +(push '(face . nil) (get :note 'flymake-overlay-control)) @end example +To restore the original look for @code{:note} types, empty or remove +its @code{flymake-overlay-control} property: + +@example +(put :note 'flymake-overlay-control '()) +@end example + +@item +@cindex severity of diagnostic +@code{flymake-severity} is a non-negative integer specifying the +diagnostic's severity. The higher the value, the more serious is the +error. If the overlay property @code{priority} is not specified in +@code{flymake-overlay-control}, @code{flymake-severity} is used to set +it and help sort overlapping overlays. + @item @vindex flymake-category @code{flymake-category} is a symbol whose property list is considered @@ -333,32 +354,29 @@ the default for missing values of any other properties. @vindex flymake-error @vindex flymake-warning @vindex flymake-note -Three default diagnostic types, @code{:error}, @code{:warning} and -@code{:note} are predefined in -@code{flymake-diagnostic-types-alist}. By default each lists a single +Three default diagnostic types are predefined: @code{:error}, +@code{:warning}, and @code{:note}. By default, each one of them has a @code{flymake-category} property whose value is, respectively, the -symbols @code{flymake-error}, @code{flymake-warning} and +category symbol @code{flymake-error}, @code{flymake-warning} and @code{flymake-note}. -These category symbols' plists is where the values of customizable -variables and faces such as @code{flymake-error-bitmap} are found. -Thus, if you change their plists, Flymake may stop honoring these -user customizations. +These category symbols' plist is where the values of customizable +variables and faces (such as @code{flymake-error-bitmap}) are found. +Thus, if you change their plists, Flymake may stop honoring these user +customizations. -The @code{flymake-category} special property is also especially useful -for backends which create diagnostics objects with non-default -types that differ from an existing type by only a few properties -(@pxref{Flymake utility functions}). +The @code{flymake-category} special property is especially useful for +backends which create diagnostics objects with non-default types that +differ from an existing type by only a few properties (@pxref{Flymake +utility functions}). As an example, consider configuring a new diagnostic type -@code{:low-priority-note} that behaves much like the @code{:note} -priority but without an overlay face. +@code{:low-priority-note} that behaves much like @code{:note}, but +without an overlay face. @example -(add-to-list - 'flymake-diagnostic-types-alist - `(:low-priority-note . ((face . nil) - (flymake-category . flymake-note)))) +(put :low-priority-note 'flymake-overlay-control '((face . nil))) +(put :low-priority-note 'flymake-category 'flymake-note) @end example @vindex flymake-diagnostics @@ -389,20 +407,17 @@ Internet search for the text of a @code{:warning} or @code{:error}. (eww-browse-url (concat "https://duckduckgo.com/?q=" - (replace-regexp-in-string " " - "+" - (flymake-diagnostic-text topmost-diag))) + (replace-regexp-in-string + " " "+" (flymake-diagnostic-text topmost-diag))) t))) (dolist (type '(:warning :error)) - (let ((a (assoc type flymake-diagnostic-types-alist))) - (setf (cdr a) - (append `((mouse-face . highlight) - (keymap . ,(let ((map (make-sparse-keymap))) - (define-key map [mouse-2] - 'my-search-for-message) - map))) - (cdr a))))) + (push '(mouse-face . highlight) (get type 'flymake-overlay-control)) + (push `(keymap . ,(let ((map (make-sparse-keymap))) + (define-key map [mouse-2] + 'my-search-for-message) + map)) + (get type 'flymake-overlay-control))) @end example @node Backend functions @@ -428,18 +443,35 @@ calling convention: one for calls made by Flymake into the backend via the backend function, the other in the reverse direction via a callback. To be usable, backends must adhere to both. -Backend functions must accept an arbitrary number of arguments: +The first argument passed to a backend function is always +@var{report-fn}, a callback function detailed below. Beyond it, +functions must be prepared to accept (and possibly ignore) an +arbitrary number of keyword-value pairs of the form +@w{@code{(@var{:key} @var{value} @var{:key2} @var{value2}...)}}. + +Currently, Flymake may pass the following keywords and values to the +backend function: @itemize -@item -the first argument is always @var{report-fn}, a callback function -detailed below; -@item -the remaining arguments are keyword-value pairs of the -form @w{@code{(@var{:key} @var{value} @var{:key2} @var{value2}...)}}. Currently, -Flymake provides no such arguments, but backend functions must be -prepared to accept (and possibly ignore) any number of them. +@item @code{:recent-changes} +The value is a list recent changes since the last time the backend +function was called for the buffer. If the list is empty, this +indicates that no changes have been recorded. If it is the first time +that this backend function is called for this activation of +@code{flymake-mode}, then this argument isn't provided at all +(i.e. it's not merely nil). + +Each element is in the form (@var{beg} @var{end} @var{text}) where +@var{beg} and @var{end} are buffer positions, and @var{text} is a +string containing the text contained between those positions (if any), +after the change was performed. + +@item @code{:changes-start} and @code{:changes-end} +The value is, repectively, the minimum and maximum buffer positions +touched by the recent changes. These are provided for convenience and +only if @code{:recent-changes} is also provided. + @end itemize Whenever Flymake or the user decide to re-check the buffer, backend @@ -495,6 +527,11 @@ details of the situation encountered, if any. @code{:force}, whose value should be a boolean suggesting that Flymake consider the report even if it was somehow unexpected. + +@item +@code{:region}, a cons (@var{beg} . @var{end}) of buffer positions +indicating that the report applies to that region and that previous +reports targeting other parts of the buffer remain valid. @end itemize @menu @@ -512,9 +549,9 @@ by calling the function @code{flymake-make-diagnostic}. @deffn Function flymake-make-diagnostic buffer beg end type text Make a Flymake diagnostic for @var{buffer}'s region from @var{beg} to -@var{end}. @var{type} is a key to -@code{flymake-diagnostic-types-alist} and @var{text} is a description -of the problem detected in this region. +@var{end}. @var{type} is a diagnostic symbol (@pxref{Flymake error +types}), and @var{text} is a description of the problem detected in +this region. @end deffn @cindex access diagnostic object @@ -715,14 +752,13 @@ Patterns for error/warning messages in the form @code{(regexp file-idx line-idx col-idx err-text-idx)}. @xref{Parsing the output}. @item flymake-proc-diagnostic-type-pred -A function to classify a diagnostic text as particular type of -error. Should be a function taking an error text and returning one of -the symbols indexing @code{flymake-diagnostic-types-alist}. If non-nil -is returned but there is no such symbol in that table, a warning is -assumed. If nil is returned, an error is assumed. Can also be a -regular expression that should match only warnings. This variable -replaces the old @code{flymake-warning-re} and -@code{flymake-warning-predicate}. +A function to classify a diagnostic text as particular type of error. +Should be a function taking an error text and returning a diagnostic +symbol (@pxref{Flymake error types}). If non-nil is returned but +there is no such symbol in that table, a warning is assumed. If nil +is returned, an error is assumed. Can also be a regular expression +that should match only warnings. This variable replaces the old +@code{flymake-warning-re} and @code{flymake-warning-predicate}. @item flymake-proc-compilation-prevents-syntax-check A flag indicating whether compilation and syntax check of the same diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi index 55010d4e430..e8ec5020df2 100644 --- a/doc/misc/gnus-faq.texi +++ b/doc/misc/gnus-faq.texi @@ -1161,13 +1161,13 @@ from using them): @example (setq nnmail-split-methods '(("duplicates" "^Gnus-Warning:.*duplicate") - ("XEmacs-NT" "^\\(To:\\|CC:\\).*localpart@@xemacs.invalid.*") - ("Gnus-Tut" "^\\(To:\\|CC:\\).*localpart@@socha.invalid.*") - ("tcsh" "^\\(To:\\|CC:\\).*localpart@@mx.gw.invalid.*") - ("BAfH" "^\\(To:\\|CC:\\).*localpart@@.*uni-muenchen.invalid.*") - ("Hamster-src" "^\\(CC:\\|To:\\).*hamster-sourcen@@yahoogroups.\\(de\\|com\\).*") + ("XEmacs-NT" "^\\(To:\\|Cc:\\).*localpart@@xemacs.invalid.*") + ("Gnus-Tut" "^\\(To:\\|Cc:\\).*localpart@@socha.invalid.*") + ("tcsh" "^\\(To:\\|Cc:\\).*localpart@@mx.gw.invalid.*") + ("BAfH" "^\\(To:\\|Cc:\\).*localpart@@.*uni-muenchen.invalid.*") + ("Hamster-src" "^\\(Cc:\\|To:\\).*hamster-sourcen@@yahoogroups.\\(de\\|com\\).*") ("Tagesschau" "^From: tagesschau <localpart@@www.tagesschau.invalid>$") - ("Replies" "^\\(CC:\\|To:\\).*localpart@@Frank-Schmitt.invalid.*") + ("Replies" "^\\(Cc:\\|To:\\).*localpart@@Frank-Schmitt.invalid.*") ("EK" "^From:.*\\(localpart@@privateprovider.invalid\\|localpart@@workplace.invalid\\).*") ("Spam" "^Content-Type:.*\\(ks_c_5601-1987\\|EUC-KR\\|big5\\|iso-2022-jp\\).*") ("Spam" "^Subject:.*\\(This really work\\|XINGA\\|ADV:\\|XXX\\|adult\\|sex\\).*") @@ -1177,10 +1177,10 @@ from using them): ("Spam" "^From:.*\\(verizon\.net\\|prontomail\.com\\|money\\|ConsumerDirect\\).*") ("Spam" "^Delivered-To: GMX delivery to spamtrap@@gmx.invalid$") ("Spam" "^Received: from link2buy.com") - ("Spam" "^CC: .*azzrael@@t-online.invalid") + ("Spam" "^Cc: .*azzrael@@t-online.invalid") ("Spam" "^X-Mailer-Version: 1.50 BETA") - ("Uni" "^\\(CC:\\|To:\\).*localpart@@uni-koblenz.invalid.*") - ("Inbox" "^\\(CC:\\|To:\\).*\\(my\ name\\|address@@one.invalid\\|address@@two.invalid\\)") + ("Uni" "^\\(Cc:\\|To:\\).*localpart@@uni-koblenz.invalid.*") + ("Inbox" "^\\(Cc:\\|To:\\).*\\(my\ name\\|address@@one.invalid\\|address@@two.invalid\\)") ("Spam" ""))) @end example @noindent diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index 0ccd52f9d4f..2862264312c 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -3102,6 +3102,21 @@ interest in relation to the sieve parameter. The Sieve language is described in RFC 3028. @xref{Top, Emacs Sieve, Top, sieve, Emacs Sieve}. +@item match-list +@cindex match-list +If this parameter is set to @code{t} and @code{nnmail-split-method} is +set to @code{gnus-group-split}, Gnus will match @code{to-address}, +@code{to-list}, @code{extra-aliases} and @code{split-regexp} against +the @code{list} split abbreviation. The split regexp is modified to +match either a @code{@@} or a dot @code{.} in mail addresses to +conform to RFC2919 @code{List-ID}. + +See @code{nnmail-split-abbrev-alist} for the regular expression +matching mailing-list headers. + +See @pxref{Group Mail Splitting} to automatically split on group +parameters. + @item (agent parameters) If the agent has been enabled, you can set any of its parameters to control the behavior of the agent in individual groups. See Agent @@ -5577,7 +5592,7 @@ command uses the process/prefix convention. Mail a wide reply to the author of the current article (@code{gnus-summary-wide-reply}). A @dfn{wide reply} is a reply that goes out to all people listed in the @code{To}, @code{From} (or -@code{Reply-to}) and @code{Cc} headers. If @code{Mail-Followup-To} is +@code{Reply-To}) and @code{Cc} headers. If @code{Mail-Followup-To} is present, that's used instead. @item S W @@ -5601,7 +5616,7 @@ message to the mailing list, and include the original message Mail a very wide reply to the author of the current article (@code{gnus-summary-wide-reply}). A @dfn{very wide reply} is a reply that goes out to all people listed in the @code{To}, @code{From} (or -@code{Reply-to}) and @code{Cc} headers in all the process/prefixed +@code{Reply-To}) and @code{Cc} headers in all the process/prefixed articles. This command uses the process/prefix convention. @item S V @@ -5643,8 +5658,7 @@ as an rfc822 @acronym{MIME} section; if the prefix is 3, decode message and forward as an rfc822 @acronym{MIME} section; if the prefix is 4, forward message directly inline; otherwise, the message is forwarded as no prefix given but use the flipped value of (@code{message-forward-as-mime}). By -default, the message is decoded and forwarded as an rfc822 @acronym{MIME} -section. +default, the forwarded message is inlined into the mail. @item S m @itemx m @@ -5836,6 +5850,15 @@ buffer (@code{gnus-summary-yank-message}). This command prompts for what message buffer you want to yank into, and understands the process/prefix convention (@pxref{Process/Prefix}). +@item S A +@kindex S A @r{(Summary)} +@findex gnus-summary-attach-article +Attach the current article into an already existing Message +composition buffer (@code{gnus-summary-attach-message}). If no such +buffer exists, a new one is created. This command prompts for what +message buffer you want to yank into, and understands the +process/prefix convention (@pxref{Process/Prefix}). + @end table @@ -6657,7 +6680,8 @@ Limit the summary buffer to the unseen articles @kindex / v @r{(Summary)} @findex gnus-summary-limit-to-score Limit the summary buffer to articles that have a score at or above some -score (@code{gnus-summary-limit-to-score}). +score (@code{gnus-summary-limit-to-score}). If given a prefix, below +some score. @item / p @kindex / p @r{(Summary)} @@ -9791,9 +9815,6 @@ this command passes the @acronym{HTML} content to the browser without eliminating these ``web bugs'' you should only use it for mails from trusted senders. -If you always want to display @acronym{HTML} parts in the browser, set -@code{mm-text-html-renderer} to @code{nil}. - This command creates temporary files to pass @acronym{HTML} contents including images if any to the browser, and deletes them when exiting the group (if you want). @@ -13209,6 +13230,11 @@ Also @pxref{Formatting Variables}. @subsection Server Commands @cindex server commands +The following keybinding are available in the server buffer. Be aware +that some of the commands will only work on servers that you've added +through this interface (with @kbd{a}), not with servers you've defined +in your init files. + @table @kbd @item v @@ -14294,6 +14320,12 @@ fetch all textual parts, while leaving the rest on the server. If non-@code{nil}, record all @acronym{IMAP} commands in the @samp{"*imap log*"} buffer. +@item nnimap-use-namespaces +If non-@code{nil}, omit the IMAP namespace prefix in nnimap group +names. If your IMAP mailboxes are called something like @samp{INBOX} +and @samp{INBOX.Lists.emacs}, but you'd like the nnimap group names to +be @samp{INBOX} and @samp{Lists.emacs}, you should enable this option. + @end table @@ -15469,6 +15501,9 @@ Matches the @samp{To}, @samp{Cc}, @samp{Apparently-To}, @samp{Resent-To} and @samp{Resent-Cc} fields. @item any Is the union of the @code{from} and @code{to} entries. +@item list +Matches the @samp{List-ID}, @samp{List-Post}, @samp{X-Mailing-List}, +@samp{X-BeenThere} and @samp{X-Loop} fields. @end table @vindex nnmail-split-fancy-syntax-table @@ -18478,7 +18513,7 @@ something along the lines of the following: (defun my-article-old-p () "Say whether an article is old." (< (time-to-days (date-to-time (mail-header-date gnus-headers))) - (- (time-to-days (current-time)) gnus-agent-expire-days))) + (- (time-to-days nil) gnus-agent-expire-days))) @end lisp with the predicate then defined as: @@ -19466,8 +19501,8 @@ score file and edit it. @item V w @kindex V w @r{(Summary)} -@findex gnus-score-find-favourite-words -List words used in scoring (@code{gnus-score-find-favourite-words}). +@findex gnus-score-find-favorite-words +List words used in scoring (@code{gnus-score-find-favorite-words}). @item V R @kindex V R @r{(Summary)} @@ -21433,6 +21468,18 @@ The prefix to remove from each file name returned by notmuch in order to get a group name (albeit with @samp{/} instead of @samp{.}). This is a regular expression. +@item nnir-notmuch-filter-group-names-function +A function used to transform the names of groups being searched in, +for use as a ``path:'' search keyword for notmuch. If nil, the +default, ``path:'' keywords are not used. Otherwise, this should be a +callable which accepts a single group name and returns a transformed +name as notmuch expects to see it. In many mail backends, for +instance, dots in group names must be converted to forward slashes: to +achieve this, set this option to +@example +(lambda (g) (replace-regexp-in-string "\\." "/" g)) +@end example + @end table @@ -25854,13 +25901,13 @@ Reset: (setq spam-stat (make-hash-table :test 'equal)) Learn spam: (spam-stat-process-spam-directory "~/Mail/mail/spam") Learn non-spam: (spam-stat-process-non-spam-directory "~/Mail/mail/misc") Save table: (spam-stat-save) -File size: (nth 7 (file-attributes spam-stat-file)) +File size: (file-attribute-size (file-attributes spam-stat-file)) Number of words: (hash-table-count spam-stat) Test spam: (spam-stat-test-directory "~/Mail/mail/spam") Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc") Reduce table size: (spam-stat-reduce-size) Save table: (spam-stat-save) -File size: (nth 7 (file-attributes spam-stat-file)) +File size: (file-attribute-size (file-attributes spam-stat-file)) Number of words: (hash-table-count spam-stat) Test spam: (spam-stat-test-directory "~/Mail/mail/spam") Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc") diff --git a/doc/misc/message.texi b/doc/misc/message.texi index 21a57590066..addad99bdbc 100644 --- a/doc/misc/message.texi +++ b/doc/misc/message.texi @@ -162,7 +162,7 @@ header should be. If it does not, it should just return @code{nil}, and the normal methods for determining the To header will be used. Each list element should be a cons, where the @sc{car} should be the -name of a header (e.g., @code{Cc}) and the @sc{cdr} should be the header +name of a header (e.g., @code{CC}) and the @sc{cdr} should be the header value (e.g., @samp{larsi@@ifi.uio.no}). All these headers will be inserted into the head of the outgoing mail. @@ -174,7 +174,7 @@ inserted into the head of the outgoing mail. The @code{message-wide-reply} pops up a message buffer that's a wide reply to the message in the current buffer. A @dfn{wide reply} is a reply that goes out to all people listed in the @code{To}, @code{From} -(or @code{Reply-to}) and @code{Cc} headers. +(or @code{Reply-To}) and @code{CC} headers. @vindex message-wide-reply-to-function Message uses the normal methods to determine where wide replies are to go, @@ -185,7 +185,7 @@ but you can change the behavior to suit your needs by fiddling with the @vindex message-dont-reply-to-names Addresses that match the @code{message-dont-reply-to-names} regular expression (or list of regular expressions or a predicate function) -will be removed from the @code{Cc} header. A value of @code{nil} means +will be removed from the @code{CC} header. A value of @code{nil} means to exclude only your email address. @vindex message-prune-recipient-rules @@ -199,7 +199,7 @@ to match addresses to be pruned. It's complicated to explain, but it's easy to use. For instance, if you get an email from @samp{foo@@example.org}, but -@samp{foo@@zot.example.org} is also in the @code{Cc} list, then your +@samp{foo@@zot.example.org} is also in the @code{CC} list, then your wide reply will go out to both these addresses, since they are unique. To avoid this, do something like the following: @@ -316,7 +316,7 @@ when forwarding a message. @item message-forward-included-headers @vindex message-forward-included-headers In non-@code{nil}, only headers that match this regexp will be kept -when forwarding a message. +when forwarding a message. This can also be a list of regexps. @item message-make-forward-subject-function @vindex message-make-forward-subject-function @@ -345,10 +345,10 @@ constructed. The default value is @code{nil}. @item message-forward-as-mime @vindex message-forward-as-mime -If this variable is @code{t} (the default), forwarded messages are -included as inline @acronym{MIME} RFC822 parts. If it's @code{nil}, forwarded -messages will just be copied inline to the new message, like previous, -non @acronym{MIME}-savvy versions of Gnus would do. +If this variable is @code{t}, forwarded messages are included as +inline @acronym{MIME} RFC822 parts. If it's @code{nil} (the default), +forwarded messages will just be copied inline to the new message, like +previous, non @acronym{MIME}-savvy versions of Gnus would do. @item message-forward-before-signature @vindex message-forward-before-signature @@ -487,10 +487,10 @@ MFT field. If there is one, it is left alone. (Except if it's empty; in that case, the field is removed and is not replaced with an automatically generated one. This lets you disable MFT generation on a per-message basis.) If there is none, then the list of recipient -addresses (in the To: and Cc: headers) is checked to see if one of them +addresses (in the To: and CC: headers) is checked to see if one of them is a list address you are subscribed to. If none of them is a list address, then no MFT is generated; otherwise, a MFT is added to the -other headers and set to the value of all addresses in To: and Cc: +other headers and set to the value of all addresses in To: and CC: @kindex C-c C-f C-a @findex message-generate-unsubscribed-mail-followup-to @@ -516,7 +516,7 @@ header, Gnus' action will depend on the value of the variable @table @code @item use - Always honor MFTs. The To: and Cc: headers in your followup will be + Always honor MFTs. The To: and CC: headers in your followup will be derived from the MFT header of the original post. This is the default. @item nil @@ -593,17 +593,17 @@ in the key binding is for Originator.) @item C-c C-f C-b @kindex C-c C-f C-b @findex message-goto-bcc -Go to the @code{Bcc} header (@code{message-goto-bcc}). +Go to the @code{BCC} header (@code{message-goto-bcc}). @item C-c C-f C-w @kindex C-c C-f C-w @findex message-goto-fcc -Go to the @code{Fcc} header (@code{message-goto-fcc}). +Go to the @code{FCC} header (@code{message-goto-fcc}). @item C-c C-f C-c @kindex C-c C-f C-c @findex message-goto-cc -Go to the @code{Cc} header (@code{message-goto-cc}). +Go to the @code{CC} header (@code{message-goto-cc}). @item C-c C-f C-s @kindex C-c C-f C-s @@ -662,7 +662,7 @@ fetches the contents of the @samp{To:} header in the current mail buffer, and appends the current @code{user-mail-address}. If the optional argument @code{include-cc} is non-@code{nil}, the -addresses in the @samp{Cc:} header are also put into the +addresses in the @samp{CC:} header are also put into the @samp{Mail-Followup-To:} header. @end table @@ -696,7 +696,7 @@ or @code{Newsgroups} header of the article you're replying to @kindex C-c C-l @findex message-to-list-only Send a message to the list only. Remove all addresses but the list -address from @code{To:} and @code{Cc:} headers. +address from @code{To:} and @code{CC:} headers. @item C-c M-n @kindex C-c M-n @@ -746,13 +746,13 @@ by the @code{message-cross-post-note-function} variable. @item C-c C-f t @kindex C-c C-f t @findex message-reduce-to-to-cc -Replace contents of @samp{To} header with contents of @samp{Cc} -header (or the @samp{Bcc} header, if there is no @samp{Cc} header). +Replace contents of @samp{To} header with contents of @samp{CC} +header (or the @samp{BCC} header, if there is no @samp{CC} header). @item C-c C-f w @kindex C-c C-f w @findex message-insert-wide-reply -Insert @samp{To} and @samp{Cc} headers as if you were doing a wide +Insert @samp{To} and @samp{CC} headers as if you were doing a wide reply even if the message was not made for a wide reply first. @item C-c C-f a @@ -902,7 +902,7 @@ found in RFC 3490. Message is a @acronym{IDNA}-compliant posting agent. The user generally doesn't have to do anything to make the @acronym{IDNA} happen---Message will encode non-@acronym{ASCII} domain names in @code{From}, -@code{To}, and @code{Cc} headers automatically. +@code{To}, and @code{CC} headers automatically. Until @acronym{IDNA} becomes more well known, Message queries you whether @acronym{IDNA} encoding of the domain name really should @@ -1011,7 +1011,7 @@ and/or encrypted messages as explained in the following. * Passphrase caching:: How to cache passphrases * PGP Compatibility:: Compatibility with older implementations * Encrypt-to-self:: Reading your own encrypted messages -* Bcc Warning:: Do not use encryption with Bcc headers +* BCC Warning:: Do not use encryption with BCC headers @end menu @node Signing and encryption @@ -1300,7 +1300,7 @@ information about the problem.) @subsection Encrypt-to-self By default, messages are encrypted to all recipients (@code{To}, -@code{Cc}, @code{Bcc} headers). Thus, you will not be able to decrypt +@code{CC}, @code{BCC} headers). Thus, you will not be able to decrypt your own messages. To make sure that messages are also encrypted to your own key(s), several alternative solutions exist: @enumerate @@ -1318,17 +1318,17 @@ OpenPGP) or @code{mml-secure-smime-encrypt-to-self} (for @acronym{S/MIME} with EasyPG). @end enumerate -@node Bcc Warning -@subsection Bcc Warning +@node BCC Warning +@subsection BCC Warning -The @code{Bcc} header is meant to hide recipients of messages. +The @code{BCC} header is meant to hide recipients of messages. However, when encrypted messages are used, the e-mail addresses of all -@code{Bcc}-headers are given away to all recipients without +@code{BCC}-headers are given away to all recipients without warning, which is a bug. @vindex mml-secure-safe-bcc-list -But now Message got to warn if @code{Bcc} recipients are found in an +But now Message got to warn if @code{BCC} recipients are found in an encrypted message when you are just about to send it. If you are sure -those @code{Bcc} addresses are safe to expose, set the +those @code{BCC} addresses are safe to expose, set the @code{mml-secure-safe-bcc-list} variable, that is a list of e-mail addresses. See @uref{https://debbugs.gnu.org/cgi/bugreport.cgi?bug=18718}. @@ -1468,20 +1468,24 @@ alias ding "ding@@ifi.uio.no (ding mailing list)" @end example After adding lines like this to your @file{~/.mailrc} file, you should -be able to just write @samp{lmi} in the @code{To} or @code{Cc} (and so +be able to just write @samp{lmi} in the @code{To} or @code{CC} (and so on) headers and press @kbd{SPC} to expand the alias. No expansion will be performed upon sending of the message---all expansions have to be done explicitly. If you're using @code{ecomplete}, all addresses from @code{To} and -@code{Cc} headers will automatically be put into the +@code{CC} headers will automatically be put into the @file{~/.ecompleterc} file. When you enter text in the @code{To} and -@code{Cc} headers, @code{ecomplete} will check out the values stored +@code{CC} headers, @code{ecomplete} will check out the values stored there and ``electrically'' say what completions are possible. To choose one of these completions, use the @kbd{M-n} command to move -down to the list. Use @kbd{M-n} and @kbd{M-p} to move down and up the -list, and @kbd{RET} to choose a completion. +down to the list. Use @kbd{@key{DOWN}} or @kbd{M-n} and +@kbd{@key{UP}} or @kbd{M-p} to move down and up the list, and +@kbd{@key{RET}} to choose a completion. + +The @code{ecomplete-sort-predicate} variable controls how +@code{ecomplete} matches are sorted. @node Spelling @section Spelling @@ -1677,7 +1681,7 @@ trailing old subject. In this case, @item message-alternative-emails @vindex message-alternative-emails Regexp or predicate function matching alternative email addresses. -The first address in the To, Cc or From headers of the original +The first address in the To, CC or From headers of the original article matching this variable is used as the From field of outgoing messages, replacing the default From value. @@ -1697,7 +1701,7 @@ off @code{message-setup-hook}. @item message-allow-no-recipients @vindex message-allow-no-recipients Specifies what to do when there are no recipients other than -@code{Gcc} or @code{Fcc}. If it is @code{always}, the posting is +@code{Gcc} or @code{FCC}. If it is @code{always}, the posting is allowed. If it is @code{never}, the posting is not allowed. If it is @code{ask} (the default), you are prompted. @@ -1709,7 +1713,7 @@ hidden when composing a message. @lisp (setq message-hidden-headers - '(not "From" "Subject" "To" "Cc" "Newsgroups")) + '(not "From" "Subject" "To" "CC" "Newsgroups")) @end lisp Headers are hidden using narrowing, you can use @kbd{M-x widen} to @@ -1718,9 +1722,9 @@ expose them in the buffer. @item message-header-synonyms @vindex message-header-synonyms A list of lists of header synonyms. E.g., if this list contains a -member list with elements @code{Cc} and @code{To}, then +member list with elements @code{CC} and @code{To}, then @code{message-carefully-insert-headers} will not insert a @code{To} -header when the message is already @code{Cc}ed to the recipient. +header when the message is already @code{CC}ed to the recipient. @end table @@ -1738,7 +1742,7 @@ header when the message is already @code{Cc}ed to the recipient. @item message-ignored-mail-headers @vindex message-ignored-mail-headers Regexp of headers to be removed before mailing. The default is@* -@samp{^[GF]cc:\\|^Resent-Fcc:\\|^Xref:\\|^X-Draft-From:\\|@* +@samp{^[GF]cc:\\|^Resent-FCC:\\|^Xref:\\|^X-Draft-From:\\|@* ^X-Gnus-Agent-Meta-Information:}. @item message-default-mail-headers @@ -2052,7 +2056,7 @@ Check whether the @code{Newsgroups} header exists and is not empty. @item quoting-style Check whether text follows last quoted portion. @item repeated-newsgroups -Check whether the @code{Newsgroups} and @code{Followup-to} headers +Check whether the @code{Newsgroups} and @code{Followup-To} headers contains repeated group names. @item reply-to Check whether the @code{Reply-To} header looks ok. @@ -2065,7 +2069,7 @@ Check for the existence of version and sendsys commands. @item shoot Check whether the domain part of the @code{Message-ID} header looks ok. @item shorten-followup-to -Check whether to add a @code{Followup-to} header to shorten the number +Check whether to add a @code{Followup-To} header to shorten the number of groups to post to. @item signature Check the length of the signature. @@ -2076,7 +2080,7 @@ Check whether the @code{Subject} header exists and is not empty. @item subject-cmsg Check the subject for commands. @item valid-newsgroups -Check whether the @code{Newsgroups} and @code{Followup-to} headers +Check whether the @code{Newsgroups} and @code{Followup-To} headers are valid syntactically. @end table @@ -2087,7 +2091,7 @@ for which the check is disabled by default if @item message-ignored-news-headers @vindex message-ignored-news-headers Regexp of headers to be removed before posting. The default is@* -@samp{^NNTP-Posting-Host:\\|^Xref:\\|^[BGF]cc:\\|^Resent-Fcc:\\|@* +@samp{^NNTP-Posting-Host:\\|^Xref:\\|^[BGF]cc:\\|^Resent-FCC:\\|@* ^X-Draft-From:\\|^X-Gnus-Agent-Meta-Information:}. @item message-default-news-headers @@ -2467,7 +2471,7 @@ an article\\nthat has been posted to %s as well.\\n\\n"}. @item message-fcc-externalize-attachments @vindex message-fcc-externalize-attachments -If @code{nil}, attach files as normal parts in Fcc copies; if it is +If @code{nil}, attach files as normal parts in FCC copies; if it is non-@code{nil}, attach local files as external parts. @item message-interactive @@ -2622,13 +2626,13 @@ consulted, in turn: A @dfn{wide reply} is a mail response that includes @emph{all} entities mentioned in the message you are responding to. All mailboxes from the following headers will be concatenated to form the outgoing -@code{To}/@code{Cc} headers: +@code{To}/@code{CC} headers: @table @code @item From (unless there's a @code{Reply-To}, in which case that is used instead). -@item Cc +@item CC @item To @end table @@ -2652,7 +2656,7 @@ sent: @end table If a @code{Mail-Copies-To} header is present, it will be used as the -basis of the new @code{Cc} header, except if this header is +basis of the new @code{CC} header, except if this header is @samp{never}. @end table diff --git a/doc/misc/mh-e.texi b/doc/misc/mh-e.texi index 898b3418f8d..99070950026 100644 --- a/doc/misc/mh-e.texi +++ b/doc/misc/mh-e.texi @@ -847,9 +847,9 @@ sending the original message, like this: To: cc: Subject: Re: Test -In-reply-to: <31054.1142621351@@stop.mail-abuse.org> +In-Reply-To: <31054.1142621351@@stop.mail-abuse.org> References: <31054.1142621351@@stop.mail-abuse.org> -Comments: In-reply-to Bill Wohler <wohler@@stop.mail-abuse.org> +Comments: In-Reply-To Bill Wohler <wohler@@stop.mail-abuse.org> message dated "Fri, 17 Mar 2006 10:49:11 -0800." X-Mailer: MH-E 8.1; nmh 1.1; GNU Emacs 23.1 -------- @@ -2589,13 +2589,6 @@ centers the output and wraps long lines more than most. It does not always handle special characters like @samp{®} or @samp{–}. It does not download images. @c ------------------------- -@item @samp{nil} -This choice obviously requires an external browser. With this setting, -HTML messages have a button for the body part which you can view with -@kbd{K v} (@code{mh-folder-toggle-mime-part}). Rendering of special -characters and handling of remote images depends on your choice of -browser. -@c ------------------------- @item @samp{shr} @cindex @samp{shr} This choice does not require an external program, but it does require diff --git a/doc/misc/org.texi b/doc/misc/org.texi index 2be2707d95e..7862713f47a 100644 --- a/doc/misc/org.texi +++ b/doc/misc/org.texi @@ -891,9 +891,7 @@ org}. been visited, i.e., where no Org built-in function have been loaded. Otherwise autoload Org functions will mess up the installation. -Then, to make sure your Org configuration is taken into account, initialize -the package system with @code{(package-initialize)} in your Emacs init file -before setting any Org option. If you want to use Org's package repository, +If you want to use Org's package repository, check out the @uref{https://orgmode.org/elpa.html, Org ELPA page}. @subsubheading Downloading Org as an archive @@ -18168,7 +18166,7 @@ Suggested Org crypt settings in Emacs init file: @lisp (require 'org-crypt) (org-crypt-use-before-save-magic) -(setq org-tags-exclude-from-inheritance (quote ("crypt"))) +(setq org-tags-exclude-from-inheritance '("crypt")) (setq org-crypt-key nil) ;; GPG key to use for encryption @@ -19707,8 +19705,8 @@ mentioned in the manual. For a complete list, use @kbd{M-x org-customize @c Local variables: @c fill-column: 77 @c indent-tabs-mode: nil -@c paragraph-start: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$" -@c paragraph-separate: "\\|^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$" +@c paragraph-start: "^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|\f\\|[ ]*$" +@c paragraph-separate: "^@[a-zA-Z]*[ \n]\\|^@x?org\\(key\\|cmd\\)\\|[ \f]*$" @c End: diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex index f2be62ce47b..5840aff4d7c 100644 --- a/doc/misc/texinfo.tex +++ b/doc/misc/texinfo.tex @@ -3,10 +3,12 @@ % Load plain if necessary, i.e., if running under initex. \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi % -\def\texinfoversion{2017-12-26.21} +\def\texinfoversion{2018-09-21.20} % -% Copyright 1985-1986, 1988, 1990-2017, 2019 Free Software Foundation, -% Inc. +% Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995, +% 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, +% 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018 +% Free Software Foundation, Inc. % % This texinfo.tex file is free software: you can redistribute it and/or % modify it under the terms of the GNU General Public License as @@ -1526,6 +1528,9 @@ output) for that.)} \startlink attr{/Border [0 0 0]}% user{/Subtype /Link /A << /S /URI /URI (#1) >>}% \endgroup} + % \pdfgettoks - Surround page numbers in #1 with @pdflink. #1 may + % be a simple number, or a list of numbers in the case of an index + % entry. \def\pdfgettoks#1.{\setbox\boxA=\hbox{\toksA={#1.}\toksB={}\maketoks}} \def\addtokens#1#2{\edef\addtoks{\noexpand#1={\the#1#2}}\addtoks} \def\adn#1{\addtokens{\toksC}{#1}\global\countA=1\let\next=\maketoks} @@ -2233,6 +2238,20 @@ end \font\smallersy=cmsy8 \def\smallerecsize{0800} +% Fonts for math mode superscripts (7pt). +\def\sevennominalsize{7pt} +\setfont\sevenrm\rmshape{7}{1000}{OT1} +\setfont\seventt\ttshape{10}{700}{OT1TT} +\setfont\sevenbf\bfshape{10}{700}{OT1} +\setfont\sevenit\itshape{7}{1000}{OT1IT} +\setfont\sevensl\slshape{10}{700}{OT1} +\setfont\sevensf\sfshape{10}{700}{OT1} +\setfont\sevensc\scshape{10}{700}{OT1} +\setfont\seventtsl\ttslshape{10}{700}{OT1TT} +\font\seveni=cmmi7 +\font\sevensy=cmsy7 +\def\sevenecsize{0700} + % Fonts for title page (20.4pt): \def\titlenominalsize{20pt} \setfont\titlerm\rmbshape{12}{\magstep3}{OT1} @@ -2367,6 +2386,20 @@ end \font\smallersy=cmsy8 \def\smallerecsize{0800} +% Fonts for math mode superscripts (7pt). +\def\sevennominalsize{7pt} +\setfont\sevenrm\rmshape{7}{1000}{OT1} +\setfont\seventt\ttshape{10}{700}{OT1TT} +\setfont\sevenbf\bfshape{10}{700}{OT1} +\setfont\sevenit\itshape{7}{1000}{OT1IT} +\setfont\sevensl\slshape{10}{700}{OT1} +\setfont\sevensf\sfshape{10}{700}{OT1} +\setfont\sevensc\scshape{10}{700}{OT1} +\setfont\seventtsl\ttslshape{10}{700}{OT1TT} +\font\seveni=cmmi7 +\font\sevensy=cmsy7 +\def\sevenecsize{0700} + % Fonts for title page (20.4pt): \def\titlenominalsize{20pt} \setfont\titlerm\rmbshape{12}{\magstep3}{OT1} @@ -2501,13 +2534,20 @@ end % In order for the font changes to affect most math symbols and letters, -% we have to define the \textfont of the standard families. We don't -% bother to reset \scriptfont and \scriptscriptfont; awaiting user need. +% we have to define the \textfont of the standard families. +% We don't bother to reset \scriptscriptfont; awaiting user need. % \def\resetmathfonts{% \textfont0=\rmfont \textfont1=\ifont \textfont2=\syfont \textfont\itfam=\itfont \textfont\slfam=\slfont \textfont\bffam=\bffont \textfont\ttfam=\ttfont \textfont\sffam=\sffont + % + % Fonts for superscript. Note that the 7pt fonts are used regardless + % of the current font size. + \scriptfont0=\sevenrm \scriptfont1=\seveni \scriptfont2=\sevensy + \scriptfont\itfam=\sevenit \scriptfont\slfam=\sevensl + \scriptfont\bffam=\sevenbf \scriptfont\ttfam=\seventt + \scriptfont\sffam=\sevensf } % @@ -2517,6 +2557,9 @@ end % to also set the current \fam for math mode. Our \STYLE (e.g., \rm) % commands hardwire \STYLEfont to set the current font. % +% The fonts used for \ifont are for "math italics" (\itfont is for italics +% in regular text). \syfont is also used in math mode only. +% % Each font-changing command also sets the names \lsize (one size lower) % and \lllsize (three sizes lower). These relative commands are used % in, e.g., the LaTeX logo and acronyms. @@ -7961,6 +8004,7 @@ end \gdef\boldbrax{\let(=\opnr\let)=\clnr\let[=\lbrb\let]=\rbrb} \gdef\magicamp{\let&=\amprm} } +\let\ampchar\& \newcount\parencount @@ -11675,7 +11719,7 @@ directory should work if nowhere else does.} @markupsetuprqdefault @c Local variables: -@c eval: (add-hook 'write-file-hooks 'time-stamp) +@c eval: (add-hook 'before-save-hook 'time-stamp) @c page-delimiter: "^\\\\message\\|emacs-page" @c time-stamp-start: "def\\\\texinfoversion{" @c time-stamp-format: "%:y-%02m-%02d.%02H" diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index bfb6d748f24..7587059f393 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -12,16 +12,6 @@ @c This is *so* much nicer :) @footnotestyle end -@c Macro for formatting a file name according to the respective -@c syntax. Macro arguments should not have any leading or trailing -@c whitespace. Not very elegant, but I don't know it better. - -@macro trampfn {method, userhost, localname} -@value{prefix}@c -\method\@value{postfixhop}@c -\userhost\@value{postfix}\localname\ -@end macro - @copying Copyright @copyright{} 1999--2019 Free Software Foundation, Inc. @@ -83,9 +73,9 @@ Savannah Project Page}. @end ifhtml There is a mailing list for @value{tramp}, available at -@email{tramp-devel@@gnu.org}, and archived at -@uref{https://lists.gnu.org/r/tramp-devel/, the -@value{tramp} Mail Archive}. +@email{@value{tramp-bug-report-address}}, and archived at +@uref{https://lists.gnu.org/r/tramp-devel/, the @value{tramp} Mail +Archive}. @page @insertcopying @@ -96,7 +86,6 @@ There is a mailing list for @value{tramp}, available at For the end user: * Obtaining @value{tramp}:: How to obtain @value{tramp}. -* History:: History of @value{tramp}. @ifset installchapter * Installation:: Installing @value{tramp} with your Emacs. @end ifset @@ -122,8 +111,11 @@ For the developer: --- The Detailed Node Listing --- @c @ifset installchapter + Installing @value{tramp} with your Emacs +* System Requirements:: Prerequisites for :@value{tramp} installation. +* Basic Installation:: Installation steps.: * Installation parameters:: Parameters in order to control installation. * Testing:: A test suite for @value{tramp}. * Load paths:: How to plug-in @value{tramp} into your environment. @@ -162,6 +154,7 @@ Using @value{tramp} * Ad-hoc multi-hops:: Declaring multiple hops in the file name. * Remote processes:: Integration with other Emacs packages. * Cleanup remote connections:: Cleanup remote connections. +* Archive file names:: Access to files in file archives. How file names, directories and localnames are mangled and managed @@ -385,31 +378,6 @@ $ autoconf @end example -@node History -@chapter History of @value{tramp} -@cindex history -@cindex development history - -@value{tramp} development started at the end of November 1998 as -@file{rssh.el}. It provided only one method of access. It used -@command{ssh} for login and @command{scp} to transfer file contents. -The name was changed to @file{rcp.el} before it got its present name -@value{tramp}. New methods of remote access were added, so was support -for version control. - -April 2000 was the first time when multi-hop methods were added. In -July 2002, @value{tramp} unified file names with Ange FTP@. In July -2004, proxy hosts replaced multi-hop methods. Running commands on -remote hosts was introduced in December 2005. Support for gateways -since April 2007 (and removed in December 2016). GVFS integration -started in February 2009. Remote commands on MS Windows hosts since -September 2011. Ad-hoc multi-hop methods (with a changed syntax) -re-enabled in November 2011. In November 2012, added Juergen -Hoetzel's @file{tramp-adb.el}. - -XEmacs support was stopped in January 2016. Since March 2017, -@value{tramp} syntax mandates a method. - @c Installation chapter is necessary only in case of standalone @c installation. Text taken from trampinst.texi. @ifset installchapter @@ -463,13 +431,13 @@ this case it is written as @code{host#port}. @anchor{Quick Start Guide: @option{ssh} and @option{plink} methods} @section Using @option{ssh} and @option{plink} -@cindex method ssh -@cindex ssh method -@cindex method plink -@cindex plink method +@cindex method @option{ssh} +@cindex @option{ssh} method +@cindex method @option{plink} +@cindex @option{plink} method If your local host runs an SSH client, and the remote host runs an SSH -server, the most simple remote file name is +server, the simplest remote file name is @file{@trampfn{ssh,user@@host,/path/to/file}}. The remote file name @file{@trampfn{ssh,,}} opens a remote connection to yourself on the local host, and is taken often for testing @value{tramp}. @@ -482,12 +450,12 @@ an @command{ssh} server: @anchor{Quick Start Guide: @option{su}, @option{sudo} and @option{sg} methods} @section Using @option{su}, @option{sudo} and @option{sg} -@cindex method su -@cindex su method -@cindex method sudo -@cindex sudo method -@cindex method sg -@cindex sg method +@cindex method @option{su} +@cindex @option{su} method +@cindex method @option{sudo} +@cindex @option{sudo} method +@cindex method @option{sg} +@cindex @option{sg} method Sometimes, it is necessary to work on your local host under different permissions. For this, you could use the @option{su} or @option{sudo} @@ -500,12 +468,25 @@ The method @option{sg} stands for ``switch group''; the changed group must be used here as user name. The default host name is the same. +@anchor{Quick Start Guide: @option{sudoedit} method} +@section Using @command{sudoedit} +@cindex method @option{sudoedit} +@cindex @option{sudoedit} method + +The @option{sudoedit} method is similar to the @option{sudo} method. +However, it is a different implementation: it does not keep an open +session running in the background. This is for security reasons; on +the backside this method is less performant than the @option{sudo} +method, it is restricted to the @samp{localhost} only, and it does not +support external processes. + + @anchor{Quick Start Guide: @option{smb} method} @section Using @command{smbclient} -@cindex method smb -@cindex smb method -@cindex ms windows (with smb method) -@cindex smbclient +@cindex method @option{smb} +@cindex @option{smb} method +@cindex ms windows (with @option{smb} method) +@cindex @command{smbclient} In order to access a remote MS Windows host or Samba server, the @command{smbclient} client is used. The remote file name syntax is @@ -518,39 +499,48 @@ of the local file name is the share exported by the remote host, @section Using GVFS-based methods @cindex methods, gvfs @cindex gvfs based methods -@cindex method sftp -@cindex sftp method -@cindex method afp -@cindex afp method -@cindex method dav -@cindex method davs -@cindex dav method -@cindex davs method - -On systems, which have installed the virtual file system for the Gnome -Desktop (GVFS), its offered methods could be used by @value{tramp}. -Examples are @file{@trampfn{sftp,user@@host,/path/to/file}}, +@cindex method @option{sftp} +@cindex @option{sftp} method +@cindex method @option{afp} +@cindex @option{afp} method +@cindex method @option{dav} +@cindex method @option{davs} +@cindex @option{dav} method +@cindex @option{davs} method + +On systems, which have installed the virtual file system for the +@acronym{GNOME} Desktop (GVFS), its offered methods could be used by +@value{tramp}. Examples are +@file{@trampfn{sftp,user@@host,/path/to/file}}, @file{@trampfn{afp,user@@host,/path/to/file}} (accessing Apple's AFP file system), @file{@trampfn{dav,user@@host,/path/to/file}} and @file{@trampfn{davs,user@@host,/path/to/file}} (for WebDAV shares). -@anchor{Quick Start Guide: Google Drive} -@section Using Google Drive -@cindex method gdrive -@cindex gdrive method +@anchor{Quick Start Guide: GNOME Online Accounts based methods} +@section Using @acronym{GNOME} Online Accounts based methods +@cindex @acronym{GNOME} Online Accounts +@cindex method @option{gdrive} +@cindex @option{gdrive} method @cindex google drive +@cindex method @option{nextcloud} +@cindex @option{nextcloud} method +@cindex owncloud -Another GVFS-based method allows to access a Google Drive file system. -The file name syntax is here always -@file{@trampfn{gdrive,john.doe@@gmail.com,/path/to/file}}. -@samp{john.doe@@gmail.com} stands here for your Google Drive account. +GVFS-based methods include also @acronym{GNOME} Online Accounts, which +support the @option{Files} service. These are the Google Drive file +system, and the OwnCloud/NextCloud file system. The file name syntax +is here always +@file{@trampfn{gdrive,john.doe@@gmail.com,/path/to/file}} +(@samp{john.doe@@gmail.com} stands here for your Google Drive +account), or @file{@trampfn{nextcloud,user@@host#8081,/path/to/file}} +(@samp{8081} stands for the port number) for OwnCloud/NextCloud files. @anchor{Quick Start Guide: Android} @section Using Android -@cindex method adb -@cindex adb method +@cindex method @option{adb} +@cindex @option{adb} method @cindex android An Android device, which is connected via USB to your local host, can @@ -558,6 +548,18 @@ be accessed via the @command{adb} command. No user or host name is needed. The file name syntax is @file{@trampfn{adb,,/path/to/file}}. +@anchor{Quick Start Guide: @option{rclone} method} +@section Using @command{rclone} +@cindex method @option{rclone} +@cindex @option{rclone} method + +A convenient way to access system storages is the @command{rclone} +program. If you have configured a storage in @command{rclone} under a +name @samp{storage} (for example), you could access it via the remote +file name syntax @file{@trampfn{rclone,storage,/path/to/file}}. User +names are not needed. + + @node Configuration @chapter Configuring @value{tramp} @cindex configuration @@ -654,8 +656,8 @@ Inline methods can work in situations where an external transfer program is unavailable. Inline methods also work when transferring files between different @emph{user identities} on the same host. -@cindex uuencode -@cindex mimencode +@cindex @command{uuencode} +@cindex @command{mimencode} @cindex base-64 encoding @value{tramp} checks the remote host for the availability and @@ -676,15 +678,15 @@ such optimization. @table @asis @item @option{rsh} -@cindex method rsh -@cindex rsh method +@cindex method @option{rsh} +@cindex @option{rsh} method @command{rsh} is an option for connecting to hosts within local networks since @command{rsh} is not as secure as other methods. @item @option{ssh} -@cindex method ssh -@cindex ssh method +@cindex method @option{ssh} +@cindex @option{ssh} method @command{ssh} is a more secure option than others to connect to a remote host. @@ -695,15 +697,15 @@ host name, a hash sign, then a port number). It is the same as passing @samp{-p 42} to the @command{ssh} command. @item @option{telnet} -@cindex method telnet -@cindex telnet method +@cindex method @option{telnet} +@cindex @option{telnet} method Connecting to a remote host with @command{telnet} is as insecure as the @option{rsh} method. @item @option{su} -@cindex method su -@cindex su method +@cindex method @option{su} +@cindex @option{su} method Instead of connecting to a remote host, @command{su} program allows editing as another user. The host can be either @samp{localhost} or @@ -711,21 +713,27 @@ the host returned by the function @command{(system-name)}. See @ref{Multi-hops} for an exception to this behavior. @item @option{sudo} -@cindex method sudo -@cindex sudo method +@cindex method @option{sudo} +@cindex @option{sudo} method Similar to @option{su} method, @option{sudo} uses @command{sudo}. @command{sudo} must have sufficient rights to start a shell. +For security reasons, a @option{sudo} connection is disabled after a +predefined timeout (5 minutes per default). This can be changed, see +@ref{Predefined connection information}. + @item @option{doas} -@cindex method doas -@cindex doas method +@cindex method @option{doas} +@cindex @option{doas} method -This method is used on OpenBSD like the @command{sudo} command. +This method is used on OpenBSD like the @command{sudo} command. Like +the @option{sudo} method, a @option{doas} connection is disabled after +a predefined timeout. @item @option{sg} -@cindex method sg -@cindex sg method +@cindex method @option{sg} +@cindex @option{sg} method The @command{sg} program allows editing as different group. The host can be either @samp{localhost} or the host returned by the function @@ -734,8 +742,8 @@ denotes a group name. See @ref{Multi-hops} for an exception to this behavior. @item @option{sshx} -@cindex method sshx -@cindex sshx method +@cindex method @option{sshx} +@cindex @option{sshx} method Works like @option{ssh} but without the extra authentication prompts. @option{sshx} uses @samp{ssh -t -t @var{host} -l @var{user} /bin/sh} @@ -755,23 +763,23 @@ missing shell prompts that confuses @value{tramp}. @option{sshx} supports the @samp{-p} argument. @item @option{krlogin} -@cindex method krlogin -@cindex krlogin method -@cindex kerberos (with krlogin method) +@cindex method @option{krlogin} +@cindex @option{krlogin} method +@cindex kerberos (with @option{krlogin} method) This method is also similar to @option{ssh}. It uses the @command{krlogin -x} command only for remote host login. @item @option{ksu} -@cindex method ksu -@cindex ksu method -@cindex kerberos (with ksu method) +@cindex method @option{ksu} +@cindex @option{ksu} method +@cindex kerberos (with @option{ksu} method) This is another method from the Kerberos suite. It behaves like @option{su}. @item @option{plink} -@cindex method plink -@cindex plink method +@cindex method @option{plink} +@cindex @option{plink} method @option{plink} method is for MS Windows users with the PuTTY implementation of SSH@. It uses @samp{plink -ssh} to log in to the @@ -783,8 +791,8 @@ session. @option{plink} method supports the @samp{-P} argument. @item @option{plinkx} -@cindex method plinkx -@cindex plinkx method +@cindex method @option{plinkx} +@cindex @option{plinkx} method Another method using PuTTY on MS Windows with session names instead of host names. @option{plinkx} calls @samp{plink -load @var{session} @@ -814,10 +822,9 @@ methods. @table @asis @item @option{rcp} -@cindex method rcp -@cindex rcp method -@cindex rcp (with rcp method) -@cindex rsh (with rcp method) +@cindex method @option{rcp} +@cindex @option{rcp} method +@cindex @command{rsh} (with @option{rcp} method) This method uses the @command{rsh} and @command{rcp} commands to connect to the remote host and transfer files. This is the fastest @@ -827,10 +834,9 @@ The alternative method @option{remcp} uses the @command{remsh} and @command{rcp} commands. @item @option{scp} -@cindex method scp -@cindex scp method -@cindex scp (with scp method) -@cindex ssh (with scp method) +@cindex method @option{scp} +@cindex @option{scp} method +@cindex @command{ssh} (with @option{scp} method) Using a combination of @command{ssh} to connect and @command{scp} to transfer is the most secure. While the performance is good, it is @@ -844,10 +850,9 @@ argument list to @command{ssh}, and @samp{-P 42} in the argument list to @command{scp}. @item @option{rsync} -@cindex method rsync -@cindex rsync method -@cindex rsync (with rsync method) -@cindex ssh (with rsync method) +@cindex method @option{rsync} +@cindex @option{rsync} method +@cindex @command{ssh} (with @option{rsync} method) @command{ssh} command to connect in combination with @command{rsync} command to transfer is similar to the @option{scp} method. @@ -859,10 +864,9 @@ is lost if the file exists only on one side of the connection. This method supports the @samp{-p} argument. @item @option{scpx} -@cindex method scpx -@cindex scpx method -@cindex scp (with scpx method) -@cindex ssh (with scpx method) +@cindex method @option{scpx} +@cindex @option{scpx} method +@cindex @command{ssh} (with @option{scpx} method) @option{scpx} is useful to avoid login shell questions. It is similar in performance to @option{scp}. @option{scpx} uses @samp{ssh -t -t @@ -876,16 +880,14 @@ This method supports the @samp{-p} argument. @item @option{pscp} @item @option{psftp} -@cindex method pscp -@cindex pscp method -@cindex pscp (with pscp method) -@cindex plink (with pscp method) -@cindex putty (with pscp method) -@cindex method psftp -@cindex psftp method -@cindex pscp (with psftp method) -@cindex plink (with psftp method) -@cindex putty (with psftp method) +@cindex method @option{pscp} +@cindex @option{pscp} method +@cindex @command{plink} (with @option{pscp} method) +@cindex @command{putty} (with @option{pscp} method) +@cindex method @option{psftp} +@cindex @option{psftp} method +@cindex @command{plink} (with @option{psftp} method) +@cindex @command{putty} (with @option{psftp} method) These methods are similar to @option{scp} or @option{sftp}, but they use the @command{plink} command to connect to the remote host, and @@ -898,10 +900,9 @@ session. These methods support the @samp{-P} argument. @item @option{fcp} -@cindex method fcp -@cindex fcp method -@cindex fsh (with fcp method) -@cindex fcp (with fcp method) +@cindex method @option{fcp} +@cindex @option{fcp} method +@cindex @command{fsh} (with @option{fcp} method) This method is similar to @option{scp}, but uses @command{fsh} to connect and @command{fcp} to transfer files. @command{fsh/fcp}, a @@ -913,18 +914,17 @@ benefits. The command used for this connection is: @samp{fsh @var{host} -l @var{user} /bin/sh -i} -@cindex method fsh -@cindex fsh method +@cindex method @option{fsh} +@cindex @option{fsh} method @option{fsh} has no inline method since the multiplexing it offers is not useful for @value{tramp}. @command{fsh} connects to remote host and @value{tramp} keeps that one connection open. @item @option{nc} -@cindex method nc -@cindex nc method -@cindex nc (with nc method) -@cindex telnet (with nc method) +@cindex method @option{nc} +@cindex @option{nc} method +@cindex @command{telnet} (with @option{nc} method) Using @command{telnet} to connect and @command{nc} to transfer files is sometimes the only combination suitable for accessing routers or @@ -932,19 +932,43 @@ NAS hosts. These dumb devices have severely restricted local shells, such as the @command{busybox} and do not host any other encode or decode programs. +@item @option{sudoedit} +@cindex method @option{sudoedit} +@cindex @option{sudoedit} method + +The @option{sudoedit} method allows to edit a file as a different user +on the local host. You could regard this as @value{tramp}'s +implementation of the @command{sudoedit}. Contrary to the +@option{sudo} method, all magic file name functions are implemented by +single @command{sudo @dots{}} commands. The purpose is to make +editing such a file as secure as possible; there must be no session +running in the Emacs background which could be attacked from inside +Emacs. + +Consequently, external processes are not implemented. + +The host name of such remote file names must represent the local host. +Since the default value is already proper, it is recommended not to +use any host name in the remote file name, like +@file{@trampfn{sudoedit,,/path/to/file}} or +@file{@trampfn{sudoedit,user@@,/path/to/file}}. + +Like the @option{sudo} method, a @option{sudoedit} password expires +after a predefined timeout. + @item @option{ftp} -@cindex method ftp -@cindex ftp method +@cindex method @option{ftp} +@cindex @option{ftp} method When @value{tramp} uses @option{ftp}, it forwards requests to whatever ftp program is specified by Ange FTP. This external program must be capable of servicing requests from @value{tramp}. @item @option{smb} -@cindex method smb -@cindex smb method -@cindex ms windows (with smb method) -@cindex smbclient +@cindex method @option{smb} +@cindex @option{smb} method +@cindex ms windows (with @option{smb} method) +@cindex @command{smbclient} This non-native @value{tramp} method connects via the Server Message Block (SMB) networking protocol to hosts running file servers that are @@ -1015,9 +1039,9 @@ can. @item @option{adb} -@cindex method adb -@cindex adb method -@cindex android (with adb method) +@cindex method @option{adb} +@cindex @option{adb} method +@cindex android (with @option{adb} method) @vindex tramp-adb-program @vindex PATH@r{, environment variable} @@ -1052,6 +1076,48 @@ specified using @file{device#42} host name syntax or @value{tramp} can use the default value as declared in @command{adb} command. Port numbers are not applicable to Android devices connected through USB@. + +@item @option{rclone} +@cindex method @option{rclone} +@cindex @option{rclone} method + +@vindex tramp-rclone-program +The program @command{rclone} allows to access different system +storages in the cloud, see @url{https://rclone.org/} for a list of +supported systems. If the @command{rclone} program isn't found in +your @env{PATH} environment variable, you can tell Tramp its absolute +path via the user option @code{tramp-rclone-program}. + +A system storage must be configured via the @command{rclone config} +command, outside Emacs. If you have configured a storage in +@command{rclone} under a name @samp{storage} (for example), you could +access it via the remote file name + +@example +@trampfn{rclone,storage,/path/to/file} +@end example + +User names are part of the @command{rclone} configuration, and not +needed in the remote file name. If a user name is contained in the +remote file name, it is ignored. + +Internally, Tramp mounts the remote system storage at location +@file{/tmp/tramp.rclone.storage}, with @file{storage} being the name +of the configured system storage. + +Optional flags to the different @option{rclone} operations could be +passed as connection property, @xref{Predefined connection +information}. Supported properties are @samp{mount-args}, +@samp{copyto-args} and @samp{moveto-args}. + +Access via @option{rclone} is slow. If you have an alternative method +for accessing the system storage, you shall prefer this. @ref{GVFS +based methods} for example, methods @option{gdrive} and +@option{nextcloud}. + +@strong{Note}: The @option{rclone} method is experimental, don't use +it in production systems! + @end table @@ -1061,7 +1127,7 @@ numbers are not applicable to Android devices connected through USB@. @cindex gvfs based methods @cindex dbus -GVFS is the virtual file system for the Gnome Desktop, +GVFS is the virtual file system for the @acronym{GNOME} Desktop, @uref{https://en.wikipedia.org/wiki/GVFS}. Remote files on GVFS are mounted locally through FUSE and @value{tramp} uses this locally mounted directory internally. @@ -1072,8 +1138,8 @@ D-Bus, dbus}. @table @asis @item @option{afp} -@cindex method afp -@cindex afp method +@cindex method @option{afp} +@cindex @option{afp} method This method is for connecting to remote hosts with the Apple Filing Protocol for accessing files on macOS volumes. @value{tramp} access @@ -1082,10 +1148,10 @@ syntax requires a leading volume (share) name, for example: @item @option{dav} @item @option{davs} -@cindex method dav -@cindex method davs -@cindex dav method -@cindex davs method +@cindex method @option{dav} +@cindex method @option{davs} +@cindex @option{dav} method +@cindex @option{davs} method @option{dav} method provides access to WebDAV files and directories based on standard protocols, such as HTTP@. @option{davs} does the same @@ -1093,11 +1159,11 @@ but with SSL encryption. Both methods support the port numbers. Paths being part of the WebDAV volume to be mounted by GVFS, as it is common for OwnCloud or NextCloud file names, are not supported by -these methods. +these methods. See method @option{nextcloud} for handling them. @item @option{gdrive} -@cindex method gdrive -@cindex gdrive method +@cindex method @option{gdrive} +@cindex @option{gdrive} method @cindex google drive Via the @option{gdrive} method it is possible to access your Google @@ -1111,36 +1177,36 @@ Since Google Drive uses cryptic blob file names internally, could produce unexpected behavior in case two files in the same directory have the same @code{display-name}, such a situation must be avoided. -@item @option{obex} -@cindex method obex -@cindex obex method +@item @option{nextcloud} +@cindex @acronym{GNOME} Online Accounts +@cindex method @option{nextcloud} +@cindex @option{nextcloud} method +@cindex owncloud -OBEX is an FTP-like access protocol for cell phones and similar simple -devices. @value{tramp} supports OBEX over Bluetooth. +As the name indicates, the method @option{nextcloud} allows you to +access OwnCloud or NextCloud hosted files and directories. Like the +@option{gdrive} method, your credentials must be populated in your +@command{Online Accounts} application outside Emacs. The method +supports port numbers. @item @option{sftp} -@cindex method sftp -@cindex sftp method +@cindex method @option{sftp} +@cindex @option{sftp} method This method uses @command{sftp} in order to securely access remote hosts. @command{sftp} is a more secure option for connecting to hosts that for security reasons refuse @command{ssh} connections. -@item @option{synce} -@cindex method synce -@cindex synce method - -@option{synce} method allows connecting to MS Windows Mobile devices. -It uses GVFS for mounting remote files and directories via FUSE and -requires the SYNCE-GVFS plugin. - @end table @defopt tramp-gvfs-methods This user option is a list of external methods for GVFS@. By default, this list includes @option{afp}, @option{dav}, @option{davs}, -@option{gdrive}, @option{obex}, @option{sftp} and @option{synce}. -Other methods to include are: @option{ftp} and @option{smb}. +@option{gdrive}, @option{nextcloud} and @option{sftp}. Other methods +to include are @option{ftp}, @option{http}, @option{https} and +@option{smb}. These methods are not intended to be used directly as +GVFS based method. Instead, they are added here for the benefit of +@ref{Archive file names}. @end defopt @@ -1378,7 +1444,8 @@ connect to @samp{bastion.your.domain}, then: @end lisp @var{proxy} can take patterns @code{%h} or @code{%u} for @var{host} or -@var{user} respectively. +@var{user} respectively. Ports or domains, if they are part of +a hop file name, are not expanded by those patterns. To login as @samp{root} on remote hosts in the domain @samp{your.domain}, but login as @samp{root} is disabled for non-local @@ -1395,8 +1462,10 @@ Opening @file{@trampfn{sudo,randomhost.your.domain,}} first connects to @samp{randomhost.your.domain} via @code{ssh} under your account name, and then performs @code{sudo -u root} on that host. -It is key for the sudo method in the above example to be applied on -the host after reaching it and not on the local host. +It is key for the @option{sudo} method in the above example to be +applied on the host after reaching it and not on the local host. +@value{tramp} checks therefore, that the host name for such hops +matches the host name of the previous hop. @var{host}, @var{user} and @var{proxy} can also take Lisp forms. These forms when evaluated must return either a string or @code{nil}. @@ -1492,6 +1561,74 @@ predefined methods. Any part of this list can be modified with more suitable settings. Refer to the Lisp documentation of that variable, accessible with @kbd{C-h v tramp-methods @key{RET}}. +In the ELPA archives, there are several examples of such extensions. +They can be installed with Emacs' Package Manager. This includes + +@table @samp +@c @item anything-tramp +@c @item counsel-tramp +@c @item helm-tramp +@c Contact Masashí Míyaura <masasam@users.noreply.github.com> + +@c @item ibuffer-tramp.el +@c Contact Svend Sorensen <svend@@ciffer.net> + +@item docker-tramp +@cindex method @option{docker} +@cindex @option{docker} method +Integration for Docker containers. A container is accessed via +@file{@trampfn{docker,user@@container,/path/to/file}}, where +@samp{user} is the (optional) user that you want to use, and +@samp{container} is the id or name of the container. + +@item kubernetes-tramp +@cindex method @option{kubectl} +@cindex @option{kubectl} method +Integration for Docker containers deployed in a Kubernetes cluster. +It is derived from @samp{docker-tramp}. A container is accessed via +@file{@trampfn{kubectl,user@@container,/path/to/file}}, @samp{user} +and @samp{container} have the same meaning as in @samp{docker-tramp}. + +@item lxc-tramp +@cindex method @option{lxc} +@cindex @option{lxc} method +Integration for LXC containers. A container is accessed via +@file{@trampfn{lxc,container,/path/to/file}}, @samp{container} has the +same meaning as in @samp{docker-tramp}. A @samp{user} specification +is ignored. + +@item lxd-tramp +@cindex method @option{lxd} +@cindex @option{lxd} method +Integration for LXD containers. A container is accessed via +@file{@trampfn{lxd,user@@container,/path/to/file}}, @samp{user} and +@samp{container} have the same meaning as in @samp{docker-tramp}. + +@item magit-tramp +@cindex method @option{git} +@cindex @option{git} method +Browing git repositories with @code{magit}. A versioned file is accessed via +@file{@trampfn{git,rev@@root-dir,/path/to/file}}. @samp{rev} is a git +revision, and @samp{root-dir} is a virtual host name for the root +directory, specified in @code{magit-tramp-hosts-alist}. + +@item tramp-hdfs +@cindex method @option{hdfs} +@cindex @option{hdfs} method +Access of a hadoop/hdfs file system. A file is accessed via +@file{@trampfn{hdfs,user@@node,/path/to/file}}, where @samp{user} is +the user that you want to use, and @samp{node} is the name of the +hadoop server. + +@item vagrant-tramp +@cindex method @option{vagrant} +@cindex @option{vagrant} method +Convenience method to access vagrant boxes. It is often used in +multi-hop file names like +@file{@value{prefix}vagrant@value{postfixhop}box|sudo@value{postfixhop}box@value{postfix}/path/to/file}, +where @samp{box} is the name of the vagrant box. +@end table + @node Customizing Completion @section Selecting config files for user/host name completion @@ -1641,7 +1778,7 @@ the need. The package @file{auth-source.el}, originally developed for No Gnus, reads passwords from different sources, @xref{Help for users, , auth-source, auth}. The default authentication file is -@file{~/.authinfo.gpg}, but this can be changed via the variable +@file{~/.authinfo.gpg}, but this can be changed via the user option @code{auth-sources}. @noindent @@ -1660,9 +1797,26 @@ file name syntax, must be appended to the machine and login items: machine melancholia#4711 port davs login daniel%BIZARRE password geheim @end example +@vindex auth-source-save-behavior +If there doesn't exist a proper entry, the password is read +interactively. After successful login (verification of the password), +it is offered to save a corresponding entry for further use by +@code{auth-source} backends which support this. This could be changed +by setting the user option @code{auth-source-save-behavior} to @code{nil}. + @vindex auth-source-debug Set @code{auth-source-debug} to @code{t} to debug messages. +@vindex ange-ftp-netrc-filename +@strong{Note} that @file{auth-source.el} is not used for @option{ftp} +connections, because @value{tramp} passes the work to Ange FTP@. If +you want, for example, use your @file{~/.authinfo.gpg} authentication +file, you must customize @code{ange-ftp-netrc-filename}: + +@lisp +(customize-set-variable 'ange-ftp-netrc-filename "~/.authinfo.gpg") +@end lisp + @anchor{Caching passwords} @subsection Caching passwords @@ -1742,6 +1896,24 @@ The parameters @code{tramp-remote-shell} and @code{tramp-remote-shell-login} in @code{tramp-methods} now have new values for the remote host. +A common use case is to override the session timeout of a connection, +that is the time (in seconds) after a connection is disabled, and must +be reestablished. This can be set for any connection; for the +@option{sudo} and @option{doas} methods there exist predefined values. +A value of @code{nil} disables this feature. For example: + +@lisp +@group +(add-to-list 'tramp-connection-properties + (list (regexp-quote "@trampfn{sudo,root@@system-name,}") + "session-timeout" 30)) +@end group +@end lisp + +@noindent +@samp{system-name} stands here for the host returned by the function +@command{(system-name)}. + @var{property} could also be any property found in @code{tramp-persistency-file-name}. @@ -1808,9 +1980,9 @@ shell supports the login argument @samp{-l}. @end defopt When remote search paths are changed, local @value{tramp} caches must -be recomputed. To force @value{tramp} to recompute afresh, exit -Emacs, remove the persistent file (@pxref{Connection caching}), and -restart Emacs. +be recomputed. To force @value{tramp} to recompute afresh, call +@kbd{M-x tramp-cleanup-this-connection @key{RET}} or friends +(@pxref{Cleanup remote connections}). @node Remote shell setup @@ -2019,10 +2191,10 @@ shell-specific config files. For example, bash can use parsing. This redefinition affects the looks of a prompt in an interactive remote shell through commands, such as @kbd{M-x shell @key{RET}}. Such prompts, however, can be reset to something more -readable and recognizable using these @value{tramp} variables. +readable and recognizable using these environment variables. -@value{tramp} sets the @env{INSIDE_EMACS} variable in the startup -script file @file{~/.emacs_SHELLNAME}. +@value{tramp} sets the @env{INSIDE_EMACS} environment variable in the +startup script file @file{~/.emacs_SHELLNAME}. @env{SHELLNAME} is @code{bash} or equivalent shell names. Change it by setting the environment variable @env{ESHELL} in the @file{.emacs} as @@ -2048,8 +2220,8 @@ fi @end ifinfo @item @command{busybox} / @command{nc} -@cindex unix command nc -@cindex nc unix command +@cindex unix command @command{nc} +@cindex @command{nc} unix command @value{tramp}'s @option{nc} method uses the @command{nc} command to install and execute a listener as follows (see @code{tramp-methods}): @@ -2267,8 +2439,8 @@ to direct all auto saves to that location. This section is incomplete. Please share your solutions. -@cindex method sshx with cygwin -@cindex sshx method with cygwin +@cindex method @option{sshx} with cygwin +@cindex @option{sshx} method with cygwin Cygwin's @command{ssh} works only with a Cygwin version of Emacs. To check for compatibility: type @kbd{M-x eshell @key{RET}}, and start @@ -2290,8 +2462,8 @@ On @uref{https://www.emacswiki.org/emacs/SshWithNTEmacs, the Emacs Wiki} it is explained how to use the helper program @command{fakecygpty} to fix this problem. -@cindex method scpx with cygwin -@cindex scpx method with cygwin +@cindex method @option{scpx} with cygwin +@cindex @option{scpx} method with cygwin When using the @option{scpx} access method, Emacs may call @command{scp} with MS Windows file naming, such as @code{c:/foo}. But @@ -2347,6 +2519,7 @@ is a feature of Emacs that may cause missed prompts when using * Ad-hoc multi-hops:: Declaring multiple hops in the file name. * Remote processes:: Integration with other Emacs packages. * Cleanup remote connections:: Cleanup remote connections. +* Archive file names:: Access to files in file archives. @end menu @@ -2453,9 +2626,10 @@ and @code{user@@} parts are optional. @defvar tramp-file-name-regexp This variable keeps a regexp which matches the selected remote file -name syntax. However, it is not recommended to use this variable in -external packages, a call of @code{file-remote-p} is much more -appropriate. +name syntax. Its value changes after every call of +@code{tramp-change-syntax}. However, it is not recommended to use +this variable in external packages, a call of @code{file-remote-p} is +much more appropriate. @ifinfo @pxref{Magic File Names, , , elisp} @end ifinfo @@ -2531,6 +2705,14 @@ names on that host. When the configuration (@pxref{Customizing Completion}) includes user names, then the completion lists will account for the user names as well. +@vindex tramp-completion-use-auth-sources +Results from @code{auth-sources} search (@pxref{Using an +authentication file}) are added to the completion candidates. This +search could be annoying, for example due to a passphrase request of +the @file{~/.authinfo.gpg} authentication file. The user option +@code{tramp-completion-use-auth-sources} controls, whether such a +search is performed during completion. + Remote hosts previously visited or hosts whose connections are kept persistently (@pxref{Connection caching}) will be included in the completion lists. @@ -2553,7 +2735,7 @@ Example: @print{} @trampfn{ssh,melancholia,/etc} @kbd{C-x C-f @trampfn{ssh,melancholia,//etc} @key{TAB}} - @print{} /etc + @print{} @trampfn{ssh,melancholia,/etc} @kbd{C-x C-f @trampfn{ssh,melancholia,/usr/local/bin///etc} @key{TAB}} @print{} /etc @@ -2579,9 +2761,9 @@ directory contents. @cindex multi-hop, ad-hoc @cindex proxy hosts, ad-hoc -@value{tramp} file name syntax can accommodate ad hoc specification of +@value{tramp} file name syntax can accommodate ad-hoc specification of multiple proxies without using @code{tramp-default-proxies-alist} -configuration setup(@pxref{Multi-hops}). +configuration setup (@pxref{Multi-hops}). Each proxy is specified using the same syntax as the remote host specification minus the file name part. Each hop is separated by a @@ -2596,13 +2778,14 @@ proxy @samp{bird@@bastion} to a remote file on @samp{you@@remotehost}: Each involved method must be an inline method (@pxref{Inline methods}). -Proxies can take patterns @code{%h} or @code{%u}. - @value{tramp} adds the ad-hoc definitions on the fly to -@code{tramp-default-proxies-alist} and is available for re-use -during that Emacs session. Subsequent @value{tramp} connections to -the same remote host can then use the shortcut form: -@samp{@trampfn{ssh,you@@remotehost,/path}}. +@code{tramp-default-proxies-alist} and is available for re-use during +that Emacs session. Subsequent @value{tramp} connections to the same +remote host can then use the shortcut form: +@samp{@trampfn{ssh,you@@remotehost,/path}}. Ad-hoc definitions are +removed from @code{tramp-default-proxies-alist} via the command +@kbd{M-x tramp-cleanup-all-connections @key{RET}} (@pxref{Cleanup +remote connections}). @defopt tramp-save-ad-hoc-proxies For ad-hoc definitions to be saved automatically in @@ -2614,6 +2797,17 @@ For ad-hoc definitions to be saved automatically in @end lisp @end defopt +Ad-hoc proxies can take patterns @code{%h} or @code{%u} like in +@code{tramp-default-proxies-alist}. The following file name expands +to user @code{root} on host @code{remotehost}, starting with an +@option{ssh} session on host @code{remotehost}: +@samp{@value{prefix}ssh@value{postfixhop}%h|su@value{postfixhop}remotehost@value{postfix}}. + +On the other hand, if a trailing hop does not specifiy a host name, +the host name of the previous hop is reused. Therefore, the following +file name is equivalent to the previous example: +@samp{@value{prefix}ssh@value{postfixhop}remotehost|su@value{postfixhop}@value{postfix}}. + @node Remote processes @section Integration with other Emacs packages @@ -2877,7 +3071,7 @@ uid=0(root) gid=0(root) groups=0(root) @anchor{Running a debugger on a remote host} @subsection Running a debugger on a remote host -@cindex @code{gud} +@cindex @file{gud.el} @cindex @code{gdb} @cindex @code{perldb} @@ -2982,16 +3176,254 @@ as in @code{tramp-cleanup-connection}. @deffn Command tramp-cleanup-all-connections Flushes all active remote connection objects, the same as in -@code{tramp-cleanup-connection}. +@code{tramp-cleanup-connection}. This command removes also ad-hoc +proxy definitions (@pxref{Ad-hoc multi-hops}). + @end deffn @deffn Command tramp-cleanup-all-buffers Just as for @code{tramp-cleanup-all-connections}, all remote -connections are cleaned up in addition to killing buffers related to -that remote connection. +connections and ad-hoc proxy definition are cleaned up in addition to +killing buffers related to that remote connection. @end deffn +@node Archive file names +@section Archive file names +@cindex file archives +@cindex archive file names +@cindex method archive +@cindex archive method + +@value{tramp} offers also transparent access to files inside file +archives. This is possible only on machines which have installed the +virtual file system for the @acronym{GNOME} Desktop (GVFS), @ref{GVFS +based methods}. Internally, file archives are mounted via the GVFS +@option{archive} method. + +A file archive is a regular file of kind @file{/path/to/dir/file.EXT}. +The extension @samp{.EXT} identifies the type of the file archive. A +file inside a file archive, called archive file name, has the name +@file{/path/to/dir/file.EXT/dir/file}. + +Most of the @ref{Magic File Names, , magic file name operations, +elisp}, are implemented for archive file names, exceptions are all +operations which write into a file archive, and process related +operations. Therefore, functions like + +@lisp +(copy-file "/path/to/dir/file.tar/dir/file" "/somewhere/else") +@end lisp + +@noindent +work out of the box. This is also true for file name completion, and +for libraries like @code{dired} or @code{ediff}, which accept archive +file names as well. + +@vindex tramp-archive-suffixes +File archives are identified by the file name extension @samp{.EXT}. +Since GVFS uses internally the library @code{libarchive(3)}, all +suffixes, which are accepted by this library, work also for archive +file names. Accepted suffixes are listed in the constant +@code{tramp-archive-suffixes}. They are + +@itemize +@item @samp{.7z} --- +7-Zip archives +@cindex @file{7z} file archive suffix +@cindex file archive suffix @file{7z} + +@item @samp{.apk} --- +Android package kits +@cindex @file{apk} file archive suffix +@cindex file archive suffix @file{apk} + +@item @samp{.ar} --- +UNIX archiver formats +@cindex @file{ar} file archive suffix +@cindex file archive suffix @file{ar} + +@item @samp{.cab}, @samp{.CAB} --- +Microsoft Windows cabinets +@cindex @file{cab} file archive suffix +@cindex @file{CAB} file archive suffix +@cindex file archive suffix @file{cab} +@cindex file archive suffix @file{CAB} + +@item @samp{.cpio} --- +CPIO archives +@cindex @file{cpio} file archive suffix +@cindex file archive suffix @file{cpio} + +@item @samp{.deb} --- +Debian packages +@cindex @file{deb} file archive suffix +@cindex file archive suffix @file{deb} + +@item @samp{.depot} --- +HP-UX SD depots +@cindex @file{depot} file archive suffix +@cindex file archive suffix @file{depot} + +@item @samp{.exe} --- +Self extracting Microsoft Windows EXE files +@cindex @file{exe} file archive suffix +@cindex file archive suffix @file{exe} + +@item @samp{.iso} --- +ISO 9660 images +@cindex @file{iso} file archive suffix +@cindex file archive suffix @file{iso} + +@item @samp{.jar} --- +Java archives +@cindex @file{jar} file archive suffix +@cindex file archive suffix @file{jar} + +@item @samp{.lzh}, @samp{.LZH} --- +Microsoft Windows compressed LHA archives +@cindex @file{lzh} file archive suffix +@cindex @file{LZH} file archive suffix +@cindex file archive suffix @file{lzh} +@cindex file archive suffix @file{LZH} + +@item @samp{.msu}, @samp{.MSU} --- +Microsoft Windows Update packages +@cindex @file{msu} file archive suffix +@cindex @file{MSU} file archive suffix +@cindex file archive suffix @file{msu} +@cindex file archive suffix @file{MSU} + +@item @samp{.mtree} --- +BSD mtree format +@cindex @file{mtree} file archive suffix +@cindex file archive suffix @file{mtree} + +@item @samp{.odb}, @samp{.odf}, @samp{.odg}, @samp{.odp}, @samp{.ods}, +@samp{.odt} --- +OpenDocument formats +@cindex @file{odb} file archive suffix +@cindex @file{odf} file archive suffix +@cindex @file{odg} file archive suffix +@cindex @file{odp} file archive suffix +@cindex @file{ods} file archive suffix +@cindex @file{odt} file archive suffix +@cindex file archive suffix @file{odb} +@cindex file archive suffix @file{odf} +@cindex file archive suffix @file{odg} +@cindex file archive suffix @file{odp} +@cindex file archive suffix @file{ods} +@cindex file archive suffix @file{odt} + +@item @samp{.pax} --- +Posix archives +@cindex @file{pax} file archive suffix +@cindex file archive suffix @file{pax} + +@item @samp{.rar} --- +RAR archives +@cindex @file{rar} file archive suffix +@cindex file archive suffix @file{rar} + +@item @samp{.rpm} --- +Red Hat packages +@cindex @file{rpm} file archive suffix +@cindex file archive suffix @file{rpm} + +@item @samp{.shar} --- +Shell archives +@cindex @file{shar} file archive suffix +@cindex file archive suffix @file{shar} + +@item @samp{.tar}, @samp{.tbz}, @samp{.tgz}, @samp{.tlz}, @samp{.txz} --- +(Compressed) tape archives +@cindex @file{tar} file archive suffix +@cindex @file{tbz} file archive suffix +@cindex @file{tgz} file archive suffix +@cindex @file{tlz} file archive suffix +@cindex @file{txz} file archive suffix +@cindex file archive suffix @file{tar} +@cindex file archive suffix @file{tbz} +@cindex file archive suffix @file{tgz} +@cindex file archive suffix @file{tlz} +@cindex file archive suffix @file{txz} + +@item @samp{.warc} --- +Web archives +@cindex @file{warc} file archive suffix +@cindex file archive suffix @file{warc} + +@item @samp{.xar} --- +macOS XAR archives +@cindex @file{xar} file archive suffix +@cindex file archive suffix @file{xar} + +@item @samp{.xpi} --- +XPInstall Mozilla addons +@cindex @file{xpi} file archive suffix +@cindex file archive suffix @file{xpi} + +@item @samp{.xps} --- +Open XML Paper Specification (OpenXPS) documents +@cindex @file{xps} file archive suffix +@cindex file archive suffix @file{xps} + +@item @samp{.zip}, @samp{.ZIP} --- +ZIP archives +@cindex @file{zip} file archive suffix +@cindex @file{ZIP} file archive suffix +@cindex file archive suffix @file{zip} +@cindex file archive suffix @file{ZIP} +@end itemize + +@vindex tramp-archive-compression-suffixes +File archives could also be compressed, identified by an additional +compression suffix. Valid compression suffixes are listed in the +constant @code{tramp-archive-compression-suffixes}. They are +@samp{.bz2}, @samp{.gz}, @samp{.lrz}, @samp{.lz}, @samp{.lz4}, +@samp{.lzma}, @samp{.lzo}, @samp{.uu}, @samp{.xz} and @samp{.Z}. A +valid archive file name would be +@file{/path/to/dir/file.tar.gz/dir/file}. Even several suffixes in a +row are possible, like @file{/path/to/dir/file.tar.gz.uu/dir/file}. + +@vindex tramp-archive-all-gvfs-methods +An archive file name could be a remote file name, as in +@file{/ftp:anonymous@@ftp.gnu.org:/gnu/tramp/tramp-2.3.2.tar.gz/INSTALL}. +Since all file operations are mapped internally to GVFS operations, +remote file names supported by @code{tramp-gvfs} perform better, +because no local copy of the file archive must be downloaded first. +For example, @samp{/sftp:user@@host:...} performs better than the +similar @samp{/scp:user@@host:...}. See the constant +@code{tramp-archive-all-gvfs-methods} for a complete list of +@code{tramp-gvfs} supported method names. + +If @code{url-handler-mode} is enabled, archives could be visited via +URLs, like +@file{https://ftp.gnu.org/gnu/tramp/tramp-2.3.2.tar.gz/INSTALL}. This +allows complex file operations like + +@lisp +@group +(progn + (url-handler-mode 1) + (ediff-directories + "https://ftp.gnu.org/gnu/tramp/tramp-2.3.1.tar.gz/tramp-2.3.1" + "https://ftp.gnu.org/gnu/tramp/tramp-2.3.2.tar.gz/tramp-2.3.2" "")) +@end group +@end lisp + +It is even possible to access file archives in file archives, as + +@lisp +@group +(progn + (url-handler-mode 1) + (find-file + "http://ftp.debian.org/debian/pool/main/c/coreutils/coreutils_8.28-1_amd64.deb/control.tar.gz/control")) +@end group +@end lisp + + @node Bug Reports @chapter Reporting Bugs and Problems @cindex bug reports @@ -3007,9 +3439,9 @@ discussing, and general discussions about @value{tramp}. post for moderator approval. Sometimes this approval step may take as long as 48 hours due to public holidays. -@email{tramp-devel@@gnu.org} is the mailing list. Messages sent to -this address go to all the subscribers. This is @emph{not} the -address to send subscription requests to. +@email{@value{tramp-bug-report-address}} is the mailing list. +Messages sent to this address go to all the subscribers. This is +@emph{not} the address to send subscription requests to. To subscribe to the mailing list, visit: @uref{https://lists.gnu.org/mailman/listinfo/tramp-devel/, the @@ -3043,7 +3475,9 @@ When including @value{tramp}'s messages in the bug report, increase the verbosity level to 6 (@pxref{Traces and Profiles, Traces}) in the @file{~/.emacs} file before repeating steps to the bug. Include the contents of the @file{*tramp/foo*} and @file{*debug tramp/foo*} -buffers with the bug report. +buffers with the bug report. Both buffers could contain +non-@acronym{ASCII} characters which are relevant for analysis, append +the buffers as attachments to the bug report. @strong{Note} that a verbosity level greater than 6 is not necessary at this stage. Also note that a verbosity level of 6 or greater, the @@ -3076,7 +3510,8 @@ Where is the latest @value{tramp}? @item Which systems does it work on? -The package works successfully on Emacs 24, Emacs 25, and Emacs 26. +The package works successfully on Emacs 24, Emacs 25, Emacs 26, and +Emacs 27. While Unix and Unix-like systems are the primary remote targets, @value{tramp} has equal success connecting to other platforms, such as @@ -3099,6 +3534,7 @@ Keep the file @code{tramp-persistency-file-name}, which is where @value{tramp} caches remote information about hosts and files. Caching is enabled by default. Don't disable it. +@vindex remote-file-name-inhibit-cache Set @code{remote-file-name-inhibit-cache} to @code{nil} if remote files are not independently updated outside @value{tramp}'s control. That cache cleanup will be necessary if the remote directories or @@ -3251,6 +3687,16 @@ first saving to a temporary file. @item +@value{tramp} fails in a chrooted environment + +@vindex tramp-local-host-regexp +When connecting to a local host, @value{tramp} uses some internal +optimizations. They fail, when there is a chrooted environment. In +order to disable those optimizations, set user option +@code{tramp-local-host-regexp} to @code{nil}. + + +@item @value{tramp} does not recognize if a @command{ssh} session hangs @command{ssh} sessions on the local host hang when the network is @@ -3410,7 +3856,7 @@ Due to the remote shell saving tilde expansions triggered by @value{tramp} can suppress this behavior with the user option @code{tramp-histfile-override}. When set to @code{t}, environment variable @env{HISTFILE} is unset, and environment variables -@env{HISTFILESIZE} @env{HISTSIZE} are set to 0. +@env{HISTFILESIZE} and @env{HISTSIZE} are set to 0. Alternatively, @code{tramp-histfile-override} could be a string. Environment variable @env{HISTFILE} is set to this file name then. Be @@ -3763,6 +4209,15 @@ export EDITOR=/path/to/emacsclient.sh @item +How to determine whether a buffer is remote? + +The buffer-local variable @code{default-directory} tells this. If the +form @code{(file-remote-p default-directory)} returns non-@code{nil}, +the buffer is remote. See the optional arguments of +@code{file-remote-p} for determining details of the remote connection. + + +@item How to disable other packages from calling @value{tramp}? There are packages that call @value{tramp} without the user ever @@ -3804,6 +4259,7 @@ in @file{.emacs}: @end lisp @item +@vindex tramp-mode To disable both @value{tramp} (and Ange FTP), set @code{tramp-mode} to @code{nil} in @file{.emacs}. @strong{Note}, that we don't use @code{customize-set-variable}, in order to avoid loading @value{tramp}. @@ -3813,6 +4269,21 @@ To disable both @value{tramp} (and Ange FTP), set @code{tramp-mode} to @end lisp @item +@vindex tramp-ignored-file-name-regexp +To deactivate @value{tramp} for some look-alike remote file names, set +@code{tramp-ignored-file-name-regexp} to a proper regexp in +@file{.emacs}. @strong{Note}, that we don't use +@code{customize-set-variable}, in order to avoid loading +@value{tramp}. + +@lisp +(setq tramp-ignored-file-name-regexp "\\`/ssh:example\\.com:") +@end lisp + +This is needed, if you mount for example a virtual file system on your +local host's root directory as @file{/ssh:example.com:}. + +@item To unload @value{tramp}, type @kbd{M-x tramp-unload-tramp @key{RET}}. Unloading @value{tramp} resets Ange FTP plugins also. @end itemize @@ -3821,7 +4292,7 @@ Unloading @value{tramp} resets Ange FTP plugins also. @c For the developer @node Files directories and localnames -@chapter How file names, directories and localnames are mangled and managed. +@chapter How file names, directories and localnames are mangled and managed @menu * Localname deconstruction:: Splitting a localname into its component parts. @@ -3847,6 +4318,7 @@ handlers. @section Integrating with external Lisp packages @subsection File name completion. +@vindex non-essential Sometimes, it is not convenient to open a new connection to a remote host, including entering the password and alike. For example, this is nasty for packages providing file name completion. Such a package diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index aecbbe261c8..f5cc2bae179 100644 --- a/doc/misc/trampver.texi +++ b/doc/misc/trampver.texi @@ -5,12 +5,12 @@ @c Copyright (C) 2003-2019 Free Software Foundation, Inc. @c See file doclicense.texi for copying conditions. -@c In the Tramp GIT, the version number is auto-frobbed from -@c configure.ac, so you should edit that file and run -@c "autoconf && ./configure" to change the version number. -@set trampver 2.3.4.26.2 +@c In the Tramp GIT, the version number is auto-frobbed from tramp.el, +@c and the bug report address is auto-frobbed from configure.ac. +@set trampver 2.4.1 +@set tramp-bug-report-address tramp-devel@@gnu.org -@c Other flags from configuration +@c Other flags from configuration. @set instprefix /usr/local @set lispdir /usr/local/share/emacs/site-lisp @set infodir /usr/local/share/info @@ -44,3 +44,17 @@ @set ipv6prefix @set ipv6postfix @end ifset + +@c Macro for formatting a file name according to the respective +@c syntax. trampver.texi is included several times in tramp.texi and +@c trampinst.texi. Redefining the macro is reported as warning for +@c creating the dvi and pdf files, so we declare the macro only the +@c first time this file is included. +@ifclear trampfndefined +@set trampfndefined +@macro trampfn {method, userhost, localname} +@value{prefix}@c +\method\@value{postfixhop}@c +\userhost\@value{postfix}\localname\ +@end macro +@end ifclear diff --git a/doc/misc/url.texi b/doc/misc/url.texi index b190c58c023..0cdfcac24e8 100644 --- a/doc/misc/url.texi +++ b/doc/misc/url.texi @@ -571,13 +571,6 @@ if it has the file suffix @file{.z}, @file{.gz}, @file{.Z}, hard-coded, and cannot be altered by customizing @code{jka-compr-compression-info-list}.) -@defopt url-directory-index-file -This option specifies the filename to look for when a @code{file} or -@code{ftp} URL specifies a directory. The default is -@file{index.html}. If this file exists and is readable, it is viewed. -Otherwise, Emacs visits the directory using Dired. -@end defopt - @node info @section info @cindex Info @@ -1291,6 +1284,20 @@ It may also be a list of the types of messages to be logged. @end defopt @defopt url-privacy-level @end defopt +@defopt url-lastloc-privacy-level +Provided @code{lastloc} is not prohibited by @code{url-privacy-level}, +this determines who we send our last location to. @code{none} means +we include our last location in every outgoing request. +@code{domain-match} means we send it only if the domain of our last +location matches the domain of the URI we are requesting. +@code{host-match} means we only send our last location back to the +same host. The default is @code{domain-match}. + +Using @code{domain-match} for this option requires emacs to make one +or more DNS requests each time a new host is contacted, to determine +the domain of the host. Results of these lookups are cached, so +repeated visits do not require repeated domain lookups. +@end defopt @defopt url-uncompressor-alist @end defopt @defopt url-passwd-entry-func |