ResFinder v0.07  (2014/02/15)
===============


What is ResFinder?
------------------

ResFinder is a simple, light, utility that will set your application's Path
to point to the location where your resources should be, depending on the
currently selected language.

The traditional layout is:

  $.!MyApp
     Resources
       France
       Germany
       UK

Using ResFinder, you can have your Path set to point to the appropriate
resources, which you can load in by simply looking for those resources at
that path.

To clarify, if your application defines the variable <MyApp$Dir>, you would
call ResFinder as follows:
  <App$Dir>.ResFinder App
which would, in the above example, set <App$Path> to be:
  $.!App.Resources.UK.,$.!App.Resources.,$.!App.
if your current language is English, or:
  $.!App.Resources.France.,$.!App.Resources.UK.,$.!App.Resources.,$.!App.
if your current language is French.

Within your program, you need only look for:
  App:Templates
and
  App:Messages
and the like. The path will point to the correct resource. In addition, as
the path contains multiple locations, it will search the directories in the
order given, so only specifically internationalised resources need to be
placed in the country-specific directories. General things that are the
same (sprites, perhaps?) can go into the Resources directory. They will be
found as well.
For example, this works:
  Type App:!Help
If there is a French version in the France directory (and with French as
the language to prefer) then it will supply the French version. Else, it
will step backwards until it finds one, even if this is !App.!Help.

  

AS AN ALTERNATIVE, the "de facto" standard is to use <app>Res$Path to
point to language resources. This is not supported as standard by ResFinder
(because <app>Res$... is not part of the allocated <app>$... namespace),
however it can be easily done as follows:
  <App$Dir>.ResFinder App AppRes$Path


There is also an additional feature or two. These are discussed below.



ResFinder syntax
----------------

The syntax is:

  ResFinder <appname> [<path var>] [-useos]
  
where:

  <appname>    Is the name of your application. It must match the system
               variable <appname>$Dir that has previously been set.
  
  <path var>   If you do NOT want to use the default of <appname>$Path, you
               can specify a custom variable in which to receive the
               located resources, such as <appname>$Resources.
               You should specify the variable without its enclosing angle
               brackets.
               NOTE: Custom path variables are created WITHOUT the trailing
                     dots and ONLY the country-specific path UNLESS the
                     variable ends with "$Path".
  
  -useos       By default, ResFinder will ask the Territory module what the
               current system language is.
               However there may be instances when you might prefer the OS
               to be in English (UK territory) but your applications to be
               in your local language (if available) [hello Steffen!] by
               having the "Country" setting be different, instead of the
               entire Territory.
               If you speak English, you probably won't need to worry about
               this. ;-)



Basic examples
--------------

  Set Sakura$Dir <Obey$Dir>
  <Sakura$Dir>.ResFinder Sakura
would set Sakura$Path to point to the canonicalised result of:
  <Sakura$Dir>.Resources.UK.,<Sakura$Dir>.Resources.,<Sakura$Dir>.

while:
  <Sakura$Dir>.ResFinder Sakura Sakura$Resources
would set Sakura$Resources to point to the canonicalised result of:
  <Sakura$Dir>.Resources.UK
  [note: only the one directory, and with no trailing '.']
  
however:
  <Sakura$Dir>.ResFinder Sakura SakuraRes$Path
would set SakuraRes$Path to point to the canonicalised result of:
  <Sakura$Dir>.Resources.UK.,<Sakura$Dir>.Resources.,<Sakura$Dir>.
  [note: so "SakuraRes:" works as it would be expected]


BTW, "canonicalised" means you won't see <Sakura$Dir>, you would see the
actual path used, like SDFS::RISCOS.$.Apps.!Sakura or the like.



Unicode migration
-----------------

In order to assist with a migration to UTF-8, if the current "Alphabet" is
UTF8, then the current language OR fallback language, and UK, will be
searched for FIRST with a ".UTF8" suffix, then without.
For example:
  !Sakura.Resources.France.UTF8       - French resources (UTF-8)
  !Sakura.Resources.France            - French resources (Latin)
  or:
  !Sakura.Resources.Germany.UTF8      - German resources (UTF-8)
  !Sakura.Resources.Germany           - French resources (Latin)
  then:
  !Sakura.Resources.UK.UTF8           - British English resources (UTF-8)
  !Sakura.Resources.UK                - British English resources (Latin)



Fallback language
-----------------

There may be cases where a person would prefer to fall back to a language
other than English. For instance, a Dutch person may be more fluent with
German than English, so would prefer Dutch (if available), German as a
fallback if there's no Dutch, and English as a last-choice option.

