diff options
Diffstat (limited to 'doc/misc')
| -rw-r--r-- | doc/misc/auth.texi | 15 | ||||
| -rw-r--r-- | doc/misc/ede.texi | 6 | ||||
| -rw-r--r-- | doc/misc/efaq.texi | 70 | ||||
| -rw-r--r-- | doc/misc/ert.texi | 14 | ||||
| -rw-r--r-- | doc/misc/gnus.texi | 11 | ||||
| -rw-r--r-- | doc/misc/message.texi | 8 | ||||
| -rw-r--r-- | doc/misc/org.texi | 6 | ||||
| -rw-r--r-- | doc/misc/texinfo.tex | 48 | ||||
| -rw-r--r-- | doc/misc/tramp.texi | 528 | ||||
| -rw-r--r-- | doc/misc/trampver.texi | 2 |
10 files changed, 533 insertions, 175 deletions
diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi index f1667c49f1a..9cf16d8ed4f 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 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 e0dfc8936d9..d657ba64c40 100644 --- a/doc/misc/efaq.texi +++ b/doc/misc/efaq.texi @@ -1490,38 +1490,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? @@ -3652,7 +3682,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 @@ -3663,7 +3693,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 diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi index 6942e853293..82e0e27ed1c 100644 --- a/doc/misc/ert.texi +++ b/doc/misc/ert.texi @@ -321,6 +321,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/gnus.texi b/doc/misc/gnus.texi index a166b33a13c..cc4b2342be6 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -13209,6 +13209,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 @@ -18478,7 +18483,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 +19471,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)} diff --git a/doc/misc/message.texi b/doc/misc/message.texi index be1c806c824..0a2a6ce49d2 100644 --- a/doc/misc/message.texi +++ b/doc/misc/message.texi @@ -1480,8 +1480,12 @@ If you're using @code{ecomplete}, all addresses from @code{To} and @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 diff --git a/doc/misc/org.texi b/doc/misc/org.texi index c6d603cd606..c727cc3f8db 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{http://orgmode.org/elpa.html, Org ELPA page}. @subsubheading Downloading Org as an archive @@ -18176,7 +18174,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 diff --git a/doc/misc/texinfo.tex b/doc/misc/texinfo.tex index 1987c50ba26..ac5c1d922ec 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-02-12.17} % % 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 @@ -182,7 +182,7 @@ % Hyphenation fixes. \hyphenation{ Flor-i-da Ghost-script Ghost-view Mac-OS Post-Script - ap-pen-dix bit-map bit-maps + auto-ma-ti-cal-ly ap-pen-dix bit-map bit-maps data-base data-bases eshell fall-ing half-way long-est man-u-script man-u-scripts mini-buf-fer mini-buf-fers over-view par-a-digm par-a-digms rath-er rec-tan-gu-lar ro-bot-ics se-vere-ly set-up spa-ces @@ -2235,6 +2235,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 +2383,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 +2531,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 +2554,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. diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index f4a1951cf30..31439043435 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -162,6 +162,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 +406,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 +465,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 +484,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 +504,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 +520,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{owncloud} +@cindex @option{owncloud} method +@cindex nextcloud -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{owncloud,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 +665,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 +687,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 +706,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 +722,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 +745,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 +766,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 +794,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 +825,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 +837,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 +853,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 +867,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 +883,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 +903,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 +917,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 +936,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 +1018,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 This method uses Android Debug Bridge program for accessing Android @@ -1060,7 +1063,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. @@ -1071,8 +1074,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 @@ -1081,18 +1084,18 @@ 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 but with SSL encryption. Both methods support the port numbers. @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 @@ -1107,23 +1110,35 @@ 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 +@cindex method @option{obex} +@cindex @option{obex} method OBEX is an FTP-like access protocol for cell phones and similar simple devices. @value{tramp} supports OBEX over Bluetooth. +@item @option{owncloud} +@cindex @acronym{GNOME} Online Accounts +@cindex method @option{owncloud} +@cindex @option{owncloud} method +@cindex nextcloud + +As the name indicates, the method @option{owncloud} 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 +@cindex method @option{synce} +@cindex @option{synce} method @option{synce} method allows connecting to MS Windows Mobile devices. It uses GVFS for mounting remote files and directories via FUSE and @@ -1134,8 +1149,11 @@ requires the SYNCE-GVFS plugin. @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{obex}, @option{owncloud}, @option{sftp} and +@option{synce}. 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 @@ -1991,8 +2009,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}): @@ -2211,8 +2229,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 @@ -2234,8 +2252,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 @@ -2290,6 +2308,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 @@ -2496,7 +2515,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 @@ -2814,7 +2833,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} @@ -2929,6 +2948,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 @@ -3013,7 +3268,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 diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index f81593fad37..eef2d9b6907 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.3.26.1 +@set trampver 2.4.0-pre @c Other flags from configuration @set instprefix /usr/local |