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 $source variable to avoid this.
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.
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.
$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.
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.
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.
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.
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.
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.
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.
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.