Re: *.m4 conventions

[Paul Eggert]

On 2024-05-13 13:23, Bruno Haible wrote:

   # stdio_h.m4 - Autoconf macros for the stdio module.
   # serial 42


Oh, I didn't know you could do that. Thanks, I'll keep it in mind.

Re: *.m4 conventions

[Bruno Haible]

Paul Eggert wrote:
> Although that's true for experts, it's not necessarily true for 
> beginners who are the main audience for the first line. A beginner won't 
> know whether stdio_h.m4 is for the entire stdio module, or just for 
> configuring the stdio.h replacement, or just for configuring the stdio 
> implementation, or something else.
> 
> In general the first line could be quite helpful for a brief explanation 
> of file contents, for non experts. Yes, this information can be put 
> elsewhere in the .m4 file, but the first line is a better place for it.

I have nothing against adding these brief explanations as a second line:

  # stdio_h.m4
  # Autoconf macros for the stdio module.
  # serial 42

or even in the first line:

  # stdio_h.m4 - Autoconf macros for the stdio module.
  # serial 42

This would satisfy my concerns as well as yours, I think?

Bruno

Re: *.m4 conventions

[Paul Eggert]

On 2024-05-13 09:57, Bruno Haible wrote:

Note that in Gnulib, a human-readable comment
   # Autoconf macros for the stdio module.
is just as trivial as this comment:
   # stdio_h.m4


Although that's true for experts, it's not necessarily true for 
beginners who are the main audience for the first line. A beginner won't 
know whether stdio_h.m4 is for the entire stdio module, or just for 
configuring the stdio.h replacement, or just for configuring the stdio 
implementation, or something else.


In general the first line could be quite helpful for a brief explanation 
of file contents, for non experts. Yes, this information can be put 
elsewhere in the .m4 file, but the first line is a better place for it.

Re: *.m4 conventions

[Bruno Haible]

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  

doc: Document our conventions for *.m4 files.
Suggested by Paul Eggert in
.
* 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}