313 lines
9.0 KiB
HTML
313 lines
9.0 KiB
HTML
|
||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
<HTML><HEAD><TITLE>Man page of DH_INSTALLDOCS</TITLE>
|
||
</HEAD><BODY>
|
||
<H1>DH_INSTALLDOCS</H1>
|
||
Section: Debhelper (1)<BR>Updated: 2020-03-27<BR><A HREF="#index">Index</A>
|
||
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<A NAME="lbAB"> </A>
|
||
<H2>NAME</H2>
|
||
|
||
dh_installdocs - install documentation into package build directories
|
||
<A NAME="lbAC"> </A>
|
||
<H2>SYNOPSIS</H2>
|
||
|
||
|
||
|
||
<B>dh_installdocs</B> [<I>debhelper options</I>] [<B>-A</B>] [<B>-X</B><I>item</I>] [<I>file</I> ...]
|
||
<A NAME="lbAD"> </A>
|
||
<H2>DESCRIPTION</H2>
|
||
|
||
|
||
|
||
<B>dh_installdocs</B> is a debhelper program that is responsible for installing
|
||
documentation into <I>usr/share/doc/package</I> in package build directories.
|
||
<P>
|
||
|
||
In compat 10 and earlier, <B><A HREF="/cgi-bin/man/man2html?1+dh_install">dh_install</A></B>(1) may be a better tool for handling
|
||
the upstream documentation, when upstream's own build system installs all the desired documentation
|
||
correctly. In this case, <B>dh_installdocs</B> is still useful for installing
|
||
packaging related documentation (e.g. the <I>debian/copyright</I> file).
|
||
<P>
|
||
|
||
From debhelper compatibility level 11 on, <B>dh_install</B> will fall back to
|
||
looking in <I>debian/tmp</I> for files, if it does not find them in the current
|
||
directory (or wherever you've told it to look using <B>--sourcedir</B>).
|
||
<P>
|
||
|
||
In compat 11 and later, <B>dh_installdocs</B> offers many of the features that
|
||
<B><A HREF="/cgi-bin/man/man2html?1+dh_install">dh_install</A></B>(1) also has. Furthermore, <B>dh_installdocs</B> also supports
|
||
the <B>nodoc</B> build profile to exclude documentation (regardless of compat
|
||
level).
|
||
<A NAME="lbAE"> </A>
|
||
<H2>FILES</H2>
|
||
|
||
|
||
|
||
<DL COMPACT>
|
||
<DT id="1">debian/<I>package</I>.docs<DD>
|
||
|
||
|
||
List documentation files to be installed into <I>package</I>.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
Supports substitution variables in compat 13 and later as
|
||
documented in <B><A HREF="/cgi-bin/man/man2html?7+debhelper">debhelper</A></B>(7).
|
||
<DT id="2"><I>debian/copyright</I><DD>
|
||
|
||
|
||
The copyright file is installed into all packages, unless a more
|
||
specific copyright file is available.
|
||
<DT id="3">debian/<I>package</I>.copyright<DD>
|
||
|
||
|
||
|
||
<DT id="4">debian/<I>package</I>.README.Debian<DD>
|
||
|
||
|
||
<DT id="5">debian/<I>package</I>.TODO<DD>
|
||
|
||
|
||
|
||
Each of these files is automatically installed if present for a
|
||
<I>package</I>.
|
||
<DT id="6"><I>debian/README.Debian</I><DD>
|
||
|
||
|
||
|
||
<DT id="7"><I>debian/TODO</I><DD>
|
||
|
||
|
||
|
||
These files are installed into the first binary package listed in
|
||
debian/control.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
Note that <I></I><FONT SIZE="-1"><I>README</I></FONT><I>.debian</I> files are also installed as <I></I><FONT SIZE="-1"><I>README</I></FONT><I>.Debian</I>,
|
||
and <I></I><FONT SIZE="-1"><I>TODO</I></FONT><I></I> files will be installed as <I></I><FONT SIZE="-1"><I>TODO</I></FONT><I>.Debian</I> in non-native packages.
|
||
<DT id="8">debian/<I>package</I>.doc-base<DD>
|
||
|
||
|
||
Installed as doc-base control files. Note that the doc-id will be
|
||
determined from the <B>Document:</B> entry in the doc-base control file in
|
||
question. In the event that multiple doc-base files in a single source
|
||
package share the same doc-id, they will be installed to
|
||
usr/share/doc-base/package instead of usr/share/doc-base/doc-id.
|
||
<DT id="9">debian/<I>package</I>.doc-base.*<DD>
|
||
|
||
|
||
If your package needs to register more than one document, you need
|
||
multiple doc-base files, and can name them like this. In the event
|
||
that multiple doc-base files of this style in a single source package
|
||
share the same doc-id, they will be installed to
|
||
usr/share/doc-base/package-* instead of usr/share/doc-base/doc-id.
|
||
</DL>
|
||
<A NAME="lbAF"> </A>
|
||
<H2>OPTIONS</H2>
|
||
|
||
|
||
|
||
<DL COMPACT>
|
||
<DT id="10"><B>-A</B>, <B>--all</B><DD>
|
||
|
||
|
||
Install all files specified by command line parameters in <FONT SIZE="-1">ALL</FONT> packages
|
||
acted on.
|
||
<DT id="11"><B>-X</B><I>item</I>, <B>--exclude=</B><I>item</I><DD>
|
||
|
||
|
||
Exclude files that contain <I>item</I> anywhere in their filename from
|
||
being installed. Note that this includes doc-base files.
|
||
<DT id="12"><B>--sourcedir=</B><I>dir</I><DD>
|
||
|
||
|
||
Look in the specified directory for files to be installed. This option
|
||
requires compat 11 or later (it is silently ignored in compat 10 or earlier).
|
||
|
||
|
||
<P>
|
||
|
||
|
||
Note that this is not the same as the <B>--sourcedirectory</B> option used
|
||
by the <B>dh_auto_</B><I>*</I> commands. You rarely need to use this option, since
|
||
<B>dh_installman</B> automatically looks for files in <I>debian/tmp</I> in debhelper
|
||
compatibility level 11 and above.
|
||
<DT id="13"><B>--doc-main-package=</B><I>main-package</I><DD>
|
||
|
||
|
||
Set the main package for a documentation package. This is used to
|
||
install the documentation of the documentation package in <I>/usr/share/doc/main-package</I> as recommended by the Debian policy
|
||
manual 3.9.7 in §12.3.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
In compat 11 (or later), this option is only useful if debhelper's
|
||
auto-detection of the main package is wrong. The option can also be
|
||
used to silence a warning from debhelper when the auto-detection fails
|
||
but the default happens to be correct.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
This option cannot be used when <B>dh_installdocs</B> is instructed to act
|
||
on multiple packages. If you need this option, you will generally
|
||
need to combine it with <B>-p</B> to ensure exactly one package is acted
|
||
on.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
Please keep in mind that some documentation (the copyright file,
|
||
<FONT SIZE="-1">README</FONT>.Debian, etc.) will be unaffected by this option.
|
||
<DT id="14"><B>--link-doc=</B><I>package</I><DD>
|
||
|
||
|
||
Make the documentation directory of all packages acted on be a symlink to
|
||
the documentation directory of <I>package</I>. This has no effect when acting on
|
||
<I>package</I> itself, or if the documentation directory to be created already
|
||
exists when <B>dh_installdocs</B> is run. To comply with policy, <I>package</I> must
|
||
be a binary package that comes from the same source package.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
debhelper will try to avoid installing files into linked documentation
|
||
directories that would cause conflicts with the linked package. The <B>-A</B>
|
||
option will have no effect on packages with linked documentation
|
||
directories, and <I>copyright</I>, <I>changelog</I>, <I></I><FONT SIZE="-1"><I>README</I></FONT><I>.Debian</I>, and <I></I><FONT SIZE="-1"><I>TODO</I></FONT><I></I> files will
|
||
not be installed.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
(An older method to accomplish the same thing, which is still supported,
|
||
is to make the documentation directory of a package be a dangling symlink,
|
||
before calling <B>dh_installdocs</B>.)
|
||
|
||
|
||
<P>
|
||
|
||
|
||
Please note that this option only applies to the documentation
|
||
directory for the package itself. When the package ships
|
||
documentation for another package (e.g. see <B>--doc-main-package</B>), it
|
||
will not use a symlink for the documentation of the other package.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
<B></B><FONT SIZE="-1"><B>CAVEAT 1</B></FONT><B></B>: If a previous version of the package was built without this
|
||
option and is now built with it (or vice-versa), it requires a ``dir to
|
||
symlink'' (or ``symlink to dir'') migration. Since debhelper has no
|
||
knowledge of previous versions, you have to enable this migration
|
||
itself.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
This can be done by providing a "debian/<I>package</I>.maintscript" file
|
||
and using <B><A HREF="/cgi-bin/man/man2html?1+dh_installdeb">dh_installdeb</A></B>(1) to provide the relevant maintainer
|
||
script snippets.
|
||
|
||
|
||
<P>
|
||
|
||
|
||
<B></B><FONT SIZE="-1"><B>CAVEAT 2</B></FONT><B></B>: The use of <B>--link-doc</B> should only be done when the
|
||
packages have same ``architecture'' type. A link from an architecture
|
||
independent package to an architecture dependent package (or vice
|
||
versa) will not work. Since compat 10, debhelper will actively reject
|
||
unsupported combinations.
|
||
<DT id="15"><I>file</I> ...<DD>
|
||
|
||
|
||
Install these files as documentation into the first package acted on. (Or
|
||
in all packages if <B>-A</B> is specified).
|
||
</DL>
|
||
<A NAME="lbAG"> </A>
|
||
<H2>EXAMPLES</H2>
|
||
|
||
|
||
|
||
This is an example of a <I>debian/package.docs</I> file:
|
||
<P>
|
||
|
||
|
||
|
||
<PRE>
|
||
README
|
||
TODO
|
||
debian/notes-for-maintainers.txt
|
||
docs/manual.txt
|
||
docs/manual.pdf
|
||
docs/manual-html/
|
||
|
||
</PRE>
|
||
|
||
|
||
<A NAME="lbAH"> </A>
|
||
<H2>NOTES</H2>
|
||
|
||
|
||
|
||
Note that <B>dh_installdocs</B> will happily copy entire directory hierarchies if
|
||
you ask it to (similar to <B>cp -a</B>). If it is asked to install a
|
||
directory, it will install the complete contents of the directory.
|
||
<A NAME="lbAI"> </A>
|
||
<H2>SEE ALSO</H2>
|
||
|
||
|
||
|
||
<B><A HREF="/cgi-bin/man/man2html?7+debhelper">debhelper</A></B>(7)
|
||
<P>
|
||
|
||
This program is a part of debhelper.
|
||
<A NAME="lbAJ"> </A>
|
||
<H2>AUTHOR</H2>
|
||
|
||
|
||
|
||
Joey Hess <<A HREF="mailto:joeyh@debian.org">joeyh@debian.org</A>>
|
||
<P>
|
||
|
||
<HR>
|
||
<A NAME="index"> </A><H2>Index</H2>
|
||
<DL>
|
||
<DT id="16"><A HREF="#lbAB">NAME</A><DD>
|
||
<DT id="17"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
||
<DT id="18"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
||
<DT id="19"><A HREF="#lbAE">FILES</A><DD>
|
||
<DT id="20"><A HREF="#lbAF">OPTIONS</A><DD>
|
||
<DT id="21"><A HREF="#lbAG">EXAMPLES</A><DD>
|
||
<DT id="22"><A HREF="#lbAH">NOTES</A><DD>
|
||
<DT id="23"><A HREF="#lbAI">SEE ALSO</A><DD>
|
||
<DT id="24"><A HREF="#lbAJ">AUTHOR</A><DD>
|
||
</DL>
|
||
<HR>
|
||
This document was created by
|
||
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
||
using the manual pages.<BR>
|
||
Time: 00:05:10 GMT, March 31, 2021
|
||
</BODY>
|
||
</HTML>
|