On 7/3/24 14:48, Bruno Haible wrote:
(Btw, is UTC=0 correct? I thought it should be UTC0
It's not portable, although it happens to work on most systems since
they default to UTC if TZ has a bogus value.
I installed the attached to fix that, and to improve on other issues I
noticed in that doc file. The basic idea is to shorten the documentation
by giving the reproducible recipe first, and then telling people what
line to omit if they don't want reproducibility.From dc2886c010dc34665370be055b2d93ff9aed68d2 Mon Sep 17 00:00:00 2001
From: Paul Eggert <egg...@cs.ucla.edu>
Date: Thu, 4 Jul 2024 00:31:33 +0100
Subject: [PATCH] gitlog-to-changelog: improve doc
---
doc/gitlog-to-changelog.texi | 70 ++++++++++++++----------------------
1 file changed, 27 insertions(+), 43 deletions(-)
diff --git a/doc/gitlog-to-changelog.texi b/doc/gitlog-to-changelog.texi
index 137b15fcda..5dc1043e45 100644
--- a/doc/gitlog-to-changelog.texi
+++ b/doc/gitlog-to-changelog.texi
@@ -12,8 +12,8 @@
@cindex gitlog
@cindex changelog
-Gnulib have a module @code{gitlog-to-changelog} to parse @code{git log}
-output and generate @code{ChangeLog} files, see
+Gnulib has a module @code{gitlog-to-changelog} to parse @code{git log}
+output and generate @file{ChangeLog} files; see
@ifinfo
@ref{Change Logs,,,standards}.
@end ifinfo
@@ -21,61 +21,45 @@ output and generate @code{ChangeLog} files, see
@url{https://www.gnu.org/prep/standards/html_node/Change-Logs.html}.
@end ifnotinfo
-You would typically use it by extending the @code{dist-hook} in the
-top-level @code{Makefile.am} like this:
+You can use it by extending the @code{dist-hook} rule in the
+top-level @file{Makefile.am} like this:
@example
dist-hook: gen-ChangeLog
-...
.PHONY: gen-ChangeLog
gen-ChangeLog:
- $(AM_V_GEN)if test -e .git; then \
- $(top_srcdir)/build-aux/gitlog-to-changelog > \
- $(distdir)/cl-t && \
- @{ rm -f $(distdir)/ChangeLog && \
- mv $(distdir)/cl-t $(distdir)/ChangeLog; @} \
+ $(AM_V_GEN)if test -e .git; then \
+ LC_ALL=en_US.UTF-8 TZ=UTC0 \
+ $(top_srcdir)/build-aux/gitlog-to-changelog \
+ > $(distdir)/ChangeLog.tmp && \
+ mv -f $(distdir)/ChangeLog.tmp $(distdir)/ChangeLog; \
fi
@end example
See @code{gitlog-to-changelog --help} for complete documentation.
-The tool prints timestamps using @code{localtime}, so its output may be
-different depending on what locale the developer that runs the tool is
-using. If your project desire reproducible ChangeLog files that doesn't
-depend on locale settings, use something like the following.
+The @code{LC_ALL=en_US.UTF-8 TZ=UTC0} line in this recipe assumes that
+you want to generate reproducible @file{ChangeLog} files that do not
+depend on the developer's locale and time zone. Omit this line if you
+prefer @file{ChangeLog} files that depend on these developer settings.
-@example
-gen-ChangeLog:
- $(AM_V_GEN)if test -e .git; then \
- env LC_ALL=en_US.UTF-8 TZ=UTC=0 \
- $(top_srcdir)/build-aux/gitlog-to-changelog > \
- $(distdir)/cl-t && \
- @{ rm -f $(distdir)/ChangeLog && \
- mv $(distdir)/cl-t $(distdir)/ChangeLog; @} \
- fi
-@end example
-
-
-If you wish to limit the ChangeLog entries (perhaps for size issues) to
-only contain entries since a particular git tag, use something like the
-following:
+If you wish to limit the @file{ChangeLog} entries (perhaps for size
+issues) to contain only entries since a particular git tag, you can
+use a @code{gen-ChangeLog} rule like the following:
@example
-dist-hook: gen-ChangeLog
-...
gen_start_ver = 8.31
-.PHONY: gen-ChangeLog
gen-ChangeLog:
- $(AM_V_GEN)if test -e .git; then \
- log_fix="$(srcdir)/build-aux/git-log-fix"; \
- test -e "$$log_fix" \
- && amend_git_log="--amend=$$log_fix" \
- || amend_git_log=; \
- $(top_srcdir)/build-aux/gitlog-to-changelog $$amend_git_log \
- -- v$(gen_start_ver)~.. > $(distdir)/cl-t && \
- @{ printf '\n\nSee the source repo for older entries\n' \
- >> $(distdir)/cl-t && \
- rm -f $(distdir)/ChangeLog && \
- mv $(distdir)/cl-t $(distdir)/ChangeLog; @} \
+ $(AM_V_GEN)if test -e .git; then \
+ log_fix='$(srcdir)/build-aux/git-log-fix'; \
+ test -e "$$log_fix" \
+ && amend_git_log=--amend=$$log_fix \
+ || amend_git_log=; \
+ @{ LC_ALL=en_US.UTF-8 TZ=UTC0 \
+ $(top_srcdir)/build-aux/gitlog-to-changelog \
+ "$$amend_git_log" -- 'v$(gen_start_ver)~..' && \
+ printf '\n\nSee the source repo for older entries.\n'; \
+ @} > $(distdir)/ChangeLog.tmp && \
+ mv -f $(distdir)/ChangeLog.tmp $(distdir)/ChangeLog; \
fi
@end example
--
2.34.1
