Version 0.6.20 Original Sources (currently in unstable)

Package source: ftp.debian.org

Signed-off-by: Georgios M. Zarkadas <gz@member.fsf.org>

8 files changed, 180 insertions, 17 deletions

diff --git a/debian/NEWS b/debian/NEWS
index 5342488..4b6c583 100644
--- a/debian/NEWS
+++ b/debian/NEWS
@@ -1,3 +1,11 @@
+dhelp (0.6.20) unstable; urgency=low
+
+  Indexing of new documents is now performed after the end of installation
+  procedure, as a background process. Thus, there are no more delays during
+  installation for systems with large number of registered documents.
+
+ -- Georgios M. Zarkadas <gz@member.fsf.org>  Mon, 03 Oct 2011 02:45:30 +0300
+
 dhelp (0.5.25) unstable; urgency=low
 
   /etc/dhelp is obsolete now. It used to be contain browser configuration
diff --git a/debian/README.Debian b/debian/README.Debian
index 7c16908..f193b8a 100644
--- a/debian/README.Debian
+++ b/debian/README.Debian
@@ -1,20 +1,84 @@
 Notes about indexing in dhelp
 =============================
 
-Right before releasing Lenny, it was decided that dhelp was going to cause too
-much trouble when upgrading, because of the policy of index-when-installing-
-packages. For that reason, that policy was dropped, and now dhelp doesn't index
-documentation on installation. 
 
-You can't configure this behaviour, but you can force (re)indexing of the
-documentation associated to certain package(s) using the utility provided in
-the examples/ directory. You should use it like this:
+How the indexer is run
+======================
 
-    sudo ruby /usr/share/doc/dhelp/examples/index_package_doc.rb <package> ...
+The scheduling of the indexer process was completely redesigned in version
+0.6.20, in order to solve the problem that the policy of index-when-installing-
+packages creates (namely long delays in the overall installation of packages
+when the size of installed documentation grows).
+
+Now dhelp indexes even during installation, but in a deferred way.  That is,
+registration of new documents or even the pool-rebuild (issued by the commands
+
+    dhelp_parse -a <document-list>
+
+and
+
+    dhelp_parse -r
+
+respectively) does not start the indexer but instead writes the filenames of
+the documents to be indexed in a cache list.  This list is later reopened
+(by a Dpkg post-install trigger) and fed to the indexer through a background
+running process.
 
-You can also force reindexing of all the currently installed documentation by
-calling the weekly cron job directly:
+Note that the indexing during install is incremental by default, in order to
+finish the indexing quicker.  This does not hurt overall searching capabilities
+since the index will be fully rebuilt anyway by the weekly cron job.
+
+If for any reason the indexer does not run and you are left with a non-empty
+cache file (it is located in /var/lib/dhelp/pending.list) you can start the
+indexer manually, issuing the command:
+
+    sudo dhelp_parse -i
+
+To force reindexing of all the currently installed documentation you can
+either issue the sequence of commands:
+
+    sudo dhelp_parse -r
+    sudo dhelp_parse -i
+
+or call the weekly cron job directly:
 
     sudo /etc/cron.weekly/dhelp
 
+To force (incremental) reindexing of certain packages you can use the utility
+provided in the examples/ directory. You should use it like this:
+
+    sudo ruby /usr/share/doc/dhelp/examples/index_package_doc.rb <package> ...
+
+
+Error reporting
+===============
+
+Up to version 0.6.19 error messages generated during indexing by the format
+conversion tools where copied verbatim to the indexers error report.  That
+resulted in lengthy and hard to understand messages from the weekly cron job
+in the cases where a package had registered a document that could not be 
+converted.
+
+From version 0.6.20 and later, raw conversion error messages are hidden from
+the indexer's error report; instead the full filename of the offending file is
+printed, so that the source of the error can easily identified.  You can then
+manually try to convert the file in order to see the exact errors generated.
+ 
+
+Log files
+=========
+
+From version 0.6.20 and above, the Dpkg post-install trigger as well as the
+weekly cron job generate a log file with the output from the indexer process
+inside directory /var/lib/dhelp/tmp.
+
+The log filename contains the date that the process started as its first
+component.  If something does not work as expected, you can search for logs
+with non-zero file size and view their content.
+
+A monthly cron job deletes all but the five last logs, in order to keep under
+control the size they occupy.
+
+
 -- Esteban Manchado Velázquez <zoso@debian.org>
