From 0b8feaaf27f2db6da8977f989ce1f07e7f30d202 Mon Sep 17 00:00:00 2001
From: Joan Josep Ordinas Rosa <jordinas@gmail.com>
Date: Mon, 17 Apr 2017 00:41:52 +0200
Subject: [PATCH] Created jqt.make

---
 bump-version.sh               |   1 +
 docs/Makefile                 | 140 +++++++++++-----------------------
 docs/jqt.make                 |  81 ++++++++++++++++++++
 docs/make.d/config.make       |  30 ++++----
 docs/make.d/front-matter.make |  85 ---------------------
 docs/make.d/pages.make        |  74 +++++++++---------
 docs/make.d/pathnames.make    |  85 +++++++++++++++++++--
 docs/make.d/phase0.jq         |  12 ++-
 docs/make.d/phase1.jq         |   8 +-
 docs/make.d/phase2.jq         |   4 +-
 docs/make.d/phase21.jq        |   2 +-
 docs/make.d/phase3.jq         |   8 +-
 docs/make.d/sitemap.make      |  11 +--
 docs/make.d/styles.make       |   6 --
 docs/make.d/tools.make        |   8 +-
 15 files changed, 293 insertions(+), 262 deletions(-)
 create mode 100644 docs/jqt.make
 delete mode 100644 docs/make.d/front-matter.make

diff --git a/bump-version.sh b/bump-version.sh
index de46843..74ca2c4 100755
--- a/bump-version.sh
+++ b/bump-version.sh
@@ -37,6 +37,7 @@ if [[ -f VERSION ]]; then
     git add CHANGES VERSION
     sed -i "s/^declare -r VERSION=/&'$NEXT_VERSION'/" bin/jqt
 	sed -i "s/\[version .*\]/[version $(NEXT_VERSION)]/" bin/jqt
+	sed -i "s/^Version *:=.*/Version := $(NEXT_VERSION)/" docs/Makefile
     git commit -am "Version bump to $NEXT_VERSION"
     git tag -a -m "Tagging version $NEXT_VERSION" "v$NEXT_VERSION"
     [[ $PUSH == yes ]] && git push origin --tags
diff --git a/docs/Makefile b/docs/Makefile
index 29b7acf..875a6f6 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -10,7 +10,7 @@
 include make.d/prelude.make
 
 # jqt version
-Version := $(shell cat ../VERSION)
+Version := 0.5.0
 
 # Metadata directory
 Metadata := .meta
@@ -24,11 +24,9 @@ endif
 
 # ======================================================================
 -include $(Metadata)/phase1.make
+ include make.d/config.make
 #
-# Load site global parameters. If `phase1.make` not exists it is built when
-# restarting with a rule defined in `config.make`.
-#
-# Exported variables:
+# Variables defined in phase1.make:
 #	__phase_1
 #	Assets
 #	Blocks
@@ -37,10 +35,13 @@ endif
 #	Destination
 #	Layouts
 #	Styles
+# Defined rules for:
+# 	$(Metadata)
+#	$(Metadata)/config.json
+#	$(Metadata)/phase1.make
+#	$(Metadata)/site.json
 # ======================================================================
 
-include make.d/config.make
-
 # Warning:
 #
 # If `__phase_1` is not defined because `phase1.make` does not exists, after
@@ -53,123 +54,72 @@ ifdef __phase_1
 
 # ======================================================================
 -include $(Metadata)/phase2.make
+ include make.d/pathnames.make
 #
-# Load variables for several pathnames.
-#
-# Exported variables:
+# Variables defined in phase2.make:
 #	__phase_2
 #	DestinationPages
 #	DestinationPaths
 #	MetadataPages 
 #	MetadataPaths
-# Exported rules for:
-# 	$(Metadata)/pages/.../page.json
+# Defined rules for:
+#	$(Metadata)/phase2.make
+# 	$(DestinationPaths)
+# 	$(MetadataPaths)
+# 	$(MetadataPages)
+# 	$(Metadata)/pages.json
+# 	$(Metadata)/sections.json
 # ======================================================================
 
-include make.d/pathnames.make
-
 ifdef __phase_2
 
-include make.d/front-matter.make
-
 # ======================================================================
 -include $(Metadata)/phase3.make
