From fa8b9c150126c0b7910c4c3ac9e283bdaf54088b Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Mon, 13 May 2024 18:41:04 +0200 Subject: [PATCH] doc: Document our conventions for *.m4 files. Suggested by Paul Eggert in . * doc/gnulib.texi (Autoconf macros): Document the structure of our *.m4 files. --- ChangeLog | 8 ++++++++ doc/gnulib.texi | 21 +++++++++++++++++++++ 2 files changed, 29 insertions(+) diff --git a/ChangeLog b/ChangeLog index 97d3ab8813..09cdfb44f9 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +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. + 2024-05-13 Paul Eggert stdbit: fix typo in MS-Windows port 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 @@ The Autoconf macros are often large enough that splitting them eases 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} -- 2.39.5