- What is costwish? What would I use it for?
costwish is a combination of a GUI with Joe English's CoST tool
for processing SGML documents. It lets you read any SGML document and tailor
the display to the type of document. It is particularly suitable for
rendering complex documents with textual and non-textual data combined.
By adding simple code it is possible to process specialised data such
as graphs, tables, molecules, etc.
It is intended for use by people who have no knowledge of SGML. This is a
tough challenge, since SGML has an unusual terminology and many
idiosyncrasies. It's also not easy to set up some SGML systems. I hope that
the tutorials, the help files, the examples and the graphical displays will
go some way to making SGML more widely known and easier to use.
It is also intended as a tool for complex document types, especially with
non-textual as well as textual content. It has been developed with
molecular sciences in mind, but is independent of application.
- What is SGML? Is it like HTML?
SGML is a standard (a "meta-language") for writing markup languages, the
best known of these being HTML. (HTML is said to be "an application of SGML",
or "a DTD of SGML".) SGML (with the related language HyTime, and the
style sheet standard DSSSL) is widely promoted as the natural system to use
for documents more complex than HTML can cope with. Many publishers are
turning to SGML for authoring, editing and producing books and journals,
and it is also used as an instrument of business where precise exchange of
information is required.
SGML is very powerful and for that reason can take a long time to learn
completely. I hope that costwish can help people to get started on this
in a simple and fruitful manner.
(Strictly conforming HTML documents - not very common, unfortunately :-( -
are good examples of SGML documents that costwish can read and process. Some
examples are included in the distribution.
- Where do I get costwish and how do I install it?
You will
either need to download an executable for your machine, or compile it (using
tcl/tk, Tix, and CoST). costwish consists of this executable and a number
of generic tcl/tk scripts for displaying, querying and processing documents.
All the components of the full costwish system are free.
You will also need an SGML parser - sgmls is recommended.
- Will it run on my machine?
costwish has been developed in the tcl/tk system, which at present only runs
on X windows systems (on UNIX machines). (tcl/tk is being ported to PCs and
MACs by Sun Microsystems and should be available later this year.)
- I can't get costwish to work
Processing a document with costwish involves many steps (though when fully
working costwish should protect you from worrying about them).
The installation instructions take you through the
steps in a modular manner. This should let you know where you are having
problems. If that doesn't help, mail me. I'll answer :-)
- It works, but what should I do now?
If you don't know any SGML, you are strongly advised to try the tutorial and read the example files and documentation. This will give you an idea of how costwish looks when it's working.
If you already have documents with a DTD, you should add your DTD's FPI to the catalog and try running costwish on your document. If it fails, check whether it parses under SGMLS (see installation instructions). If is doesn't parse, something is probably wrong with your document. costwish might help you understand the error messages. If it does parse under sgmls, then either costwish is picking up the environment wrong
(check that the sgmls instruction from costwish output on the log actually works) or there is a bug in costwish. Let me know.
- Why are there so many windows?
A document can have many thousand nodes (e.g. Julius Caesar) and you could be interested in several simultaneously. It's possible that you might want (say) the Dramatis Personae, the TOC, two or three scenes, the results of some searches, a list of the SCENE titles, etc. and it soon mounts up. Initially I had 1 window per node, but am developing compound panes and other methods; soon I hope to have a folder of recently visited nodes - it's very like HTML browsing!
- Can I use it with my DTD? or document?
Almost certainly yes. sgmls caters for a very large number of SGML options. (Options like LINK, RANK, CONCUR are very infrequently used and I don't recommend them for beginners.) CoST is slightly less comprehensive and I think doesn't cater well for SUBDOC. If you have a DTD with SUBDOC, I'm afraid you'll have to ask JOE.
- Why isn't SGML as simple as HTML?
Firstly it was developed when many documents were hand-authored and so a lot of keyboard short-cuts were introduced (e.g. <TAG>a tag</> is the SHORTTAG shortcut.) Unfortunately these can't be regulated without the SGML declaration which (for many beginners, including myself) has little function other than to introduce a rich source of errors and confusion. In principle it allows other markup syntax (e.g. (TAG)...(?TAG)) but you would be foolish to follow this without good reason.
Secondly, many documents are complex. SGML caters for documents split over many files (using entities) and for conditional parsing (marked sections). It also allows document validation (e.g. the type of an attribute, correctness of links (ID->IDREF), etc.) HTML is too weak to support highly structured, complex documents.
- I keep getting error messages
Yes :-(. So did/do I. Unfortunately, even for simple documents 4 files may be required (catalog, DTD, declaration and document instance). It's easy to omit one or use the wrong one and then you get errors. The benefit is that *when* you get it set up OK under costwish it then runs very easily. Of course you may make errors as well. There is fairly large
list of common SGMLS errors.
- What can costwish do?
costwish can parse and render any SGML document. If nothing is known about the semantics of the document (e.g. <FOO>xyzzy<BAR>plugh</BAR></FOO>.) then all costwish can do is echo the input in various ways. However, it's easy to write a postprocessor and costwish has been used for several major documents:
- What is the future of costwish?
costwish has been primarily developed for non-textual applications and for rendering documents rather than typesetting or managament of large documentation systems. It's intended to be extensible and I'd be delighted to get offers. Examples would be:
- customisation of particular DTDs.
- addition to the core (e.g. more general search facilities).
- generic postprocessing routines.
- indexing and other document management.
I shall continue to develop the core gently but the primary push will be on molecular applications and the development of hyperglossaries.
I'm looking (a) to port costwish to PC and Mac using the tcl/tk ports; (b) to convert using other technology - can't say more at present.
- Can I edit costwish?
costwish is freely available but protected by copyright.
You may add additional code for your own purposes so long as it is separated from the core (e.g. in separate directories), and you are free to distribute this.
You may edit the core distribution for your own purposes but may not redistribute those edits - this restriction is to prevent mutant versions (I've learnt this from experience). By this I hope to produce a core which does not required editing and which can be personally customised.
- Can I use it in commercial applications?
Not if you charge money for it. You may distribute it in a commercial package so long as it is identical with the distributed version and all the credits and documentation is included.
- What doesn't costwish do?
costwish is not (and probably won't be) an authoring tool, though it looks attractive. (Creating a DTD-compatible document interactively is non-trivial).
It isn't a parser, nor is it a WWW browser, nor a typesetting tool though it could well be integrated into the latter applications.