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 B<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 B<.TH> line. If you have a
23 properly formatted B<.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 B<3perl>, which are placed in F<man3>, and given an
26 extension of F<.3perl>). If your B<.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 F<.ll.8> and F<.ll_LL.8>, or by use of the B<--language> switch.
32 If B<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 B<.TH> line. Edit the man page and correct the section, and
35 B<dh_installman> will follow suit. See L<man(7)> for details about the B<.TH>
36 section. If B<dh_installman> seems to install a man page into a directory
37 like F</usr/share/man/pl/man1/>, that is because your program has a
38 name like F<foo.pl>, and B<dh_installman> assumes that means it is translated
39 into Polish. Use B<--language=C> to avoid this.
41 After the man page installation step, B<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 F<.so> links. If so, it changes them to symlinks.
45 Also, B<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=>I<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 B<-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 if (defined `man --version`) {
201 foreach my $dir (qw{usr/share/man}) {
202 next unless -e "$tmp/$dir";
204 return if ! -f $_ || -l $_;
205 my ($tmp, $orig)=($_.".new", $_);
206 complex_doit "man --recode UTF-8 ./\Q$orig\E > \Q$tmp\E";
207 # recode uncompresses compressed pages
208 doit "rm", "-f", $orig if s/\.(gz|Z)$//;
209 doit "chmod", 644, $tmp;
210 doit "mv", "-f", $tmp, $_;
216 # Check if a file is a .so man page, for use by File::Find.
218 # The -s test is becuase a .so file tends to be small. We don't want
219 # to open every man page. 1024 is arbitrary.
220 if (! -f $_ || -s $_ > 1024 || -s == 0) {
224 # Test first line of file for the .so thing.
226 open (SOTEST, "zcat $_|") or die "$_: $!";
229 open (SOTEST,$_) || die "$_: $!";
235 error("failed to read $_");
238 if ($l=~m/\.so\s+(.*)\s*/) {
240 # This test is here to prevent links like ... man8/../man8/foo.8
241 if (basename($File::Find::dir) eq
243 $solink=basename($solink);
245 # A so link with a path is relative to the base of the man
246 # page hierarchy, but without a path, is relative to the
248 elsif ($solink =~ m!/!) {
249 $solink="../$solink";
252 if (-e $solink || -e "$solink.gz") {
253 push @sofiles,"$File::Find::dir/$_";
254 push @sodests,$solink;
263 This program is a part of debhelper.
267 Joey Hess <joeyh@debian.org>