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
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();