To invoke this behaviour, simply set the system variable ResFinder$Fallback
to the name of the desired fallback language, for example:
  *Set ResFinder$Fallback Germany



Scanning order
--------------

ResFinder does not actually *look* for resources, it just looks for where
resources should be.

The order of scanning is as follows, using <Sakura$Dir> as a base:

If UTF-8:    <Sakura$Dir>.Resources.[language].UTF8
Always:      <Sakura$Dir>.Resources.[language]

If [language] does not exist, and if ResFinder$Fallback is defined:
  If UTF-8:  <Sakura$Dir>.Resources.[fallback].UTF8
  Always:    <Sakura$Dir>.Resources.[fallback]

Then, always (unless [language] *is* UK!):
If UTF-8:    <Sakura$Dir>.Resources.UK.UTF8
Always:      <Sakura$Dir>.Resources.UK

Then, always:
             <Sakura$Dir>.Resources
             <Sakura$Dir>


To give you an example, if France is the configured country and Germany is
the fallback, with French resources, the path would be:
  <Sakura$Dir>.Resources.France.,<Sakura$Dir>.Resources.UK.,<Sakura$Dir>.Re
  sources.,<Sakura$Dir>.

Again, using the same criteria, but there are no French resources but there
are German ones:
  <Sakura$Dir>.Resources.Germany.,<Sakura$Dir>.Resources.UK.,<Sakura$Dir>.R
  esources.,<Sakura$Dir>.

Again, same criteria, only with no resources other than UK:
  <Sakura$Dir>.Resources.UK.,<Sakura$Dir>.Resources.,<Sakura$Dir>.

And, finally, same criteria, with French resources, only this time we're
using UTF8:
  <Sakura$Dir>.Resources.France.UTF8.,<Sakura$Dir>.Resources.France.,<Sakur
  a$Dir>.Resources.UK.UTF8.,<Sakura$Dir>.Resources.UK.,<Sakura$Dir>.Resourc
  es.,<Sakura$Dir>.

It's the same if using fallback (Germany.UTF8, Germany, UK.UTF8, UK), and
likewise if only setting up English resources (UK.UTF8, UK).


Obviously, this depends upon the presence of said resources...


Just a clarification - the use of [language] and [fallback] is an either/or
which means you will be defining [language] OR [fallback]; not both at the
same time.



Additional features
-------------------

ResFinder sets two additional system variables.

  ResFinder$Language
  
  This is set to the language that ResFinder was looking for, for your
  resources. For many of you, this will say "UK".
  Note that if you have a multilingual setup, the "-useos" option may alter
  the language available.
  
  
  ResFinder$PlatformClass
  
  It is a pain to try to work out what sort of machine RISC OS is running
  on, so let ResFinder work it out for you!
  ResFinder will not tell you EXACTLY what the system is, just the class,
  which should be sufficient for most purposes.
  
  ResFinder$PlatformClass is set to a numerical value, as follows:
  
    0 - System could not be identified
    
    1 - A "Mesolithic" system, in other words, anything at all that is
        running in 26 bit PC+PSR mode. Archimedes, RiscPC, VirtualRPC...if
        it is 26 bit, it is this.
        [you could use the OS version OS_Byte 129,0,&FF ->R1 to further
         narrow down the possibilities for older systems, where it is likely
         that the OS version will matter more than the hardware...]
        NOTE: ANYTHING 26bit is this. You may assume ALL the rest are 32bit.
    
    2 - RiscPC or RiscPC-like (A7000, RPCEmu, etc).
    
    3 - Iyonix.
    
    4 - OMAP3: Beagle, Beagle xM, IGPV, etc.
    
    5 - OMAP4: Pandaboard.
    
    6 - RaspberryPi.
    
  This does not base assumptions on specific system modules or the like, it
  first asks the HAL; and if the HAL does not know, it probes the CPU to
  determine what sort it is.
  
  Any non-ROOL or otherwise incompatible 32 bit version of RISC OS is likely
  to be flagged as an unknown system. This will only affect the version of
  RISC OS running on the A9home, and since ROLtd appear to have never
  finished that (Adjust 32 v4.42) version of the OS.......
  

It is possible to use this functionality of ResFinder without checking or
setting resource paths.

Simply specify the application name as "null" (lower case), like this:

  ResFinder null
or:
  ResFinder null -useos



Help, support, etc
------------------

This version of ResFinder is available from:

  http://www.heyrick.co.uk/software/resfinder/
  
You can email me at:

  heyrick 1973 -at- yahoo -dot- co -dot- uk

