]> Savannah Git Hosting - gnulib.git/commitdiff
gitlog-to-changelog: improve doc
authorPaul Eggert <eggert@cs.ucla.edu>
Wed, 3 Jul 2024 23:31:33 +0000 (00:31 +0100)
committerPaul Eggert <eggert@cs.ucla.edu>
Wed, 3 Jul 2024 23:32:50 +0000 (00:32 +0100)
doc/gitlog-to-changelog.texi

index 137b15fcda5b2ae7730e3b9d200f92d9c24c8bb2..5dc1043e4575aea3b5f054f69ef52a6782df5a16 100644 (file)
@@ -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