+-- Georgios M. Zarkadas <gz@member.fsf.org>
diff --git a/debian/changelog b/debian/changelog
index eebd0e1..fb9dde2 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,23 @@
+dhelp (0.6.20) unstable; urgency=low
+
+  [ Georgios M. Zarkadas ]
+  * New co-maintainer: Georgios M. Zarkadas <gz@member.fsf.org>. 
+  * Fix incomprehensible error messages in dhelp cron output; now the
+    document's filename is reported (Closes: #561883).
+  * Fix unsorted documents in the section index; they are now sorted
+    on title (Closes: #567889).
+  * Fix running the indexer on each individual package install; now the
+    indexing is deferred until the end of installation (Closes: #615900).
+  * Fix removing an unrelated directory from the postrm script; this
+    legacy code has now been removed (Closes: #642273).
+  * Added Greek translation (Closes: #641917).
+  * Bump Standards-Version to 3.9.1.
+
+  [ Esteban Manchado Velázquez ]
+  * Sponsor the upload :-)
+
+ -- Esteban Manchado Velázquez <zoso@debian.org>  Thu, 13 Oct 2011 00:08:15 +0200
+
 dhelp (0.6.19) unstable; urgency=low
 
   * Fix URI escaping (Closes: #583349). Thanks John Gruenenfelder.
diff --git a/debian/control b/debian/control
index 4afcc31..86e167b 100644
--- a/debian/control
+++ b/debian/control
@@ -2,12 +2,12 @@ Source: dhelp
 Section: doc
 Priority: optional
 Maintainer: Esteban Manchado Velázquez <zoso@debian.org>
-Uploaders: Stefan Hornburg (Racke) <racke@linuxia.de>
-Standards-Version: 3.8.4
+Uploaders: Stefan Hornburg (Racke) <racke@linuxia.de>, Georgios M. Zarkadas <gz@member.fsf.org>
+Standards-Version: 3.9.1
 Build-Depends: debhelper (>= 5), cdbs (>= 0.4.23-1.1), libgettext-ruby-util
 
 Package: dhelp
-Depends: perl-modules, libtemplate-perl, libhtml-parser-perl, liburi-perl, ruby1.8, libdb-ruby1.8, libcommandline-ruby1.8, libgettext-ruby1.8, doc-base, swish++, liblocale-gettext-perl, libdata-page-perl, pstotext, poppler-utils, ${misc:Depends}
+Depends: perl-modules, libtemplate-perl, libhtml-parser-perl, liburi-perl, ruby1.8, libdb-ruby1.8, libcommandline-ruby1.8, libgettext-ruby1.8, doc-base, swish++, liblocale-gettext-perl, libdata-page-perl, pstotext, poppler-utils, ucf (>= 0.8), ${misc:Depends}
 Recommends: iceweasel | firefox | www-browser
 Suggests: httpd, info2www, man2html, lynx | links | w3m | html2text, catdvi
 Architecture: all
diff --git a/debian/cron.monthly b/debian/cron.monthly
new file mode 100755
index 0000000..67f2e45
--- /dev/null
+++ b/debian/cron.monthly
@@ -0,0 +1,28 @@
+#!/bin/sh
+# Remove all but the newest five *.index-log.* files, to keep them
+# from accumulating inside /var/lib/dhelp/tmp.
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public
+# License along with this program; if not, write to the Free
+# Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+# MA  02111-1307  USA.
+
+if [ -d /var/lib/dhelp/tmp ]; then
+  (
+    cd /var/lib/dhelp/tmp || exit
+    ls *.index-log.* \
+    | sort --numeric-sort --field-separator='-' --key=1,4 --key=6,7 --key=9,10 \
+    | head --lines=-5 \
+    | xargs --no-run-if-empty --max-args=1 --max-lines=1 rm -f
+  )
+fi
diff --git a/debian/dirs b/debian/dirs
index 069020b..b9a40ef 100644
--- a/debian/dirs
+++ b/debian/dirs
@@ -1,4 +1,6 @@
 usr/share/dhelp
+usr/share/dhelp/scripts
 var/lib/dhelp
 var/lib/dhelp/tmp
 etc/apache2/conf.d
+etc/apt/apt.conf.d
diff --git a/debian/postinst b/debian/postinst
index 42dfd16..9a7f2c0 100755
--- a/debian/postinst
+++ b/debian/postinst
@@ -34,13 +34,43 @@ rm -f /var/lib/dhelp/swish++.index
 # that call dhelp don't barf (from scrollkeeper package)
 touch /var/lib/dhelp/configured
 
+DHELP_INDEXER=/usr/share/dhelp/index-deferred
+DHELP_APTHOOK=/etc/apt/apt.conf.d/35dhelp
+
+# create and register with ucf our dpkg post-invoke hook
+
+DHELP_POSTCMD="\"if test -x ${DHELP_INDEXER}; then ${DHELP_INDEXER}; fi\""
+DHELP_TMP_APTHOOK=`mktemp 2>/dev/null`
+if [ $? -ne 0 ]; then
+    >&2 echo "Error: unable to create temporary file"
+    exit 1
+fi
+if ! chmod 644 ${DHELP_TMP_APTHOOK}; then
+    >&2 echo "Error: unable to change mode of temporary file"
+    exit 2
+fi
+echo "Dpkg::Post-Invoke { ${DHELP_POSTCMD}; };" > ${DHELP_TMP_APTHOOK}
+
+ucf --debconf-ok --three-way ${DHELP_TMP_APTHOOK} ${DHELP_APTHOOK}
+rm -f ${DHELP_TMP_APTHOOK}
+ucfr dhelp ${DHELP_APTHOOK}
+
+# 'dhelp_parse -r', among other actions, produces the pending list.
 echo -n "Building HTML tree..."
 dhelp_parse -r
 echo " done."
 
+# Thus, if index file does not exist, it suffices to do incremental indexing.
 if [ ! -f /var/lib/dhelp/documents.index ]; then
     echo "Reindexing documentation in the background"
-    /etc/cron.weekly/dhelp 2>/dev/null >/dev/null &
+    if [ -x ${DHELP_INDEXER} ]; then
+        ${DHELP_INDEXER}
+    else
+        >&2 echo "Error: ${DHELP_INDEXER} does not exist or is not executable"
+        exit 3
+    fi
 fi
 
+unset DHELP_INDEXER DHELP_POSTCMD DHELP_APTHOOK DHELP_TMP_APTHOOK || true
+
 #DEBHELPER#
diff --git a/debian/postrm b/debian/postrm
index d0beb96..db7f05e 100755
--- a/debian/postrm
+++ b/debian/postrm
@@ -17,9 +17,20 @@
 # Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
 # MA  02111-1307  USA.
 
-if [ "$1" = purge ]; then
-    # remove files generated by postinst
-	rm -rf /etc/dhelp
+# remove and unregister with ucf our dpkg post-invoke hook
+
+DHELP_APTHOOK=/etc/apt/apt.conf.d/35dhelp
+
+for ext in '' '~' '%' .bak .ucf-new .ucf-old .ucf-dist; do
+    rm -f ${DHELP_APTHOOK}${ext}
+done
+if which ucf >/dev/null; then
+    ucf --purge ${DHELP_APTHOOK}
 fi
+if which ucfr >/dev/null; then
+    ucfr --purge dhelp ${DHELP_APTHOOK}
+fi
+
+unset DHELP_APTHOOK || true
 
 #DEBHELPER#