
Module Internationalisation.
----------------------------

1. Messages.

   Any text in the module body should be replaced by text coming from a
messages file, this includes and single character strings which are referred
to in the module. The only exception is Help and Syntax text which should
remain in the module as well as being put in two separate messages files, the
token used for the help and syntax messages should be the command itself.

 The messages file.

   The messages file should not be included in the module itself. It will be
combined into a central Messages module which will provide all the messages
files for all system modules. The path for the messages file for module X
would normally be: Resources:$.Resources.X.Messages.

 Opening the messages file.

   The messages file should be opened on service PostInit, this service is
issued immediately after all the modules have been initialised, and
therefore ensures that both ResourceFS and the messages module have been
initialised, and that the messages file can be found. This means that the
messages file is not available during the initialisation of the module, If
any text has to be printed during the initialisation of the module, you
should do the following:

      Try and open the messages file.
            If you get an error message, print the text in English.
            Otherwise use the messages file to print text.

   At the moment opening the messages file will always fail, or open the
English messages file which is in the ROM, but this enables us to replace
the messages in the ROM with messages for another language, without making
any further changes to the modules.

The code to open the message file should look like this:

        ADR     r0, MessageFile_Block
        ADR     r1, message_filename
        MOV     r2, #0
        SWI     XMessageTrans_OpenFile


   Reading from the messages file:
 
   MessageTrans should be used for all access to the messages file.
   All text to be printed should be read from the messages file.

   Errors:                
   =======


        At the moment the code for returning errors should look something
like the follwoing:

             ADR        R0,ErrorBlock_AnError
             SETV
             Pull       "....,PC"

To enable translation of the error text you should do the following:

1. Change the text for the error to be the message token, and move the text
   to the messages file.
2  When about to report the error:

    ADR          R0,ErrorBlock_AnError
    BL           CopyError
    Pull         "....,PC"

Where CopyError is
 
        Push    "R1-R7,LR"

;       R0 -> Error block (Word aligned) containing error number , token, terminated by 0 or error number , "token:default"
;       R1 -> 4-word data structure passed to MessageTrans_LoadFile
;       R2 -> buffer to hold result (0 => Use internal buffer)
;       R3 = buffer size (if R2 non-0)
;       R4 -> parameter 0 (0 => don't substitute for "%0")
;       R5 -> parameter 1 (0 => don't substitute for "%1")
;       R6 -> parameter 2 (0 => don't substitute for "%2")
;       R7 -> parameter 3 (0 => don't substitute for "%3")
                                                                          
        ADR     R1,MessageFile_Block
        MOV     R2,#0                   ; Use internal buffer
        MOV     R4,#0                   ; Argument pointers.
        MOV     R5,#0
        MOV     R6,#0    
        MOV     R7,#0
        SWI     XMessageTrans_ErrorLookup    ; Get error text. (Sets V !)
        Pull    "R1-R7,PC"              ; error token.


 For errors which may be reported from IRQs you should pre_cache
the translated error into a local buffer instead of translating it every
time it is to be reported. In this case you should re-cache the error on
Service_TerritoryStarted so that you get the new text if a new language
comes into effect. Pre-caching should be done by calling
MessageTrans_Lookup, and not MessageTrans_ErrorLookup.
 


 Sorting:
 ========

        All assumptions about the sorting order being the same as the ASCII
order of characters should be removed.

      There is a new SWI provided Territory_Collate:

       On entry:

                R1 -> String1  (0 Terminated)
                R2 -> String2  (0 Terminated)
                R3  Flags:
                          Bit 0 :  1 = Ignore case.
                          Bit 1 :  1 = Ignore accents.
       On exit:
             R0   <0 if S1 < S2 
                  =0 if S1 = S2
                  >0 if S1 > S2 
             Other registers preserved.

             Z set if equal (EQ).
             C set and Z clear if S1 > S2 (HI)
             N set and V clear if S1 < S2 (LT)

             V set if error.
          
      I.E.  flags set as for numeric compare you can use HI,LT, and EQ
condition codes.

       Always use this call when sorting !

 Time:
 =====

      The concept of time zones has been introduced, the system 5 byte time
is now concidered to be in UTC (GMT) whenever a 5 byte time is used it is
assumed to be an absolute indication of the time, unaffected by changes in
local time.

      All system calls which take a 5 byte time and produce text output will
produce the output in local time, given a UTC 5 byte value.

      When setting the clock, a string giving the LOCAL time in the format
    day,dd mmm yyyy.hh:mm:ss should be given, note that this is the buffer
order, so the day should be the first thing in the buffer even if the write
direction is right to left.


                






   
 
