Add an example for the :authorizable `dbus-call-method' keyword

This was requested in bug#71969 over a year ago.

* doc/misc/dbus.texi (Synchronous Methods): Add example for
`dbus-call-method' with authorization.  (Bug#79062)

(cherry picked from commit 59575c32aa1e0d28c1c7113f1ce73cb64cec8e92)

diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi
index 89a0ca086a63a4b2e5ce450f1774b680a04280d9..f9ab2c56e3cb49b340f882d06738dd9569b28d27 100644 (file)
--- a/doc/misc/dbus.texi
+++ b/doc/misc/dbus.texi
@@ -1228,7 +1228,19 @@ and Events}).
 
 If the parameter @code{:authorizable} is given and the following
 @var{auth} is non-@code{nil}, the invoked method may interactively
-prompt the user for authorization.  The default is @code{nil}.
+prompt the user for authorization.  The default is @code{nil}.  For
+example, the following will restart the Bluez systemd service, prompting
+the user for authorization via polkit (assuming a polkit agent is
+running):
+
+@lisp
+(dbus-call-method
+ :system
+ "org.freedesktop.systemd1" "/org/freedesktop/systemd1"
+ "org.freedesktop.systemd1.Manager" "RestartUnit"
+ :authorizable t
+ "bluetooth.service" "replace")
+@end lisp
 
 The remaining arguments @var{args} are passed to @var{method} as
 arguments.  They are converted into D-Bus types as described in