From: Jeff King <peff@peff.net>
Date: Fri, 14 Apr 2023 07:04:49 GMT
Subject: Re: [PATCH] doc: set actual revdate for manpages
Message-ID: <20230414070449.GA540206@coredump.intra.peff.net>
In-Reply-To: <20230413074722.71260-1-felipe.contreras@gmail.com>

On Thu, Apr 13, 2023 at 01:47:22AM -0600, Felipe Contreras wrote:

> manpages expect the date of the last revision, if that is not found
> DocBook Stylesheets go through a series of hacks to generate one with
> the format `%d/%d/%Y` which is not ideal.
> 
> In addition to this format not being standard, different tools generate
> dates with different formats.
> 
> There's no need for any confusion if we specify the revision date, so
> let's do so.

That seems like a good goal, and should reduce our asciidoc/asciidoctor
diff considerably.

> This patch requires [1] to actually work, and has a simple conflict with
> [2], so it's written on top of both.
> 
> [1] https://lore.kernel.org/git/20230323221523.52472-1-felipe.contreras@gmail.com/
> [2] https://lore.kernel.org/git/20230408001829.11031-1-felipe.contreras@gmail.com/

I wasted a bit of time trying this out, so let me elaborate on "actually
work" for the benefit of other reviewers. Without the patch in [1]
(which is 8806120de6c on fc/remove-header-workarounds-for-asciidoc),
this patch works as advertised with asciidoctor, but has no effect with
asciidoc.  The reason is that asciidoc puts the <date> tags in the
header, and the custom header removed by 8806120de6c suppresses
asciidoc's default header entirely (so a workaround would be to include
the <date> tags in our custom header, but I don't see any reason not to
just build on top of 8806120de6c, as you did here).

> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 3133ea3182..b629176d7d 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -144,13 +144,16 @@ man5dir = $(mandir)/man5
>  man7dir = $(mandir)/man7
>  # DESTDIR =
>  
> +GIT_DATE := $(shell git show --quiet --pretty='%as')

What will/should this do in a distribution tarball, where we won't have
a Git repository at all? I think we'll just end up with a blank date in
the xml file, though it looks like docbook turns that into today's date
in the result.

That's not _too_ bad, but feels a bit inconsistent (and it uses the
format you're trying to get rid of!).

It would be nicer to populate the date variable in that case, like we do
for GIT_VERSION. I think that could look something like this:

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 2ccc3a9bc9..307634a94f 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -144,8 +144,6 @@ man5dir = $(mandir)/man5
 man7dir = $(mandir)/man7
 # DESTDIR =
 
-GIT_DATE := $(shell git show --quiet --pretty='%as')
-
 ASCIIDOC = asciidoc
 ASCIIDOC_EXTRA =
 ASCIIDOC_HTML = xhtml11
diff --git a/GIT-VERSION-GEN b/GIT-VERSION-GEN
index 9a1111af9b..14903bd261 100755
--- a/GIT-VERSION-GEN
+++ b/GIT-VERSION-GEN
@@ -10,7 +10,8 @@ LF='
 # then try git-describe, then default.
 if test -f version
 then
-	VN=$(cat version) || VN="$DEF_VER"
+	VN=$(cut -d" " -f1 version) || VN="$DEF_VER"
+	DN=$(cut -d" " -f2 version) || DN=""
 elif test -d ${GIT_DIR:-.git} -o -f .git &&
 	VN=$(git describe --match "v[0-9]*" HEAD 2>/dev/null) &&
 	case "$VN" in
@@ -22,19 +23,22 @@ elif test -d ${GIT_DIR:-.git} -o -f .git &&
 	esac
 then
 	VN=$(echo "$VN" | sed -e 's/-/./g');
+	DN=$(git log -1 --format=%as HEAD)
 else
 	VN="$DEF_VER"
+	DN=""
 fi
 
 VN=$(expr "$VN" : v*'\(.*\)')
 
 if test -r $GVF
 then
-	VC=$(sed -e 's/^GIT_VERSION = //' <$GVF)
+	VC=$(sed -ne 's/^GIT_VERSION = //p' <$GVF)
 else
 	VC=unset
 fi
 test "$VN" = "$VC" || {
 	echo >&2 "GIT_VERSION = $VN"
 	echo "GIT_VERSION = $VN" >$GVF
+	echo "GIT_DATE = $DN" >>$GVF
 }
diff --git a/Makefile b/Makefile
index 60ab1a8b4f..fa8db1943c 100644
--- a/Makefile
+++ b/Makefile
@@ -3573,7 +3573,7 @@ endif
 dist: git-archive$(X) configure
 	@$(RM) -r .dist-tmp-dir
 	@mkdir .dist-tmp-dir
-	@echo $(GIT_VERSION) > .dist-tmp-dir/version
+	@echo $(GIT_VERSION) $(GIT_DATE) > .dist-tmp-dir/version
 	@$(MAKE) -C git-gui TARDIR=../.dist-tmp-dir/git-gui dist-version
 	./git-archive --format=tar \
 		$(GIT_ARCHIVE_EXTRA_FILES) \
-- 
2.40.0.515.gdfb9e78b42