[debhelper-devel] Bug#871795: debhelper: please document that debian/dirs is handled by dh_installdirs

[Johannes Schauer]

Hi,

Quoting Sven Joachim (2017-08-12 01:41:40)
> On 2017-08-12 01:23 +0900, Johannes Schauer wrote:
> > Currently, the man page of dh_installdirs only documents that it takes care
> > of debian/package.dirs. But it also takes care of debian/dirs.
> 
> This is documented in debhelper(7):
> 
> ,----
> |        Note for the first (or only) binary package listed in
> |        debian/control, debhelper will use debian/foo when there's no
> |        debian/package.foo file.
> `----
> 
> > Please add that information to the man page.
> 
> I don't think replicating the above information in every dh_* manpage
> would be very good, since using debian/foo instead of debian/package.foo
> is probably not really recommended (it breaks when you reorder the packages
> in debian/control).

Maybe. But when I was searching the documentation for debian/dirs, d/dirs or
just dirs, I could not've possibly found that paragraph from debhelper(7). The
only way to find it would've been to read all the docs.

So maybe it's a bad idea to document this in every dh_* manpage but if it is,
then please document things like debian/dirs in a way that makes it easier to
find this information.

I don't think whether it's recommended or not should make a difference in how
"findable" the information is. In my case I was looking at another person's
package and was wondering what the debian/dirs file does. If it's bad practice
to use it, then it should say so in the accompanying text. But it's not helpful
if "hiding" it like that makes it harder to understand another person's
packaging.

Personally, for example I learned to use debian/package.foo all the way even
when my source package only had one binary package. I admit that this was
mainly due to the fact that the dh_* man pages only documented the
debian/package.foo way but I don't think I would've done this any different if
the dh_* pages also documented debian/foo but in the same paragraph advised
against its usage together with the reason you cited.

Thanks!

cheers, josch
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: signature
URL: <http://lists.alioth.debian.org/pipermail/debhelper-devel/attachments/20170812/034144e6/attachment-0003.sig>