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/efaq.texi | 76 | ||||
| -rw-r--r-- | doc/misc/emacs-mime.texi | 35 | ||||
| -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 | 61 | ||||
| -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 | 51 | ||||
| -rw-r--r-- | doc/misc/tramp.texi | 618 | ||||
| -rw-r--r-- | doc/misc/trampver.texi | 12 | ||||
| -rw-r--r-- | doc/misc/url.texi | 21 |
21 files changed, 918 insertions, 483 deletions
diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index 11086b33037..fd07ea4ca13 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 f1667c49f1a..fcbc83ead5b 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 fdec65a9a7f..83807c6fd28 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 553b935b1ef..6985f194213 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 60915e29962..36a9cb0291a 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 7feb5166fc8..42bedb10f68 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/efaq.texi b/doc/misc/efaq.texi index 8bdd40c71cf..26d9c82b219 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? @@ -2958,7 +2988,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 +3041,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 +3763,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 +3774,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 +4568,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 2c607cc97c5..9280311b5c9 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 @@ -1535,7 +1535,7 @@ 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) @@ -1561,6 +1561,9 @@ Here's a bunch of time/date/second/day examples: (time-less-p '(13818 19266) '(13818 19145)) @result{} nil +(time-equal-p '(13818 19266) '(13818 19145)) +@result{} nil + (time-subtract '(13818 19266) '(13818 19145)) @result{} (0 121) @@ -1641,6 +1644,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 must 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 +1852,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 6942e853293..6a34f5c5722 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 ea1d070c2aa..c19d5e1a437 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 43adc2eda0f..aa17eee9d94 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 eb82ef04ad1..bda7e1428b5 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 efef01f6978..2ae5a0a0420 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 db0534e8a68..2f7d8407fc4 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)} @@ -25854,13 +25889,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 be1c806c824..61eca759f46 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 b44e503996b..85455257475 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 873ce4d2cdb..9ea78f5ace9 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 1987c50ba26..d7f7f53a348 100644 --- a/doc/misc/texinfo.tex +++ b/doc/misc/texinfo.tex @@ -3,11 +3,11 @@ % 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-06-02.09} % % 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 +% 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 @@ -1528,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} @@ -2235,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} @@ -2369,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} @@ -2503,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 } % @@ -2519,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. @@ -11677,7 +11718,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 6e026837079..7bc365ffdfe 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--2018 Free Software Foundation, Inc. @@ -122,8 +112,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 +155,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 @@ -405,7 +399,8 @@ 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}. +Hoetzel's @file{tramp-adb.el}. Archive file names are supported since +December 2017. XEmacs support was stopped in January 2016. Since March 2017, @value{tramp} syntax mandates a method. @@ -463,10 +458,10 @@ 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 @@ -482,12 +477,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} @@ -502,10 +497,10 @@ must be used here as user name. The default host name is the same. @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 +513,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 @@ -654,8 +658,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 +680,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 +699,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 +715,21 @@ 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. @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. @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 +738,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 +759,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 +787,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 +818,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 +830,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 +846,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 +860,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 +876,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 +896,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 +910,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 @@ -933,18 +929,18 @@ such as the @command{busybox} and do not host any other encode or decode programs. @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 +1011,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} @@ -1061,7 +1057,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 +1068,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 +1078,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 +1089,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 +1107,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 @@ -1395,8 +1391,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}. @@ -1641,7 +1639,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,6 +1658,13 @@ 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. @@ -1808,9 +1813,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 +2024,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 +2053,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 +2272,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 +2295,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 +2352,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 @@ -2553,7 +2559,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 @@ -2875,7 +2881,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} @@ -2990,6 +2996,242 @@ 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 @@ -3041,7 +3283,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 @@ -3074,7 +3318,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 @@ -3097,6 +3342,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 @@ -3249,6 +3495,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 @@ -3408,7 +3664,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 @@ -3761,6 +4017,15 @@ export EDITOR=/path/to/emacsclient.sh @item +How to determine wheter 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 @@ -3802,6 +4067,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}. @@ -3811,6 +4077,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 @@ -3819,7 +4100,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. @@ -3845,6 +4126,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 c6473f5b734..3a3ada9e846 100644 --- a/doc/misc/trampver.texi +++ b/doc/misc/trampver.texi @@ -8,7 +8,7 @@ @c In the Tramp GIT, the version number is auto-frobbed from @c configure.ac, so you should edit that file and run @c "autoconf && ./configure" to change the version number. -@set trampver 2.3.4.26.2 +@set trampver 2.4.1-pre @c Other flags from configuration @set instprefix /usr/local @@ -44,3 +44,13 @@ @set ipv6prefix @set ipv6postfix @end ifset + +@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 diff --git a/doc/misc/url.texi b/doc/misc/url.texi index 04bbc48dd2a..eaeae603526 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 |