diff --git a/Makefile.common b/Makefile.common
index 79833ac60c..08a13b055f 100644
--- a/Makefile.common
+++ b/Makefile.common
@@ -1,96 +1,130 @@
 #
 # Copyright 2014-2019 the Pacemaker project contributors
 #
 # The version control history for this file may have further details.
 #
 # This source code is licensed under the GNU General Public License version 2
 # or later (GPLv2+) WITHOUT ANY WARRANTY.
 #
 
 #
 # Some variables to help with silent rules
 # https://www.gnu.org/software/automake/manual/html_node/Automake-silent_002drules-Option.html
 #
 # We require a minimum automake version of 1.11, which includes AM_V_GEN and
 # AM_V_at, but AM_V_P is not available until 1.13.
 
 V ?= $(AM_DEFAULT_VERBOSITY)
 
 # When a make command is prefixed with one of the AM_V_* macros, it may also be
 # desirable to suffix the command with this, to silence stdout.
 PCMK_quiet = $(pcmk_quiet_$(V))
 pcmk_quiet_0 = >/dev/null
 pcmk_quiet_1 = 
 
 # AM_V_GEN is intended to be used in custom pattern rules, and replaces echoing
 # the command used with a more concise line with "GEN" and the name of the file
 # being generated. Our AM_V_* macros are similar but more descriptive.
 AM_V_MAN = $(am__v_MAN_$(V))
 am__v_MAN_0 = @echo "  MAN      $@";
 am__v_MAN_1 = 
 
 AM_V_SCHEMA = $(am__v_SCHEMA_$(V))
 am__v_SCHEMA_0 = @echo "  SCHEMA   $@";
 am__v_SCHEMA_1 = 
 
 AM_V_PUB = $(am__v_PUB_$(V))
 am__v_PUB_0 = @echo "  PUB     $@: $(DOCBOOK_FORMATS)";
 am__v_PUB_1 = 
 
 MAINTAINERCLEANFILES	= Makefile.in
 
 AM_CPPFLAGS		= -I$(top_builddir)/include -I$(top_srcdir)/include   \
 			  -I$(top_builddir)/libltdl -I$(top_srcdir)/libltdl
 
+#
+# Man page builders
+#
+# We have three types of man pages:
+# - man pages for the tools
+# - man pages for OCF agents
+# - man pages for cluster properties used by daemons
+#
+# "BUILD_HELP" actually means "help2man is available", so it only controls the
+# tool man pages, which are generated by help2man. The other man pages are
+# generated via XSL transforms.
+#
+
 if BUILD_HELP
 man8_MANS		= $(sbin_PROGRAMS:%=%.8) $(sbin_SCRIPTS:%=%.8)
-endif
 
 HELP2MAN_ARGS = -N --section 8 --name "Part of the Pacemaker cluster resource manager"
 
+# Some of our tools' help are just shell script invocations of another tool's
+# help. Putting the real tool in MAN8DEPS helps detect when the wrapped help
+# needs updating.
+#
+# If a ".inc" file exists, the tool has been converted to use glib for
+# argument parsing, otherwise it still uses the libcrmcommon functions.
+#
+# @TODO Drop MAN8DEPS once we've converted all tools to libpacemaker API calls
+#       and all wrappers to C code.
 %.8:	% $(MAN8DEPS)
 	$(AM_V_at)chmod a+x $(abs_builddir)/$<
-	$(AM_V_MAN)if [ -f $(abs_builddir)/$@.inc ]; then \
-		PATH=$(abs_builddir):$$PATH $(HELP2MAN) $(HELP2MAN_ARGS) -h --help-all -i $(abs_builddir)/$@.inc $(abs_builddir)/$< | sed -e '/.SS "Usage:"/,+3d' > $@ ; \
-	else \
-		PATH=$(abs_builddir):$$PATH $(HELP2MAN) $(HELP2MAN_ARGS) $(abs_builddir)/$< --output $@ ; \
+	$(AM_V_MAN)if [ -f $(abs_builddir)/$@.inc ]; then			\
+		PATH=$(abs_builddir):$$PATH $(HELP2MAN) $(HELP2MAN_ARGS)	\
+			-h --help-all						\
+			-i $(abs_builddir)/$@.inc $(abs_builddir)/$<		\
+			| sed -e '/.SS "Usage:"/,+3d' > $@ ;			\
+	else									\
+		PATH=$(abs_builddir):$$PATH $(HELP2MAN) $(HELP2MAN_ARGS)	\
+			$(abs_builddir)/$< --output $@ ;			\
 	fi
