at: sd: clean up, document

3 files changed, 188 insertions, 38 deletions

diff --git a/build-aux/Makefile.once.head/00-amcfg.mk b/build-aux/Makefile.once.head/20-amcfg.mk
index e2610b4be5..0a16c148a2 100644
--- a/build-aux/Makefile.once.head/00-amcfg.mk
+++ b/build-aux/Makefile.once.head/20-amcfg.mk
@@ -1,9 +1,24 @@
 mod.amcfg.description = (systemd) Automake-to-Autothing configuration
 mod.amcfg.depends += am
 define mod.amcfg.doc
-# User varaibles:
+# User variables:
 #   - `V`
 #   - `AM_V_*`
+#   - `pamconfdir`
+#   - `tmpfilesdir`
+#   - `sysusersdir`
+#   - `sysctldir`
+#   - `bashcompletiondir`
+#   - `zshcompletiondir`
+#   - `LIBTOOL`
+#   - `INSTALL_PROGRAM`
+#   - `INSTALL_SCRIPT`
+#   - `INSTALL_DATA`
+# Inputs:
+#   - Global variable: `sd.ALL_LIBTOOLFLAGS`
+# Outputs:
+#   - Global variable: `am.sys2out_*`
+#   - Global variable: `am.INSTALL_*`
 endef
 mod.amcfg.doc := $(value mod.amcfg.doc)
 
diff --git a/build-aux/Makefile.once.head/20-sd.mk b/build-aux/Makefile.once.head/20-sd.mk
index 545071d233..4e44d2f7b3 100644
--- a/build-aux/Makefile.once.head/20-sd.mk
+++ b/build-aux/Makefile.once.head/20-sd.mk
@@ -23,8 +23,81 @@
 
 mod.sd.description = (systemd) shared build rules
 mod.sd.depends += am
+define mod.sd.doc
+# User variables:
+#   (flags)
+#   - `CFLAGS`
+#   - `CPPFLAGS`
+#   - `LDFLAGS`
+#   - `LIBTOOLFLAGS`
+#   (programs)
+#   - `CC`
+#   - `CCLD`
+#   - `LIBTOOL`
+#   - `MKDIR_P`
+#   - `SED`
+#   (verbosity)
+#   - `V`
+#   - `AM_V_*`
+#   - `INTLTOOL_V_MERGE*`
+#   (substitutions)$(foreach v,$(sort $(sd.substitution_keys)),$(at.nl)#   - $v)
+# Inputs:
+#   - Global variable    : `DEPDIR`
+#   - Global variable    : `ENABLE_TESTS`
+#   - Global variable    : `ENABLE_UNSAFE_TESTS`
+#   - Global variable    : `OUR_CFLAGS`
+#   - Global variable    : `OUR_CPPFLAGS`
+#   - Global variable    : `OUR_LDFLAGS`
+#   - Global variable    : `OUR_LIBTOOLFLAGS`
+#   (Makefiles)
+#   - Directory variable : `sd.CFLAGS`
+#   - Directory variable : `sd.CPPFLAGS`
+#   - Directory variable : `sd.LDFLAGS`
+#   - Directory variable : `sd.LIBTOOLFLAGS`
+#   - Directory variable : `sd.sed_files` (default based on `EXTRA_DIST`)
+#   (am)
+#   - Directory variable : `EXTRA_DIST`
+#   - Directory variable : `am.out_PROGRAMS`
+#   - Directory variable : `am.CFLAGS`
+#   - Directory variable : `am.CPPFLAGS`
+#   - Target variable    : `am.LDFLAGS`
+# Outputs:
+#   - Global variable    : `SHELL`
+#   - Make setting       : `.DELETE_ON_ERROR`
+#   - Make setting       : `.SECONDARY`
+#   - Global variable    : `sd.substitutions`
+#   - Global variable    : `sd.substitution_keys`
+#   - Global variable    : `sd.sed_process`
+#   - Directory variable : `files.out.int`
+#   - Target variable    : `sd.ALL_CFLAGS`
+#   - Target variable    : `sd.ALL_CPPFLAGS`
+#   - Target variable    : `sd.ALL_LDFLAGS`
+#   - Target variable    : `sd.ALL_LIBTOLFLAGS`
+#   - Target variable    : `sd.COMPILE`
+#   - Target variable    : `sd.LTCOMPILE`
+#   - Target variable    : `sd.LINK`
+#   - Target             : `$$(outdir)/%.o`
+#   - Target             : `$$(outdir)/%.lo`
+#   - Target             : `$$(outdir)/$$(DEPDIR)`
+#   - Target             : `$$(outdir)/%.la`
+#   - Target             : `$$(addprefix $$(outdir)/,$$(am.out_PROGRAMS))`
+#   - Target             : `$$(outdir)/test-lib%-sym.c`
+#   - Target             : `$$(outdir)/%-from-name.gperf`
+#   - Target             : `$$(outdir)/%-from-name.h`
+#   - Target             : `$$(addprefix $$(outdir)/,$$(sd.sed_files))`
+#   - Target             : `$$(outdir)/%.c: $$(srcdir)/%.gperf`
+#   - Target             : `$$(outdir)/%: $$(srcdir)/%.m4`
+# ???:
+#   - tests
+#   - unsafe_tests
+#   - TESTS
 
