XML Catalog Manager                                                  README
===========================================================================


Introduction
------------

XML Catalog Manager, or xmlcatmgr for short, is an utility used to
manipulate SGML and XML catalogs.  Its main purpose is to add and remove
entries from them in a completely automated way.  It is designed with
simplicity in mind to avoid depending on external programs and/or
libraries.

This document describes build-time features specific to this package.  No
instructions about how it works are given here.  For those, refer to the
xmlcatmgr(1) manual page after installation.

You can find the latest version of this program, as well as more
information, on its web site:

        http://xmlcatmgr.sourceforge.net/


License
-------

This program is licensed under the terms of a license known as the Revised
BSD License.  Read the `COPYING' file, included in the distribution file,
for more information.


Installation procedure
----------------------

This source code package uses the GNU Build System, composed of GNU
Autoconf and GNU Automake.  This means that it comes with a standard
`configure' script and a set of well known make targets.

The `INSTALL' document, included in the distribution file, describes the
installation procedure using all standard options.  The following sections
describe all extra features found in this package.


Default catalog files
---------------------

This program can manage XML and SGML catalogs, despite its name.  Every
system has a pair of system wide catalogs which apply to all packages
installed in it.  xmlcatmgr uses the following default values:
${sysconfdir}/sgml/catalog for the SGML catalog and
${sysconfdir}/xml/catalog for the XML catalog.  These are just defaults
which can be overriden at run time by a command line option.  However, it
is often useful to have those defaults properly adjusted for the current
system.

One way to change both defaults at once is to change the `sysconfdir'
setting using configure's `--sysconfdir' argument.  For example, issuing:

        $ ./configure --sysconfdir=/etc

changes the defaults to /etc/sgml/catalog and /etc/xml/catalog.  Note that
this command is the one you will want to use if you are running a Linux
system, because they often store SGML and XML catalogs in these places.

If setting `sysconfdir' is not enough for your purposes, you can set the
DEFAULT_CATALOG_SGML and DEFAULT_CATALOG_XML environment variables before
running `configure' (or give them at the command line), which will change
the default SGML and XML catalogs respectively.  So, another way to achieve
the same behavior as before could be:

        $ ./configure DEFAULT_CATALOG_SGML=/etc/sgml/catalog \
                      DEFAULT_CATALOG_XML=/etc/xml/catalog


Developer mode
--------------

Programming without mistakes is impossible.  This package comes with a
special mode that enables several features to try to catch some of them.
As the program is considered stable, this mode is disabled by default,
which means that assertions, debugging code and warning messages during
compilation are all turned off.  However, if you are interested in
improving the program or finding bugs in it, you should enable this mode
by passing the `--enable-developer' flag to the `configure' script.


Installation of documentation
-----------------------------

Most of the documents found in the root directory of the distribution file
are installed alongside the program, mainly to ensure that the full text of
the license is placed somewhere.  However, you can disable the installation
of such documents passing the `--disable-docs' flag to the `configure'
script.


The manual page
---------------

The included manual page is written using groff's mdoc package.  It is
installed in source form, so that a viewable version is generated upon user
request.  Therefore you will need to have the correct version of groff with
the mdoc package to be able to see it.  The `configure' script performs no
checks on this issue.


Versions of tools
-----------------

Since all the files created by the GNU Build System are not under version
control (due to multiple reasons), it is useful to keep a record of which
versions of each tool were used to generate the files distributed in this
tarball.  This allows a further reconstruction of the tarball, if needed.

The following versions correspond to this tarball:

- GNU Autoconf 2.59
- GNU Automake 1.9.1
- GNU M4 1.4

Please note that you _don't_ _need_ any of the tools listed here to build
this program by itself.


Building from the repository
----------------------------

If you have fetched this program's source code using CVS, you may have
probably noticed that all the files generated by the GNU Build System are
missing, as described in the previous point.  In order to recreate those
files, make sure you have the appropiate versions of the tools and issue:

        $ autoreconf -is

If you wish to clean your source tree completely of any files not managed
by the repository, run the `clean-all.sh' script located in the `admin'
directory:

        $ ./admin/clean-all.sh


Feedback
--------

Should you have any comments, criticisms, opinions, suggestions or
anything else, contact me at:

        Julio M. Merino Vidal <jmmv@users.sourceforge.net>

Thank you for using this program.


===========================================================================
$Id: README,v 1.15 2004/09/01 09:04:14 jmmv Exp $
