:: commit 4db04403eff134cb52db16da30314e4cec22c5c5

Caleb Maclennan <caleb@alerque.com> — 2022-10-27 12:21

parents: 5eab953be1

Add version info and proper cross-linking to man pages (#68)

* Extend autotools package name tranformation support to man pages

* Extend autotools to support build dates without breaking reproducable builds

* Add program version and date to man pages

* Remove extranious spaces so man pages cross-link
diff --git a/.gitignore b/.gitignore
index 0d3df43..738bb6a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -33,8 +33,12 @@ Makefile
 Makefile.in
 autom4te.cache/
 /build-aux/*
+!/build-aux/ax_build_date_epoch.m4
 !/build-aux/ax_check_compile_flag.m4
 !/build-aux/ax_pthread.m4
+!/build-aux/ax_progvar.m4
+!/build-aux/ax_subst_man_date.m4
+!/build-aux/ax_transformed_package_name.m4
 !/build-aux/git-version-gen
 bzip3.pc
 
diff --git a/build-aux/ax_build_date_epoch.m4 b/build-aux/ax_build_date_epoch.m4
new file mode 100644
index 0000000..dbecb06
--- /dev/null
+++ b/build-aux/ax_build_date_epoch.m4
@@ -0,0 +1,70 @@
+# ===========================================================================
+#   https://www.gnu.org/software/autoconf-archive/ax_build_date_epoch.html
+# ===========================================================================
+#
+# SYNOPSIS
+#
+#   AX_BUILD_DATE_EPOCH(VARIABLE[, FORMAT[, ACTION-IF-FAIL]])
+#
+# DESCRIPTION
+#
+#   Sets VARIABLE to a string representing the current time.  It is
+#   formatted according to FORMAT if specified, otherwise it is formatted as
+#   the number of seconds (excluding leap seconds) since the UNIX epoch (01
+#   Jan 1970 00:00:00 UTC).
+#
+#   If the SOURCE_DATE_EPOCH environment variable is set, it uses the value
+#   of that variable instead of the current time.  See
+#   https://reproducible-builds.org/specs/source-date-epoch).  If
+#   SOURCE_DATE_EPOCH is set but cannot be properly interpreted as a UNIX
+#   timestamp, then execute ACTION-IF-FAIL if specified, otherwise error.
+#
+#   VARIABLE is AC_SUBST-ed.
+#
+# LICENSE
+#
+#   Copyright (c) 2016 Eric Bavier <bavier@member.fsf.org>
+#
+#   This program is free software: you can redistribute it and/or modify it
+#   under the terms of the GNU General Public License as published by the
+#   Free Software Foundation, either version 3 of the License, or (at your
+#   option) any later version.
+#
+#   This program is distributed in the hope that it will be useful, but
+#   WITHOUT ANY WARRANTY; without even the implied warranty of
+#   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+#   Public License for more details.
+#
+#   You should have received a copy of the GNU General Public License along
+#   with this program. If not, see <https://www.gnu.org/licenses/>.
+#
+#   As a special exception, the respective Autoconf Macro's copyright owner
+#   gives unlimited permission to copy, distribute and modify the configure
+#   scripts that are the output of Autoconf when processing the Macro. You
+#   need not follow the terms of the GNU General Public License when using
+#   or distributing such scripts, even though portions of the text of the
+#   Macro appear in them. The GNU General Public License (GPL) does govern
+#   all other use of the material that constitutes the Autoconf Macro.
+#
+#   This special exception to the GPL applies to versions of the Autoconf
+#   Macro released by the Autoconf Archive. When you make and distribute a
+#   modified version of the Autoconf Macro, you may extend this special
+#   exception to the GPL to apply to your modified version as well.
+
+#serial 2
+
+AC_DEFUN([AX_BUILD_DATE_EPOCH],
+[dnl
+AC_MSG_CHECKING([for build time])
+ax_date_fmt="m4_default($2,%s)"
+AS_IF([test x"$SOURCE_DATE_EPOCH" = x],
+ [$1=`date "+$ax_date_fmt"`],
+ [ax_build_date=`date -u -d "@$SOURCE_DATE_EPOCH" "+$ax_date_fmt" 2>/dev/null \
+                 || date -u -r "$SOURCE_DATE_EPOCH" "+$ax_date_fmt" 2>/dev/null`
+  AS_IF([test x"$ax_build_date" = x],
+   [m4_ifval([$3],
+      [$3],
+      [AC_MSG_ERROR([malformed SOURCE_DATE_EPOCH])])],
+   [$1=$ax_build_date])])
+AC_MSG_RESULT([$$1])
+])dnl AX_BUILD_DATE_EPOCH
diff --git a/build-aux/ax_progvar.m4 b/build-aux/ax_progvar.m4
new file mode 100644
index 0000000..131c806
--- /dev/null
+++ b/build-aux/ax_progvar.m4
@@ -0,0 +1,5 @@
+AC_DEFUN([AX_PROGVAR], [
+          test -n "$m4_toupper($1)" || { AC_PATH_PROG(m4_toupper($1), m4_default($2,$1)) }
+          test -n "$m4_toupper($1)" || AC_MSG_ERROR([m4_default($2,$1) is required])
+         ])
+
diff --git a/build-aux/ax_subst_man_date.m4 b/build-aux/ax_subst_man_date.m4
new file mode 100644
index 0000000..3eea16d
--- /dev/null
+++ b/build-aux/ax_subst_man_date.m4
@@ -0,0 +1,13 @@
+AC_DEFUN([AX_SUBST_MAN_DATE], [
+          ax_date_fmt="m4_default($1,%d %B %Y)"
+          ax_src_file="m4_default($2,*.1.in)"
+          AS_IF([test ! -e .gitignore],
+                     [
+                      AX_PROGVAR([date])
+                      AX_BUILD_DATE_EPOCH(MAN_DATE, "$ax_date_fmt")
+                     ], [
+                      AX_PROGVAR([git])
+                      MAN_DATE=$($GIT log -1 --format="%cd" --date=format:"$ax_date_fmt" -- $ax_src_file)
+                     ])
+          AC_SUBST([MAN_DATE])
+])
diff --git a/build-aux/ax_subst_transformed_package_name.m4 b/build-aux/ax_subst_transformed_package_name.m4
new file mode 100644
index 0000000..a6ae774
--- /dev/null
+++ b/build-aux/ax_subst_transformed_package_name.m4
@@ -0,0 +1,5 @@
+AC_DEFUN([AX_SUBST_TRANSFORMED_PACKAGE_NAME], [
+          AC_PROG_SED
+          TRANSFORMED_PACKAGE_NAME="$(printf "$PACKAGE_NAME" | $SED -e "$(printf "$program_transform_name" | $SED -e 's/\$\$/\$/')")"
+          AC_SUBST([TRANSFORMED_PACKAGE_NAME])
+])
diff --git a/bz3grep.1 b/bz3grep.1
deleted file mode 100644
index c1b5fd9..0000000
--- a/bz3grep.1
+++ /dev/null
@@ -1,22 +0,0 @@
-.TH "BZ3GREP" "1"
-.
-.SH "NAME"
-\fBbz3grep\fR \- print lines matching a pattern in bzip3\-compressed files
-.
-.SH "SYNOPSIS"
-\fBbz3grep\fR [\fIgrep\-flags\fR] [\-\-] \fIpattern\fR [\fIfiles\fR \.\.\.]
-.
-.SH "DESCRIPTION"
-\fBbz3grep\fR runs \fBgrep (1)\fR on files, or \fBstdin\fR if no files argument is given, after decompressing them with \fBbz3cat (1)\fR\.
-.
-.P
-The grep\-flags and pattern arguments are passed on to \fBgrep (1)\fR\. If an \fB\-e\fR flag is found in the \fBgrep\-flags\fR, \fBbz3grep\fR will not look for a pattern argument\.
-.
-.SH "EXIT STATUS"
-In case of missing arguments or missing pattern, 1 will be returned, otherwise 0\.
-.
-.SH "SEE ALSO"
-\fBbzip3 (1)\fR
-.
-.SH "AUTHORS"
-Thomas Klausner \fIwiz@NetBSD\.org\fR
\ No newline at end of file
diff --git a/bz3grep.1.in b/bz3grep.1.in
new file mode 100644
index 0000000..a4c4971
--- /dev/null
+++ b/bz3grep.1.in
@@ -0,0 +1,22 @@
+.TH bz3grep 1 "@MAN_DATE@" "version v@VERSION@"
+.
+.SH "NAME"
+\fBbz3grep\fR \- print lines matching a pattern in bzip3\-compressed files
+.
+.SH "SYNOPSIS"
+\fBbz3grep\fR [\fIgrep\-flags\fR] [\-\-] \fIpattern\fR [\fIfiles\fR \.\.\.]
+.
+.SH "DESCRIPTION"
+\fBbz3grep\fR runs \fBgrep(1)\fR on files, or \fBstdin\fR if no files argument is given, after decompressing them with \fBbz3cat(1)\fR\.
+.
+.P
+The grep\-flags and pattern arguments are passed on to \fBgrep(1)\fR\. If an \fB\-e\fR flag is found in the \fBgrep\-flags\fR, \fBbz3grep\fR will not look for a pattern argument\.
+.
+.SH "EXIT STATUS"
+In case of missing arguments or missing pattern, 1 will be returned, otherwise 0\.
+.
+.SH "SEE ALSO"
+\fBbzip3(1)\fR
+.
+.SH "AUTHORS"
+Thomas Klausner \fIwiz@NetBSD\.org\fR
diff --git a/bz3less.1 b/bz3less.1.in
similarity index 57%
rename from bz3less.1
rename to bz3less.1.in
index e19d579..20f3aff 100644
--- a/bz3less.1
+++ b/bz3less.1.in
@@ -1,5 +1,5 @@
-.TH BZ3LESS 1
-
+.TH bz3less 1 "@MAN_DATE@" "version v@VERSION@"
+.
 .SH "NAME"
 \fBbz3less\fR \- view bzip3\-compressed files
 
@@ -7,9 +7,9 @@
 \fBbz3less\fR [\fIflags\fR] [\fIfile\fR \.\.\.]
 
 .SH "DESCRIPTION"
-\fBbz3less\fR runs \fBless (1)\fR on files or stdin,
+\fBbz3less\fR runs \fBless(1)\fR on files or stdin,
 if no files argument is given, after decompressing them
-with \fBbz3cat (1)\fR\.
+with \fBbz3cat(1)\fR\.
 
 .SH "SEE ALSO"
-\fBbzip3 (1)\fR, \fBless (1)\fR
+\fBbzip3(1)\fR, \fBless(1)\fR
diff --git a/bz3more.1 b/bz3more.1.in
similarity index 57%
rename from bz3more.1
rename to bz3more.1.in
index afbc466..814870f 100644
--- a/bz3more.1
+++ b/bz3more.1.in
@@ -1,5 +1,5 @@
-.TH BZ3MORE 1
-
+.TH bz3more 1 "@MAN_DATE@" "version v@VERSION@"
+.
 .SH "NAME"
 \fBbz3more\fR \- view bzip3\-compressed files
 
@@ -7,9 +7,9 @@
 \fBbz3more\fR [\fIflags\fR] [\fIfile\fR \.\.\.]
 
 .SH "DESCRIPTION"
-\fBbz3more\fR runs \fBmore (1)\fR on files or stdin,
+\fBbz3more\fR runs \fBmore(1)\fR on files or stdin,
 if no files argument is given, after decompressing them
-with \fBbz3cat (1)\fR\.
+with \fBbz3cat(1)\fR\.
 
 .SH "SEE ALSO"
-\fBbzip3 (1)\fR, \fBmore (1)\fR
+\fBbzip3(1)\fR, \fBmore(1)\fR
diff --git a/bzip3.1 b/bzip3.1.in
similarity index 84%
rename from bzip3.1
rename to bzip3.1.in
index ee6114d..413e99b 100644
--- a/bzip3.1
+++ b/bzip3.1.in
@@ -1,10 +1,11 @@
-.TH BZIP3 1
+.TH @TRANSFORMED_PACKAGE_NAME@ 1 "@MAN_DATE@" "version v@VERSION@"
+.
 .SH NAME
-bzip3 \- an efficient statistical file compressor and spiritual successor
+@TRANSFORMED_PACKAGE_NAME@ \- an efficient statistical file compressor and spiritual successor
 to bzip2
 
 .SH SYNOPSIS
-.B bzip3
+.B @TRANSFORMED_PACKAGE_NAME@
 .RB [ " \-BbcdehftV " ]
 [
 .I "filenames \&..."
@@ -13,16 +14,16 @@ to bzip2
 .P
 .B bz3cat
 is equivalent to
-.B bzip3 \-dc
+.B @TRANSFORMED_PACKAGE_NAME@ \-dc
 .P
 .B bunzip3
 is equivalent to
-.B bzip3 \-d
+.B @TRANSFORMED_PACKAGE_NAME@ \-d
 .SH DESCRIPTION
 Compress or decompress a file using run length encoding and Lempel Ziv
 prediction, followed by the Burrows-Wheeler transform and arithmetic
 coding.
-.B bzip3,
+.B @TRANSFORMED_PACKAGE_NAME@,
 like its ancestor
 .B bzip2,
 excels at compressing text or source code.
@@ -32,20 +33,20 @@ those of
 .B bzip2,
 but they are not identical.
 .PP
-.B bzip3
+.B @TRANSFORMED_PACKAGE_NAME@
 expects at most two filenames intertwined with flags.
-.B bzip3
+.B @TRANSFORMED_PACKAGE_NAME@
 will by default not overwrite existing files.
 If this behaviour is intended, use the \-f flag.
 
 If no file names are specified,
-.B bzip3
+.B @TRANSFORMED_PACKAGE_NAME@
 will compress from standard input to standard output, refusing
 to output binary data to a terminal. The \-e flag (encode) is implied.
 
 .B bunzip3
 (or,
-.B bzip3 \-d
+.B @TRANSFORMED_PACKAGE_NAME@ \-d
 equivalently) decompresses data from standard input to the standard
 output, refusing to read from a terminal.
 
@@ -53,9 +54,9 @@ If two files are specified, the first one is used in place of
 standard input, and the second one is used in place of standard
 output.
 
-If the \-c flag is present, bzip3 will read from the specified
+If the \-c flag is present, @TRANSFORMED_PACKAGE_NAME@ will read from the specified
 file and output data to standard output instead. Otherwise, if decoding,
-.B bzip3
+.B @TRANSFORMED_PACKAGE_NAME@
 will try to guess the decompressed filename by removing the
 .I .bz3
 extension. If not present, an error will be reported. If encoding,
@@ -67,12 +68,12 @@ extension to the input filename.
 .TP
 .B \-B --batch
 Enable batch mode. By default,
-.B bzip3
+.B @TRANSFORMED_PACKAGE_NAME@
 will error if more than two files are passed, and the two files specified
 are always treated as input and output. The batch mode makes
-.B bzip3
+.B @TRANSFORMED_PACKAGE_NAME@
 treat every file as input, so for example
-.I bzip3 -Bd *.bz3
+.I @TRANSFORMED_PACKAGE_NAME@ -Bd *.bz3
 will decompress all
 .I .bz3
 files in the current directory.
@@ -99,6 +100,7 @@ Display a help message and exit.
 .TP
 .B \-v --verbose
 Set verbose output mode to see compression statistics.
+.TP
 .B \-V --version
 Display version information and exit.
 .TP
@@ -120,7 +122,7 @@ file format has constant overhead of 9 bytes per file and from
 9 to 17 bytes per block. Random data is coded so that expansion
 is generally under 0.8%.
 
-.B bzip3
+.B @TRANSFORMED_PACKAGE_NAME@
 uses 32-bit CRC to ensure that the decompressed version of a file is
 identical to the original. This guards against corruption of the
 compressed data. 
@@ -151,4 +153,4 @@ helped with portability problems, encouraged me to work on bzip3 and lent
 me machines for performance tests.
 
 .SH "SEE ALSO"
-\fBbzip2 (1)\fR, \fBbz3less (1)\fR, \fBbz3more (1)\fR, \fBbz3grep (1)\fR, \fBbunzip3\fR
+\fBbzip2(1)\fR, \fBbz3less(1)\fR, \fBbz3more(1)\fR, \fBbz3grep(1)\fR, \fBbunzip3(1)\fR
diff --git a/configure.ac b/configure.ac
index bd3a561..15fc864 100644
--- a/configure.ac
+++ b/configure.ac
@@ -59,6 +59,10 @@ AM_COND_IF([PASSED_CFLAGS], [
 	])
 ])
 
+AX_SUBST_TRANSFORMED_PACKAGE_NAME
+AX_SUBST_MAN_DATE
+
 AC_CONFIG_FILES([Makefile bzip3.pc])
+AC_CONFIG_FILES([bzip3.1 bz3grep.1 bz3less.1 bz3more.1])
 AC_ARG_PROGRAM
 AC_OUTPUT
tab: 248 wrap: offon