[shepherd] 04/04: doc: Clarify and illustrate 'herd eval root' & co.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository shepherd.

commit 954742cd0d066ac4be7de4a031d7e229fd445c5d
Author: Ludovic Courtès <ludo@gnu.org>
AuthorDate: Thu May 18 23:24:49 2023 +0200

    doc: Clarify and illustrate 'herd eval root' & co.
    
    * doc/shepherd.texi (The root Service): Clarify that code is evaluated
    in the shepherd process.  Add 'herd eval root' examples.
---
 doc/shepherd.texi | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/doc/shepherd.texi b/doc/shepherd.texi
index 533480d..0f46eb3 100644
--- a/doc/shepherd.texi
+++ b/doc/shepherd.texi
@@ -1287,14 +1287,25 @@ Displays which services are started and which ones are 
not.
 @item detailed-status
 Displays detailed information about every registered service.
 
+@cindex evaluating code in shepherd
 @item load @var{file}
-Evaluate the Scheme code in @var{file} in a fresh module that uses the
-@code{(shepherd services)} module---as with the
-@code{--config} option of @command{shepherd} (@pxref{Invoking shepherd}).
+Evaluate in the @command{shepherd} process the Scheme code in
+@var{file}, in a fresh module that uses the @code{(shepherd services)}
+module---as with the @code{--config} option of @command{shepherd}
+(@pxref{Invoking shepherd}).
 
 @item eval @var{exp}
 Likewise, evaluate Scheme expression @var{exp} in a fresh module with
-all the necessary bindings.
+all the necessary bindings.  Here is a couple of examples:
+
+@example
+# herd eval root "(+ 2 2)"
+4
+# herd eval root "(getpid)"
+1
+# herd eval root "(lookup-running 'xorg-server)"
+(service (version 0) (provides (xorg-server)) @dots{})
+@end example
 
 @item unload @var{service-name}
 Attempt to remove the service identified by @var{service-name}.