
-----------------------------  !Verma (0.27c)  -----------------------------

                         Copyright : Somascape 1998

                               Author : Lenny

----------------------------------------------------------------------------

0.0  Contents
     ========

     1.0  Overview
     1.1    Features
     1.2    Limitations
     2.0  Iconbar
     2.1    Iconbar menu
     3.0  Modules in ROM/RMA
     3.1    ROM/RMA list menu
     3.2    Module menu
     4.0  Directory scanning
     4.1    Viewer menu
     5.0  The Module Detail window
     6.0  The Keyword Help window
     7.0  The Save window
     8.0  The Find window
     9.0  The Find Address window
    10.0  Scanning options
    11.0  Contacting the author

----------------------------------------------------------------------------

1.0  Overview
     ========

!Verma is a utility that displays version, etc information about
relocatable modules, both those in memory (ROM/RMA) and those on disc
(filetype &FFA) - in the latter case without the need to first install
them in the RMA.  These two types of module list involve different sets of
data, so two different window layouts are used.  Throughout this document
the former is referred to as the ROM/RMA window (or list) and the latter
as a Viewer.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

1.1  Features
     ========

 * Lists modules in memory (ROMs and/or RMA), showing each module's main
   details.  [ as of v0.20 ]

    * The familiar module maintainance commands are available from a menu,
      as is the ability to extract modules from the RMA, saving them to
      disc.

    * ROM/RMA modules can be listed alphabetically, by title.
      [ as of v0.23 ]

 * Module files or directories (including application dirs) may be dragged
   to !Verma's iconbar icon, whereupon it will display a Viewer window
   showing all modules found.

    * Options available from the iconbar menu allow scanning to recurse
      and/or include neighbouring objects.

    * Multiple Viewers are supported (handy if you want to visually
      compare directories of modules).

    * Support for long filenames (though leafnames are displayed truncated
      to 12 characters).  [ as of v0.17 ]

    * Multiple occurances of modules are indicated.

    * Modules that are also present in the RMA are indicated as such (by
      showing the version number of that in the RMA).

    * Clicking Shift-SELECT on an item in a Viewer will perform a
      Filer_OpenDir revealing that object.

 * The contents of module lists can be saved as a Text file (to disc or
   direct to another application).

 * Module lists can be searched for specific modules.  [ as of v0.19 ]

 * A Detail window (listing individual SWIs and keywords) can be opened
   from either type of module list window.  [ as of v0.20 ]
   Version 0.22 added flags and commands/keywords to the list.
   Version 0.24 added service details.
   Version 0.25 added podule info (requires RISC OS 3.50, or later).

    * Clicking on a Service number or SWI name in the Detail window will
      attempt a StrongHelp lookup, first loading StrongHelp if
      necessary/possible.

    * Clicking on a keyword in the Detail window will open the Keyword
      Help window.  [ as of v0.22 ]

    * The contents of the Detail window can be saved to disc as a Text
      file.  [ as of v0.22 ]

 * All of !Verma's windows use the current Desktop font if this is
   available (ie if the Nested Wimp version of the WindowManager is
   present), otherwise the System font is used.

 * A Dynamic Area will be used if the facility is available.  If DA's are
   not available, then application space is used.  [ as of v0.13 ]

 * Support for interactive help.  [ as of v0.20 ]

 * 26/32-bit neutral.  [ as of v0.20 ]
   0.26 and later are linked with StubsG, so Castle's 32-bit CLib is no
   longer required.

 * Support for ARMX6 and ARM7 based hardware.  [ as of v0.27c ]
   Note that the application's ProgInfo window still reports itself as
   0.27.  Sorry about that.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

1.2  Limitations
     ===========

 * Module files that are compressed (eg PPP, AcornURI) are indicated as
   such, though are not decompressed.  Hence any SWI or flags information
   for these is not revealed.  This does not apply to resident modules, as
   modules are decompressed by the OS upon loading into the RMA.

 * Command/keyword help for disc based modules can be less than
   satisfactory in instances where 'compacted' text is used.
   Only the first 42 entries of the RISC OS internal dictionary are common
   across different OS versions.

 * Directory scanning doesn't multitask.  Sorry about that, though the
   ESCAPE key can be used to abort a lengthy scan.

These shortcomings may be addressed in future versions.

----------------------------------------------------------------------------

2.0  Iconbar
     =======

 * Click SELECT on the iconbar icon to Open/Surface the ROM/RMA Modules
   window.

 * Click ADJUST on the iconbar icon to Open/Close the ROM/RMA Modules
   window.  When closing the ROM/RMA window, the Detail window will also
   be closed if its contents relate to a ROM/RMA based module.

 * Click MENU on the iconbar icon to open the iconbar menu.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