+ include make.d/pages.make
 #
 # Load rules for pages and nodes. If not exists is built when restarting with
 # rule defined in `pages.make`.
 #
-# Exported variables:
+# Variables defined in phase3.make:
 #	__phase_3
-# Exported rules for:
-# 	dependencies and rules for all HTML files
+# Defined rules for:
+#	$(Metadata)/phase3.make
+# 	$(DestinationPages)
+# Defined targets:
+#	all
+# 	build
+# 	clean
+# 	clobber
+# 	fresh
+# 	init
+# 	touch
 # ======================================================================
 
-include make.d/pages.make
-
 ifdef __phase_3
 
+# ======================================================================
 include make.d/sitemap.make
 include make.d/styles.make
 include make.d/tools.make
-
-########################################################################
-#  Specific rules for this web site
-########################################################################
-
-# Call jqt with user defined flags
-JQT = jqt $(JQTFLAGS)
-
-# Options for `jqt`.
-JQTFLAGS += 					\
-	-5 					\
-	-I./					\
-	-j'$$'pages:$(Metadata)/pages		\
-	-msite:$(Metadata)/config.json		\
-	-msections:$(Metadata)/sections.json	\
-	-iblocks/filters			\
-	--toc-depth=4				\
-	-msnippets:$(Metadata)/snippets.json	\
-
-# Snippets
-$(Metadata)/snippets.json: $(Data)/snippets.yaml \
-| $(Metadata)
-	$(info ==> $@)
-	@jqt -T < $< | yaml2json > $@
-
-# Extra dependencies
-$(DestinationPages): $(Metadata)/snippets.json $(Blocks)/filters.jq $(Blocks)/*/*.html $(Blocks)/*/*/*.html
-
 #
-# Generate man page for jqt
+# Several complementary files.
 #
-
-# gpp for the man page (to be build without calling jqt!)
-GPP_MD := gpp						\
-	-U '<%' '>' '\B' '\B' '\W>' '<' '>' '$$' ''	\
-	-M '<%' '>' '\B' '\B' '\W>' '<' '>'		\
-	+sccc '&\n' '' ''				\
-	+sccc '\\n' '' ''				\
-	+sccc '<\#' '\#>\n' ''				\
-	+siqi "'" "'" '\'				\
-	+siQi '"' '"' '\'				\
-	+ssss '<!--' '-->' ''				\
-	+ssss '`'  '`' ''				\
-	+ssss '\n```' '\n```' ''			\
-	+ssss '\n~~~' '\n~~~' ''			\
-    
-#
-ManPage := ../jqt.1.gz
-
-# Man page: jqt(1)
-$(ManPage): $(Content)/jqt.1.text
-	$(info ==> $@)
-	@$(GPP_MD) -I$(Content) < $<			\
-	| pandoc --standalone --from markdown --to man	\
-	| gzip > $@
-
-# Add prerequisites and recipes to common targets
-all:: $(ManPage)
-
-clean::
-	@rm -f $(ManPage)
-
-clobber::
-	@rm -f $(ManPage)
+# Defined rules for:
+#	$(Destination)/sitemap.xml
+#	$(Destination)/sitemap.xml.gz
+#	$(Destination)/styles.css
+# Defined targets:
+# 	help
+# 	lint
+# 	valid
+# ======================================================================
 
 ########################################################################
-# Generate Help text
-# Independent target: helps generating text for `jqt -h`
-# Needs explicit call: `make /tmp/help`
+include jqt.make
 #
-/tmp/help: $(Content)/help.text
-	$(info ==> $@)
-	@jqt -P MarkDown -I$(Content) < $<				\
-	| pandoc --from markdown --to plain -				\
-	| sed '1,7b;/^$$/d;s/_\([A-Z]\+\)_/\1/g;/^[^A-Z]/s/^/    /'	\
-	> $@
-
-clean::
-	@rm -f /tmp/help
+# Project specific makefile. All the previous modules are expected to be
+# independent, valid for any project without any change.
+########################################################################
 
 endif # __phase_3
 endif # __phase_2
diff --git a/docs/jqt.make b/docs/jqt.make
new file mode 100644
index 0000000..e6d4fd1
--- /dev/null
+++ b/docs/jqt.make
@@ -0,0 +1,81 @@
+########################################################################
+#  Specific makefile for this web site
+########################################################################
+
+# Options for `jqt`.
+JQTFLAGS += 					\
+	-5 					\
+	--toc-depth=4				\
+	-I./					\
+	-msite:$(Metadata)/config.json		\
+	-msections:$(Metadata)/sections.json	\
+	-msnippets:$(Metadata)/snippets.json	\
+	-iblocks/filters			\
+	-j'$$'pages:$(Metadata)/pages		\
+
+# Snippets
+$(Metadata)/snippets.json: $(Data)/snippets.yaml \
+| $(Metadata)
+	$(info ==> $@)
+	@jqt -T < $< | yaml2json > $@
+
+clean::
+	@rm -f $(Metadata)/snippets.json
+
+# Extra dependencies
+$(DestinationPages): $(Metadata)/snippets.json # $(Blocks)/filters.jq $(Blocks)/*/*.html $(Blocks)/*/*/*.html
+
+########################################################################
+# Generate man page for jqt
+########################################################################
+
+# gpp for the man page (to be build without calling jqt!)
+GPP_MD := gpp						\
+	-U '<%' '>' '\B' '\B' '\W>' '<' '>' '$$' ''	\
+	-M '<%' '>' '\B' '\B' '\W>' '<' '>'		\
+	+sccc '&\n' '' ''				\
+	+sccc '\\n' '' ''				\
+	+sccc '<\#' '\#>\n' ''				\
+	+siqi "'" "'" '\'				\
+	+siQi '"' '"' '\'				\
+	+ssss '<!--' '-->' ''				\
+	+ssss '`'  '`' ''				\
+	+ssss '\n```' '\n```' ''			\
+	+ssss '\n~~~' '\n~~~' ''			\
+    
+#
+ManPage := ../jqt.1.gz
+
+# Man page: jqt(1)
+$(ManPage): $(Content)/jqt.1.text
+	$(info ==> $@)
+	@$(GPP_MD) -I$(Content) < $<			\
+	| pandoc --standalone --from markdown --to man	\
+	| gzip > $@
+
+# Add prerequisites and recipes to common targets
+all:: $(ManPage)
+
+clean::
+	@rm -f $(ManPage)
+
+clobber::
+	@rm -f $(ManPage)
+
+########################################################################
+# Generate help text
+########################################################################
+
+# Independent target: helps generating text for `jqt -h`
+# Needs explicit call: `make /tmp/help`
+/tmp/help: $(Content)/help.text
+	$(info ==> $@)
+	@jqt -P MarkDown -I$(Content) < $<				\
+	| pandoc --from markdown --to plain -				\
+	| sed '1,7b;/^$$/d;s/_\([A-Z]\+\)_/\1/g;/^[^A-Z]/s/^/    /'	\
+	> $@
+
+clean::
+	@rm -f /tmp/help
+
+# vim:ai:sw=8:ts=8:noet:fileencoding=utf8:syntax=make
diff --git a/docs/make.d/config.make b/docs/make.d/config.make
index 2f581c1..28f860e 100644
--- a/docs/make.d/config.make
+++ b/docs/make.d/config.make
@@ -2,20 +2,25 @@
 # config.make
 #
 # Build files derived from user defined configuration:
