[debhelper-devel] [debhelper] 01/01: dh_link.1: Improve the documentation

[Niels Thykier]

This is an automated email from the git hooks/post-receive script.

nthykier pushed a commit to branch master
in repository debhelper.

commit d64ac7fb93d6c2f99aeb240b3082684723031c83
Author: Johannes Schauer <josch at debian.org>
Date:   Wed Apr 12 09:00:15 2017 +0000

    dh_link.1: Improve the documentation
    
    Signed-off-by: Niels Thykier <niels at thykier.net>
---
 debian/changelog |  5 +++++
 dh_link          | 29 ++++++++++++++++++++++-------
 2 files changed, 27 insertions(+), 7 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index 06d360d..56ab599 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -53,6 +53,11 @@ debhelper (10.3) UNRELEASED; urgency=medium
   * Dh_Lib.pm: Introduce a log_installed_files sub that can be used
     to inform dh_missing that a given file has been installed.
 
+  [ Johannes Schauer ]
+  * dh_link.1: Improve the documentation and use ln(1) as a reference
+    to make it simplier for people, who are used to the terms from ln.
+    (Closes: #860091)
+
  -- Helmut Grohne <helmut at subdivi.de>  Sat, 18 Feb 2017 17:49:08 +0000
 
 debhelper (10.2.5) unstable; urgency=medium
diff --git a/dh_link b/dh_link
index 208e875..815c81d 100755
--- a/dh_link
+++ b/dh_link
@@ -20,14 +20,16 @@ B<dh_link> [S<I<debhelper options>>] [B<-A>] [B<-X>I<item>] [S<I<source destinat
 B<dh_link> is a debhelper program that creates symlinks in package build
 directories.
 
-B<dh_link> accepts a list of pairs of source and destination files. The source
-files are the already existing files that will be symlinked from. The
-destination files are the symlinks that will be created. There B<must> be
-an equal number of source and destination files specified.
+B<dh_link> accepts a list of pairs of source and destination
+files. The source files are the already existing files that will be
+symlinked from (called B<target> by L<ln(1)>). The destination files
+are the symlinks that will be created (called B<link name> by
+L<ln(1)>). There B<must> be an equal number of source and destination
+files specified.
 
-Be sure you B<do> specify the full filename to both the source and
-destination files (unlike you would do if you were using something like
-L<ln(1)>).
+Be sure you B<do> specify the absolute path (without leading slash) to
+both the source and destination files (unlike you would do if you were
+using something like L<ln(1)>).
 
 B<dh_link> will generate symlinks that comply with Debian policy - absolute
 when policy says they should be absolute, and relative links with as short
@@ -49,6 +51,14 @@ Lists pairs of source and destination files to be symlinked. Each pair
 should be put on its own line, with the source and destination separated by
 whitespace.
 
+In each pair the source file (called B<target> by L<ln(1)>) comes
+first and is followed by the destination file (called B<link name> by
+L<ln(1)>). Thus the pairs of source and destination files in each line
+are give in the same order as they would be given to L<ln(1)>.
+
+In contrast to L<ln(1)>, source and destination paths must be absolute
+without a leading slash.
+
 =back
 
 =head1 OPTIONS
@@ -85,6 +95,11 @@ Make F<bar.1> be a symlink to F<foo.1>
 Make F</usr/lib/foo/> be a link to F</var/lib/foo/>, and F<bar.1> be a symlink to
 the F<foo.1>
 
+ var/lib/foo usr/lib/foo
+ usr/share/man/man1/foo.1 usr/share/man/man1/bar.1
+
+Same as above but as content for a debian/I<package>.links file.
+
 =cut
 
 init();

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debhelper/debhelper.git