
			Costwish 1.0

'costwish' refers to a system for analysing, rendering and processing SGML
documents.  It consists of several components, all of which are supplied in 
this kit.  Some of these (e.g. sgmls, tcl/tk) are widely used and may already
be installed on your system.  Be careful in this case, sinec they may be 
different versions and incompatibilities may not be obvious.  If in doubt,
talk to your local sysguru - if still unclear, construct the whole of the
system in your area (i.e. without linking into system-wide libraries, etc.).

NOTE:  The parsing step (translation of an SGML document into its ESIS 
representation) is independent of costwish (which can, if desired, accept
raw ESIS files).  This means that there are two separate and independent 
parts to the installation and if you have any difficulties you should tackle 
them separately.  When costwish is fully installed, it removes much of the
difficulty that newcomers find when running SGML parsers usch as sgmls.  

The file DIRECTORIES gives you an indication of the directory structure
required for a costwish implementation.


SGML parser
-----------

You need an SGML 'parser' which can:

	- use the SGML open catalog system, and manage several catalogs if
		necessary.
	- output the parsed document as an ESIS stream.

(Note that many exisitng SGML tools do not have an explicit parsing stage
since it is inimately combined with the rendering or transformation, and 
most do not output an ESIS stream.  Nor do some support the open catalog.)

I strongly recommend the use of sgmls V1.1.91. from J. Clark.  This is freely
available from his site and many mirrors, and is available on all platforms.
You may also wish to use his later software (nsgmls) which has the required
functionality and much more - I have no personal knowledge of it.

Note that the man pages for sgmls (sgmls.txt) are comprehensive but can
cause newcomers to SGML difficulty, especially since HOW to run it can be
machine-dependent.  sgmls can give 230 error messages, which - though quite 
correct - use unfamiliar terminology.  (costwish has an explanation of some 
of the commonest!).  We therefore supply some simple examples for you to
test parsing with.

Step 1.
.......

Obtain (or compile) and executable of sgmls - it must be version 1.1.91 to 
support the open catalog.  You *may* already have it on your system (e.g.
if you have Linux); try typing:
	sgmls -v
to see the version.  If not, download the version appropriate to your machine;
see INSTALL.cost for details.

Step 2.
.......

Make sure it works.  Start simply with a very simply file in the demos 
directory, simple1.sgm.  Go there and type:
    sgmls simple1.sgm
If this fails, something's seriously wrong; if not, progress through 
simple2.sgm to simple4.sgm.  For simple4.sgm, you'll need to know where your
catalog file is and html20.dtd.  They should both be in:
    $HOME/costwish/dtd
or something similar.  By the time you've finished that, you'll realise
that many SGMLS errors arise simply because the directories aren't yet
right.  I can't make it much easier, I'm afraid!
that the main problem is making sure that sgmls

Costwish
--------

costwish operates on the ESIS files - you'll find some in the demos/ directory.
You can therefore test costwish independently of sgmls.  

To run costwish you will need:
    (a) a costwish executable for your machine (costwishexe).  (In early 
	versions this was called costwish; apologies if confusion still 
	remains).
    (b) to setup a few environment variables (in setup.csh)
    (c) to make sure you have *.tcl files in your cw/ directory.

There are two ways of getting costwish:

(A) Download costwish executable for your machine.  This is by far the easiest
way of getting started if it's appropriate.

(B) Compile the system from the source code.  The components are:
	- tcl/tk
	- blt
	- tix
	- cost
    The first three compile 'out of the box' using the GNU autoconfigure script
(see Joe's notes - INSTALL.cost - as well).  CoST itself should be 
straightforward (I have compiled it on 4 architectures).  Note that the
CoST distribution allows for itcl (the OO version of tcl to be used, but
I have not used itcl since  there was a time when there was problems linking
it with all the components.  Feel free to experiment now, if you want.  Note 
also that CoST is NOT compatible with tcl7.5* or tk4.1*; I'm sure this will
be resolved, but until then use tcl7.4 and tk4.0.  The components are then 
linked to give a single executable, costwishexe.

costwish is a superset of tcl, tk, cost, blt and tix.  It therefore behaves
like a wish interpreter and you should just type:
	costwishexe
If everything is OK, you'll get a little window (about 200x200) called 
'costwishexe' and a prompt (%).  Possible problems at this stage are:
	- failure to find the TCL_LIBRARY, TK_LIBRARY, TIX_LIBRARY, or
		COSTLIB *.tcl files.  These should be in costwish/lib and
		are set with the environment variables (see setup.csh)
	- X window problems (make sure that you X environment is OK by (say)
		typing 'xclock')

costwish scripts
----------------

You should execute setup.csh ('source setup.csh', or whatever your shell
requires).  You should now be able to run costwish:
    costwishexe $CWDIR/cw.tcl
This should bring up a large grey window with several panes (cw.tcl) and 
write a smallish log to the text window.  (It's useful to keep this text window 
in view as it sometimes has useful info).

Customisation
-------------

You *may* need to customise your installation:

(a) cw/costwishini.tcl:		This file allows you to customise your SGMLS
	environment and also add helper applications.  It should work 
	'out of the box', but if not you may have to do some inspired
	tweaking here.

(b) cw.customisation.tcl:	This allows you to add in routines for your
	own DTDs.  Here you are just setting pointers to the directories
	(user/*) - should be clear enough.

(Even if you don't know any tcl you should be able to grok these files by
analogy :-)

(c) user/mydtd/*.tcl:	This is where you can customise your own DTD.  I'm
	afraid there is no developer's documentation yet :-), so you'll
	have to work by analogy.  Basically you can write simple routines
	for as many GIs as you want, with routines like:
		MYGI::displayNode
	in user/mydtd/postproc.tcl
	The routines in user/play should give you a good idea.
	(Of course you may want to keep the routines elsewhere - just tweak
	cw/customisation.tcl to point to them).


Multiple catalogs
-----------------

If you are needing to search several catalogs (e.g. in a complex DTD), sgmls
gives two methods:
    (a) SGML_CATALOG_FILES:	Setting this environment variable to a list
	of catalogs will search them in order.  Try:
		setenv SGML_CATALOG_FILES "dir1/catalog1:dir2/catalog2"
	and so on.  You can amend as many as you like.  (I initially used this
	in costwish, but changed to the next method...)

    (b) command-line (-m catalogname):  Any number of catalog files can be
	concatenated on the command line, e.g.:
		sgmls -m dir1/catalog1 dir2/catalog2 mydoc.sgm
	costwish uses this and allows you to set up a list of catalogs
	in $COSTWISHDTD/cwcatalogs.  Note that this is NOT standard SGML,
	although it follows similar conventions.
	
SGML problems in costwish
-------------------------

As far as I know the SGML declaration has to go on the command line.  This
is a pain to organise in costwish and I may have to provide a selection
mechanism.

sgmls resolves relative directory names in the catalog but NOT in document
instances.  This means that for some SGML documents (e.g. Joe's 
docs/cost/manual.doc) sgmls (and therefore costwish) MUST be run in the
directory the files as in.  This can be obviated through SGML_PATH but
this is a really hairy format and the man pages sgmls.txt - though precise -
are opaque to most humans.  

sgmls errors.  sgmls gives copious error messages, which I've tried to trap.
They are meaningless to newcomers to SGML and I've tried to give a simple
interactive analysis.