-# 	config.{yaml,json} => config.json => site.json => phase_1.make
+# 	config.{yaml,json} => config.json => site.json => phase1.make
 #
-# Imported variables:
-#	Metadata
-#	Version
-# Exported rules for:
+# Variables defined in phase1.make:
+#	__phase_1
+#	Assets
+#	Blocks
+#	Content
+#	Data
+#	Destination
+#	Layouts
+#	Styles
+# Defined rules for:
 # 	$(Metadata)
-# 	$(Metadata)/
 #	$(Metadata)/config.json
+#	$(Metadata)/phase1.make
 #	$(Metadata)/site.json
-#	$(Metadata)/phase_1.make
 
 ########################################################################
-# Metadata directory for all generated metadata and make files
+# Metadata directory for all generated make and metadata files
 ########################################################################
 
 $(Metadata):
@@ -23,14 +28,12 @@ $(Metadata):
 	@mkdir --parents $@ >/dev/null 2>&1 || true
 
 ########################################################################
-# Rules for configuration files
+# Files derived from user defined configuration file
 ########################################################################
 
 #
-# Create `$(Metadata)/config.json`.
+# Create `$(Metadata)/config.json` from `config.yaml` or `config.json`.
 #
-
-# Input is user defined `config.yaml` or `config.json`.
 ifeq (config.yaml,$(wildcard config.yaml))
 
 # Convert `config.yaml` to `$(Metadata)/config.json`.
