[debhelper-devel] [debhelper] 01/02: Improve some bits of documentation

[Niels Thykier]

This is an automated email from the git hooks/post-receive script.

nthykier pushed a commit to branch master
in repository debhelper.

commit 2d45b5a3b6723c0d4ee9ddebc7846f2d75dc945a
Author: Niels Thykier <niels at thykier.net>
Date:   Tue Oct 3 20:32:14 2017 +0000

    Improve some bits of documentation
    
    Signed-off-by: Niels Thykier <niels at thykier.net>
---
 debhelper.pod  | 23 +++++++++++------------
 dh_installdocs | 10 ++++++++--
 2 files changed, 19 insertions(+), 14 deletions(-)

diff --git a/debhelper.pod b/debhelper.pod
index e39bafd..e9ba245 100644
--- a/debhelper.pod
+++ b/debhelper.pod
@@ -710,14 +710,13 @@ returns a non-zero exit from analysing a given file.
 
 =item -
 
-The B<dh_installdocs> and B<dh_installexamples> tools will now
-attempt to guess the "main package" for a given documentation
-package (e.g. I<pkg-doc> will have I<pkg> as main package).
-
-When a main package is detected, I<most> documentation will be
-installed into F<< /usr/share/doc/I<main-pkg> >> as recommended
-by Debian policy §12.3 since 3.9.7.  Notably exceptions include
-the copyright file and the changelog file.
+The B<dh_installdocs> and B<dh_installexamples> tools will now attempt
+to guess the "main package" for a given documentation package
+(e.g. I<pkg-doc> will have I<pkg> as main package if the latter
+exists).  If a main package is found, I<most> of the documentation
+will be installed into F<< /usr/share/doc/I<main-pkg> >> by default as
+recommended by Debian policy §12.3 since version 3.9.7.  Notable
+exceptions include the copyright file and changelog files.
 
 The B<--doc-main-package> option can be used when the auto-detection
 is insufficient.
@@ -725,11 +724,11 @@ is insufficient.
 =item -
 
 The B<dh_strip> and B<dh_shlibdeps> tools no longer uses filename
-patterns to determine which files to process.  Instead, they read the
-ELF header to determine if a given file is an shared object or an
-ELF executable.
+patterns to determine which files to process.  Instead, they open the
+file and look for an ELF header to determine if a given file is an
+shared object or an ELF executable.
 
-This may cause the tools to process more files than previously.
+This change may cause the tools to process more files than previously.
 
 =back
 
diff --git a/dh_installdocs b/dh_installdocs
index 8ffa4bf..70fd2b0 100755
--- a/dh_installdocs
+++ b/dh_installdocs
@@ -114,8 +114,8 @@ on multiple packages.  If you need this option, you will generally
 need to combine it with B<-p> to ensure exactly one package is acted
 on.
 
-Please keep in mind that some documentation (notably, the copyright
-file and the package changelog) will be unaffected by this option.
+Please keep in mind that some documentation (the copyright file,
+README.Debian, etc.) will be unaffected by this option.
 
 =item B<--link-doc=>I<package>
 
@@ -135,6 +135,12 @@ not be installed.
 is to make the documentation directory of a package be a dangling symlink,
 before calling B<dh_installdocs>.)
 
+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>), it
+will not use a symlink for the documentation of the other package.
+
+
 B<CAVEAT 1>: 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

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debhelper/debhelper.git