2.1  Iconbar menu
     ============

 * Info : The usual.  Additionally, it contains a pair of buttons :
   * Email : Attempts to open a Write email window (addressed to me).
   * Web   : Attempts to log onto my web site (software area).

 * Help : Runs this text file.

 * Address : Leads to the Find Address window.  See section 9.0.

 * Scan options : Leads to the (directory) Scan options submenu :

   * Neighbours : When ticked, scanning will include objects that are in
     the same directory as the dragged object.

   * Recurse : When ticked, scanning recurses down the directory tree.

   * Expanded pane : When ticked, Viewers will be opened with their pane
     already expanded (ie showing the additional Info field).  See section
     4.0.

 * Close Viewers : Closes all open Viewer windows.  The Detail window will
   also be closed if its contents relate to a disc based module.

 * Quit : The usual.

----------------------------------------------------------------------------

3.0  Modules in ROM/RMA
     ==================

Other programs offering similar features take the approach of presenting
information about ROM and RMA modules in separate windows.  !Verma uses a
single window which can be made to display either ROM or RMA modules, or
(uniquely, I believe) both together (using the popup Show menu in the
window's toolbar pane).

The following is shown for each module :

 * ROM : the ROM location or '-' if not a ROM-based module.  Modules in
   the system ROM are listed from 0 onwards, whereas modules from
   expansion card ROMs are shown with the format 'c:m', where 'c' is the
   expansion card number and 'm' is the ROM location within that ROM
   section (each 0 onwards).

 * RMA : the RMA location or '-' if not in the RMA (ie it's ROM-based and
   currently either Dormant or Unplugged).

 * Status : ROM modules have four possible states - Unplugged, Dormant
   (displaced by a module loaded into the RMA), Active or Running (as the
   currently paged application).  Modules that have been loaded from disc
   are shown as Loaded, to distinguish them from ROM sourced modules,
   though in reality they are Active.
   Note that you'll never see Running in !Verma's window as, at the time
   the information is gathered, !Verma is the current task and it isn't a
   module. :o)

 * Address : the address in memory at which the module resides.  This is
   coloured green for ROM-based modules that are running from their ROM
   location.  Modules running from the RMA, ie loaded from ROM (eg using
   RMFaster) or from disc are coloured blue.

 * Workspace : this is actually the module's 'private word', which is
   generally used as a workspace pointer (into RMA space), though not
   always.  If this is zero, '-' is shown.  Non-zero values deemed not to
   be a valid pointer are coloured red (most likely the private word is
   used directly for flags).

 * Title : the module's title, and if mutiply instantiated, including the
   instantiation postfix.

 * Version : the module's version and date details.

 * 32b : the state of the 32-bit-safe flag (Y or N). '-' is shown if there
   is no module flags word (interpreted by the OS as N).

 * SWIs : the number of SWIs provided by this module.

 * Chunk : the base SWI number for this module, or '-' if no SWIs.

 * Prefix : the SWI name prefix, or '-' if no SWIs.

Note that for Dormant and Unplugged modules, only the ROM location,
Status, Title and Version (excluding date) details are shown.


Clicking SELECT or ADJUST on an entry in this window will open/close the
Module Detail window listing individual SWIs and keywords etc.  See
section 5.0.


Due to the way the ROM and RMA modules are combined into a single list,
when showing the combined list (All modules) they are not listed in strict
numerical sequence (ROM/RMA location), which may initially confuse, though
there is a logic to it, as follows :

 * The ROM modules are enumerated first, a process which gives minimal
   information about each module (just status, title and version, exc
   date).

 * Then the RMA is enumerated, this process revealing greater detail per
   module.  Each module is compared with the ROM modules already listed :

    * Any that match on title and version are obviously ROM modules that
      are active/running, so the additional info is used to fill out this
      existing entry.  (cf other software that lists ROM modules
      separately, and thus with just the minimal details.)
      Only Dormant and Unplugged modules are shown with minimal info.

    * Any that match on title but not on version are modules that have
      been loaded from disc, displacing the ROM based version.  These are
      inserted in the list immediately after the matching entry.
      This has the advantage that dormant/unplugged modules and any
      replacement are listed together.

    * The remainder must have been loaded from disc, their details being
      added to the end of the list.

When showing either only ROM modules or only RMA modules, they are listed
in correct numerical sequence.  When showing both ROM and RMA modules,
they are (intentially) interleaved as described above.

When the AlphaSort switch is ticked, the modules are listed
alphabetically, by title.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

3.1  ROM/RMA list menu
     =================

Available by clicking MENU anywhere in the ROM/RMA Modules window.

 * Info : The same as on the iconbar menu.

 * Module : Leads to the Module submenu.  See section 3.2.

 * Refresh : Rescans the RMA and updates the window's contents.

 * Save : Leads to the Save window, enabling you to save the window's
   contents as a Text file.  See section 7.0.

 * Find : Leads to the Find window, enabling you to search for specific
   modules.  See section 8.0.

 * Clear : Removes any highlighting (resulting from a Find operation).

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

3.2  Module menu
     ===========

 * Enter : Start a module as a task.
   Only modules in the RMA, that can be started as an application (ie with
   a valid non-zero start address).

 * ReInit : Reinitialises a module, reversing Unplug status if necessary.
   Any modules, except Dormant/Unplugged for which there's already a later
   version in the RMA.

 * Insert : Reverses effect of Unplug, but does not reinitialise a module.
   Only Unplugged ROM modules, that don't have a later version in the RMA.

 * Faster : Copies a module from ROM to RAM.
   Only system ROM modules (ie not podule-based modules) that are not
   Unplugged or Dormant, and that are running from their ROM address.
   (Podule ROM based modules are always run from RAM anyway.)

 * Kill : Kills a module, removing it from the RMA.
   Any Active modules in the RMA.

 * Unplug : Prevent a module from being initialised upon a reset.
   Only for Active ROM modules, or Dormant ones for which there isn't a
   later version in the RMA.

 * Extract : Save a module from the RMA to disc.
   For any Active/Running modules (ie in the RMA).  Earlier versions only
   allowed ROM modules to be extracted, though this restriction has been
   relaxed, so it is now possible to save a module to disc, even if it
   originated from disc (the original file may have been 'compressed').

----------------------------------------------------------------------------

4.0  Directory scanning
     ==================

Simply drag a Module file (or directory of) to !Verma's iconbar icon.

In obeyance with the scanning options (Neighbours and Recurse) a Viewer
window is opened showing all modules found, listing for each module :

 * Leafname, Title and Version/Date.

 * If a module with the same title is already in the RMA, then its version
   number is shown, for easy comparison.  This is coloured grey if the RMA
   version is more recent, or red if the disc version is the more recent.
   Note that the RMA is rescanned immediately prior to assesing the
   dragged file or directory, to ensure that any comparisons are current.

 * The state of the 32-bit-safe flag, if present, is shown (a '-'
   indicates there is no flags word).

 * For modules that provide SWIs, the number of SWIs, the Chumk number (in
   hex) and the SWI Prefix are also shown.

A Viewer's pane area can be expanded (using the top-right triangular
button) revealing an extra Info icon, that gives additional info re the
module currently under the pointer (the full filename, help string, module
flags, or SWI area).

Multiple occurances of modules (ie with the same Title) are indicated, by
the red numbers on the left of the Viewer.  The 'M' in the header pane is
coloured red if any multiple occurances are found, or black if there are
none.

Multiple Viewers are supported, and you can also drag a module (or
directory of) into an already open Viewer to replace its contents.

If you attempt to scan an object that is located in your hard disc's root
directory when both the Neighbours and Recurse options are ticked, !Verma
pops up an alert warning you that this action would involve scanning the
ENTIRE disc, and gives you the option of aborting the scan.  So, if you
wish to recursively scan (eg) !Boot, then it is probably a good idea to
untick Neighbours.

If you wish to interrupt a lengthy scan, press the ESCAPE key.


Clicking SELECT or ADJUST on an entry in this window will open/close the
Module Detail window listing individual SWIs and keywords etc.  See
section 5.0.

Shift-clicking SELECT or ADJUST on an entry in a Viewer will perform a
Filer_OpenDir revealing that object.

Adjust-closing a Viewer will open a Filer window for the associated path.
Combine with Shift to open the Filer window, without closing the Viewer.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

4.1  Viewer menu
     ===========

 * Info : The same as on the iconbar menu.

 * Refresh : Rescans the same path, using the now current scan options.
   Note that the RMA is rescanned immediately prior to the path rescan,
   to ensure that any comparisons are current.

 * Save : Leads to the Save window, enabling you to save the window's
   contents as a Text file.  See section 7.0.

 * Find : Leads to the Find window, enabling you to search for specific
   modules.  See section 8.0.

 * Clear : Removes any highlighting (resulting from a Find operation).

----------------------------------------------------------------------------

5.0  The Module Detail window
     ========================

This window can be opened from either type of module list.

The upper pane shows the module's title and version/date information,
whether it is located in ROM, RMA or on disc, and the version that is
currently active in the RMA (if any at all).

The main window area shows the module's help text, flags and service
details, and lists any SWIs and/or keywords that are provided by this
module.  If the module is located on podule ROM, then the podule is
identified (this feature requires RISC OS 3.50, or later - 3.10 users will
not see any podule related info).

There are three possibilities for the Flags section (the first two are
only mentioned if true) :

 * whether the module can be started as an application.
 * whether the module's code area will be retained upon quitting the
   module (determined by bit 31 of the finalisation offset).
 * 32-bit readiness.

In the Services section, the type of service handler present (if any) is
reported.  If a RISC OS 4 style fast service handler is present, the
service numbers supported are listed (sorry no service number details for
old style service handlers).

Clicking on a Service or SWI entry will attempt to perform a StrongHelp
lookup, loading StrongHelp first if necessary (and if 'seen').

Clicking on a command/keyword will open/surface/close the Keyword Help
window.  See section 6.0.

Clicking MENU opens a menu allowing the window's contents to be saved as a
Text file.  See section 7.0.

----------------------------------------------------------------------------

6.0  The Keyword Help window
     =======================

This just displays the help info associated with a command/keyword.

There is a problem that I have been unable to work around re help text
that contains 'compacted' text, ie that uses the RISC OS internal
dictionary.  This only affects disc based modules, where I have to
manually extract the help information (with RMA based modules I can get
the OS to extract the info).  The problem is that only the first 42
entries in the internal dictionary are fixed, the remainder being
generated dynamically on a per OS basis.  So if a disc based module
contains compacted help text with dictionary entries higher than 42,
you'll see '[PPn]' instead of what token 'n' would decode to.

This window doesn't have a menu.

----------------------------------------------------------------------------

7.0  The Save window
     ===============

The Save window allows the contents of a module list or the Detail window
to be saved as a Text file (to disc or direct to another application). 
Switches in the Save window provide control over the degree of detail.

It is permissable to use a path variable (eg 'MyPath:ModInfo'), though if
any such variable contains multiple paths, it will be rejected as an
invalid filename.

----------------------------------------------------------------------------

8.0  The Find window
     ===============

The Find window allows the contents of a module list to be searched for
specific modules.  Radio icons allow you to search by Title, Help text,
SWI chunk number, SWI prefix, or for all instances of a given multiple
occurance (if searching the ROM/RMA list, then Help text and Multiple are
faded, as searching these fields is not possible/relevant) :

 * Title, Help text, SWI prefix :
   A case-insensitive substring search is performed.

 * Chunk number :
   6 hex characters (max).  Any number of '#' characters may be used as
   single character wildcards.

 * Multiple occurance :
   Use the bump icons to specify the instance (equating to the number
   shown in red on the left of the Viewer display).  The associated module
   title is shown immediately below.

Click on Find to perform a fresh search whereupon each row for which a
match was found is highlighted, and the window is scrolled to reveal the
first match.  This highlighting remains until another search is performed
or the relevant menu's Clear option is used.

Clicking on Find Also will not clear any previous highlighting prior to
performing the search.

Note that for the ROM/RMA window, any highlighting will be cleared when
performing a Refresh, or changing the Show mode (ROM, RMA, All), but not
when just toggling the AlphaSort mode.

----------------------------------------------------------------------------

9.0  The Find Address window
     =======================

The Find Address window allows the user to enter an address which is
passed to Justin Fletcher's Addr utility.  Thus all the functionality
behind this window is due to Justin's utility.

It is useful for tracking down the source of errors.  Eg if you receive an
'Address exception at address xxx' error, just enter the value reported
(xxx) into this window, and Addr will identify the code responsible.

If Addr is not found on <Run$Path> the menu option leading to this window
is faded.  It is up to the user to obtain a copy of Addr if they wish to
use this facility.

----------------------------------------------------------------------------

10.0 Scanning options
     ================

Sorry this bit isn't in English, though a truth table should at least be
unambiguous ...

The scope of the directory scanning when a filer object is dragged to
!Verma's iconbar icon is determined by three factors : whether a module
file or a directory/app is dragged to !Verma, and the state of the two
options, Neighbours and Recurse :

  Obj = the object dragged to !Verma (M=Module, D=Directory)
  N   = state of Neighbours option (1=ticked, 0=not ticked)
  R   = state of Recurse option (1=ticked, 0=not ticked)

  'parent' is the directory in which the 'object' resides.

  --------------------------------------------------------------------
   Obj  R   N   |  Display                           |  Re.
  --------------------------------------------------------------------
    M   0   0   |  A single module                   |  object
    M   0   1   |  All modules in a single dir       |  parent
    M   1   0   |  A single module                   |  object
    M   1   1   |  All modules in a dir recursively  |  parent
    D   0   0   |  All modules in a single dir       |  object
    D   0   1   |  All modules in 2 dirs             |  parent+object
    D   1   0   |  All modules in a dir recursively  |  object
    D   1   1   |  All modules in a dir recursively  |  parent
  --------------------------------------------------------------------

----------------------------------------------------------------------------

11.0 Contacting the author
     =====================

For bug reports, suggestions, sighs of adulation, derisive comments or
submission of gratuities, please contact me (Lenny) :

  email: riscos@somascape.org   (Use the button in the Info window.)

----------------------------------------------------------------------------
