man page of dh_installman incomplete for newbie

[Francesco Fumanti]

Today I had to use dh_installman for the first time, so I looked at its man page. The man page explains what it does, but the information about how to use it is missing. The following information would have been useful in my case (Fortunately, somebody in irc gave it to me; googling was not very helpful) :

<Example of missing info>
You can use dh_installman in the following way:
- create a file called yourpackagename.manpages in the debian directory
- for each man page to install, add a line of the form "debian/manpagename" (without quotes) to the yourpackagename.manpages file
- put each man page to install by dh_installman into the debian directory
<end of example of missing info>

The actual manpage talkes about debian/package.manpages (= yourpackagename.manpages from my example), but it does not explain how to add the man pages to it, nor in what directory to store the man pages.

Finally, I wonder whether similar dh_* helpers lack the same information.

[Jonathan Michalon (johndescs)]

I just experienced the same problem... that's really not good enough documented.

[David Reynolds (david-reynoldsfamily)]

Same thing happened to me, I had to google and find this bug report to work out how to use this. Could the documentation be improved?

[Colin Watson (cjwatson)]

General information about how to use dh_* commands is in the debhelper(7) manual page, which is linked from SEE ALSO in dh_installman(1) (and others). For instance, it says:

DEBHELPER CONFIG FILES
       Many debhelper commands make use of files in debian/ to control
       what they do. Besides the common debian/changelog and
       debian/control, which are in all packages, not just those using
       debhelper, some additional files can be used to configure the
       behavior of specific debhelper commands. These files are typically
       named debian/package.foo (where "package" of course, is replaced
       with the package that is being acted on).

       For example, dh_installdocs uses files named debian/package.docs to
       list the documentation files it will install. See the man pages of
       individual commands for details about the names and formats of the
       files they use. Generally, these files will list files to act on,
       one file per line. Some programs in debhelper use pairs of files
       and destinations or slightly more complicated formats.

       Note that if a package is the first (or only) binary package listed
       in debian/control, debhelper will use debian/foo if no
       debian/package.foo file can be found.

       In some rare cases, you may want to have different versions of
       these files for different architectures. If files named
       debian/package.foo.arch exist, where "arch" is the same as the
       output of "dpkg-architecture -qDEB_HOST_ARCH", then they will be
       used in preference to other, more general files.

       In many cases, these config files are used to specify various types
       of files. Documentation or example files to install, files to move,
       and so on. When appropriate, in cases like these, you can use
       standard shell wildcard characters ('?' and '*' and '[..]'
       character classes) in the files.

       You can also put comments in these files; lines beginning with "#"
       are ignored.

There is no need for any explanation of where to store the manual pages in dh_installman(1), since there are no restrictions on this.

[ronny (ronny-standtke)]

I just run into exactly the same problem: the man page of dh_installman was not helpful enough for me to understand what I have to do exactly. There is no reason *not* to improve the documentation.

[Chris Conway (cconway)]

I'd like to add a "me too" on the lack of debhelper/CDBS documentation.

[unchiujar (vasile-jureschi)]

Me too, I had to use this bug report to get manpages installed.
* changed the content of manpage.1
* changed the name of manpage.1 myapp.1
* added the manpages filenames to dh_installman line in debian/rules after looking at the manpage for dh_installman
* found this bug report

[Tim Landscheidt (scfc)]

I was looking for information on how to specify man pages for multiple binary packages installed by "make install", and the man page for dh_installman (and this bug report) was not helpful. It took me trial and error (and a look at dh_installman's source) to find out that you need to specify:

| debian/tmp/usr/share/man/man1/jstart.1
| debian/tmp/usr/share/man/man1/jstop.1
| debian/tmp/usr/share/man/man1/jsub.1

This was (very) counterintuitive, as for example *.install lists files as:

| usr/bin/job
| usr/bin/jstart
| usr/bin/jstop
| usr/bin/jsub
| usr/bin/qcronsub

[Launchpad Janitor (janitor)]

This bug was fixed in the package debhelper - 10.4ubuntu1

---------------
debhelper (10.4ubuntu1) artful; urgency=medium

  * Merge from Debian unstable. Remaining changes:
    - dh_installchangelogs: Do not install upstream changelog in compat
      level 7. This floods packages with huge upstream changelogs which
      are unnecessary on an installed system.
    - Restore maintainer ability to override ddeb compression
    - Generate ddebs from debhelper instead of pkg-create-dbgsym
      + Make debhelper Conflict/Replace pkg-create-dbgsym to force it off.
      + Mirror udeb code in dh_builddeb to allow us to alter file extension.
      + Set dbgsym Package-Type to ddeb to get correct debian/files output.
      + Depend on dpkg-dev (>= 1.18.23ubuntu3) so the above works correctly.

debhelper (10.4) experimental; urgency=medium

  * Team upload.

  [ Niels Thykier ]
  * meson.pm: Pass --wrap-mode=nodownload to meson (requires meson
    0.40-1 or later).
  * dh_install: Fix initialized warning when --sourcedir is absent
    on the cmd-line.
  * dh_missing: Accept --sourcedir (given it is passed by dh_install).
    (Closes: #862049)
  * Dh_Lib.pm: Fix a bug in pkgfile that caused dh to skip helpers
    that had configuration files. Thanks to Michael Biebl for finding
    and reporting. (Closes: #863387)

  [ Chris Lamb ]
  * dh_fixperms: Fix regression where dh_fixperms would fail to correct
    permissions because it used an invalid find expression.
    (Closes: #862003)

debhelper (10.3) experimental; urgency=medium

  [ Helmut Grohne ]
  * Supply PKG_CONFIG for cross compilation with the makefile buildsystem.
    (Closes: #853881)
  * Disable stripping during dh_auto_* in makefile buildsystem in compat 11.
    (Closes: #844077)
  * Remove explicit "Multi-Arch: no" stanzas as they are auto-rejected.
    (Closes: #857028)

  [ Niels Thykier ]
  * Dh_Lib.pm: Make getpackages() produce the correct result independently
    of the order of the fields in a given paragraph of debian/control.
    (Closes: #847138)
  * dh_installman: Report installed manpages so the new dh_missing tool
    is informed about them.
  * dh_install: Deprecate --list-missing/--fail-missing in favor of the
    new dh_missing tool. The options will be removed in compat 11.
  * dh: Run dh_missing by default (in no op mode).
  * dh_prep: Clean up generated files so they work like other temporary
    debhelper files.
  * dh_installinit: Clarify that it might make sense to skip dh_installinit
    for a package if it provides a systemd service but no sysvinit file.
    (Closes: #800043)
  * dh_installinit: Deprecate --no-restart-on-upgrade in favor of the new
    name --no-stop-on-upgrade, which does the same thing but is less
    likely to be confused with --no-restart-after-upgrade and is more
    descriptive of what it actually does. Thanks to Simon McVittie and
    Michael Biebl for the help. (Closes: #837528)
  * debian/rules: Only apply the --no-parallel to dh_auto_test. The rest
    of debhelper's build appears to work fine with --parallel.
  * dh_systemd_enable.1: Clarify that --no-enable does not control
    whether a service is started and that dh_systemd_sta...