RJKDOC
======

RJKDOC consists of SGML DTD plus some processing tools for converting
into other formats - text, HTML and troff man page source.

It is intended to build both man pages and reference documentation
from a single source.


Warning
-------

This should be considered pre-release software.  There are doubtless
bugs and flaws.  Please send bug reports and/or patches to Richard
Kettlewell at <richard+rjkdoc@sfere.greenend.org.uk>.

NOTE: Do not blame me if any of the things recommended below break
your system.  You are expected to know what you are doing if you go
round patching your include files.  Make backup copies before altering
anything.


Assumptions
-----------

Tools Required

The programs are written in a combination of C and C++ and depend on
the SP library and header files.  So you must have a working C++
compiler and libraries, and SP installed somewhere.  egcs-2.91.60 and
the Debian package of SP work for me.

Try ftp://ftp.jclark.com/pub/jade if you don't have SP.

GNU Make is required.

You'll need my rgetopt library installed.


Build Assumptions

My code rather assumes SP_MULTI_BYTE was set when SP was built, and
consequently uses wide characters everywhere; this is because that's
how the binary library of SP is installed by Debian.


C++ wstring Type

On some systems there are some "issues" involving the `wstring' type.

The first problem you may encounter is that it is simply not defined;
in fact the configure script knows about this and will cause it to be
defined in terms of basic_string if it is missing.

Secondly on some systems basic_string is not suitable for turning into
a `wstring', or indeed anything other than a `string'.  In particular,
libstdc++ 2.91.60 in Debian would appear to have such a problem
(Bug#46550, now closed); hopefully you have a more recent version, but
if not upgrade or apply `wstring.patch' in the rjkdoc distribution to
your installed copy of `/usr/include/g++-2/std/bastring.h'.

Update: they contrived to break it AGAIN.  The GCC 2.95.4 libstdc++
requires '/usr/include/g++-3/std/bastring.h' to be patched by
'wstring.patch.g++-3'.


SP Installation

Finally, on some systems SP is not properly installed.  In particular, 
`EventGenerator.h', `ParserEventGeneratorKit.h' and
`SGMLApplication.h' are missing.  If you have this problem, copy these 
files from the SP source distribution into some directory where the
compiler will find them.  (I use /usr/local/include/sp, and tell the
configure program to look there.)

Now that we've got all that out of the way, we can move on to...


Building and Installation
-------------------------

You must tell configure where to look for the SP includes and
library using the --with-spinclude and --with-splib options.  Both of
these take a space-separated list of directories, which will be used
on the compiler command line with the appropriate -I and -L options.

Also, you can (optionally) identify the SGML catalog to update using
the --with-sgml-catalog option.  This can be overridden at install
time by setting the SGML_CATALOG makefile variable.

For example:

    sh configure --with-sp-include=/usr/local/include/sp \
                 --with-sp-lib=/usr/local/lib

You can list multiple directories in these options, for example:

    sh configure --with-sp-include="/usr/include/sp /usr/local/include/sp" \
        --with-sgml-catalog=/etc/sgml.catalog

If you have rgetopt installed as a shared library, you can use that
instead of using the built-in copy:

    sh configure --with-rgetopt-include=/usr/local/include \
                 --with-rgetopt-lib=/usr/local/lib

If you have it installed and configure detects it, but nonetheless
want to use the built-in version for some reason, specify
`--with-builtin-rgetopt=yes' to configure.

To build type one of these commands:

    make                           # includes debugging symbols
    make CXXFLAGS=-O2 CFLAGS=-O2   # excludes debugging symbols

The latter is faster and requires less disc space.  Finally install
with one of these commands:

    make install                   # does not strip binaries on install
    make install-strip             # strips binaries on install

This will install files as follows:

1) The librjkdoc shared library will be installed in ${libdir}, if the 
   package was built with shared libraries in use.

2) The binaries will be installed in ${bindir} and their manual pages
   under ${mandir}.

3) The rjkdoc DTD will be installed under ${dtddir}, which defaults to
   ${sgmldir}/dtd.  The rjkdoc-chars entity will be installed under
   ${entitydir}, which defaults to ${sgmldir}/entities.

4) If an SGML catalog file was specified with --with-sgml-catalog, or
   by setting the makefile variable SGML_CATALOG, then that file will
   be updated to map the public identifiers for the rjkdoc DTD and
   rjkdoc-chars to the installed filenames.

See `INSTALL' for more (generic) information.


Documentation
-------------

The source to the documentation is in rjkdoc.sgml.  Plain text and
HTML versions are also included in the distribution tarball, and man
pages are generated at compile time.

------------------------------------------------------------------------

Local Variables:
mode:text
End:
