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 , you would call ResFinder as follows: .ResFinder App which would, in the above example, set 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 Res$Path to point to language resources. This is not supported as standard by ResFinder (because Res$... is not part of the allocated $... namespace), however it can be easily done as follows: .ResFinder App AppRes$Path There is also an additional feature or two. These are discussed below. ResFinder syntax ---------------- The syntax is: ResFinder [] [-useos] where: Is the name of your application. It must match the system variable $Dir that has previously been set. If you do NOT want to use the default of $Path, you can specify a custom variable in which to receive the located resources, such as $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 .ResFinder Sakura would set Sakura$Path to point to the canonicalised result of: .Resources.UK.,.Resources.,. while: .ResFinder Sakura Sakura$Resources would set Sakura$Resources to point to the canonicalised result of: .Resources.UK [note: only the one directory, and with no trailing '.'] however: .ResFinder Sakura SakuraRes$Path would set SakuraRes$Path to point to the canonicalised result of: .Resources.UK.,.Resources.,. [note: so "SakuraRes:" works as it would be expected] BTW, "canonicalised" means you won't see , 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 as a base: If UTF-8: .Resources.[language].UTF8 Always: .Resources.[language] If [language] does not exist, and if ResFinder$Fallback is defined: If UTF-8: .Resources.[fallback].UTF8 Always: .Resources.[fallback] Then, always (unless [language] *is* UK!): If UTF-8: .Resources.UK.UTF8 Always: .Resources.UK Then, always: .Resources To give you an example, if France is the configured country and Germany is the fallback, with French resources, the path would be: .Resources.France.,.Resources.UK.,.Re sources.,. Again, using the same criteria, but there are no French resources but there are German ones: .Resources.Germany.,.Resources.UK.,.R esources.,. Again, same criteria, only with no resources other than UK: .Resources.UK.,.Resources.,. And, finally, same criteria, with French resources, only this time we're using UTF8: .Resources.France.UTF8.,.Resources.France.,.Resources.UK.UTF8.,.Resources.UK.,.Resourc es.,. 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 *.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: .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 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]