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 mouse cursor shapes used by the AES,
and a set of icons used by the desktop, both of which are treated as
partial resource files.  All of these are now maintained in resource
files rather than C source code: AES/GEM uses gem.rsc/gem.def and
mform.rsc/mform.def, and the desktop uses desktop.rsc/desktop.def and
icon.rsc/icon.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, ird, and mrd
(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.

Conditional inclusion of resource items
---------------------------------------
The source code generated by the resource decompilers does not support
conditional compilation depending on the configuration options.  This
means that all items in the resource file are included in the generated
C code, even if they are not required due to configuration options.
In order to reduce memory usage, a separate program (draft) performs a
preprocessing step and excludes items that are not required for the
current set of configuration options.  The decompiler processes the
output of draft rather than the full resource.  This extra step is
currently only required for the desktop resource.

*IMPORTANT*
If you add a tree (dialog), alert, free string, or menu item to the desktop
resource, and the new item is dependent on a configuration option, you
should update the exclude_items[] array in tools/draftexc.c so that draft
can exclude the new item where appropriate.


Object alignment in EmuTOS
==========================
Translations typically have a length different from the original
English text.  In order to keep dialogs looking tidy in all languages,
it is often useful to centre- or right-align text objects.  The AES
does not provide an easy way of doing this (alignment in TEDINFO objects
affects the text within the object, as well as object positioning).

To allow centre- or right-alignment of text objects, we steal unused
bits in ob_flags to indicate the required alignment.
The following bits are used:
    0x8000      centre-aligned
    0x4000      right-aligned
If both bits are set, centre alignment takes precedence.

Note that this does not require any changes to the AES, because this
extra function is performed outside the AES, and only for the internal
desktop resource.  Also note that this aligns the *object*, not the
text within the object.  It is perfectly reasonable (and common) to
have left-aligned text within a right-aligned TEDINFO object.

*IMPORTANT*
At the lowest level, the AES attempts to align text on screen byte
boundaries (see function gr_just()in gemgraf.c).  In doing this, it
takes into account text justification as specified in the TEDINFO
'te_just' variable, but it does not know that we have pre-aligned
objects as described above.  This can cause the horizontal position of
a pre-aligned string to be adjusted differently from that of a normal
string and, if the two types of string appear next to each other, they
may not be aligned with each other even though they should be.

There is no simple general fix for this without modifying the AES,
which is not desirable for compatibility reasons.  The problem is most
likely to show up with a dialog box that is not an even number of bytes
wide: when centered, it will start on a half-byte screen boundary, and
typically so will all contained strings (before any AES adjustment).

Normally, you can avoid this issue by ensuring that any dialog box
containing pre-aligned objects is an even number of bytes wide.  If
this does not help, increasing or decreasing the length of affected
pre-aligned strings by 1 byte should fix the problem.


An example of how to use the object alignment bits
==================================================
Suppose you have two or more objects (in the same box) that contain a
common feature (e.g. a colon).  You want to align that feature (i.e.
you want to make it appear at the same x-offset within the box), but
the text string that appears in front of that feature varies in length
for different languages.

First, mark each object as right-aligned.  Then, for each object, let:
    s = starting x offset
    w = width (assumed to be large enough for all languages)
    t = text length
    f = offset from start of text to alignment feature
The feature should be aligned in all languages if the value of (s+w-t+f)
is the same for all the objects.


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.


erd/grd/ird/mrd: the EmuTOS Resource Decompilers
================================================
These programs are compiled from the same source code; grd is generated
iff the preprocessor symbol GEM_RSC is defined, ird iff the symbol
ICON_RSC is defined, and mrd iff the symbol MFORM_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.
   This action 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.
   (g) text objects that consist of all dashes are assumed to be menu
       separator lines and are truncated to a single dash (they will
       be set up correctly during EmuDesk resource initialisation).
3. 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.
4. The mouse-form resource decompiler (mrd) decompiles the pseudo-BITBLKs
   use to store mouse cursors directly into MFORM data.  The BITBLKs
   themselves are not generated.

Program omissions
-----------------
The programs do 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, ird, or mrd
    -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
      mrd       -pmform