+endif
 
+# Save raw XML meta-data from daemon executables, for later conversion into man
+# pages. (Note that more specific rules may override this for creating other
+# types of XML files.)
 %.xml:  %
 	$(AM_V_at)$(abs_builddir)/$< metadata > $@
 
+# Process the raw daemon and OCF agent meta-data output using our
+# meta-data-to-docbook-XML tranform.
 %.dbook: %.xml
-	$(AM_V_at)$(XSLTPROC) --nonet --novalid --stringparam man.name $* $(DBOOK_OPTS) $(top_srcdir)/xml/ocf-meta2man.xsl $(abs_builddir)/$< > $(abs_builddir)/$@
+	$(AM_V_at)$(XSLTPROC) --nonet --novalid --stringparam man.name $* \
+		$(DBOOK_OPTS) $(top_srcdir)/xml/ocf-meta2man.xsl \
+		$(abs_builddir)/$< > $(abs_builddir)/$@
 
+# Generate the actual man page for an OCF resource agent from the intermediate
+# docbook XML.
 %.7:	%.dbook
 	$(AM_V_MAN)$(XSLTPROC) $(MANPAGE_XSLT) $(abs_builddir)/$< $(PCMK_quiet)
+
 # 
 # Build docbook from asciidoc because XML is a PITA to edit
 #
 # Build each chapter as a book (since the numbering isn't right for
 # articles and only books can have appendices) and then strip out the
 # bits we don't want/need
 #
 # XXX Sequence of tr/sed commands should be replaced with a single XSLT
 #
 %.xml:  %.txt
 if IS_ASCIIDOC
 	$(AM_V_GEN)$(ASCIIDOC_CONV) -b docbook -d book -o $@-tt $<
 else
 	$(AM_V_GEN)$(ASCIIDOC_CONV) -b docbook45 -d book -o $@-tt $<
 endif
 	$(AM_V_at)tr -d '\036\r' <$@-tt >$@-t; rm -f $@-tt  # Fix line endings
 	$(AM_V_at)sed -i 's/\ lang="en"//' $@-t      # Never specify a language in the chapters
 	$(AM_V_at)sed -i 's/simpara/para/g' $@-t     # publican doesn't correctly render footnotes with simpara
 	$(AM_V_at)sed -i 's/.*<date>.*//g' $@-t      # Remove dangling tag
 	$(AM_V_at)sed -i 's/.*preface>//g' $@-t      # Remove preface elements
 	$(AM_V_at)sed -i 's:<title></title>::g' $@-t # Remove empty title
 	$(AM_V_at)sed -i 's/chapter/section/g' $@-t  # Chapters become sections, so that books can become chapters
 	$(AM_V_at)sed -i 's/<.*bookinfo.*>//g' $@-t  # Strip out bookinfo, we don't need it
 	$(AM_V_at)! grep -q "<appendix" $@-t || sed -i \
 	  's/.*book>//;tb;bf;:b;N;s/.*<title>.*<\/title>.*//;tb;/<appendix/{:i;n;/<\/appendix/{p;d};bi};bb;:f;p;d' \
 	  $@-t  # We just want the appendix tag (asciidoctor adds non-empty book-level title)
 	$(AM_V_at)sed -i 's/book>/chapter>/g' $@-t   # Rename to chapter (won't trigger if previous sed did)
 	$(AM_V_GEN)mv $@-t $@
