; 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.

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)}

doc/emacs/files.texi

@@ -1174,14 +1174,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

doc/misc/tramp.texi

@@ -3934,9 +3934,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})

etc/NEWS

@@ -1084,12 +1084,12 @@ cherry pick via 'tramp-cleanup-connection' or clear them all via
 +++
 *** New command 'tramp-dired-find-file-with-sudo'.
 This command, bound to '@' in Dired, visits the file or directory on the
-recent Dired line with root permissions.
+recent Dired line with superuser, or root, permissions.
 
 +++
-*** Command 'tramp-revert-buffer-with-sudo' is bound to 'C-x x @' now.
-Called with the prefix argument 'C-u', the used Tramp method is asked
-interactively.  This happens also for 'tramp-dired-find-file-with-sudo'.
+*** 'C-x x @' is now bound to 'tramp-revert-buffer-with-sudo'.
+You can use 'C-u C-x x @' to select a Tramp method other than the
+default, 'sudo'.
 
 +++
 *** Connection method "kubernetes" supports now optional namespace.

lisp/net/tramp-cmds.el

@@ -683,10 +683,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)
@@ -708,10 +719,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)))))