RUNSP2: a user-friendly Windows shell for NSGMLS
================================================

Purpose
=======

RUNSP2 is designed to let you run the NSGMLS parser in a
Windows environment.  It provides standard Windows
facilities for opening a file to be parsed and running the
parser, but goes beyond that by 'reading' the error
messages, and providing a helpful editing environment in
which the user can correct the errors found.

The original idea was to support all the command-line
options of NSGMLS via menu options or a dialog box, and I
will go on to do this if the basic idea works well enough to
justify the effort.

At present this program just runs the parser (NSGMLS) and
the simple normalizer (SGMLNORM).  Later, I may extend it to
run all the programs in the SP suite.

This program is heavily dependent on the user having the
latest version of NSGMLS (V1.1 for Windows 3.1; V1.1.1 for
Windows 95). Note that this is a potential weakness in the
approach: if James Clark changes the message format in
future releases of NSGMLS, my program will need to track
these changes or die!

Compatibility
=============

I have developed this program to work with the messages
produced by the latest version of NSGMLS (SP1_1 or SP1_1_1
release), and one tester has already found that it will not
work with earlier versions.  You can (should!) download the
latest version from James Clark's site.  It has
run successfully under both Windows 3.1 and Windows 95,
although there is no particular support for Win 95's long
filenames.

Installation
============

The file RUNSP2.ZIP contains the program RUNSP2.EXE.  If you
unzip the file and copy RUNSP2.EXE to the directory in which
you have installed NSGMLS.EXE, it should then 'find' NSGMLS
when asked to do so.  (Note that you can choose to install
it elsewhere, and then tell RUNSP2 where to find the
parser.)

You will have to set up your own short-cut or icon for this
program. (I may get around to providing a proper
installation procedure if it transpires that more than one
person wants to use it!)

'Warranty' and Usage Conditions
===============================

I offer no guarantees that RUNSP2 will work, and accept no
responsibility for any damage caused.  (Having said that, I
don't foresee any problems worse than having it fail to work
for you.)

RUNSP2 is being made available on the understanding that it
is at an early stage of testing and should not be passed on
to unwary third parties without a suitable health warning. 
I hope that you will report all problems and lacunae to me,
and in return I will do my best to sort them out and post
updated versions of the software at this site.

Operation
=========

RUNSP2 lets you open the file you want to check/parse, and
puts it into an editor window.  You can do this either by
the File - Open menu option, or by dragging the file's icon
onto the program window or icon.

If you then press the 'run parser' button (or <F9>), a
little batch file runs the parser in a separate window. 
Alternatively, there is an 'Auto-run parser' toggle in the
Options menu.  If this option is checked (before you open a
file!), RUNSP2 will run the parser immediately.

I have provided a .PIF file for Windows 3.1 which causes
this window (a) not to take up the whole screen and (b) to
close itself when its job is done. If running it under Win
95 you can edit the properties of the DOS window so that it
behaves itself in a similar manner.  You should only have
to do this once.

When the parser has finished running, RUNSP2 analyses the
log file it has produced, and loads all the files containing
errors.  (Yes, this includes files from your DTD if it is
faulty!)  It then places the cursor at the position of the
first error, and displays the error message in a box at the
bottom of the screen.  There are buttons to let you move
through the errors (first, next, previous, last error). 
Each time you are placed at an error, you can use the
editing facilities to correct it straight away.  If you run
the parser again after making some corrections, all your
edits are automatically saved first.

If there are no errors, it tells you so, and an extra button
appears which runs the normalizer program SGMLNORM on the
current document.

The editor used should have sufficient capacity to deal with
large files (16MB in theory: over 1MB, anyway) and with very
long lines (up to 32767 characters).  (The second aspect is
important: some SGML utilities output byte streams with very
few carriage returns.  If there are none, the editor will
effectively have a file size limit of 32K.)

The editor uses standard Windows conventions: I haven't
spent any time investigating or documenting it.  It does its
work with the NSGMLS error messages by a combination of
bookmarks (which should stay in the right place when you
edit the text) and word wrap (without which you might never
see many of the errors!).

Note that the error message itself is actually contained in
a read-only 'memo' window, which means that you can
highlight and copy phrases from it to your document via the
clipboard (Ctrl-Ins to copy; Shift-Ins to paste).  This is
particularly useful where the error message contains a list
of legal values (element names or attribute values).

The Options menu item includes the possibility of setting
the SGML Declaration and SGML Catalog files: once you have
done this, the program remembers these settings and you
shouldn't have to do it again unless you have multiple
declarations or catalogs for different purposes.  You
will need a catalog file if there are any PUBLIC identifiers
in the files you want to parse.

Known 'funnies'
===============

One thing you need to watch is that the cursor isn't always
visible when moving to an error.  This can usually be
cured either by scrolling down a few lines and back, by
moving to the next error and then back, or in extremis by
minimizing the window and then restoring it to full size.

It is quite possible that you will get error messages which
are not dealt with sensibly.  Please report these to me and
I will try to cope with them.  Remember that some messages
do not give a filename, or do not give a specific position
within a file: I clearly cannot point to the relevant part
of the source in such cases!

At present, the editor used doesn't deal correctly with
files that use Line Feed only as their 'record end' symbol.

RUNSP2 doesn't yet cope nicely with more than one 'main
file'.

Let me know how you get on!

Updates
=======

4 September 1997
================

Improvement:

   * the File-Open dialog now has a history list (horribly
displayed!) of up to 20 recently opened files.  Also, this
dialog now remembers (within each invocation of the program)
the directory and file suffix you used last time, and uses
them as a starting point for subsequent file selections
   * the auto-run option setting is now being remembered
between invocations of the program


Bug fixes:

   * the program did not respond correctly if a file was
dragged onto its icon.  It now loads that file and runs the
parser straight away
   * the auto-run option setting is now being remembered
between invocations of the program

1 July 1997
===========

Bug fixes:

   *  the error messages were not being displayed when the
[first] error was not in the main file being checked
   * when running the normalizer, you always got the "save
as" dialogue, followed by an error because the file already
exists!

While I was at it, I have changed the logfile suffix to
'LG$' to try to avoid name clashes.

I have also added an option so that you can have the whole
log file in its own child window.  (This is useful for
tracking messages that can't be linked to a specific point
in the source, and for working out why RUNSP has failed to
interpret the log correctly!)

Richard Light, last updated 4 September 1997