Package: debhelper
Version: 5.0.35
Severity: wishlist
Currently the default templates include manpage.1.ex which is in nroff(1)
format. It would be good if there were also choice to use Perl native *.pod
format manual pages.
I'm attaching the concept below that I'm using. Attached files:
1. Separate make rule (as subroutine)
3. Template for the pod file.
HOW TO USE:
The debian/rules needs following lines:
PKG = package
MK_MAN = debian/manpod.mk
...
# NOTE: This target is not part of the build process. Run this
# separately when the documentation changes.
manpod:
$(MAKE) PACKAGE=$(PKG) MANSECT=1 \
MANPOD='debian/$(PKG).1.pod' \
-f $(MK_MAN) debian/$(PKG).1
To make use of the above:
$ mv manualpage.1.pod package.1.pod
.. edit the *.pod
.. create manual
$ make -f debian/rules manpod
The 'manpod' target could be incorporated in the 'build' rule as well.
Different manual pages can be genrated in case package "splits" it's
files to seprate debian/control::package sections by duplicating as
many lines as needed in 'manpod' target:
$(MAKE) PACKAGE=$(PKG)-client MANSECT=1 \
MANPOD='debian/$(PKG)-client.1.pod' \
-f $(MK_MAN) debian/$(PKG)-client.1
$(MAKE) PACKAGE=$(PKG)-server MANSECT=1 \
MANPOD='debian/$(PKG)-server.1.pod' \
-f $(MK_MAN) debian/$(PKG)-server.1
...
Jari
-- System Information:
Debian Release: testing/unstable
APT prefers unstable
APT policy: (500, 'unstable'), (500, 'stable')
Architecture: i386 (i686)
Shell: /bin/sh linked to /bin/dash
Kernel: Linux 2.6.16-2-686
Locale: LANG=C, LC_CTYPE=C (charmap=ISO-8859-1) (ignored: LC_ALL set to en_US)
Versions of packages debhelper depends on:
ii binutils 2.16.1cvs20060413-1 The GNU assembler, linker and bina
ii coreutils [fileutils 5.96-3 The GNU core utilities
ii dpkg-dev 1.13.21 package building tools for Debian
ii file 4.17-1 Determines file type using "magic"
ii html2text 1.3.2a-3 An advanced HTML to text converter
ii perl 5.8.8-6 Larry Wall's Practical Extraction
ii po-debconf 1.0.2 manage translated Debconf template
debhelper recommends no packages.
-- no debconf information
# This is manual page in Perl POD format. Read more at
# http://perldoc.perl.org/perlpod.html or run command:
#
# perldoc perlpod | less
#
# To check the syntax:
#
# podchecker *.pod
#
# Create manual page with command:
#
# pod2man PAGE.N.pod > PAGE.N
=pod
=head1 NAME
program - Description
=head1 SYNOPSIS
program [options]
=head1 OPTIONS
=over 4
=item B<-h>
Print available options.
=item B<-v>
Print the version number.
=back
=head1 DESCRIPTION
=head1 ENVIRONMENT
None.
=head1 FILES
None.
=head1 SEE ALSO
C<wmtime(1)>
=head1 AUTHORS
This manual page was written by Foo Bar <[EMAIL PROTECTED]>, for the
Debian GNU system (but may be used by others). Released under GPL v2
or any later version.
=cut
# Change target => install: build $(MANPAGE)
PACKAGE = package
PODCENTER = Debian
MANSECT = 1
MANPOD = debian/$(PACKAGE).$(MANSECT).pod
MANPAGE = debian/$(PACKAGE).$(MANSECT)
$(MANPAGE): $(MANPOD)
pod2man --center="$(PODCENTER)" \
--name="$(PACKAGE)" \
--section=$(MANSECT) \
$(MANPOD) \
| sed 's,[Pp]erl v[0-9.]\+,$(PACKAGE),' \
> $(MANPAGE)
# End of of Makefile part
