Re: *.m4 conventions

[Bruno Haible <bruno@clisp.org>]

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  <bruno@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}