Problem was that when running stow_contents/unstow_contents recursively from
stow_node/unstow_node the information for the source path (without the dot- to
. transformation) was lost.

In the case of stow_contents the solution is just to remove the leading
dots (..) from the $source path (since the $source path is passed as an argument
to the function)

In the case of unstow_contents the solution is the same as for stow_contents but
the arguments was now passed so I added it to the function.

This variables is used to keep track of the current level in the source.

This only updates copyright notices to 2020, and URLs to https.

gmane has been dead for quite a while:

    https://lars.ingebrigtsen.no/2020/01/06/whatever-happened-to-news-gmane-org/

We no longer need to ensure that texi2any (a.k.a. makeinfo) is called
with -I $(srcdir) in order to make the

    @verbatiminclude default-ignore-list

in the manual work, because texi2any includes the current working
directory by default anyway.  Presumably this behaviour was introduced
after this AM_MAKEINFOFLAGS was previously added, because it was
needed at some point in the past.

We actually override check-TESTS.

Allow easy navigation to function definitions in emacs.

The rg (ripgrep) search is needed because as the dumb-jump README says:

   [...] the default searcher (git-grep) won't be able to search
   outside of the project root. This edge case will be fixed in a
   future release.

See: https://github.com/jacktasia/dumb-jump

And add some debug.

Bring this more up to date by mentioning the dotfiles use case.

$path is a vague variable name.

At first sight this parameter looks redundant since we have
$self->{stow_path}, but in one case the value can differ from that,
so mention that explicitly.

…refix

Unlike with the stow_{contents,node}{,_orig}() counterpart functions,
when unstowing, it's not necessary to pass the $stow_path parameter
because it can never differ from $self->{stow_path}.

The stow_*() functions need this for the corner case of unfolding a
tree which is stowed from a different stow directory to the one being
used for the current stowing operation (see the "Multiple Stow
Directories" section of the manual).

Explain a few things in preparation for a bugfix.

This removes duplication.

This completely messes up the current function documentation.

Previously join_paths() was incorrectly handling absolute paths, for
example join_paths('a/b', '/c/d') would return 'a/b/c/d' rather than
'/c/d'.  This was a problem when following a symlink in
find_stowed_path(), because if the symlink was not owned by Stow and
pointed to an absolute path, find_stowed_path() might accidentally
deem the link owned by Stow, if c/d was a valid path relative to the
current directory.

join_paths() is used in specific ways and has specific behaviour
required which is nuanced and not obvious at first sight.  So make
this explicit for future reference.

Placing a .stow file in a directory tells Stow that this directory
should be considered a Stow directory.  This is already
well-documented.

There was an undocumented and slightly broken feature where placing a
.nonstow file in a directory was treated in exactly the same way.  The
intention was for .nonstow to cause Stow to skip stowing into and
unstowing from that directory and any of its descendants.  However, it
also caused Stow to consider symlinks into any of those directories as
owned by Stow, even though that was clearly not the intention.  So
separate treatment of .stow and .nonstow markers, so that while both
provide protection against Stow stowing and unstowing, only .stow
affects the symlink ownership logic in find_stowed_path() and
marked_stow_dir().

Probably no one uses the undocumented .nonstow feature, so it may make
sense to remove this in future.

This makes the code and test output both more legible.

When unstowing a package, cleanup_invalid_links() is invoked to remove
any invalid links owned by Stow.  It was invoking link_owned_by_package()
to check whether each existing link is owned by Stow.  This in turn
called find_stowed_path() which since 40a0807 was not allowing for
the possibility that it could be passed a symlink *not* owned by Stow
with an absolute target and consequently emitting an erroneous warning.

So remove this erroneous warning, and refactor find_stowed_path()
to use two new helper functions for detecting stow directories:
link_dest_within_stow_dir() and find_containing_marked_stow_dir().
Also refactor the logic within each to be simpler and more accurate,
and add more test cases to the corresponding parts of the test suite.

Fixes #65.
Closes #103.

#65

Target can have two opposing meanings:

1. the target directory where symlinks are managed by Stow, and
2. the destinations of those symlinks

So try to move away from this by using the word "destination" for
symlinks.

Some methods had comments with a prefix which made the paragraph
inconveniently narrow, and made refilling it really awkward.  So
switch to a more natural comment style.

As previously noted, the old comment style was difficult to edit.
It's also not idiomatic Perl style, so reformat as pod.  This exposes
more of the inner workings of Stow as documentation, but that
shouldn't be a problem.

As part of this change, remove outdated and sometimes misleading
information about if/when each function throws an exception.

Source can be ambiguous, as mentioned in the manual.

The $target variable was ambiguous, as it could have referred to the
path to the target directory, or the path to a sub-directory in the
target, as well as its intended meaning of a subpath relative to the
target directory.  So rename it to try to find the balance between
clarity and verbosity.

…_node()

Refactor the compat mode code to reuse the existing unstow_contents()
and unstow_node().  This allows us to remove the parallel versions in
unstow_contents_orig() and unstow_node(), which contained a lot of
duplicated code and were a significant maintenance burden.

GNU and Stow are both originally from the USA, so it makes sense
to stay consistent with American English.

This is very similar to a previous commit which did the same rename in
stow_node().

The $target variable was ambiguous, as it could have referred to the
path to the target directory, or the path to a sub-directory in the
target, as well as its intended meaning of a subpath relative to the
target directory.  So rename it to try to find the balance between
clarity and verbosity.

These lines were accidentally removed by 8436768.

It's always a directory, so make this explicit.

$path is horribly vague, so rename to be more informative.

$path is horribly vague, so rename to be more informative.

$path is horribly vague, so rename to be more informative.

$path is horribly vague, so rename to be more informative.

$path is horribly vague, so rename to be more informative.

The $target variable was ambiguous, as it could have referred to the
path to the target directory, or the path to a sub-directory in the
target, as well as its intended meaning of a subpath relative to the
target directory.  So rename it to try to find the balance between
clarity and verbosity.

$path is horribly vague, so rename to $link to be more informative.

Also the use of "$target" to describe a link's destination is very
confusing in the context of Stow for reasons explained in the manual.
So rename to $link_dest.

$path is horribly vague, so rename it to be more informative.

Improve variable names, POD, and add helpful comments.

The use of the word "source" to describe a link's destination is
confusing in the context of Stow for reasons explained in the manual.

So rename the $second_source variable to avoid this.

These don't add much value, and the reference to $source was out of
date anyway.

The use of the word "source" is confusing in the context of Stow for
reasons explained in the manual.

The use of the word "source" to describe a link's destination is
confusing in the context of Stow for reasons explained in the manual.

So rename the $existing_source variable to $link_dest avoid this.