[shepherd] 01/04: doc: Recommend against 'make-system-constructor'.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository shepherd.

commit 35a1212e943ff81dcb7f3b45a1721a767630426a
Author: Ludovic Courtès <ludo@gnu.org>
AuthorDate: Sat Mar 11 16:04:52 2023 +0100

    doc: Recommend against 'make-system-constructor'.
    
    * doc/shepherd.texi (Service De- and Constructors): Move
    'make-system-constructor' and 'make-system-destructor' to the bottom and
    recommend against them.
---
 doc/shepherd.texi | 30 ++++++++++++++++++------------
 1 file changed, 18 insertions(+), 12 deletions(-)

diff --git a/doc/shepherd.texi b/doc/shepherd.texi
index a7c10d3..431e4b3 100644
--- a/doc/shepherd.texi
+++ b/doc/shepherd.texi
@@ -880,18 +880,6 @@ All of the procedures listed below return procedures 
generated from
 the supplied arguments.  These procedures take one argument in the
 case of destructors and no arguments in the case of constructors.
 
-@deffn {procedure} make-system-constructor @var{command}@dots{}
-The returned procedure will execute @var{command} in a shell and
-return @code{#t} if execution was successful, otherwise @code{#f}.
-For convenience, it takes multiple arguments which will be
-concatenated first.
-@end deffn
-
-@deffn {procedure} make-system-destructor @var{command}@dots{}
-Similar to @code{make-system-constructor}, but returns @code{#f} if
-execution of the @var{command} was successful, @code{#t} if not.
-@end deffn
-
 @deffn {procedure} make-forkexec-constructor @var{command} @
   [#:user #f] @
   [#:group #f] @
@@ -1160,6 +1148,24 @@ Return a procedure that terminates a systemd-style 
service as created by
 @code{make-systemd-constructor}.
 @end deffn
 
+The following constructor/destructor pair is also available for your
+convenience, but we recommend using @code{make-forkexec-constructor} and
+@code{make-kill-destructor} instead (this is typically more robust than
+going through the shell):
+
+@deffn {procedure} make-system-constructor @var{command}@dots{}
+The returned procedure will execute @var{command} in a shell and
+return @code{#t} if execution was successful, otherwise @code{#f}.
+For convenience, it takes multiple arguments which will be
+concatenated first.
+@end deffn
+
+@deffn {procedure} make-system-destructor @var{command}@dots{}
+Similar to @code{make-system-constructor}, but returns @code{#f} if
+execution of the @var{command} was successful, @code{#t} if not.
+@end deffn
+
+
 @c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 
 @node Service Examples