]> Savannah Git Hosting - gnulib.git/commitdiff
doc: Document our conventions for *.m4 files.
authorBruno Haible <bruno@clisp.org>
Mon, 13 May 2024 16:41:04 +0000 (18:41 +0200)
committerBruno Haible <bruno@clisp.org>
Mon, 13 May 2024 16:57:56 +0000 (18:57 +0200)
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.

ChangeLog
doc/gnulib.texi

index 97d3ab8813638f8c8dd37167ba890871071449a5..09cdfb44f953ee0a1c09c37f44efafd087175f63 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+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.
+
 2024-05-13  Paul Eggert  <eggert@cs.ucla.edu>
 
        stdbit: fix typo in MS-Windows port
index 24acb1afc8f6ec4e981fd0b242947413894b0508..07b18aa7b886e32cfdceeff27eac6ac63bb9f8a1 100644 (file)
@@ -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}