Modifying resources in EmuTOS
=============================
There are two built-in resource files in EmuTOS: the desktop and the
AES/GEM.  There is also a set of icons used by the desktop, which is
treated as a partial resource file.  All of these are now maintained
in resource files rather than C source code; the desktop uses both
desktop.rsc/desktop.def & icon.rsc/icon.def, and AES/GEM uses
gem.rsc/gem.def.  Changes are made "offline" with a standard resource
editor, and the changed file(s) replace the existing ones.  The make
process uses special-purpose resource decompilers erd, grd, and ird
(see below) to convert the .rsc/.def files into C source code which is
then compiled into the EmuTOS image(s).  All the resource decompilers
are built from the same source code, with some compile-time and
run-time differences.

Tips on using a resource editor with the current EmuTOS resources
=================================================================
1. Atari TOS and most resource editors support a maximum of 30 or 31
   characters per line in an alert; however, EmuTOS supports up to 40
   characters/line.  If you need to edit an alert with lines longer
   than the standard, you may need to make your resource editor treat
   the alert as a string to avoid mangling due to line truncation.
2. Some resource editors (such as Interface) have an option to optimize
   spaces in menu items.  You may need to disable this to avoid the
   "Sort by" menu items from being altered.
3. The generated C code for the desktop resource includes #ifdefs for
   conditionally-compiled code; this allows code space to be minimised
   for the 192K ROMs (see the list of EmuTOS-specific features below
   for more details).  When you add a dialog or a free string/alert to
   the desktop resource, *where* you add it will affect whether it is
   compiled conditionally or not.  If you want it to be compiled
   conditionally, you should add it at the end.  If you want it to
   be always compiled, you *must* add it before the start of the
   conditionally-compiled items; this is currently specified as ADTTREZ
   for dialogs, STNOOPEN for free strings/alerts.

erd/grd/ird: the EmuTOS Resource Decompilers
============================================
These programs are compiled from the same source code; grd is generated
iff the preprocessor symbol GEM_RSC is defined, and ird iff the symbol
ICON_RSC is defined.  They decompile the various resource files into .c
and .h files, which are input to the EmuTOS make process.  The programs
are similar to a general-purpose resource decompiler, but have a number
of EmuTOS-specific additions/changes, as well as a number of deliberate
omissions.

EmuTOS-specific features
------------------------
1. For compatibility with EmuTOS multi-language support, text strings
   (defined as strings containing any character other than a space, a
   digit or punctuation) are normally output to the .c file enclosed
   in the N_() macro.  This allows the EmuTOS multi-language support
   to identify this as a string to be translated.
   Additionally, strings consisting of all dashes (which are used to
   separate menu items in the desktop) are also enclosed in N_().
   Although such strings do not themselves need to be translated, their
   lengths may need to change to correspond to changes in menu item
   lengths, and enclosing the strings in the N_() macro makes them
   visible to the translation process.
   These actions may cause some strings to be unnecessarily marked as
   to-be-translated; therefore, before enclosing a string with N_(),
   the program references a "no translate" array containing strings
   that should _not_ be so enclosed.
2. The following features reduce ROM memory requirements (not all
   are applicable to all decompilers):
   (a) duplicate image data is automatically eliminated; multiple
       BITBLKs may point to the same image data.
   (b) duplicate icon data is automatically eliminated; multiple
       ICONBLKs may point to the same mask/data arrays.
   (c) strings in objects are trimmed of trailing spaces.
   (d) duplicate strings (strings that occur in more than one object,
       such as "OK") may be eliminated by including such strings in
       a "shared string" array; when this is done, the program will
       assign them to individual variables which are then pointed to
       by more than one object.
   (e) the te_ptext pointer in TEDINFOs is always set to NULL; this
       field is initialised properly by the resource fixup code
       elsewhere in EmuTOS.
   (f) the TEDINFO validation string, pointed to by te_pvalid, is
       optimized by removing duplicate characters from the end of
       the string.
3. For the desktop resource decompiler (erd) only, the following feature
   saves more ROM space when compiling for the 192K ROM images: the
   generated code for certain items is surrounded by a #ifdef/#endif
   wrapper.  This is based on three program-supplied values:
       . a starting free string name
       . a starting tree name
       . the #ifdef string (currently "#ifndef TARGET_192").
   All free strings with numbers greater than or equal to the number
   of the starting free string are wrapped.  Trees are treated in a
   similar fashion.  Objects/tedinfos/bitblks/iconblks that appear only
   in wrapped trees will also be wrapped.  Note that, at this time, this
   process does NOT extend to the images pointed to by bitblks/iconblks,
   but this could be added with some extra work.
4. For both erd and grd, all arrays of resource information are globally
   visible, and the normal resource fixup is performed by code within
   other parts of EmuTOS.  The resource initialisation routine only
   copies the OBJECT and TEDINFO arrays from initialised variables
   (which will be located in ROM) to globally-visible arrays, located
   in RAM.  This allows modification of OBJECTs and TEDINFOs.

Program omissions
-----------------
The programs does not handle CICONBLKs or USERDEFs, since they are not
currently found in the resource.  If they are added to the resource
later, it should be easy to add the appropriate code to the decompiler.

Program usage
-------------
The programs are invoked from the shell/commandline by:
    <program> [-d] [-p<prefix>] [-v] <RSCfile> <Cfile>

where:
    <program>   is erd, grd or ird
    -d          requests debugging output
    -p          specifies the prefix to apply to the names of all
                globally-visible generated data items
    -v          requests verbose output (start & end messages)
    <RSCfile>   identifies the input RSC/definition files
    <Cfile>     identifies the output .c/.h files

Notes:
 1. Filenames for input and output files
    File extensions should be omitted for <RSCfile> and <Cfile>.  The
    files used for input are <RSCfile>.rsc and <RSCfile.<def> where
    <def> is the definition file corresponding to the resource file.
    Existing resource construction programs generate definition files
    in one of 3 different formats, with differing extensions:
      .HRD      most recent, supports mixed case names up to 16 bytes
      .DEF/.RSD original, upper case names up to 8 bytes
      .DFN      slightly simplified version of .DEF/.RSD, with flag
                values in a different sequence
    The decompilers attempt to open the files in the above order,
    stopping when one is opened successfully.
 2. The prefix
    The -p option specifies a prefix to be applied to the names of all
    the arrays in the .c file.  If no prefix is supplied, but the input
    definition file is an HRD file, and it contains prefix information,
    that prefix will be used.  In either case, an underscore will be
    inserted between the prefix and the array name.  For example, a
    prefix of "my" will prefix each of the array names in the .c file
    with "my_".
    NOTE: for the current EmuTOS source, you should use the following:
      erd       -pdesk
      grd       (no prefix)
      ird       -picon
