5 dh_installman - install man pages into package build directories
11 use Debian::Debhelper::Dh_Lib;
15 B<dh_installman> [S<I<debhelper options>>] [S<I<manpage ...>>]
19 dh_installman is a debhelper program that handles installing
20 man pages into the correct locations in package build directories. You tell
21 it what man pages go in your packages, and it figures out where to
22 install them based on the section field in their .TH line. If you have a
23 properly formatted .TH line, your man page will be installed into the right
24 directory, with the right name (this includes proper handling of pages
25 with a subsection, like "3perl", which are placed in man3, and given an
26 extension of ".3perl"). If your .TH line is incorrect or missing, the program
27 may guess wrong based on the file extension.
29 It also supports translated man pages, by looking for extensions
30 like .ll.8 and .ll_LL.8, or by use of the --language switch.
32 If dh_installman seems to install a man page into the wrong section or with
33 the wrong extension, this is because the man page has the wrong section
34 listed in its .TH line. Edit the man page and correct the section, and
35 dh_installman will follow suit. See L<man(7)> for details about the .TH
36 section. If dh_installman seems to install a man page into a directory
37 like /usr/share/man/pl/man1/, that is because your program has a
38 name like "foo.pl", and dh_installman assumes that means it is translated
39 into Polish. Use --language=C to avoid this.
41 After the man page installation step, dh_installman will check to see if
42 any of the man pages in the temporary directories of any of the packages it
43 is acting on contain ".so" links. If so, it changes them to symlinks.
45 Also, dh_installman will use man to guess the character encoding of each
46 manual page and convert it to UTF-8. If the guesswork fails for some
47 reason, you can override it using an encoding declaration. See
48 L<manconv(1)> for details.
54 =item debian/I<package>.manpages
56 Lists man pages to be installed.
66 Install all files specified by command line parameters in ALL packages
69 =item B<--language>=ll
71 Use this to specify that the man pages being acted on are written in the
76 Install these man pages into the first package acted on. (Or in all
77 packages if -A is specified).
83 An older version of this program, L<dh_installmanpages(1)>, is still used
84 by some packages, and so is still included in debhelper.
85 It is, however, deprecated, due to its counterintuitive and inconsistent
86 interface. Use this program instead.
91 "language=s" => \$dh{LANGUAGE},
97 foreach my $package (@{$dh{DOPACKAGES}}) {
98 next if is_udeb($package);
100 my $tmp=tmpdir($package);
101 my $file=pkgfile($package,"manpages");
104 @manpages=filearray($file, ".") if $file;
106 if (($package eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) {
107 push @manpages, @ARGV;
110 foreach my $page (@manpages) {
111 my $basename=basename($page);
113 # Support compressed pages.
115 if ($basename=~m/(.*)(\.gz)/) {
121 # See if there is a .TH entry in the man page. If so,
122 # we'll pull the section field from that.
124 open (IN, "zcat $page|") or die "$page: $!";
127 open (IN, $page) or die "$page: $!";
130 if (/^\.TH\s+\S+\s+"?(\d+[^"\s]*)"?/) {
135 # Failing that, we can try to get it from the filename.
137 ($section)=$basename=~m/.*\.([1-9]\S*)/;
140 # Now get the numeric component of the section.
141 my ($realsection)=$section=~m/^(\d)/ if defined $section;
142 if (! $realsection) {
143 error("Could not determine section for $page");
146 # Get the man page's name -- everything up to the last dot.
147 my ($instname)=$basename=~m/^(.*)\./;
149 my $destdir="$tmp/usr/share/man/man$realsection/";
151 if (! defined $dh{LANGUAGE} || ! exists $dh{LANGUAGE}) {
152 # Translated man pages are typically specified by adding the
153 # language code to the filename, so detect that and
154 # redirect to appropriate directory, stripping the code.
155 ($langcode)=$basename=~m/.*\.([a-z][a-z](?:_[A-Z][A-Z])?)\.(?:[1-9]|man)/;
157 elsif ($dh{LANGUAGE} ne 'C') {
158 $langcode=$dh{LANGUAGE};
161 if (defined $langcode && $langcode ne '') {
162 # Strip the language code from the instname.
163 $instname=~s/\.$langcode$//;
166 if (defined $langcode && $langcode ne '') {
167 $destdir="$tmp/usr/share/man/$langcode/man$realsection/";
169 $destdir=~tr:/:/:s; # just for looks
170 my $instpage="$destdir$instname.$section";
172 next if -l $instpage;
173 next if compat(5) && -e $instpage;
176 doit "install","-d",$destdir;
179 complex_doit "zcat \Q$page\E > \Q$instpage\E";
182 doit "install","-p","-m644",$page,$instpage;
186 # Now the .so conversion.
187 @sofiles=@sodests=();
188 foreach my $dir (qw{usr/share/man}) {
189 if (-e "$tmp/$dir") {
190 find(\&find_so_man, "$tmp/$dir");
193 foreach my $sofile (@sofiles) {
194 my $sodest=shift(@sodests);
195 doit "rm","-f",$sofile;
196 doit "ln","-sf",$sodest,$sofile;
199 # Now utf-8 conversion.
200 foreach my $dir (qw{usr/share/man}) {
201 if (-e "$tmp/$dir") {
203 return if ! -f $_ || -l $_;
204 my ($tmp, $orig)=($_.".new", $_);
205 complex_doit "man --recode UTF-8 ./\Q$orig\E > \Q$tmp\E";
206 # recode uncompresses compressed pages
207 doit "rm", "-f", $orig if s/\.(gz|Z)$//;
208 doit "chmod", 644, $tmp;
209 doit "mv", "-f", $tmp, $_;
215 # Check if a file is a .so man page, for use by File::Find.
217 # The -s test is becuase a .so file tends to be small. We don't want
218 # to open every man page. 1024 is arbitrary.
219 if (! -f $_ || -s $_ > 1024 || -s == 0) {
223 # Test first line of file for the .so thing.
225 open (SOTEST, "zcat $_|") or die "$_: $!";
228 open (SOTEST,$_) || die "$_: $!";
234 error("failed to read $_");
237 if ($l=~m/\.so\s+(.*)\s*/) {
239 # This test is here to prevent links like ... man8/../man8/foo.8
240 if (basename($File::Find::dir) eq
242 $solink=basename($solink);
245 $solink="../$solink";
248 push @sofiles,"$File::Find::dir/$_";
249 push @sodests,$solink;
257 This program is a part of debhelper.
261 Joey Hess <joeyh@debian.org>