-
-#	echo Rebuilt $@ from $<
diff --git a/tools/Makefile.am b/tools/Makefile.am
index c91747a33a..477adeb77b 100644
--- a/tools/Makefile.am
+++ b/tools/Makefile.am
@@ -1,153 +1,156 @@
 #
 # Copyright 2004-2019 the Pacemaker project contributors
 #
 # The version control history for this file may have further details.
 #
 # This source code is licensed under the GNU General Public License version 2
 # or later (GPLv2+) WITHOUT ANY WARRANTY.
 #
 include $(top_srcdir)/Makefile.common
 
 if BUILD_SYSTEMD
 systemdunit_DATA = crm_mon.service
 endif
 
 noinst_HEADERS		= crm_mon.h crm_resource.h
 
 pcmkdir			= $(datadir)/$(PACKAGE)
 pcmk_DATA		= report.common report.collector
 
 sbin_SCRIPTS		= crm_report crm_standby crm_master crm_failcount
 if BUILD_CIBSECRETS
 sbin_SCRIPTS		+= cibsecret
 endif
 
 EXTRA_DIST		= crm_mon.sysconfig		\
 			  crm_mon.8.inc			\
 			  stonith_admin.8.inc
 
 sbin_PROGRAMS		= attrd_updater \
 			  cibadmin \
 			  crmadmin \
 			  crm_simulate \
 			  crm_attribute \
 			  crm_diff \
 			  crm_error \
 			  crm_mon \
 			  crm_node \
 			  crm_resource \
 			  crm_rule \
 			  crm_shadow \
 			  crm_verify \
 			  crm_ticket \
 			  iso8601 \
 			  stonith_admin
 
 if BUILD_SERVICELOG
 sbin_PROGRAMS		+= notifyServicelogEvent
 endif
 if BUILD_OPENIPMI_SERVICELOG
 sbin_PROGRAMS		+= ipmiservicelogd
 endif
 
 ## SOURCES
 
