Directory structure (for reference if things go wrong!)
-------------------------------------------------------

The description of the directory structure is for a complete standalone 
system run by a single user.  If you are installing costwish for the
first time, it's probably a good idea to do this so you can test the 
installation and get to know how it works.  If you later install it for
system-wide usage (e.g. /usr/local/bin, /usr/local/lib) you'll need to 
make sure it doesn't clash with any components that might already have been
installed.

costwish is an extensible system that can be used for many DTDs and if you are
installing all the components yourself I recommend you install it something 
like this (MYHOME might be your home directory, or you might wish to make a 
special directory for everything mentioned here).  Directories in brackets
are optional - some people like to have local bin and/or lib directories:

			       MYHOME
                                 |
  -----------------------------------------------------------------------
  |       |       |        |        |       |      |     |      |       |
(bin)    blt    cost   costwish   (lib)   sgml    tcl    tk    tix    mydtd
                           |
                  	   |
     ---------------------------------------------
     |      |     |      |     |     |      |     |
   (bin)   cw   demos  docs   dtd   lib    src  user

If you download a pre-compiled version of the costwish executable, you do
NOT need the lib, blt, cost, tcl, tk, or tix directories.  (You will still 
need the BLT and TIX library files in costwish/lib).

If you *do* need to compile costwishexe, it helps if blt, cost, tcl, tk and 
tix are all at the same level.  These directories should be the ones that
correspond to versions, so 'tcl' corresponds to the 'tcl7.4' directory that
will unpack from the tcl distribution.  (BLT, cost, tcl, tk, tix may therefore
all have version suffixes).

Optional or only required for compilation:

bin:	for the excutables (e.g. sgmls, costwishexe, helper applications, etc.)
	bin should be early in your PATH so that typing 'sgmls' runs this 
	version:
		set path=($MYHOME/bin $path)

	Alternatively you may wish to install the executables somewhere like
	/usr/local/bin, or you may have a personal bin directory already.

lib:	This library is for linking the costwish executable and contains
	archived object libraries such as:
		libtcl.a, libBLT.a

        Alternatively you may wish to install the archives somewhere like
        /usr/local/lib, or you may have a personal lib directory already.

	NOTE:  during linking, there will be a LIBSRC path or similar.  If
	you pick up *incompatible* versions of the archives (e.g. from a
	Linux slackware distribution or similar) your exe's will crash.  All
	*.o and *.a MUST be compiled and linked with tcl7.4 and tk4.0
	(Not earlier OR later).

blt:	the full distribution kit for blt-1.8.  Unpack it directly here.  
	(NOTE:  blt is not used directly in core costwishexe and could be 
	omitted if absolutely necessary.)

tix:	the full distribution kit for Tix-4.06b.  Unpack it directly here.

tcl/tk:	the full distribution kit for tcl7.4 and tk4.0.  Do NOT try to use 
	tcl7.5 or tk4.1 or later versions until the tcl distribution has
	stabilised the procedure for sharable libraries.  If you already use
	tcl7.5, etc. cost-2.03a is not compatible.

	If any brave souls wish to port costwishexe to tcl/tk under Windows,
	we'd LOVE to hear from you!  It should be possible and we hope it will
	happen some time later this year.

cost:	the full distribution kit for cost-2.03a.  Unpack it directly here.

sgml:	I keep things like sgmls, perlSGML (dtd2html), etc. under it.
        sgmls executables are available for many systems, but it's also 
        very easy to compile.

mydtd:	You may wish to keep your own (or other DTDs) at the same level.  A
	minimal system for using with costwish might contain:

	mydtd/dtd/:		directory for DTD(s), catalog(s), declarations,
				etc.
	mydtd/setup.csh:	shell script to customise environment for this
				DTD.
	mydtd/costwish/:	directory with *.tcl scripts for running under
				costwish.
	mydtd/data/:		directory for document instances of that DTD.
	
	mydtd/doc/:		directory with docs for that DTD (maybe 
				produced by dtd2html).

Essential:

costwish: This directory tree should be created when costwish is downloaded.
	It contains (at least) the following:

				costwish
				   |
            ---------------------------------------------
            |      |     |      |     |     |      |     |
          (bin)   cw   demos  docs   dtd   lib    src  user


bin:	An optional directory for binaries (e.g. helper applications).

cw:	The main tree for costwish tools - see below
	Within cw are the following important files:
		costwishini.tcl	initialisation for costwish.  This may need
				tweaking for you environment
		customisation.tcl  addtional local customisation for costwish
				(such as DTD support, local helpers, etc)
		misc_local.tcl  other local support routines not linked to a
				DTD.
		other*.tcl	these should not be edited.
		null.esis	resets costwish to a NULL document

demos:	A number of simple examples (*.sgm) to ensure your installation is OK
        and to help you understand some of the simpler aspects of SGML.
	Also a set of tutorials.  Some ESIS streams are also provided.

docs:	Several types of documentation (*.html for costwish, costdoc 
	(from Joe), blt, tix, etc)

dtd:	This contains a catalog and some common DTDs (html-2.0, docbook-2.4,
	play.dtd).  It also contains a subdirectory (ents) with most of the
	common ISO entities.  There may be some HTML-based documentation.

lib:	Essential.  This should contain 4 subdirectories:
		cost    tcl7.4  tix     tk4.0
	These contain *.tcl scripts which customise the costwish executable
	at runtime.  They are pointed to by environment variables set up by:
		setenv COSTWISH $MYHOME/costwish
		setenv COSTWISHLIB $COSTWISH/lib
		setenv COSTLIB $COSTWISHLIB/cost
		setenv TIX_LIBRARY $COSTWISHLIB/tix
		setenv TCL_LIBRARY $COSTWISHLIB/tcl7.4
		setenv TK_LIBRARY $COSTWISHLIB/tk4.0
	If you get an error message complaining about any of the last four
	environment variables, check that it is set and pointing to here.

src:	Optional.  C code that could be linked into costwishexe (cmllib.c) or 
	standalone helpers (e.g. dtdless.c).  At present DTD-specific routines
	are either written in *.tcl scripts or have to be linked into 
	costwishexe.  With later versions of tcl it should be possible to 
	load object libraries at run-time.

user:	the *.tcl scripts to customise each DTD.  There are two:
		play:  Jon Bosak's Shakespeare DTD
		costdoc: Joe English's DTD for cost documentation.


The cw subtree:
		     cw
		      |
                  ---------
		  |  	  |
		html	library	

html:	costwish scripts for postprocessing HTML documents (rudimentary so far)

library: Support *.tcl scripts for costwish (mainly by other authors than PMR).