@@ -54,11 +57,12 @@ endif
 #
 # Create `$(Metadata)/site.json` from `$(Metadata)/config.json`.
 #
-$(Metadata)/site.json: $(Metadata)/config.json make.d/config.make
+$(Metadata)/site.json: $(Metadata)/config.json make.d/config.make make.d/phase0.jq
 	$(info ==> $@)
 	@jq --sort-keys				\
 	    --from-file make.d/phase0.jq	\
 	    --arg Version $(Version)		\
+	    --arg Metadata $(Metadata)		\
 	    < $< > $@
 
 #
diff --git a/docs/make.d/front-matter.make b/docs/make.d/front-matter.make
deleted file mode 100644
index 17d709b..0000000
--- a/docs/make.d/front-matter.make
+++ /dev/null
@@ -1,85 +0,0 @@
-########################################################################
-# front-matter.conf
-#
-# Collect metadata from front-matter sections.
-#
-# Imported variables:
-# 	Content
-#	Destination
-#	DestinationPages
-#	DestinationPaths
-#	Layouts
-#	Metadata
-#	MetadataPages
-#	MetadataPaths
-# Exported rules for:
-# 	$(DestinationPaths)
-# 	$(Metadata)/pages.json
-# 	$(Metadata)/sections.json
-# 	$(MetadataPages)
-# 	$(MetadataPaths)
-
-########################################################################
-# Extra dependencies
-########################################################################
-
-# Add prerequisites to default goal
-all:: $(DestinationPages)
-
-$(DestinationPages): $(Destination)/%.html : $(Metadata)/pages/%.json
-$(DestinationPages): $(Layouts)/default.html
-
-########################################################################
-# Rules for directories
-########################################################################
-
-# Directories starting at `$(Destination)/`
-$(DestinationPaths):
-	$(info ==> $@)
-	@mkdir --parents $@ >/dev/null 2>&1 || true
-
-# Directories starting at `$(Metadata)/pages/`.
-$(MetadataPaths):
-	$(info ==> $@)
-	@mkdir --parents $@ >/dev/null 2>&1 || true
-
-$(DestinationPages): | $$(dir $$@)
-$(MetadataPages): | $$(dir $$@)
-
-########################################################################
-# Group metadata
-########################################################################
-
-$(Metadata)/pages.json: $(MetadataPages)
-	$(info ==> $@)
-	@jq --slurp '.' $^ > $@
-
-$(Metadata)/sections.json: $(Metadata)/pages.json
-	$(info ==> $@)
-	@jq '[.[].section] | unique | map(select(.))' < $< > $@
-
-########################################################################
-# Build metadata for pages.
-########################################################################
-
-define EXTRACT_FRONT_MATTER =
-  sed -n -e '1d'		\
-  	 -e '/^---$$/q'		\
-	 -e '/^\.\.\.$$/q'	\
-	 -e '/^\#/d'		\
-	 -e 'p'
-endef
-
-define BUILD_JSON
-  yaml2json |					\
-  jq --sort-keys				\
-     --arg Source $<				\
-     --arg Target $@				\
-     --arg Metadata $(Metadata)			\
-     --slurpfile config $(Metadata)/config.json	\
-     --from-file make.d/phase21.jq
-endef
-
-$(MetadataPages): $(Metadata)/config.json	
-
-# vim:ai:sw=8:ts=8:noet:fileencoding=utf8:syntax=make
diff --git a/docs/make.d/pages.make b/docs/make.d/pages.make
index c869b69..8bc60b9 100644
--- a/docs/make.d/pages.make
+++ b/docs/make.d/pages.make
@@ -3,20 +3,45 @@
 #
 # Define standard rules and rules for HTML pages and nodes.
 #
-# Imported variables:
-#	Assets
-#	Destination
-#	Layouts
-#	Metadata
-#	JQTFLAGS
-# Exported rules for:
-#	all:: # assets
+# Defined rules for:
+#	$(Metadata)/phase3.make
+# Defined targets:
+#	all
 # 	build
 # 	clean
 # 	clobber
-# 	touch
 # 	fresh
-#	$(Metadata)/phase3.make
+# 	init
+# 	touch
+
+########################################################################
+# Create makefile containing rules for all HTML files
+########################################################################
+
+# Rules for each page (depend also on sections.json only to force build)
+$(Metadata)/phase3.make: $(Metadata)/pages.json $(Metadata)/sections.json make.d/pages.make make.d/phase3.jq $(Metadata)/phase2.make
+	$(info ==> $@)
+	@jq --raw-output			\
+	    --arg Metadata $(Metadata)		\
+	    --arg Layouts $(Layouts)		\
+	    --arg Destination $(Destination)	\
+	    --from-file make.d/phase3.jq	\
+	    < $< > $@
+
+#
+# Variables used when building HTML files in phase3.make.
+#
+
+JQT = jqt $(JQTFLAGS)
+
+define DETAILS =
+  sed -e 's/^<p><details><\/p>/<details>/'	\
+      -e 's/^<p><\/details><\/p>/<\/details>/'	\
+      -e 's/^<p><summary>/<summary>/'		\
+      -e 's/<\/summary><\/p>/<\/summary>/'
+endef
+
+ifdef __phase_3
 
 ########################################################################
 # Standard targets
@@ -24,8 +49,8 @@
 
 .PHONY: clean clobber build touch fresh
 
