[debhelper-devel] Bug#860091: debhelper: Please be more verbose in the dh_link man page

[Johannes Schauer]

Package: debhelper
Version: 10.2.3
Severity: wishlist
Tags: patch

Hi,

I didn't find the dh_link man page very helpful when I trued to create a
debian/I<package>.links file. I noticed the following shortcomings:

 - the man page uses the source/destination nomenclature which I find
   quite confusing. I would've thought that the "destination" of a
   symlink is the path that the symlink points to and thus the symlink
   itself must be the source. Indeed it seems to be the other way round.
   It would probably help to at least mention the parallels to the
   nomenclature used in ln(1)

 - the man page talks about "full filename" but actually means a full
   "path". And instead of saying "full" it would probably be less
   ambiguous and more precise to use the word "absolute" instead.

 - Furthermore, the path must be given without the leading slash. This
   is shown in the examples but never mentioned in the text.

 - The documentation for the debian/I<package>.links files never
   mentions the order in which source and destination have to be listed.
   It would also help to reduce confusion to mention that the order is
   the same that would be used for the ln(1) command.

 - If one just searches for how to write a debian/I<package>.links file,
   one easily misses the note that paths must be given absolute and not
   relative to the symlink itself. That the paths inside
   debian/I<package>.links files must be given in an absolute manner is
   more an implicit assumption but instead should be made explicit for
   clarity.

Attached patch addresses all my above concerns and also adds an example
for debian/I<package>.links files in the EXAMPLES section.

I hope it helps!

Thanks!

cheers, josch
-------------- next part --------------
diff --git a/dh_link b/dh_link
index 208e8751..f5e87426 100755
--- a/dh_link
+++ b/dh_link
@@ -21,11 +21,11 @@ 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
+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
+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)>).
 
@@ -49,6 +49,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 +93,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();