tools: Makefile self-documentation system

Makefile

@@ -161,8 +161,30 @@ RELEASEBINARYSUFFIX=$(shell echo "-$(VERSION)-`uname`-`arch`" | tr '[:upper:]' '
 TIME:=$(shell date +"%Y%m%d%H%M")
 
 
+# import the def-help function for documenting make rules. 
+# Standard usage:
+# TARGET: PREREQUISITES \
+# 	$(call def-help,TARGET,\
+# 	HELP\
+# 	)
+# 	ACTIONS
+#
+# Also:
+# $(call def-help-section,SECTION,\
+# HELP\
+# )
+#
+# Arguments to def-help etc. may not contain , so use eg ; instead.
+# They should not contain ' as it breaks emacs font-lock.
+# HELP is one or more lines, or can be blank.
+#
+include help-system.mk
+
+default: help \
+	$(call def-help,help,\
+	list all documented rules in this makefile\
+	)
 
-defaulttarget: bin/hledgerdev
 
 ######################################################################
 # SETUP

help-system.mk

@@ -0,0 +1,31 @@
+# makefile self-documentation
+# http://www.cmcrossroads.com/print/article/self-documenting-makefiles
+
+help:
+	@echo $(if $(need-help),,Type \'make$(dash-f) help\' to get help)
+
+need-help := $(filter help,$(MAKECMDGOALS))
+
+define def-help
+	$(if $(need-help),$(warning $1 --$2))
+endef
+
+# define print-lines
+# 	@echo $1
+# endef
+#	$(if $(true),$(printf $1),$(printf '\n'$1))
+
+define def-help-section
+	$(if $(need-help),$(warning --------------------$1--------------------$2))
+endef
+
+define last-element
+	$(word $(words $1),$1)
+endef
+
+this-makefile := $(call last-element,$(MAKEFILE_LIST))
+other-makefiles := $(filter-out $(this-makefile),$(MAKEFILE_LIST))
+parent-makefile := $(call last-element,$(other-makefiles))
+
+dash-f := $(if $(filter-out Makefile makefile GNUmakefile, $(parent-makefile)), -f $(parent-makefile))
+