dh_make issue/suggestion

[Jason Pepas <j.pepas@mail.utexas.edu>]

Hello,

I have recently started learning how to create debian packages.

I have some thoughts on what I see as an issue, and some thoughts on resolving
it.  Keep in mind I have only been at this for a couple of days, so take this
with a grain of salt.

dh_make does a good job of providing reasonable defaults, with one exception
I have encountered.

Regarding manpage documentation, I see the following scenarios:

1.
the upstream source already has manpages.
they are either in nroff format and are installed via the upstream
Makefile's "install" target,
or they are in sgml, are built in the upstream Makefile "build" target,
and the resulting nroff is then installed via the upstread Makefile "install"
target.

2.
there are no upstream manpages.
manpages are created during debianization.
they reside in nroff format in /debian, and the rules "install" target calls
"dh_installman foo.1", etc to install them,
or they reside in sgml format in /debian, the rules "build" target calls
docbook-to-man, and then the rules "install" target installs the resulting
nroff.

it is the latter half of the second option where I see a possible improvement.

thoughtfully, the dh_make rules file includes a commented call to 
docbook-to-man in the rules "build" target.  

however, this results in debian/../foo.1, etc.

this temporary file does not get cleaned with a call to "debuild clean",
which I beleive is what should be responsible for cleaning it.

I propose adding the following commented line to the rules "clean" target to
supplement the commented call to docbook-to-man:

	# uncomment this if you uncommented the docbook-to-man call above.
	#rm -f foo.1

however, this leads to the problem of "what if debian/../foo.1 was supplied
by upstream?".  thus, we need to make it a little more intelligent:

	# uncomment this if you uncommented the docbook-to-man call above.
	#if test -e debian/foo.sgml; then rm -f foo.1; fi

thus, if the user renamed debian/manpage.sgml.ex to debian/foo.sgml, it is
safe to assume that either there is no upstream manpage, or that it is safe
to overwrite the upstream manpage.

this also leads to the idea that we should really wrap the call to 
docbook-to-man in the rules build target:

	#if test -e debian/foo.sgml; then /usr/bin/docbook-to-man debian/foo.sgml > 
foo.1; fi

finally, I propose an addition be made to the new maintainer's guide to point
out that you have to give dh_installman some arguments for it to do anything.
section 5.8 discusses all the required steps to supply a manpage when the
upstream source lacks one, but they don't mention you need to change the
call from "dh_installman" to "dh_installman foo.1"

again, I am new to all this, so constructive criticism is very welcome.

-jason pepas
jason@pepas.com