/*******************************************************************************

    Author ......... Simon Newell
    Contact ........ simonnew@speedymail.org
    Home Site ...... http://sourceforge.net/projects/attachment-doc/
    Plugin ......... Document Attachment To Html Converter (attachment_doc)
    Version ........ 1.1
    Purpose ........ Allows you to convert your document attachments 
                     (.doc, .pdf) 
                     to html and view them in a browser.

*******************************************************************************/

The SquirrelMail attachment_doc plugin depends on 3rd party libraries for the
conversion of the document attachments to html format. This document contains
generic installation instructions for the attachment_doc plugin.

	1. Installing the attachment_doc plugin

	2. Upgrading the attachment_doc plugin

	3. Downloading and installing wv (required for msword attachments)

	4. Downloading and installing pdftohtml (required for pdftohtml attachments)

Each of these steps will be described below in detail. 


Installing the attachment_doc plugin
=====================================

1) Un-tar attachment_doc into the SquirrelMail plugins directory.
   e.g.

   $ cd /var/www/htdocs/squirrelmail/plugins
   $ gzip -dc attachment_doc-1.0.tar.gz | tar xvf -

2) Copy config.php.sample to config.php and modify the config.php file in the
   attachment_doc includes directory such that $bindir contains the path where the 
   required wvHtml and pdftohtml binaries are located. 
   e.g.

   $ cp config.php.sample config.php
   $ vi config.php

   The default path is "/usr/local/bin".

3) Modify the config.php file in the attachment_doc includes directory
   such that $dirname contains the path where generated html and graphic 
   files are kept and viewed. This path should be both writable and 
   readable by the httpd user (i.e. nobody or apache in most cases).
   e.g.

   $ chown apache:apache squirrelmail/plugins/attachment_doc/tmp

   $ ls -ld squirrelmail/plugins/attachment_doc/tmp/
   drwxr-xr-x    2 apache   apache       4096 Jul 22 04:11 tmp/

   The default path is "<SM_PATH>/plugins/attachment_doc/tmp".

   NB: See "Downloading and installing wv" and "Download and installing 
       pdftohtml" sections for further instructions.

4) Go to your config directory and run conf.pl. Choose
   option 8 and add the plugin (+). Save and exit.
   
   $ cd ../config
   $ ./conf.pl


Upgrading the attachment_doc Plugin
===================================

1) Un-tar attachment_doc into the SquirrelMail plugins directory.

   $ cd plugins
   $ tar -zxvf attachment_doc-2.1.tar.gz

2) Change into the attachment_doc includes directory, check your config.php 
   file against the new version, to see if there are any new settings that 
   you must add to your config.php file.

   $ diff -Nau config.php config.php.sample
         
   Or simply replace your config.php file with the provided sample and 
   reconfigure the plugin from scratch 
   (see step 2 under the installation procedure above).


Downloading and installing wv
=============================

  The attachment_doc plugin uses wv in converting msword documents to html.
  The external libraries needed by wv are zlib, libpng and libwmf.

  wv homepage:
  http://wvware.sourceforge.net/index.html

  Links to the required packages:
  http://prdownloads.sf.net/wvware/wv-1.0.0.tar.gz
  http://www.zlib.net/zlib-1.2.1.tar.gz
  http://download.sourceforge.net/libpng/libpng-1.2.5.tar.gz
  http://prdownloads.sf.net/wvware/libwmf-0.2.8.3.tar.gz

1) Install the zlib library:

   $ ./configure
   $ make test
   $ make install prefix=PATH 
     (where PATH is the folder to install zlib, the default is /usr/local)

2) Install the libpng library:

   Before installing libpng, you must first install zlib. zlib can be 
   placed in another directory, at the same level as libpng. Your system 
   might already have a preinstalled zlib, but you will still need to have 
   access to the zlib.h and zconf.h include files that correspond to the
   version of zlib that's installed.

   After installing zlib, copy the file (or files) that you need from the
   libpng scripts directory into main libpng directory,
       
   $ cp scripts/makefile.std makefile

   Read the makefile to see if you need to change any source or target 
   directories to match your preferences. Then read pngconf.h to see if you 
   want to make any configuration changes.

   Then just run "make test" which will create the libpng library in this 
   directory and run a quick test that reads the "pngtest.png" file and 
   writes a "pngout.png" file that should be identical to it. Look for 
   "9782 zero samples" in the output of the test.

   $ make test
   $ make install

3) Install the libwmf library:

   $ ./configure --prefix=PATH
     (where PATH is the installation prefix, the default is /usr/local)

   $ make test
   $ make install

   By default, `make install' will install the package's files in
   `/usr/local/bin', `/usr/local/man', etc.  You can specify an
   installation prefix other than `/usr/local' by giving `configure' 
   the option `--prefix=PATH'.

4) Build and install wv:

   $ ./configure --with-libwmf --with-png --with-zlib --prefix=PATH
     (where PATH is the installation prefix, the default is /usr/local)

   $ make
   $ make install

   By default, `make install' will install the package's files in
   `/usr/local/bin', `/usr/local/man', etc.  You can specify an
   installation prefix other than `/usr/local' by giving `configure' 
   the option `--prefix=PATH'.

5) You can test out the installation by running the following command 
   to convert a sample doc file to a html file:

   $ /usr/local/bin/wvHtml --targetdir=/tmp /tmp/testinput.doc testoutput.html

For more detailed explanations on the installation, consult the INSTALL 
file for the wv package and the various libraries.

Downloading and installing pdftohtml
====================================

  The attachment_doc plugin uses pdftohtml in converting pdf files to html.

  The pdftohtml home page:
  http://pdftohtml.sourceforge.net/

  Links to the required packages:
  http://prdownloads.sf.net/pdftohtml/pdftohtml-0.36.tar.gz


1) Install the pdftohtml package:

     $ make

2) Copy the compiled binary to the specified folder you want.

     $ cp pdftohtml /usr/local/bin/pdftohtml

3) You can test out the installation by running the following command 
   to convert a sample pdf file to a html file:

     $ /usr/local/bin/pdftohtml -q -c -noframes /tmp/testinput.pdf /tmp/testoutput.html

For more detailed explanations on the installation, consult the INSTALL 
file for the pdftohtml package.

