ht://Dig 3.2.0b4 README.developer
Copyright (c) 2002-2004 The ht://Dig Group

--
This README file is for newbie developers like myself.  As I learn stuff,
I'm putting it here.  If anyone wants to write a better guide, please do!

Lachlan   lha@users.sourceforge.net

--
I follow Lachlan's initiative, and post some new things here as well. :-)

Gabriele  angusgb@users.sourceforge.net


AUTOMATICALLY GENERATED FILES
=============================
Many files, such as  attrs.html,  are automatically generated from a "master"
documents, such as  defaults.cc.  The procedure for generating these files
is as follows.

To generate		From			Use
===========		====			===
htdoc/attrs.html,	htcommon/defaults.cc,	htdoc/cf_generate.pl
htdoc/cf_byprog.html,	htdoc/attrs_head.html,
htdoc/cf_byname.html	htdoc/attrs_tail.html,
			htdoc/cf_byprog_head.html
			htdoc/cf_byprog_tail.html
			htdoc/cf_byname_head.html
			htdoc/cf_byname_tail.html

Many files are automatically overwritten by the configuration process from
their "*.in" variants.  These include:
    */Makefile
    db/db.h
    db/configure
    db/db_config.h
    db/stamp-h
    include/config.h
    include/stamp.h
    test/test_functions
    test/conf/access.conf
    test/conf/htdig.conf
    test/conf/htdig.conf2
    test/conf/htdig.conf3
    test/conf/httpd.conf
    test/conf/mime.types.in
    test/conf/srm.conf.in

AUTO{CONF,MAKE}
===============
First, I suggest you to give a look at the 'GNU autoconf, automake and libtool' book
by Gary V. Vaughan, Ben Elliston, Tom Tromey  and Ian Lance Taylor. It is freely
downloadable from the net at http://sources.redhat.com/autobook/ - if you have a
Debian Linux station, just type 'apt-get install autobook'. It is a great source
of information.

Don't change the  Makefiles  or  configure  directly.  They are generated
automatically by a 'bootstrapping application' from the  Makefile.in  and
configure.in  files.
Although the book above suggest to use a specific bootstrapping script (see
chapter 8 'Bootstrapping'), we just use the latest autoconf version.

The Makefile.in files are in turn generated from Makefile.am  and configure.in
is manually modified (initial suggestion came from autoscan).

The file called aclocal.m4 is generated by aclocal according to the macros that
are present on the developer's machine and to the contents of the acinclude.m4 file:
if you want to add some specific macros (you can get some from the 'autoconf archive'
project by GNU) you have to do it here not in aclocal.

According to configure.in and aclocal.m4, configure script is then generated, by autoconf.

The dependencies seem to be:
configure <-- configure.in
	   |
	   |- aclocal.m4 <-- *** acinclude.m4 (change this) ***

Make changes to  Makefile.am  or  acinclude.m4  and then type:
autoreconf -if

Current source files have been generated by using: autoconf 2.57,
libtool 1.5.0a and automake 1.7.6

See <http://www.murrayc.com/learning/linux/automake/automake.shtml>.


THINGS TO DO WHEN MAKING A CHANGE:
==================================

- Add any new attributes to  defaults.cc  and run  cf_generate.pl
- Add any new dependencies to  */Makefile.am  and run  aclocal  etc., as above.
- Add new tests in  test/  to test the new functionality
- Test by (at least!)  "./configure --enable-tests"  then  "make check"
- Write a Changelog entry.
- Update STATUS if appropriate