Installation guide for Halibut
==============================

This file is a guide to building and installing the documentation
utility `Halibut' from its source archive.

If you are reading this, then you have probably already unpacked the
source archive somewhere.

Building Halibut
----------------

If you have GNU make and gcc, you should simply be able to type
`make'. The Makefile will generate a `build' subdirectory, and will
put all the object files and binaries in there.

In a release archive, the Makefile will also check the source files
against a list of MD5 checksums, and if they match it will
automatically add the correct version number to the build. This is
_not_ a secure measure intended to enforce that only approved
Halibut sources are ever built into a binary with a given version
number; it is merely a sanity check against heavily modified copies
_accidentally_ confusing users expecting standard versions of
Halibut. Distribution maintainers are entirely at liberty, if they
choose, to modify Halibut source files as appropriate for their
distribution and then have the resulting binary call itself by the
original version number. If you run `make VERSION=x.y', the
resulting Halibut binary will call itself version x.y irrespective
of the md5sum manifest. (You may also need to do this if your build
system does not have the md5sum program.)

Halibut unfortunately does not yet come with an autoconf-generated
makefile, so if you do not have these utilities then you will have
to do the build manually. Look in the master `Makefile' to find the
list of source modules (they will be listed on the line starting
`MODULES :=', and continued on lines starting `MODULES +='), compile
those files with the C compiler of your choice, and link them
together into a binary. In addition to the modules on that list, you
will also need to compile `version.c', and if you wish your Halibut
binary to identify itself with a version number then you will have
to define the preprocessor symbol `VERSION' to the required version
number string. On Unix this can be done with a command such as

  cc -c -DVERSION=\"0.9\" version.c

Halibut's source files are intended to be almost entirely portable
ANSI C. If they fail to compile and run correctly on your compiler,
this might very well be considered a bug.

Building the Halibut manual
---------------------------

Once you have built Halibut itself, you might well want to build its
manual. If you're using GNU make, you can do this just by changing
into the `doc' subdirectory and typing `make'. (This relies on the
Halibut binary you built in the previous step being present in the
`build' subdirectory.)

Failing that, you will need to read the Makefile and run a manual
Halibut command, of the form

  halibut --text=halibut.txt --html blurb.but intro.but [...] index.but

(The precise list of .but files is given at the top of doc/Makefile.)

This will build plain text documentation in `halibut.txt', and a set
of HTML files (*.html). It will also build a short man page
`halibut.1', although this is by no means a replacement for the full
manual.

Installing Halibut
------------------

Halibut requires no additional data files. Simply install the
binary, man page and full documentation in appropriate places for
your system.