## INSTALL - How to compile and install          Sam Jun  9 15:33:53 CEST 2001
## ===========================================================================
#
# For the impatient:

'cd' into the html2text distribution directory

./configure	(in some shells 'sh ./configure')
make		(or in some cases 'make -r')

'mv' the html2text executable to its installation directory (e.g. /usr/local/bin)


## ---------------------------------------------------------------------------
#
# html2text can be compiled on many UNIX-like platforms, in particular those
# that provide a modern GNU compiler (g++).

1. Untar the distribution package:

	$ gunzip html2text-1.2.X.tar.gz
	$ tar xf html2text-1.2.X.tar


2. Change into the html2text distribution directory:

	$ cd html2text-1.2.X


3. To generate the make files, issue:

	$ ./configure

If you're using a csh on an old version of System V, you might need to type
'sh ./configure' to prevent the csh from trying to execute 'configure'
itself.

While the script is running, it prints some messages telling which features
it is checking for, alike (the exact output depends on your platform):

| Checking C++ compiler... use "g++"
| Checking <sys/poll.h>... OK
| Checking for socket libraries... no extra libraries required
| Checking "bool"... built-in
| Checking "explicit"... built-in
| Checking Standard C++ library... works; no need to make "./libstd"
| Checking "auto_ptr"... not defined or not working, use
|  "./libstd/include/auto_ptr.h"
| Checking "makedepend" includes... use "-I/usr/include -I/usr/include/bits
|  -I/usr/include/g++ -I/usr/include/gnu -I/usr/include/sys
|  -I/usr/lib/gcc-lib/i486-suse-linux/2.95.2/include "
| Creating "./Makefile" from "./Makefile.in"... done
| 
| Preparing completed. You may now run "make".


4. Optionally, run

	$ make depend

if you have the MAKEDEPEND utility.


5. Then compile html2text with:

	$ make

Some compilers have weird built-in rules which collide with the rules in the
make files. If 'make' fails, then try to disable the built-in rules. For most
'make' utilities, this can be achieved by specifying the '-r' command line
option, i.e. 'make -r'.

Compiling 'html2text' takes awhile. While 'make' is running, it will print
some messages (and, hopefully, no errors), alike:

| g++ -c  -DVERSION=1.2.4    -DAUTO_PTR_BROKEN -O html2text.C
| g++ -c  -DVERSION=1.2.4    -DAUTO_PTR_BROKEN -O html.C
| g++ -c  -DVERSION=1.2.4    -DAUTO_PTR_BROKEN -O HTMLControl.C
| g++ -c  -DVERSION=1.2.4    -DAUTO_PTR_BROKEN -O HTMLParser.C
| g++ -c  -DVERSION=1.2.4    -DAUTO_PTR_BROKEN -O Area.C
| g++ -c  -DVERSION=1.2.4    -DAUTO_PTR_BROKEN -O format.C
| g++ -c  -DVERSION=1.2.4    -DAUTO_PTR_BROKEN -O sgml.C
| g++ -c  -DVERSION=1.2.4    -DAUTO_PTR_BROKEN -O table.C
| g++ -c  -DVERSION=1.2.4    -DAUTO_PTR_BROKEN -O urlistream.C
| g++ -c  -DVERSION=1.2.4    -DAUTO_PTR_BROKEN -O Properties.C
| g++ -c  -DVERSION=1.2.4    -DAUTO_PTR_BROKEN -O cmp_nocase.C
| g++ -O html2text.o html.o HTMLControl.o HTMLParser.o Area.o format.o sgml.o
|  table.o urlistream.o Properties.o cmp_nocase.o    -o html2text
| 
| Compilation completed. You may now move "html2text", "html2text.1.gz"
| and "html2textrc.5.gz" to their installation directories (e.g.
| "/usr/local/bin", "/usr/local/man/man1" and "/usr/local/man/man5").

Notice: To generate 'HTMLParser.C' and 'HTMLParser.h' from 'HTMLParser.y',
you need bison++, proposed Version 2.2. bison++ was written by Alain
Coetmeur, and 2.2 is a March 1993 version. I don't know where an 'official'
bison++ distribution can be found, nor to which platforms it has been ported
to. For those who don't have bison++ 2.2, the generated 'HTMLParser.C' and
'HTMLParser.h' files are included, so you will be able to compile html2text
even if you don't have bison++.


6. No automatic installation is provided by now.

Be root. Then move the html2text executable and the manual pages to their
respective installation directories (e.g. /usr/local/bin, /usr/local/man/man1
and /usr/local/man/man5). Be sure you set the execution rights accordingly
and the files are owned by root or whoever owns binaries on your system. E.g.:

	# install -s -m 755 html2text /usr/local/bin
	# install -m 644 html2text.1.gz /usr/local/man/man1
	# install -m 644 html2textrc.5.gz /usr/local/man/man5

After this, create a directory for the documentation files at an appropriate
place (e.g. /usr/doc/html2text or /usr/share/doc/html2text), and move all
documentation files into that folder. E.g.:

	# install -d -m 755 /usr/share/doc/html2text
	# install -b -p -m 644 *[ABD-Z] /usr/share/doc/html2text

Be sure you read the README file!


## ---------------------------------------------------------------------------
#
# Hints for porting html2text to other platforms:


From version 1.02, html2text requires the "socket()" function and its
friends, which live in different libraries for the different systems.
"configure" tries several sets of "-l" linker options to find the right
libraries.

Some C++ compilers lack a built-in "bool" data type. "configure" attempts to
find a suitable definition which it passes to the compiler with
"-DBOOL_DEFINITION=...".

html2text requires a standard C++ library. Since some old C++ compilers do
not come with a standard C++ library, I have implemented parts of the library
in the 'libstd' subdirectory; the exported header files are in
'libstd/include'. For platforms which come with a (working) standard C++
library, the "home-grown" library in 'libstd' is not compiled and linked.
However, on some platforms, these librarys did not work. I don't know if this
because the compiler or our 'libstd' library is broken, or because we have
some syntax errors in the source code files.

Some old GNU Standard C++ Library versions falsely re-names "list::erase()"
as "list::remove()". I fixed this with a "-DSTRING_ERASE=remove" on the "g++"
command line.

Some compilers do come with a Standard C++ Library, but the definition of the
"auto_ptr" template is missing from "<memory>", or is not standard-compliant.
This condition is checked by "configure" and "./libstd/include/auto_ptr.h" is
included if necessary (preprocessor symbol "HAS_WORKING_AUTO_PTR").

"make depend" attempts to run the MAKEDEPEND utility (not included in this
package). Unfortunately, most C++ compilers implicitly use some "secret"
include directories, which MAKEDEPEND doesn't know of; as a result,
MAKEDEPEND may issue some "could not find..." errors, which shouldn't worry
you. The "configure" script attempts to guess the "secret include directory"
and passes it with "-I" to MAKEDEPEND.

Have fun, Arno.


## ---------------------------------------------------------------------------

Martin Bayer <mbayer@zedat.fu-berlin.de>
