man page of dh_installman incomplete for newbie

Bug #184156 reported by Francesco Fumanti
This bug affects 5 people
Affects Status Importance Assigned to Milestone
debhelper (Ubuntu)
Fix Released

Bug Description

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.

Revision history for this message
Jonathan Michalon (johndescs) wrote :

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

Revision history for this message
David Reynolds (david-reynoldsfamily) wrote :

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?

Revision history for this message
Colin Watson (cjwatson) wrote :

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:

       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/ (where "package" of course, is replaced
       with the package that is being acted on).

       For example, dh_installdocs uses files named debian/ 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/ 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/ 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.

Changed in debhelper:
status: New → Invalid
Revision history for this message
ronny (ronny-standtke) wrote :

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.

Changed in debhelper:
status: Invalid → Confirmed
Revision history for this message
Chris Conway (cconway) wrote :

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

Revision history for this message
unchiujar (vasile-jureschi) wrote :

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

Revision history for this message
Tim Landscheidt (scfc) wrote :

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

Revision history for this message
Launchpad Janitor (janitor) wrote :
Download full text (5.3 KiB)

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 ]
  * 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)
  * 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 ]
  * 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...


Changed in debhelper (Ubuntu):
status: Confirmed → Fix Released
To post a comment you must log in.
This report contains Public information  
Everyone can see this information.

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.