Update README.Debian file with web server configuration instructions.

1 files changed, 151 insertions, 8 deletions

diff --git a/debian/README.Debian b/debian/README.Debian
index f193b8a..266c75d 100644
--- a/debian/README.Debian
+++ b/debian/README.Debian
@@ -1,9 +1,152 @@
-Notes about indexing in dhelp
-=============================
+1. Debian Online Help fetures
+==============================================
 
+Debian Online Help builds an index of all documentation in your system that
+is registered with doc-base (and updates it when new packages are installed).
+You can view this index with any web browser in two possible modes:
 
-How the indexer is run
-======================
+1. Offline, using the file:// protocol. Just use the command:
+
+    <your-browser> file:///usr/share/doc/HTML/index.html
+
+2. Online, by installing a web server of your choice and opening the URL:
+
+    http://localhost/doc/HTML/index.html
+
+You can start Debian Online Help using the command `dhelp'. It will detect
+if you are using a web server and start in online mode, else it will start
+in offline mode. 
+
+You can search for documentation relating to a particular query string using
+the command `dhelp <query-string>', or use the search form if you have a web
+server installed.
+
+Debian Online Help tries hard to not carry with it excessive dependencies
+in order to allow you to accommodate any software setup without bringing in
+unneeded components. All optional components will be used if found, but the
+core functionality will still be provided if they are missing. If they get
+installed in the future, they will be available at the next index update.
+
+The list below summarizes the available functionality in any possible setup.
+Note that browsing offline through the file:/// protocol, as well as using
+search through the `dhelp <query-string>' command remain functional in _all_
+cases. 
+
+-- No web server installed:
+
+   Only offline mode works. Online mode and CGI scripts do not.
+   If you do not wish to install even a web browser, you can still use the
+   `html2text' package to view the text of the index pages from the console.
+
+-- A web server that does not support CGI is installed:
+
+   Offline and online modes work (web server may need manual configuration,
+   cf. section 1 below). CGI scripts do not work (ie the links to man and
+   info pages, the online mode's links to the documentation and the search
+   web form).
+
+-- A web server that supports CGI is installed, but man2html/info2www aren't
+
+   Offline and online modes work, as well as the the online mode's links to
+   the documentation and the search web form. The links to man/info pages
+   are inactive.
+
+-- A web server that supports CGI as well as man2html/info2www are installed
+
+   The full functionality of Debian Online Help is available.
+
+
+2. Configuring dhelp to work with a web server
+==============================================
+
+Debian Online Help comes pre-configured for quite a few web servers that
+support aliases. If this is your case, then no further actions are needed
+(you may have to issue the command `dpkg-reconfigure dhelp' in case you 
+are installing the web server _after_ dhelp has been installed).
+
+For some web servers though that support aliases and for all web servers
+that do not support them, it is required to do a few actions by hand in
+order to finish dhelp configuration.
+
+The following tables summarize the situation and gives instructions for
+dhelp configuration with each web server:
+
+Table #1: Web servers that _do not_ require manual configuration
+------------------------------------------------------------------------------
+boa         : The default boa configuration has the /doc alias enabled.
+------------------------------------------------------------------------------
+lighttpd    : A configuration snippet is installed during dhelp installation.
+------------------------------------------------------------------------------
+mathopd     : The default mathopd configuration has the /doc alias enabled.
+------------------------------------------------------------------------------
+
+Table #2: Web servers that _may_ require manual configuration
+------------------------------------------------------------------------------
+apache2     : A configuration snippet is installed during dhelp installation.
+
+              For newer versions of the package (squeeze: >=2.2.16-6+squeeze7,
+              wheezy: >=2.2.22-4, all: >=2.4.1) you will have to enable the
+              /doc alias manually due to CVE-2012-0216.
+
+    Action  : Uncomment the `Alias /doc/ ...' line inside the installed dhelp
+              configuration snippet for apache2. Its path depends on apache2
+              version.
+              <  2.4 : /etc/apache2/conf.d/dhelp
+              >= 2.4 : /etc/apache2/conf-available/dhelp.conf
+------------------------------------------------------------------------------
+
+Table #3: Web servers that _do_ require manual configuration
+------------------------------------------------------------------------------
+bozohttpd   : Does not support aliases. Action : cf. [1] below.
+------------------------------------------------------------------------------
+micro-httpd : Does not support aliases. Action : cf. [1] below.
+------------------------------------------------------------------------------
+mini-httpd  : Does not support aliases. Action : cf. [1] below.
+------------------------------------------------------------------------------
+monkey      : Does not support aliases.
+
+ [1] Action : Create a symlink named `doc' to `/usr/sharedoc', inside
+              the web server's document root (Debian default is /var/www).
+              The command to create it is:
+
+                  ln -s /usr/share/doc  /var/www/doc
+------------------------------------------------------------------------------
+nginx       : The default nginx configuration has the /doc alias enabled, but
+              the server does not support CGI scripts by default.
+
+    Action  : Install the `fcgiwrap' package and copy the following line to
+              the `server {...}' block of the default virtual site (its path
+              is: /etc/nginx/sites-available/default):
+
+                  include /usr/share/doc/fcgiwrap/examples/nginx.conf
+------------------------------------------------------------------------------
+yaws        : An example configuration file for dhelp is provided at
+              `/usr/share/dhelp/config/yaws-dhelp.conf', but is not installed
+              in `/etc/yaws/conf.avail' because yaws does not allow overlayed
+              <server> directives.
+              In addition, the cgi scripts coming with dhelp cannot work as is
+              because they lack the `.cgi' extension.
+
+    Action  : Use the supplied dhelp configuration snippet to manually edit
+              your configuration. To support the dhelp cgi scripts you need
+              to create a wrapper erlang appmode and edit the configuration
+              to load it.
+------------------------------------------------------------------------------
+
+Any web server not listed in the tables above will most probably require
+manual configuration. The recipy in [1], above, will work with any web
+server, so this is the first thing to try.
+
+The dhelp configuration snippets provided at /usr/share/dhelp/config, as
+`<webserver>-dhelp.conf' for each web server, list additional information
+in case you would like to create a custom dhelp configuration. 
+
+
+3. Notes about indexing in dhelp
+================================
+
+3.1 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-
@@ -50,8 +193,8 @@ 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
-===============
+3.2 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
@@ -65,8 +208,8 @@ 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
-=========
+3.3 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