[shepherd] 03/04: doc: Clarify when the service interface may be used.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository shepherd.

commit d3d437a34bcb11fc416bf141181d8908064aeceb
Author: Ludovic Courtès <ludo@gnu.org>
AuthorDate: Thu May 18 23:18:35 2023 +0200

    doc: Clarify when the service interface may be used.
    
    * doc/shepherd.texi (Services): Add note about valid usage contexts.
---
 doc/shepherd.texi | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/doc/shepherd.texi b/doc/shepherd.texi
index f6ce44b..533480d 100644
--- a/doc/shepherd.texi
+++ b/doc/shepherd.texi
@@ -615,6 +615,25 @@ what PID or other value is associated with it, and so on.
 This section explains how to define services and how to query their
 configuration and state using the Shepherd's programming interfaces.
 
+@quotation Note
+The programming interface defined in this section may only be used
+within a @command{shepherd} process.  Examples where you may use it
+include:
+
+@itemize
+@item
+the @command{shepherd} configuration file (@pxref{Service Examples});
+@item
+as an argument to @command{herd eval root @dots{}} (@pxref{The root
+Service});
+@item
+at the REPL (@pxref{REPL Service}).
+@end itemize
+
+These procedures may not be used in Guile processes other than
+@command{shepherd} itself.
+@end quotation
+
 @menu
 * Defining Services::           Defining services.
 * Service Registry::            Mapping service names to records.