You may also see me in the ROOL forums.



Licence
-------

ResFinder is Copyright  2014 Richard Murray.
Licensed under the EUPL v1.1 only.

You will find a short PDF describing the EUPL along with this software.


One specific note, for clarity, is that the open source licence applies
specifically and only to this EXECUTABLE - and any request for source code
under the licence will cover ONLY this EXECUTABLE and not any part of that
which this EXECUTABLE is used alongside; thus this open source executable
may be used in a closed-source commercial package provided that the various
terms of the licence are respected (ie, provide source to ResFinder if you
modify it, or point people to my website if you don't, etc etc).
[just sayin', 'cos some people have real weird ideas about stuff like GPL]



Something went wrong?
---------------------

My computer is not correctly identified!
  Tell me. Tell me what sort of computer it is, and what ResFinder
  incorrectly identified it as. Note that ALL 26 bit machines are considered
  identical; and the RiscPC class machines likewise.
  
My language settings are wrong.
  Try using/not using the -useos option. Without reads the Territory version
  of the system language, with uses the *Country setting.

The reported path is just a dot, huh?
  If you are seeing something like this:
    *ResFinder MyApp
    *Show MyApp*
    MyApp$Path : .
    *
  then this is because you have asked ResFinder to look for resources for
  an application without its location having been defined yet.
  Try this:
    *Set MyApp$Dir <Obey$Dir>
    *<MyApp$Dir>.ResFinder MyApp
    *Show MyApp*
    MyApp$Dir : SDFS::RISCOS.$.Coding.Projects.ResFinder.Test
    MyApp$Path : SDFS::RISCOS.$.Coding.Projects.ResFinder.Test.Resources.UK.
    ,SDFS::RISCOS.$.Coding.Projects.ResFinder.Test.Resources.,SDFS::RISCOS.$
    .Coding.Projects.ResFinder.Test.

Why does the auto-generated path have a '.' following, but custom ones not?
  Custom paths ONLY have a '.' following if they end with "$Path". This is
  because variables that are something$Path have a special meaning to RISC
  OS, so you can use something: to refer to that path. As the OS replaces
  the "something:" part with the path, it must end with a '.' or else the
  final result won't make sense.
  Accordingly, ResFinder auto-generates a variable for you that will work
  correctly within RISC OS. MyApp: or Sakura: or whathaveyou.
  If you specify a custom system variable to set, it will not behave like
  the Path variable, so it will not have the trailing '.'.
  For example:
    ResFinder Sakura
  gives you:
    Sakura$Path
  so you can load:
    Sakura:Templates
  However:
    ResFinder Sakura Sakura$Resources
  gives you:
    Sakura$Resources
  so you should load:
    <Sakura$Resources>.Templates

  You can, however, set paths as follows:
    ResFinder Sakura SakuraRes$Path
  which would give you:
    SakuraRes$Path
  so you can load:
    SakuraRes:Templates
    
Why do non-path custom variables not include all the parts like $Path does?
  Because that doesn't work. The multiple-location scanning behaviour is
  specific to paths and how the filesystem deals with paths.

You could parse the custom variable and pass it to OS_File as a path?
  The point is to remove the need for the author to write such things. The
  aim is that the author needs only specify "Sakura:Templates" and the OS
  will handle the rest, using the predefined path variables.

Why don't you set <appname>Res$Path like the original ResFind?
  Simple. When you register an application, such as "Sakura", this gives you
  the right to call your application !Sakura; to include sprite resources
  called !sakura, sm!sakura, ic_sakura; and to create system variables that
  begin "Sakura$".
  Thus, a variable beginning "SakuraRes$" is not within the allocated
  namespace and should not be used (unless registered separately).
  There are circumstances where this might be desirable, for instance the
  main path pointing to the application for static resources (data files
  and the like) and the resources path pointing to the language-specific
  resources. In this case, use the custom system variable to specify your
  own path.
  If you wish to use something akin to SakuraRes$Path - you should include
  this in the registration for your application.

Which is better, Territories or country codes?
  You'll probably want to "-useos" as a matter of course... As to what and
  how, there are arguments on both sides.
  
Why don't you use country numbers like the Toolbox does?
  Because "Res" and "Res7" and such are often not in separate directories
  so the path method won't work; plus outside of the Toolbox, pretty much
  everybody else seems to have standardised themselves on the method of
  using ...Resources.[countryname] to hold their resources.
  If you disagree, you probably won't want to use ResFinder. ;-)

What kind of person writes something like this in assembler?
  Me.
  (^_^)
  

[end]
