Notes about indexing in dhelp
=============================


How the indexer is run
======================

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.

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>