-TESTS ?=
+endef
+
+tests ?=
+unsafe_tests ?=
+TESTS = $(if $(ENABLE_TESTS),$(tests) \
+        $(if $(ENABLE_UNSAFE_TESTS),$(unsafe_tests)))
 
 # Make behavior
 SHELL = bash -o pipefail
@@ -37,7 +110,6 @@ OUR_CPPFLAGS += -MT $@ -MD -MP -MF $(@D)/$(DEPDIR)/$(basename $(@F)).P$(patsubst
 OUR_CPPFLAGS += -include $(topoutdir)/config.h
 OUR_CPPFLAGS += $(sort -I$(@D) $(if $(<D),-I$(<D) -I$(call at.out2src,$(<D))))
 
-# 
 sd.ALL_CFLAGS       = $(strip $(OUR_CFLAGS)       $(am.CFLAGS)       $(sd.CFLAGS)       $(CFLAGS)       )
 sd.ALL_CPPFLAGS     = $(strip $(OUR_CPPFLAGS)     $(am.CPPFLAGS)     $(sd.CPPFLAGS)     $(CPPFLAGS)     )
 sd.ALL_LDFLAGS      = $(strip $(OUR_LDFLAGS)      $(am.LDFLAGS)      $(sd.LDFLAGS)      $(LDFLAGS)      )
@@ -63,21 +135,11 @@ AM_V_M4_ ?= $(AM_V_M4_$(AM_DEFAULT_VERBOSITY))
 AM_V_M4_0 ?= @echo "  M4      " $@;
 AM_V_M4_1 ?=
 
-AM_V_XSLT ?= $(AM_V_XSLT_$(V))
-AM_V_XSLT_ ?= $(AM_V_XSLT_$(AM_DEFAULT_VERBOSITY))
-AM_V_XSLT_0 ?= @echo "  XSLT    " $@;
-AM_V_XSLT_1 ?=
-
 AM_V_GPERF ?= $(AM_V_GPERF_$(V))
 AM_V_GPERF_ ?= $(AM_V_GPERF_$(AM_DEFAULT_VERBOSITY))
 AM_V_GPERF_0 ?= @echo "  GPERF   " $@;
 AM_V_GPERF_1 ?=
 
-AM_V_LN ?= $(AM_V_LN_$(V))
-AM_V_LN_ ?= $(AM_V_LN_$(AM_DEFAULT_VERBOSITY))
-AM_V_LN_0 ?= @echo "  LN      " $@;
-AM_V_LN_1 ?=
-
 AM_V_RM ?= $(AM_V_RM_$(V))
 AM_V_RM_ ?= $(AM_V_RM_$(AM_DEFAULT_VERBOSITY))
 AM_V_RM_0 ?= @echo "  RM      " $@;
@@ -113,17 +175,17 @@ AM_V_GEN_ ?= $(AM_V_GEN_$(AM_DEFAULT_VERBOSITY))
 AM_V_GEN_0 ?= @echo "  GEN     " $@;
 AM_V_GEN_1 ?=
 
+AM_V_lt ?= $(AM_V_lt_$(V))
+AM_V_lt_ ?= $(AM_V_lt_$(AM_DEFAULT_VERBOSITY))
+AM_V_lt_0 ?= --silent
+AM_V_lt_1 ?=
+
 INTLTOOL_V_MERGE ?= $(INTLTOOL_V_MERGE_$(V))
 INTLTOOL_V_MERGE_OPTIONS ?= $(intltool_v_merge_options_$(V))
 INTLTOOL_V_MERGE_ ?= $(INTLTOOL_V_MERGE_$(AM_DEFAULT_VERBOSITY))
 INTLTOOL_V_MERGE_0 ?= @echo "  ITMRG " $@;
 INTLTOOL_V_MERGE_1 ?=
 
-AM_V_lt ?= $(AM_V_lt_$(V))
-AM_V_lt_ ?= $(AM_V_lt_$(AM_DEFAULT_VERBOSITY))
-AM_V_lt_0 ?= --silent
-AM_V_lt_1 ?=
-
 sd.substitutions = \
        '|rootlibexecdir=$(rootlibexecdir)|' \
        '|rootbindir=$(rootbindir)|' \
@@ -192,23 +254,3 @@ sd.SED_PROCESS = \
 	$(AM_V_GEN)$(MKDIR_P) $(dir $@) && \
 	$(SED) $(subst '|,-e 's|@,$(subst =,\@|,$(subst |',|g',$(sd.substitutions)))) \
 		< $< > $@
-
-sd.XSLTPROC_FLAGS = \
-	--nonet \
-	--xinclude \
-	--stringparam man.output.quietly 1 \
-	--stringparam funcsynopsis.style ansi \
-	--stringparam man.authors.section.enabled 0 \
-	--stringparam man.copyright.section.enabled 0 \
-	--stringparam systemd.version $(VERSION) \
-	--path '$(outdir):$(srcdir):$(topoutdir)/man:$(topsrcdir)/man'
-
-sd.XSLT = $(if $(XSLTPROC), $(XSLTPROC), xsltproc)
-sd.XSLTPROC_PROCESS_MAN = \
-	$(AM_V_XSLT)$(sd.XSLT) -o $@ $(sd.XSLTPROC_FLAGS) $(srcdir)/man/custom-man.xsl $<
-
-sd.XSLTPROC_PROCESS_HTML = \
-	$(AM_V_XSLT)$(sd.XSLT) -o $@ $(sd.XSLTPROC_FLAGS) $(srcdir)/man/custom-html.xsl $<
-
-sd.html-alias = \
-	$(AM_V_LN)$(LN_S) -f $(notdir $<) $@
diff --git a/build-aux/Makefile.once.head/20-sdman.mk b/build-aux/Makefile.once.head/20-sdman.mk
new file mode 100644
index 0000000000..558c60531d
--- /dev/null
+++ b/build-aux/Makefile.once.head/20-sdman.mk
@@ -0,0 +1,93 @@
+#  -*- Mode: makefile; indent-tabs-mode: t -*-
+#
+#  This file is part of systemd.
+#
+#  Copyright 2010-2012 Lennart Poettering
+#  Copyright 2010-2012 Kay Sievers
+#  Copyright 2013 Zbigniew Jędrzejewski-Szmek
+#  Copyright 2013 David Strauss
+#  Copyright 2016 Luke Shumaker
+#
+#  systemd is free software; you can redistribute it and/or modify it
+#  under the terms of the GNU Lesser General Public License as published by
+#  the Free Software Foundation; either version 2.1 of the License, or
+#  (at your option) any later version.
+#
+#  systemd 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
+#  Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public License
+#  along with systemd; If not, see <http://www.gnu.org/licenses/>.
+
+mod.sdman.description = (systemd) manpages
+mod.sdman.depends += am files write-atomic
+define mod.sdman.doc
+# User variables:
+#   - `V`
+#   - `AM_V_LN*`
+#   - `AM_V_XSLT*`
+#   - `LN_S`
+#   - `XSLTPROC`
+# Inputs:
+#   - Global variable    : `ENABLE_MANPAGES`
+#   - Global variable    : `VERSION`
+#   - Directory variable : `files.src.src`
+# Outputs:
+#   - File               : `$(srcdir)/Makefile-man.mk`
+#   - Directory variable : `at.subdirs`
+#   - Directory variable : `files.src.gen`
+#   - Directory variable : `man_MANS`
+#   - Directory variable : `noinst_DATA` (HTML)
+#   - Target             : `$(outdir)/%.1`
+#   - Target             : `$(outdir)/%.3`
+#   - Target             : `$(outdir)/%.5`
+#   - Target             : `$(outdir)/%.7`
+#   - Target             : `$(outdir)/%.8`
+#   - Target             : `$(outdir)/%.html`
+#
+# sdman -> Makefile-man.mk:
+#   - Global variable    : `sdman.html-alias`
+# Makefile-man.mk -> sdman:
+#   - Directory variable : `sdman.MANPAGES`
+#   - Directory variable : `sdman.MANPAGES_ALIAS`
+#
+# The `sdman.*` variables are the interface by which the module
+# communicates with the genrated Makefile-man.mk file.  They should not
+# be used outside of the `sdman` module.
+endef
+mod.sdman.doc := $(value mod.sdman.doc)
+
+V ?=
+LN_S ?= ln -s
+
+AM_V_LN ?= $(AM_V_LN_$(V))
+AM_V_LN_ ?= $(AM_V_LN_$(AM_DEFAULT_VERBOSITY))
+AM_V_LN_0 ?= @echo "  LN      " $@;
+AM_V_LN_1 ?=
+
+AM_V_XSLT ?= $(AM_V_XSLT_$(V))
+AM_V_XSLT_ ?= $(AM_V_XSLT_$(AM_DEFAULT_VERBOSITY))
+AM_V_XSLT_0 ?= @echo "  XSLT    " $@;
+AM_V_XSLT_1 ?=
+
+_sdman.XSLTPROC_FLAGS = \
+	--nonet \
+	--xinclude \
+	--stringparam man.output.quietly 1 \
+	--stringparam funcsynopsis.style ansi \
+	--stringparam man.authors.section.enabled 0 \
+	--stringparam man.copyright.section.enabled 0 \
+	--stringparam systemd.version $(VERSION) \
+	--path '$(outdir):$(srcdir):$(topoutdir)/man:$(topsrcdir)/man'
+
+_sdman.XSLT = $(if $(XSLTPROC), $(XSLTPROC), xsltproc)
+_sdman.XSLTPROC_PROCESS_MAN = \
+	$(AM_V_XSLT)$(_sdman.XSLT) -o $@ $(_sdman.XSLTPROC_FLAGS) $(srcdir)/man/custom-man.xsl $<
+
+_sdman.XSLTPROC_PROCESS_HTML = \
+	$(AM_V_XSLT)$(_sdman.XSLT) -o $@ $(_sdman.XSLTPROC_FLAGS) $(srcdir)/man/custom-html.xsl $<
+
+sdman.html-alias = \
+	$(AM_V_LN)$(LN_S) -f $(notdir $<) $@