-# Copy Assets
-all:: | $(Destination)
+# Copy Assets after create HTML pages
+all:: $(DestinationPages) | $(Destination)
 	@cp --verbose --recursive --update $(Assets)/* $(Destination) \
 	| sed "s/^.*-> ./==> /;s/.$$//"
 
@@ -41,7 +66,7 @@ clobber:: clean
 build: clean all
 
 # Clobber and build again
-define p_test_and_touch.sh
+define TEST_AND_TOUCH.sh
   if test -e config.yaml;	\
   then touch config.yaml;	\
   elif test -e config.json;	\
@@ -51,7 +76,7 @@ define p_test_and_touch.sh
 endef
 
 touch:
-	@$(p_test_and_touch.sh)
+	@$(TEST_AND_TOUCH.sh)
 	@$(MAKE) -s all
 
 # Clobber and build again
@@ -62,25 +87,6 @@ init:
 	@rm -rf $(Metadata)
 	@$(MAKE) -s $(Metadata)/phase3.make
 
-########################################################################
-# Create makefile containing rules for all HTML files
-########################################################################
-
-define DETAILS :=
-  sed -e 's/^<p><details><\/p>/<details>/'	\
-      -e 's/^<p><\/details><\/p>/<\/details>/'	\
-      -e 's/^<p><summary>/<summary>/'		\
-      -e 's/<\/summary><\/p>/<\/summary>/'
-endef
-
-# Rules for each page (depend also on sections.json only to force build)
-$(Metadata)/phase3.make: $(Metadata)/pages.json $(Metadata)/sections.json make.d/pages.make make.d/phase3.jq
-	$(info ==> $@)
-	@jq --raw-output			\
-	    --arg Metadata $(Metadata)		\
-	    --arg Layouts $(Layouts)		\
-	    --arg Destination $(Destination)	\
-	    --from-file make.d/phase3.jq	\
-	    < $< > $@
+endif
 
 # vim:ai:sw=8:ts=8:noet:fileencoding=utf8:syntax=make
diff --git a/docs/make.d/pathnames.make b/docs/make.d/pathnames.make
index 9c68490..9ab665d 100644
--- a/docs/make.d/pathnames.make
+++ b/docs/make.d/pathnames.make
@@ -3,16 +3,23 @@
 #
 # Build metadata from filesystem introspection.
 #
-# Imported variables:
-#	Content
-#	Destination
-#	Metadata
-#
-# Exported rules for:
+# Variables defined in phase2.make:
+#	__phase_2
+#	DestinationPages
+#	DestinationPaths
+#	MetadataPages 
+#	MetadataPaths
+# Defined rules for:
 #	$(Metadata)/phase2.make
+# 	$(DestinationPaths)
+# 	$(MetadataPaths)
+# 	$(MetadataPages)
+# 	$(Metadata)/pages.json
+# 	$(Metadata)/sections.json
 
 ########################################################################
-# Create makefile defining global parameters about pathnames
+# Create makefile defining global variables about pathnames and rules to
+# generate JSON metadata files for each page.
 ########################################################################
 
 $(Metadata)/phase2.make: make.d/pathnames.make make.d/phase2.jq $(Metadata)/phase1.make
@@ -30,4 +37,68 @@ $(Metadata)/phase2.make: make.d/pathnames.make make.d/phase2.jq $(Metadata)/phas
 	     --arg Metadata $(Metadata)			\
 	     > $@
 
+ifdef __phase_2
+
+#
+# Variables used when building JSON files in phase2.make.
+#
+
+define EXTRACT_FRONT_MATTER =
+  sed -n -e '1d'		\
+  	 -e '/^---$$/q'		\
+	 -e '/^\.\.\.$$/q'	\
+	 -e '/^\#/d'		\
+	 -e 'p'
+endef
+
+define BUILD_JSON
+  yaml2json |					\
+  jq --sort-keys				\
+     --arg Source $<				\
+     --arg Target $@				\
+     --arg Metadata $(Metadata)			\
+     --slurpfile config $(Metadata)/config.json	\
+     --from-file make.d/phase21.jq
+endef
+
+########################################################################
+# Rules for directories
+########################################################################
+
+# Directories starting at `$(Destination)/`
+$(DestinationPaths):
+	$(info ==> $@)
+	@mkdir --parents $@ >/dev/null 2>&1 || true
+
+# Directories starting at `$(Metadata)/pages/`.
+$(MetadataPaths):
+	$(info ==> $@)
+	@mkdir --parents $@ >/dev/null 2>&1 || true
+
+########################################################################
+# Group metadata
+########################################################################
+
+$(Metadata)/pages.json: $(MetadataPages)
+	$(info ==> $@)
+	@jq --slurp '.' $^ > $@
+
+$(Metadata)/sections.json: $(Metadata)/pages.json
+	$(info ==> $@)
+	@jq '[.[].section] | unique | map(select(.))' < $< > $@
+
+########################################################################
+# Extra dependencies
+########################################################################
+
+$(DestinationPages): $(Destination)/%.html : $(Metadata)/pages/%.json
+$(DestinationPages): $(Layouts)/default.html
+
+$(MetadataPages): $(Metadata)/config.json
+
+$(DestinationPages): | $$(dir $$@)
+$(MetadataPages): | $$(dir $$@)
+
+endif
+
 # vim:ai:sw=8:ts=8:noet:fileencoding=utf8:syntax=make
diff --git a/docs/make.d/phase0.jq b/docs/make.d/phase0.jq
index 8b3ec17..28d6523 100644
--- a/docs/make.d/phase0.jq
+++ b/docs/make.d/phase0.jq
@@ -1,7 +1,12 @@
-# phase0.jq --arg Version s
+# phase0.jq --arg Version $(Version) --arg Metadata $(Metadata)
 # 
-# Generate site.json from config.json. Add some new members
-# and delete `.defaults`.
+# Generate site.json from config.json.
+
+########################################################################
+# Output object
+########################################################################
+
+# Add some new members if not defined and delete `.defaults`.
 
 del(.defaults)
 | . + { 
@@ -12,6 +17,7 @@ del(.defaults)
   	Data:        (.Data        // "data"),
   	Layouts:     (.Layouts     // "layouts"),
   	Styles:      (.Styles      // "styles"),
+  	Metadata:    (.Metadata    // $Metadata),
   	Version:     (.Version     // $Version)
 }
 
diff --git a/docs/make.d/phase1.jq b/docs/make.d/phase1.jq
index 8861569..bbda52b 100644
--- a/docs/make.d/phase1.jq
+++ b/docs/make.d/phase1.jq
@@ -2,12 +2,16 @@
 # 
 # Generate phase1.make from site.json.
 
-# Format members as make variables.
-
 def comment:
     "# vim:syntax=make"
 ;
 
+########################################################################
+# Output makefile
+########################################################################
+
+# Format members as make variables.
+
 "__phase_1   := 1",
 "Assets      := " + .Assets,
 "Blocks      := " + .Blocks,
diff --git a/docs/make.d/phase2.jq b/docs/make.d/phase2.jq
index 2d576bb..78bf9ba 100644
--- a/docs/make.d/phase2.jq
+++ b/docs/make.d/phase2.jq
@@ -1,4 +1,4 @@
-# phase2.jq --arg Destination s -arg Content s --arg Metadata s
+# phase2.jq --arg Content $(Content) --arg Destination $(Destination) --arg Metadata $(Metadata)
 # 
 # Generate phase2.make from `find` output.
 
@@ -48,6 +48,8 @@ def mpages($documents):
     | "MetadataPages := " + ($json | join(" ")) + "\n" + mrule
 ;
 
+########################################################################
+# Output makefile
 ########################################################################
 
 (.[:-1] / "\n") as $documents
diff --git a/docs/make.d/phase21.jq b/docs/make.d/phase21.jq
index 95f4437..82f0820 100644
--- a/docs/make.d/phase21.jq
+++ b/docs/make.d/phase21.jq
@@ -49,7 +49,7 @@ def page_section:
 ;
 
 ########################################################################
-#
+# Output object for each page
 ########################################################################
 
 . + {
diff --git a/docs/make.d/phase3.jq b/docs/make.d/phase3.jq
index 7abd3b6..17cd2f7 100644
--- a/docs/make.d/phase3.jq
+++ b/docs/make.d/phase3.jq
@@ -1,6 +1,6 @@
-# phase3.jq --arg Destination s -arg Layouts s --arg Metadata s
+# phase3.jq --arg Metadata $(Metadata) --arg Layouts $(Layouts) --arg Destination $(Destination)
 # 
-# Generate phase3.make from pages.json from pages.json
+# Generate phase3.make from pages.json
 
 def comment:
     "# vim:syntax=make"
@@ -12,6 +12,10 @@ def use:
     else "" end
 ;
 
+########################################################################
+# Output makefile
+########################################################################
+
 "__phase_3 := 1",
 (.[] | (
     $Destination+"/"+.url+": "+.source+" "+$Layouts+"/"+.layout+".html"+use,
diff --git a/docs/make.d/sitemap.make b/docs/make.d/sitemap.make
index 41ef787..2f5ddf1 100644
--- a/docs/make.d/sitemap.make
+++ b/docs/make.d/sitemap.make
@@ -3,16 +3,11 @@
 #
 # Define rules for sitemap.
 #
-# Imported variables:
-#	Destination
-#	Metadata
 # Exported rules for:
-#	$(Destination)/sitemap.*
-
-########################################################################
-# Sitemap
-########################################################################
+#	$(Destination)/sitemap.xml
+#	$(Destination)/sitemap.xml.gz
 
+# XML sitemap
 define SITEMAP.jq
   $$site[0].baseurl as $$baseurl | \
   "<?xml version='\''1.0'\'' encoding='\''UTF-8'\''?> \
diff --git a/docs/make.d/styles.make b/docs/make.d/styles.make
index 02ed07d..ee2bf1a 100644
--- a/docs/make.d/styles.make
+++ b/docs/make.d/styles.make
@@ -3,10 +3,6 @@
 #
 # Generate main CSS stylesheet.
 #
-# Imported variables:
-#	Destination
-#	Blocks
-#	Styles
 # Exported rules for:
 #	$(Destination)/styles.css
 
@@ -18,12 +14,10 @@ $(Destination)/styles.css:		\
 	$(Styles)/*.m 			\
 	$(Styles)/milligram/*.css	\
 
-# Generate main CSS stylesheet.
 $(Destination)/styles.css: $(Styles)/main.css
 	$(info ==> $@)
 	@jqt -P CSS-min -I$(Styles) < $< > $@
 
-# Add `$(Destination)/styles.css` to `all` target.
 all:: $(Destination)/styles.css | $(Destination)
 
 # vim:ai:sw=8:ts=8:noet:fileencoding=utf8:syntax=make
diff --git a/docs/make.d/tools.make b/docs/make.d/tools.make
index c95a960..0714b5e 100644
--- a/docs/make.d/tools.make
+++ b/docs/make.d/tools.make
@@ -1,16 +1,14 @@
 ########################################################################
 # tools.make
 #
-# Tools.
+# Miscelaneous tools.
 #
 # Parameters:
 # 	vnudir
-# Imported variables:
-#	Destination
-# Exported rules for:
+# Defined targets:
 # 	help
-# 	valid
 # 	lint
+# 	valid
 
 ########################################################################
 # Show all targets