                       __          ___
                      (__  |     |  |  |     '  __ _|__
                         \ |  |  |  |  |     | (__  |
                      ___/ \__|__/ _|_ |____ ( ___) (__


                         1 9 9 5   S t r a y l i g h t

_____________________________________________________________________________


                                ABOUT SWILIST

	If you use C or the objasm assembler, and you need to use SWIs, then
	you'll probably want to have a file defining names for all the SWIs
	you'll be using, which you can include in any files which need it.
	SWIList is a small program designed to generate such files.

	There are lots of programs which do this job, although SWIList
	provides several important features which the others don't:

	  * It's language independent.  So you can use the same program to
	    generate SWI files for C, assembler, or any other language you
	    need.  All you have to do is describe the language to SWIList.

	  * It doesn't just scan the modules in memory.  You can drop module
	    files onto SWIList's icon in order to add their SWIs to the list.
	    SWIList also keeps a file of all the names so far, which you can
	    save, so you can add new modules easily when you obtain (or
	    write) them.

_____________________________________________________________________________


                               RUNNING SWILIST

Introduction

	SWIList runs when you double-click its icon in a Filer window.  It
	will add its icon to the icon bar in the traditional way.  If you
	haven't yet saved a SWI dump (see below), SWIList will take a little
	while to read in all the modules currently loaded.


The main menu

	If you click /menu/ on the SWIList icon, the main menu will be
	opened, from which you can choose the following options:

	Info		Displays a dialogue box showing information about the
			SWIList application, including the version number,
			which you should note with any bug reports.

	Save list  	Displays a submenu of languages.  Choosing one of
			the items from this submenu opens a dialogue box
			which will let you save a SWI list file in the
			appropriate language.


	Save dump	Displays a dialogue box which lets you save the
			`SWI dump' -- a file containing all the SWI names
			currently in memory.  More information about SWI
			dumps is given below.

	Rescan modules	Discards all the SWI names currently in memory and
			rescans the loaded modules.  This can take a short
			while.

	Quit		Removes the SWIList application from memory.


SWI dumps

	A *SWI dump* contains information about SWI names and numbers.  It's
	a binary file, not intended for `user consumption'.  SWIList will
	attempt to load the file `SWIdump' from its application directory
	when it starts up; if it can't find this then it will scan the
	modules in memory.  This feature allows you to add to the SWIs
	currently recognised when new modules come along, rather than having
	to redo the whole lot from scratch.


Format files

	In order to make SWIList language independent, all the information
	about specific languages is contained in a file called `Format'
	in SWIList's application directory.  You can alter the existing
	formats, or ad your own for languages which aren't already supported
	(e.g. Pascal).

	The file's layout is fairly straightforward.  The description of
	how to format each language is held in a `chunk', headed by the
	name of the language in square brackets (`[', `]').  (Actually,	this
	isn't quite true -- the thing in the brackets is the menu item text,
	so we've followed it with `...' because the item leads to a dialogue
	box.)

	SWIList's output files are structured, and the format description
	echoes this.  At the top of an output file is a header.  Then, for
	each SWI-providing module, there is a header line, and this is
	followed by a piece of text for each individual SWI.  Finally, the
	file is finished off with a footer.

	The format for a language is divided into four sections, separated
	by `%%'s:

	 1. The header text for the output.  This is where you'd set up any
	    macros needed, and ensure that the file is only included once,
	    if this is required.

	 2. The header line (or lines) for each module.  This is usually
	    just a comment.

	 3. The text to define each individual SWI.  Don't forget to define
	    the `X' versions of the SWIs here.

	 4. The footer text for the output file.

	The text within each section can contain *format specifiers*, which
	are replaced with appropriate text while the file is being written.
	A format specifier begins with a `%' character.  The replacement text
	is determined by the next character:

	`%m'	Replaced by the name of the module whose SWIs are being
		written.  This is usually used in the module separator lines.

	`%s'	Replaced by the name of the SWI currently being defined.
		This is intended to be used when defining the individual
		SWIs.

	`%n'	Replaced by the number of the SWI currently being defined.
		The number is written in hex, so be sure to include the
		appropriate specifier for the language (e.g. `&' in assembler
		or `0x' in C).

	`%x'	Replaced by the number of the `X' version of the SWI being
		defined, also in hex.

	`%p'	Replaced by a `%' character, just in case you need one.

	`%d'	Replaced by the current date and time.  The default format
		of the date is determined by an entry in SWIList's `Messages'
		file, although you can supply your own by placing it in
		square brackets immediately after the `%d'.  The syntax of
		date formats is as described for the Alarm application,
		and the SWI OS_ConvertDateAndTime.

	For an example, which should help make everything clear, see the
	`Format' file supplied.


Choices

	The Risc PC boot system sets up a system variable `Choices$Path'
	which allows applications to find configuration files kept separately
	from the application directory.  If you have a Risc PC, or have set
	up the `Choices$Path' variable, SWIList will search for the `Format'
	and `SWIDump' files there before it looks in its application
	directory.

_____________________________________________________________________________


                               TECHNICAL THINGS

	SWIList was written entirely in ARM Assembler.  It gobbles large
	amounts of memory because it's using the Sapphire library which is
	completely excessive for SWIList's fairly modest needs.  Some of the
	more advanced features of SWIList would have been difficult to
	implement without Sapphire however, and I doubt that I could have
	been bothered.  For example:

	  * RAM transfer support, for both loading and saving (including
	    formatted SWI list files).

	  * The format file support.

	  * The dynamic menu of formats.

	  * All the little luxuries like pointer changing and DragASprite
	    support (including the icon being hidden when it's dragged).

	So there!

	The SWIList source code uses the BASIC assembler and Straylight's
	BASIC Assembler Supplement (BAS), which allows AOF object files
	to be generated from BASIC; the object was then linked to the
	Sapphire library.  Sapphire was however written using Acorn's objasm
	assembler, which was a considerably more pleasant experience.

_____________________________________________________________________________
