Subject: Re: implement a stable 'Last updated' in Documentation

From: Olaf Hering <[email-masked]>
Date: Tue, 27 Jan 2015 12:11:07 +0100

On Mon, Jan 26, Olaf Hering wrote:

> Several files in Documentation have an unstable 'Last updated' timestamp. The
> reason is that their mtime changes every time, which prevents reproducible
> builds.
> 
> 341 technical/api-index.txt: technical/api-index-skel.txt \
> 342         technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
> 343         $(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
> 
> 388 howto-index.txt: howto-index.sh $(wildcard howto/*.txt)
> 389         $(QUIET_GEN)$(RM) $@+ $@ && \
> 390         '$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(wildcard howto/*.txt)) >$@+ && \
> 391         mv $@+ $@
> 
> 399 $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt
> 400         $(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
> 401         sed -e '1,/^$$/d' $< | \
> 402         $(TXT_TO_HTML) - >$@+ && \
> 403         mv $@+ $@
> 
> What file timestamp should be used for them? Likely "../version"?
> The final file, before passing it to asciidoc, should get a fixed timestamp
> with 'touch -r $reference_file $file'.

I came up with this change. If anything happens to depend on
howto-index.txt and technical/api-index.txt then this part needs rework.

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 3e39e28..25ad0bd 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -6,6 +6,7 @@ TECH_DOCS =
 ARTICLES =
 SP_ARTICLES =
 OBSOLETE_HTML =
+TIMESTAMP_FILE = ../version
 
 MAN1_TXT += $(filter-out \
 		$(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \
@@ -341,6 +342,7 @@ user-manual.xml: user-manual.txt user-manual.conf
 technical/api-index.txt: technical/api-index-skel.txt \
 	technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
 	$(QUIET_GEN)cd technical && '$(SHELL_PATH_SQ)' ./api-index.sh
+	touch -r '$(TIMESTAMP_FILE)' $@
 
 technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
 $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt asciidoc.conf
@@ -388,6 +390,7 @@ $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml
 howto-index.txt: howto-index.sh $(wildcard howto/*.txt)
 	$(QUIET_GEN)$(RM) $@+ $@ && \
 	'$(SHELL_PATH_SQ)' ./howto-index.sh $(sort $(wildcard howto/*.txt)) >$@+ && \
+	touch -r '$(TIMESTAMP_FILE)' $@+ && \
 	mv $@+ $@
 
 $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
@@ -397,9 +400,12 @@ WEBDOC_DEST = /pub/software/scm/git/docs
 
 howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
 $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt
-	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
-	sed -e '1,/^$$/d' $< | \
-	$(TXT_TO_HTML) - >$@+ && \
+	$(QUIET_ASCIIDOC)$(RM) $@++ $@+ $@ && \
+	sed -e '1,/^$$/d' $< >$@++ && \
+	touch -r '$(TIMESTAMP_FILE)' $@++ && \
+	$(TXT_TO_HTML) -o $@+ $@++ && \
+	$(RM) $@++ && \
+	touch $@+ && \
 	mv $@+ $@
 
 install-webdoc : html

Olaf