For NEWS, README and TODO files, the current behavior varies depending on
whether the files reside in the upstream tarball or in the debian/ directory.

For the upstream files, dh_installdocs successfully catches everything it finds.

For the debian/ directory content, some files must explicitely have a .Debian
extension while other files get it appended automatically by dh_installdocs.
For instance, it currently is that debian/README won't be automatically found,
but debian/README.Debian will be. In contradiction, debian/NEWS is found and
automatically renamed to NEWS.Debian, while debian/NEWS.Debian will be missed.

It would be desirable for this behavior to become consistant.

What I propose is that the helper should catch any occurance of NEWS|README|TODO
inside the debian/ directory, adding the .Debian extension if found missing.

- -- System Information:
Debian Release: 4.0
  APT prefers stable
  APT policy: (500, 'stable')
Architecture: i386 (i586)

Kernel: Linux 2.6.21-lx (PREEMPT)
Locale: LANG=fi_FI.UTF-8, LC_CTYPE=fi_FI.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash

Versions of packages debhelper depends on:
ii  binutils                     2.17-3      The GNU assembler, linker and bina
ii  coreutils                    5.97-5.3    The GNU core utilities
ii  dpkg-dev                     1.13.25     package building tools for Debian
ii  file                         4.17-5etch1 Determines file type using "magic"
ii  html2text                    1.3.2a-3    An advanced HTML to text converter
ii  perl                         5.8.8-7     Larry Wall's Practical Extraction
ii  po-debconf                   1.0.8       manage translated Debconf template

debhelper recommends no packages.

- -- no debconf information
iD8DBQFGdpb/eXr56x4Muc0RAmhtAJ9uyaNiQPmJ703rTPCEF7KyXmyG9gCgqOA2
UNMnf1IhyxI7jbCMoTrlT/8=
=SwZV
-----END PGP SIGNATURE-----

Martin-Éric Racine wrote:

That's not accurate. dh_installdocs does not find any upsteam
documentation files, it simply installs all files that are listed.

dh_installdocs does not do anything with NEWS files. These are handled
by dh_installchanglogs in a manner completely symmetric with how
debian/changelogs is handled. It would make no more sense for
dh_installchangelogs to look for debian/NEWS.Debian than it would for it
to look for debian/changelog.Debian -- those are not the filenames that
Debian tools such as dch use when modifying or reading these files.

It might be possible to get dh_installdocs to look for debian/README and
debian/TODO.Debian, although I'm not sure what to do:

- if both a debian/README.Debian and a debian/REAMDE exist
- about packages that include a debian/README without intending it to
  be included in the binary package (since it's currently not)

Both cannot exist. Report an error if that happens.

Anything that is not meant for inclusion should go into e.g.
debian/INSTALL which remains consistent with any upstream INSTALL not
being included in a binary.

The overall idea is that all occurrences of debian/[NEWS|README|TODO]
be included in the binary and renamed [NEWS|README|TODO].Debian, which
would finally apply a consistent behavior for all of those CAPS
documentation files.

As a transitional measure, debhelpers could report a warning if any of
the above files are
already have the .Debian extension or if both exist.

Hello Joey,

I notice that we never reached a solution on this issue. What is the status?

Cheers!

Martin-Éric Racine wrote:

Fixing this completly safely probably means doing so at a new debhelper
compatability level.

Hello

lintian is now checking for this case (NEWS|TODO), see #946126.

Regards
Vince