* [Shepherd][PATCH 0/4] Move documentation to a 'doc' directory.
@ 2016-01-27 20:45 Mathieu Lirzin
2016-01-27 20:45 ` [Shepherd][PATCH 1/4] build: Build Guile objects before generating man pages Mathieu Lirzin
` (3 more replies)
0 siblings, 4 replies; 11+ messages in thread
From: Mathieu Lirzin @ 2016-01-27 20:45 UTC (permalink / raw)
To: guix-devel
[-- Attachment #1: Type: text/plain, Size: 1716 bytes --]
Regarding patch 4, Deleting ‘man-page-target’ function (which was just added)
was a personal choice. I don't like the use of “fancy” GNU Make features
which provide another layer of complexity on top of Automake's paradigm which
can be obscure by itself for an uninformed public.
Mathieu Lirzin (4):
build: Build Guile objects before generating man pages.
doc: Move examples to the 'doc/examples' directory.
doc: Move manual to the 'doc' directory.
doc: Move man pages to the 'doc' directory.
.gitignore | 49 +-
Makefile.am | 45 +-
configure.ac | 3 +-
doc/examples/README | 17 +
doc/examples/_unknown.scm | 153 +++++
doc/examples/wolfgangj.scm | 132 ++++
doc/fdl-1.3.texi | 505 ++++++++++++++
doc/shepherd.texi | 1593 ++++++++++++++++++++++++++++++++++++++++++++
examples/Makefile.am | 3 -
examples/README | 17 -
examples/_unknown.scm | 153 -----
examples/wolfgangj.scm | 132 ----
fdl-1.3.texi | 505 --------------
shepherd.texi | 1593 --------------------------------------------
14 files changed, 2450 insertions(+), 2450 deletions(-)
create mode 100644 doc/examples/README
create mode 100644 doc/examples/_unknown.scm
create mode 100644 doc/examples/wolfgangj.scm
create mode 100644 doc/fdl-1.3.texi
create mode 100644 doc/shepherd.texi
delete mode 100644 examples/Makefile.am
delete mode 100644 examples/README
delete mode 100644 examples/_unknown.scm
delete mode 100644 examples/wolfgangj.scm
delete mode 100644 fdl-1.3.texi
delete mode 100644 shepherd.texi
--
2.7.0.rc3
^ permalink raw reply [flat|nested] 11+ messages in thread
* [Shepherd][PATCH 1/4] build: Build Guile objects before generating man pages.
2016-01-27 20:45 [Shepherd][PATCH 0/4] Move documentation to a 'doc' directory Mathieu Lirzin
@ 2016-01-27 20:45 ` Mathieu Lirzin
2016-01-27 22:55 ` Ludovic Courtès
2016-01-27 20:45 ` [Shepherd][PATCH 2/4] doc: Move examples to the 'doc/examples' directory Mathieu Lirzin
` (2 subsequent siblings)
3 siblings, 1 reply; 11+ messages in thread
From: Mathieu Lirzin @ 2016-01-27 20:45 UTC (permalink / raw)
To: guix-devel
[-- Attachment #1: Type: text/plain, Size: 214 bytes --]
Before that, man pages were not successfully generated for VPATH builds.
* Makefile.am (BUILT_SOURCES): Add every '.go' files.
---
Makefile.am | 6 +++++-
1 file changed, 5 insertions(+), 1 deletion(-)
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-build-Build-Guile-objects-before-generating-man-page.patch --]
[-- Type: text/x-patch; name="0001-build-Build-Guile-objects-before-generating-man-page.patch", Size: 479 bytes --]
diff --git a/Makefile.am b/Makefile.am
index dcffcea..6ebd0f1 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -26,7 +26,11 @@ templates = \
modules/shepherd/system.scm.in
# Build this module first.
-BUILT_SOURCES = modules/shepherd/config.scm
+BUILT_SOURCES = \
+ $(nodist_shepherdsub_DATA) \
+ $(nodist_scripts_DATA) \
+ $(nodist_guilemodule_DATA)
+
# The source files.
# XXX: we can't use 'nobase_' because of the modules/ subdirectory.
^ permalink raw reply related [flat|nested] 11+ messages in thread
* [Shepherd][PATCH 2/4] doc: Move examples to the 'doc/examples' directory.
2016-01-27 20:45 [Shepherd][PATCH 0/4] Move documentation to a 'doc' directory Mathieu Lirzin
2016-01-27 20:45 ` [Shepherd][PATCH 1/4] build: Build Guile objects before generating man pages Mathieu Lirzin
@ 2016-01-27 20:45 ` Mathieu Lirzin
2016-01-27 22:57 ` Ludovic Courtès
2016-01-27 20:45 ` [Shepherd][PATCH 3/4] doc: Move manual to the 'doc' directory Mathieu Lirzin
2016-01-27 20:45 ` [Shepherd][PATCH 4/4] doc: Move man pages " Mathieu Lirzin
3 siblings, 1 reply; 11+ messages in thread
From: Mathieu Lirzin @ 2016-01-27 20:45 UTC (permalink / raw)
To: guix-devel
[-- Attachment #1: Type: text/plain, Size: 1195 bytes --]
* doc/examples/README: moved from 'examples' directory.
* doc/examples/_unknown.scm: Likewise.
* doc/examples/wolfgangj.scm: Likewise.
* examples/Makefile.am: Delete file.
* configure.ac (AC_CONFIG_FILES): Adapt to it.
* Makefile.am (EXTRA_DIST): Add files from "doc/examples" directory.
(SUBDIRS): Delete variable.
---
Makefile.am | 10 ++-
configure.ac | 3 +-
doc/examples/README | 17 +++++
doc/examples/_unknown.scm | 153 +++++++++++++++++++++++++++++++++++++++++++++
doc/examples/wolfgangj.scm | 132 ++++++++++++++++++++++++++++++++++++++
examples/Makefile.am | 3 -
examples/README | 17 -----
examples/_unknown.scm | 153 ---------------------------------------------
examples/wolfgangj.scm | 132 --------------------------------------
9 files changed, 311 insertions(+), 309 deletions(-)
create mode 100644 doc/examples/README
create mode 100644 doc/examples/_unknown.scm
create mode 100644 doc/examples/wolfgangj.scm
delete mode 100644 examples/Makefile.am
delete mode 100644 examples/README
delete mode 100644 examples/_unknown.scm
delete mode 100644 examples/wolfgangj.scm
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0002-doc-Move-examples-to-the-doc-examples-directory.patch --]
[-- Type: text/x-patch; name="0002-doc-Move-examples-to-the-doc-examples-directory.patch", Size: 26036 bytes --]
diff --git a/Makefile.am b/Makefile.am
index 6ebd0f1..2985a86 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -67,7 +67,6 @@ CLEANFILES = \
# Documentation.
info_TEXINFOS = shepherd.texi
-SUBDIRS = examples
AM_V_HELP2MAN = $(AM_V_HELP2MAN_$(V))
AM_V_HELP2MAN_ = $(AM_V_HELP2MAN_$(AM_DEFAULT_VERBOSITY))
@@ -97,7 +96,14 @@ dist_man1_MANS = shepherd.1 herd.1
dist_man8_MANS = halt.8 reboot.8
# Things not automatically included in the distribution.
-EXTRA_DIST = $(templates) QUESTIONS fdl-1.3.texi ChangeLog-2003
+EXTRA_DIST = \
+ ChangeLog-2003 \
+ fdl-1.3.texi \
+ QUESTIONS \
+ $(templates) \
+ doc/examples/README \
+ doc/examples/_unknown.scm \
+ doc/examples/wolfgangj.scm
# Create the socket directory (aka. 'default-socket-dir'.) Make it
# accessible only by its owner since otherwise 'shepherd' suggests using
diff --git a/configure.ac b/configure.ac
index 339167c..abab3fa 100644
--- a/configure.ac
+++ b/configure.ac
@@ -94,7 +94,6 @@ AM_MISSING_PROG([HELP2MAN], [help2man])
dnl Finish.
AC_CONFIG_FILES([Makefile
- examples/Makefile
- modules/shepherd/system.scm])
+ modules/shepherd/system.scm])
AC_OUTPUT
diff --git a/doc/examples/README b/doc/examples/README
new file mode 100644
index 0000000..86b4b6a
--- /dev/null
+++ b/doc/examples/README
@@ -0,0 +1,17 @@
+Example configurations for dmd
+=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+
+This directory contains personal configuration files and interesting
+configuration possibilities, the latter being in the files starting
+with an underscore character. You can send me your configuration too
+(or your cute configuration code snippets), and I will include it
+here, provided that it is available under a license that makes it Free
+Software. Note that for personal configurations I don't want
+ChangeLogs, since I won't maintain your configuration anyway :-) but
+changes in the snippets should be documented like other changes.
+
+Hint: If you send my your configuration, then not only can other
+people learn from it, but I can also make sure that I do not break
+your code too often by making incompatible changes, and if I do it
+anyway but notice it, I might tell you how to change the code to work
+with a new version.
diff --git a/doc/examples/_unknown.scm b/doc/examples/_unknown.scm
new file mode 100644
index 0000000..fb639ab
--- /dev/null
+++ b/doc/examples/_unknown.scm
@@ -0,0 +1,153 @@
+;; _unknown.scm -- An example for an `unknown' service.
+;; Copyright (C) 2003 Wolfgang Jährling <wolfgang@pro-linux.de>
+;;
+;; This file is part of the GNU Shepherd.
+;;
+;; The GNU Shepherd is free software; you can redistribute it and/or modify it
+;; under the terms of the GNU General Public License as published by
+;; the Free Software Foundation; either version 3 of the License, or (at
+;; your option) any later version.
+;;
+;; The GNU Shepherd is distributed in the hope that it will be useful, but
+;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;; GNU General Public License for more details.
+;;
+;; You should have received a copy of the GNU General Public License
+;; along with the GNU Shepherd. If not, see <http://www.gnu.org/licenses/>.
+
+;; Return true if STR1 lacks a character that exists in STR2, but
+;; otherwise both are identical.
+(define (lacks-char-from? str1 str2)
+ (and (= (string-length str1)
+ (+ (string-length str2) 1))
+ (letrec ((next
+ (lambda (pos)
+ (and (not (= pos (string-length str1)))
+ (or (string=? str2
+ (string-append
+ (substring str1 0 pos)
+ (substring str1
+ (+ pos 1)
+ (string-length str1))))
+ (next (+ pos 1)))))))
+ (next 0))))
+
+;; Return true if either of STR1 and STR2 lacks a character found in
+;; the other one, but otherwise both are identical (e.g. as is the
+;; case for "blah" and "bla").
+(define (differs-by-missing-char? str1 str2)
+ (or (lacks-char-from? str1 str2)
+ (lacks-char-from? str2 str1)))
+
+;; Return true if the only difference between STR1 and STR2 is that a
+;; successive pair of characters is switched in one of them.
+(define (differs-by-switched-chars? str1 str2)
+ (and (= (string-length str1)
+ (string-length str2))
+ (> (string-length str1) 1)
+ (letrec ((next
+ (lambda (pos)
+ (and (not (= pos (string-length str1)))
+ (or (string=? str2
+ (string-append
+ (substring str1 0 (- pos 1))
+ (string (string-ref str1 pos)
+ (string-ref str1 (- pos 1)))
+ (substring str1
+ (+ pos 1)
+ (string-length str1))))
+ (next (+ pos 1)))))))
+ (next 1))))
+
+;; Return true if they differ by exactly one character (e.g. as is the
+;; case for "blah" and "bleh"), if it isn't the only one.
+(define (differs-by-one-char? str1 str2)
+ (and (= (string-length str1)
+ (string-length str2))
+ (> (string-length str1) 1)
+ (letrec ((next
+ (lambda (pos found-difference)
+ (if (= pos (string-length str1))
+ found-difference
+ (if (char=? (string-ref str1 pos)
+ (string-ref str2 pos))
+ (next (+ pos 1) found-difference)
+ (and (not found-difference)
+ (next (+ pos 1) #t)))))))
+ (next 0 #f))))
+
+;; Return true if STR1 and STR2 are identical, except for case
+;; (e.g. this gives true for "foobar" and "FooBAR").
+(define (differs-only-in-case? str1 str2)
+ (and (not (string=? str1 str2))
+ (string-ci=? str1 str2)))
+
+;; Return true if STR1 and STR2 are `similar' strings, meaning that
+;; they only differ in a minor way.
+(define (similar? str1 str2)
+ (any (lambda (pred?)
+ (pred? str1 str2))
+ (list differs-by-missing-char?
+ differs-by-switched-chars?
+ differs-by-one-char?
+ differs-only-in-case?)))
+
+\f
+
+;; TODO
+;; - We could look for non-running services first on `start' etc.
+;; - We also should do `unknown-action' (if service is known)
+;; - If doing this, we should enable the service to handle it
+;; - Make this the `default unknown service'
+;; - Messages if nothing found.
+
+;; Suggest a service that satisfies PRED?, if given, and has a name
+;; similar to SERVICE-SYMBOL.
+(define look-for-service
+ (case-lambda
+ ((service-symbol) (look-for-service service-symbol (lambda (x) #t)))
+ ((service-symbol pred?)
+ (call/ec
+ (lambda (return)
+ (for-each-service
+ (lambda (s)
+ (and (pred? s)
+ (similar? (symbol->string service-symbol)
+ (symbol->string (canonical-name s)))
+ (begin
+ (format #t "Did you mean ~a maybe?" (canonical-name s))
+ (newline)
+ (return #t)))))
+ #f)))))
+
+;; The classical compose.
+(define (compose f g)
+ (lambda (x)
+ (f (g x)))
+
+ (define unknown-service
+ (make <service>
+ #:provides '(unknown)
+ #:actions (make-actions
+ (start
+ "Called if user wants to start an unknown service."
+ (lambda (running service-sym . args)
+ (or (look-for-service service-sym (compose not running?))
+ (look-for-service service-sym))
+ running))
+ (stop
+ "Called if user wants to stop an unknown service."
+ (lambda (running service-sym . args)
+ (or (look-for-service service-sym running?)
+ (look-for-service service-sym))
+ running))
+ (action
+ "Called if user frobs an unknown service."
+ (lambda (running service-sym the-action . args)
+ (or (look-for-service service-sym running?)
+ (look-for-service service-sym))
+ running)))))
+
+ (register-services unknown-service)
+ (start unknown-service)
diff --git a/doc/examples/wolfgangj.scm b/doc/examples/wolfgangj.scm
new file mode 100644
index 0000000..0c16108
--- /dev/null
+++ b/doc/examples/wolfgangj.scm
@@ -0,0 +1,132 @@
+;; wolfgangj.scm -- Personal dmd configuration of Wolfgang Jährling.
+;; Copyright (C) 2002, 2003 Wolfgang Jährling <wolfgang@pro-linux.de>
+;;
+;; This file is part of the GNU Shepherd.
+;;
+;; The GNU Shepherd is free software; you can redistribute it and/or modify it
+;; under the terms of the GNU General Public License as published by
+;; the Free Software Foundation; either version 3 of the License, or (at
+;; your option) any later version.
+;;
+;; The GNU Shepherd is distributed in the hope that it will be useful, but
+;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+;; GNU General Public License for more details.
+;;
+;; You should have received a copy of the GNU General Public License
+;; along with the GNU Shepherd. If not, see <http://www.gnu.org/licenses/>.
+
+\f
+
+;; A few notes about the computer this setup is for: It is a PC
+;; running Debian GNU/Linux 3.0, on which I am usually using screen,
+;; which is why I need few terminals. I am using it to connect to the
+;; internet via ISDN, but I'm also using it in my local network, in
+;; which case it is running Apache. Because I don't want to have
+;; Apache running when I am online, I made Apache conflict with the
+;; ISDN setup.
+
+;; Laziness.
+(define (number->symbol num)
+ (string->symbol (number->string num)))
+
+;; Even more laziness.
+(define cat string-append)
+
+;; Some values for this system.
+(define getty "/sbin/getty")
+(define ifconfig "/sbin/ifconfig")
+(define isdnctrl "/usr/sbin/isdnctrl")
+
+(define inet-interface "ippp0")
+(define inet-dial (cat isdnctrl " dial " inet-interface))
+(define inet-hangup (cat isdnctrl " hangup " inet-interface))
+
+(define local-interface "eth0")
+(define local-ip "192.168.0.9")
+
+(define init.d-dir "/etc/init.d/")
+(define apache (cat init.d-dir "apache"))
+(define inet (cat init.d-dir "isdnutils"))
+(define exim (cat init.d-dir "exim"))
+
+;; Create a service providing a terminal.
+(define (make-term num)
+ (let ((sym (symbol-append 'term- (number->symbol num))))
+ (make <service>
+ #:provides (list sym)
+ #:respawn? #t
+ #:start (make-forkexec-constructor getty "38400"
+ (cat "tty" (number->string num)))
+ #:stop-delay? #t)))
+
+;; Number of terminals created by default.
+(define default-terms 3)
+
+;; How many terms have been created with `add-new-term'.
+(define term-counter 0)
+
+;; Add a new terminal to the list of registered services.
+(define (add-new-term)
+ (set! term-counter (+ term-counter 1))
+ (register-services (make-term term-counter)))
+
+(register-services
+ (make <service>
+ #:provides '(term)
+ #:actions (make-actions
+ (create "Create a new terminal."
+ (lambda (running)
+ (add-new-term)))
+ (counter-set "Set the terminal creation counter."
+ (lambda (running num)
+ (set! term-counter (string->number num))))
+ (status "Display the terminal creation counter."
+ (lambda (running)
+ (local-output "Terminal counter is at ~a."
+ term-counter)))))
+ (make <service>
+ #:provides '(apache insecurity)
+ #:requires '(local-net)
+ #:start (make-system-constructor apache " start")
+ #:stop (make-system-destructor apache " stop"))
+ (make <service>
+ #:provides '(inet insecurity)
+ #:start (make-system-constructor inet " start")
+ #:stop (make-system-destructor inet " stop")
+ #:actions (make-actions
+ (dial "Connect to the big, evil internet."
+ (lambda (running)
+ (system inet-dial)
+ #t))
+ (hangup "Cut the internet connection."
+ (lambda (running)
+ (system inet-hangup)
+ #t))))
+ (make <service>
+ #:provides '(local-net)
+ #:start (make-system-constructor ifconfig " " local-interface " " local-ip)
+ #:stop (make-system-destructor ifconfig " " local-interface " down"))
+ (make <service>
+ #:provides '(exim mailer-daemon)
+ #:requires '(inet)
+ #:start (make-system-constructor exim " start")
+ #:stop (make-system-destructor exim " stop")))
+
+;; Create a few terminals.
+(letrec ((loop (lambda (i)
+ (and (not (zero? i))
+ (begin
+ (add-new-term)
+ (loop (- i 1)))))))
+ (loop default-terms))
+
+;; Go into background.
+(action 'dmd 'daemonize)
+
+;; Setup internet, a mailer and a few terms.
+(for-each start
+ (append '(term inet mailer-daemon)
+ (map (lambda (x)
+ (symbol-append 'term- (number->symbol x)))
+ (iota default-terms 1))))
diff --git a/examples/Makefile.am b/examples/Makefile.am
deleted file mode 100644
index 648b244..0000000
--- a/examples/Makefile.am
+++ /dev/null
@@ -1,3 +0,0 @@
-# examples/Makefile.am -- Add a few examples to the distribution.
-
-EXTRA_DIST = README _unknown.scm wolfgangj.scm
diff --git a/examples/README b/examples/README
deleted file mode 100644
index 86b4b6a..0000000
--- a/examples/README
+++ /dev/null
@@ -1,17 +0,0 @@
-Example configurations for dmd
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-
-This directory contains personal configuration files and interesting
-configuration possibilities, the latter being in the files starting
-with an underscore character. You can send me your configuration too
-(or your cute configuration code snippets), and I will include it
-here, provided that it is available under a license that makes it Free
-Software. Note that for personal configurations I don't want
-ChangeLogs, since I won't maintain your configuration anyway :-) but
-changes in the snippets should be documented like other changes.
-
-Hint: If you send my your configuration, then not only can other
-people learn from it, but I can also make sure that I do not break
-your code too often by making incompatible changes, and if I do it
-anyway but notice it, I might tell you how to change the code to work
-with a new version.
diff --git a/examples/_unknown.scm b/examples/_unknown.scm
deleted file mode 100644
index 9e425df..0000000
--- a/examples/_unknown.scm
+++ /dev/null
@@ -1,153 +0,0 @@
-;; _unknown.scm -- An example for an `unknown' service.
-;; Copyright (C) 2003 Wolfgang Jährling <wolfgang@pro-linux.de>
-;;
-;; This file is part of the GNU Shepherd.
-;;
-;; The GNU Shepherd is free software; you can redistribute it and/or modify it
-;; under the terms of the GNU General Public License as published by
-;; the Free Software Foundation; either version 3 of the License, or (at
-;; your option) any later version.
-;;
-;; The GNU Shepherd is distributed in the hope that it will be useful, but
-;; WITHOUT ANY WARRANTY; without even the implied warranty of
-;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-;; GNU General Public License for more details.
-;;
-;; You should have received a copy of the GNU General Public License
-;; along with the GNU Shepherd. If not, see <http://www.gnu.org/licenses/>.
-
-;; Return true if STR1 lacks a character that exists in STR2, but
-;; otherwise both are identical.
-(define (lacks-char-from? str1 str2)
- (and (= (string-length str1)
- (+ (string-length str2) 1))
- (letrec ((next
- (lambda (pos)
- (and (not (= pos (string-length str1)))
- (or (string=? str2
- (string-append
- (substring str1 0 pos)
- (substring str1
- (+ pos 1)
- (string-length str1))))
- (next (+ pos 1)))))))
- (next 0))))
-
-;; Return true if either of STR1 and STR2 lacks a character found in
-;; the other one, but otherwise both are identical (e.g. as is the
-;; case for "blah" and "bla").
-(define (differs-by-missing-char? str1 str2)
- (or (lacks-char-from? str1 str2)
- (lacks-char-from? str2 str1)))
-
-;; Return true if the only difference between STR1 and STR2 is that a
-;; successive pair of characters is switched in one of them.
-(define (differs-by-switched-chars? str1 str2)
- (and (= (string-length str1)
- (string-length str2))
- (> (string-length str1) 1)
- (letrec ((next
- (lambda (pos)
- (and (not (= pos (string-length str1)))
- (or (string=? str2
- (string-append
- (substring str1 0 (- pos 1))
- (string (string-ref str1 pos)
- (string-ref str1 (- pos 1)))
- (substring str1
- (+ pos 1)
- (string-length str1))))
- (next (+ pos 1)))))))
- (next 1))))
-
-;; Return true if they differ by exactly one character (e.g. as is the
-;; case for "blah" and "bleh"), if it isn't the only one.
-(define (differs-by-one-char? str1 str2)
- (and (= (string-length str1)
- (string-length str2))
- (> (string-length str1) 1)
- (letrec ((next
- (lambda (pos found-difference)
- (if (= pos (string-length str1))
- found-difference
- (if (char=? (string-ref str1 pos)
- (string-ref str2 pos))
- (next (+ pos 1) found-difference)
- (and (not found-difference)
- (next (+ pos 1) #t)))))))
- (next 0 #f))))
-
-;; Return true if STR1 and STR2 are identical, except for case
-;; (e.g. this gives true for "foobar" and "FooBAR").
-(define (differs-only-in-case? str1 str2)
- (and (not (string=? str1 str2))
- (string-ci=? str1 str2)))
-
-;; Return true if STR1 and STR2 are `similar' strings, meaning that
-;; they only differ in a minor way.
-(define (similar? str1 str2)
- (any (lambda (pred?)
- (pred? str1 str2))
- (list differs-by-missing-char?
- differs-by-switched-chars?
- differs-by-one-char?
- differs-only-in-case?)))
-
-\f
-
-;; TODO
-;; - We could look for non-running services first on `start' etc.
-;; - We also should do `unknown-action' (if service is known)
-;; - If doing this, we should enable the service to handle it
-;; - Make this the `default unknown service'
-;; - Messages if nothing found.
-
-;; Suggest a service that satisfies PRED?, if given, and has a name
-;; similar to SERVICE-SYMBOL.
-(define look-for-service
- (case-lambda
- ((service-symbol) (look-for-service service-symbol (lambda (x) #t)))
- ((service-symbol pred?)
- (call/ec
- (lambda (return)
- (for-each-service
- (lambda (s)
- (and (pred? s)
- (similar? (symbol->string service-symbol)
- (symbol->string (canonical-name s)))
- (begin
- (format #t "Did you mean ~a maybe?" (canonical-name s))
- (newline)
- (return #t)))))
- #f)))))
-
-;; The classical compose.
-(define (compose f g)
- (lambda (x)
- (f (g x)))
-
-(define unknown-service
- (make <service>
- #:provides '(unknown)
- #:actions (make-actions
- (start
- "Called if user wants to start an unknown service."
- (lambda (running service-sym . args)
- (or (look-for-service service-sym (compose not running?))
- (look-for-service service-sym))
- running))
- (stop
- "Called if user wants to stop an unknown service."
- (lambda (running service-sym . args)
- (or (look-for-service service-sym running?)
- (look-for-service service-sym))
- running))
- (action
- "Called if user frobs an unknown service."
- (lambda (running service-sym the-action . args)
- (or (look-for-service service-sym running?)
- (look-for-service service-sym))
- running)))))
-
-(register-services unknown-service)
-(start unknown-service)
diff --git a/examples/wolfgangj.scm b/examples/wolfgangj.scm
deleted file mode 100644
index b01ddd0..0000000
--- a/examples/wolfgangj.scm
+++ /dev/null
@@ -1,132 +0,0 @@
-;; wolfgangj.scm -- Personal dmd configuration of Wolfgang Jährling.
-;; Copyright (C) 2002, 2003 Wolfgang Jährling <wolfgang@pro-linux.de>
-;;
-;; This file is part of the GNU Shepherd.
-;;
-;; The GNU Shepherd is free software; you can redistribute it and/or modify it
-;; under the terms of the GNU General Public License as published by
-;; the Free Software Foundation; either version 3 of the License, or (at
-;; your option) any later version.
-;;
-;; The GNU Shepherd is distributed in the hope that it will be useful, but
-;; WITHOUT ANY WARRANTY; without even the implied warranty of
-;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-;; GNU General Public License for more details.
-;;
-;; You should have received a copy of the GNU General Public License
-;; along with the GNU Shepherd. If not, see <http://www.gnu.org/licenses/>.
-
-\f
-
-;; A few notes about the computer this setup is for: It is a PC
-;; running Debian GNU/Linux 3.0, on which I am usually using screen,
-;; which is why I need few terminals. I am using it to connect to the
-;; internet via ISDN, but I'm also using it in my local network, in
-;; which case it is running Apache. Because I don't want to have
-;; Apache running when I am online, I made Apache conflict with the
-;; ISDN setup.
-
-;; Laziness.
-(define (number->symbol num)
- (string->symbol (number->string num)))
-
-;; Even more laziness.
-(define cat string-append)
-
-;; Some values for this system.
-(define getty "/sbin/getty")
-(define ifconfig "/sbin/ifconfig")
-(define isdnctrl "/usr/sbin/isdnctrl")
-
-(define inet-interface "ippp0")
-(define inet-dial (cat isdnctrl " dial " inet-interface))
-(define inet-hangup (cat isdnctrl " hangup " inet-interface))
-
-(define local-interface "eth0")
-(define local-ip "192.168.0.9")
-
-(define init.d-dir "/etc/init.d/")
-(define apache (cat init.d-dir "apache"))
-(define inet (cat init.d-dir "isdnutils"))
-(define exim (cat init.d-dir "exim"))
-
-;; Create a service providing a terminal.
-(define (make-term num)
- (let ((sym (symbol-append 'term- (number->symbol num))))
- (make <service>
- #:provides (list sym)
- #:respawn? #t
- #:start (make-forkexec-constructor getty "38400"
- (cat "tty" (number->string num)))
- #:stop-delay? #t)))
-
-;; Number of terminals created by default.
-(define default-terms 3)
-
-;; How many terms have been created with `add-new-term'.
-(define term-counter 0)
-
-;; Add a new terminal to the list of registered services.
-(define (add-new-term)
- (set! term-counter (+ term-counter 1))
- (register-services (make-term term-counter)))
-
-(register-services
- (make <service>
- #:provides '(term)
- #:actions (make-actions
- (create "Create a new terminal."
- (lambda (running)
- (add-new-term)))
- (counter-set "Set the terminal creation counter."
- (lambda (running num)
- (set! term-counter (string->number num))))
- (status "Display the terminal creation counter."
- (lambda (running)
- (local-output "Terminal counter is at ~a."
- term-counter)))))
- (make <service>
- #:provides '(apache insecurity)
- #:requires '(local-net)
- #:start (make-system-constructor apache " start")
- #:stop (make-system-destructor apache " stop"))
- (make <service>
- #:provides '(inet insecurity)
- #:start (make-system-constructor inet " start")
- #:stop (make-system-destructor inet " stop")
- #:actions (make-actions
- (dial "Connect to the big, evil internet."
- (lambda (running)
- (system inet-dial)
- #t))
- (hangup "Cut the internet connection."
- (lambda (running)
- (system inet-hangup)
- #t))))
- (make <service>
- #:provides '(local-net)
- #:start (make-system-constructor ifconfig " " local-interface " " local-ip)
- #:stop (make-system-destructor ifconfig " " local-interface " down"))
- (make <service>
- #:provides '(exim mailer-daemon)
- #:requires '(inet)
- #:start (make-system-constructor exim " start")
- #:stop (make-system-destructor exim " stop")))
-
-;; Create a few terminals.
-(letrec ((loop (lambda (i)
- (and (not (zero? i))
- (begin
- (add-new-term)
- (loop (- i 1)))))))
- (loop default-terms))
-
-;; Go into background.
-(action 'dmd 'daemonize)
-
-;; Setup internet, a mailer and a few terms.
-(for-each start
- (append '(term inet mailer-daemon)
- (map (lambda (x)
- (symbol-append 'term- (number->symbol x)))
- (iota default-terms 1))))
^ permalink raw reply related [flat|nested] 11+ messages in thread
* [Shepherd][PATCH 3/4] doc: Move manual to the 'doc' directory.
2016-01-27 20:45 [Shepherd][PATCH 0/4] Move documentation to a 'doc' directory Mathieu Lirzin
2016-01-27 20:45 ` [Shepherd][PATCH 1/4] build: Build Guile objects before generating man pages Mathieu Lirzin
2016-01-27 20:45 ` [Shepherd][PATCH 2/4] doc: Move examples to the 'doc/examples' directory Mathieu Lirzin
@ 2016-01-27 20:45 ` Mathieu Lirzin
2016-01-27 22:58 ` Ludovic Courtès
2016-01-27 20:45 ` [Shepherd][PATCH 4/4] doc: Move man pages " Mathieu Lirzin
3 siblings, 1 reply; 11+ messages in thread
From: Mathieu Lirzin @ 2016-01-27 20:45 UTC (permalink / raw)
To: guix-devel
[-- Attachment #1: Type: text/plain, Size: 784 bytes --]
* doc/shepherd.texi: Moved from the root directory.
* doc/fdl-1.3.texi: Likewise.
* Makefile.am (info_TEXINFOS): Add a 'doc/' prefix to 'shepherd.texi'.
(EXTRA_DIST): Remove 'fdl-1.3.texi'.
(doc_shepherd_TEXINFOS): New variable.
* .gitignore: Update it.
---
.gitignore | 49 +-
Makefile.am | 4 +-
doc/fdl-1.3.texi | 505 +++++++++++++++++
doc/shepherd.texi | 1593 +++++++++++++++++++++++++++++++++++++++++++++++++++++
fdl-1.3.texi | 505 -----------------
shepherd.texi | 1593 -----------------------------------------------------
6 files changed, 2125 insertions(+), 2124 deletions(-)
create mode 100644 doc/fdl-1.3.texi
create mode 100644 doc/shepherd.texi
delete mode 100644 fdl-1.3.texi
delete mode 100644 shepherd.texi
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0003-doc-Move-manual-to-the-doc-directory.patch --]
[-- Type: text/x-patch; name="0003-doc-Move-manual-to-the-doc-directory.patch", Size: 184093 bytes --]
diff --git a/.gitignore b/.gitignore
index 7cb94f2..111817f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,26 +1,29 @@
-/configure
-/shepherd.info
-/stamp-vti
-/version.texi
+*.go
+*~
+,*
+.dirstamp
+/*.1
+/*.8
+/INSTALL
+/aclocal.m4
+/autom4te.cache
+/build-aux/*
/config.cache
/config.log
/config.scm
/config.status
-/herd
-/shepherd
+/configure
+/doc/shepherd.info
+/doc/stamp-vti
+/doc/version.texi
/examples/Makefile
-/autom4te.cache
-/build-aux/*
-Makefile.in
-Makefile
-*~
-,*
+/halt
+/herd
/missing
-/texinfo.tex
-/INSTALL
-/aclocal.m4
-*.go
/modules/shepherd/config.scm
+/modules/shepherd/system.scm
+/reboot
+/shepherd
/shepherd.aux
/shepherd.cp
/shepherd.cps
@@ -28,28 +31,26 @@ Makefile
/shepherd.fns
/shepherd.ky
/shepherd.log
+/shepherd.pdf
/shepherd.pg
/shepherd.toc
/shepherd.tp
/shepherd.tps
/shepherd.vr
/shepherd.vrs
-/modules/shepherd/system.scm
-/halt
-/reboot
-/shepherd.pdf
/test-suite.log
/tests/basic.log
/tests/basic.trs
/tests/misbehaved-client.log
/tests/misbehaved-client.trs
-/tests/respawn.log
-/tests/respawn.trs
/tests/no-home.log
/tests/no-home.trs
+/tests/respawn.log
+/tests/respawn.trs
/tests/sigint.log
/tests/sigint.trs
/tests/status-sexp.log
/tests/status-sexp.trs
-/*.1
-/*.8
+/texinfo.tex
+Makefile
+Makefile.in
diff --git a/Makefile.am b/Makefile.am
index 2985a86..52f66d6 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -66,7 +66,8 @@ CLEANFILES = \
$(bin_SCRIPTS) $(sbin_SCRIPTS)
# Documentation.
-info_TEXINFOS = shepherd.texi
+info_TEXINFOS = doc/shepherd.texi
+doc_shepherd_TEXINFOS = doc/fdl-1.3.texi
AM_V_HELP2MAN = $(AM_V_HELP2MAN_$(V))
AM_V_HELP2MAN_ = $(AM_V_HELP2MAN_$(AM_DEFAULT_VERBOSITY))
@@ -98,7 +99,6 @@ dist_man8_MANS = halt.8 reboot.8
# Things not automatically included in the distribution.
EXTRA_DIST = \
ChangeLog-2003 \
- fdl-1.3.texi \
QUESTIONS \
$(templates) \
doc/examples/README \
diff --git a/doc/fdl-1.3.texi b/doc/fdl-1.3.texi
new file mode 100644
index 0000000..cb71f05
--- /dev/null
+++ b/doc/fdl-1.3.texi
@@ -0,0 +1,505 @@
+@c The GNU Free Documentation License.
+@center Version 1.3, 3 November 2008
+
+@c This file is intended to be included within another document,
+@c hence no sectioning command or @node.
+
+@display
+Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+@uref{http://fsf.org/}
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document @dfn{free} in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License. Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein. The ``Document'', below,
+refers to any such manual or work. Any member of the public is a
+licensee, and is addressed as ``you''. You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section
+of the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject. (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License. If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant. The Document may contain zero
+Invariant Sections. If the Document does not identify any Invariant
+Sections then there are none.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License. A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text. A copy that is not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, La@TeX{} input
+format, SGML or XML using a publicly available
+DTD, and standard-conforming simple HTML,
+PostScript or PDF designed for human modification. Examples
+of transparent image formats include PNG, XCF and
+JPG. Opaque formats include proprietary formats that can be
+read and edited only by proprietary word processors, SGML or
+XML for which the DTD and/or processing tools are
+not generally available, and the machine-generated HTML,
+PostScript or PDF produced by some word processors for
+output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+The ``publisher'' means any person or entity that distributes copies
+of the Document to the public.
+
+A section ``Entitled XYZ'' means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language. (Here XYZ stands for a
+specific section name mentioned below, such as ``Acknowledgements'',
+``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
+of such a section when you modify the Document means that it remains a
+section ``Entitled XYZ'' according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document. These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+@enumerate A
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has fewer than five),
+unless they release you from this requirement.
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section Entitled ``History'', Preserve its Title, and add
+to it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section Entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
+the Title of the section, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements and/or
+dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
+@item
+Delete any section Entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section to be Entitled ``Endorsements'' or
+to conflict in title with any Invariant Section.
+
+@item
+Preserve any Warranty Disclaimers.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled ``History''
+in the various original documents, forming one section Entitled
+``History''; likewise combine any sections Entitled ``Acknowledgements'',
+and any sections Entitled ``Dedications''. You must delete all
+sections Entitled ``Endorsements.''
+
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an ``aggregate'' if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers. In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled ``Acknowledgements'',
+``Dedications'', or ``History'', the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License. Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+@uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation. If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
+@item
+RELICENSING
+
+``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works. A
+public wiki that anybody can edit is an example of such a server. A
+``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
+site means any set of copyrightable works thus published on the MMC
+site.
+
+``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+``Incorporate'' means to publish or republish a Document, in whole or
+in part, as part of another Document.
+
+An MMC is ``eligible for relicensing'' if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole
+or in part into the MMC, (1) had no cover texts or invariant sections,
+and (2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
+@end enumerate
+
+@page
+@heading ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+ Copyright (C) @var{year} @var{your name}.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.3
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
+@end group
+@end smallexample
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the ``with@dots{}Texts.''@: line with this:
+
+@smallexample
+@group
+ with the Invariant Sections being @var{list their titles}, with
+ the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
+ being @var{list}.
+@end group
+@end smallexample
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End:
diff --git a/doc/shepherd.texi b/doc/shepherd.texi
new file mode 100644
index 0000000..5dc5f9c
--- /dev/null
+++ b/doc/shepherd.texi
@@ -0,0 +1,1593 @@
+\input texinfo @c -*- texinfo -*-
+@c shepherd.texi -- The documentation in Texinfo format.
+@documentencoding UTF-8
+@setfilename shepherd.info
+@settitle The GNU Shepherd Manual
+
+@include version.texi
+@set OLD-YEARS 2002, 2003
+@set NEW-YEARS 2013, 2016
+
+@copying
+Copyright @copyright{} @value{OLD-YEARS} Wolfgang J@"ahrling@*
+Copyright @copyright{} @value{NEW-YEARS} Ludovic Courtès
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
+copy of the license is included in the section entitled ``GNU Free
+Documentation License''.
+@end copying
+
+@dircategory System software
+@direntry
+* shepherd: (shepherd). The Shepherd service manager.
+* herd: (shepherd)Invoking herd
+ Controlling the Shepherd service manager.
+* reboot: (shepherd)Invoking reboot
+ Rebooting a Shepherd-controlled system.
+* halt: (shepherd)Invoking halt
+ Turning off a Shepherd-controlled system.
+@end direntry
+
+@titlepage
+@title The GNU Shepherd Manual
+@subtitle For use with the GNU Shepherd @value{VERSION}
+@subtitle Last updated @value{UPDATED}
+
+@author Wolfgang J@"ahrling
+@author Ludovic Courtès
+
+@insertcopying
+@end titlepage
+
+@contents
+
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@ifnottex
+@node Top
+@top The GNU Shepherd Manual
+
+This manual documents the GNU@tie{}Shepherd version @value{VERSION}, a
+service manager for the GNU system.
+
+@menu
+* Introduction:: Introduction to the Shepherd service manager.
+* Jump Start:: How to do simple things with the Shepherd.
+* herd and shepherd:: User interface to service management.
+* Services:: Details on services.
+* Runlevels:: Details on runlevels.
+* Misc Facilities:: Generally useful things provided by the Shepherd.
+* Internals:: Hacking shepherd.
+
+* GNU Free Documentation License:: The license of this manual.
+* Concept Index::
+* Procedure and Macro Index::
+* Variable Index::
+* Type Index::
+@end menu
+@end ifnottex
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Introduction
+@chapter Introduction
+
+@cindex service manager
+This manual documents the GNU@tie{}Daemon Shepherd, or GNU@tie{}Shepherd
+for short. The Shepherd looks after system services, typically @dfn{daemons}.
+It is used to start and stop them in a reliable
+fashion. For instance it will dynamically determine and start any
+other services that our desired service depends upon. As another
+example, the Shepherd might detect conflicts among services. In this
+situation it would simply prevent the conflicting services from
+running concurrently.
+
+The Shepherd is the @dfn{init system} of the GNU operating system---it is the
+first user process that gets started, typically with PID 1, and runs
+as @code{root}. Normally the purpose of init systems is to manage all
+system-wide services, but the Shepherd can also be a useful tool assisting
+unprivileged users in the management of their own daemons.
+
+Flexible software requires some time to master and
+the Shepherd is no different. But don't worry: this manual should allow you to
+get started quickly. Its first chapter is designed as a practical
+introduction to the Shepherd and should be all you need for everyday use
+(@pxref{Jump Start}). In chapter two we will describe the
+@command{herd} and @command{shepherd} programs, and their relationship, in
+more detail (@ref{herd and shepherd}). Subsequent chapters provide a full
+reference manual and plenty of examples, covering all of Shepherd's
+capabilities. Finally, the last chapter provides information for
+those souls brave enough to hack the Shepherd itself.
+
+@cindex dmd
+The Shepherd was formerly known as ``dmd'', which stands for @dfn{Daemon
+Managing Daemons} (or @dfn{Daemons-Managing Daemon}?).
+
+@cindex Guile
+@cindex Scheme
+@cindex GOOPS
+This program is written in Guile, an implementation of the
+Scheme programming language, using the GOOPS extension for
+object-orientation. Guile is also the Shepherd's configuration language.
+@xref{Introduction,,, guile, GNU Guile Reference Manual}, for an
+introduction to Guile. We have tried to
+make the Shepherd's basic features as accessible as possible---you should be
+able to use these even if you do not know how to program in Scheme. A
+basic grasp of Guile and GOOPS is required only if you wish to make
+use of the Shepherd's more advanced features.
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Jump Start
+@chapter Jump Start
+
+@cindex prefix
+This chapter gives a short overview of the Shepherd. It is enough if you just
+need the basic features of it. As it is not assumed that readers are
+familiar with all the involved issues, a very experienced user might
+be annoyed by the often very detailed descriptions in this
+introduction. Those users are encouraged to just skip to the
+reference section.
+
+Note that all the full file names in the following text are based on
+the assumption that you have installed the Shepherd with an empty prefix. If
+your the Shepherd installation for example resides in @code{/usr/local}
+instead, add this directory name in front of the absolute file names
+mentioned below.
+
+@cindex Configuration file
+When @command{shepherd} gets started, it reads and evaluates a
+configuration file. When it is started with superuser priviledges, it
+tries to use @code{/etc/shepherd.scm}. When started as normal user, it
+looks for a file called @code{$XDG_CONFIG_HOME/shepherd/init.scm}. If
+the @code{XDG_CONFIG_HOME} environment variable is not defined,
+@code{$HOME/.config/shepherd/init.scm} is used instead. With the option
+@code{--config} (or, for short, @code{-c}), you can specify where to
+look instead. So if you want to start @command{shepherd} with an
+alternative file, use one of the following commands:
+
+@example
+shepherd --config=/etc/shepherd.scm.old
+shepherd -c /etc/shepherd.scm.old
+@end example
+
+@cindex Starting a service
+As the final ``d'' suggests, @command{shepherd} is just
+a daemon that (usually) runs in the
+background, so you will not interact with it directly. After it is
+started, @command{shepherd} will listen on a socket special file, usually
+@code{/var/run/shepherd/socket}, for further commands. You use the tool
+@dfn{herd} to send these commands to @command{shepherd}. Usage of herd is simple and
+straightforward: To start a service called @code{apache}, you use:
+
+@example
+herd start apache
+@end example
+
+@cindex Status (of services)
+@cindex Service status
+When you do this, all its dependencies will get resolved. For
+example, a webserver is quite likely to depend on working networking,
+thus it will depend on a service called @code{networking}. So if you
+want to start @code{apache}, and @code{networking} is not yet running, it
+will automatically be started as well. The current status of all the
+services defined in the configuration file can be queried like this:
+
+@example
+herd status
+@end example
+
+@noindent
+Or, to get additional details about each service, run:
+
+@example
+herd detailed-status
+@end example
+
+@noindent
+In this example, this would show the @code{networking} and @code{apache}
+services as started. If you just want to know the status of the
+@code{apache} service, run:
+
+@example
+herd status apache
+@end example
+
+@cindex Stopping a service
+You can stop
+a service and all the services that depend on it will be stopped.
+Using the example above, if you stop @code{networking}, the service
+@code{apache} will be stopped as well---which makes perfect sense,
+as it cannot work without the network being up. To actually stop a
+service, you use the following, probably not very surprising, command:
+
+@example
+herd stop networking
+@end example
+
+There are two more actions you can perform on every service: The
+actions @code{enable} and @code{disable} are used to prevent and allow
+starting of the particular service. If a service is intended to be
+restarted whenever it terminates (how this can be done will not be
+covered in this introduction), but it is respawning too often in a
+short period of time (by default 5 times in 5 seconds), it will
+automatically be disabled. After you have fixed the problem that
+caused it from being respawned too fast, you can start it again with
+the commands:
+
+@example
+herd enable foo
+herd start foo
+@end example
+
+@cindex virtual services
+@cindex fallback services
+But there is far more you can do than just that. Services can not
+only simply depend on other services, they can also depend on
+@emph{virtual} services. A virtual service is a service that is
+provided by one or more service additionally. For instance, a service
+called @code{exim} might provide the virtual service
+@code{mailer-daemon}. That could as well be provided by a service
+called @code{smail}, as both are mailer-daemons. If a service needs
+any mailer-daemon, no matter which one, it can just depend on
+@code{mailer-daemon}, and one of those who provide it gets started (if
+none is running yet) when resolving dependencies. The nice thing is
+that, if trying to start one of them fails, @command{shepherd} will go on and try to
+start the next one, so you can also use virtual services for
+specifying @emph{fallbacks}.
+
+Additionally to all that, you can perform service-specific actions.
+Coming back to our original example, @code{apache} is able to
+reload its modules, therefore the action @code{reload-modules} might
+be available:
+
+@example
+herd reload-modules apache
+@end example
+
+The service-specific actions can only be used when the service is
+started, i.e. the only thing you can do to a stopped service is
+starting it. An exception exists, see below. (If you may at some
+point find this too restrictive because you want to use variants of
+the same service which are started in different ways, consider using
+different services for those variants instead, which all provide the
+same virtual service and thus conflict with each other, if this is
+desired. That's one of the reasons why virtual services exist, after
+all.)
+
+There are two actions which are special, because even if services
+can implement them on their own, a default implementation is provided
+by @command{shepherd} (another reason why they are special is that the default
+implementations can be called even when the service is not running;
+this inconsistency is just to make it more intuitive to get
+information about the status of a service, see below).
+
+These actions are @code{restart} and @code{status}. The default
+implementation of @code{restart} calls @code{stop} and @code{start} on
+the affected service in order, the @code{status} action displays some
+general information about the service, like what it provides, what it
+depends on and with which other services it conflicts (because they
+provide a virtual service that is also provided by that particular
+service).
+
+Another special action is @code{list-actions}, which displays a list
+of the additional actions a service provides; obviously, it can also
+be called when the service is not running. Services cannot provide
+their own implementation of @code{list-actions}.
+
+A special service is @code{root}, which is used for controlling the
+Shepherd itself. You can also reference to this service as
+@code{shepherd}. It implements various actions. For example, the
+@code{status} action displays which services are started and which ones
+are stopped, whereas @code{detailed-status} has the effect of applying
+the default implementation of @code{status} to all services one after
+another. The @code{load} action is unusual insofar as it shows a
+feature that is actually available to all services, but which we have
+not seen yet: It takes an additional argument. You can use @code{load}
+to load arbitrary code into the Shepherd at runtime, like this:
+
+@example
+herd load shepherd ~/additional-services.scm
+@end example
+
+This is enough now about the @command{herd} and @command{shepherd} programs, we
+will now take a look at how to configure the Shepherd. In the configuration
+file, we need mainly the definition of services. We can also do
+various other things there, like starting a few services already.
+
+FIXME: Finish. For now, look at the @code{examples/} subdirectory.
+
+@example
+...
+@end example
+
+Ok, to summarize:
+
+@itemize @bullet
+@item
+@command{shepherd} is a daemon, @command{herd} the program that controls it.
+@item
+You can start, stop, restart, enable and disable every service, as
+well as display its status.
+@item
+You can perform additional service-specific actions, which you can
+also list.
+@item
+Actions can have arguments.
+@item
+You can display the status of a service, even if the service does not
+provide a specific implementation for this action. The same is true
+for restarting.
+@item
+The @code{root}/@code{shepherd} service is used to control
+@command{shepherd} itself.
+@end itemize
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node herd and shepherd
+@chapter @command{herd} and @command{shepherd}
+
+@cindex herd
+@cindex shepherd
+@cindex daemon
+@cindex daemon controller
+@cindex relative file names
+@cindex herding, of daemons
+The daemon that runs in the background and is responsible for
+controlling the services is @command{shepherd}, while the user interface
+tool is called @command{herd}: it's the command that allows you to
+actually @emph{herd} your daemons@footnote{
+@cindex deco, daemon controller
+In the past, when the
+GNU@tie{}Shepherd was known as GNU@tie{}dmd, the @command{herd} command
+was called @code{deco}, for @dfn{DaEmon COntroller}.}. To perform an
+action, like stopping a service or calling an action of a service, you
+use the herd program. It will communicate with shepherd over a Unix
+Domain Socket.
+
+Thus, you start @command{shepherd} once, and then always use herd whenever you want
+to do something service-related. Since herd passes its current
+working directory to @command{shepherd}, you can pass relative file names without
+trouble. Both @command{shepherd} and herd understand the standard arguments
+@code{--help}, @code{--version} and @code{--usage}.
+
+
+@menu
+* Invoking shepherd:: How to start the service damon.
+* Invoking herd:: Controlling daemons.
+* Invoking reboot:: Rebooting a shepherd-controlled system.
+* Invoking halt:: Turning off a shepherd-controlled system.
+@end menu
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Invoking shepherd
+@section Invoking @command{shepherd}
+
+@cindex @command{shepherd} Invocation
+@cindex invoking @command{shepherd}
+The @code{shepherd} program has the following synopsis:
+
+@example
+shepherd [@var{option}@dots{}]
+@end example
+
+It accepts the following options:
+
+@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}).
+
+@item -I
+@itemx --insecure
+@cindex security
+@cindex insecure
+Do not check if the directory where the socket---our communication
+rendez-vous with @command{herd}---is located has permissions @code{700}.
+If this option is not specified, @command{shepherd} will abort if the
+permissions are not as expected.
+
+@item -l [@var{file}]
+@itemx --logfile[=@var{file}]
+@cindex logging
+@cindex log file
+Log output into @var{file}, or if @var{file} is not given,
+@code{/var/log/shepherd.log} when running as superuser,
+@code{$XDG_CONFIG_HOME/shepherd/shepherd.log} otherwise.
+
+@item --pid[=@var{file}]
+When @command{shepherd} is ready to accept connections, write its PID to @var{file} or
+to the standard output if @var{file} is omitted.
+
+@item -p [@var{file}]
+@itemx --persistency[=@var{file}]
+@c FIXME-CRITICAL
+
+@item -s @var{file}
+@itemx --socket=@var{file}
+@cindex socket special file
+Receive further commands on the socket special file @var{file}. If
+this option is not specified, @file{@var{localstatedir}/run/shepherd/socket} is
+taken.
+
+If @code{-} is specified as file name, commands will be read from
+standard input, one per line, as would be passed on a @command{herd}
+command line (@pxref{Invoking herd}).
+
+@item --quiet
+Synonym for @code{--silent}.
+
+@end table
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Invoking herd
+@section Invoking herd
+
+@cindex herd
+The @command{herd} command is a generic client program to control a
+running instance of @command{shepherd} (@pxref{Invoking shepherd}). It has the
+following synopsis:
+
+@example
+herd [@var{option}@dots{}] @var{action} [@var{service} [@var{arg}@dots{}]]
+@end example
+
+It causes the @var{action} of the @var{service} to be invoked. When
+@var{service} is omitted and @var{action} is @code{status} or
+@code{detailed-status}, the @code{root} service is used@footnote{This
+shorthand does not work for other actions such as @code{stop}, because
+inadvertently typing @code{herd stop} would stop all the services, which
+could be pretty annoying.} (@pxref{The root and unknown services}, for
+more information on the @code{root} service.)
+
+For each action, you should pass the appropriate @var{arg}s. Actions
+that are available for every service are @code{start}, @code{stop},
+@code{restart}, @code{status}, @code{enable}, @code{disable}, and
+@code{doc}.
+
+If you pass a file name as an @var{arg}, it will be passed as-is to
+the Shepherd, thus if it is not an absolute name, it is local to the current
+working directory of @command{shepherd}, not to herd.
+
+The @code{herd} command understands the following option:
+
+@table @samp
+
+@item -s @var{file}
+@itemx --socket=@var{file}
+Send commands to the socket special file @var{file}. If this option is
+not specified, @file{@var{localstatedir}/run/shepherd/socket} is taken.
+
+@end table
+
+The @code{herd} command returns zero on success, and a non-zero exit
+code on failure. In particular, it returns a non-zero exit code when
+@var{action} or @var{service} does not exist and when the given action
+failed.
+
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Invoking reboot
+@section Invoking reboot
+
+@cindex herd
+The @command{reboot} command is a convenience client program to instruct
+the Shepherd (when used as an init system) to stop all running services and
+reboot the system. It has the following synopsis:
+
+@example
+reboot [@var{option}@dots{}]
+@end example
+
+It is equivalent to running @command{herd stop shepherd}. The
+@code{reboot} command understands the following option:
+
+@table @samp
+
+@item -s @var{file}
+@itemx --socket=@var{file}
+Send commands to the socket special file @var{file}. If this option is
+not specified, @file{@var{localstatedir}/run/shepherd/socket} is taken.
+
+@end table
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Invoking halt
+@section Invoking halt
+
+@cindex herd
+The @command{halt} command is a convenience client program to instruct
+the Shepherd (when used as an init system) to stop all running services and turn
+off the system. It has the following synopsis:
+
+@example
+halt [@var{option}@dots{}]
+@end example
+
+It is equivalent to running @command{herd power-off shepherd}. As
+usual, the @code{halt} command understands the following option:
+
+@table @samp
+
+@item -s @var{file}
+@itemx --socket=@var{file}
+Send commands to the socket special file @var{file}. If this option is
+not specified, @file{@var{localstatedir}/run/shepherd/socket} is taken.
+
+@end table
+
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Services
+@chapter Services
+
+@cindex service
+@tindex <service>
+The @dfn{service} is obviously a very important concept of the Shepherd. On the
+Guile level, a service is represented as an instance of
+@code{<service>}, a GOOPS class (@pxref{GOOPS,,, guile, GNU Guile
+Reference Manual}). When creating an instance of it, you can specify
+the initial values of its slots, and you actually must do this for some
+of the slots.
+
+The @code{<service>} class and its associated procedures and methods are
+defined in the @code{(shepherd service)} module.
+
+@menu
+* Slots of services:: What a <service> object consists of.
+* Methods of services:: What you can do with a <service> object.
+* Service Convenience:: How to conveniently work with services.
+* Service De- and Constructors:: Commonly used ways of starting and
+ stopping services.
+* Service Examples:: Examples that show how services are used.
+* The root and unknown services:: Special services in the Shepherd.
+@end menu
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Slots of services
+@section Slots of services
+
+@cindex <service>, slots of
+@cindex slots of <service>
+A service has the following slots, all of which can be initialized
+with a keyword (i.e. @code{#:provides}, used when creating the object)
+of the same name, except where stated otherwise. You should not
+access them directly with @code{slot-ref} or @code{slot-set!}
+usually, use the methods of the service class @ref{Methods of
+services} instead.
+
+@itemize @bullet
+@item
+@vindex provides (slot of <service>)
+@cindex canonical names of services
+@code{provides} is a list of symbols that are provided by the service.
+A symbol can only be provided by one service running at a time,
+i.e. if two services provide the same symbol, only one of them can
+run, starting the other one will fail. Therefore, these symbols are
+mainly used to denote conflicting services. The first symbol in the
+list is the canonical name for the service, thus it must be unique.
+This slot has no default value and must therefore be initialized.
+
+@item
+@vindex requires (slot of <service>)
+@code{requires} is, like @code{provides}, a list of symbols that
+specify services. In this case, they name what this service depends
+on, i.e. before the service can be started, services that provide
+those symbols must be started. If a required symbol is provided by
+several services, one will be started. By default, this slot
+contains the empty list.
+
+@item
+@vindex running (slot of <service>)
+@cindex Hook for individual services
+@code{running} is a hook that can be used by each service in its own
+way. The default value is @code{#f}, which indicates that the service
+is not running. When an attempt is made to start the service, it will
+be set to the return value of the procedure in the @code{start} slot.
+It will also be passed as an argument to the procedure in the
+@code{stop} slot. This slot can not be initialized with a keyword.
+
+@item
+@vindex respawn? (slot of <service>)
+@cindex Respawning services
+@code{respawn?} specifies whether the service should be respawned by
+the Shepherd. If this slot has the value @code{#t}, then assume the
+@code{running} slot specifies a child process PID and restart the
+service if that process terminates. Otherwise this slot is @code{#f},
+which is the default. See also the @code{last-respawns} slot.
+
+@item
+@vindex start (slot of <service>)
+@cindex Starting a service
+@cindex Service constructor
+@code{start} contains the ``constructor'' for the service, which will
+be called to start the service. (Therefore, it is not a constructor
+in the sense that it initializes the slots of a @code{<service>}
+object.) This must be a procedure that accepts any amount of
+arguments, which will be the additional arguments supplied by the
+user. If the starting attempt failed, it must return @code{#f}. The
+value will be stored in the @code{running} slot. The default value is
+a procedure that returns @code{#t} and performs no further actions,
+therefore it is desirable to specify a different one usually.
+
+@item
+@vindex stop (slot of <service>)
+@cindex Stoping a service
+@cindex Service destructor
+@code{stop} is, similar to @code{start}, a slot containing a
+procedure. But in this case, it gets the current value of the
+@code{running} slot as first argument and the user-supplied arguments
+as further arguments; it gets called to stop the service. Its return
+value will again be stored in the @code{running} slot, so that it
+should return @code{#f} if it is now possible again to start the
+service at a later point. The default value is a procedure that
+returns @code{#f} and performs no further actions.
+
+@item
+@vindex actions (slot of <service>)
+@cindex Actions of services
+@cindex Service actions
+@code{actions} specifies the additional actions that can be performed
+on a service when it is running. A typical example for this is the
+@code{restart} action. The macro @code{make-actions} @ref{Service
+Convenience} is provided to abstract the actual data representation
+format for this slot. (It actually is a hash currently.)
+
+@item
+@vindex enabled? (slot of <service>)
+@code{enabled?} cannot be initialized with a keyword, and contains
+@code{#t} by default. When the value becomes @code{#f} at some point,
+this will prevent the service from getting started. A service can be
+enabled and disabled with the methods @code{enable} and
+@code{disable}, respectively @ref{Methods of services}.
+
+@item
+@vindex last-respawns (slot of <service>)
+@code{last-respawns} cannot be initialized with a keyword and is only
+ever used when the @code{respawn?} slot contains @code{#t}; it is a
+circular list with @code{(car respawn-limit)} elements, where each
+element contains the time when it was restarted, initially all 0,
+later a time in seconds since the Epoch. The first element is the one
+that contains the oldest one, the last one the newest.
+
+@item
+@vindex stop-delay? (slot of <service>)
+@code{stop-delay?} being false causes the @code{stop} slot to be
+unused; instead, stopping the service will just cause the
+@code{waiting-for-termination?} slot be set to @code{#t}.
+
+@item
+@vindex waiting-for-termination? (slot of <service>)
+@code{waiting-for-termination?} cannot be initialized with a keyword
+and should not be used by others, it is only used internally for
+respawnable services when the @code{stop-delay?} slot contains a true
+value. @code{waiting-for-termination?} contains @code{#t} if the
+service is still running, but the user requested that it be stopped,
+in which case if the service terminates the next time, the respawn
+handler will not start it again.
+
+otherwise @code{#f}.
+
+@end itemize
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Methods of services
+@section Methods of services
+
+@deffn {method} start (obj <service>)
+Start the service @var{obj}, including all the services it depends on.
+It tries quite hard to do this: When a service that provides a
+required symbol can not be started, it will look for another service
+that also provides this symbol, until starting one such service
+succeeds. There is some room for theoretical improvement here, of
+course, but in pratice the current strategy already works very well.
+This method returns the new value of the @code{running} slot
+@ref{Slots of services}, which is @code{#f} if the service could not
+be started.
+@end deffn
+
+@deffn {method} stop (obj <service>)
+This will stop the service @var{obj}, trying to stop services that
+depend in it first, so they can be shutdown cleanly. If this will
+fail, it will continue anyway. Stopping of services should usually
+succeed, though. Otherwise, the behaviour is very similar to the
+@code{start} method. The return value is also the new @code{running}
+value, thus @code{#f} if the service was stopped.
+@end deffn
+
+@deffn {method} action (obj <service>) the-action . args
+Calls the action @var{the-action} (a symbol) of the service @var{obj},
+with the specified @var{args}, which have a meaning depending on the
+particular action.
+@end deffn
+
+@deffn {method} conflicts-with (obj <service>)
+Returns a list of the canonical names of services that conflict with
+the service @var{obj}.
+@end deffn
+
+@deffn {method} canonical-name (obj <service>)
+Returns the canonical name of @var{obj}, which is the first element of
+the @code{provides} list.
+@end deffn
+
+@deffn {method} provided-by (obj <service>)
+Returns which symbols are provided by @var{obj}.
+@end deffn
+
+@deffn {method} required-by (obj <service>)
+Returns which symbols are required by @var{obj}.
+@end deffn
+
+@deffn {method} running? (obj <service>)
+Returns whether the service @var{obj} is running.
+@end deffn
+
+@deffn {method} respawn? (obj <service>)
+Returns whether the service @var{obj} should be respawned if it
+terminates.
+@end deffn
+
+@deffn {method} default-display-status (obj <service>)
+Display status information about @var{obj}. This method is called
+when the user performs the action @code{status} on @var{obj}, but
+there is no specific implementation given for it. It is also called
+when @code{detailed-status} is applied on the @code{root} service.
+@end deffn
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Service Convenience
+@section Service Convenience
+
+In addition to the facilities listed below, there are also some
+procedures that provide commonly needed constructors and destructors
+for services @ref{Service De- and Constructors}.
+
+@deffn {procedure} register-services . services
+Register all @var{services}, so that they can be taken into account
+when trying to resolve dependencies.
+@end deffn
+
+@deffn {procedure} lookup-services name
+Return a list of all registered services which provide the symbol
+@var{name}.
+@end deffn
+
+@deffn {macro} make-actions (name proc) ...
+This macro is used to create a value for the @code{actions} slot of a
+service object @ref{Slots of services}. Each @var{name} is a symbol
+and each @var{proc} the corresponding procedure that will be called to
+perform the action. A @var{proc} has one argument, which will be the
+current value of the @code{running} slot of the service.
+@end deffn
+
+@deffn {method} start (obj <symbol>)
+Start a registered service providing @var{obj}.
+@end deffn
+
+@deffn {method} stop (obj <symbol>)
+Stop a registered service providing @var{obj}.
+@end deffn
+
+@deffn {method} action (obj <symbol>) the-action . args
+The same as the @code{action} method of class @code{<service>}, but
+uses a service that provides @var{obj} and is running.
+@end deffn
+
+@deffn {procedure} for-each-service proc
+Call @var{proc}, a procedure taking one argument, once for each
+registered service.
+@end deffn
+
+@deffn {procedure} find-running services
+Check if any of @var{services} is running. If this is the case,
+return its canonical name. If not, return @code{#f}. Only the first
+one will be returned; this is because this is mainly intended to be
+applied on the return value of @code{lookup-services}.
+@end deffn
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Service De- and Constructors
+@section Service De- and Constructors
+
+@cindex generating constructors
+@cindex generating destructors
+@cindex constructors, generation of
+@cindex destructors, generation of
+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] @
+ [#:pid-file #f] @
+ [#:directory (default-service-directory)] @
+ [#:environment-variables (default-environment-variables)]
+Return a procedure that forks a child process, closes all file
+descriptors except the standard output and standard error descriptors, sets
+the current directory to @var{directory}, changes the environment to
+@var{environment-variables} (using the @code{environ} procedure), sets the
+current user to @var{user} and the current group to @var{group} unless they
+are @code{#f}, and executes @var{command} (a list of strings.) The result of
+the procedure will be the PID of the child process.
+
+When @var{pid-file} is true, it must be the name of a PID file
+associated with the process being launched; the return value is the PID
+read from that file, once that file has been created.
+@end deffn
+
+@deffn {procedure} make-kill-destructor [@var{signal}]
+Returns a procedure that sends @var{signal} to the pid which it takes
+as argument. This @emph{does} work together with respawning services,
+because in that case the @code{stop} method of the @code{<service>}
+class sets the @code{running} slot to @code{#f} before actually
+calling the destructor; if it would not do that, killing the process
+in the destructor would immediately respawn the service.
+@end deffn
+
+The @code{make-forkexec-constructor} procedure builds upon the following
+procedures.
+
+@deffn {procedure} exec-command @var{command} @
+ [#:user #f] @
+ [#:group #f] @
+ [#:directory (default-service-directory)] @
+ [#:environment-variables (default-environment-variables)]
+@deffnx {procedure} fork+exec-command @var{command} @
+ [#:user #f] @
+ [#:group #f] @
+ [#:directory (default-service-directory)] @
+ [#:environment-variables (default-environment-variables)]
+Run @var{command} as the current process from @var{directory}, and with
+@var{environment-variables} (a list of strings like @code{"PATH=/bin"}.)
+File descriptors 1 and 2 are kept as is, whereas file descriptor 0
+(standard input) points to @file{/dev/null}; all other file descriptors
+are closed prior to yielding control to @var{command}.
+
+By default, @var{command} is run as the current user. If the
+@var{user} keyword argument is present and not false, change to
+@var{user} immediately before invoking @var{command}. @var{user} may
+be a string, indicating a user name, or a number, indicating a user
+ID. Likewise, @var{command} will be run under the current group,
+unless the @var{group} keyword argument is present and not false.
+
+@code{fork+exec-command} does the same as @code{exec-command}, but in
+a separate process whose PID it returns.
+@end deffn
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Service Examples
+@section Service Examples
+
+FIXME: This needs a lot of work.
+
+You can create a service and then register it this way:
+
+@lisp
+(define apache (make <service>
+ #:provides '(apache)
+ #:start (...)
+ #:stop (...)))
+(register-services apache)
+@end lisp
+
+However, as you usually won't need a variable for the service, you can
+pass it directly to @code{register-services}. Here is an example that
+also specifies some more initial values for the slots:
+
+@lisp
+(register-services
+ (make <service>
+ #:provides '(apache-2.0 apache httpd)
+ #:requires '()
+ #:start (...)
+ #:stop (...)
+ #:actions (make-actions
+ (reload-modules (...))
+ (restart (...)))))
+@end lisp
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node The root and unknown services
+@section The @code{root} and @code{unknown} services
+
+@cindex root service
+@cindex special services
+The service @code{root} is special, because it is used to control the
+Shepherd itself. It has an alias @code{shepherd}. It provides the
+following actions (in addition to @code{enable}, @code{disable} and
+@code{restart} which do not make sense here).
+
+@table @code
+@item status
+Displays which services are started and which ones are not.
+
+@item detailed-status
+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{--config} option of @command{shepherd} (@pxref{Invoking shepherd}).
+
+@item unload @var{service-name}
+Attempt to remove the service identified by @var{service-name}.
+@command{shepherd} will first stop the service, if necessary, and then
+remove it from the list of registered services. Any services
+depending upon @var{service-name} will be stopped as part of this
+process.
+
+If @var{service-name} simply does not exist, output a warning and do
+nothing. If it exists, but is provided by several services, output a
+warning and do nothing. This latter case might occur for instance with
+the fictional service @code{web-server}, which might be provided by both
+@code{apache} and @code{nginx}. If @var{service-name} is the special
+string and @code{all}, attempt to remove all services except for the Shepherd
+itself.
+
+@item reload @var{file-name}
+Unload all known optional services using unload's @code{all} option,
+then load @var{file-name} using @code{load} functionality. If
+file-name does not exist or @code{load} encounters an error, you may
+end up with no defined services. As these can be reloaded at a later
+stage this is not considered a problem. If the @code{unload} stage
+fails, @code{reload} will not attempt to load @var{file-name}.
+
+@item daemonize
+Fork and go into the background. This should be called before
+respawnable services are started, as otherwise we would not get the
+@code{SIGCHLD} signals when they terminate.
+
+@item enable-persistency
+When terminating, safe the list of running services in a file.
+@c FIXME-CRITICAL: How can we specify which one?
+
+@item disable-persistency
+Don't safe the list of running services when terminating.
+
+@end table
+
+@cindex unknown service
+@cindex fallback service
+The @code{unknown} service must be defined by the user and if it
+exists, is used as a fallback whenever we try to invoke an unknown
+action of an existing service or use a service that does not exist.
+This is useful only in few cases, but enables you to do various sorts
+of unusual things.
+
+@c FIXME-CRITICAL: finish
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Runlevels
+@chapter Runlevels
+
+RUNLEVELS DO NOT WORK YET! Do not use them! Ignore this section!
+
+@cindex runlevel
+@tindex <runlevel>
+A @dfn{runlevel} makes it easier to start and stop groups of services,
+to bring the system into a certain state. An object of class
+@code{<runlevel>} is an abstract runlevel, and has the following
+methods:
+
+@deffn {method} enter (rl <runlevel>) services
+This will be called when the runlevel should be entered.
+@var{services} is the list of the currently running services.
+@end deffn
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Misc Facilities
+@chapter Misc Facilities
+
+This is a list of facilities which are available to code running
+inside of the Shepherd and is considered generally useful, but is not directly
+related to one of the other topic covered in this manual.
+
+@menu
+* Errors:: Signalling, handling and ignoring errors.
+* Communication:: Input/Output in various ways.
+* Others:: Stuff that is useful, but is homeless.
+@end menu
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Errors
+@section Errors
+
+@cindex assertions
+@deffn {macro} assert expr
+If @var{expr} yields @code{#f}, display an appropriate error
+message and throw an @code{assertion-failed} exception.
+@end deffn
+
+@deffn {procedure} caught-error key args
+Tell the Shepherd that a @var{key} error with @var{args} has occured. This is
+the simplest way to cause caught error result in uniformly formated
+warning messages. The current implementation is not very good,
+though.
+@end deffn
+
+@deffn {procedure} call/cc proc
+An alias for @code{call-with-current-continuation}.
+@end deffn
+
+@deffn {procedure} call/ec proc
+A simplistic implementation of the nonstandard, but popular procedure
+@code{call-with-escape-continuation}, i.e. a @code{call/cc} for
+outgoing continuations only. Note that the variant included in the Shepherd is
+not aware of @code{dynamic-wind} at all and does not yet support
+returning multiple values.
+@end deffn
+
+@cindex system errors
+@deffn {macro} without-system-error expr@dots{}
+Evaluates the @var{expr}s, not going further if a system error occurs,
+but also doing nothing about it.
+@end deffn
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Communication
+@section Communication
+
+The @code{(shepherd comm)} module provides primitives that allow clients such
+as @command{herd} to connect to @command{shepherd} and send it commands to
+control or change its behavior (@pxref{Slots of services, actions of
+services}).
+
+@tindex <shepherd-command>
+Currently, clients may only send @dfn{commands}, represented by the
+@code{<shepherd-command>} type. Each command specifies a service it
+applies to, an action name, a list of strings to be used as arguments,
+and a working directory. Commands are instantiated with
+@code{shepherd-command}:
+
+@deffn {procedure} shepherd-command @var{action} @var{service} @
+ [#:@var{arguments} '()] [#:@var{directory} (getcwd)]
+Return a new command (a @code{<shepherd-command>}) object for
+@var{action} on @var{service}.
+@end deffn
+
+@noindent
+Commands may then be written to or read from a communication channel
+with the following procedures:
+
+@deffn {procedure} write-command @var{command} @var{port}
+Write @var{command} to @var{port}.
+@end deffn
+
+@deffn {procedure} read-command @var{port}
+Receive a command from @var{port} and return it.
+@end deffn
+
+In practice, communication with @command{shepherd} takes place over a
+Unix-domain socket, as discussed earlier (@pxref{Invoking shepherd}).
+Clients may open a connection with the procedure below.
+
+@deffn {procedure} open-connection [@var{file}]
+Open a connection to the daemon, using the Unix-domain socket at
+@var{file}, and return the socket.
+
+When @var{file} is omitted, the default socket is used.
+@end deffn
+
+@cindex output
+The daemon writes output to be logged or passed to the
+currently-connected client using @code{local-output}:
+
+@deffn {procedure} local-output format-string . args
+This procedure should be used for all output operations in the Shepherd. It
+outputs the @var{args} according to the @var{format-string}, then
+inserts a newline. It writes to whatever is the main output target of
+the Shepherd, which might be multiple at the same time in future versions.
+@end deffn
+
+@cindex protocol, between @command{shepherd} and its clients
+Under the hood, @code{write-command} and @code{read-command} write/read
+commands as s-expressions (sexps). Each sexp is intelligible and
+specifies a protocol version. The idea is that users can write their
+own clients rather than having to invoke @command{herd}. For instance,
+when you type @command{herd status}, what is sent over the wire is the
+following sexp:
+
+@lisp
+(shepherd-command
+ (version 0)
+ (action status) (service root)
+ (arguments ()) (directory "/data/src/dmd"))
+@end lisp
+
+The reply is also an sexp, along these lines:
+
+@lisp
+(reply (version 0)
+ (result (((service @dots{}) @dots{})))
+ (error #f) (messages ()))
+@end lisp
+
+This reply indicates that the @code{status} action was successful,
+because @code{error} is @code{#f}, and gives a list of sexps denoting
+the status of services as its @code{result}. The @code{messages} field
+is a possibly-empty list of strings meant to be displayed as is to the
+user.
+
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Others
+@section Others
+
+@cindex hashes
+@deffn {procedure} copy-hashq-table table new-size
+Create a hash-table with size @var{new-size}, and insert all values
+from @var{table} into it, using @code{eq?} when inserting. This
+procedure is mainly used internally, but is a generally useful
+utillity, so it can by used by everyone.
+@end deffn
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Internals
+@chapter Internals
+
+This chapter contains information about the design and the
+implementation details of the Shepherd for people who want to hack it.
+
+The GNU@tie{}Shepherd is developed by a group of people in connection
+with @uref{https://www.gnu.org/software/guix/, GuixSD}, GNU's advanced
+distribution, but it can be used on other distros as well. You're very
+much welcome to join us! You can report bugs to
+@email{bug-guix@@gnu.org} and send patches or suggestions to
+@email{guix-devel@@gnu.org}.
+
+@menu
+* Coding standards:: How to properly hack the Shepherd.
+* Design decisions:: Why the Shepherd is what it is.
+* Service Internals:: How services actually work.
+* Runlevel evolution:: Learning from past mistakes.
+@end menu
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Coding standards
+@section Coding standards
+
+About formatting: Use common sense and GNU Emacs (which actually is
+the same, of course), and you almost can't get the formatting wrong.
+Formatting should be as in Guile and Guix, basically. @xref{Coding
+Style,,, guix, GNU Guix Reference Manual}, for more info.
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Design decisions
+@section Design decisions
+
+@quotation Note
+This section was written by Wolfgang Jährling back in 2003 and documents
+the original design of what was then known as GNU@tie{}dmd. The main
+ideas remain valid but some implementation details and goals have
+changed.
+@end quotation
+
+The general idea of a service manager that uses dependencies, similar
+to those of a Makefile, came from the developers of the GNU Hurd, but
+as few people are satisfied with System V Init, many other people had
+the same idea independently. Nevertheless, the Shepherd was written with the
+goal of becoming a replacement for System V Init on GNU/Hurd, which
+was one of the reasons for choosing the extension language of the GNU
+project, Guile, for implementation (another reason being that it makes
+it just so much easier).
+
+The runlevel concept (i.e. thinking in @emph{groups} of services) is
+sometimes useful, but often one also wants to operate on single
+services. System V Init makes this hard: While you can start and stop
+a service, @code{init} will not know about it, and use the runlevel
+configuration as its source of information, opening the door for
+inconsistencies (which fortunatly are not a practical problem
+usually). In the Shepherd, this was avoided by having a central entity that is
+responsible for starting and stopping the services, which therefore
+knows which services are actually started (if not completely
+inproperly used, but that is a requirement which is impossible to
+avoid anyway). While runlevels are not implemented yet, it is clear
+that they will sit on top of the service concept, i.e. runlevels will
+merely be an optional extension that the service concept does not rely
+on. This also makes changes in the runlevel design easier when it may
+become necessary.
+
+The consequence of having a daemon running that controls the services
+is that we need another program as user interface which communicates
+with the daemon. Fortunatly, this makes the commands necessary for
+controlling services pretty short and intuitive, and gives the
+additional bonus of adding some more flexibility. For example, it is
+easiely possible to grant password-protected control over certain
+services to unprivileged users, if desired.
+
+An essential aspect of the design of the Shepherd (which was already mentioned
+above) is that it should always know exactly what is happening,
+i.e. which services are started and stopped. The alternative would
+have been to not use a daemon, but to save the state on the file
+system, again opening the door for inconsistencies of all sorts.
+Also, we would have to use a seperate program for respawning a service
+(which just starts the services, waits until it terminates and then
+starts it again). Killing the program that does the respawning (but
+not the service that is supposed to be respawned) would cause horrible
+confusion. My understanding of ``The Right Thing'' is that this
+conceptionally limited strategy is exactly what we do not want.
+
+The way dependencies work in the Shepherd took a while to mature, as it was not
+easy to figure out what is appropriate. I decided to not make it too
+sophisticated by trying to guess what the user might want just to
+theoretically fulfill the request we are processing. If something
+goes wrong, it is usually better to tell the user about the problem
+and let her fix it, taking care to make finding solutions or
+workarounds for problems (like a misconfigured service) easy. This
+way, the user is in control of what happens and we can keep the
+implementation simple. To make a long story short, @emph{we don't try
+to be too clever}, which is usually a good idea in developing
+software.
+
+If you wonder why I was giving a ``misconfigured service'' as an
+example above, consider the following situation, which actually is a
+wonderful example for what was said in the previous paragraph: Service
+X depends on symbol S, which is provided by both A and B. A depends
+on AA, B depends on BB. AA and BB conflict with each other. The
+configuration of A contains an error, which will prevent it from
+starting; no service is running, but we want to start X now. In
+resolving its dependencies, we first try to start A, which will cause
+AA to be started. After this is done, the attempt of starting A
+fails, so we go on to B, but its dependency BB will fail to start
+because it conflicts with the running service AA. So we fail to
+provide S, thus X cannot be started. There are several possibilities
+to deal with this:
+
+@itemize @bullet
+@item
+When starting A fails, terminate those services which have been
+started in order to fulfill its dependencies (directly and
+indirectly). In case AA was running already, we would not want to
+terminate it. Well, maybe we would, to avoid the conflict with BB.
+But even if we would find out somehow that we need to terminate AA to
+eventually start X, is the user aware of this and wants this to happen
+(assuming AA was running already)? Probably not, she very likely has
+assumed that starting A succeeds and thus terminating AA is not
+necessary. Remember, unrelated (running) services might depend in AA.
+Even if we ignore this issue, this strategy is not only complicated,
+but also far from being perfect: Let's assume starting A succeeds, but
+X also depends on a service Z, which requires BB. In that case, we
+would need to detect in the first place that we should not even try to
+start A, but directly satisfy X's dependency on S with B.
+
+@item
+We could do it like stated above, but stop AA only if we know we won't
+need it anymore (for resolving further dependencies), and start it
+only when it does not conflict with anything that needs to get
+started. But should we stop it if it conflicts with something that
+@emph{might} get started? (We do not always know for sure what we
+will start, as starting a service might fail and we want to fall back
+to a service that also provides the particular required symbol in that
+case.) I think that either decision will be bad in one case or
+another, even if this solution is already horribly complicated.
+
+@item
+When we are at it, we could just calculate a desired end-position, and
+try to get there by starting (and stopping!) services, recalculating
+what needs to be done whenever starting a service fails, also marking
+that particular service as unstartable, except if it fails to start
+because a dependency could not be resolved (or maybe even then?).
+This is even more complicated. Instead of implementing this and
+thereby producing code that (a) nobody understands, (b) certainly has
+a lot of bugs, (c) will be unmaintainable and (d) causes users to
+panic because they won't understand what will happen, I decided to do
+the following instead:
+
+@item
+Just report the error, and let the user fix it (in this case, fix the
+configuration of A) or work around it (in this case, disable A so that
+we won't start AA but directly go on to starting B).
+@end itemize
+
+I hope you can agree that the latter solution after all is the best
+one, because we can be sure to not do something that the user does not
+want us to do. Software should not run amok. This explanation was
+very long, but I think it was necessary to justify why the Shepherd uses a very
+primitive algorithm to resolve dependencies, despite the fact that it
+could theoretically be a bit more clever in certain situations.
+
+One might argue that it is possible to ask the user if the planned
+actions are ok with her, and if the plan changes ask again, but
+especially given that services are supposed to usually work, I see few
+reasons to make the source code of the Shepherd more complicated than
+necessary. If you volunteer to write @emph{and} maintain a more
+clever strategy (and volunteer to explain it to everyone who wants to
+understand it), you are welcome to do so, of course@dots{}
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Service Internals
+@section Service Internals
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Runlevel evolution
+@section Runlevel evolution
+
+@quotation Note
+This section was written by Wolfgang Jährling back in 2003 and is kept
+mostly for historians to read.
+@end quotation
+
+This section describes how the runlevel concept evolved over time.
+This is basically a collection of mistakes, but is provided here for
+your information, and possibly for your amusement, but I'm not sure if
+all this weird dependency stuff is really that funny.
+
+@menu
+* Runlevel assumptions:: What runlevels should be like
+* Runlevels - part one:: The first attempts of making it work
+* Runlevels - part two:: It should work... somehow...
+@end menu
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Runlevel assumptions
+@subsection Runlevel assumptions
+
+A runlevel is a system state, i.e. it consists of the information
+about which services are supposed to be available and which not. This
+vague definition implies that several different runlevel styles can be
+implemented in a service manager.
+
+For example, you can do it like System V Init, specifying which
+services should be started when we enter a runlevel and which ones
+should be stopped when leaving it. But one could also specify for
+every service in which runlevels it should be running.
+
+In the Shepherd, we do not want to limit ourselfes to a single runlevel style.
+We allow for all possible strategies to be implemented, providing the
+most useful ones as defaults. We also want to make it possible to
+combine the different styles arbitrariely.
+
+Therefore, when entering a runlevel, we call a user-defined piece of
+code, passing it the list of currently active services and expecting
+as the result a list of service symbols which tell us which services
+we want to have running. This interface makes it very easy to
+implement runlevel styles, but makes it not-so-easy for the runlevel
+implementation itself, because we have to get from the current state
+into a desired state, which might be more or less vague (since it is
+not required to be a list of canonical names). Obviously service
+conflicts and already running services need to be taken into account
+when deciding which services should be used to provide the various
+symbols.
+
+Also, the runlevel implementation should be implemented completely on
+top of the service concept, i.e. the service part should not depend on
+the idea of runlevels or care about them at all. Otherwise
+understanding the service part (which is the most essential aspect of
+the Shepherd) would become harder than necessary.
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Runlevels - part one
+@subsection Runlevels, part one
+
+I came up with the following method (here in Pseudo-Scheme), which is
+possibly slightly buggy, but should give you the idea:
+
+@lisp
+;; Beginning with the canonical names in CURRENT-SERVICES, start and
+;; stop services until getting into a state where everything requested
+;; in TARGET-SERVICES (which does not only consist of canonical names)
+;; is provided, and the things they depends on, but no more.
+(define (switch-runlevel current-services target-services)
+ (let ((target-services-backup target-services)
+ (unstartable '()))
+ (let retry ()
+ (repeat-until-none-of-these-changes-annythig
+ ;; Replace all of them with canonical names which provide them.
+ (canonicalize-names! target-services unstartable current-services)
+ ;; Add what we need additionally.
+ (add-dependencies! target-services unstartable current-services))
+ (remove-redundancy! target-services)
+ (stop-all-unneeded target-services)
+ (catch 'service-could-not-be-started
+ (lambda ()
+ ;; Iterate over the list, starting only those which
+ ;; have all dependencies already resolved, so nothing
+ ;; we don't want will be started. Repeat until done.
+ (carefully-start target-services))
+ (lambda (key service)
+ (set! unstartable (cons service unstartable))
+ (set! target-services backup-target-services)
+ (set! current-services (compute-current-services))
+ (retry))))))
+@end lisp
+
+This indeed looks like a nice way to get what we want. However, the
+details of this are not as easy as it looks like. When replacing
+virtual services with canonical names, we have to be very careful.
+Consider the following situation:
+
+The virtual service X is provided by both A and B, while Y is provided
+only by B. We want to start C (which depends on X) and D (which
+depends on Y). Obviously we should use B to fulfill the dependency
+of C and D on X and Y, respectively. But when we see that we need
+something that provides X, we are likely to do the wrong thing: Select
+A. Thus, we need to clean this up later. I wanted to do this as
+follows:
+
+While substituting virtual services with canonical names, we also safe
+which one we selected to fulfill what, like this:
+
+@lisp
+((A . (X))
+ (B . (Y)))
+@end lisp
+
+Later we look for conflicts, and as A and B conflict, we look which
+one can be removed (things they provide but are not required by anyone
+should be ignored, thus we need to create a list like the above). In
+this case, we can replace A with B as B also provides X (but A does
+not provide Y, thus the reverse is impossible). If both could be
+used, we probably should decide which one to use by looking at further
+conflicts, which gets pretty hairy. But, in this case, we are lucky
+and end up with this:
+
+@lisp
+((B . (X Y)))
+@end lisp
+
+This way of finding out which service we should use in case of
+conflicts sounds pretty sane, but if you think it will work well, you
+have been fooled, because actually it breaks horribly in the following
+situation:
+
+@multitable @columnfractions .10 .30
+@item Service @tab Provides
+@item A @tab @code{W X Y -}
+@item B @tab @code{W X - Z}
+@item C @tab @code{- X Y Z}
+@item D @tab @code{W - - -}
+@end multitable
+
+If we need all of W, X, Y and Z, then obviously we need to take C and
+D. But if we have a list like this, we cannot fix it:
+
+@lisp
+((A . (W X Y))
+ (B . (Z)))
+@end lisp
+
+Thus, we cannot do it this way.
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Runlevels - part two
+@subsection Runlevels, part two
+
+Let's look again at the table at the end of part two:
+
+@multitable @columnfractions .10 .30
+@item Service @tab Provides
+@item A @tab @code{W X Y -}
+@item B @tab @code{W X - Z}
+@item C @tab @code{- X Y Z}
+@item D @tab @code{W - - -}
+@end multitable
+
+If from this table it is so obvious for us what we should do, then it
+should also be possible to calculate it for a computer, given such a
+table as input. Ok, we have to take into account conflicts that are
+not visible in this table, but the general idea is usable. But how do
+we find which combination works? I found only one way yet: Kind of a
+brute force attack: Try combinations until we find one that works.
+
+This alone would be too slow. With 20 services we would have 2^20
+possible combinations, that is a bit more than a million. Fortunatly,
+we can optimize this. First I thought we could remove all services
+from the list that do not provide any symbol we need, but that is
+obviously a stupid idea, as we might need them for dependencies, in
+which case we need to take into account their conflicts. But the
+following method would work:
+
+Very often a symbol that is required will be a canonical name already,
+i.e. be provided only by a single service. Using our example above,
+let's suppose we also need the symbol V, which is provided only by D.
+The first step we do is to look which (required) symbols are provided
+only by a single service, as we will need this service for sure. In
+this case, we would need D. But by using it, we would also get the
+other symbols it provides, W in this case. This means that we don't
+need to bother looking at other services that provide W, as we cannot
+use them because they conflict with a service that we definitely need.
+In this case, we can remove A and B from the list this way. Note that
+we can remove them entirely, as all their conflicts become irrelevant
+to us now. In this simple case we would not even have to do much
+else, C is the only remaining service.
+
+After this first step, there remain the symbols that are provided by
+two or more services. In every combination we try, exactly one of
+them must be used (and somehow we should take into account which
+services are running already). This also reduces the amount of
+possible combinations a lot. So what remains after that are the
+services we might need for fulfilling dependencies. For them, we
+could try all combinations (2^n), making sure that we always try
+subsets before any of their supersets to avoid starting unneeded
+services. We should take into account which services are already
+running as well.
+
+The remaining question is, what to do if starting a service fails. A
+simple solution would be to recursively remove all services that
+depend on it directly or indirectly. That might cause undesired
+side-effects, if a service was running but it had to be stopped
+because one of the services that provides something it depends on gets
+exchanged for another service that provides the same symbol, but fails
+to start. The fact that we would have to stop the (first) service is
+a problem on its own, though.
+
+
+@c *********************************************************************
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+
+@include fdl-1.3.texi
+
+@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+
+@node Concept Index
+@unnumbered Concept Index
+
+@printindex cp
+
+@node Procedure and Macro Index
+@unnumbered Procedure and Macro Index
+
+@printindex fn
+
+@node Variable Index
+@unnumbered Variable Index
+
+@printindex vr
+
+@node Type Index
+@unnumbered Type Index
+
+@printindex tp
+
+@bye
diff --git a/fdl-1.3.texi b/fdl-1.3.texi
deleted file mode 100644
index cb71f05..0000000
--- a/fdl-1.3.texi
+++ /dev/null
@@ -1,505 +0,0 @@
-@c The GNU Free Documentation License.
-@center Version 1.3, 3 November 2008
-
-@c This file is intended to be included within another document,
-@c hence no sectioning command or @node.
-
-@display
-Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
-@uref{http://fsf.org/}
-
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
-@end display
-
-@enumerate 0
-@item
-PREAMBLE
-
-The purpose of this License is to make a manual, textbook, or other
-functional and useful document @dfn{free} in the sense of freedom: to
-assure everyone the effective freedom to copy and redistribute it,
-with or without modifying it, either commercially or noncommercially.
-Secondarily, this License preserves for the author and publisher a way
-to get credit for their work, while not being considered responsible
-for modifications made by others.
-
-This License is a kind of ``copyleft'', which means that derivative
-works of the document must themselves be free in the same sense. It
-complements the GNU General Public License, which is a copyleft
-license designed for free software.
-
-We have designed this License in order to use it for manuals for free
-software, because free software needs free documentation: a free
-program should come with manuals providing the same freedoms that the
-software does. But this License is not limited to software manuals;
-it can be used for any textual work, regardless of subject matter or
-whether it is published as a printed book. We recommend this License
-principally for works whose purpose is instruction or reference.
-
-@item
-APPLICABILITY AND DEFINITIONS
-
-This License applies to any manual or other work, in any medium, that
-contains a notice placed by the copyright holder saying it can be
-distributed under the terms of this License. Such a notice grants a
-world-wide, royalty-free license, unlimited in duration, to use that
-work under the conditions stated herein. The ``Document'', below,
-refers to any such manual or work. Any member of the public is a
-licensee, and is addressed as ``you''. You accept the license if you
-copy, modify or distribute the work in a way requiring permission
-under copyright law.
-
-A ``Modified Version'' of the Document means any work containing the
-Document or a portion of it, either copied verbatim, or with
-modifications and/or translated into another language.
-
-A ``Secondary Section'' is a named appendix or a front-matter section
-of the Document that deals exclusively with the relationship of the
-publishers or authors of the Document to the Document's overall
-subject (or to related matters) and contains nothing that could fall
-directly within that overall subject. (Thus, if the Document is in
-part a textbook of mathematics, a Secondary Section may not explain
-any mathematics.) The relationship could be a matter of historical
-connection with the subject or with related matters, or of legal,
-commercial, philosophical, ethical or political position regarding
-them.
-
-The ``Invariant Sections'' are certain Secondary Sections whose titles
-are designated, as being those of Invariant Sections, in the notice
-that says that the Document is released under this License. If a
-section does not fit the above definition of Secondary then it is not
-allowed to be designated as Invariant. The Document may contain zero
-Invariant Sections. If the Document does not identify any Invariant
-Sections then there are none.
-
-The ``Cover Texts'' are certain short passages of text that are listed,
-as Front-Cover Texts or Back-Cover Texts, in the notice that says that
-the Document is released under this License. A Front-Cover Text may
-be at most 5 words, and a Back-Cover Text may be at most 25 words.
-
-A ``Transparent'' copy of the Document means a machine-readable copy,
-represented in a format whose specification is available to the
-general public, that is suitable for revising the document
-straightforwardly with generic text editors or (for images composed of
-pixels) generic paint programs or (for drawings) some widely available
-drawing editor, and that is suitable for input to text formatters or
-for automatic translation to a variety of formats suitable for input
-to text formatters. A copy made in an otherwise Transparent file
-format whose markup, or absence of markup, has been arranged to thwart
-or discourage subsequent modification by readers is not Transparent.
-An image format is not Transparent if used for any substantial amount
-of text. A copy that is not ``Transparent'' is called ``Opaque''.
-
-Examples of suitable formats for Transparent copies include plain
-ASCII without markup, Texinfo input format, La@TeX{} input
-format, SGML or XML using a publicly available
-DTD, and standard-conforming simple HTML,
-PostScript or PDF designed for human modification. Examples
-of transparent image formats include PNG, XCF and
-JPG. Opaque formats include proprietary formats that can be
-read and edited only by proprietary word processors, SGML or
-XML for which the DTD and/or processing tools are
-not generally available, and the machine-generated HTML,
-PostScript or PDF produced by some word processors for
-output purposes only.
-
-The ``Title Page'' means, for a printed book, the title page itself,
-plus such following pages as are needed to hold, legibly, the material
-this License requires to appear in the title page. For works in
-formats which do not have any title page as such, ``Title Page'' means
-the text near the most prominent appearance of the work's title,
-preceding the beginning of the body of the text.
-
-The ``publisher'' means any person or entity that distributes copies
-of the Document to the public.
-
-A section ``Entitled XYZ'' means a named subunit of the Document whose
-title either is precisely XYZ or contains XYZ in parentheses following
-text that translates XYZ in another language. (Here XYZ stands for a
-specific section name mentioned below, such as ``Acknowledgements'',
-``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title''
-of such a section when you modify the Document means that it remains a
-section ``Entitled XYZ'' according to this definition.
-
-The Document may include Warranty Disclaimers next to the notice which
-states that this License applies to the Document. These Warranty
-Disclaimers are considered to be included by reference in this
-License, but only as regards disclaiming warranties: any other
-implication that these Warranty Disclaimers may have is void and has
-no effect on the meaning of this License.
-
-@item
-VERBATIM COPYING
-
-You may copy and distribute the Document in any medium, either
-commercially or noncommercially, provided that this License, the
-copyright notices, and the license notice saying this License applies
-to the Document are reproduced in all copies, and that you add no other
-conditions whatsoever to those of this License. You may not use
-technical measures to obstruct or control the reading or further
-copying of the copies you make or distribute. However, you may accept
-compensation in exchange for copies. If you distribute a large enough
-number of copies you must also follow the conditions in section 3.
-
-You may also lend copies, under the same conditions stated above, and
-you may publicly display copies.
-
-@item
-COPYING IN QUANTITY
-
-If you publish printed copies (or copies in media that commonly have
-printed covers) of the Document, numbering more than 100, and the
-Document's license notice requires Cover Texts, you must enclose the
-copies in covers that carry, clearly and legibly, all these Cover
-Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
-the back cover. Both covers must also clearly and legibly identify
-you as the publisher of these copies. The front cover must present
-the full title with all words of the title equally prominent and
-visible. You may add other material on the covers in addition.
-Copying with changes limited to the covers, as long as they preserve
-the title of the Document and satisfy these conditions, can be treated
-as verbatim copying in other respects.
-
-If the required texts for either cover are too voluminous to fit
-legibly, you should put the first ones listed (as many as fit
-reasonably) on the actual cover, and continue the rest onto adjacent
-pages.
-
-If you publish or distribute Opaque copies of the Document numbering
-more than 100, you must either include a machine-readable Transparent
-copy along with each Opaque copy, or state in or with each Opaque copy
-a computer-network location from which the general network-using
-public has access to download using public-standard network protocols
-a complete Transparent copy of the Document, free of added material.
-If you use the latter option, you must take reasonably prudent steps,
-when you begin distribution of Opaque copies in quantity, to ensure
-that this Transparent copy will remain thus accessible at the stated
-location until at least one year after the last time you distribute an
-Opaque copy (directly or through your agents or retailers) of that
-edition to the public.
-
-It is requested, but not required, that you contact the authors of the
-Document well before redistributing any large number of copies, to give
-them a chance to provide you with an updated version of the Document.
-
-@item
-MODIFICATIONS
-
-You may copy and distribute a Modified Version of the Document under
-the conditions of sections 2 and 3 above, provided that you release
-the Modified Version under precisely this License, with the Modified
-Version filling the role of the Document, thus licensing distribution
-and modification of the Modified Version to whoever possesses a copy
-of it. In addition, you must do these things in the Modified Version:
-
-@enumerate A
-@item
-Use in the Title Page (and on the covers, if any) a title distinct
-from that of the Document, and from those of previous versions
-(which should, if there were any, be listed in the History section
-of the Document). You may use the same title as a previous version
-if the original publisher of that version gives permission.
-
-@item
-List on the Title Page, as authors, one or more persons or entities
-responsible for authorship of the modifications in the Modified
-Version, together with at least five of the principal authors of the
-Document (all of its principal authors, if it has fewer than five),
-unless they release you from this requirement.
-
-@item
-State on the Title page the name of the publisher of the
-Modified Version, as the publisher.
-
-@item
-Preserve all the copyright notices of the Document.
-
-@item
-Add an appropriate copyright notice for your modifications
-adjacent to the other copyright notices.
-
-@item
-Include, immediately after the copyright notices, a license notice
-giving the public permission to use the Modified Version under the
-terms of this License, in the form shown in the Addendum below.
-
-@item
-Preserve in that license notice the full lists of Invariant Sections
-and required Cover Texts given in the Document's license notice.
-
-@item
-Include an unaltered copy of this License.
-
-@item
-Preserve the section Entitled ``History'', Preserve its Title, and add
-to it an item stating at least the title, year, new authors, and
-publisher of the Modified Version as given on the Title Page. If
-there is no section Entitled ``History'' in the Document, create one
-stating the title, year, authors, and publisher of the Document as
-given on its Title Page, then add an item describing the Modified
-Version as stated in the previous sentence.
-
-@item
-Preserve the network location, if any, given in the Document for
-public access to a Transparent copy of the Document, and likewise
-the network locations given in the Document for previous versions
-it was based on. These may be placed in the ``History'' section.
-You may omit a network location for a work that was published at
-least four years before the Document itself, or if the original
-publisher of the version it refers to gives permission.
-
-@item
-For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
-the Title of the section, and preserve in the section all the
-substance and tone of each of the contributor acknowledgements and/or
-dedications given therein.
-
-@item
-Preserve all the Invariant Sections of the Document,
-unaltered in their text and in their titles. Section numbers
-or the equivalent are not considered part of the section titles.
-
-@item
-Delete any section Entitled ``Endorsements''. Such a section
-may not be included in the Modified Version.
-
-@item
-Do not retitle any existing section to be Entitled ``Endorsements'' or
-to conflict in title with any Invariant Section.
-
-@item
-Preserve any Warranty Disclaimers.
-@end enumerate
-
-If the Modified Version includes new front-matter sections or
-appendices that qualify as Secondary Sections and contain no material
-copied from the Document, you may at your option designate some or all
-of these sections as invariant. To do this, add their titles to the
-list of Invariant Sections in the Modified Version's license notice.
-These titles must be distinct from any other section titles.
-
-You may add a section Entitled ``Endorsements'', provided it contains
-nothing but endorsements of your Modified Version by various
-parties---for example, statements of peer review or that the text has
-been approved by an organization as the authoritative definition of a
-standard.
-
-You may add a passage of up to five words as a Front-Cover Text, and a
-passage of up to 25 words as a Back-Cover Text, to the end of the list
-of Cover Texts in the Modified Version. Only one passage of
-Front-Cover Text and one of Back-Cover Text may be added by (or
-through arrangements made by) any one entity. If the Document already
-includes a cover text for the same cover, previously added by you or
-by arrangement made by the same entity you are acting on behalf of,
-you may not add another; but you may replace the old one, on explicit
-permission from the previous publisher that added the old one.
-
-The author(s) and publisher(s) of the Document do not by this License
-give permission to use their names for publicity for or to assert or
-imply endorsement of any Modified Version.
-
-@item
-COMBINING DOCUMENTS
-
-You may combine the Document with other documents released under this
-License, under the terms defined in section 4 above for modified
-versions, provided that you include in the combination all of the
-Invariant Sections of all of the original documents, unmodified, and
-list them all as Invariant Sections of your combined work in its
-license notice, and that you preserve all their Warranty Disclaimers.
-
-The combined work need only contain one copy of this License, and
-multiple identical Invariant Sections may be replaced with a single
-copy. If there are multiple Invariant Sections with the same name but
-different contents, make the title of each such section unique by
-adding at the end of it, in parentheses, the name of the original
-author or publisher of that section if known, or else a unique number.
-Make the same adjustment to the section titles in the list of
-Invariant Sections in the license notice of the combined work.
-
-In the combination, you must combine any sections Entitled ``History''
-in the various original documents, forming one section Entitled
-``History''; likewise combine any sections Entitled ``Acknowledgements'',
-and any sections Entitled ``Dedications''. You must delete all
-sections Entitled ``Endorsements.''
-
-@item
-COLLECTIONS OF DOCUMENTS
-
-You may make a collection consisting of the Document and other documents
-released under this License, and replace the individual copies of this
-License in the various documents with a single copy that is included in
-the collection, provided that you follow the rules of this License for
-verbatim copying of each of the documents in all other respects.
-
-You may extract a single document from such a collection, and distribute
-it individually under this License, provided you insert a copy of this
-License into the extracted document, and follow this License in all
-other respects regarding verbatim copying of that document.
-
-@item
-AGGREGATION WITH INDEPENDENT WORKS
-
-A compilation of the Document or its derivatives with other separate
-and independent documents or works, in or on a volume of a storage or
-distribution medium, is called an ``aggregate'' if the copyright
-resulting from the compilation is not used to limit the legal rights
-of the compilation's users beyond what the individual works permit.
-When the Document is included in an aggregate, this License does not
-apply to the other works in the aggregate which are not themselves
-derivative works of the Document.
-
-If the Cover Text requirement of section 3 is applicable to these
-copies of the Document, then if the Document is less than one half of
-the entire aggregate, the Document's Cover Texts may be placed on
-covers that bracket the Document within the aggregate, or the
-electronic equivalent of covers if the Document is in electronic form.
-Otherwise they must appear on printed covers that bracket the whole
-aggregate.
-
-@item
-TRANSLATION
-
-Translation is considered a kind of modification, so you may
-distribute translations of the Document under the terms of section 4.
-Replacing Invariant Sections with translations requires special
-permission from their copyright holders, but you may include
-translations of some or all Invariant Sections in addition to the
-original versions of these Invariant Sections. You may include a
-translation of this License, and all the license notices in the
-Document, and any Warranty Disclaimers, provided that you also include
-the original English version of this License and the original versions
-of those notices and disclaimers. In case of a disagreement between
-the translation and the original version of this License or a notice
-or disclaimer, the original version will prevail.
-
-If a section in the Document is Entitled ``Acknowledgements'',
-``Dedications'', or ``History'', the requirement (section 4) to Preserve
-its Title (section 1) will typically require changing the actual
-title.
-
-@item
-TERMINATION
-
-You may not copy, modify, sublicense, or distribute the Document
-except as expressly provided under this License. Any attempt
-otherwise to copy, modify, sublicense, or distribute it is void, and
-will automatically terminate your rights under this License.
-
-However, if you cease all violation of this License, then your license
-from a particular copyright holder is reinstated (a) provisionally,
-unless and until the copyright holder explicitly and finally
-terminates your license, and (b) permanently, if the copyright holder
-fails to notify you of the violation by some reasonable means prior to
-60 days after the cessation.
-
-Moreover, your license from a particular copyright holder is
-reinstated permanently if the copyright holder notifies you of the
-violation by some reasonable means, this is the first time you have
-received notice of violation of this License (for any work) from that
-copyright holder, and you cure the violation prior to 30 days after
-your receipt of the notice.
-
-Termination of your rights under this section does not terminate the
-licenses of parties who have received copies or rights from you under
-this License. If your rights have been terminated and not permanently
-reinstated, receipt of a copy of some or all of the same material does
-not give you any rights to use it.
-
-@item
-FUTURE REVISIONS OF THIS LICENSE
-
-The Free Software Foundation may publish new, revised versions
-of the GNU Free Documentation License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns. See
-@uref{http://www.gnu.org/copyleft/}.
-
-Each version of the License is given a distinguishing version number.
-If the Document specifies that a particular numbered version of this
-License ``or any later version'' applies to it, you have the option of
-following the terms and conditions either of that specified version or
-of any later version that has been published (not as a draft) by the
-Free Software Foundation. If the Document does not specify a version
-number of this License, you may choose any version ever published (not
-as a draft) by the Free Software Foundation. If the Document
-specifies that a proxy can decide which future versions of this
-License can be used, that proxy's public statement of acceptance of a
-version permanently authorizes you to choose that version for the
-Document.
-
-@item
-RELICENSING
-
-``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any
-World Wide Web server that publishes copyrightable works and also
-provides prominent facilities for anybody to edit those works. A
-public wiki that anybody can edit is an example of such a server. A
-``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the
-site means any set of copyrightable works thus published on the MMC
-site.
-
-``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0
-license published by Creative Commons Corporation, a not-for-profit
-corporation with a principal place of business in San Francisco,
-California, as well as future copyleft versions of that license
-published by that same organization.
-
-``Incorporate'' means to publish or republish a Document, in whole or
-in part, as part of another Document.
-
-An MMC is ``eligible for relicensing'' if it is licensed under this
-License, and if all works that were first published under this License
-somewhere other than this MMC, and subsequently incorporated in whole
-or in part into the MMC, (1) had no cover texts or invariant sections,
-and (2) were thus incorporated prior to November 1, 2008.
-
-The operator of an MMC Site may republish an MMC contained in the site
-under CC-BY-SA on the same site at any time before August 1, 2009,
-provided the MMC is eligible for relicensing.
-
-@end enumerate
-
-@page
-@heading ADDENDUM: How to use this License for your documents
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and
-license notices just after the title page:
-
-@smallexample
-@group
- Copyright (C) @var{year} @var{your name}.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.3
- or any later version published by the Free Software Foundation;
- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
- Texts. A copy of the license is included in the section entitled ``GNU
- Free Documentation License''.
-@end group
-@end smallexample
-
-If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
-replace the ``with@dots{}Texts.''@: line with this:
-
-@smallexample
-@group
- with the Invariant Sections being @var{list their titles}, with
- the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
- being @var{list}.
-@end group
-@end smallexample
-
-If you have Invariant Sections without Cover Texts, or some other
-combination of the three, merge those two alternatives to suit the
-situation.
-
-If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License,
-to permit their use in free software.
-
-@c Local Variables:
-@c ispell-local-pdict: "ispell-dict"
-@c End:
diff --git a/shepherd.texi b/shepherd.texi
deleted file mode 100644
index 5dc5f9c..0000000
--- a/shepherd.texi
+++ /dev/null
@@ -1,1593 +0,0 @@
-\input texinfo @c -*- texinfo -*-
-@c shepherd.texi -- The documentation in Texinfo format.
-@documentencoding UTF-8
-@setfilename shepherd.info
-@settitle The GNU Shepherd Manual
-
-@include version.texi
-@set OLD-YEARS 2002, 2003
-@set NEW-YEARS 2013, 2016
-
-@copying
-Copyright @copyright{} @value{OLD-YEARS} Wolfgang J@"ahrling@*
-Copyright @copyright{} @value{NEW-YEARS} Ludovic Courtès
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.3 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
-copy of the license is included in the section entitled ``GNU Free
-Documentation License''.
-@end copying
-
-@dircategory System software
-@direntry
-* shepherd: (shepherd). The Shepherd service manager.
-* herd: (shepherd)Invoking herd
- Controlling the Shepherd service manager.
-* reboot: (shepherd)Invoking reboot
- Rebooting a Shepherd-controlled system.
-* halt: (shepherd)Invoking halt
- Turning off a Shepherd-controlled system.
-@end direntry
-
-@titlepage
-@title The GNU Shepherd Manual
-@subtitle For use with the GNU Shepherd @value{VERSION}
-@subtitle Last updated @value{UPDATED}
-
-@author Wolfgang J@"ahrling
-@author Ludovic Courtès
-
-@insertcopying
-@end titlepage
-
-@contents
-
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@ifnottex
-@node Top
-@top The GNU Shepherd Manual
-
-This manual documents the GNU@tie{}Shepherd version @value{VERSION}, a
-service manager for the GNU system.
-
-@menu
-* Introduction:: Introduction to the Shepherd service manager.
-* Jump Start:: How to do simple things with the Shepherd.
-* herd and shepherd:: User interface to service management.
-* Services:: Details on services.
-* Runlevels:: Details on runlevels.
-* Misc Facilities:: Generally useful things provided by the Shepherd.
-* Internals:: Hacking shepherd.
-
-* GNU Free Documentation License:: The license of this manual.
-* Concept Index::
-* Procedure and Macro Index::
-* Variable Index::
-* Type Index::
-@end menu
-@end ifnottex
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Introduction
-@chapter Introduction
-
-@cindex service manager
-This manual documents the GNU@tie{}Daemon Shepherd, or GNU@tie{}Shepherd
-for short. The Shepherd looks after system services, typically @dfn{daemons}.
-It is used to start and stop them in a reliable
-fashion. For instance it will dynamically determine and start any
-other services that our desired service depends upon. As another
-example, the Shepherd might detect conflicts among services. In this
-situation it would simply prevent the conflicting services from
-running concurrently.
-
-The Shepherd is the @dfn{init system} of the GNU operating system---it is the
-first user process that gets started, typically with PID 1, and runs
-as @code{root}. Normally the purpose of init systems is to manage all
-system-wide services, but the Shepherd can also be a useful tool assisting
-unprivileged users in the management of their own daemons.
-
-Flexible software requires some time to master and
-the Shepherd is no different. But don't worry: this manual should allow you to
-get started quickly. Its first chapter is designed as a practical
-introduction to the Shepherd and should be all you need for everyday use
-(@pxref{Jump Start}). In chapter two we will describe the
-@command{herd} and @command{shepherd} programs, and their relationship, in
-more detail (@ref{herd and shepherd}). Subsequent chapters provide a full
-reference manual and plenty of examples, covering all of Shepherd's
-capabilities. Finally, the last chapter provides information for
-those souls brave enough to hack the Shepherd itself.
-
-@cindex dmd
-The Shepherd was formerly known as ``dmd'', which stands for @dfn{Daemon
-Managing Daemons} (or @dfn{Daemons-Managing Daemon}?).
-
-@cindex Guile
-@cindex Scheme
-@cindex GOOPS
-This program is written in Guile, an implementation of the
-Scheme programming language, using the GOOPS extension for
-object-orientation. Guile is also the Shepherd's configuration language.
-@xref{Introduction,,, guile, GNU Guile Reference Manual}, for an
-introduction to Guile. We have tried to
-make the Shepherd's basic features as accessible as possible---you should be
-able to use these even if you do not know how to program in Scheme. A
-basic grasp of Guile and GOOPS is required only if you wish to make
-use of the Shepherd's more advanced features.
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Jump Start
-@chapter Jump Start
-
-@cindex prefix
-This chapter gives a short overview of the Shepherd. It is enough if you just
-need the basic features of it. As it is not assumed that readers are
-familiar with all the involved issues, a very experienced user might
-be annoyed by the often very detailed descriptions in this
-introduction. Those users are encouraged to just skip to the
-reference section.
-
-Note that all the full file names in the following text are based on
-the assumption that you have installed the Shepherd with an empty prefix. If
-your the Shepherd installation for example resides in @code{/usr/local}
-instead, add this directory name in front of the absolute file names
-mentioned below.
-
-@cindex Configuration file
-When @command{shepherd} gets started, it reads and evaluates a
-configuration file. When it is started with superuser priviledges, it
-tries to use @code{/etc/shepherd.scm}. When started as normal user, it
-looks for a file called @code{$XDG_CONFIG_HOME/shepherd/init.scm}. If
-the @code{XDG_CONFIG_HOME} environment variable is not defined,
-@code{$HOME/.config/shepherd/init.scm} is used instead. With the option
-@code{--config} (or, for short, @code{-c}), you can specify where to
-look instead. So if you want to start @command{shepherd} with an
-alternative file, use one of the following commands:
-
-@example
-shepherd --config=/etc/shepherd.scm.old
-shepherd -c /etc/shepherd.scm.old
-@end example
-
-@cindex Starting a service
-As the final ``d'' suggests, @command{shepherd} is just
-a daemon that (usually) runs in the
-background, so you will not interact with it directly. After it is
-started, @command{shepherd} will listen on a socket special file, usually
-@code{/var/run/shepherd/socket}, for further commands. You use the tool
-@dfn{herd} to send these commands to @command{shepherd}. Usage of herd is simple and
-straightforward: To start a service called @code{apache}, you use:
-
-@example
-herd start apache
-@end example
-
-@cindex Status (of services)
-@cindex Service status
-When you do this, all its dependencies will get resolved. For
-example, a webserver is quite likely to depend on working networking,
-thus it will depend on a service called @code{networking}. So if you
-want to start @code{apache}, and @code{networking} is not yet running, it
-will automatically be started as well. The current status of all the
-services defined in the configuration file can be queried like this:
-
-@example
-herd status
-@end example
-
-@noindent
-Or, to get additional details about each service, run:
-
-@example
-herd detailed-status
-@end example
-
-@noindent
-In this example, this would show the @code{networking} and @code{apache}
-services as started. If you just want to know the status of the
-@code{apache} service, run:
-
-@example
-herd status apache
-@end example
-
-@cindex Stopping a service
-You can stop
-a service and all the services that depend on it will be stopped.
-Using the example above, if you stop @code{networking}, the service
-@code{apache} will be stopped as well---which makes perfect sense,
-as it cannot work without the network being up. To actually stop a
-service, you use the following, probably not very surprising, command:
-
-@example
-herd stop networking
-@end example
-
-There are two more actions you can perform on every service: The
-actions @code{enable} and @code{disable} are used to prevent and allow
-starting of the particular service. If a service is intended to be
-restarted whenever it terminates (how this can be done will not be
-covered in this introduction), but it is respawning too often in a
-short period of time (by default 5 times in 5 seconds), it will
-automatically be disabled. After you have fixed the problem that
-caused it from being respawned too fast, you can start it again with
-the commands:
-
-@example
-herd enable foo
-herd start foo
-@end example
-
-@cindex virtual services
-@cindex fallback services
-But there is far more you can do than just that. Services can not
-only simply depend on other services, they can also depend on
-@emph{virtual} services. A virtual service is a service that is
-provided by one or more service additionally. For instance, a service
-called @code{exim} might provide the virtual service
-@code{mailer-daemon}. That could as well be provided by a service
-called @code{smail}, as both are mailer-daemons. If a service needs
-any mailer-daemon, no matter which one, it can just depend on
-@code{mailer-daemon}, and one of those who provide it gets started (if
-none is running yet) when resolving dependencies. The nice thing is
-that, if trying to start one of them fails, @command{shepherd} will go on and try to
-start the next one, so you can also use virtual services for
-specifying @emph{fallbacks}.
-
-Additionally to all that, you can perform service-specific actions.
-Coming back to our original example, @code{apache} is able to
-reload its modules, therefore the action @code{reload-modules} might
-be available:
-
-@example
-herd reload-modules apache
-@end example
-
-The service-specific actions can only be used when the service is
-started, i.e. the only thing you can do to a stopped service is
-starting it. An exception exists, see below. (If you may at some
-point find this too restrictive because you want to use variants of
-the same service which are started in different ways, consider using
-different services for those variants instead, which all provide the
-same virtual service and thus conflict with each other, if this is
-desired. That's one of the reasons why virtual services exist, after
-all.)
-
-There are two actions which are special, because even if services
-can implement them on their own, a default implementation is provided
-by @command{shepherd} (another reason why they are special is that the default
-implementations can be called even when the service is not running;
-this inconsistency is just to make it more intuitive to get
-information about the status of a service, see below).
-
-These actions are @code{restart} and @code{status}. The default
-implementation of @code{restart} calls @code{stop} and @code{start} on
-the affected service in order, the @code{status} action displays some
-general information about the service, like what it provides, what it
-depends on and with which other services it conflicts (because they
-provide a virtual service that is also provided by that particular
-service).
-
-Another special action is @code{list-actions}, which displays a list
-of the additional actions a service provides; obviously, it can also
-be called when the service is not running. Services cannot provide
-their own implementation of @code{list-actions}.
-
-A special service is @code{root}, which is used for controlling the
-Shepherd itself. You can also reference to this service as
-@code{shepherd}. It implements various actions. For example, the
-@code{status} action displays which services are started and which ones
-are stopped, whereas @code{detailed-status} has the effect of applying
-the default implementation of @code{status} to all services one after
-another. The @code{load} action is unusual insofar as it shows a
-feature that is actually available to all services, but which we have
-not seen yet: It takes an additional argument. You can use @code{load}
-to load arbitrary code into the Shepherd at runtime, like this:
-
-@example
-herd load shepherd ~/additional-services.scm
-@end example
-
-This is enough now about the @command{herd} and @command{shepherd} programs, we
-will now take a look at how to configure the Shepherd. In the configuration
-file, we need mainly the definition of services. We can also do
-various other things there, like starting a few services already.
-
-FIXME: Finish. For now, look at the @code{examples/} subdirectory.
-
-@example
-...
-@end example
-
-Ok, to summarize:
-
-@itemize @bullet
-@item
-@command{shepherd} is a daemon, @command{herd} the program that controls it.
-@item
-You can start, stop, restart, enable and disable every service, as
-well as display its status.
-@item
-You can perform additional service-specific actions, which you can
-also list.
-@item
-Actions can have arguments.
-@item
-You can display the status of a service, even if the service does not
-provide a specific implementation for this action. The same is true
-for restarting.
-@item
-The @code{root}/@code{shepherd} service is used to control
-@command{shepherd} itself.
-@end itemize
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node herd and shepherd
-@chapter @command{herd} and @command{shepherd}
-
-@cindex herd
-@cindex shepherd
-@cindex daemon
-@cindex daemon controller
-@cindex relative file names
-@cindex herding, of daemons
-The daemon that runs in the background and is responsible for
-controlling the services is @command{shepherd}, while the user interface
-tool is called @command{herd}: it's the command that allows you to
-actually @emph{herd} your daemons@footnote{
-@cindex deco, daemon controller
-In the past, when the
-GNU@tie{}Shepherd was known as GNU@tie{}dmd, the @command{herd} command
-was called @code{deco}, for @dfn{DaEmon COntroller}.}. To perform an
-action, like stopping a service or calling an action of a service, you
-use the herd program. It will communicate with shepherd over a Unix
-Domain Socket.
-
-Thus, you start @command{shepherd} once, and then always use herd whenever you want
-to do something service-related. Since herd passes its current
-working directory to @command{shepherd}, you can pass relative file names without
-trouble. Both @command{shepherd} and herd understand the standard arguments
-@code{--help}, @code{--version} and @code{--usage}.
-
-
-@menu
-* Invoking shepherd:: How to start the service damon.
-* Invoking herd:: Controlling daemons.
-* Invoking reboot:: Rebooting a shepherd-controlled system.
-* Invoking halt:: Turning off a shepherd-controlled system.
-@end menu
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Invoking shepherd
-@section Invoking @command{shepherd}
-
-@cindex @command{shepherd} Invocation
-@cindex invoking @command{shepherd}
-The @code{shepherd} program has the following synopsis:
-
-@example
-shepherd [@var{option}@dots{}]
-@end example
-
-It accepts the following options:
-
-@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}).
-
-@item -I
-@itemx --insecure
-@cindex security
-@cindex insecure
-Do not check if the directory where the socket---our communication
-rendez-vous with @command{herd}---is located has permissions @code{700}.
-If this option is not specified, @command{shepherd} will abort if the
-permissions are not as expected.
-
-@item -l [@var{file}]
-@itemx --logfile[=@var{file}]
-@cindex logging
-@cindex log file
-Log output into @var{file}, or if @var{file} is not given,
-@code{/var/log/shepherd.log} when running as superuser,
-@code{$XDG_CONFIG_HOME/shepherd/shepherd.log} otherwise.
-
-@item --pid[=@var{file}]
-When @command{shepherd} is ready to accept connections, write its PID to @var{file} or
-to the standard output if @var{file} is omitted.
-
-@item -p [@var{file}]
-@itemx --persistency[=@var{file}]
-@c FIXME-CRITICAL
-
-@item -s @var{file}
-@itemx --socket=@var{file}
-@cindex socket special file
-Receive further commands on the socket special file @var{file}. If
-this option is not specified, @file{@var{localstatedir}/run/shepherd/socket} is
-taken.
-
-If @code{-} is specified as file name, commands will be read from
-standard input, one per line, as would be passed on a @command{herd}
-command line (@pxref{Invoking herd}).
-
-@item --quiet
-Synonym for @code{--silent}.
-
-@end table
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Invoking herd
-@section Invoking herd
-
-@cindex herd
-The @command{herd} command is a generic client program to control a
-running instance of @command{shepherd} (@pxref{Invoking shepherd}). It has the
-following synopsis:
-
-@example
-herd [@var{option}@dots{}] @var{action} [@var{service} [@var{arg}@dots{}]]
-@end example
-
-It causes the @var{action} of the @var{service} to be invoked. When
-@var{service} is omitted and @var{action} is @code{status} or
-@code{detailed-status}, the @code{root} service is used@footnote{This
-shorthand does not work for other actions such as @code{stop}, because
-inadvertently typing @code{herd stop} would stop all the services, which
-could be pretty annoying.} (@pxref{The root and unknown services}, for
-more information on the @code{root} service.)
-
-For each action, you should pass the appropriate @var{arg}s. Actions
-that are available for every service are @code{start}, @code{stop},
-@code{restart}, @code{status}, @code{enable}, @code{disable}, and
-@code{doc}.
-
-If you pass a file name as an @var{arg}, it will be passed as-is to
-the Shepherd, thus if it is not an absolute name, it is local to the current
-working directory of @command{shepherd}, not to herd.
-
-The @code{herd} command understands the following option:
-
-@table @samp
-
-@item -s @var{file}
-@itemx --socket=@var{file}
-Send commands to the socket special file @var{file}. If this option is
-not specified, @file{@var{localstatedir}/run/shepherd/socket} is taken.
-
-@end table
-
-The @code{herd} command returns zero on success, and a non-zero exit
-code on failure. In particular, it returns a non-zero exit code when
-@var{action} or @var{service} does not exist and when the given action
-failed.
-
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Invoking reboot
-@section Invoking reboot
-
-@cindex herd
-The @command{reboot} command is a convenience client program to instruct
-the Shepherd (when used as an init system) to stop all running services and
-reboot the system. It has the following synopsis:
-
-@example
-reboot [@var{option}@dots{}]
-@end example
-
-It is equivalent to running @command{herd stop shepherd}. The
-@code{reboot} command understands the following option:
-
-@table @samp
-
-@item -s @var{file}
-@itemx --socket=@var{file}
-Send commands to the socket special file @var{file}. If this option is
-not specified, @file{@var{localstatedir}/run/shepherd/socket} is taken.
-
-@end table
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Invoking halt
-@section Invoking halt
-
-@cindex herd
-The @command{halt} command is a convenience client program to instruct
-the Shepherd (when used as an init system) to stop all running services and turn
-off the system. It has the following synopsis:
-
-@example
-halt [@var{option}@dots{}]
-@end example
-
-It is equivalent to running @command{herd power-off shepherd}. As
-usual, the @code{halt} command understands the following option:
-
-@table @samp
-
-@item -s @var{file}
-@itemx --socket=@var{file}
-Send commands to the socket special file @var{file}. If this option is
-not specified, @file{@var{localstatedir}/run/shepherd/socket} is taken.
-
-@end table
-
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Services
-@chapter Services
-
-@cindex service
-@tindex <service>
-The @dfn{service} is obviously a very important concept of the Shepherd. On the
-Guile level, a service is represented as an instance of
-@code{<service>}, a GOOPS class (@pxref{GOOPS,,, guile, GNU Guile
-Reference Manual}). When creating an instance of it, you can specify
-the initial values of its slots, and you actually must do this for some
-of the slots.
-
-The @code{<service>} class and its associated procedures and methods are
-defined in the @code{(shepherd service)} module.
-
-@menu
-* Slots of services:: What a <service> object consists of.
-* Methods of services:: What you can do with a <service> object.
-* Service Convenience:: How to conveniently work with services.
-* Service De- and Constructors:: Commonly used ways of starting and
- stopping services.
-* Service Examples:: Examples that show how services are used.
-* The root and unknown services:: Special services in the Shepherd.
-@end menu
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Slots of services
-@section Slots of services
-
-@cindex <service>, slots of
-@cindex slots of <service>
-A service has the following slots, all of which can be initialized
-with a keyword (i.e. @code{#:provides}, used when creating the object)
-of the same name, except where stated otherwise. You should not
-access them directly with @code{slot-ref} or @code{slot-set!}
-usually, use the methods of the service class @ref{Methods of
-services} instead.
-
-@itemize @bullet
-@item
-@vindex provides (slot of <service>)
-@cindex canonical names of services
-@code{provides} is a list of symbols that are provided by the service.
-A symbol can only be provided by one service running at a time,
-i.e. if two services provide the same symbol, only one of them can
-run, starting the other one will fail. Therefore, these symbols are
-mainly used to denote conflicting services. The first symbol in the
-list is the canonical name for the service, thus it must be unique.
-This slot has no default value and must therefore be initialized.
-
-@item
-@vindex requires (slot of <service>)
-@code{requires} is, like @code{provides}, a list of symbols that
-specify services. In this case, they name what this service depends
-on, i.e. before the service can be started, services that provide
-those symbols must be started. If a required symbol is provided by
-several services, one will be started. By default, this slot
-contains the empty list.
-
-@item
-@vindex running (slot of <service>)
-@cindex Hook for individual services
-@code{running} is a hook that can be used by each service in its own
-way. The default value is @code{#f}, which indicates that the service
-is not running. When an attempt is made to start the service, it will
-be set to the return value of the procedure in the @code{start} slot.
-It will also be passed as an argument to the procedure in the
-@code{stop} slot. This slot can not be initialized with a keyword.
-
-@item
-@vindex respawn? (slot of <service>)
-@cindex Respawning services
-@code{respawn?} specifies whether the service should be respawned by
-the Shepherd. If this slot has the value @code{#t}, then assume the
-@code{running} slot specifies a child process PID and restart the
-service if that process terminates. Otherwise this slot is @code{#f},
-which is the default. See also the @code{last-respawns} slot.
-
-@item
-@vindex start (slot of <service>)
-@cindex Starting a service
-@cindex Service constructor
-@code{start} contains the ``constructor'' for the service, which will
-be called to start the service. (Therefore, it is not a constructor
-in the sense that it initializes the slots of a @code{<service>}
-object.) This must be a procedure that accepts any amount of
-arguments, which will be the additional arguments supplied by the
-user. If the starting attempt failed, it must return @code{#f}. The
-value will be stored in the @code{running} slot. The default value is
-a procedure that returns @code{#t} and performs no further actions,
-therefore it is desirable to specify a different one usually.
-
-@item
-@vindex stop (slot of <service>)
-@cindex Stoping a service
-@cindex Service destructor
-@code{stop} is, similar to @code{start}, a slot containing a
-procedure. But in this case, it gets the current value of the
-@code{running} slot as first argument and the user-supplied arguments
-as further arguments; it gets called to stop the service. Its return
-value will again be stored in the @code{running} slot, so that it
-should return @code{#f} if it is now possible again to start the
-service at a later point. The default value is a procedure that
-returns @code{#f} and performs no further actions.
-
-@item
-@vindex actions (slot of <service>)
-@cindex Actions of services
-@cindex Service actions
-@code{actions} specifies the additional actions that can be performed
-on a service when it is running. A typical example for this is the
-@code{restart} action. The macro @code{make-actions} @ref{Service
-Convenience} is provided to abstract the actual data representation
-format for this slot. (It actually is a hash currently.)
-
-@item
-@vindex enabled? (slot of <service>)
-@code{enabled?} cannot be initialized with a keyword, and contains
-@code{#t} by default. When the value becomes @code{#f} at some point,
-this will prevent the service from getting started. A service can be
-enabled and disabled with the methods @code{enable} and
-@code{disable}, respectively @ref{Methods of services}.
-
-@item
-@vindex last-respawns (slot of <service>)
-@code{last-respawns} cannot be initialized with a keyword and is only
-ever used when the @code{respawn?} slot contains @code{#t}; it is a
-circular list with @code{(car respawn-limit)} elements, where each
-element contains the time when it was restarted, initially all 0,
-later a time in seconds since the Epoch. The first element is the one
-that contains the oldest one, the last one the newest.
-
-@item
-@vindex stop-delay? (slot of <service>)
-@code{stop-delay?} being false causes the @code{stop} slot to be
-unused; instead, stopping the service will just cause the
-@code{waiting-for-termination?} slot be set to @code{#t}.
-
-@item
-@vindex waiting-for-termination? (slot of <service>)
-@code{waiting-for-termination?} cannot be initialized with a keyword
-and should not be used by others, it is only used internally for
-respawnable services when the @code{stop-delay?} slot contains a true
-value. @code{waiting-for-termination?} contains @code{#t} if the
-service is still running, but the user requested that it be stopped,
-in which case if the service terminates the next time, the respawn
-handler will not start it again.
-
-otherwise @code{#f}.
-
-@end itemize
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Methods of services
-@section Methods of services
-
-@deffn {method} start (obj <service>)
-Start the service @var{obj}, including all the services it depends on.
-It tries quite hard to do this: When a service that provides a
-required symbol can not be started, it will look for another service
-that also provides this symbol, until starting one such service
-succeeds. There is some room for theoretical improvement here, of
-course, but in pratice the current strategy already works very well.
-This method returns the new value of the @code{running} slot
-@ref{Slots of services}, which is @code{#f} if the service could not
-be started.
-@end deffn
-
-@deffn {method} stop (obj <service>)
-This will stop the service @var{obj}, trying to stop services that
-depend in it first, so they can be shutdown cleanly. If this will
-fail, it will continue anyway. Stopping of services should usually
-succeed, though. Otherwise, the behaviour is very similar to the
-@code{start} method. The return value is also the new @code{running}
-value, thus @code{#f} if the service was stopped.
-@end deffn
-
-@deffn {method} action (obj <service>) the-action . args
-Calls the action @var{the-action} (a symbol) of the service @var{obj},
-with the specified @var{args}, which have a meaning depending on the
-particular action.
-@end deffn
-
-@deffn {method} conflicts-with (obj <service>)
-Returns a list of the canonical names of services that conflict with
-the service @var{obj}.
-@end deffn
-
-@deffn {method} canonical-name (obj <service>)
-Returns the canonical name of @var{obj}, which is the first element of
-the @code{provides} list.
-@end deffn
-
-@deffn {method} provided-by (obj <service>)
-Returns which symbols are provided by @var{obj}.
-@end deffn
-
-@deffn {method} required-by (obj <service>)
-Returns which symbols are required by @var{obj}.
-@end deffn
-
-@deffn {method} running? (obj <service>)
-Returns whether the service @var{obj} is running.
-@end deffn
-
-@deffn {method} respawn? (obj <service>)
-Returns whether the service @var{obj} should be respawned if it
-terminates.
-@end deffn
-
-@deffn {method} default-display-status (obj <service>)
-Display status information about @var{obj}. This method is called
-when the user performs the action @code{status} on @var{obj}, but
-there is no specific implementation given for it. It is also called
-when @code{detailed-status} is applied on the @code{root} service.
-@end deffn
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Service Convenience
-@section Service Convenience
-
-In addition to the facilities listed below, there are also some
-procedures that provide commonly needed constructors and destructors
-for services @ref{Service De- and Constructors}.
-
-@deffn {procedure} register-services . services
-Register all @var{services}, so that they can be taken into account
-when trying to resolve dependencies.
-@end deffn
-
-@deffn {procedure} lookup-services name
-Return a list of all registered services which provide the symbol
-@var{name}.
-@end deffn
-
-@deffn {macro} make-actions (name proc) ...
-This macro is used to create a value for the @code{actions} slot of a
-service object @ref{Slots of services}. Each @var{name} is a symbol
-and each @var{proc} the corresponding procedure that will be called to
-perform the action. A @var{proc} has one argument, which will be the
-current value of the @code{running} slot of the service.
-@end deffn
-
-@deffn {method} start (obj <symbol>)
-Start a registered service providing @var{obj}.
-@end deffn
-
-@deffn {method} stop (obj <symbol>)
-Stop a registered service providing @var{obj}.
-@end deffn
-
-@deffn {method} action (obj <symbol>) the-action . args
-The same as the @code{action} method of class @code{<service>}, but
-uses a service that provides @var{obj} and is running.
-@end deffn
-
-@deffn {procedure} for-each-service proc
-Call @var{proc}, a procedure taking one argument, once for each
-registered service.
-@end deffn
-
-@deffn {procedure} find-running services
-Check if any of @var{services} is running. If this is the case,
-return its canonical name. If not, return @code{#f}. Only the first
-one will be returned; this is because this is mainly intended to be
-applied on the return value of @code{lookup-services}.
-@end deffn
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Service De- and Constructors
-@section Service De- and Constructors
-
-@cindex generating constructors
-@cindex generating destructors
-@cindex constructors, generation of
-@cindex destructors, generation of
-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] @
- [#:pid-file #f] @
- [#:directory (default-service-directory)] @
- [#:environment-variables (default-environment-variables)]
-Return a procedure that forks a child process, closes all file
-descriptors except the standard output and standard error descriptors, sets
-the current directory to @var{directory}, changes the environment to
-@var{environment-variables} (using the @code{environ} procedure), sets the
-current user to @var{user} and the current group to @var{group} unless they
-are @code{#f}, and executes @var{command} (a list of strings.) The result of
-the procedure will be the PID of the child process.
-
-When @var{pid-file} is true, it must be the name of a PID file
-associated with the process being launched; the return value is the PID
-read from that file, once that file has been created.
-@end deffn
-
-@deffn {procedure} make-kill-destructor [@var{signal}]
-Returns a procedure that sends @var{signal} to the pid which it takes
-as argument. This @emph{does} work together with respawning services,
-because in that case the @code{stop} method of the @code{<service>}
-class sets the @code{running} slot to @code{#f} before actually
-calling the destructor; if it would not do that, killing the process
-in the destructor would immediately respawn the service.
-@end deffn
-
-The @code{make-forkexec-constructor} procedure builds upon the following
-procedures.
-
-@deffn {procedure} exec-command @var{command} @
- [#:user #f] @
- [#:group #f] @
- [#:directory (default-service-directory)] @
- [#:environment-variables (default-environment-variables)]
-@deffnx {procedure} fork+exec-command @var{command} @
- [#:user #f] @
- [#:group #f] @
- [#:directory (default-service-directory)] @
- [#:environment-variables (default-environment-variables)]
-Run @var{command} as the current process from @var{directory}, and with
-@var{environment-variables} (a list of strings like @code{"PATH=/bin"}.)
-File descriptors 1 and 2 are kept as is, whereas file descriptor 0
-(standard input) points to @file{/dev/null}; all other file descriptors
-are closed prior to yielding control to @var{command}.
-
-By default, @var{command} is run as the current user. If the
-@var{user} keyword argument is present and not false, change to
-@var{user} immediately before invoking @var{command}. @var{user} may
-be a string, indicating a user name, or a number, indicating a user
-ID. Likewise, @var{command} will be run under the current group,
-unless the @var{group} keyword argument is present and not false.
-
-@code{fork+exec-command} does the same as @code{exec-command}, but in
-a separate process whose PID it returns.
-@end deffn
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Service Examples
-@section Service Examples
-
-FIXME: This needs a lot of work.
-
-You can create a service and then register it this way:
-
-@lisp
-(define apache (make <service>
- #:provides '(apache)
- #:start (...)
- #:stop (...)))
-(register-services apache)
-@end lisp
-
-However, as you usually won't need a variable for the service, you can
-pass it directly to @code{register-services}. Here is an example that
-also specifies some more initial values for the slots:
-
-@lisp
-(register-services
- (make <service>
- #:provides '(apache-2.0 apache httpd)
- #:requires '()
- #:start (...)
- #:stop (...)
- #:actions (make-actions
- (reload-modules (...))
- (restart (...)))))
-@end lisp
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node The root and unknown services
-@section The @code{root} and @code{unknown} services
-
-@cindex root service
-@cindex special services
-The service @code{root} is special, because it is used to control the
-Shepherd itself. It has an alias @code{shepherd}. It provides the
-following actions (in addition to @code{enable}, @code{disable} and
-@code{restart} which do not make sense here).
-
-@table @code
-@item status
-Displays which services are started and which ones are not.
-
-@item detailed-status
-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{--config} option of @command{shepherd} (@pxref{Invoking shepherd}).
-
-@item unload @var{service-name}
-Attempt to remove the service identified by @var{service-name}.
-@command{shepherd} will first stop the service, if necessary, and then
-remove it from the list of registered services. Any services
-depending upon @var{service-name} will be stopped as part of this
-process.
-
-If @var{service-name} simply does not exist, output a warning and do
-nothing. If it exists, but is provided by several services, output a
-warning and do nothing. This latter case might occur for instance with
-the fictional service @code{web-server}, which might be provided by both
-@code{apache} and @code{nginx}. If @var{service-name} is the special
-string and @code{all}, attempt to remove all services except for the Shepherd
-itself.
-
-@item reload @var{file-name}
-Unload all known optional services using unload's @code{all} option,
-then load @var{file-name} using @code{load} functionality. If
-file-name does not exist or @code{load} encounters an error, you may
-end up with no defined services. As these can be reloaded at a later
-stage this is not considered a problem. If the @code{unload} stage
-fails, @code{reload} will not attempt to load @var{file-name}.
-
-@item daemonize
-Fork and go into the background. This should be called before
-respawnable services are started, as otherwise we would not get the
-@code{SIGCHLD} signals when they terminate.
-
-@item enable-persistency
-When terminating, safe the list of running services in a file.
-@c FIXME-CRITICAL: How can we specify which one?
-
-@item disable-persistency
-Don't safe the list of running services when terminating.
-
-@end table
-
-@cindex unknown service
-@cindex fallback service
-The @code{unknown} service must be defined by the user and if it
-exists, is used as a fallback whenever we try to invoke an unknown
-action of an existing service or use a service that does not exist.
-This is useful only in few cases, but enables you to do various sorts
-of unusual things.
-
-@c FIXME-CRITICAL: finish
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Runlevels
-@chapter Runlevels
-
-RUNLEVELS DO NOT WORK YET! Do not use them! Ignore this section!
-
-@cindex runlevel
-@tindex <runlevel>
-A @dfn{runlevel} makes it easier to start and stop groups of services,
-to bring the system into a certain state. An object of class
-@code{<runlevel>} is an abstract runlevel, and has the following
-methods:
-
-@deffn {method} enter (rl <runlevel>) services
-This will be called when the runlevel should be entered.
-@var{services} is the list of the currently running services.
-@end deffn
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Misc Facilities
-@chapter Misc Facilities
-
-This is a list of facilities which are available to code running
-inside of the Shepherd and is considered generally useful, but is not directly
-related to one of the other topic covered in this manual.
-
-@menu
-* Errors:: Signalling, handling and ignoring errors.
-* Communication:: Input/Output in various ways.
-* Others:: Stuff that is useful, but is homeless.
-@end menu
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Errors
-@section Errors
-
-@cindex assertions
-@deffn {macro} assert expr
-If @var{expr} yields @code{#f}, display an appropriate error
-message and throw an @code{assertion-failed} exception.
-@end deffn
-
-@deffn {procedure} caught-error key args
-Tell the Shepherd that a @var{key} error with @var{args} has occured. This is
-the simplest way to cause caught error result in uniformly formated
-warning messages. The current implementation is not very good,
-though.
-@end deffn
-
-@deffn {procedure} call/cc proc
-An alias for @code{call-with-current-continuation}.
-@end deffn
-
-@deffn {procedure} call/ec proc
-A simplistic implementation of the nonstandard, but popular procedure
-@code{call-with-escape-continuation}, i.e. a @code{call/cc} for
-outgoing continuations only. Note that the variant included in the Shepherd is
-not aware of @code{dynamic-wind} at all and does not yet support
-returning multiple values.
-@end deffn
-
-@cindex system errors
-@deffn {macro} without-system-error expr@dots{}
-Evaluates the @var{expr}s, not going further if a system error occurs,
-but also doing nothing about it.
-@end deffn
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Communication
-@section Communication
-
-The @code{(shepherd comm)} module provides primitives that allow clients such
-as @command{herd} to connect to @command{shepherd} and send it commands to
-control or change its behavior (@pxref{Slots of services, actions of
-services}).
-
-@tindex <shepherd-command>
-Currently, clients may only send @dfn{commands}, represented by the
-@code{<shepherd-command>} type. Each command specifies a service it
-applies to, an action name, a list of strings to be used as arguments,
-and a working directory. Commands are instantiated with
-@code{shepherd-command}:
-
-@deffn {procedure} shepherd-command @var{action} @var{service} @
- [#:@var{arguments} '()] [#:@var{directory} (getcwd)]
-Return a new command (a @code{<shepherd-command>}) object for
-@var{action} on @var{service}.
-@end deffn
-
-@noindent
-Commands may then be written to or read from a communication channel
-with the following procedures:
-
-@deffn {procedure} write-command @var{command} @var{port}
-Write @var{command} to @var{port}.
-@end deffn
-
-@deffn {procedure} read-command @var{port}
-Receive a command from @var{port} and return it.
-@end deffn
-
-In practice, communication with @command{shepherd} takes place over a
-Unix-domain socket, as discussed earlier (@pxref{Invoking shepherd}).
-Clients may open a connection with the procedure below.
-
-@deffn {procedure} open-connection [@var{file}]
-Open a connection to the daemon, using the Unix-domain socket at
-@var{file}, and return the socket.
-
-When @var{file} is omitted, the default socket is used.
-@end deffn
-
-@cindex output
-The daemon writes output to be logged or passed to the
-currently-connected client using @code{local-output}:
-
-@deffn {procedure} local-output format-string . args
-This procedure should be used for all output operations in the Shepherd. It
-outputs the @var{args} according to the @var{format-string}, then
-inserts a newline. It writes to whatever is the main output target of
-the Shepherd, which might be multiple at the same time in future versions.
-@end deffn
-
-@cindex protocol, between @command{shepherd} and its clients
-Under the hood, @code{write-command} and @code{read-command} write/read
-commands as s-expressions (sexps). Each sexp is intelligible and
-specifies a protocol version. The idea is that users can write their
-own clients rather than having to invoke @command{herd}. For instance,
-when you type @command{herd status}, what is sent over the wire is the
-following sexp:
-
-@lisp
-(shepherd-command
- (version 0)
- (action status) (service root)
- (arguments ()) (directory "/data/src/dmd"))
-@end lisp
-
-The reply is also an sexp, along these lines:
-
-@lisp
-(reply (version 0)
- (result (((service @dots{}) @dots{})))
- (error #f) (messages ()))
-@end lisp
-
-This reply indicates that the @code{status} action was successful,
-because @code{error} is @code{#f}, and gives a list of sexps denoting
-the status of services as its @code{result}. The @code{messages} field
-is a possibly-empty list of strings meant to be displayed as is to the
-user.
-
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Others
-@section Others
-
-@cindex hashes
-@deffn {procedure} copy-hashq-table table new-size
-Create a hash-table with size @var{new-size}, and insert all values
-from @var{table} into it, using @code{eq?} when inserting. This
-procedure is mainly used internally, but is a generally useful
-utillity, so it can by used by everyone.
-@end deffn
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Internals
-@chapter Internals
-
-This chapter contains information about the design and the
-implementation details of the Shepherd for people who want to hack it.
-
-The GNU@tie{}Shepherd is developed by a group of people in connection
-with @uref{https://www.gnu.org/software/guix/, GuixSD}, GNU's advanced
-distribution, but it can be used on other distros as well. You're very
-much welcome to join us! You can report bugs to
-@email{bug-guix@@gnu.org} and send patches or suggestions to
-@email{guix-devel@@gnu.org}.
-
-@menu
-* Coding standards:: How to properly hack the Shepherd.
-* Design decisions:: Why the Shepherd is what it is.
-* Service Internals:: How services actually work.
-* Runlevel evolution:: Learning from past mistakes.
-@end menu
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Coding standards
-@section Coding standards
-
-About formatting: Use common sense and GNU Emacs (which actually is
-the same, of course), and you almost can't get the formatting wrong.
-Formatting should be as in Guile and Guix, basically. @xref{Coding
-Style,,, guix, GNU Guix Reference Manual}, for more info.
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Design decisions
-@section Design decisions
-
-@quotation Note
-This section was written by Wolfgang Jährling back in 2003 and documents
-the original design of what was then known as GNU@tie{}dmd. The main
-ideas remain valid but some implementation details and goals have
-changed.
-@end quotation
-
-The general idea of a service manager that uses dependencies, similar
-to those of a Makefile, came from the developers of the GNU Hurd, but
-as few people are satisfied with System V Init, many other people had
-the same idea independently. Nevertheless, the Shepherd was written with the
-goal of becoming a replacement for System V Init on GNU/Hurd, which
-was one of the reasons for choosing the extension language of the GNU
-project, Guile, for implementation (another reason being that it makes
-it just so much easier).
-
-The runlevel concept (i.e. thinking in @emph{groups} of services) is
-sometimes useful, but often one also wants to operate on single
-services. System V Init makes this hard: While you can start and stop
-a service, @code{init} will not know about it, and use the runlevel
-configuration as its source of information, opening the door for
-inconsistencies (which fortunatly are not a practical problem
-usually). In the Shepherd, this was avoided by having a central entity that is
-responsible for starting and stopping the services, which therefore
-knows which services are actually started (if not completely
-inproperly used, but that is a requirement which is impossible to
-avoid anyway). While runlevels are not implemented yet, it is clear
-that they will sit on top of the service concept, i.e. runlevels will
-merely be an optional extension that the service concept does not rely
-on. This also makes changes in the runlevel design easier when it may
-become necessary.
-
-The consequence of having a daemon running that controls the services
-is that we need another program as user interface which communicates
-with the daemon. Fortunatly, this makes the commands necessary for
-controlling services pretty short and intuitive, and gives the
-additional bonus of adding some more flexibility. For example, it is
-easiely possible to grant password-protected control over certain
-services to unprivileged users, if desired.
-
-An essential aspect of the design of the Shepherd (which was already mentioned
-above) is that it should always know exactly what is happening,
-i.e. which services are started and stopped. The alternative would
-have been to not use a daemon, but to save the state on the file
-system, again opening the door for inconsistencies of all sorts.
-Also, we would have to use a seperate program for respawning a service
-(which just starts the services, waits until it terminates and then
-starts it again). Killing the program that does the respawning (but
-not the service that is supposed to be respawned) would cause horrible
-confusion. My understanding of ``The Right Thing'' is that this
-conceptionally limited strategy is exactly what we do not want.
-
-The way dependencies work in the Shepherd took a while to mature, as it was not
-easy to figure out what is appropriate. I decided to not make it too
-sophisticated by trying to guess what the user might want just to
-theoretically fulfill the request we are processing. If something
-goes wrong, it is usually better to tell the user about the problem
-and let her fix it, taking care to make finding solutions or
-workarounds for problems (like a misconfigured service) easy. This
-way, the user is in control of what happens and we can keep the
-implementation simple. To make a long story short, @emph{we don't try
-to be too clever}, which is usually a good idea in developing
-software.
-
-If you wonder why I was giving a ``misconfigured service'' as an
-example above, consider the following situation, which actually is a
-wonderful example for what was said in the previous paragraph: Service
-X depends on symbol S, which is provided by both A and B. A depends
-on AA, B depends on BB. AA and BB conflict with each other. The
-configuration of A contains an error, which will prevent it from
-starting; no service is running, but we want to start X now. In
-resolving its dependencies, we first try to start A, which will cause
-AA to be started. After this is done, the attempt of starting A
-fails, so we go on to B, but its dependency BB will fail to start
-because it conflicts with the running service AA. So we fail to
-provide S, thus X cannot be started. There are several possibilities
-to deal with this:
-
-@itemize @bullet
-@item
-When starting A fails, terminate those services which have been
-started in order to fulfill its dependencies (directly and
-indirectly). In case AA was running already, we would not want to
-terminate it. Well, maybe we would, to avoid the conflict with BB.
-But even if we would find out somehow that we need to terminate AA to
-eventually start X, is the user aware of this and wants this to happen
-(assuming AA was running already)? Probably not, she very likely has
-assumed that starting A succeeds and thus terminating AA is not
-necessary. Remember, unrelated (running) services might depend in AA.
-Even if we ignore this issue, this strategy is not only complicated,
-but also far from being perfect: Let's assume starting A succeeds, but
-X also depends on a service Z, which requires BB. In that case, we
-would need to detect in the first place that we should not even try to
-start A, but directly satisfy X's dependency on S with B.
-
-@item
-We could do it like stated above, but stop AA only if we know we won't
-need it anymore (for resolving further dependencies), and start it
-only when it does not conflict with anything that needs to get
-started. But should we stop it if it conflicts with something that
-@emph{might} get started? (We do not always know for sure what we
-will start, as starting a service might fail and we want to fall back
-to a service that also provides the particular required symbol in that
-case.) I think that either decision will be bad in one case or
-another, even if this solution is already horribly complicated.
-
-@item
-When we are at it, we could just calculate a desired end-position, and
-try to get there by starting (and stopping!) services, recalculating
-what needs to be done whenever starting a service fails, also marking
-that particular service as unstartable, except if it fails to start
-because a dependency could not be resolved (or maybe even then?).
-This is even more complicated. Instead of implementing this and
-thereby producing code that (a) nobody understands, (b) certainly has
-a lot of bugs, (c) will be unmaintainable and (d) causes users to
-panic because they won't understand what will happen, I decided to do
-the following instead:
-
-@item
-Just report the error, and let the user fix it (in this case, fix the
-configuration of A) or work around it (in this case, disable A so that
-we won't start AA but directly go on to starting B).
-@end itemize
-
-I hope you can agree that the latter solution after all is the best
-one, because we can be sure to not do something that the user does not
-want us to do. Software should not run amok. This explanation was
-very long, but I think it was necessary to justify why the Shepherd uses a very
-primitive algorithm to resolve dependencies, despite the fact that it
-could theoretically be a bit more clever in certain situations.
-
-One might argue that it is possible to ask the user if the planned
-actions are ok with her, and if the plan changes ask again, but
-especially given that services are supposed to usually work, I see few
-reasons to make the source code of the Shepherd more complicated than
-necessary. If you volunteer to write @emph{and} maintain a more
-clever strategy (and volunteer to explain it to everyone who wants to
-understand it), you are welcome to do so, of course@dots{}
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Service Internals
-@section Service Internals
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Runlevel evolution
-@section Runlevel evolution
-
-@quotation Note
-This section was written by Wolfgang Jährling back in 2003 and is kept
-mostly for historians to read.
-@end quotation
-
-This section describes how the runlevel concept evolved over time.
-This is basically a collection of mistakes, but is provided here for
-your information, and possibly for your amusement, but I'm not sure if
-all this weird dependency stuff is really that funny.
-
-@menu
-* Runlevel assumptions:: What runlevels should be like
-* Runlevels - part one:: The first attempts of making it work
-* Runlevels - part two:: It should work... somehow...
-@end menu
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Runlevel assumptions
-@subsection Runlevel assumptions
-
-A runlevel is a system state, i.e. it consists of the information
-about which services are supposed to be available and which not. This
-vague definition implies that several different runlevel styles can be
-implemented in a service manager.
-
-For example, you can do it like System V Init, specifying which
-services should be started when we enter a runlevel and which ones
-should be stopped when leaving it. But one could also specify for
-every service in which runlevels it should be running.
-
-In the Shepherd, we do not want to limit ourselfes to a single runlevel style.
-We allow for all possible strategies to be implemented, providing the
-most useful ones as defaults. We also want to make it possible to
-combine the different styles arbitrariely.
-
-Therefore, when entering a runlevel, we call a user-defined piece of
-code, passing it the list of currently active services and expecting
-as the result a list of service symbols which tell us which services
-we want to have running. This interface makes it very easy to
-implement runlevel styles, but makes it not-so-easy for the runlevel
-implementation itself, because we have to get from the current state
-into a desired state, which might be more or less vague (since it is
-not required to be a list of canonical names). Obviously service
-conflicts and already running services need to be taken into account
-when deciding which services should be used to provide the various
-symbols.
-
-Also, the runlevel implementation should be implemented completely on
-top of the service concept, i.e. the service part should not depend on
-the idea of runlevels or care about them at all. Otherwise
-understanding the service part (which is the most essential aspect of
-the Shepherd) would become harder than necessary.
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Runlevels - part one
-@subsection Runlevels, part one
-
-I came up with the following method (here in Pseudo-Scheme), which is
-possibly slightly buggy, but should give you the idea:
-
-@lisp
-;; Beginning with the canonical names in CURRENT-SERVICES, start and
-;; stop services until getting into a state where everything requested
-;; in TARGET-SERVICES (which does not only consist of canonical names)
-;; is provided, and the things they depends on, but no more.
-(define (switch-runlevel current-services target-services)
- (let ((target-services-backup target-services)
- (unstartable '()))
- (let retry ()
- (repeat-until-none-of-these-changes-annythig
- ;; Replace all of them with canonical names which provide them.
- (canonicalize-names! target-services unstartable current-services)
- ;; Add what we need additionally.
- (add-dependencies! target-services unstartable current-services))
- (remove-redundancy! target-services)
- (stop-all-unneeded target-services)
- (catch 'service-could-not-be-started
- (lambda ()
- ;; Iterate over the list, starting only those which
- ;; have all dependencies already resolved, so nothing
- ;; we don't want will be started. Repeat until done.
- (carefully-start target-services))
- (lambda (key service)
- (set! unstartable (cons service unstartable))
- (set! target-services backup-target-services)
- (set! current-services (compute-current-services))
- (retry))))))
-@end lisp
-
-This indeed looks like a nice way to get what we want. However, the
-details of this are not as easy as it looks like. When replacing
-virtual services with canonical names, we have to be very careful.
-Consider the following situation:
-
-The virtual service X is provided by both A and B, while Y is provided
-only by B. We want to start C (which depends on X) and D (which
-depends on Y). Obviously we should use B to fulfill the dependency
-of C and D on X and Y, respectively. But when we see that we need
-something that provides X, we are likely to do the wrong thing: Select
-A. Thus, we need to clean this up later. I wanted to do this as
-follows:
-
-While substituting virtual services with canonical names, we also safe
-which one we selected to fulfill what, like this:
-
-@lisp
-((A . (X))
- (B . (Y)))
-@end lisp
-
-Later we look for conflicts, and as A and B conflict, we look which
-one can be removed (things they provide but are not required by anyone
-should be ignored, thus we need to create a list like the above). In
-this case, we can replace A with B as B also provides X (but A does
-not provide Y, thus the reverse is impossible). If both could be
-used, we probably should decide which one to use by looking at further
-conflicts, which gets pretty hairy. But, in this case, we are lucky
-and end up with this:
-
-@lisp
-((B . (X Y)))
-@end lisp
-
-This way of finding out which service we should use in case of
-conflicts sounds pretty sane, but if you think it will work well, you
-have been fooled, because actually it breaks horribly in the following
-situation:
-
-@multitable @columnfractions .10 .30
-@item Service @tab Provides
-@item A @tab @code{W X Y -}
-@item B @tab @code{W X - Z}
-@item C @tab @code{- X Y Z}
-@item D @tab @code{W - - -}
-@end multitable
-
-If we need all of W, X, Y and Z, then obviously we need to take C and
-D. But if we have a list like this, we cannot fix it:
-
-@lisp
-((A . (W X Y))
- (B . (Z)))
-@end lisp
-
-Thus, we cannot do it this way.
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Runlevels - part two
-@subsection Runlevels, part two
-
-Let's look again at the table at the end of part two:
-
-@multitable @columnfractions .10 .30
-@item Service @tab Provides
-@item A @tab @code{W X Y -}
-@item B @tab @code{W X - Z}
-@item C @tab @code{- X Y Z}
-@item D @tab @code{W - - -}
-@end multitable
-
-If from this table it is so obvious for us what we should do, then it
-should also be possible to calculate it for a computer, given such a
-table as input. Ok, we have to take into account conflicts that are
-not visible in this table, but the general idea is usable. But how do
-we find which combination works? I found only one way yet: Kind of a
-brute force attack: Try combinations until we find one that works.
-
-This alone would be too slow. With 20 services we would have 2^20
-possible combinations, that is a bit more than a million. Fortunatly,
-we can optimize this. First I thought we could remove all services
-from the list that do not provide any symbol we need, but that is
-obviously a stupid idea, as we might need them for dependencies, in
-which case we need to take into account their conflicts. But the
-following method would work:
-
-Very often a symbol that is required will be a canonical name already,
-i.e. be provided only by a single service. Using our example above,
-let's suppose we also need the symbol V, which is provided only by D.
-The first step we do is to look which (required) symbols are provided
-only by a single service, as we will need this service for sure. In
-this case, we would need D. But by using it, we would also get the
-other symbols it provides, W in this case. This means that we don't
-need to bother looking at other services that provide W, as we cannot
-use them because they conflict with a service that we definitely need.
-In this case, we can remove A and B from the list this way. Note that
-we can remove them entirely, as all their conflicts become irrelevant
-to us now. In this simple case we would not even have to do much
-else, C is the only remaining service.
-
-After this first step, there remain the symbols that are provided by
-two or more services. In every combination we try, exactly one of
-them must be used (and somehow we should take into account which
-services are running already). This also reduces the amount of
-possible combinations a lot. So what remains after that are the
-services we might need for fulfilling dependencies. For them, we
-could try all combinations (2^n), making sure that we always try
-subsets before any of their supersets to avoid starting unneeded
-services. We should take into account which services are already
-running as well.
-
-The remaining question is, what to do if starting a service fails. A
-simple solution would be to recursively remove all services that
-depend on it directly or indirectly. That might cause undesired
-side-effects, if a service was running but it had to be stopped
-because one of the services that provides something it depends on gets
-exchanged for another service that provides the same symbol, but fails
-to start. The fact that we would have to stop the (first) service is
-a problem on its own, though.
-
-
-@c *********************************************************************
-@node GNU Free Documentation License
-@appendix GNU Free Documentation License
-
-@include fdl-1.3.texi
-
-@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
-
-@node Concept Index
-@unnumbered Concept Index
-
-@printindex cp
-
-@node Procedure and Macro Index
-@unnumbered Procedure and Macro Index
-
-@printindex fn
-
-@node Variable Index
-@unnumbered Variable Index
-
-@printindex vr
-
-@node Type Index
-@unnumbered Type Index
-
-@printindex tp
-
-@bye
^ permalink raw reply related [flat|nested] 11+ messages in thread
* [Shepherd][PATCH 4/4] doc: Move man pages to the 'doc' directory.
2016-01-27 20:45 [Shepherd][PATCH 0/4] Move documentation to a 'doc' directory Mathieu Lirzin
` (2 preceding siblings ...)
2016-01-27 20:45 ` [Shepherd][PATCH 3/4] doc: Move manual to the 'doc' directory Mathieu Lirzin
@ 2016-01-27 20:45 ` Mathieu Lirzin
2016-01-27 22:57 ` Ludovic Courtès
3 siblings, 1 reply; 11+ messages in thread
From: Mathieu Lirzin @ 2016-01-27 20:45 UTC (permalink / raw)
To: guix-devel
[-- Attachment #1: Type: text/plain, Size: 396 bytes --]
* Makefile.am (man-page-target): Delete function.
(dist_man1_MANS, dist_man8_MANS): Prefix each element with 'doc/'.
(shepherd.1): Rename to ...
(doc/shepherd.1): ... this.
(doc/%.1, doc/%.8): New targets.
(gen_man): New variable.
* .gitignore: Update it.
---
.gitignore | 4 ++--
Makefile.am | 27 ++++++++++-----------------
2 files changed, 12 insertions(+), 19 deletions(-)
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0004-doc-Move-man-pages-to-the-doc-directory.patch --]
[-- Type: text/x-patch; name="0004-doc-Move-man-pages-to-the-doc-directory.patch", Size: 1833 bytes --]
diff --git a/.gitignore b/.gitignore
index 111817f..632dafe 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,8 +2,6 @@
*~
,*
.dirstamp
-/*.1
-/*.8
/INSTALL
/aclocal.m4
/autom4te.cache
@@ -13,6 +11,8 @@
/config.scm
/config.status
/configure
+/doc/*.1
+/doc/*.8
/doc/shepherd.info
/doc/stamp-vti
/doc/version.texi
diff --git a/Makefile.am b/Makefile.am
index 52f66d6..41c0f47 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -74,27 +74,20 @@ AM_V_HELP2MAN_ = $(AM_V_HELP2MAN_$(AM_DEFAULT_VERBOSITY))
AM_V_HELP2MAN_0 = @echo " HELP2MAN" $@;
HELP2MANFLAGS = --source=GNU --info-page=$(PACKAGE_TARNAME)
+gen_man = $(AM_V_HELP2MAN)LANGUAGE= $(HELP2MAN) $(HELP2MANFLAGS)
-define man-page-target
+doc/shepherd.1: modules/shepherd.scm
+ $(gen_man) --output="$@" "$(top_builddir)/`basename "$@" .1`"
-%.$(1): modules/shepherd/scripts/%.scm
- -$$(AM_V_HELP2MAN)LANGUAGE= \
- $(HELP2MAN) --output="$$@" --section=$(1) \
- $(HELP2MANFLAGS) \
- "$(top_builddir)/`basename "$$@" .$(1)`"
+doc/%.1: modules/shepherd/scripts/%.scm
+ $(gen_man) --output="$@" "$(top_builddir)/`basename "$@" .1`"
-endef
+doc/%.8: modules/shepherd/scripts/%.scm
+ $(gen_man) --section=8 --output="$@" \
+ "$(top_builddir)/`basename "$@" .8`"
-# Create targets for sections 1 and 8.
-$(eval $(foreach section,1 8,$(call man-page-target,$(section))))
-
-shepherd.1: modules/shepherd.scm
- -$(AM_V_HELP2MAN)LANGUAGE= \
- $(HELP2MAN) --output="$@" $(HELP2MANFLAGS) \
- "$(top_builddir)/shepherd"
-
-dist_man1_MANS = shepherd.1 herd.1
-dist_man8_MANS = halt.8 reboot.8
+dist_man1_MANS = doc/shepherd.1 doc/herd.1
+dist_man8_MANS = doc/halt.8 doc/reboot.8
# Things not automatically included in the distribution.
EXTRA_DIST = \
^ permalink raw reply related [flat|nested] 11+ messages in thread
* Re: [Shepherd][PATCH 1/4] build: Build Guile objects before generating man pages.
2016-01-27 20:45 ` [Shepherd][PATCH 1/4] build: Build Guile objects before generating man pages Mathieu Lirzin
@ 2016-01-27 22:55 ` Ludovic Courtès
2016-01-27 23:15 ` Mathieu Lirzin
0 siblings, 1 reply; 11+ messages in thread
From: Ludovic Courtès @ 2016-01-27 22:55 UTC (permalink / raw)
To: Mathieu Lirzin; +Cc: guix-devel
Mathieu Lirzin <mthl@gnu.org> skribis:
> Before that, man pages were not successfully generated for VPATH builds.
How so?
Ludo’.
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [Shepherd][PATCH 4/4] doc: Move man pages to the 'doc' directory.
2016-01-27 20:45 ` [Shepherd][PATCH 4/4] doc: Move man pages " Mathieu Lirzin
@ 2016-01-27 22:57 ` Ludovic Courtès
0 siblings, 0 replies; 11+ messages in thread
From: Ludovic Courtès @ 2016-01-27 22:57 UTC (permalink / raw)
To: Mathieu Lirzin; +Cc: guix-devel
Mathieu Lirzin <mthl@gnu.org> skribis:
> * Makefile.am (man-page-target): Delete function.
> (dist_man1_MANS, dist_man8_MANS): Prefix each element with 'doc/'.
> (shepherd.1): Rename to ...
> (doc/shepherd.1): ... this.
> (doc/%.1, doc/%.8): New targets.
> (gen_man): New variable.
> * .gitignore: Update it.
OK!
I thought removing the function might increase duplication, but the way
you did it does not.
Ludo’.
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [Shepherd][PATCH 2/4] doc: Move examples to the 'doc/examples' directory.
2016-01-27 20:45 ` [Shepherd][PATCH 2/4] doc: Move examples to the 'doc/examples' directory Mathieu Lirzin
@ 2016-01-27 22:57 ` Ludovic Courtès
0 siblings, 0 replies; 11+ messages in thread
From: Ludovic Courtès @ 2016-01-27 22:57 UTC (permalink / raw)
To: Mathieu Lirzin; +Cc: guix-devel
Mathieu Lirzin <mthl@gnu.org> skribis:
> * doc/examples/README: moved from 'examples' directory.
> * doc/examples/_unknown.scm: Likewise.
> * doc/examples/wolfgangj.scm: Likewise.
> * examples/Makefile.am: Delete file.
> * configure.ac (AC_CONFIG_FILES): Adapt to it.
> * Makefile.am (EXTRA_DIST): Add files from "doc/examples" directory.
> (SUBDIRS): Delete variable.
OK!
Ludo'.
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [Shepherd][PATCH 3/4] doc: Move manual to the 'doc' directory.
2016-01-27 20:45 ` [Shepherd][PATCH 3/4] doc: Move manual to the 'doc' directory Mathieu Lirzin
@ 2016-01-27 22:58 ` Ludovic Courtès
0 siblings, 0 replies; 11+ messages in thread
From: Ludovic Courtès @ 2016-01-27 22:58 UTC (permalink / raw)
To: Mathieu Lirzin; +Cc: guix-devel
Mathieu Lirzin <mthl@gnu.org> skribis:
> * doc/shepherd.texi: Moved from the root directory.
> * doc/fdl-1.3.texi: Likewise.
> * Makefile.am (info_TEXINFOS): Add a 'doc/' prefix to 'shepherd.texi'.
> (EXTRA_DIST): Remove 'fdl-1.3.texi'.
> (doc_shepherd_TEXINFOS): New variable.
> * .gitignore: Update it.
OK! An improvement I had been contemplating for some time… ;-)
Thanks,
Ludo'.
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [Shepherd][PATCH 1/4] build: Build Guile objects before generating man pages.
2016-01-27 22:55 ` Ludovic Courtès
@ 2016-01-27 23:15 ` Mathieu Lirzin
2016-01-28 9:09 ` Ludovic Courtès
0 siblings, 1 reply; 11+ messages in thread
From: Mathieu Lirzin @ 2016-01-27 23:15 UTC (permalink / raw)
To: Ludovic Courtès; +Cc: guix-devel
ludo@gnu.org (Ludovic Courtès) writes:
> Mathieu Lirzin <mthl@gnu.org> skribis:
>
>> Before that, man pages were not successfully generated for VPATH builds.
>
> How so?
Using commit bc7757cd1f3d0a162e765d0ecebde052765a6a23:
--8<---------------cut here---------------start------------->8---
mthl@godel:~/src/shepherd$ git clean -xdf
[...]
mthl@godel:~/src/shepherd$ autoreconf -vfi
autoreconf: Entering directory `.'
autoreconf: configure.ac: not using Gettext
autoreconf: running: aclocal --force
autoreconf: configure.ac: tracing
autoreconf: configure.ac: not using Libtool
autoreconf: running: /usr/bin/autoconf --force
autoreconf: configure.ac: not using Autoheader
autoreconf: running: automake --add-missing --copy --force-missing
Unescaped left brace in regex is deprecated, passed through in regex; marked by <-- HERE in m/\${ <-- HERE ([^ \t=:+{}]+)}/ at /usr/bin/automake line 3936.
configure.ac:53: installing 'build-aux/compile'
configure.ac:17: installing 'build-aux/config.guess'
configure.ac:17: installing 'build-aux/config.sub'
configure.ac:11: installing 'build-aux/install-sh'
configure.ac:11: installing 'build-aux/missing'
Makefile.am: installing './INSTALL'
Makefile.am:65: installing 'build-aux/mdate-sh'
Makefile.am:65: installing 'build-aux/texinfo.tex'
parallel-tests: installing 'build-aux/test-driver'
autoreconf: Leaving directory `.'
mthl@godel:~/src/shepherd$ mkdir bd
mthl@godel:~/src/shepherd$ cd bd
mthl@godel:~/src/shepherd/bd$ ../configure
[...]
configure: creating ./config.status
config.status: creating Makefile
config.status: creating examples/Makefile
config.status: creating modules/shepherd/system.scm
config.status: executing depfiles commands
mthl@godel:~/src/shepherd/bd$ make
/bin/mkdir -p "`dirname modules/shepherd/config.scm`"
/bin/sed -e 's,%PREFIX%,/usr/local,g' -e 's,%modsrcdir%,/home/mthl/src/shepherd/bd/../modules,g' -e 's,%modbuilddir%,/home/mthl/src/shepherd/bd/modules,g' -e 's,%localstatedir%,/usr/local/var,g' -e 's,%sysconfdir%,/usr/local/etc,g' -e 's,%VERSION%,0.3,g' -e 's,%PACKAGE_BUGREPORT%,bug-guix@gnu.org,g' -e 's,%PACKAGE_NAME%,GNU Shepherd,g' -e 's,%PACKAGE_URL%,http://www.gnu.org/software/shepherd/,g' -e 's,%GUILE%,/usr/bin/guile,g' < ../modules/shepherd/config.scm.in >modules/shepherd/config.scm
make all-recursive
make[1]: Entering directory '/home/mthl/src/shepherd/bd'
Making all in examples
make[2]: Entering directory '/home/mthl/src/shepherd/bd/examples'
make[2]: Nothing to be done for 'all'.
make[2]: Leaving directory '/home/mthl/src/shepherd/bd/examples'
make[2]: Entering directory '/home/mthl/src/shepherd/bd'
Updating ../version.texi
MAKEINFO ../shepherd.info
GEN shepherd
GEN herd
GEN halt
GEN reboot
HELP2MAN shepherd.1
help2man: impossible de récupérer l'information « --help » de ./shepherd
Try `--no-discard-stderr' if option outputs to stderr
Makefile:1943: recipe for target 'shepherd.1' failed
make[2]: [shepherd.1] Error 1 (ignorée)
HELP2MAN herd.1
help2man: impossible de récupérer l'information « --help » de ./herd
Try `--no-discard-stderr' if option outputs to stderr
Makefile:1940: recipe for target 'herd.1' failed
make[2]: [herd.1] Error 1 (ignorée)
HELP2MAN halt.8
help2man: impossible de récupérer l'information « --help » de ./halt
Try `--no-discard-stderr' if option outputs to stderr
Makefile:1940: recipe for target 'halt.8' failed
make[2]: [halt.8] Error 1 (ignorée)
HELP2MAN reboot.8
help2man: impossible de récupérer l'information « --help » de ./reboot
Try `--no-discard-stderr' if option outputs to stderr
Makefile:1940: recipe for target 'reboot.8' failed
make[2]: [reboot.8] Error 1 (ignorée)
GUILEC modules/shepherd.go
GUILEC modules/shepherd/scripts/halt.go
GUILEC modules/shepherd/scripts/herd.go
GUILEC modules/shepherd/scripts/reboot.go
GUILEC modules/shepherd/config.go
GUILEC modules/shepherd/system.go
GUILEC modules/shepherd/args.go
GUILEC modules/shepherd/service.go
GUILEC modules/shepherd/support.go
../modules/shepherd/support.scm:203:2: warning: non-literal format string
GUILEC modules/shepherd/runlevel.go
../modules/shepherd/runlevel.scm:106:6: warning: possibly unbound variable `next-services'
GUILEC modules/shepherd/comm.go
make[2]: Leaving directory '/home/mthl/src/shepherd/bd'
make[1]: Leaving directory '/home/mthl/src/shepherd/bd'
mthl@godel:~/src/shepherd/bd$
--8<---------------cut here---------------end--------------->8---
Another iteration of ‘make’ is required to build the man pages.
I think this is important enough to be fixed before the release. ;)
--
Mathieu Lirzin.
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [Shepherd][PATCH 1/4] build: Build Guile objects before generating man pages.
2016-01-27 23:15 ` Mathieu Lirzin
@ 2016-01-28 9:09 ` Ludovic Courtès
0 siblings, 0 replies; 11+ messages in thread
From: Ludovic Courtès @ 2016-01-28 9:09 UTC (permalink / raw)
To: Mathieu Lirzin; +Cc: guix-devel
Mathieu Lirzin <mthl@gnu.org> skribis:
> GEN shepherd
> GEN herd
> GEN halt
> GEN reboot
> HELP2MAN shepherd.1
> help2man: impossible de récupérer l'information « --help » de ./shepherd
> Try `--no-discard-stderr' if option outputs to stderr
> Makefile:1943: recipe for target 'shepherd.1' failed
> make[2]: [shepherd.1] Error 1 (ignorée)
[...]
> Another iteration of ‘make’ is required to build the man pages.
Thanks for explaining!
This is weird, I don’t understand why that happens. I can’t even
reproduce it:
--8<---------------cut here---------------start------------->8---
ludo@pluto /tmp$ git clone /data/src/dmd/
Cloning into 'dmd'...
done.
ludo@pluto /tmp$ cd dmd/
ludo@pluto /tmp/dmd$ autoreconf -vfi
autoreconf: Entering directory `.'
autoreconf: configure.ac: not using Gettext
autoreconf: running: aclocal --force
autoreconf: configure.ac: tracing
autoreconf: configure.ac: not using Libtool
autoreconf: running: /gnu/store/w29nf3k2yclf7b33i8iibblj67687my2-autoconf-2.69/bin/autoconf --force
autoreconf: configure.ac: not using Autoheader
autoreconf: running: automake --add-missing --copy --force-missing
configure.ac:53: installing 'build-aux/compile'
configure.ac:17: installing 'build-aux/config.guess'
configure.ac:17: installing 'build-aux/config.sub'
configure.ac:11: installing 'build-aux/install-sh'
configure.ac:11: installing 'build-aux/missing'
Makefile.am: installing './INSTALL'
Makefile.am:65: installing 'build-aux/mdate-sh'
Makefile.am:65: installing 'build-aux/texinfo.tex'
parallel-tests: installing 'build-aux/test-driver'
autoreconf: Leaving directory `.'
ludo@pluto /tmp/dmd$ mkdir +build
ludo@pluto /tmp/dmd$ cd +build/
ludo@pluto /tmp/dmd/+build$ ../configure -C && make -j4 V=1
configure: creating cache config.cache
checking for a BSD-compatible install... /run/current-system/profile/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... /run/current-system/profile/bin/mkdir -p
checking for gawk... gawk
checking whether make sets $(MAKE)... yes
checking whether make supports nested variables... yes
checking whether make supports nested variables... (cached) yes
checking build system type... x86_64-unknown-linux-gnu
checking host system type... x86_64-unknown-linux-gnu
checking for a sed that does not truncate output... /run/current-system/profile/bin/sed
checking for guile... /home/ludo/soft/bin/guile
checking for Guile version >= 2.0... 2.0.11
checking for guild... /home/ludo/soft/bin/guild
checking for guile-config... /home/ludo/soft/bin/guile-config
checking whether it is Guile 2.0... yes
checking for guild... (cached) /home/ludo/soft/bin/guild
checking for gcc... gcc
checking whether the C compiler works... yes
checking for C compiler default output file name... a.out
checking for suffix of executables...
checking whether we are cross compiling... no
checking for suffix of object files... o
checking whether we are using the GNU C compiler... yes
checking whether gcc accepts -g... yes
checking for gcc option to accept ISO C89... none needed
checking whether gcc understands -c and -o together... yes
checking for style of include used by make... GNU
checking dependency style of gcc... none
checking the '_SC_OPEN_MAX' value... 4
checking <sys/reboot.h> constants... done
configure: updating cache config.cache
checking that generated files are newer than configure... done
configure: creating ./config.status
config.status: creating Makefile
config.status: creating modules/shepherd/system.scm
config.status: executing depfiles commands
/run/current-system/profile/bin/mkdir -p "`dirname modules/shepherd/config.scm`"
/run/current-system/profile/bin/sed -e 's,%PREFIX%,/usr/local,g' -e 's,%modsrcdir%,/tmp/dmd/+build/../modules,g' -e 's,%modbuilddir%,/tmp/dmd/+build/modules,g' -e 's,%localstatedir%,/usr/local/var,g' -e 's,%sysconfdir%,/usr/local/etc,g' -e 's,%VERSION%,0.3,g' -e 's,%PACKAGE_BUGREPORT%,bug-guix@gnu.org,g' -e 's,%PACKAGE_NAME%,GNU Shepherd,g' -e 's,%PACKAGE_URL%,http://www.gnu.org/software/shepherd/,g' -e 's,%GUILE%,/home/ludo/soft/bin/guile,g' < ../modules/shepherd/config.scm.in >modules/shepherd/config.scm
make all-am
make[1]: Entering directory '/tmp/dmd/+build'
/run/current-system/profile/bin/mkdir -p "`dirname shepherd`" ; \
/run/current-system/profile/bin/sed -e 's,%PREFIX%,/usr/local,g' -e 's,%modsrcdir%,/tmp/dmd/+build/../modules,g' -e 's,%modbuilddir%,/tmp/dmd/+build/modules,g' -e 's,%localstatedir%,/usr/local/var,g' -e 's,%sysconfdir%,/usr/local/etc,g' -e 's,%VERSION%,0.3,g' -e 's,%PACKAGE_BUGREPORT%,bug-guix@gnu.org,g' -e 's,%PACKAGE_NAME%,GNU Shepherd,g' -e 's,%PACKAGE_URL%,http://www.gnu.org/software/shepherd/,g' -e 's,%GUILE%,/home/ludo/soft/bin/guile,g' < ../shepherd.in >shepherd ; \
chmod +x shepherd
/run/current-system/profile/bin/mkdir -p "`dirname herd`" ; \
/run/current-system/profile/bin/sed -e 's,%PREFIX%,/usr/local,g' -e 's,%modsrcdir%,/tmp/dmd/+build/../modules,g' -e 's,%modbuilddir%,/tmp/dmd/+build/modules,g' -e 's,%localstatedir%,/usr/local/var,g' -e 's,%sysconfdir%,/usr/local/etc,g' -e 's,%VERSION%,0.3,g' -e 's,%PACKAGE_BUGREPORT%,bug-guix@gnu.org,g' -e 's,%PACKAGE_NAME%,GNU Shepherd,g' -e 's,%PACKAGE_URL%,http://www.gnu.org/software/shepherd/,g' -e 's,%GUILE%,/home/ludo/soft/bin/guile,g' < ../herd.in >herd ; \
chmod +x herd
/run/current-system/profile/bin/mkdir -p "`dirname halt`" ; \
/run/current-system/profile/bin/sed -e 's,%PREFIX%,/usr/local,g' -e 's,%modsrcdir%,/tmp/dmd/+build/../modules,g' -e 's,%modbuilddir%,/tmp/dmd/+build/modules,g' -e 's,%localstatedir%,/usr/local/var,g' -e 's,%sysconfdir%,/usr/local/etc,g' -e 's,%VERSION%,0.3,g' -e 's,%PACKAGE_BUGREPORT%,bug-guix@gnu.org,g' -e 's,%PACKAGE_NAME%,GNU Shepherd,g' -e 's,%PACKAGE_URL%,http://www.gnu.org/software/shepherd/,g' -e 's,%GUILE%,/home/ludo/soft/bin/guile,g' < ../halt.in >halt ; \
chmod +x halt
make[2]: Entering directory '/tmp/dmd/+build'
/run/current-system/profile/bin/mkdir -p "`dirname reboot`" ; \
/run/current-system/profile/bin/sed -e 's,%PREFIX%,/usr/local,g' -e 's,%modsrcdir%,/tmp/dmd/+build/../modules,g' -e 's,%modbuilddir%,/tmp/dmd/+build/modules,g' -e 's,%localstatedir%,/usr/local/var,g' -e 's,%sysconfdir%,/usr/local/etc,g' -e 's,%VERSION%,0.3,g' -e 's,%PACKAGE_BUGREPORT%,bug-guix@gnu.org,g' -e 's,%PACKAGE_NAME%,GNU Shepherd,g' -e 's,%PACKAGE_URL%,http://www.gnu.org/software/shepherd/,g' -e 's,%GUILE%,/home/ludo/soft/bin/guile,g' < ../reboot.in >reboot ; \
chmod +x reboot
LANGUAGE= /bin/sh /tmp/dmd/build-aux/missing help2man --source=GNU --info-page=shepherd --output="doc/shepherd.1" "./`basename "doc/shepherd.1" .1`"
LANGUAGE= /bin/sh /tmp/dmd/build-aux/missing help2man --source=GNU --info-page=shepherd --output="doc/herd.1" "./`basename "doc/herd.1" .1`"
make[2]: Leaving directory '/tmp/dmd/+build'
LANGUAGE= /bin/sh /tmp/dmd/build-aux/missing help2man --source=GNU --info-page=shepherd --section=8 --output="doc/halt.8" \
"./`basename "doc/halt.8" .8`"
Updating ../doc/version.texi
LANGUAGE= /bin/sh /tmp/dmd/build-aux/missing help2man --source=GNU --info-page=shepherd --section=8 --output="doc/reboot.8" \
"./`basename "doc/reboot.8" .8`"
/run/current-system/profile/bin/mkdir -p "`dirname "modules/shepherd.go"`" ; \
: && out=1 || out=- ; \
unset GUILE_LOAD_COMPILED_PATH ; LC_ALL=C \
/home/ludo/soft/bin/guild compile --target="x86_64-unknown-linux-gnu" \
-L "./modules" \
-L "../modules" \
-Wformat -Wunbound-variable -Warity-mismatch \
-o "modules/shepherd.go" "../modules/shepherd.scm" >&$out
/run/current-system/profile/bin/mkdir -p "`dirname "modules/shepherd/scripts/halt.go"`" ; \
: && out=1 || out=- ; \
unset GUILE_LOAD_COMPILED_PATH ; LC_ALL=C \
/home/ludo/soft/bin/guild compile --target="x86_64-unknown-linux-gnu" \
-L "./modules" \
-L "../modules" \
-Wformat -Wunbound-variable -Warity-mismatch \
-o "modules/shepherd/scripts/halt.go" "../modules/shepherd/scripts/halt.scm" >&$out
/run/current-system/profile/bin/mkdir -p "`dirname "modules/shepherd/scripts/herd.go"`" ; \
: && out=1 || out=- ; \
unset GUILE_LOAD_COMPILED_PATH ; LC_ALL=C \
/home/ludo/soft/bin/guild compile --target="x86_64-unknown-linux-gnu" \
-L "./modules" \
-L "../modules" \
-Wformat -Wunbound-variable -Warity-mismatch \
-o "modules/shepherd/scripts/herd.go" "../modules/shepherd/scripts/herd.scm" >&$out
wrote `modules/shepherd/scripts/halt.go'
/run/current-system/profile/bin/mkdir -p "`dirname "modules/shepherd/scripts/reboot.go"`" ; \
: && out=1 || out=- ; \
unset GUILE_LOAD_COMPILED_PATH ; LC_ALL=C \
/home/ludo/soft/bin/guild compile --target="x86_64-unknown-linux-gnu" \
-L "./modules" \
-L "../modules" \
-Wformat -Wunbound-variable -Warity-mismatch \
-o "modules/shepherd/scripts/reboot.go" "../modules/shepherd/scripts/reboot.scm" >&$out
/run/current-system/profile/bin/mkdir -p "`dirname "modules/shepherd/config.go"`" ; \
: && out=1 || out=- ; \
unset GUILE_LOAD_COMPILED_PATH ; LC_ALL=C \
/home/ludo/soft/bin/guild compile --target="x86_64-unknown-linux-gnu" \
-L "./modules" \
-L "../modules" \
-Wformat -Wunbound-variable -Warity-mismatch \
-o "modules/shepherd/config.go" "modules/shepherd/config.scm" >&$out
wrote `modules/shepherd.go'
/run/current-system/profile/bin/mkdir -p "`dirname "modules/shepherd/system.go"`" ; \
: && out=1 || out=- ; \
unset GUILE_LOAD_COMPILED_PATH ; LC_ALL=C \
/home/ludo/soft/bin/guild compile --target="x86_64-unknown-linux-gnu" \
-L "./modules" \
-L "../modules" \
-Wformat -Wunbound-variable -Warity-mismatch \
-o "modules/shepherd/system.go" "modules/shepherd/system.scm" >&$out
wrote `modules/shepherd/config.go'
/run/current-system/profile/bin/mkdir -p "`dirname "modules/shepherd/args.go"`" ; \
: && out=1 || out=- ; \
unset GUILE_LOAD_COMPILED_PATH ; LC_ALL=C \
/home/ludo/soft/bin/guild compile --target="x86_64-unknown-linux-gnu" \
-L "./modules" \
-L "../modules" \
-Wformat -Wunbound-variable -Warity-mismatch \
-o "modules/shepherd/args.go" "../modules/shepherd/args.scm" >&$out
wrote `modules/shepherd/scripts/herd.go'
/run/current-system/profile/bin/mkdir -p "`dirname "modules/shepherd/service.go"`" ; \
: && out=1 || out=- ; \
unset GUILE_LOAD_COMPILED_PATH ; LC_ALL=C \
/home/ludo/soft/bin/guild compile --target="x86_64-unknown-linux-gnu" \
-L "./modules" \
-L "../modules" \
-Wformat -Wunbound-variable -Warity-mismatch \
-o "modules/shepherd/service.go" "../modules/shepherd/service.scm" >&$out
wrote `modules/shepherd/system.go'
/run/current-system/profile/bin/mkdir -p "`dirname "modules/shepherd/support.go"`" ; \
: && out=1 || out=- ; \
unset GUILE_LOAD_COMPILED_PATH ; LC_ALL=C \
/home/ludo/soft/bin/guild compile --target="x86_64-unknown-linux-gnu" \
-L "./modules" \
-L "../modules" \
-Wformat -Wunbound-variable -Warity-mismatch \
-o "modules/shepherd/support.go" "../modules/shepherd/support.scm" >&$out
wrote `modules/shepherd/scripts/reboot.go'
/run/current-system/profile/bin/mkdir -p "`dirname "modules/shepherd/runlevel.go"`" ; \
: && out=1 || out=- ; \
unset GUILE_LOAD_COMPILED_PATH ; LC_ALL=C \
/home/ludo/soft/bin/guild compile --target="x86_64-unknown-linux-gnu" \
-L "./modules" \
-L "../modules" \
-Wformat -Wunbound-variable -Warity-mismatch \
-o "modules/shepherd/runlevel.go" "../modules/shepherd/runlevel.scm" >&$out
wrote `modules/shepherd/args.go'
/run/current-system/profile/bin/mkdir -p "`dirname "modules/shepherd/comm.go"`" ; \
: && out=1 || out=- ; \
unset GUILE_LOAD_COMPILED_PATH ; LC_ALL=C \
/home/ludo/soft/bin/guild compile --target="x86_64-unknown-linux-gnu" \
-L "./modules" \
-L "../modules" \
-Wformat -Wunbound-variable -Warity-mismatch \
-o "modules/shepherd/comm.go" "../modules/shepherd/comm.scm" >&$out
../modules/shepherd/support.scm:204:2: warning: non-literal format string
wrote `modules/shepherd/support.go'
restore=: && backupdir=".am$$" && \
am__cwd=`pwd` && CDPATH="${ZSH_VERSION+.}:" && cd .. && \
rm -rf $backupdir && mkdir $backupdir && \
if (/bin/sh /tmp/dmd/build-aux/missing makeinfo --version) >/dev/null 2>&1; then \
for f in ../doc/shepherd.info ../doc/shepherd.info-[0-9] ../doc/shepherd.info-[0-9][0-9] ../doc/shepherd.i[0-9] ../doc/shepherd.i[0-9][0-9]; do \
if test -f $f; then mv $f $backupdir; restore=mv; else :; fi; \
done; \
else :; fi && \
cd "$am__cwd"; \
if /bin/sh /tmp/dmd/build-aux/missing makeinfo -I doc -I ../doc \
-o ../doc/shepherd.info ../doc/shepherd.texi; \
then \
rc=0; \
CDPATH="${ZSH_VERSION+.}:" && cd ..; \
else \
rc=$?; \
CDPATH="${ZSH_VERSION+.}:" && cd .. && \
$restore $backupdir/* `echo "./../doc/shepherd.info" | sed 's|[^/]*$||'`; \
fi; \
rm -rf $backupdir; exit $rc
../modules/shepherd/runlevel.scm:106:6: warning: possibly unbound variable `next-services'
wrote `modules/shepherd/runlevel.go'
wrote `modules/shepherd/comm.go'
wrote `modules/shepherd/service.go'
make[1]: Leaving directory '/tmp/dmd/+build'
ludo@pluto /tmp/dmd/+build$ git describe
v0.2-109-gcc6ba32
ludo@pluto /tmp/dmd/+build$ ls doc/*.[18]
doc/halt.8 doc/herd.1 doc/reboot.8 doc/shepherd.1
--8<---------------cut here---------------end--------------->8---
(There’s the problem that man pages end up in $builddir instead of
$srcdir; oh well.)
> I think this is important enough to be fixed before the release. ;)
I think it’s OK because people building from the tarball won’t have this
problem since man pages are included in the tarball.
So I’m punting on this for now, and I suggest that we keep investigating
after the release.
Thank you,
Ludo’.
^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2016-01-28 9:09 UTC | newest]
Thread overview: 11+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-01-27 20:45 [Shepherd][PATCH 0/4] Move documentation to a 'doc' directory Mathieu Lirzin
2016-01-27 20:45 ` [Shepherd][PATCH 1/4] build: Build Guile objects before generating man pages Mathieu Lirzin
2016-01-27 22:55 ` Ludovic Courtès
2016-01-27 23:15 ` Mathieu Lirzin
2016-01-28 9:09 ` Ludovic Courtès
2016-01-27 20:45 ` [Shepherd][PATCH 2/4] doc: Move examples to the 'doc/examples' directory Mathieu Lirzin
2016-01-27 22:57 ` Ludovic Courtès
2016-01-27 20:45 ` [Shepherd][PATCH 3/4] doc: Move manual to the 'doc' directory Mathieu Lirzin
2016-01-27 22:58 ` Ludovic Courtès
2016-01-27 20:45 ` [Shepherd][PATCH 4/4] doc: Move man pages " Mathieu Lirzin
2016-01-27 22:57 ` Ludovic Courtès
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/guix.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).