-MAN8DEPS		= crm_attribute crm_node
+# A few tools are just thin wrappers around crm_attribute.
+# This makes their help get updated when crm_attribute changes
+# (see Makefile.common).
+MAN8DEPS		= crm_attribute
 
 crmadmin_SOURCES	= crmadmin.c
 crmadmin_LDADD		= $(top_builddir)/lib/pengine/libpe_status.la	\
 			  $(top_builddir)/lib/cib/libcib.la		\
 			  $(top_builddir)/lib/common/libcrmcommon.la
 
 crm_error_SOURCES	= crm_error.c
 crm_error_LDADD		= $(top_builddir)/lib/common/libcrmcommon.la
 
 cibadmin_SOURCES	= cibadmin.c
 cibadmin_LDADD		= $(top_builddir)/lib/cib/libcib.la		\
 			  $(top_builddir)/lib/common/libcrmcommon.la
 
 crm_shadow_SOURCES	= crm_shadow.c
 crm_shadow_LDADD	= $(top_builddir)/lib/cib/libcib.la		\
 			  $(top_builddir)/lib/common/libcrmcommon.la
 
 crm_node_SOURCES	= crm_node.c
 crm_node_LDADD		= $(top_builddir)/lib/cib/libcib.la		\
 			  $(top_builddir)/lib/common/libcrmcommon.la
 
 crm_simulate_SOURCES	= crm_simulate.c
 
 crm_simulate_LDADD	= $(top_builddir)/lib/pengine/libpe_status.la	\
 			  $(top_builddir)/lib/pacemaker/libpacemaker.la	\
 			  $(top_builddir)/lib/cib/libcib.la		\
 			  $(top_builddir)/lib/common/libcrmcommon.la
 
 crm_diff_SOURCES	= crm_diff.c
 crm_diff_LDADD		= $(top_builddir)/lib/common/libcrmcommon.la
 
 crm_mon_SOURCES		= crm_mon.c crm_mon_curses.c crm_mon_print.c crm_mon_runtime.c
 crm_mon_LDADD		= $(top_builddir)/lib/pengine/libpe_status.la	\
 			  $(top_builddir)/lib/fencing/libstonithd.la	\
 			  $(top_builddir)/lib/pacemaker/libpacemaker.la	\
 			  $(top_builddir)/lib/cib/libcib.la		\
 			  $(top_builddir)/lib/common/libcrmcommon.la	\
 			  $(CURSESLIBS)
 
 crm_verify_SOURCES	= crm_verify.c
 crm_verify_LDADD	= $(top_builddir)/lib/pengine/libpe_status.la 	\
 			  $(top_builddir)/lib/pacemaker/libpacemaker.la	\
 			  $(top_builddir)/lib/cib/libcib.la		\
 			  $(top_builddir)/lib/common/libcrmcommon.la
 
 crm_attribute_SOURCES	= crm_attribute.c
 crm_attribute_LDADD	= $(top_builddir)/lib/cluster/libcrmcluster.la	\
 			  $(top_builddir)/lib/cib/libcib.la		\
 			  $(top_builddir)/lib/common/libcrmcommon.la
 
 crm_resource_SOURCES	= crm_resource.c crm_resource_ban.c crm_resource_runtime.c crm_resource_print.c
 crm_resource_LDADD	= $(top_builddir)/lib/pengine/libpe_rules.la  	\
 			  $(top_builddir)/lib/fencing/libstonithd.la	\
 			  $(top_builddir)/lib/lrmd/liblrmd.la 		\
 			  $(top_builddir)/lib/services/libcrmservice.la \
 			  $(top_builddir)/lib/pengine/libpe_status.la 	\
 			  $(top_builddir)/lib/pacemaker/libpacemaker.la	\
 			  $(top_builddir)/lib/cib/libcib.la		\
 			  $(top_builddir)/lib/common/libcrmcommon.la
 
 crm_rule_SOURCES 	= crm_rule.c
 crm_rule_LDADD		= $(top_builddir)/lib/cib/libcib.la		\
 			  $(top_builddir)/lib/pengine/libpe_rules.la   \
 			  $(top_builddir)/lib/pengine/libpe_status.la   \
 			  $(top_builddir)/lib/common/libcrmcommon.la
 
 iso8601_SOURCES		= iso8601.c
 iso8601_LDADD		= $(top_builddir)/lib/common/libcrmcommon.la
 
 attrd_updater_SOURCES	= attrd_updater.c
 attrd_updater_LDADD	= $(top_builddir)/lib/common/libcrmcommon.la
 
 crm_ticket_SOURCES	= crm_ticket.c
 crm_ticket_LDADD	= $(top_builddir)/lib/pengine/libpe_rules.la	\
 			  $(top_builddir)/lib/pengine/libpe_status.la	\
 			  $(top_builddir)/lib/pacemaker/libpacemaker.la	\
 			  $(top_builddir)/lib/cib/libcib.la		\
 			  $(top_builddir)/lib/common/libcrmcommon.la
 
 stonith_admin_SOURCES	= stonith_admin.c
 stonith_admin_LDADD	= $(top_builddir)/lib/common/libcrmcommon.la	\
 			  $(top_builddir)/lib/cib/libcib.la		\
 			  $(top_builddir)/lib/pengine/libpe_status.la	\
 			  $(top_builddir)/lib/fencing/libstonithd.la
 
 if BUILD_SERVICELOG
 notifyServicelogEvent_SOURCES	= notifyServicelogEvent.c
 notifyServicelogEvent_CFLAGS	= $(SERVICELOG_CFLAGS)
 notifyServicelogEvent_LDADD	= $(top_builddir)/lib/common/libcrmcommon.la $(SERVICELOG_LIBS)
 endif
 
 if BUILD_OPENIPMI_SERVICELOG
 ipmiservicelogd_SOURCES	= ipmiservicelogd.c
 ipmiservicelogd_CFLAGS	= $(OPENIPMI_SERVICELOG_CFLAGS) $(SERVICELOG_CFLAGS)
 ipmiservicelogd_LDFLAGS	= $(top_builddir)/lib/common/libcrmcommon.la $(OPENIPMI_SERVICELOG_LIBS) $(SERVICELOG_LIBS)
 endif
 
 CLEANFILES = $(man8_MANS)