aspiers · aspiers · Apr 6, 2024 · May 24, 2020 · May 25, 2020 · May 25, 2020
diff --git a/.dir-locals.el b/.dir-locals.el
@@ -0,0 +1,6 @@
+((cperl-mode . ((dumb-jump-force-searcher . rg)
+                (cperl-indent-level . 4)
+                (cperl-close-paren-offset . -4)
+                (cperl-indent-subs-specially . nil)
+                (indent-tabs-mode . nil)
+                (eval . (auto-fill-mode -1)))))
diff --git a/.dumbjump b/.dumbjump
@@ -0,0 +1,2 @@
++bin/*.in
++lib/*.pm.in
diff --git a/AUTHORS b/AUTHORS
@@ -1,3 +1,7 @@
+This file documents the high-level history of Stow, and some of its
+major contributors.  See also the THANKS file for a more complete list
+of contributors.
+
 Stow was originally written by Bob Glickstein <[email protected]>,
 Zanshin Software, Inc.
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,106 @@
+Contributing to GNU Stow
+========================
+
+Development of Stow, and GNU in general, is a volunteer effort, and
+you can contribute.  If you'd like to get involved, it's a good idea to join
+the [stow-devel](https://lists.gnu.org/mailman/listinfo/stow-devel)
+mailing list.
+
+Bug reporting
+-------------
+
+Please follow the procedure described in [the "Reporting Bugs"
+section](https://www.gnu.org/software/stow/manual/html_node/Reporting-Bugs.html#Reporting-Bugs)
+of [the manual](README.md#documentation).
+
+Development
+-----------
+
+For [development sources](https://savannah.gnu.org/git/?group=stow)
+and other information, please see the [Stow project
+page](http://savannah.gnu.org/projects/stow/) at
+[savannah.gnu.org](http://savannah.gnu.org).
+
+There is also a
+[stow-devel](https://lists.gnu.org/mailman/listinfo/stow-devel)
+mailing list (see [Mailing lists](README.md#mailing-lists)).
+
+Please be aware that all program source files (excluding the test
+suite) end in `.in`, and are pre-processed by `Makefile` into
+corresponding files with that prefix stripped before execution.  So if
+you want to test any modifications to the source, make sure that you
+change the `.in` files and then run `make` to regenerate the
+pre-processed versions before doing any testing.  To avoid forgetting
+(which can potentially waste a lot of time debugging the wrong code),
+you can automatically run `make` in an infinite loop every second via:
+
+    make watch
+
+(You could even use fancier approaches like
+[`inotifywait(1)`](https://www.man7.org/linux/man-pages/man1/inotifywait.1.html)
+or [Guard](https://guardgem.org/).  But those are probably overkill in
+this case where the simple `while` loop is plenty good enough.)
+
+Testing
+~~~~~~~
+
+The test suite can be found in the [`t/`](t/) subdirectory.  You can
+run the test suite via:
+
+    make check
+
+Tests can be run individually as follows.  First you have to ensure
+that the `t/`, `bin/`, and `lib/` directories are on Perl's search path.
+Assuming that you run all tests from the root of the repository tree,
+this will do the job:
+
+    export PERL5LIB=t:bin:lib
+
+(Not all tests require all of these, but it's safer to include all of
+them.)
+
+Secondly, be aware that if you want to test modifications to the
+source files, you will need to run `make watch`, or `make` before each
+test run as explained above.
+
+Now running an individual test is as simple as:
+
+    perl t/chkstow.t
+
+or with a given debugging verbosity corresponding to the `-v` / `--verbose`
+command-line option:
+
+    TEST_VERBOSE=4 perl t/chkstow.t
+
+The [`prove(1)` test runner](https://perldoc.perl.org/prove) is another
+good alternative which provides several handy extra features.  Invocation
+is very similar, e.g.:
+
+    prove t/stow.t
+
+or to run the whole suite:
+
+    prove
+
+However currently there is an issue where this interferes with
+`TEST_VERBOSE`.
+
+Translating Stow
+----------------
+
+Stow is not currently multi-lingual, but patches would be very
+gratefully accepted. Please e-mail
+[stow-devel](https://lists.gnu.org/mailman/listinfo/stow-devel) if you
+intend to work on this.
+
+Maintainers
+-----------
+
+Stow is currently being maintained by Adam Spiers.  Please use [the
+mailing lists](README.md#mailing-lists).
+
+Helping the GNU project
+-----------------------
+
+For more general information, please read [How to help
+GNU](https://www.gnu.org/help/).
diff --git a/MANIFEST b/MANIFEST
@@ -3,6 +3,7 @@ aclocal.m4
 automake/install-sh
 automake/mdate-sh
 automake/missing
+automake/texinfo.tex
 bin/chkstow
 bin/chkstow.in
 bin/stow
@@ -11,6 +12,7 @@ Build.PL
 ChangeLog
 configure
 configure.ac
+CONTRIBUTING.md
 COPYING
 default-ignore-list
 doc/ChangeLog.OLD
@@ -19,7 +21,6 @@ doc/manual.pdf
 doc/stow.8
 doc/stow.info
 doc/stow.texi
-doc/texinfo.tex
 doc/version.texi
 INSTALL.md
 lib/Stow.pm
@@ -43,6 +44,7 @@ t/find_stowed_path.t
 t/foldable.t
 t/ignore.t
 t/join_paths.t
+t/link_dest_within_stow_dir.t
 t/parent.t
 t/stow.t
 t/rc_options.t

diff --git a/MANIFEST.SKIP b/MANIFEST.SKIP
@@ -87,3 +87,10 @@ tmp-testing-trees
 .travis.yml
 ^docker/
 ^[a-zA-Z]*-docker.sh
+
+# Avoid development config
+.dir-locals.el
+.dumbjump
+
+# Avoid CI
+.github/
diff --git a/Makefile.am b/Makefile.am
@@ -32,24 +32,24 @@ pmstowdir = $(pmdir)/Stow
 pm_DATA = lib/Stow.pm
 pmstow_DATA = lib/Stow/Util.pm
 
-TEXINFO_TEX = doc/texinfo.tex
 export TEXI2DVI_BUILD_MODE = clean
 AM_MAKEINFOFLAGS = -I $(srcdir)
 
 # We require this -I parameter to ensure that the include of the
-# default ignore list in the manual works.  Unfortunately this is
-# the only way to do it:
+# default ignore list in the manual works correctly, even when the
+# manual is being built via make distcheck from a different directory.
+# Unfortunately this is the only way to do it:
 #
-#   http://article.gmane.org/gmane.comp.sysutils.automake.bugs/4334/match=passing+parameters
+#   https://lists.gnu.org/archive/html/bug-automake/2008-09/msg00040.html
 #
 # even though it annoyingly produces a warning with the -Wall option
 # to AM_INIT_AUTOMAKE which has to be silenced via -Wno-override.
 TEXI2DVI = texi2dvi $(AM_MAKEINFOFLAGS)
 
-doc_deps = $(info_TEXINFOS) doc/version.texi
-
 DEFAULT_IGNORE_LIST = $(srcdir)/default-ignore-list
 
+doc_deps = $(info_TEXINFOS) doc/version.texi $(DEFAULT_IGNORE_LIST)
+
 TESTS_DIR = $(srcdir)/t
 TESTS_OUT = tmp-testing-trees
 TESTS_ENVIRONMENT = $(PERL) -Ibin -Ilib -I$(TESTS_DIR)
@@ -77,7 +77,7 @@ check_DATA = $(TESTS_OUT)
 # Note that automake's `check' rule cannot be overridden
 # for some weird reason:
 #
-#   http://thread.gmane.org/gmane.comp.sysutils.automake.general/13040/focus=13041
+#   https://lists.gnu.org/archive/html/automake/2011-09/msg00029.html
 #
 # so we override check-TESTS instead which is where the real work is
 # done anyway.  Unfortunately this produces a warning with the -Wall
@@ -95,7 +95,6 @@ EXTRA_DIST = \
 	bin/stow.in bin/chkstow.in lib/Stow.pm.in lib/Stow/Util.pm.in \
 	doc/manual-split \
 	$(TESTS) t/testutil.pm \
-	$(TEXINFO_TEX) \
 	$(DEFAULT_IGNORE_LIST) \
 	$(CPAN_FILES)
 CLEANFILES = $(bin_SCRIPTS) $(pm_DATA) $(pmstow_DATA)
@@ -190,7 +189,7 @@ doc/stow.8: bin/stow.in Makefile.am
 #
 # If it were not for a troublesome dependency on doc/$(am__dirstamp):
 #
-#   http://article.gmane.org/gmane.comp.sysutils.automake.general/13192
+#   https://lists.gnu.org/archive/html/automake/2011-11/msg00107.html
 #
 # we could have achieved this using the built-in rules combined with
 # install-data-hook to rename from stow.pdf to manual.pdf etc. on
@@ -299,3 +298,28 @@ ChangeLog: doc/ChangeLog.OLD
 	else \
 	    echo "Not in a git repository; can't update ChangeLog."; \
 	fi
+
+# Watch for changes, and if any rebuilds are required, also do a
+# make install.
+#
+# If we solved https://github.com/aspiers/stow/issues/84, we could
+# probably ditch this:
+watch:
+	@echo "Watching for changes to program source files ..."
+	@while true; do \
+	    if $(MAKE) 2>&1 | \
+		grep -vE 'make\[[1-9]\]: (Entering|Leaving) directory ' | \
+		grep -v 'Nothing to be done'; \
+	    then \
+		echo; \
+		echo "-----------------------------------------------------"; \
+		echo "make found things to rebuild; doing $(MAKE) install ..."; \
+		echo; \
+		$(MAKE) install; \
+		echo; \
+		echo ">>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>"; \
+		echo; \
+	    fi; \
+	    sleep 1; \
+	done 2>&1 | \
+	grep -vE 'make\[[1-9]\]: (Entering|Leaving) directory '
diff --git a/NEWS b/NEWS
@@ -1,5 +1,66 @@
 News file for Stow.
 
+* Changes in version 2.3.2
+
+*** Eliminated a spurious warning on unstowing
+
+    2.3.1 introduced a benign but annoying warning when unstowing
+    in certain circumstances.  It looked like:
+
+      BUG in find_stowed_path? Absolute/relative mismatch between Stow dir X and path Y
+
+    This was caused by erroneous logic, and has now been fixed.
+
+*** Improved debug output
+
+    Extra output resulting from use of the -v / --verbose flag
+    now appears in a more logical and understandable way.
+
+*** Janitorial tasks
+
+    Users are not substantially affected by these changes.
+
+***** Added some more information from the web page to the README
+
+***** Made some improvements to the documentation
+
+***** Improve readability of source code
+
+      Quite a few extra details have been added in comments to clarify
+      how the code works.  Many variable names have also been
+      improved.  The comments of many Stow class methods have been
+      converted into Perl POD format.
+
+***** Added a =CONTRIBUTING.md= file
+
+***** Add a =watch= target to =Makefile=
+
+      =make watch= provides easy continual pre-processing during
+      development, which reduces the risk of debugging the wrong code.
+
+***** Removed texinfo.tex from the distribution
+
+      This eliminates existing and future bit-rot.
+
+***** Updated aclocal.m4 from 1.15.1 to 1.16.5
+
+      This mostly just updates copyright notices to 2021, and URLs to https.
+
+***** Replace broken gmane links with links to lists.gnu.org
+
+      [[https://lars.ingebrigtsen.no/2020/01/06/whatever-happened-to-news-gmane-org/][gmane has been dead for quite a while.]]
+
+***** Improve support for navigating / editing source via emacs
+
+******* Support source navigation in emacs via [[https://github.com/jacktasia/dumb-jump][dumb-jump]].
+
+******* Configure cperl-mode to match existing coding style.
+
+*** Various maintainer tweaks
+
+    Further improved the release process and its documentation in
+    various minor ways.
+
 * Changes in version 2.3.1
 
 *** Remove dependencies on Hash::Merge and Clone::Choose
@@ -138,6 +199,7 @@ News file for Stow.
         consistency.
 
       - INSTALL.md now also documents how to build directly from git.
+
 *** Fixes for bugs, tests, and other technical debt
 
 ***** Add Docker files for convenient testing across multiple Perl versions
@@ -235,7 +297,7 @@ due to Stow::Util missing $VERSION.
     stow directory path being calculated as
     ../../../usr/home/user/local/stow relative to the target.
 
-    See http://article.gmane.org/gmane.comp.gnu.stow.bugs/8820 for details.
+    See https://lists.gnu.org/archive/html/bug-stow/2013-04/msg00000.html for details.
 
 *** Fix stowing of relative links when --no-folding is used.
 
@@ -276,7 +338,7 @@ due to Stow::Util missing $VERSION.
 
     Thanks to Gabriele Balducci for reporting this problem:
 
-        http://thread.gmane.org/gmane.comp.gnu.stow.general/6676
+        https://lists.gnu.org/archive/html/help-stow/2014-09/msg00000.html
 
 *** Internal code cleanups
 
@@ -586,4 +648,5 @@ due to Stow::Util missing $VERSION.
   org-export-with-toc: nil
   org-export-with-author: nil
   org-toc-odd-levels-only: t
+  org-blank-before-new-entry: ((heading . auto) (plain-list-item . auto))
   End: