=============================================================================
MkResApps - ResourceFS Utility                                   Version 1.10

(c) Stephen Fryatt, 1997                                      6 December 2002
=============================================================================


License
-------

  MkResApps is FREEWARE.  Copyright is held by the author, Stephen Fryatt,
  1997.

  MkResApps may be copied freely, so long as it remains unaltered with all
  its files and documentation intact.

  If you wish to distribute MkResApps, please contact me to get my
  permission.  This is so that I can ensure that you have the latest version
  available.  MkResApps may not be sold, although Public Domain libraries may
  charge for the cost of discs.

  No guarantee is made as to the suitability or stability of MkResApps for
  any particular purpose.  No liability can be accepted by the author for any
  loss or damage caused by the use of MkResApps.



Introduction
------------

  MkResApps is a small BASIC utility that creates a Relocatable Module to add
  links to files, directories and applications to the ResourceFS.  The
  utility works from the command line, producing the required module from a
  source text file.

  It is more flexible than the RISC OS 3.5+ AddApp utility in that it can
  handle nested directories; it also pre-assembles the module so that the
  time to execute your !Boot sequence is minimised.  MkResApps can also
  handle links to directories and files on your hard disc.



Installing MkResApps
--------------------

  MkResApps requires RISC OS 3.1 or later.  The module that it produces is
  26/32-bit neutral and should work on RISC OS 5.  The utility can be run off
  a hard disc or floppy disc, but to get any benefit from the resulting
  module, you will need to have a boot sequence.

  To install MkResApps on a hard disc, copy the MkResApps BASIC file to a
  suitable place on your disc.  Ideally this should be your Library, so that
  it can be run from the command line; failing that, make sure that it is in
  your currently selected directory (CSD) whenever you need to use it.

  If you have a RiscPC or a version of the new Boot, copy the ResFSApps
  directory into your Choices:Boot.Predesk directory.  On an older machine,
  if you want to use the two filetypes you must ensure that the !Run file
  inside the directory gets run when the machine is turned on, and that any
  modules created by MkResApps are saved in here with the filename ExtraApps.

  MkResApps uses two filetypes from the User Area to allow it to link to
  directories and files (it can be made to use Obey files instead by adding a
  command line option, see below).  To change the filetypes used, load the
  MkResApps program into an editor and change the lines near the top that
  read

    dirlink_file%=&0DA
    filelink_file%=&0DB

  to the new filetypes.  Also change the lines in the !Run file that read

    Set Alias$@RunType_0DA Obey %%*0
    Set Alias$@RunType_0DB Obey %%*0

    Set File$Type_0DA DirLink
    Set File$Type_0DB FileLink

  and rename the sprites in !Sprites and !Sprites22 appropriately.



Using MkResApps
---------------

  MkResApps is a command-line utility that uses a text file containing the
  files you want to include to create a relocatable module.  Instructions are
  given here for use under the various versions of RISC OS, and for using the
  program itself.


  Using the Module on RISC OS 3.5
  -------------------------------

  Under RISC OS 3.5 it is possible to completely replace the applications
  stored in the 'Apps' folder on the icon bar.  This was the original purpose
  for which I wrote MkResApps: Resources has now become a simple application
  launcher.

  To remove the existing applications from the Resources folder, you must
  edit the file Choices:Boot.PreDesktop.  Load it into a text editor and find
  the line that reads

    AddApp Boot:^.Apps.!*

  You must comment this out, by placing a vertical bar ("|") at the start of
  the line.

  In order to replace the applications in ResourceFS, they must be included
  in the Apps folder on the Resources: path.  This is the default action that
  MkResApps takes: you do not need to specify the "-root" option when
  creating the module.

  To make your module load on start up, save it within the
  Choices:Boot.PreDesk folder.  If you specify no "-module" (or "-outfile")
  option, MkResApps does this for you.


  Using the Module on RISC OS 3.1
  -------------------------------

  Under RISC OS 3.1, it is not possible (as far as I know) to remove the ROM
  Apps from the Apps folder on the icon bar.  Because of this, you can only
  add more applications.  These can either be in the root directory (as are
  !Paint and !Draw etc.) or they can be put into their own folder.  In this
  case, use the "-root" option, such as "-root Apps.NewApps".  This would put
  the extra files within a folder called NewApps.  Note that the root path
  must start with Apps if you wish the extra applications to be available
  from the 'Apps' folder on the icon bar.


  Using the Module on RISC OS 3.6 and RISC OS 3.7
  -----------------------------------------------

  I'm not sure if you can remove the existing applications from the 'Apps'
  folder under these versions of the OS.  See the relevant section above for
  details on what to do, depending on whether or not this is possible.



Creating Source Files
---------------------

  Source files have the following syntax, which bears more than a passing
  resemblance to C.

  The applications, directories and files to add are specified by their full
  pathname on your hard disc, and terminated by a semicolon (";"):

    ADFS::Gromit.$.MainApps.DiscIndex.!Index;

  To specify the directory structure in the Apps Folder, directories are
  indicated by their name followed by curly braces ("{", "}"):

    Directory
    {
    }

  Applications (or further directories) to appear within are listed inside
  the curly brackets: This produces a structure something like this:

    ADFS::Gromit.$.MainApps.DiscIndex.!Index;
    ADFS::Gromit.$.MainApps.Others.Editors.!Family;
    ADFS::Gromit.$.MainApps.Others.Editors.!Innovate;
    ADFS::Gromit.$.MainApps.Others.Editors.!TelAddr;

    Accounting
    {
      ADFS::Gromit.$.MainApps.Others.Editors.!Accounts+;
    }

    Database
    {
      ADFS::Gromit.$.MainApps.Others.DataBase.!Designer;
      ADFS::Gromit.$.MainApps.Others.DataBase.!Manager;
    }

    ADFS::Gromit.$.MainApps.Others.Misc.!Lottery;
    ADFS::Gromit.$.MainApps.Others.Misc.!MacroLife;
    ADFS::Gromit.$.MainApps.Others.Misc.!WorldTime;

  This would produce the following directory structure:

    Resources:Apps --- !Index
                    |- !Family
                    |- !Innovate
                    |- !TelAddr
                    |
                    |- Accounting --- !Accounts+
                    |
                    |- Database   --- !Designer
                    |              |- !Manager
                    |- !Lottery
                    |- !MacroLife
                    -- !WorldTime



Creating the Module
-------------------

  Once you have saved the source file to disc, create the module using the
  MkResApps program.  Save MkResApps in your Library or put it in the CSD and
  then use the "MkResApps" command.

  MkResApps -source <sourcefile> [-module <modulefile>]

    The "MkResApps" creates a module to add dummy applications to ResourceFS.
    It can be abbreviated to simply

      MkResApps <sourcefile> [<modulefile>]

    The following options are supported:

    -source (or -in) <source>

      Specifies the module source file.  This must be supplied.

    -module (or -out) <module>

      Specifies the module to be created.  If none is specified, the module
      is saved in the Choices:Boot.PreDesk directory on a RiscPC.  An error
      will occur if this option is missed out on RISC OS 3.1 (unless you have
      emulated the RISC OS 3.5+ !Boot structure).

    -root <rootdir>

      Specifies the root directory to use in the Resources: path.  If
      omitted, the default of Resources:Apps is used.  The option
      "-rootNewDir.Folder" would put all the files in
      Resources:NewDir.Folder.

    -nohelp

      Do not include links to !Help files.

    -obey

      Use obey files instead of the custom types for links to directories and
      files.

    -verbose

      Print information about each object that is added to the module.

    If any objects don't exist, they will be reported along with a line
    number in the module source file.  Check that you have not mis-typed the
    pathnames, and that all preceding semicolons are present.

    Once the module has been constructed, it is saved and also copied
    directly into the RMA and started as a module.  This allows you to test
    your new module immediately: the files will (or at least should) appear
    in the Apps folder at once!



What MkResApps does
-------------------

    MkResApps creates a module which adds files to the ResourceFS.  To save
    space in memory, it only adds 'dummy' applications containing at most
    three files: !Run, !Boot and !Help.  These are all Obey files and simply
    provide links to the real files.

    !Run files must always be included.  These contain only one line, of the
    form

      /<RealApp$Dir>.!Run

    This will run the real !Run file when the dummy application is
    double-clicked.

    !Boot files are more tricky.  If the real application contained a !Boot
    file, the dummy !Boot contains a line of the form

      /<RealApp$Dir>.!Boot

    so that opening the directory with the dummy application inside will
    cause the real !Boot file to be run.  If the real application had no
    !Boot, but did have a file with the name !Sprites and type FF9 then the
    dummy !Boot contains

      IconSprites <RealApp$Dir>.!Sprites

    to cause the application's sprites to be loaded into the Wimp pool.  If
    all this fails, no !Boot file is included.

    The !Help file is only checked if the "-nohelp" option is not given.  In
    this case, any object in the real application called !Help will create an
    Obey file in the dummy application called !Help containing the line

      Filer_Run <RealApp$Dir>.!Help

    This causes the !Help object (whatever it may be) to be run when the
    dummy application's filer Help option is chosen.

    Directories and files are simply linked to by Obey files (possibly with a
    different filetype and icon) that "Filer_OpenDir" or "Filer_Run" the
    required object.



Version History
---------------

    The following is a list of all the versions of MkResApps.


  0.03 (6 June 1997)
  ------------------

    * Initial release version.


  0.04 (27 May 1998)
  ------------------

    * Bug fix to stop multiply nested directories in the resources: structure
      from confusing the program.


  1.00 (23 July 1999)
  -------------------

    * Added support for links to files in the resource system.
    * Allows Obey files to be used instead of MkResApps' own file types.
    * Removed the Verbose option.


  1.01 (24 July 1999)
  -------------------

    * Some internal tweaks to remove global variables.
    * Documentation overhaul.
    * Reimplemented the Verbose option correctly.


  1.10 (6 December 2002)
  ----------------------

    Public Beta release.

    * Generated module converted to new format and checked for 32-bit
      compatibility.



Updates and Contacting Me
-------------------------

  If you have any comments about MkResApps, or would like to report any bugs
  that you find, you can email me at the address below.

  Updates to MkResApps and more programmes for RISC OS computers can be
  found on my website at http://www.stevefryatt.org.uk/software/

  Stephen Fryatt
  email: steve@stevefryatt.org.uk
