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 install
22 them based on the section field in their B<.TH> or B<.Dt> line. If you have
23 a properly formatted B<.TH> or B<.Dt> line, your man page will be installed
24 into the right directory, with the right name (this includes proper handling
25 of pages with a subsection, like B<3perl>, which are placed in F<man3>, and
26 given an extension of F<.3perl>). If your B<.TH> or B<.Dt> line is incorrect
27 or missing, the program 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> or B<.Dt> line. Edit the man page and correct the
35 section, and B<dh_installman> will follow suit. See L<man(7)> for details
36 about the B<.TH> section, and L<mdoc(7)> for the B<.Dt> section. If
37 B<dh_installman> seems to install a man page into a directory
38 like F</usr/share/man/pl/man1/>, that is because your program has a
39 name like F<foo.pl>, and B<dh_installman> assumes that means it is translated
40 into Polish. Use B<--language=C> to avoid this.
42 After the man page installation step, B<dh_installman> will check to see if
43 any of the man pages in the temporary directories of any of the packages it
44 is acting on contain F<.so> links. If so, it changes them to symlinks.
46 Also, B<dh_installman> will use man to guess the character encoding of each
47 manual page and convert it to UTF-8. If the guesswork fails for some
48 reason, you can override it using an encoding declaration. See
49 L<manconv(1)> for details.
55 =item debian/I<package>.manpages
57 Lists man pages to be installed.
67 Install all files specified by command line parameters in ALL packages
70 =item B<--language=>I<ll>
72 Use this to specify that the man pages being acted on are written in the
77 Install these man pages into the first package acted on. (Or in all
78 packages if B<-A> is specified).
84 An older version of this program, L<dh_installmanpages(1)>, is still used
85 by some packages, and so is still included in debhelper.
86 It is, however, deprecated, due to its counterintuitive and inconsistent
87 interface. Use this program instead.
92 "language=s" => \$dh{LANGUAGE},
98 foreach my $package (@{$dh{DOPACKAGES}}) {
99 next if is_udeb($package);
101 my $tmp=tmpdir($package);
102 my $file=pkgfile($package,"manpages");
105 @manpages=filearray($file, ".") if $file;
107 if (($package eq $dh{FIRSTPACKAGE} || $dh{PARAMS_ALL}) && @ARGV) {
108 push @manpages, @ARGV;
111 foreach my $page (@manpages) {
112 my $basename=basename($page);
114 # Support compressed pages.
116 if ($basename=~m/(.*)(\.gz)/) {
122 # See if there is a .TH or .Dt entry in the man page. If so,
123 # we'll pull the section field from that.
125 open (IN, "zcat $page|") or die "$page: $!";
128 open (IN, $page) or die "$page: $!";
131 if (/^\.TH\s+\S+\s+"?(\d+[^"\s]*)"?/ ||
132 /^\.Dt\s+\S+\s+(\d+[^\s]*)/) {
137 # Failing that, we can try to get it from the filename.
139 ($section)=$basename=~m/.*\.([1-9]\S*)/;
142 # Now get the numeric component of the section.
143 my ($realsection)=$section=~m/^(\d)/ if defined $section;
144 if (! $realsection) {
145 error("Could not determine section for $page");
148 # Get the man page's name -- everything up to the last dot.
149 my ($instname)=$basename=~m/^(.*)\./;
151 my $destdir="$tmp/usr/share/man/man$realsection/";
153 if (! defined $dh{LANGUAGE} || ! exists $dh{LANGUAGE}) {
154 # Translated man pages are typically specified by adding the
155 # language code to the filename, so detect that and
156 # redirect to appropriate directory, stripping the code.
157 ($langcode)=$basename=~m/.*\.([a-z][a-z](?:_[A-Z][A-Z])?)\.(?:[1-9]|man)/;
159 elsif ($dh{LANGUAGE} ne 'C') {
160 $langcode=$dh{LANGUAGE};
163 if (defined $langcode && $langcode ne '') {
164 # Strip the language code from the instname.
165 $instname=~s/\.$langcode$//;
168 if (defined $langcode && $langcode ne '') {
169 $destdir="$tmp/usr/share/man/$langcode/man$realsection/";
171 $destdir=~tr:/:/:s; # just for looks
172 my $instpage="$destdir$instname.$section";
174 next if -l $instpage;
175 next if compat(5) && -e $instpage;
178 doit "install","-d",$destdir;
181 complex_doit "zcat \Q$page\E > \Q$instpage\E";
184 doit "install","-p","-m644",$page,$instpage;
188 # Now the .so conversion.
189 @sofiles=@sodests=();
190 foreach my $dir (qw{usr/share/man}) {
191 if (-e "$tmp/$dir") {
192 find(\&find_so_man, "$tmp/$dir");
195 foreach my $sofile (@sofiles) {
196 my $sodest=shift(@sodests);
197 doit "rm","-f",$sofile;
198 doit "ln","-sf",$sodest,$sofile;
201 # Now utf-8 conversion.
202 if (defined `man --version`) {
203 foreach my $dir (qw{usr/share/man}) {
204 next unless -e "$tmp/$dir";
206 return if ! -f $_ || -l $_;
207 my ($tmp, $orig)=($_.".new", $_);
208 complex_doit "man --recode UTF-8 ./\Q$orig\E > \Q$tmp\E";
209 # recode uncompresses compressed pages
210 doit "rm", "-f", $orig if s/\.(gz|Z)$//;
211 doit "chmod", 644, $tmp;
212 doit "mv", "-f", $tmp, $_;
218 # Check if a file is a .so man page, for use by File::Find.
220 # The -s test is becuase a .so file tends to be small. We don't want
221 # to open every man page. 1024 is arbitrary.
222 if (! -f $_ || -s $_ > 1024 || -s == 0) {
226 # Test first line of file for the .so thing.
228 open (SOTEST, "zcat $_|") or die "$_: $!";
231 open (SOTEST,$_) || die "$_: $!";
237 error("failed to read $_");
240 if ($l=~m/\.so\s+(.*)\s*/) {
242 # This test is here to prevent links like ... man8/../man8/foo.8
243 if (basename($File::Find::dir) eq
245 $solink=basename($solink);
247 # A so link with a path is relative to the base of the man
248 # page hierarchy, but without a path, is relative to the
250 elsif ($solink =~ m!/!) {
251 $solink="../$solink";
254 if (-e $solink || -e "$solink.gz") {
255 push @sofiles,"$File::Find::dir/$_";
256 push @sodests,$solink;
265 This program is a part of debhelper.
269 Joey Hess <joeyh@debian.org>