Paul Eggert wrote:
> Is this stuff documented somewhere in the .texi files? If not, I suppose
> it should be.
Done through the patch below.
> Frankly I continue to be annoyed by having to read and write a line "#
> FILENAME.m4" at the start of every m4 file FILENAME.m4. It's better for
> a file's first line to be a human-readable comment explaining what the
> file is for. Any automated procedure already knows the file name, so why
> do we need to put the name there manually, an error-prone process?
Documented as below.
Note that in Gnulib, a human-readable comment
# Autoconf macros for the stdio module.
is just as trivial as this comment:
# stdio_h.m4
Note also that both the file name line and the serial number appear
to be *currently* unused for most Gnulib *.m4 files. That's because they
become relevant only for *.m4 files installed in $PREFIX/share/aclocal.
*Currently* there are only few (host-cpu-c-abi.m4, lib-*.m4, progtest.m4, ...)
because after being imported into gettext, gettext installs them in
$PREFIX/share/aclocal. But they become relevant again
- When users use *.m4 files outside of their package's directory
(and it's not our business to control or dictate the package structure
of the packages),
- When users or distros install *.m4 files globally, for whatever reason
(and it's not our business to control or dictate what distros do).
- When gnulib-tool's way of operating may change. I can imagine that
in a couple of years, the way gnulib-tool shares its source code
is different than what it is today. (Simon Josefsson and the Debian
project are already experimenting with alternative but correct ways
to distribute Gnulib.)
2024-05-13 Bruno Haible <br...@clisp.org>
doc: Document our conventions for *.m4 files.
Suggested by Paul Eggert in
<https://lists.gnu.org/archive/html/bug-gnulib/2024-05/msg00156.html>.
* doc/gnulib.texi (Autoconf macros): Document the structure of our *.m4
files.
diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index 24acb1afc8..07b18aa7b8 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -584,6 +584,27 @@
maintenance.
@end enumerate
+Autoconf macro files in Gnulib all start with a header consisting of
+@c https://lists.gnu.org/archive/html/bug-gnulib/2024-04/msg00053.html
+@enumerate
+@item
+A comment line with the file name.
+This is useful because in some cases the generated @code{aclocal.m4}
+file does not contain a reference to the @code{.m4} file but its entire
+contents.
+The comment makes it clear which @code{.m4} file is where in the
+@code{aclocal.m4} file.
+@item
+A comment line with a serial number.
+This is useful when people use the @samp{aclocal --install} command.
+@code{aclocal} will then refrain from copying a file with a smaller
+serial number onto a file with a larger serial number.
+The serial number should be a positive integer on the main branch,
+or a positive fractional number on a stable branch.
+@item
+The copyright and license header, as usual.
+@end enumerate
+
@node Using @code{AC_LIBOBJ}
@section Making proper use of @code{AC_LIBOBJ}
