make: Ensure documentation is cleaned up and regenerated when needed

- Files are not the only inputs to `texi', so we cannot rely on their
  modification times alone, to determine whether a rebuild is required.
  The new `redo-docs' always regenerates the texi file and thus all
  other formats.  Use that target before publishing the manual.

- Teach `html-dir' to only regenerate if the texi file has actually
  been touched.

- However when `html-dir' does regenerate, we must first remove all
  existing html files, to avoid files that used to be generated but
  are not being generated anymore, from sticking around.

Makefile

@@ -9,7 +9,8 @@ help:
 	$(info make all          - generate lisp and manual)
 	$(info make lisp         - generate byte-code and autoloads)
 	$(info make redo         - re-generate byte-code and autoloads)
-	$(info make docs         - generate most manual formats)
+	$(info make docs         - generate all manual formats)
+	$(info make redo-docs    - re-generate all manual formats)
 	$(info make texi         - generate texi manual)
 	$(info make info         - generate info manual)
 	$(info make html         - generate html manual file)
@@ -22,13 +23,15 @@ help:
 	$(info make clean        - remove most generated files)
 	@printf "\n"
 
-redo:
-	@$(MAKE) -C lisp clean lisp
 lisp:
 	@$(MAKE) -C lisp lisp
+redo:
+	@$(MAKE) -C lisp clean lisp
 
 docs:
 	@$(MAKE) -C docs docs
+redo-docs:
+	@$(MAKE) -C docs redo-docs
 texi:
 	@$(MAKE) -C docs texi
 info:

docs/Makefile

@@ -3,16 +3,21 @@ include ../default.mk
 
 docs: texi info html html-dir pdf
 
-texi: $(PKG).texi
-info: $(PKG).info dir
-html: $(PKG).html
-pdf:  $(PKG).pdf
+texi:     $(PKG).texi
+info:     $(PKG).info dir
+html:     $(PKG).html
+html-dir: $(PKG)/index.html
+pdf:      $(PKG).pdf
 
 ORG_ARGS  = --batch -Q $(ORG_LOAD_PATH)
 ORG_EVAL += --eval "(setq indent-tabs-mode nil)"
 ORG_EVAL += --eval "(setq org-src-preserve-indentation nil)"
 ORG_EVAL += --funcall org-texinfo-export-to-texinfo
 
+redo-docs:
+	@touch $(PKG).org
+	@make docs
+
 %.texi: %.org
 	@printf "Generating $@\n"
 	@$(EMACS) $(ORG_ARGS) $< $(ORG_EVAL)
@@ -40,8 +45,9 @@ HTML_FIXUP_MENU   = '/<\/body>/i<div id="s-css-s--menu"><\/div>'
 	@$(MAKEINFO) --html --no-split $(MANUAL_HTML_ARGS) $<
 	@sed -i -e $(HTML_FIXUP_CSS) -e $(HTML_FIXUP_ONLOAD) -e $(HTML_FIXUP_MENU) $@
 
-html-dir: $(PKG).texi
+%/index.html: %.texi
 	@printf "Generating $(PKG)/*.html\n"
+	@rm -rf $(PKG)
 	@$(MAKEINFO) --html -o $(PKG)/ $(MANUAL_HTML_ARGS) $<
 	@for f in $$(find $(PKG) -name '*.html') ; do \
 	sed -i -e $(HTML_FIXUP_CSS) -e $(HTML_FIXUP_ONLOAD) -e $(HTML_FIXUP_MENU) $$f ; \
@@ -62,15 +68,15 @@ comma := ,
 empty :=
 space := $(empty) $(empty)
 
-publish: html html-dir pdf
+publish: redo-docs
 	@aws s3 cp $(PKG).html $(PUBLISH_TARGET)
 	@aws s3 cp $(PKG).pdf  $(PUBLISH_TARGET)
 	@aws s3 sync $(PKG)    $(PUBLISH_TARGET)$(PKG)/
 	@printf "Generating CDN invalidation\n"
 	@aws cloudfront create-invalidation --distribution-id $(CFRONT_DIST) --paths \
 	"$(subst $(space),$(comma),$(addprefix $(PUBLISH_PATH),$(CFRONT_PATHS)))" > /dev/null
 
-release: html html-dir pdf
+release: redo-docs
 	@aws s3 cp $(PKG).html $(RELEASE_TARGET)
 	@aws s3 cp $(PKG).pdf  $(RELEASE_TARGET)
 	@aws s3 sync $(PKG)    $(RELEASE_TARGET)$(PKG)/