chiark - git - mdw - ssr/blob - StraySrc/SapphToys/!SWIlist/!Help

   1                        __          ___
   2                       (__  |     |  |  |     '  __ _|__
   3                          \ |  |  |  |  |     | (__  |
   4                       ___/ \__|__/ _|_ |____ ( ___) (__
   5
   6
   7                       ©   1 9 9 5   S t r a y l i g h t
   8
   9 _____________________________________________________________________________
  10
  11
  12                                 ABOUT SWILIST
  13
  14         If you use C or the objasm assembler, and you need to use SWIs, then
  15         you'll probably want to have a file defining names for all the SWIs
  16         you'll be using, which you can include in any files which need it.
  17         SWIList is a small program designed to generate such files.
  18
  19         There are lots of programs which do this job, although SWIList
  20         provides several important features which the others don't:
  21
  22           * It's language independent.  So you can use the same program to
  23             generate SWI files for C, assembler, or any other language you
  24             need.  All you have to do is describe the language to SWIList.
  25
  26           * It doesn't just scan the modules in memory.  You can drop module
  27             files onto SWIList's icon in order to add their SWIs to the list.
  28             SWIList also keeps a file of all the names so far, which you can
  29             save, so you can add new modules easily when you obtain (or
  30             write) them.
  31
  32 _____________________________________________________________________________
  33
  34
  35                                RUNNING SWILIST
  36
  37 Introduction
  38
  39         SWIList runs when you double-click its icon in a Filer window.  It
  40         will add its icon to the icon bar in the traditional way.  If you
  41         haven't yet saved a SWI dump (see below), SWIList will take a little
  42         while to read in all the modules currently loaded.
  43
  44
  45 The main menu
  46
  47         If you click /menu/ on the SWIList icon, the main menu will be
  48         opened, from which you can choose the following options:
  49
  50         Info            Displays a dialogue box showing information about the
  51                         SWIList application, including the version number,
  52                         which you should note with any bug reports.
  53
  54         Save list       Displays a submenu of languages.  Choosing one of
  55                         the items from this submenu opens a dialogue box
  56                         which will let you save a SWI list file in the
  57                         appropriate language.
  58
  59
  60         Save dump       Displays a dialogue box which lets you save the
  61                         `SWI dump' -- a file containing all the SWI names
  62                         currently in memory.  More information about SWI
  63                         dumps is given below.
  64
  65         Rescan modules  Discards all the SWI names currently in memory and
  66                         rescans the loaded modules.  This can take a short
  67                         while.
  68
  69         Quit            Removes the SWIList application from memory.
  70
  71
  72 SWI dumps
  73
  74         A *SWI dump* contains information about SWI names and numbers.  It's
  75         a binary file, not intended for `user consumption'.  SWIList will
  76         attempt to load the file `SWIdump' from its application directory
  77         when it starts up; if it can't find this then it will scan the
  78         modules in memory.  This feature allows you to add to the SWIs
  79         currently recognised when new modules come along, rather than having
  80         to redo the whole lot from scratch.
  81
  82
  83 Format files
  84
  85         In order to make SWIList language independent, all the information
  86         about specific languages is contained in a file called `Format'
  87         in SWIList's application directory.  You can alter the existing
  88         formats, or ad your own for languages which aren't already supported
  89         (e.g. Pascal).
  90
  91         The file's layout is fairly straightforward.  The description of
  92         how to format each language is held in a `chunk', headed by the
  93         name of the language in square brackets (`[', `]').  (Actually, this
  94         isn't quite true -- the thing in the brackets is the menu item text,
  95         so we've followed it with `...' because the item leads to a dialogue
  96         box.)
  97
  98         SWIList's output files are structured, and the format description
  99         echoes this.  At the top of an output file is a header.  Then, for
 100         each SWI-providing module, there is a header line, and this is
 101         followed by a piece of text for each individual SWI.  Finally, the
 102         file is finished off with a footer.
 103
 104         The format for a language is divided into four sections, separated
 105         by `%%'s:
 106
 107          1. The header text for the output.  This is where you'd set up any
 108             macros needed, and ensure that the file is only included once,
 109             if this is required.
 110
 111          2. The header line (or lines) for each module.  This is usually
 112             just a comment.
 113
 114          3. The text to define each individual SWI.  Don't forget to define
 115             the `X' versions of the SWIs here.
 116
 117          4. The footer text for the output file.
 118
 119         The text within each section can contain *format specifiers*, which
 120         are replaced with appropriate text while the file is being written.
 121         A format specifier begins with a `%' character.  The replacement text
 122         is determined by the next character:
 123
 124         `%m'    Replaced by the name of the module whose SWIs are being
 125                 written.  This is usually used in the module separator lines.
 126
 127         `%s'    Replaced by the name of the SWI currently being defined.
 128                 This is intended to be used when defining the individual
 129                 SWIs.
 130
 131         `%n'    Replaced by the number of the SWI currently being defined.
 132                 The number is written in hex, so be sure to include the
 133                 appropriate specifier for the language (e.g. `&' in assembler
 134                 or `0x' in C).
 135
 136         `%x'    Replaced by the number of the `X' version of the SWI being
 137                 defined, also in hex.
 138
 139         `%p'    Replaced by a `%' character, just in case you need one.
 140
 141         `%d'    Replaced by the current date and time.  The default format
 142                 of the date is determined by an entry in SWIList's `Messages'
 143                 file, although you can supply your own by placing it in
 144                 square brackets immediately after the `%d'.  The syntax of
 145                 date formats is as described for the Alarm application,
 146                 and the SWI OS_ConvertDateAndTime.
 147
 148         For an example, which should help make everything clear, see the
 149         `Format' file supplied.
 150
 151
 152 Choices
 153
 154         The Risc PC boot system sets up a system variable `Choices$Path'
 155         which allows applications to find configuration files kept separately
 156         from the application directory.  If you have a Risc PC, or have set
 157         up the `Choices$Path' variable, SWIList will search for the `Format'
 158         and `SWIDump' files there before it looks in its application
 159         directory.
 160
 161 _____________________________________________________________________________
 162
 163
 164                                TECHNICAL THINGS
 165
 166         SWIList was written entirely in ARM Assembler.  It gobbles large
 167         amounts of memory because it's using the Sapphire library which is
 168         completely excessive for SWIList's fairly modest needs.  Some of the
 169         more advanced features of SWIList would have been difficult to
 170         implement without Sapphire however, and I doubt that I could have
 171         been bothered.  For example:
 172
 173           * RAM transfer support, for both loading and saving (including
 174             formatted SWI list files).
 175
 176           * The format file support.
 177
 178           * The dynamic menu of formats.
 179
 180           * All the little luxuries like pointer changing and DragASprite
 181             support (including the icon being hidden when it's dragged).
 182
 183         So there!
 184
 185         The SWIList source code uses the BASIC assembler and Straylight's
 186         BASIC Assembler Supplement (BAS), which allows AOF object files
 187         to be generated from BASIC; the object was then linked to the
 188         Sapphire library.  Sapphire was however written using Acorn's objasm
 189         assembler, which was a considerably more pleasant experience.
 190
 191 _____________________________________________________________________________