X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=dh_installdocs.1;h=aa72b46b23f79ba4bd58ea31bf68158433940f9a;hb=a4b2194440fac0e24db7b0a5c5fa7aacf06e8645;hp=f21563ca5a864b462697b860ef5b13c343b9ade5;hpb=ecff4e2941eefd33c368be7a0ee372406a6d0e94;p=debhelper.git diff --git a/dh_installdocs.1 b/dh_installdocs.1 index f21563c..aa72b46 100644 --- a/dh_installdocs.1 +++ b/dh_installdocs.1 @@ -1,59 +1,88 @@ -.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 compatibility 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 +Joey Hess