[Automake-NG] [FYI] [ng] dist: enhance comments; prefer '#' over '##' where possible

[Stefano Lattarini]

* lib/am/distdir.am: Here, throughout the file, to make the output
makefile more comprehensible.

Signed-off-by: Stefano Lattarini <address@hidden>
---
 lib/am/distdir.am | 111 ++++++++++++++++++++++++++++++------------------------
 1 file changed, 62 insertions(+), 49 deletions(-)

diff --git a/lib/am/distdir.am b/lib/am/distdir.am
index d946226..b8cc67d 100644
--- a/lib/am/distdir.am
+++ b/lib/am/distdir.am
@@ -16,63 +16,68 @@
 
 am.dist.common-files += %DIST-COMMON%
 
-## Makefile fragments used internally by automake-generated Makefiles.
+# Makefile fragments used internally by automake-generated Makefiles.
 am.dist.mk-files = $(wildcard $(am.conf.aux-dir)/am-ng/*)
 
-## Use 'sort', not 'am.util.uniq', for performance reasons.  Luckily, we
-## don't care in which order the distributed files are.
+# Use 'sort', not 'am.util.uniq', for performance reasons.  Luckily, we
+# don't care in which order the distributed files are.
 am.dist.all-files = $(call am.memoize,am.dist.all-files,$(strip $(sort \
   $(am.dist.common-files) $(am.dist.sources) $(am.dist.mk-files) \
   $(TEXINFOS) $(EXTRA_DIST))))
 
-## Try to avoid repeated slashes in the entries, to make the filtering
-## in the 'am.dist.files-tmp2' definition below more reliable.
-## This idiom should compress up to four consecutive '/' characters
-## in each $(am.dist.all-files) entry.
+# Try to avoid repeated slashes in the entries, to make the filtering
+# in the 'am.dist.files-tmp2' definition below more reliable.
+# This idiom should compress up to four consecutive '/' characters
+# in each $(am.dist.all-files) entry.
 am.dist.files-tmp1 = $(call am.memoize,am.dist.files-tmp1, \
   $(subst //,/,$(subst //,/,$(am.dist.all-files))))
 
+# Files filtered out here require an ad-hoc "munging".
+#
+# 1. In the first $(patsubst), we strip leading $(srcdir) (which might
+#    appears in EXTRA_DIST, especially if one want to use the $(wildcard)
+#    built-in in there), so that in our 'distdir' recipe below we can loop
+#    on the list of distributed files and copy them in the distribution
+#    directory with a simple "cp $file $(distdir)/$file" -- which would
+#    break if $file contained a leading $(srcdir) component.  However,
+#    it should be noted that this filtering has the quite undesirable
+#    side effect of triggering a VPATH search also for files specified
+#    *explicitly* with a $(srcdir) prefix; but this limitation is also
+#    present in mainline Automake, and concerns only such corner-case
+#    situations that it's probably not worth worrying about.
+#
+# 2. In the second $(patsubst), we also rewrite $(top_srcdir) -- which
+#    can sometimes appear in $(am.dist.common-files), and can be an
+#    absolute path -- by $(top_builddir) (which is always relative).
+#    If needed, $(srcdir) will be prepended later by our VPATH-aware
+#    rules.  The same caveats reported above apply.
+#
 am.dist.files-tmp2 = $(call am.memoize,am.dist.files-tmp2, \
-## Files filtered out here require an ad-hoc "munging"; see the two
-## following 'patsubst's.
   $(filter-out $(srcdir)/% $(top_srcdir)/%, $(am.dist.files-tmp1)) \
-## Let's strip leading $(srcdir) (which might appears in EXTRA_DIST,
-## especially if one want to use the $(wildcard) built-in in there),
-## so that in our 'distdir' recipe below we can loop on the list of
-## distributed files and copy them in the distribution directory with
-## a simple "cp $file $(distdir)/$file" -- which would break if $file
-## contained a leading $(srcdir) component.
-## However, it should be noted that this filtering has the undesirable
-## side effect of triggering a VPATH search also for files specified
-## *explicitly* with a $(srcdir) prefix; but this limitation is also
-## present in mainstream Automake, and concerns only such corner-case
-## situations that it's probably not worth worrying about.
   $(patsubst $(srcdir)/%, %, \
              $(filter $(srcdir)/%, $(am.dist.files-tmp1))) \
-## Also rewrite $(top_srcdir) -- which can sometimes appear in
-## $(am.dist.common-files), and can be absolute -- by $(top_builddir)
-## (which is always relative).  If needed, $(srcdir) will be
-## prepended later by our VPATH-aware rules.
-## The same caveats reported above apply.
   $(patsubst $(top_srcdir)/%, $(top_builddir)/%, \
              $(filter $(top_srcdir)/%, $(am.dist.files-tmp1))))
 
-## Strip extra whitespaces, for more safety.
+# Strip extra whitespaces, for more safety.
 am.dist.files-cooked = \
   $(call am.memoize,am.dist.files-cooked,$(strip $(am.dist.files-tmp2)))
 
-## Given the pre-processing done above to the list of distributed files,
-## this definition ensures that we won't try to create the wrong
-## directories when $(top_srcdir) or $(srcdir) appears in some entry of
-## the list of all distributed files.
-## For example, with EXTRA_DIST containing "$(srcdir)/subdir/file", this
-## will allow our rules to correctly create "$(distdir)/subdir", and not
-## "$(distdir)/$(srcdir)/subdir" -- which, in a VPATH build where
-## "$(subdir) = ..", would be the build directory!
+# Given the pre-processing done above to the list of distributed files,
+# this definition ensures that we won't try to create the wrong
+# directories when $(top_srcdir) or $(srcdir) appears in some entry of
+# the list of all distributed files.
+# For example, with EXTRA_DIST containing "$(srcdir)/subdir/file", this
+# will allow our rules to correctly create "$(distdir)/subdir", and not
+# "$(distdir)/$(srcdir)/subdir" -- which, in a VPATH build where
+# "$(subdir) = ..", would be the build directory!
 am.dist.parent-dirs = \
   $(call am.memoize,am.dist.parent-dirs,$(strip $(sort \
     $(filter-out ., $(patsubst ./%,%,$(dir $(am.dist.files-cooked)))))))
 
+# These two variables are used in the 'distdir' rule below to avoid
+# potetial problems with overly long command lines (the infamous
+# "Argument list too long" error).
 am.dist.xmkdir = \
   @$(MKDIR_P) $(patsubst %,"$(distdir)"/%,$1)$(am.chars.newline)
 am.dist.write-filelist = \
@@ -80,31 +85,42 @@ am.dist.write-filelist = \
     >> $(am.dir)/address@hidden(am.chars.newline)
 
 if %?TOPDIR_P%
+
+# This is user-overridable.
 distdir = $(PACKAGE)-$(VERSION)
+# This is not, but must be public to be avaialable in the "dist-hook"
+# rules (this is also documented in the Automake manual).
 top_distdir = $(distdir)
 
+# A failed "make distcheck" might leace some parts of the $(distdir)
+# readonly, so we need these hoops to ensure it is removed correctly.
+# On MSYS (1.0.17, at least) it is not possible to remove a directory
+# that is in use; so, if the first rm fails, we sleep some seconds and
+# retry, to give pending processes some time to exit and "release" the
+# directory before we remove it.  The value of "some seconds" is 5 for
+# the moment, which is mostly an arbitrary value, but seems high enough
+# in practice.  See automake bug#10470.
 am.dist.remove-distdir = \
   if test -d "$(distdir)"; then \
     find "$(distdir)" -type d ! -perm -200 -exec chmod u+w {} ';' \
       && rm -rf "$(distdir)" \
-## On MSYS (1.0.17) it is not possible to remove a directory that is in
-## use; so, if the first rm fails, we sleep some seconds and retry, to
-## give pending processes some time to exit and "release" the directory
-## before we remove it.  The value of "some seconds" is 5 for the moment,
-## which is mostly an arbitrary value, but seems high enough in practice.
-## See automake bug#10470.
       || { sleep 5 && rm -rf "$(distdir)"; }; \
   else :; fi
+
+# Define this separately, so that if can be overridden by the recursive
+# make invocation in 'dist-all'.  That is needed to support concurrent
+# creation of different tarball formats.
 am.dist.post-remove-distdir = $(am.dist.remove-distdir)
+
 endif %?TOPDIR_P%
 
 if %?SUBDIRS%
-## computes a relative pathname RELDIR such that DIR1/RELDIR = DIR2.
-## Input:
-## - DIR1            relative pathname, relative to the current directory
-## - DIR2            relative pathname, relative to the current directory
-## Output:
-## - reldir          relative pathname of DIR2, relative to DIR1
+# Computes a relative pathname RELDIR such that DIR1/RELDIR = DIR2.
+# Input:
+#   - dir1      relative pathname, relative to the current directory.
+#   - dir2      relative pathname, relative to the current directory.
+# Output:
+#   - reldir    relative pathname of dir2, relative to dir1.
 am.dist.relativize-path = \
   dir0=`pwd`; \
   sed_first='s,^\([^/]*\)/.*$$,\1,'; \
@@ -152,9 +168,6 @@ if  %?CK-NEWS%
        esac
 endif  %?CK-NEWS%
 endif %?TOPDIR_P%
-##
-## Only for the top dir.
-##
 if %?TOPDIR_P%
        $(am.dist.remove-distdir)
        test -d "$(distdir)" || mkdir "$(distdir)"
-- 
1.7.12.rc0