From 78426b84e8b0e5de87a2203e0c8dd738cd237270 Mon Sep 17 00:00:00 2001 From: Michael Albinus Date: Wed, 14 Feb 2018 09:28:33 +0100 Subject: [PATCH] Improvements on tramp.texi * doc/misc/tramp.texi: Use Tramp version in title. Further improvements on user option indexing. Finish command examples with @key{RET} where appropriate. (Remote processes): Use 'M-&' for invocation of async shell. (Frequently Asked Questions): Add example with simplified syntax. --- doc/misc/tramp.texi | 116 +++++++++++++++++++++++++------------------- 1 file changed, 67 insertions(+), 49 deletions(-) diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 61fd0d33a73..e264298efcf 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -1,18 +1,16 @@ \input texinfo @c -*- mode: texinfo; coding: utf-8 -*- @setfilename ../../info/tramp.info @c %**start of header -@settitle TRAMP User Manual @include docstyle.texi -@c %**end of header - -@c This is *so* much nicer :) -@footnotestyle end - @c In the Tramp repository, 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. - @include trampver.texi +@settitle @value{tramp} @value{trampver} User Manual +@c %**end of header + +@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 @@ -48,7 +46,7 @@ copy and modify this GNU manual.'' @end direntry @titlepage -@title @value{tramp} version @value{trampver} User Manual +@title @value{tramp} @value{trampver} User Manual @author by Daniel Pittman @author based on documentation by Kai Großjohann @end titlepage @@ -57,9 +55,9 @@ copy and modify this GNU manual.'' @node Top, Overview, (dir), (dir) -@top @value{tramp} version @value{trampver} User Manual +@top @value{tramp} @value{trampver} User Manual -This file documents @value{tramp} version @value{trampver}, a remote file +This file documents @value{tramp} @value{trampver}, a remote file editing package for Emacs. @value{tramp} stands for ``Transparent Remote (file) Access, Multiple @@ -319,7 +317,7 @@ behind the scenes when you open a file with @value{tramp}. @chapter Obtaining @value{tramp} @cindex obtaining @value{tramp} -@value{tramp} is included as part of Emacs (since Emacs version 22.1). +@value{tramp} is included as part of Emacs (since Emacs 22.1). @value{tramp} is also freely packaged for download on the Internet at @uref{https://ftp.gnu.org/gnu/tramp/}. @@ -1444,8 +1442,8 @@ server. Both ssh and PuTTY support such proxy settings, using an HTTP tunnel via the @command{CONNECT} command (conforming to RFC 2616, 2817 -specifications). Proxy servers using HTTP version 1.1 or later -protocol support this command. +specifications). Proxy servers using HTTP 1.1 or later protocol +support this command. @subsection Tunneling with ssh @@ -1483,6 +1481,7 @@ proxy server @samp{proxy.your.domain} on port 3128. @cindex using non-standard methods @cindex create your own methods +@vindex tramp-methods The @code{tramp-methods} variable currently has an exhaustive list of predefined methods. Any part of this list can be modified with more suitable settings. Refer to the Lisp documentation of that variable, @@ -1493,8 +1492,8 @@ accessible with @kbd{C-h v tramp-methods @key{RET}}. @section Selecting config files for user/host name completion @cindex customizing completion @cindex selecting config files -@vindex tramp-completion-function-alist +@vindex tramp-completion-function-alist @code{tramp-completion-function-alist} uses predefined files for user and host name completion (@pxref{File name completion}). For each method, it keeps a set of configuration files and a function that can @@ -1632,8 +1631,8 @@ the need. @anchor{Using an authentication file} @subsection Using an authentication file -@vindex auth-sources +@vindex auth-sources 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 @@ -1679,7 +1678,6 @@ Set @code{password-cache} to @code{nil} to disable password caching. @node Connection caching @section Reusing connection related information @cindex caching -@vindex tramp-persistency-file-name @vindex tramp-persistency-file-name For faster initial connection times, @value{tramp} stores previous @@ -1703,11 +1701,11 @@ connection related information for that host and creates a new entry. @node Predefined connection information @section Setting own connection related information -@vindex tramp-connection-properties For more precise customization, parameters specified by @code{tramp-methods} can be overwritten manually. +@vindex tramp-connection-properties Set @option{tramp-connection-properties} to manually override @code{tramp-methods}. Properties in this list are in the form @code{(@var{regexp} @var{property} @var{value})}. @var{regexp} @@ -1882,7 +1880,6 @@ prompts, for which @value{tramp} uses @option{tramp-wrong-passwd-regexp}. @item @command{tset} and other questions @cindex unix command tset @cindex tset unix command -@vindex tramp-terminal-type @vindex tramp-terminal-type To suppress inappropriate prompts for terminal type, @value{tramp} @@ -1963,9 +1960,9 @@ shell-specific config files. For example, bash can use @value{tramp} redefines the remote shell prompt internally for robust parsing. This redefinition affects the looks of a prompt in an -interactive remote shell through commands, such as @kbd{M-x -shell}. Such prompts, however, can be reset to something more readable -and recognizable using these @value{tramp} variables. +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. @value{tramp} sets the @env{INSIDE_EMACS} variable in the startup script file @file{~/.emacs_SHELLNAME}. @@ -2078,8 +2075,8 @@ directory for temporary files: @item Open a remote connection with the command @kbd{C-x C-f -@trampfn{ssh,192.168.0.26#2222,}}, where @command{sshd} is listening -on port @samp{2222}. +@trampfn{ssh,192.168.0.26#2222,} @key{RET}}, where @command{sshd} is +listening on port @samp{2222}. To add a corresponding entry to the @file{~/.ssh/config} file (recommended), use this: @@ -2106,7 +2103,7 @@ the previous example, fix the connection properties as follows: @noindent Open a remote connection with a more concise command @kbd{C-x C-f -@trampfn{ssh,android,}}. +@trampfn{ssh,android,} @key{RET}}. @end itemize @@ -2114,8 +2111,8 @@ Open a remote connection with a more concise command @kbd{C-x C-f @section Auto-save and Backup configuration @cindex auto-save @cindex backup -@vindex backup-directory-alist +@vindex backup-directory-alist To avoid @value{tramp} from saving backup files owned by @samp{root} to locations accessible to others, default backup settings in @option{backup-directory-alist} have to be altered. @@ -2158,7 +2155,6 @@ Disabling backups can be targeted to just the @option{su} and @end group @end lisp -@vindex backup-directory-alist @vindex tramp-backup-directory-alist Another option is to create better backup file naming with user and host names prefixed to the file name. For example, transforming @@ -2219,8 +2215,9 @@ This section is incomplete. Please share your solutions. @cindex 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}, and start @kbd{ssh -test.host}. Incompatibilities trigger this message: +check for compatibility: type @kbd{M-x eshell @key{RET}}, and start +@kbd{ssh test.host @key{RET}}. Incompatibilities trigger this +message: @example Pseudo-terminal will not be allocated because stdin is not a terminal. @@ -2536,8 +2533,8 @@ remote host name and file name. For example, hopping over a single proxy @samp{bird@@bastion} to a remote file on @samp{you@@remotehost}: @example -@c @kbd{C-x C-f @trampfn{ssh@value{postfixhop}bird@@bastion|ssh,you,remotehost,/path}} -@kbd{C-x C-f @value{prefix}ssh@value{postfixhop}bird@@bastion|ssh@value{postfixhop}you@@remotehost@value{postfix}/path} +@c @kbd{C-x C-f @trampfn{ssh@value{postfixhop}bird@@bastion|ssh,you,remotehost,/path} @key{RET}} +@kbd{C-x C-f @value{prefix}ssh@value{postfixhop}bird@@bastion|ssh@value{postfixhop}you@@remotehost@value{postfix}/path @key{RET}} @end example Proxies can take patterns @code{%h} or @code{%u}. @@ -2759,14 +2756,15 @@ host. Example: @example @group @kbd{C-x C-f @trampfn{sudo,,} @key{RET}} -@kbd{M-! tail -f /var/log/syslog.log & @key{RET}} +@kbd{M-& tail -f /var/log/syslog.log @key{RET}} @end group @end example @command{tail} command outputs continuously to the local buffer, @file{*Async Shell Command*} -@kbd{M-x auto-revert-tail-mode} runs similarly showing continuous output. +@kbd{M-x auto-revert-tail-mode @key{RET}} runs similarly showing +continuous output. @subsection Running @code{eshell} on a remote host @@ -2775,8 +2773,8 @@ host. Example: @value{tramp} is integrated into @file{eshell.el}, which enables interactive eshell sessions on remote hosts at the command prompt. You must add the module @code{em-tramp} to @code{eshell-modules-list}. -Here's a sample interaction after opening @kbd{M-x eshell} on a remote -host: +Here's a sample interaction after opening @kbd{M-x eshell @key{RET}} +on a remote host: @example @group @@ -2857,7 +2855,7 @@ calls include: @end group @end example -Just the local part of a remote file name, such as @kbd{perl -d +Just the local part of a remote file name, such as @command{perl -d /home/user/myprog.pl}, is not possible. Arguments of the program to be debugged must be literal, can take @@ -2877,8 +2875,8 @@ command. Powershell V2.0 on the remote host is required to run processes triggered from @value{tramp}. @option{explicit-shell-file-name} and @option{explicit-*-args} have to -be set properly so @kbd{M-x shell} can open a proper remote shell on a -MS Windows host. To open @command{cmd}, set it as follows: +be set properly so @kbd{M-x shell @key{RET}} can open a proper remote +shell on a MS Windows host. To open @command{cmd}, set it as follows: @lisp @group @@ -2962,9 +2960,9 @@ Before sending a bug report, run the test suite first @ref{Testing}. Check if the bug or problem is already addressed in @xref{Frequently Asked Questions}. -Run @kbd{M-x tramp-bug} to generate a buffer with details of the -system along with the details of the @value{tramp} -installation. Please include these details with the bug report. +Run @kbd{M-x tramp-bug @key{RET}} to generate a buffer with details of +the system along with the details of the @value{tramp} installation. +Please include these details with the bug report. The bug report must describe in as excruciating detail as possible the steps required to reproduce the problem. These details must include @@ -3089,7 +3087,7 @@ put the cursor at the top of the buffer, and then apply the following expression: @example -@kbd{M-: (re-search-forward (concat tramp-shell-prompt-pattern "$"))} +@kbd{M-: (re-search-forward (concat tramp-shell-prompt-pattern "$")) @key{RET}} @end example If the cursor has not moved to the prompt at the bottom of the buffer, @@ -3293,9 +3291,10 @@ the following code in @file{~/.emacs} file. How to get a Visual Warning when working with @samp{root} privileges? Host indication in the mode line? +@cindex @value{tramp} theme @vindex tramp-theme-face-remapping-alist Install @file{tramp-theme} from GNU ELPA via Emacs' Package Manager. -Enable it via @kbd{M-x load-theme @key{RET} tramp}. Further +Enable it via @kbd{M-x load-theme @key{RET} tramp @key{RET}}. Further customization is explained in user option @option{tramp-theme-face-remapping-alist}. @@ -3369,6 +3368,24 @@ is @file{@trampfn{ssh,news@@news.my.domain,/opt/news/etc}}, then: @enumerate +@item +Use simplified syntax: + +If you always apply the default method (@pxref{Default Method}), you +could use the simplified @value{tramp} syntax (@pxref{Change file name +syntax}): + +@lisp +@group +(customize-set-variable 'tramp-default-method "ssh") +(tramp-change-syntax 'simplified) +@end group +@end lisp + +The reduced typing: @kbd{C-x C-f +@code{@value{prefix}news@@news.my.domain@value{postfix}/opt/news/etc} +@key{RET}}. + @item Use default values for method name and user name: @@ -3383,11 +3400,12 @@ You can define default methods and user names for hosts, @end group @end lisp -The reduced typing: @kbd{C-x C-f @trampfn{-,news.my.domain,/opt/news/etc}}. +The reduced typing: @kbd{C-x C-f +@trampfn{-,news.my.domain,/opt/news/etc} @key{RET}}. @strong{Note} that there are some useful shortcuts already. Accessing your local host as @samp{root} user, is possible just by @kbd{C-x C-f -@trampfn{su,,}}. +@trampfn{su,,} @key{RET}}. @item Use configuration options of the access method: @@ -3404,7 +3422,7 @@ Host xy @end group @end example -The reduced typing: @kbd{C-x C-f @trampfn{ssh,xy,/opt/news/etc}}. +The reduced typing: @kbd{C-x C-f @trampfn{ssh,xy,/opt/news/etc} @key{RET}}. Depending on the number of files in the directories, host names completion can further reduce key strokes: @kbd{C-x C-f @@ -3572,8 +3590,8 @@ Load @file{bbdb} in Emacs: @end group @end lisp -Create a BBDB entry with @kbd{M-x bbdb-create-ftp-site}. Then specify -a method and user name where needed. Examples: +Create a BBDB entry with @kbd{M-x bbdb-create-ftp-site @key{RET}}. +Then specify a method and user name where needed. Examples: @example @group @@ -3709,8 +3727,8 @@ To disable both @value{tramp} (and Ange FTP), set @code{tramp-mode} to @end lisp @item -To unload @value{tramp}, type @kbd{M-x tramp-unload-tramp}. Unloading -@value{tramp} resets Ange FTP plugins also. +To unload @value{tramp}, type @kbd{M-x tramp-unload-tramp @key{RET}}. +Unloading @value{tramp} resets Ange FTP plugins also. @end itemize @end itemize -- 2.39.2