; Touch up tramp-*-with-sudo documentation, add FIXMEs

* doc/emacs/dired.texi (Dired Visiting):
* doc/emacs/files.texi (Reverting):
* doc/misc/tramp.texi (Ad-hoc multi-hops):
* etc/NEWS:
* lisp/net/tramp-cmds.el (tramp-revert-buffer-with-sudo)
(tramp-dired-find-file-with-sudo): Touch up documentation of
these features.  Add FIXMEs about renaming the two commands.

(cherry picked from commit a57e9f45db6007bdb4af21a444f0ed62d1b2010e)

diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi
index 0d7d7c4cf261f41ef44eab3586578de3d2a00855..602c8e5bfb253cd7ed1944a171c890612ec25369 100644 (file)
--- a/doc/emacs/dired.texi
+++ b/doc/emacs/dired.texi
@@ -463,10 +463,11 @@ navigate the buffer but forbids changing it; @xref{View Mode}.
 @item @@
 @kindex @@ @r{(Dired)}
 @findex tramp-dired-find-file-with-sudo
-Open the file described on the current line, with root permissions
-(@code{tramp-dired-find-file-with-sudo}).  Calling it with the @kbd{C-u}
-prefix argument asks for another Tramp method interactively but
-@option{sudo}.  @xref{Ad-hoc multi-hops, Tramp,, tramp, The Tramp Manual}.
+Open the file described on the current line, with superuser, or root,
+permissions (@code{tramp-dired-find-file-with-sudo}).  If called with a
+@kbd{C-u} prefix argument, it prompts for another Tramp method to use
+other than the default, @option{sudo}.  @xref{Ad-hoc multi-hops, Tramp,,
+tramp, The Tramp Manual}.
 
 @item ^
 @kindex ^ @r{(Dired)}

diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index e7c5130c6b56acab87508985bd291762cdd388c8..7f62603ae41f9007f424e3cf597a4b666e033a15 100644 (file)
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -1172,14 +1172,16 @@ the major mode actually turned on as result of reverting a buffer
 depends on mode remapping, and could be different from the original mode
 if you customized @code{major-mode-remap-alist} in-between.
 
+@cindex reverting with superuser permissions
 @cindex reverting with root permissions
 @findex tramp-revert-buffer-with-sudo
 @kindex C-x x @@
-A variant of reverting a buffer is visiting it by the
-@code{tramp-revert-buffer-with-sudo} (@kbd{C-x x @@}) command. It
-reopens the file or Dired buffer with root permissions.  With a prefix
-argument of @kbd{C-u}, you could change the default Tramp method
-(@option{sudo}).  @xref{Ad-hoc multi-hops, Tramp,, tramp, The Tramp Manual}.
+The @kbd{C-x x @@} keystroke is bound to the
+@code{tramp-revert-buffer-with-sudo} command.  This visits the file
+again, but with superuser, or root, permissions.  If called with a
+@kbd{C-u} prefix argument, it prompts for another Tramp method to use
+other than the default, @option{sudo}.  @xref{Ad-hoc multi-hops, Tramp,,
+tramp, The Tramp Manual}.
 
 @node Auto Revert
 @section Auto Revert: Keeping buffers automatically up-to-date

diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi
index 26143da95017fb25b771a25404cbb9b990512209..04811355b9a492b5c01a9b8f6e0de9cb06731cf5 100644 (file)
--- a/doc/misc/tramp.texi
+++ b/doc/misc/tramp.texi
@@ -3924,9 +3924,8 @@ method.  The commands @code{tramp-revert-buffer-with-sudo} (@kbd{C-x x
 
 @kindex C-x x @@
 @deffn Command tramp-revert-buffer-with-sudo
-This command shows the current buffer with @option{sudo} permissions.
-The buffer must either visit a file, or a directory
-(@code{dired-mode}).
+This command visits the current buffer with @option{sudo} permissions.
+The buffer must either visit a file, or a directory in @code{dired-mode}.
 @end deffn
 
 @kindex @@ @r{(in dired})

diff --git a/lisp/net/tramp-cmds.el b/lisp/net/tramp-cmds.el
index 2789d00380c1f6731b870554d53712609b6a345f..6db1e9bfd12875df5054ea7cd082bdcc7ff2a921 100644 (file)
--- a/lisp/net/tramp-cmds.el
+++ b/lisp/net/tramp-cmds.el
@@ -681,10 +681,21 @@ An alternative method could be chosen with `tramp-file-name-with-method'."
      (make-tramp-file-name
       :method tramp-file-name-with-method :localname filename))))
 
+;; FIXME: We would like to rename this for Emacs 31.1 to a name that
+;; does not encode the default method.  It is intended as a generic
+;; privilege-elevation command.  Some ideas from bug#76974:
+;; `tramp-revert-buffer-obtain-root',
+;; `tramp-revert-buffer-as-superuser'.
+
 ;;;###autoload
 (defun tramp-revert-buffer-with-sudo ()
-  "Revert current buffer to visit with \"sudo\" permissions.
-An alternative method could be chosen with `tramp-file-name-with-method'.
+  "Visit the current file again with superuser, or root, permissions.
+
+By default this is done using the \"sudo\" Tramp method.
+You can customize `tramp-file-name-with-method' to change this.
+
+Interactively, with a prefix argument, prompt for a different method.
+
 If the buffer visits a file, the file is replaced.
 If the buffer runs `dired', the buffer is reverted."
   (interactive)
@@ -706,10 +717,16 @@ If the buffer runs `dired', the buffer is reverted."
       (dired-advertise)
       (revert-buffer)))))
 
+;; FIXME: See FIXME above about renaming this before Emacs 31.1.
+
 ;;;###autoload
 (defun tramp-dired-find-file-with-sudo ()
-  "In Dired, visit the file or directory named on this line.
-This is performed with \"sudo\" permissions."
+  "Visit the file or directory named on this line as the superuser.
+
+By default this is done using the \"sudo\" Tramp method.
+YOu can customize `tramp-file-name-with-method' to change this.
+
+Interactively, with a prefix argument, prompt for a different method."
   (interactive)
   (with-tramp-file-name-with-method
     (find-file (tramp-file-name-with-sudo (dired-get-file-for-visit)))))