/------------------------------\
|            SFSkyEdit         |
| Star Fighter 3000 sky editor |
|   Christopher Bazley, 2001  |
|  Version 1.69 (02 Aug 2022)  |
\------------------------------/
N.B. This text is best viewed at a display width of 77 columns.

-----------------------------------------------------------------------------
1   Introduction and Purpose
    ========================

  SFSkyEdit is an interactive editor for 'Star Fighter 3000' sky files.

  A SFSkyCol file (in '!Star3000.Landscapes.Sky') contains the colours used
to paint a particular type of planetary atmosphere (e.g. sunset, morning,
night, gas clouds etc). This application allows you to edit these colours or
define new skies.

-----------------------------------------------------------------------------
2   Requirements
    ============

   RISC OS 3.10 or better.
   The so-called 'nested Wimp' (softloadable as part of Acorn's universal
    !Boot application).
   A !System directory (which must have been 'seen' by the Filer).
   The Toolbox modules (in !System or in ROM with RISC OS 3.6 and later).

  If any of the above facilities are unavailable then the program will fail
to load, with an error message describing the problem.

  Not essential, but desirable:

   The DragAnObject module (standard with RISC OS 3.5 and later).
   A modern version of the Window Manager which supports auto-scrolling
    (i.e. RISC OS 4 or later).

-----------------------------------------------------------------------------
3   Quick Guide
    ===========

  Load the SFSkyEdit application. Open your '!Star3000' game directory and
locate the sub directory 'Sky' in 'Landscapes' or 'Disc2.Landscapes'. Drag a
file from this directory to the SFSkyEdit icon on the icon bar, and an
editing window will open. (If you choose 'Earth' or 'Earth2' you may get a
warning message. This is nothing to worry about.)

  Within the editing window will be a stack of 63 coloured rectangles. These
represent the colour bands currently in the file. There will be a red bar
below the bottom-most colour band. This is the caret.

  Click SELECT to position the caret or drag SELECT to make a selection.
Click or drag ADJUST to change the extent of a selection.

  Selected bands are highlighted with a border and the colour number (0-255)
assigned to that band. To deselect all selected bands, press Ctrl-Z or click
SELECT outside the selected area. The caret and selection are mutually
exclusive (i.e. only one may exist at a time).

  To change the colour of all selected bands, press Ctrl-E and choose a
colour from the palette. The same dialogue box can be opened from the menu as
'Effect'> 'Set colour'. To move selected bands drag SELECT from within the
selection, or Shift-drag to copy. Position the bands at their destination
using the ghost (green) caret.

  There are two quick ways to create a high quality sky file:

1) Insert consecutive areas of plain colour ('Edit' > 'Insert bands...'),
   select all the new areas plus some black, and smooth the finished product
   ('Effect' > 'Smooth transitions').

2) Insert consecutive gradated fills, with the final one fading to black.

  Which method you use is a matter of personal preference, but they are
largely incompatible since you cannot successfully apply smoothing to
gradated fills.

  Finally, to see the results of your handiwork in real time, press F7 or
choose 'Utilities' > 'Preview...' from the menu.

-----------------------------------------------------------------------------
4   Jargon
    ======

  "Colour band" - the building blocks of a sky file that are represented as
coloured rectangles in the editing window. There are 63 bands in a file,
each of which may be any colour of the standard mode 13 palette.

  "Pattern" - actual pixel data that will be plotted to the screen by the sky
renderer. There are 126 patterns in a file, each consisting of a 4 pixels.
Patterns are not directly editable by SFSkyEdit; you need to use SFToSpr for
that.

  "Caret" - as in a text editor, this is a positionable marker at which data
may be inserted, and from where selections may be made. In SFSkyEdit the
caret looks like a horizontal bar with uprights at either end. It is
normally red, but turns grey when the editing window loses the input focus.

  "Ghost caret" - this is a green bar that follows the mouse pointer during
a drag operation, and shows where the bands being dragged would be inserted
if dropped.

  "Clipboard" - an invisible area of temporary storage that is used when
copying or moving colour bands. SFSkyEdit uses the global clipboard, which
means that it is shared between all applications.

-----------------------------------------------------------------------------
5   Editing model
    =============

  The editing model used by SFSkyEdit is not strictly speaking appropriate,
but I have adopted it to make the application easier to use.

  Within this manual you will find many references to 'insertion' and
'removal' of colour bands, implying that a sky file is (like this text file)
a sequence of data of arbitrary length. In fact, a sky file is of finite
length (63 colour bands) and cannot be extended.

  This means that inevitably whenever bands are 'inserted' some bands are
pushed off the top. This is very unlikely to be a problem, however, as there
is loads of space in a file (no Fednet sky goes above band 35). All the
bands at the top are likely to be either black or rubbish that you forgot to
delete.

-----------------------------------------------------------------------------
6   Data input and output
    =====================

  SFSkyEdit will load files of type 'SFSkyCol' (&404) that are double-
clicked in a directory display. It also loads files of this type that are
dropped on its icon bar icon or editing windows. If a file that was double-
clicked or dragged to the icon bar is already open for editing then the
corresponding window will be brought to the front of the stack.

  Files are verified for consistency upon loading. Certain of the original
files do not strictly conform to the standard editing model (see 10.2 'Sky
file format'), which is reported via a warning dialogue box. In practice
this is nothing to worry about. To disable such warnings for the remainder of
a session, click on the 'Disable warning' button in the dialogue box.

  Arbitrary-length sequences of colour numbers are represented by files of
type 'CSV' (&DFE). 'Comma-separated values' is a delimited ASCII data format
where fields are separated by the comma character and records are separated
by carriage return and/or linefeed. Selected colour bands are exported in
this format when dragged directly to a directory display or another
application, and SFSkyEdit will load CSV files dropped on its icon or editing
windows.

  When importing CSV data, SFSkyEdit evaluates each field of the first
record as a decimal value and reports an error if any of these values are
not valid colour numbers. Subsequent records are ignored. The colours from
the CSV file will be inserted in the destination window at the caret (or
replacing any selection that may exist).

-----------------------------------------------------------------------------
7   The icon bar
    ============

7.1 Icon bar icon
    -------------
  Click SELECT to create a new sky file. All colour bands will be
initialised as black, and the render offset and stars start height will be 0.

  Click ADJUST to bring all open windows to the front, e.g. in case they are
hidden behind other windows open on the desktop.

  Click MENU to open the icon bar menu (see 7.2).

7.2 Icon bar menu
    -------------
'Info'

  Leads to a standard 'About this program' window.

'Help...'

  Opens this user manual with whatever application claims the Text filetype.

'Options'

  This submenu allows you to configure aspects of the behaviour of the
application, by clicking on menu items to toggle whether the corresponding
option is on or off (see 7.3).

'Views'

  This submenu lists lists all open editing windows. Click SELECT or ADJUST
on a submenu item to bring the corresponding window to the front of the
window stack.

'Quit'

  Before quitting, SFSkyEdit will check whether any of the files being edited
have unsaved changes. If so then you will be prompted to confirm that you
wish to discard such changes.

7.3 Options menu
    ------------
'Options' > 'Dither warning'

  If switched on, a warning dialogue box will be displayed upon loading a sky
colours file which doesn't conform to the standard dithering rules. This
option is enabled by default unless the switch '-nowarn' is appended to the
command line in the application's !Run file.

'Options' > 'Trap caret'

  If switched on, the caret will be kept within the visible area when
scrolling an editing window. This option is enabled by default unless the
switch '-notrap' is appended to the command line in the application's !Run
file.

-----------------------------------------------------------------------------
8   Main editing window
    ===================

8.1 Sky colours display
    -------------------
  The main section of the editing window is occupied by a vertical stack of
coloured rectangles. These are the 'colour bands', of which there are 63 in a
sky file. Selected bands are highlighted with a border and the colour number
(0 to 255) assigned to that band.

  The caret looks like a red horizontal bar with uprights at both ends. When
a file is first opened it appears below band 0, but may be moved up and down
using the arrow keys and Home/End. When it reaches the top or bottom edge of
the window the view will scroll automatically in that direction. Use of the
caret is described further in the next section of the manual.

  When you scroll the editing window the caret may automatically be moved
so that it remains within the visible area (this behaviour is configurable
using the 'Trap caret' menu option). The Page Up and Page Down keys can be
used to scroll upward and downward in steps of one 'page' per key press.

8.2 Header data
    -----------
  At the top of the editing window are two writable values: 'Compression
offset' and 'Stars altitude'. These reflect the current state of two values
in the sky file's header, and may be altered by typing into the writable
field or clicking on the adjacent adjuster arrows.

  The higher the compression offset value is, the more compressed the colour
bands will appear at ground level. The stars altitude specifies the height
above ground level at which the game will start to plot stars. This can be
used to give the impression that the atmosphere becomes thinner at high
altitudes. It is usually easier to set both of these values by eye, using the
interactive sky preview (see 9.3).

8.3 Mouse actions
    -------------
  SFSkyEdit uses the standard RISC OS selection and drag & drop model, which
should be familiar to anyone who has used a text editor. Selections must be
contiguous, meaning that only neighbouring bands may be selected (no gaps are
allowed). The caret and selection are mutually exclusive, which means that
only one may exist at a time (conceptually, the caret is a zero-length
selection).

  To position the caret, click SELECT on the editing window. Clicking on a
selection has no effect in case it is the start of a drag. You can override
this by holding down the Ctrl key to force placement of the caret.

  To select a range of colour bands, click and hold SELECT to position the
caret at a starting point and then (still holding SELECT) drag upward or
downward to extend the selection. The end of the selection will follow the
mouse pointer until you release the mouse button. The editing window should
scroll automatically if the mouse pointer approaches the top or bottom edge
of the visible area.

   Alternatively, click ADJUST to instantly select all colour bands between
the caret position and the mouse pointer. An existing selection may be
modified by clicking or dragging ADJUST, to grab the nearest end point of the
selection and move it to the current pointer position.

  To copy or move selected colour bands, drag SELECT from any point within
the selected area to another place in the same sky file or to another editing
window. If the drag terminates at a directory display then a CSV file named
'Selection' will be created within that directory; beware of overwriting
any existing file of the same name. Whilst dragging colour bands, a green
caret shows where they would be inserted if dropped, and editing windows will
scroll automatically if the pointer lingers near the top or bottom of their
visible area.

  Dragging selected bands within a file will move them. To copy them, hold
the Shift key when starting the drag. These actions are reversed when
dragging to another file (Shift-drag to move, drag to copy).

Summary of mouse operations:

SELECT click
  In clear: Move the caret to the mouse pointer and disband any selection.
  On selection: If the Ctrl key is held then put the caret at the mouse
                pointer and and disband any selection.

SELECT double-click
  On selection: Choose a new colour for the selected bands.

SELECT drag
  In clear:  Drag out a new selection from the caret position.
  On selection: Move or copy the selected colour bands to the drop location.

ADJUST click
  If selection: Set nearest end of selection to mouse pointer.
  If no selection: Create new selection from caret position to mouse pointer.

ADJUST drag
  If selection: Drag extend/contract the nearest end of the selection.

8.4 File menu
    ---------
'File' > 'Info'

  This leads to a standard 'About this file' window, which gives information
about the file being edited: its current size in bytes, the time and date of
the most recent save, the file path under which it was most recently saved,
its filetype, and whether it has any unsaved modifications. If the file has
not yet been saved then the 'Date' field will show the time of creation.

'File' > 'Save'

  This leads to a standard savebox. Type a file name and drag the icon to a
directory display, or type a full file path and press Return.

  Switch on the 'Selection' option button to save only the selected colour
bands; this will be faded if there is no selection in the editing window.
Note that the filetype used for the savebox is 'SFSkyCol' (compressed Fednet
format), whereas dragging a selection directly from an editing window will
save it in CSV format. CSV is more useful if you are planning to insert the
selected colours into another sky file, because it is not a fixed-length
format (hence there is no black 'padding' at the top).

'File' > 'New view'

  Clicking on this menu entry opens a new editing window (i.e. view) for
the file. The title of each editing window displays the number of views (if
more than one) and unsaved changes to the file won't be discarded until the
last view is closed.

8.5 Editing menu
    ------------
  This menu gives access to the main functions of the sky file editor.

'Edit' > 'Insert bands...'

  This item brings up a dialogue box that allows you to set up an insertion
operation. Although this dialogue box isn't really transient (because it uses
pop-up colour pickers), it behaves similarly in that it automatically closes
if you interact with unrelated parts of the user interface.

  The number of bands to insert is set by typing into the numeric field at
the top of the window or clicking on the adjacent adjuster arrows. When doing
a gradated fill this number also dictates the smoothness of colour transition
that can be achieved.

  If you wish the new colour bands to be a plain colour, set the 'Plain
fill' radio button, and select a colour from the pop-up colour picker. If
used for an insertion, this colour will become the default for future
insertions.

  The facility to do a gradated fill is essentially another interface to the
'Interpolate' function (see 8.6). Using a sequence of gradated fills you can
quickly build up a high-quality sky file without much fiddling.

  The default start and end colours for a gradated fill are those
immediately above and below the current caret position. At the bottom of the
file there is no preceding colour, so the start colour is set to white. You
can select alternative colours from the pop-up colour pickers - doing so will
automatically set the corresponding 'Include...' option button (see below).

  The 'Include start colour' and 'Include end colour' options allow you to
do a gradated fill without actually including the initial and/or final
colour. This is useful for interpolating between pre-existing adjacent
colour bands and for merging consecutive fills.

  Normally these options are set automatically depending on whether the
start and end colours correspond to the colours adjacent to the caret, but
you can also set them manually. By default neither start nor end colours are
included, except at the start of the file where inclusion of the start
colour is sensible.

  To reset the dialogue box ADJUST-click on the 'Cancel' button. Clicking
'Insert' will insert the specified number of new colour bands and move the
caret up by the same amount. If you click with ADJUST rather than SELECT
then the start and end colour will be updated for another insertion and the
dialogue box will remain open. (This is useful for doing consecutive
gradated fills.)

'Edit' > 'Cut'

  Moves the selected colour bands to the global clipboard, erasing any data
currently held on it. Colour bands above those which were removed will be
shuffled downward to fill the space, and new black bands will appear to fill
the gap thus created at the top.

'Edit' > 'Copy'

  Copies the selected colour bands to the global clipboard, erasing any data
currently held on it.

'Edit' > 'Paste'

  If the global clipboard holds colours in the format understood by SFSkyEdit
then this operation will paste them into the editing window. They will be
inserted at the current caret position, causing all bands above the caret to
shuffle upward (at the end of the file some will be lost). If there is no
caret then the clipboard contents will instead replace the the current
selection.

'Edit' > 'Delete'

  Like 'Cut', except that the removed colour bands are discarded instead of
being moved to the clipboard.

'Edit' > 'Select all'

  Select all colour bands in the sky file.

'Edit' > 'Clear selection'

  Deselect any colour bands that may have been selected.

8.6 Effects menu
    ------------
  This menu provides actions which change the colour of the selected bands.
If there is no selection then all of the items on this menu will be faded.

'Effect' > 'Set colour'

  This item leads to a dialogue box that allows you to choose a colour from
the standard 256 colour palette. You can revert to the original colour at any
time by ADJUST clicking the 'Cancel' button. When you are happy with your
choice (displayed in the bottom left of the dialogue box) click 'OK' to
confirm. All bands selected in the editing window will be set to the chosen
colour.

'Effect' > 'Interpolate...'

  This item opens a dialogue box that allows you to set up an interpolation
between two colours. Although the dialogue box isn't really transient
(because it uses pop-up colour pickers), it behaves similarly in that it
automatically closes if you interact with unrelated parts of the user
interface.

  Given a start and end colour, SFSkyEdit can calculate the colours that
(when applied to the intervening bands) will most closely approximate a
smooth transition.

  By default the start/end colours used will be the first and last bands of
the current selection, but you can choose alternative colours from the pop-
up palette. To revert to the default colours ADJUST-click on the 'Cancel'
button.

  When you click 'Interpolate' the finished colour gradient will overwrite
the current selection. If you want to *insert* a colour gradient then you
should instead use the 'Insert bands' facility described earlier.

'Effect' > 'Smooth transitions'

  This item attempts to smooth abrupt changes from one colour to another,
within the selected bands.

  Unfortunately SFSkyEdit is unable to determine which the key colour bands
are and which are just intermediate colours. For this reason smoothing will
only really work where there are large blocks of contiguous bands all set to
the same colour.

  The routine attempts to find the centre point of each block of colour (or
uses the start and end of the selection for the first and final blocks).
Then, it changes all the intervening bands to make a smooth gradient between
the various mid-points, which remain unaltered.

  Basically, this is a one time only option, since almost by definition
there will not remain any large blocks of contiguous colour after a
smoothing operation. Not amazingly useful...

8.7 Utilities menu
    --------------
  This menu provides utilities which don't fit neatly elsewhere into the
menu hierarchy.

  'Utilities' > 'Goto'

  This item leads to a dialogue box that allows you to move the caret to a
specific position within the sky colours file. You can change the target
caret position by typing into the numeric field or clicking on the adjacent
adjuster arrows. To revert to the current caret position, ADJUST-click on
the 'Cancel' button. Click on 'Go' to move the caret to the specified
position.

  'Utilities' > 'Preview...'

  This item opens an interactive preview of the sky colours file being edited
(see 9). If a preview already exists then it will be brought to the front of
the window stack. Unlike the various dialogue boxes, each editing window can
have its own preview (the title of a preview window shows the name of the sky
file being rendered).

8.8 Keyboard shortcuts
    ------------------
F1        : Help (open the user manual).
Ctrl-F1   : Show file details, including date last saved and size etc.
Ctrl-F2   : Close editing window (gives discard/save/cancel prompt if no
            other views of the same file exist).
F3        : Open a savebox to allow the whole file or a selection to be
            saved.
Ctrl-F3   : Immediate save to last file path (without opening savebox).
F5        : Open a dialogue box to go to a specific position.
F7        : Open an interactive preview of the sky.

Scrolling:
Page Up (or Shift-Up)     : Scroll the view upward by one 'page'.
Page Down (or Shift-Down) : Scroll the view downward by one 'page'.

Caret movement:
Home (or Ctrl-Down) : Move the caret to the start of the sky file.
End  (or Ctrl-Up)   : Move the caret to the end of the sky file.
Up                  : Move the caret upward by one colour band.
Down                : Move the caret downward by one colour band.

Editing operations:
Ctrl-A             : Select all colour bands.
Ctrl-Z             : Deselect any selected colour bands.
Insert             : Open a dialogue box to insert colour bands.
Ctrl-C             : Copy selected colour bands to the global clipboard.
Ctrl-X             : Cut selected colour bands to the clipboard.
Ctrl-V             : Paste colour bands from the clipboard.
Ctrl-K (or Delete) : Remove selected colour bands from the sky file.

Effects on a selection:
Ctrl-E : Open the colour picker to set the colour of the selected bands.
Ctrl-S : Try to smooth abrupt colour transitions within the selection.
Ctrl-I : Open a dialogue box to interpolate between two colours.

-----------------------------------------------------------------------------
9    Preview window
     ==============

9.1 Sky rendering
    -------------
  A preview shows an interactive view of how a sky colours file would look if
it were rendered in the game. The only difference should be that images of
planets and suns are not composited onto the sky in a preview. It is updated
automatically as the file is edited or the viewing parameters are changed.

  The height of each colour band depends upon the viewing altitude in
relation to its position within the sky file. At high altitudes the first
few bands will be compressed to one or two rows of pixels at the horizon.
The angle of elevation does not affect the height of the bands; it simply
allows you to see a higher part of the output from the rendering algorithm.

  Stars are superimposed on the sky using a logical OR operation, which can
have unexpected effects with bright background colours. For example, consider
a background pixel where some colour component has the value %10 (2), upon
which is superimposed a star of brightness %01 (1). The combined value of
that pixel will be %11 (3). As the altitude increases, the star's brightness
increases to %10 (2) but the combined value %10 (2) is lower than before!

  Aliasing effects may spoil the appearance of dithered patterns at
percentage scales not exactly divisible by 50 (assuming standard eigen
factors). That is because scaling is applied to a bitmap that has already
been dithered instead of rendering the sky with different parameters.

  A snapshot of a sky preview can be saved by clicking MENU and following the
submenu arrow of the 'Save' menu item to open a savebox. Type a file name and
drag the sprite file icon to a directory display, or type a full file path
and press Return. The dimensions of the saved bitmap are unaffected by the
scale of the preview.

9.2 Viewing parameters
    ------------------
  Toolbars attached to the outside of a preview window allow control over a
number of viewing parameters: altitude, angle of elevation (in degrees from
horizontal) and direction (in degrees clockwise from north). Each of these
values can be set by typing into a numeric field or dragging an adjacent
slider. The blue slider controls altitude, the green slider angle of
elevation, and the red slider direction.

  Changing viewing parameters does not affect the actual sky colours file.

9.3 Editing menu
    ------------
  This menu allows the compression offset and stars altitude held in the
header of a sky colours file (see 8.2) to be updated according to the current
altitude of a preview.

  'Edit' > 'Set compression offset'

  This item adds the current viewing altitude to the compression offset,
subtracts it from the stars altitude, and then zeros it. Broadly speaking,
that has the effect of raising the ground level to the viewing altitude.
However, the appearance of the rendered sky may change because the rendering
algorithm caps the index of the pattern to be rendered according to the true
altitude before applying any compression offset.

  'Edit' > 'Set stars altitude'

  This item records the current viewing altitude as the new stars altitude
(the height above ground level at which the stars begin to be plotted).
Beware of setting this value too low because strong background colours can
interfere with increases in a star's brightness (see 9.1).

9.4 Utilities menu
    --------------
  This menu provides utilities which don't fit neatly elsewhere into the
menu hierarchy.

  'Utilities' > 'Scale view'

  This item leads to a standard 'Scale view' dialogue box which allows you to
type a percentage scale or adjust the current scale by clicking on adjacent
adjuster arrows. A number of buttons allow preset scales to be inserted into
the numeric field. To revert to the current scale, ADJUST-click on the
'Cancel' button. Click on 'Scale' to apply the new scale. You may wish to
enlarge the visible area of the preview window after increasing the scale.

  Changing a preview's scale does not affect the actual sky colours file nor
any snapshots of the preview that may be subsequently saved.

  'Utilities' > 'Show toolbars'

  If switched off, the toolbars attached to the outside of the preview window
will be hidden. This prevents any of the viewing parameters (direction,
altitude, angle of elevation) from being altered.

  'Utilities' > 'Save as default'

  This item saves the current scale and toolbar hide state of the sky preview
as the default settings for any previews subsequently created.

  'Utilities' > 'Random stars'

  This item generates a new star field, using pseudo-random values for the
position, brightness and colour of each star.

9.5 Keyboard shortcuts
    ------------------
F1        : Help (open the user manual).
Ctrl-F2   : Close the preview window.
F3        : Open a savebox to allow a snapshot of the preview to be saved.
F5        : Update the compression offset and stars altitude from the current
            viewing altitude.
F6        : Set the stars altitude to the current viewing altitude.
F7        : Generate a new star field.
F10       : Toggle whether the toolbars are shown or hidden.
F11       : Open a dialogue box to set the viewing scale.
Up        : Increase the viewing altitude by 16 units (of 3648).
Down      : Decrease the viewing altitude by 16 units (of 3648).
Left      : Rotate the view anticlockwise by 4 degrees (of 359).
Right     : Rotate the view clockwise by 4 degrees (of 359).
Ctrl-Up   : Increase the angle of elevation by 1 degree (of 60).
Ctrl-Down : Decrease the angle of elevation by 1 degree (of 60).

-----------------------------------------------------------------------------
10  Data formats
    ============

10.1 Compression format
     ------------------
  The first 4 bytes of a compressed file give the expected size of the data
when decompressed, as a 32 bit signed little-endian integer. Gordon Key's
file decompression module 'FDComp', which is presumably normative, rejects
input files where the top bit of the fourth byte is set (i.e. negative
values).

  Thereafter, the compressed data consists of tightly packed groups of 1, 8
or 9 bits without any padding between them or alignment with byte boundaries.
A decompressor must deal with two main types of chunk: The first (load a
byte) consists of 1+8 bits, and the second (copy data within output buffer)
consists of 1+9+8 or 1+9+9 bits.

The type of each chunk is determined by whether its first bit is set:

0.   Decode the next 8 bits of the input file (0-255) and write them as a
   byte at the current output position. The fact that this directive requires
   9 bits to represent 8 bits of information explains the inflation that can
   occur when attempting to compress random data.

1.   Decode the next 9 bits of the input file, which give an offset (0-511)
   within the data already decompressed, relative to a point 512 bytes behind
   the current output position. If this offset is greater than or equal to
   256 (i.e. within the last 256 bytes written) then decode the next 8 bits,
   which give the number of bytes (0-255) to be copied to the current output
   position. Otherwise, the next 9 bits give the number of bytes to be copied
   (0-511).

    If the read pointer is before the start of the output buffer then zeros
  should be written at the output position until it becomes valid again. This
  is a legitimate method of initialising areas of memory with zeros.

    A quirk of 'FDComp' is that least 1 byte is always written. That is
  probably a bug, although a well-written compressor should not insert
  directives to copy 0 bytes anyway. Note also that it isn't possible to
  replicate the whole of the preceding 512 bytes in one operation.

10.2 Sky file format
     ---------------
  Sky colour files are stored in a compressed format (see above). The table
below shows the layout of the decompressed data, which always totals 512
bytes.

Offset  Data
+0      Render offset (signed little-endian, typical range 0 to 3648)
+4      Stars plot height (signed little-endian, typical range -32768 to
        3648)
+8...   Sky data (126 patterns) :
  +8    Pattern 1 (4 pixels, 8 bits per pixel)
  +12   Pattern 2
  +16   Pattern 3...
  +508  ...Pattern 126

  Each quad-pixel pattern is tiled across the full width of the screen, and
also vertically as many times as is necessary to 'stretch' that colour band
to the desired height. On alternate lines the pattern is rotated left by one
pixel, to avoid the ugly vertical stripes that would otherwise result. The
default RISC OS 256 colour palette is assumed.

  SFSkyEdit has been designed to allow sky files similar to the Fednet
originals to be created and edited. To facilitate that, it imposes quite
strict constraints on the pixel data. These constraints have been derived
from the existing sky files. [*]

  Rather than allowing literally any sequence of 126 quad-pixel patterns,
SFSkyEdit allows only every other pattern to be edited. These editable
patterns must each consist of a plain colour, with the intervening patterns
available for dithering colour transitions. This gives 63 editable colour
bands rather than the actual 126 patterns.

  The plain patterns are odd-numbered and the dithered ones are even-numbered
(counting from 0). Since the first colour cannot be sensibly dithered with a
preceding colour, it is wider than other colour bands:

Index  Pattern  Role
-----  -------  ----
0      0000     Clone of pattern 1
1      0000     Plain colour band 0 (editable)

2      1010     Dithered
3      1111     Plain colour band 1 (editable)

4      1212     Dithered
5      2222     Plain colour band 2 (editable)

  If the pixel data in a sky file does not follow the conventions described
(e.g. outlandish patterns are used, or there are contiguous dithered rows),
then SFSkyEdit may badly misinterpret them. I make no apology for that,
since I have no reason to suppose that any such files exist or ever will.

[*] Violations:
  A couple of the Fednet sky files contain isolated peculiarities that
violate the strict rules set out above: The final (non-black) pattern of both
'Earth' and 'Earth2' consists of the preceding blue dithered with another
blue rather than the black of the following pattern.

  In practice this doesn't really matter, though the oddity could be
rectified by using SFSkyEdit to reset the black colour band and consequently
the dithering on the transitional pattern.

-----------------------------------------------------------------------------
11  File types
    ==========

  The filetypes used by SF3000 are highly non-official. Presumably they
thought that this wouldn't matter for files used internally in the game. I
already know of some clashes (none serious) with other filetypes, but I
can't really alter them retrospectively.

Type  Name     Contents
----  ----     --------
&404  SFSkyCol SF3000 compressed sky colours.
&DFE  CSV      Comma separated values, which SFSkyEdit can interpret as
               colour numbers if they are in the range 0 to 255.

-----------------------------------------------------------------------------
12  Program history
    ===============

1.00 (15th August 2001) -----------------------------------------------------
   First version (though it inherits much of the structure and features of
    SFcolours).

1.01 (17th August 2001) -----------------------------------------------------
   Had forgotten to RMEnsure the nested Wimp in the !Run file, to safeguard
    use of 24-bit icon colours.

1.02 (19th August 2001) -----------------------------------------------------
   Fixed code that passes input focus back to main window - no longer gives
    error when it is already gone and child windows are closed.
   Closes interpolate/insert dialogue boxes and preview window when parent
    editing window is closed.

1.03 (19th September 2001) --------------------------------------------------
   Fixed bug in Loader component regarding multi-stage RAM transfers.

1.10 (24th December 2001) ---------------------------------------------------
   Total overhaul of source code from the ground up, with many improvements
    and fixes not really externally visible.
   Now uses flexlib rather than the C library heap, for storing large data
    blocks. This means that the Wimpslot expands and contracts as necessary.
   ADJUST-clicking the close icon of a document window now opens its parent
    directory, as proscribed by the Style Guide.
   Added audible warnings for failed actions (e.g. copy when no selection).
   Menu options now grey/ungrey appropriately when hot keys are pressed in
    main editing window.
   Clicking editing window closes Insert/Interpolate dialogue boxess if open
    as children, to give impression of transience.
   Preview images are now scaled correctly for screenmode eigen factors.
   Fixed a number of embarrassing memory leaks.
   Fixed bug in Loader component with !Scrap transfer from other apps,
    where suggested leaf name was shorter than "<Wimp$Scrap>".
   Corrected 'SFsky' menu titles, left from before I'd decided on the name.
   No longer get weird colours by clicking at very edge of palette.

1.11 (8th January 2002) -----------------------------------------------------
   Fixed "Invalid Object Id" bug on start-up, where app had been launched
    by double-clicking on sky file.
   Minor improvement to handling of ADJUST-clicks on action buttons in
    palette dialogue box.

1.12 (3rd May 2002) ---------------------------------------------------------
   New 16 colour & 256 colour sprites.
   Verifies format of sky files on loading. Added '-nowarn' command line
    switch to disable this.
   Other internal improvements including more efficient code (!RunImage
    actually smaller).

1.13 (11th November 2002) ---------------------------------------------------
   Further improvement to error-checking macros.
   Corrected mistake in !Run file where the CallASWI module was not being
    loaded on RISC OS 3.6, despite being required on all OSes prior to 3.7.
   Recompiled using the official Castle release of 32-bit Acorn C/C++.

1.14 (11th April 2003) ------------------------------------------------------
   Fixed bug where auto-scrolling stopped when pointer reached edge of
    window (only manifested in modes with non-standard eigen factors).
   Auto-scrolling is now constant rate, since it adjusts itself to the
    elapsed time between null polls.
   Changed key shortcuts for close window to ctrl-F2, as per the style
    guide.
   Slightly more verbose error messages for situation where a file can't be
    opened.
   Moved 'Help' item to top of icon bar menu, as per Castle docs.

1.20 (13th June 2003) -------------------------------------------------------
   The current selection is now highlighted using a dark background colour
    in addition to numbering the icons and giving them borders.
   You can now double-click on selected bands to change their colour and
    ADJUST-drag to alter the extent of an existing selection.
   Paste from clipboard now replaces any selection, rather than being
    disabled except when there was a caret.
   Implemented full keyboard control of the caret, and added 'Trap caret'
    option to keep the caret inside the view area when scrolling.
   Redesigned the 'Insert' dbox to provided more complete control over
    inclusion of start/end colours and the starting colour for the fill.
   All dialogue boxes can now be reset by ADJUST-clicking on the 'Cancel'
    button. This allows a simplified design for the 'Interpolate' dbox.
   Reorganisation of the menu structure and other tweaking to the user
    interface after reference to the Style Guide.
   The caret no longer disappears entirely when editing window loses the
    input focus. This helps when using the 'Insert' dbox.
   When closed, transient dialogue boxes that claim the input focus now
    restore it to the previous owner. The 'Insert' and 'Interpolate' dboxes
    still pass the focus to the main window, but now only do so if they own
    it.
   The 'Insert' and 'Interpolate' pseudo-transient dboxes no longer have
    back-icons and will now be dismissed by a variety of mouse clicks - not
    just those on the parent window.
   File paths are now canonicalised before being displayed or compared
    (i.e. 'IDEFS::Tamzin.$.!Boot.Choices' rather than '<Choices$Write>')
   Now uses the Toolbox's standard 'Quit' dbox object rather than a custom
    dbox. The default action is now 'Cancel' rather than 'Quit'.
   Removed COPY and ^H as alternative key shortcuts for delete, and
    implemented HOME and END keys to go to top/bottom of sky file.
   Fixed a redraw bug in the palette dbox, though this was only evident in
    screen modes with a y eigen factor of less than 1.
   No longer gives repeated errors and loses the caret off the top when an
    insertion overruns the end of a file.
   The caret is now relocated to the base of a removed area on a cut or
    delete operation, rather than appearing in an unrelated position.
   Fixed bugs with drag-and-drop: When moving a selection to a higher
    location in another file the insertion point was incorrect, and a drop on
    the site of a former selection would replace those bands.
   Fixed bug where the caret was not drawn if Ctrl-Z was pressed to clear
    the selection and it was not within the selection redraw area.
   Can no longer crash the program by entering rubbish values into the 'Min
    sky height' and 'Stars start height' writable fields whilst the preview
    window is open.
   Integrates much better with the pinboard - any iconised window icon is
    removed when that window is re-opened independently by the application.
   More sensible response to error on Toolbox_Initialise (doesn't rely on
    messages file, which isn't open).

1.21 (19th August 2003) -----------------------------------------------------
   Even if there is no unsaved data when a PreQuit message is received, we
    now wait for the Quit message rather than dying prematurely.
   Where possible, changed to use SWIs instead of Star Commands for file
    access. This is faster and also reduces code size.
   Now demands version 5.43 of the shared C library, since this is the
    earliest version documented as supporting C99 functions (some of which
    are used).
   Formatted the manual text for a fixed-width 77 column display (Zap's
    default).

1.22 (13th September 2003) --------------------------------------------------
   The program now directly incorporates compression code, hence it is no
  longer dependent on the Comp and Decomp modules from !FednetRes.
   Released with source code under the terms of the GNU G.P.L.

1.23 (23rd October 2003) ----------------------------------------------------
   Internal changes.

1.24 (7th November 2003) ----------------------------------------------------
   On shutdown, no longer quits immediately that 'Quit' is selected from
    the quit confirm dbox. Instead all editing windows are closed and we
    wait for a Quit message (analogous to what Paint, Edit & Draw do).
   Now restarts desktop shutdown by sending a keypress event to the task
    that sent us the PreQuit message (as recommended by the PRM), instead of
    using SWI Wimp_ProcessKey.

1.25 (1st March 2004) -------------------------------------------------------
   Re-compiled with release 9 of CBLibrary.

1.26 (7th November 2004) ----------------------------------------------------
   Reduced the size of the colour picker dbox, which now hangs off the
    Effect menu rather than requiring a menu click to open it. It no longer
    claims the input focus because a transient dbox should only 'borrow' it
    (Toolbox issue).
   Changed titlebar colours of transient dboxes to be grey regardless of
    whether they have the input focus (as per the Style Guide).
   Made changes necessary and/or desirable to compile with release 12 of
    CBLibrary.
   We no longer restore the initial savebox filename when a user clicks
    ADJUST on the Cancel button, because by rights this should be handled by
    the SaveAs module (which will hopefully be fixed, as Scale has been).
   Added system variables to !Boot file for Castle's proposed help system.

1.27 (19th November 2004) ---------------------------------------------------
   English default messages are now used to report flex memory errors
    because a bug in the library prevents use of our messages file.

1.28 (7th January 2005) -----------------------------------------------------
   The main editing window now scrolls by the correct distance (exactly one
    'page') when the user clicks in the well of the vertical scroll bar.
    Previously the area obscured by the internal pane was not taken into
    account.
   Fixed longstanding memory leaks that would occur if a single editing
    window was repeatedly opened and then discarded. This was because the
    program had not made provision for removal of event handlers for the
    shared objects attached to this window.
   Fixed a minor error in calculation of the position of the top edge of
    the rubber band box used to represent dragging a selection, when clipped
    to the window's visible area.
   The colour translation table used for plotting the sky preview is now
    stored in the program's heap rather than a flex block and because it is
    not generated until needed (or the screen mode changes) the initial
    wimpslot is smaller.

1.29 (06 Mar 2005) ----------------------------------------------------------
   New editing windows are now opened in a downwards stack starting at the
    centre of the screen (as per the Style Guide). Previously, new files
    would open centred on screen and files loaded would open at the pointer.
   The currently selected colour is now highlighted within the palette as
    well as being displayed separately at the bottom of this dbox.
   Duplicate files are now rejected earlier instead of being discarded
    after having been loaded.
   Non-existent files specified as command line arguments are now reported.
   We now use global message 'BadParm' instead of a similar message of own.
   Various other internal changes including those necessary or desirable
    when building with release 15 of CBLibrary.

1.30 (14 May 2005) ----------------------------------------------------------
   Many internal changes - notably to processing of Toolbox events (now use
    our own event numbers) and tidying up upon object deletion. Code size
    has actually shrunk compared with previous versions!
   Added new key shortcut Ctrl-F3 to trigger an immediate save.
   Fixed longstanding memory leak upon opening a new editing window
    (was registering one too many event handlers).
   Fixed bug where failure to save a file would result in two error
    messages in succession; one from the application and another from the
    SaveAs module.
   The menu tree is now closed if its state becomes outdated following use
    of a keyboard shortcut.

1.31 (04 Jul 2005) ----------------------------------------------------------
   Now uses Wimp_PollIdle to limit the frequency of null events during drag
    operations.
   Improved the efficiency of redraw & recalculation at termination of move-
    by-drag operations within a single file. At the same time fixed a
    longstanding bug (since v1.12?) where the editing window would scroll
    to the former selection position upon termination of such drags.
   Fixed a longstanding bug where the wrong editing window would be auto-
    scrolled and have its selection updated if the pointer strayed into it
    during a drag-select operation.
   Scrolling speed should now remain constant when monotonic timer wraps
    around (had been dropping 1 centisecond).
   It is now possible to halt a drag-selection by pressing the Escape key
    (same as when dragging colour bands).
   Updated ResFind from version 2.01b to latest version 2.12 (improved
    support for truncated country names & long paths).
   Built with release 18 of CBLibrary (which it requires).
   No longer requires the new (C99, APCS-32) shared C library or a version
    of the floating point emulator that supports LFM/SFM instructions.

1.32 (05 Aug 2005) ----------------------------------------------------------
   Eliminated unnecessary redraw upon gaining or losing input focus when no
    caret displayed.
   Internal changes to use more Toolbox interfaces in preference to Wimp
    ones and improve efficiency in other cases.
   The destination editing window now gains the input focus upon termination
    of drag and drop.
   Fixed bug where extent of new selection was not clipped when pasting
    near EOF, subsequently allowing garbage to be read from out of bounds.
   The user is now prevented from inserting bands at EOF (by any method)
    by greyed out menu entries and/or an audible warning.
   More conservative estimation of whether a smoothing operation resulted in
    changes to a file.

1.33 (11 Aug 2005) ----------------------------------------------------------
   Moved definition of system variables for Castle's proposed help system
    from !Boot file to Obey file in subdirectory for relevant country (to
    allow internationalisation).
   !Run file no longer invokes ResFind a second time, having executed !Boot
    (which does so).

1.34 (09 Sep 2005) ----------------------------------------------------------
   No longer leaks memory claimed for colour translation table if subsequent
    call to ColourTrans_SelectTable fails.
   Actually linked against generic shared C library stubs (had accidentally
    reverted to using Castle's stubs in version 1.33).

1.35 (02 Feb 2006) ----------------------------------------------------------
   General tidy up of excessive brackets and casting in source code.
   Updated our LoaderPreFilter function for compatibility with release 19
    of CBlibrary.
   Updated manual text, !Boot file, Resource file and Messages text for
    revised file type names.
   Removed redundant paragraph from 'Licence and Disclaimer' section of
    manual.

1.40 (18 Oct 2006) ----------------------------------------------------------
   Now supports the global clipboard and drag-and-drop protocols, to allow
    seamless interaction with other applications. (Previously these features
    only worked within a given incarnation of SFSkyEdit.)
   Selected colour bands now display the associated colour number (for
    screen mode 13) instead of the indices of those bands within the file.
   Whilst the input focus is elsewhere, the current selection is faded or
    the caret is removed. (Previously the caret was just changed to grey.)
   The Home and End keys now act on the caret rather than just scrolling the
    editing window.
   You can now disband a selection and set the caret position by clicking
    on it with the Ctrl key held down.
   Wimp lose/gain caret events are now ignored (as per application note 240)
    so that the input focus is not considered to be lost unless claimed by
    another application.
   The caret is now erased rather than faded when the input focus is lost.
   The 'ghost' caret used to show the insertion point during a drag is now
    green instead of orange.
   Auto-scrolling of editing windows during a drag is now delegated to the
    window manager (and hence requires RISC OS 4 or later). The configured
    auto-scroll delay is used when dragging selected colours.
   If solid file drags are configured then the selected colours will now be
    represented by an icon during a drag, instead of a cycling dashed box.
   If a cycling dashed box is used then this is no longer clipped to the
    visible area of the selection at the start of the drag.
   Dragging selected colours to the SFSkyEdit icon on the icon bar will
    now open a new editing window containing just those colours.
   Will now load colours dropped on the internal pane or furniture of an
    editing window (by inserting them at the caret or replacing the
    selection).
   Fixed a bug where the 'ghost' caret was placed outside the visible area
    of an editing window if the pointer moved over its title bar during a
    drag.
   Fixed a bug with the 'Trap caret' option; pressing the PgDn or PgUp key
    when the window can scroll no further would move the caret anyway. In
    the latter case the caret would be lost off the top!
   It is now possible to insert new bands while a selection exists (the
    selected colour bands are replaced).
   Colour bands are now selected at their destination, after having been
    copied within a file by dragging with Shift held.
   The number and border of selected colour bands are now plotted using
    absolute black or white, instead of relying on Wimp colours 0 and 7.
    This ensures high contrast regardless of the desktop palette.
   The palette dialogue box now claims the input focus and displays the
    current colour number, which can be changed using the keyboard or
    adjuster arrows.
   The mouse pointer is now bounded whilst dragging to change the selected
    colour in the palette dialogue box.
   Improved the implementation of smoothing so that it works on narrower
    areas of contiguous colour.
   Built with release 22 of CBLibrary (which it requires).

1.41 (18 Oct 2006) ----------------------------------------------------------
   Minor fix to prevent unwanted scrolling after dragging selected bands to
    move them elsewhere.
   Reduced initial memory requirement.
   Squeezed !RunImage file.

1.42 (25 Oct 2006) ----------------------------------------------------------
   Fixed a bug where the tick on the 'Trap caret' menu item was updated
    whether or not this menu was open as a descendant of the editing window
    for which this option was changed.
   The icon bar icon now claims drags where it is interested in the file
    type offered.
   Added a 'Web' button to the 'About this program' window. This requires
    a later version of the ProgInfo module.
   Can now import colours in the Data file format produced by SFcolours.
   Can now export (but not import) selected colour bands in CSV and text
    format for compatibility with other applications.
   Renamed some objects in the Resource file.
   Initial memory requirement increased to 112 KB.

1.43 (09 Nov 2006) ----------------------------------------------------------
   Can now import, as well as export, colours in CSV format. CSV has now
    completely superseded the esoteric data format for exported colours that
    was introduced in version 1.40.
   Imported colours are now selected when displayed in a new editing
    window, after having been dragged to the icon bar icon.
   The name of file type &DFE is now defined when the application is 'seen'
    by the Filer. Moved the naming of file types into the country-specific
    Obey file 'SFSkyEditRes:SysVars'.
   Harmonised the test used to decide whether to display a ghost caret
    (during a drag) with that used to decide whether a mouse click is within
    a selection. This avoids a redraw bug in the DragAnObject module, which
    occurs when an area overlapping the representation of a dragged object
    is independently redrawn before the mouse has moved.

1.44 (18 Nov 2006) ----------------------------------------------------------
   Linked with a new version of CBLibrary to fix a bug where a spurious
    'your_ref' value was included in outgoing DataSave messages, if a drag
    had previously been claimed (even if the recipient was not the claimant).
   Fine tuned the restrictions on the range of acceptable values for the
    render offset and stars height. It is now possible to save sky files
    with a negative stars height (like in "Warrior" and "Death").
   The decompressed data size, render offset and stars height are now
    checked as part of the validation process when a file is loaded.
   The dithering method used has been changed to produce results identical
    to existing sky files.
   Now accesses pixel data in bytes rather than words (for compatibility
    with changes to the structures defined by CBLibrary).
   The stars height is now updated as appropriate, when a new ground level
    is set in the preview window.

1.45 (23 Nov 2006) ----------------------------------------------------------
   The file types list used when probing for clipboard data is now in the
    same order as when pasting data from the clipboard or claiming a drag.
   Corrected the title input focus colour of the colour picker dialogue box.
   Restored 'back' window tools to the persistent dialogue boxes (were
    removed in version 1.20).

1.46 (26 Nov 2006) ----------------------------------------------------------
   Removed dependence on CBLibrary's Loader module. As a consequence it has
    been possible to reduce the initial memory requirement by 4 KB.
   The default document name (e.g. "<untitled>") and default leaf name for
    the save box are now in the messages file, to allow nationalisation.

1.47 (28 Apr 2007) ----------------------------------------------------------
   At Matt Holgate's suggestion, implemented Sprite file (type &FF9) as one
    of the export formats offered to receiving applications when pasting the
    clipboard contents, and for drag-and-drop. In practice this isn't very
    useful because most applications are too stupid to specify a preference
    and therefore get the data in its default format (which is CSV). However,
    clipboard paste into modern versions of Paint will now work.
   The source code for dithering colour transitions is now a little more
    comprehensible to humans.

1.48 (12 Sep 2007) ----------------------------------------------------------
   Removed a somewhat arbitrary restriction in handling changes to the
    'Render offset' and 'Stars height' values. New values outside the range 0
    to 10000 failed to update the sky preview window or mark the edited file
    as having unsaved changes. The original reason was that versions of the
    Window module prior to 1.86 sometimes returned out-of-bounds values.
   Fixed a bug where data of type SFSkyCol (&404) imported directly from an
    application into an editing window (e.g. by dragging the file icon from a
    savebox) was not decompressed. This manifested as a misleading warning
    message 'Decompressed data is the wrong size for a sky colours file',
    followed by insertion of apparently random colour bands (if the user
    chose to continue).
   Fixed a bug where DataSave messages received in reply to a DragClaim
    message were ignored if the drag destination was not the last window to
    be created (was dependent on the order of event handler registration).
    This was concealed by the fact that SFSkyEdit uses a short-cut when the
    drag destination is another editing window which it owns.

1.49 (25 Jun 2009) ----------------------------------------------------------
   Changed the keyboard shortcuts to trap/free the caret, open the preview
    window and set the stars/ground height offsets (although the old Ctrl-
    T/P/S/G key shortcuts still work). These are now mapped to function keys,
    which are language-neutral and only require a single keypress. (The idea
    is that only editing actions should be mapped to Ctrl-letter key
    combinations.)
   If the preview window is already open then it is now shown by bringing it
    to the front of the window stack and giving it input focus, instead of
    re-opening it relative to the position of the editing window.
   The preview window now claims the system-wide caret/selection entity
    when it gains the input focus, so that the current owner can undraw its
    caret or fade its selection.
   It is now possible to save only the selected colour bands, rather than
    the entire sky file, by means of a new option button in the savebox.
   Internal changes in preparation for saving in a format negotiated with
    the recipient, when a file icon is dragged from the save dialogue box
    (not yet utilised).
   Fixed a bug where the heap block holding the path associated with a file
    being edited was deallocated immediately before copying that string to a
    new block, after the user chose 'File' > 'Save' from the menu. (Uncovered
    by Fortify, which overwrites the content of deallocated blocks
    immediately.)
   Now tends to stop whatever it was doing if the user chooses to continue
    execution after an unexpected error (to prevent recurring errors).
   Documented the decompression algorithm here.

1.50 (31 Aug 2009) ----------------------------------------------------------
   All command-line arguments are now parsed together after initialisation,
    rather than only the input file names. Syntax checking is more stringent:
    switches must now be specified before file names.
   Errors when dealing with activation of the 'Quit' button in the query
    dialogue box displayed during desktop shutdown are now treated as fatal.
   Fixed a bug where "Not enough memory" could be reported (accurately)
    twice in quick succession when saving a selection, cutting or copying
    colour bands to the clipboard.
   Fixed a failed assertion caused by attempting to enable budging of the
    flex heap without having first disabled it, after warning "Decompressed
    data is...", "Sky render offset is..." or "Stars plot height is..."
    (harmless in release builds).
   Uses a new CBLibrary function to read screen size instead of caching the
    current mode's dimensions in pixels.
   Changes to guard against "Invalid Object Id" errors when trying to
    determine whether Wimp messages are of interest to editing windows that
    have been deleted but for which no Toolbox_ObjectDeleted event has yet
    been delivered.
   Reduced the decompressed executable size from 91928 to 90336 bytes by
    substituting data for code and hand-optimising. Reduced initial wimpslot
    from 112 KB to 108 KB.

1.51 (13 Sep 2009) ----------------------------------------------------------
   A binary search is now used to find which initialisation function to call
    (if any) for the template named in a Toolbox_ObjectAutoCreated event.
   The same code is now used when claiming a drag for the iconbar icon as
    when claiming a drag for a document window.
   Further changes to use arrays of arguments instead of many in-line calls
    to the same function with different arguments.
   Fixed a regression in the previous version where file icons dragged to
    the internal pane were ignored.
   Stopped using reserved identifiers (those starting with an underscore
    followed by a capital letter).
   Further reduced the decompressed executable size to 89664 bytes.

1.52 (17 Oct 2009) ----------------------------------------------------------
   Now uses unsigned rather than signed types where all negative values are
    invalid and natural-width integer types instead of 'uint8_t' except where
    memory is at a premium.
   Improved modularity of code, guided by moving structure definitions from
    header to source files and providing accessor functions where
    unavoidable.
   Caret is no longer drawn slightly attenuated and misshapen in screen
    modes with eigen values of less than 1.
   Gave names to a huge number of 'magic' values (numeric constants).
   Uses new type-safe SWI veneers provided by release 34 of CBLibrary.
   Errors are still detected at low level but now handled at a higher level
    (typically event handler functions).
   No longer so reliant on SWI Toolbox_GetClientHandle (more efficient
    access to data associated with UI objects) and Toolbox_ObjectDeleted
    events.
   No longer marks the file as having unsaved changes when the compression
    offset or stars altitude is set from the preview window unless at least
    one of those values has actually changed.
   Trapping the caret within the visible area of an editing window as it is
    scrolled is now a global rather than per-window option. It can be
    switched off by default by passing a new command line option '-notrap'.
   Created an 'Options' submenu from the iconbar to allow the dither warning
    and caret trapping to be switched on or off.
   Increased altitude limits from 2048 to 3648, to match the observed
    maximum compression of colour bands within the game. Relaxed
    verification of sky colours files as necessary.
   Implemented a facility to move the caret to a specific position within a
    sky colours file. This dialogue box shares a new 'Utilities' submenu with
    the 'Preview...' menu option.
   Sky previews now include a pseudo-random star field to show the
    configured stars height.
   Implemented a facility to save a snapshot of a sky preview as a Sprite
    file.
   Implemented a facility to change the viewing scale of a sky preview.
   Moved the keyboard shortcuts for 'Set compression offset' and 'Set stars
    altitude' from F10/F11 to F5/F6, thus freeing F11 for its standard action
    of opening a scale dialogue box.
   The toolbars attached to a sky preview window can now be hidden.
   It is now possible to control the direction and angle of elevation for a
    sky preview, in addition to the simulated altitude.
   The viewing altitude of a sky preview can now be changed by typing a
    numeric value for more precise control than dragging the slider.
   The menu tree attached to a preview window has grown to accommodate the
    new features.
   Changed the button type of the 'Insert' and 'Interpolate' window
    templates from 'writable' to 'never'. Clicking on the background to gain
    input focus felt like a bug because of the many gadgets which get in the
    way.
   Swapped the event code generated by Home and End keypresses so that Home
    moves the caret to position 0.

1.53 (18 Oct 2009)
   Added missing RMEnsure commands in the !Run file to ensure that a
    suitable version of the Scale module is present.

1.54 (02 Jul 2010)
   Specified the appropriate switches to prevent the Norcroft C compiler
    from generating unaligned memory accesses incompatible with ARM v6 and
    later (for RISC OS on BeagleBoard).
   Renamed some functions to use opposite verbs (get/set rather than
    get/write) and consistent terminology (colour rather than shade).
   The back-end functions no longer operate on double-indirected pointers
    (it wasn't explicit that they were flex pointers, which made it easy to
    introduce very hard to find bugs).
   Use 'flex_ptr' more widely to reduce the number of casts to that type.
   Removed references to CBLibrary header file "TboxBugs.h".
   Expunged references to type and function names deprecated in release 34
    of CBLibrary.
   Corrected the spelling of "indicies" to "indices".
   Removed some superfluous casts from 'void *' to other pointer types.
   Removed an 'absdiff' function (the C compiler can inline the standard
    library function 'abs').
   Reworded the advice appended when reporting error messages to the user.

1.55 (09 Jan 2011) ----------------------------------------------------------
   Linked against release 40 of CBLibrary, in which the compression and
    decompression code have been rewritten from scratch.

1.56 (28 Jan 2011) ----------------------------------------------------------
   Linked against release 42 of CBLibrary, in which the speed of compression
    and error detection during decompression have been improved.

1.57 (13 Feb 2011) ----------------------------------------------------------
   The 'About this file' window now shows the compressed rather than in-
    memory size of the file (i.e. the size of the file had it been saved at
    the moment the window was opened).
   Updated the amount of free memory required to start the application from
    116K to 164K (of which 120K is assigned to the application memory slot).

1.58 (25 Sep 2013) ----------------------------------------------------------
   Fixed a bug where dragging selected bands with solid dragging effects
    configured on caused a data abort. The icon-rendering routine called
    back by the DragAnObject module had been trying to illegally access
    static data (to change the flex budge state). Presumably this dates from
    version 1.54.
   Deleted some enumerators for file system object types that are now
    duplicated in CBLibrary.
   Widespread minor changes to avoid type-casting the result address passed
    to function toolbox_get_client_handle.
   Fixed a misuse of constant NULL_ObjectId in place of NULL.

1.59 (19 Feb 2016) ----------------------------------------------------------
   Much code refactoring: reduced use of 'goto', split command line argument
    parsing and application initialisation from the main event polling loop,
    and moved handling of DataOpen messages to the iconbar module because
    they are treated very similarly to DataLoad.
   Created a set of unit tests that simulate event delivery.
   Fixed a bug where DataRequest messages wrongly claimed that SFSkyEdit
    could handle compressed sky data. (Compressed sky data can only be loaded
    by dragging it into SFSkyEdit, not by pasting from the clipboard.)
   Fixed a bug where a "Decompressed data is the wrong size for a sky
    colours file" error occurred if the clipboard owner sent compressed sky
    data to SFSkyEdit (which can happen whether or not SFSkyEdit wrongly
    requests clipboard contents in that format).
   Fixed a bug where DragClaim messages sent by SFSkyEdit were too large.
   Fixed a memory leak where lookup tables used to render a sky preview
    were not deallocated if a preview window was destroyed without first
    hiding it (e.g. by closing the main editing window). The tables are
    now generated upon application initialization, which makes the amount
    of memory used initially higher but steady.
   Fixed a bug where PreQuit messages were always assumed to incorporate a
    flags word, making it unpredictable whether or not desktop shutdown was
    restarted if no flags were present. That had little practical effect
    because the extra word is always present from RISC OS 3 onward.
   Linked against release 50 of CBLibrary, which provides new string buffer
    and linked list implementations which are utilised. Failure of the
    standard library's fseek function is now detected and the code to handle
    drags has been made more robust.
   ObjectDeleted event handlers are no longer registered for shared objects
    that are created upon application initialization and never deleted.
   The initial filename displayed in the savebox belonging to a sky preview
    window is no longer updated after a successful save to a safe destination
    (avoiding apparent 'leaks').
   The colour translation table used to draw the sky preview window is now
    discarded upon mode or palette change rather than simply being marked
    as outdated (giving unit tests a mechanism to force it to be freed).
   Optimised the makefile by using $(addprefix ) and suffix-based rules.

1.60 (04 Aug 2016) ----------------------------------------------------------
   Fixed auto-scrolling upon dragging a selection over an editing window,
    which was broken in version 1.59 (because it was enabled every time the
    drag was claimed and therefore the delay never expired).
   If a drag terminates within a window belonging to the same instance of
    the application then auto-scrolling is disabled immediately and the ghost
    caret undrawn instead of sending a Dragging message with the 'do not
    claim' flag set.
   Removed reliance on calling the _kernel_setenv function with NULL to
    delete a variable because of a bug in early versions of the shared C
    library (including 3.75, the minimum required).
   Simplified OS error handling. Most OS calls are very unlikely to fail or
    have few side-effects (e.g. redraw), and are therefore handled at the
    earliest opportunity instead of being passed up the callstack.
   Reduced usage of short-lived flex buffers for passing data between
    functions; where necessary, a temporary array of 63 ints is declared.
    Similarly, the clipboard now has static storage duration.
   The EditSky_create function no longer creates empty files; it only wraps
    existing files in a user interface.
   The EditSky_bands_updated function must now be called separatedly if
    required, instead of passing a boolean argument to many other functions.
   Removed functions unconnected with editing windows (IO_make_CSV_file,
    IO_make_sky_file, IO_make_sprite_file, IO_claim_drag) from the SkyIO.h
    interface.
   More use of C99 idioms for variable declaration.
   Created an alternative makefile for use with GNU Make and the GNU C
    compiler.

1.61 (27 Sep 2016) ----------------------------------------------------------
   Further refactoring and simplification of OS error handling.

1.62 (09 Feb 2019) ----------------------------------------------------------
   Fixed a bug where failure to create a preview window for many reasons
    returned an illegal address instead of a null pointer.
   The command line parser uses decode_load_exec instead of custom code.
   Added 'const' qualifiers to event handler function arguments.
   Updated the Makefiles to share a common list of source files and link
    with separate C libraries instead of the old monolithic CBLibrary.
   Deleted the build configuration in which OLD_SCL_STUBS was not defined.
   Moved validation of the sky dither pattern into the back-end.
   Moved drawing and layout of the editor display into a separate module.
   Redraw of the editor display no longer uses a lookup table to decide
    whether to use black or white for contrast with colour bands.

1.63 (24 Feb 2020) ----------------------------------------------------------
   Fixed a regression in version 1.62 where colour band indices were
    displayed instead of colour numbers.
   Added support for multiple views of the same file.
   Changed the colour interpolation code to round to the nearest integer
    instead of towards zero.
   Added support for pasting compressed sky colours from the clipboard.
   Broadcasts caret-claim messages in response to gain-caret events to
    integrate better with other applications that move the caret to windows
    belonging to SFSkyEdit.
   Uses abstract data streams for input and output as required by the
    'Entity2', 'Saver2' and 'Loader3' components in release 58 of CBLibrary.
   Separated more of the platform-independent code from the user interface
    code and wrote unit tests for it.
   Eliminated 'extern' linkage specifiers and pre-declaration of 'static'
    functions where possible.
   Tweaked the application icons to have an irregular outline as is normal.

1.64 (02 Jun 2020) ----------------------------------------------------------
   Added support for undo and redo.

1.65 (28 Oct 2020) ----------------------------------------------------------
   Downgraded the SaveAs object template version for compatibility with
    ROOL's ResEd.
   Specified a list of messages of interest upon task initialization for
    improved efficiency.
   Defined custom Toolbox event numbers for creating a new file and for
    bringing all windows to the front, to allow the user interface to be
    reconfigured using ResEd alone.
   Rely less on toolbox_get_object_state() to determine whether objects
    are showing, since some versions return unreliable results.

1.66 (02 Dec 2020) ----------------------------------------------------------
   Linked with a bugfixed version of my streams library that cannot become
    stuck in an infinite loop when writing to a compressed file.
   A new CBlibrary function, loader3_load_file(), is used to load files
    dragged from a directory display to the iconbar icon.

1.67 (09 Dec 2020) ----------------------------------------------------------
   Linked with a bugfixed version of my streams library that cannot produce
    truncated output when writing to a compressed file. (Previous attempted
    bugfix had this bad side-effect.)
   Minor refactoring: more use of compound literal assignment for
    robustness and succinctness.

1.68 (01 Aug 2022) ----------------------------------------------------------
   Intercept #include of library headers (for debugging purposes) using
    local files of the same name, which requires use of "" instead of <>.
   Use bit fields for a struct with many Boolean members.
   Assign compound literals to ensure full initialization of dynamically
    allocated objects.
   Use a new library function to remove all event handlers and delete a
    Toolbox object.
   Prefer returning early if successful rather than conditional error
    clean-up.
   Declare objects with initializers where possible.
   Use new library veneer to SWI Wimp_AutoScroll.
   Simplified I/O code that no longer tracks individual operations in
    parallel to CBlibrary's data load, data save and global clipboard
    management code.
   Fading of the 'Paste' menu entry now relies on about-to-be-shown events
    generated by the root menu. Sending a Wimp message to the owner of the
    global clipboard when the 'Edit' menu was about to be shown didn't work
    on RISC OS 5 (probably because it doesn't update open menus).
   No longer uses a different error message for the specific case of an
    unsupported file type pasted from the clipboard.
   Moved the handler for messages generated by double-clicking a file in
    a directory display to a more sensible place.

1.69 (02 Aug 2022) ----------------------------------------------------------
   Check the return value of fclose() for error before marking a file as
    having no unsaved changes.

-----------------------------------------------------------------------------
13  Compiling the program
    =====================

  If you did not receive source code with this program then you can download
it from http://starfighter.acornarcade.com

  This program incorporates code from several C libraries created by the same
author: CBLibrary, CBOSLib, CBUtilLib, SF3KLib and GKeyLib. Source code for
those libraries is available at http://starfighter.acornarcade.com/mysite/

  To compile and link the program you will also require ISO 'C' (9899:1999)
library headers, stubs for the shared C library, and the flex, toolbox, event
and wimp libraries supplied with the Acorn C/C++ Development Suite. You must
ensure that the library directories clib, tboxlibs and flexlib are on your
C$Path, otherwise the compiler won't be able to find the required headers.

  Two make files are supplied:

   'Makefile' is intended for use with Acorn Make Utility (AMU) and the
    Norcroft C compiler supplied with the Acorn C/C++ Development Suite.
   'GMakefile' is intended for use with GNU Make and the GNU C Compiler.
    I have used it experimentally to compile but not to link the program.

  The APCS variant specified for the Norcroft compiler is 32 bit for
compatibility with ARMv5 and fpe2 for compatibility with older versions of
the floating point emulator. Generation of unaligned data loads/stores is
disabled for compatibility with ARMv6. When building the code for release,
it is linked with RISCOS Ltd's generic C library stubs ('StubsG').

-----------------------------------------------------------------------------
14  Licence and Disclaimer
    ======================

  This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public Licence as published by the Free
Software Foundation; either version 2 of the Licence, or (at your option)
any later version.

  This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public Licence for
more details.

  You should have received a copy of the GNU General Public Licence along
with this program; if not, write to the Free Software Foundation, Inc.,
675 Mass Ave, Cambridge, MA 02139, USA.

-----------------------------------------------------------------------------
15  Credits
    =======

  SFSkyEdit was designed and programmed by Christopher Bazley.

  This program contains a small but important section of code written by
Fednet themselves. The routine is used to render the sky preview, with minor
modification to conform to the APCS.

  Credit goes to David O'Shea and Keith McKillop for working out the
Fednet compression algorithm. David wrote a DeComp module for use with the
Stunt Racer track designer, which early versions of SFSkyEdit relied upon.

  Olaf Krumnow and Herbert zur Nedden of the German Archimedes Group wrote
the ResFind program I use to find the correct resources for different
languages.

  Thanks to the denizens of comp.sys.acorn.programmer for their advice - in
particular Kevin Bracey, Richard Murray and Stewart Brodie.

  Thanks to my brother Martin for his bug-spotting!

  The application name "SFSkyEdit" (including associated sprites/system
variables) has been officially registered with RISCOS Ltd.

  The game Star Fighter 3000 is  FEDNET Software 1994, 1995.

-----------------------------------------------------------------------------
16  Contact details
    ===============

  Feel free to contact me with any bug reports, suggestions or anything else.

  Email: mailto:cs99cjb@gmail.com

  WWW:   http://starfighter.acornarcade.com
