[shepherd] 04/10: doc: Clarify upfront what the config file does.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository shepherd.

commit 8b2170649b0e37ebfe1b22dcb7a42ec160e9dbe2
Author: Ludovic Courtès <ludo@gnu.org>
AuthorDate: Thu Apr 27 11:25:47 2023 +0200

    doc: Clarify upfront what the config file does.
    
    * doc/shepherd.texi (Invoking shepherd): For '--config', enumerate what
    the file does, with cross-references.  Add index entry.
    (The root Service): Remove mention of (oop goops).
    (Service Examples): Add index entry.
---
 doc/shepherd.texi | 29 ++++++++++++++++++++++-------
 1 file changed, 22 insertions(+), 7 deletions(-)

diff --git a/doc/shepherd.texi b/doc/shepherd.texi
index 9ec81b9..4e10ae4 100644
--- a/doc/shepherd.texi
+++ b/doc/shepherd.texi
@@ -385,17 +385,31 @@ shepherd [@var{option}@dots{}]
 
 It accepts the following options:
 
+@cindex configuration file
 @table @samp
 @item -c @var{file}
 @itemx --config=@var{file}
 Read and evaluate @var{file} as the configuration script on startup.
 
-@var{file} is evaluated in the context of a fresh module where bindings
-from the @code{(shepherd service)} module and Guile's @code{(oop goops)} are
-available, in addition to the default set of Guile bindings.  In
-particular, this means that code in @var{file} may use
-@code{register-services}, the @code{<service>} class, and related tools
-(@pxref{Services}).
+Scheme code in @var{file} is evaluated in the context of a fresh module
+where bindings from the @code{(shepherd service)} module are available,
+in addition to the default set of Guile bindings.  It may typically
+perform three actions:
+
+@enumerate
+@item
+defining services using the @code{service} procedure (@pxref{Defining
+Services});
+@item
+registering those services with @code{register-services} (@pxref{Service
+Registry});
+@item
+starting some or all of those services with
+@code{start-in-the-background} (@pxref{Interacting with Services}).
+@end enumerate
+
+@xref{Service Examples}, for examples of what @var{file} might look
+like.
 
 @item -I
 @itemx --insecure
@@ -1223,7 +1237,7 @@ Displays detailed information about every registered 
service.
 
 @item load @var{file}
 Evaluate the Scheme code in @var{file} in a fresh module that uses the
-@code{(oop goops)} and @code{(shepherd services)} modules---as with the
+@code{(shepherd services)} module---as with the
 @code{--config} option of @command{shepherd} (@pxref{Invoking shepherd}).
 
 @item eval @var{exp}
@@ -1329,6 +1343,7 @@ environment variable (@pxref{Environment Variables,
 @node Service Examples
 @section Service Examples
 
+@cindex configuration file, examples
 The configuration file of the @command{shepherd} command
 (@pxref{Invoking shepherd}) defines, registers, and possibly starts
 @dfn{services}.  Each service specifies other services it depends on and