Drop the date from the committed man page (#3659)

The date in the .TH line of jq.1.prebuilt changed whenever the manual was
regenerated in a new month, causing merge conflicts between pull requests
that touch the manual, and it did not reflect the release date anyway.
Generate the committed man page without a date.

Stamp the date into jq.1 at build time instead, taking it from the current
commit, or from SOURCE_DATE_EPOCH where that is set, so that release
tarballs and distribution builds still carry one and the behaviour added
in #3514 is kept. Write it in UTC and in ISO 8601 rather than the previous
"%B %Y", for which mandoc reports "cannot parse date, using it verbatim".

.github/workflows/manpage.yml

@@ -42,12 +42,8 @@ jobs:
           ./configure --enable-docs
       - name: Build man page, man.test, manonig.test
         run: |
-          mv jq.1.prebuilt jq.1.old
+          rm -f jq.1.prebuilt tests/man.test tests/manonig.test
-          rm -f tests/man.test manonig.test
           make jq.1.prebuilt tests/man.test tests/manonig.test
       - name: Make sure that jq.1.prebuilt, man.test, manonig.test are up to date
         run: |
-          git diff --exit-code tests/man.test tests/manonig.test
+          git diff --exit-code jq.1.prebuilt tests/man.test tests/manonig.test
-          # skip build date in jq.1.prebuilt
-          test -s jq.1.prebuilt
-          diff -- <(tail -n +3 jq.1.old) <(tail -n +3 jq.1.prebuilt)

Makefile.am

@@ -190,8 +190,18 @@ else
 	@echo As a result, the manpage is out of date.
 endif
 
+# The committed manpage has no date to avoid merge conflicts. Stamp the date
+# of the last commit when building in a git repository, including on make
+# dist, so that release tarballs ship a dated jq.1. Respect SOURCE_DATE_EPOCH
+# so that distribution builds can pin the date.
 jq.1: jq.1.prebuilt
-	$(AM_V_GEN) cp $(srcdir)/jq.1.prebuilt $@
+	$(AM_V_GEN) date=`if test -n "$$SOURCE_DATE_EPOCH"; then \
+	    date -u -d "@$$SOURCE_DATE_EPOCH" +%F 2>/dev/null || \
+	    date -u -r "$$SOURCE_DATE_EPOCH" +%F 2>/dev/null; \
+	  elif test -e $(srcdir)/.git; then \
+	    cd $(srcdir) && git log -1 --format=%cd --date=short 2>/dev/null; \
+	  fi`; \
+	sed 's/^\.TH "JQ" "1" ""/.TH "JQ" "1" "'"$$date"'"/' $(srcdir)/jq.1.prebuilt > $@
 
 CLEANFILES += jq.1
 

docs/build_manpage.py

@@ -1,13 +1,10 @@
 #!/usr/bin/env python3
-from datetime import date
 from io import StringIO
 from lxml import etree
 import markdown
 from markdown.extensions import Extension
 import re
-import os
 import sys
-from time import time
 import yaml
 
 
@@ -68,9 +65,7 @@ class RoffWalker(object):
         last_tag = None
         while root is not None:
             if root.tag == 'h1':
-                epoch = int(os.environ.get('SOURCE_DATE_EPOCH', time()))
+                self.__write_cmd('.TH "JQ" "1" "" "" ""')
-                self.__write_cmd('.TH "JQ" "1" "{}" "" ""'.format(
-                    date.fromtimestamp(epoch).strftime('%B %Y')))
                 self.__write_cmd('.SH "NAME"')
                 # TODO: properly parse this
                 self.__write_raw(r'\fBjq\fR \- Command\-line JSON processor' +

jq.1.prebuilt

@@ -1,5 +1,5 @@
 .
-.TH "JQ" "1" "August 2026" "" ""
+.TH "JQ" "1" "" "" ""
 .
 .SH "NAME"
 \fBjq\fR \- Command\-line JSON processor