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

[Niels Thykier]

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
> 
> [...]

Hi Josch,

Thanks for the patch and very happy to accept that. :)

One question though, are you sure about the path not being allowed to
have a leading slash?  AFAICT, the code at least handles the link target
perfectly fine if it has a leading slash.  And I am inclined to say that
it is a bug if it does not support leading slashes in the link name either.

Thanks,
~Niels