-.TH DH_INSTALLDOCS 1
+.TH DH_INSTALLDOCS 1 "" "Debhelper Commands" "Debhelper Commands"
.SH NAME
dh_installdocs \- install documentation into package build directories
.SH SYNOPSIS
.B dh_installdocs
-.I "[-v] [-a] [-i] [-ppackage] [file ...]"
+.I "[debhelper options] [-A] [-n] [file ...]"
.SH "DESCRIPTION"
dh_installdocs is a debhelper program that is responsible for installing
-documentation into usr/doc/package in package build directories.
+documentation into usr/share/doc/package in package build directories.
.P
dh_installdocs automatically installs debian/copyright if it exists. If
-dh_installdocs is acting on multiple packages, debian/copyright files will be
-installed into all packages.
+dh_installdocs is acting on multiple packages, debian/copyright files will be
+installed into all packages. However, if you need to have seperate copyright
+files for different binary packages, you can use files named
+debian/package.copyright.
.P
-Any filenames specified as parameters, as well as debian/README.debian and
-debian/TODO, if they exist, will be installed into the first binary
-package listed in debian/control, if dh_installdocs is acting on that
-package.
+Any filenames specified as parameters will be installed into the first
+package dh_installdocs is told to act on. By default, this is the first
+binary package in debian/control, but if you use -p, -i, or -a flags, it
+will be the first package specified by those flags.
.P
-A file named debian/docs (for the first binary package in debian/control),
-or debian/package.docs (for each additional package in debian/control) can
-list other files to be installed.
+Also, debian/README.Debian (or debian/README.debian) and debian/TODO, if
+they exist, will be installed into the first binary package listed in
+debian/control, if dh_installdocs is acting on that package. Note that
+debian/TODO will be installed named TODO.Debian, if the package is not a
+debian native package. Also note that README.debian is installed as
+README.Debian, for consitency. Note that debian/package.README.Debian and
+debian/package.TODO can be used to specify files for subpackages.
+.P
+Files named debian/package.docs can list other files to be installed.
+.P
+This program will automatically generate postinst and prerm commands to
+maintain a compatability symlink, /usr/doc/package, to the documentation in
+/usr/share/doc/package. See
+.BR dh_installdeb (1)
+for an explanation of how this works.
+.P
+Files named debian/package.doc-base, will be installed as doc-base control
+files, and will make this program automatically generate the postinst and
+prerm commands needed to interface with the doc-base package. See
+.BR dh_installdeb (1)
+for an explanation of how this works.
+Note that the doc-id will be determined from the "Document:" entry in the
+doc-base control file in question.
+.PP
+If your package needs to register more
+than one document, you need multiple files. To accomplish this, you can use
+files named debian/package.doc-base.*
.SH OPTIONS
.TP
-.B \-v
-Verbose mode; show all commands that modify the package build directory.
-.TP
-.B \-a
-Install files for all architecture dependent packages.
+.B debhelper options
+See
+.BR debhelper (1)
+for a list of options common to all debhelper commands.
.TP
-.B \-i
-Install files for all architecture independent packages.
+.B \-A, \--all
+Install all files specified by command line parameters in ALL packages
+acted on.
.TP
-.B \-ppackage
-Install files for the package named "package".
+.B \-n, \--noscripts
+Do not modify postinst/prerm scripts.
.TP
.B file ...
-Install these files as documentation into the first binary package listed in
-debian/control, if we are acting on that package.
+Install these files as documentation into the first package acted on. (Or in
+all packages if -A is specified).
.SH NOTES
-The
-.B \-a
-.B \-i
-and
-.B \-p
-arguments are cumulative. If none are specified, then all packages listed in
-the control file will be effected.
+Note that dh_installdocs will happily copy entire directory hierarchies if
+you ask it to (it uses cp -a internally). If it is asked to install a
+directory, it will install the complete contents of the directory.
.SH ENVIRONMENT
-.TP
-.I DH_VERBOSE
-Enables verbose mode
+See
+.BR debhelper (1)
+for a list of environment variables that affect all debhelper commands.
.SH "SEE ALSO"
-.BR /usr/doc/debhelper/README
+.BR debhelper (1)
+.TP
+.BR install-docs (8)
+.SH NOTES
+Note that this command is not idempotent. "dh_clean -k" should be called
+between invocations of this command. Otherwise, it may cause multiple
+instances of the same text to be added to maintainer scripts.
.SH BUGS
-Filenames with spaces in them will not currently be installed.
+It's impossible to specify filenames with spaces or other whitespace in them
+in debian/package.docs file. This is more a historical design flaw than a bug.
.SH "CONFORMS TO"
-Debian policy, version 2.3.0.0
+Debian policy, version 3.0.1
.SH AUTHOR
-Joey Hess <joeyh@master.debian.org>
+Joey Hess <joeyh@debian.org>
projects / debhelper.git / blobdiff