Acorn Arabic system.

The *COUNTRY command below should be sufficient for most Arabic-speaking
users of the BBC Micro.  It is expected that a user will issue '*COUNTRY
Arabic' and then use View, ViewSheet, or ViewStore wholly in Arabic.

Software developers on the other hand, providing programs for people to
use, may need to build calls to some of the other facilities into those
programs.  These other facilities are listed in order of increasing
complexity and decreasing likelihood of being needed.  The commands at the
end of this document are for system developers only and will probably
never be used by most people.

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


*COUNTRY Arabic

   This command when issued will convert the BBC Micro into an Arabic
micro-computer.

   When the computer is configured as an Arabic machine, several things
happen:  notably, the action of certain keys on the keyboard change.  The
most obvious change being that the <WHAT KEY?> key now has the ability to
switch the computer from an English display to an Arabic one.

This switching will have immediate effect, reversing any text on the
screen and changing the direction of cursor movement.  Arabic text
displayed from then on will be context analysed as appropriate.

   It is hoped that most simple and straightforward systems software and
applications software will run immediately in this simple Arabic mode. 
Programs which produce English text messages may need to be changed to
produce Arabic text messages, but all data used by such programs may be
entered in Arabic correctly.

   Standard Acorn programs such as View, ViewSheet, and ViewStore will
work in this way, and it is possible that in the future they will be
incrementally upgraded to both accept commands, and display information,
in Arabic.

   BASIC programming will have to be done in English mode, but fast
switching will allow users to change to Arabic mode in order to enter
Arabic strings and comments.  BASIC programs when running may of course
run completely in Arabic display mode.


*COUNTRY UK

   When any other *COUNTRY command is issued the effects of the '*COUNTRY
Arabic' command will be undone before the new *COUNTRY command takes
effect.

   It is recommended that users switch back to the English-style display
by using the <WHAT KEY?> key before they issue this command: the *COUNTRY
command does not reverse the screen for you.

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


*ALPHABET Arabic

   This command will insert an Arabic character set without activating any
form of context sensitivity or cursor behaviour.  The form of character
displayed for any of the ISO Arabic codes will be the 'stand-alone' form.
The other forms may be generated by explicitly selecting 'Arabic1',
'Arabic2', or 'Arabic3' which will give the Start-Of-Word, Middle-Of-Word,
and End-Of-Word forms respectively.

*KEYBOARD Arabic

   This command changes the codes returned when pressing keys on the
keyboard.  The values returned correspond to the ISO value of the
character inscribed on the keytop.  The code key is used to escape back to
the UK keyboard.  Only unshifted keys return Arabic codes; all shifted
keys return the value which the UK keyboard would return.  The CAPS-LOCK
key has no effect in Arabic.

   The Arabic keyboard mode does not enable the <WHAT KEY> key, so
utilities such as the high-quality Arabic text editor are free to handle
mixed language text in whatever way they feel best.

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

   The Acorn Arabic system acknowleges that it is very difficult to design
a system to automatically cater for mixed-language work and solves the
problem by delegating mixed work to custom software.  It instead takes the
approach of providing a good Arabic-only system and allows rapid switching
from Arabic-only to English-only and back again.

   Given that the BBC Micro VDU stream has always been control-character
based rather than ISO escape-sequence based, mixed-language work under
control of escape sequences is not feasible to implement.

   Arabic-only printing is therefore the only form of printing supported.
The ideal printer envisaged by this system is one where the printer knows
the ISO Arabic character set and does its own context analysis.  Given
that such printers are not yet common-place, the Acorn Arabic system
offers a simple emulation of this by performing context analysis itself
and reversing lines of text internally before sending data to the printer. 
The emulation is done at the lowest level of the system just before data
goes out to the printer.

   The length of line understood by the printer has to be programmed in to
the BBC Micro driving the printer.  The Arabic processing mentioned above
should only be done by the micro driving the printer directly, thus if a
printer is connected to the Econet, the BBC generating the text will
assume that it is talking to a printer which genuinely understands Arabic
and the printer-server machine will do the line-reversal and context
analysis locally.

   If ISO Arabic printers do become available (the most likely option
being an intelligent laser printer), they will be driven from this scheme
very easily, and will accept escape sequences sent directly to the printer
just as UK printers currently accept Epson escape sequences.

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

   Most commands to the Arabic system are implemented by the system
procedure OSBYTE with parameters A=70 and X=9.  The full list is given
below, with *-command alternatives where appropriate.

   Note that *FX 70 is the *COUNTRY call, and that 9 is the code for
Arabic; hence *FX 70,9 is identical to *COUNTRY Arabic.  This is because
the *FX command sets any missing parameters (Y in this case) to 0.  The
use of OsByte(70,9,Y) is an extension to this interface which requires the
Y parameter to be set explicitly in all calls from assembly code.

   (The only Arabic functions which do not use OsByte(70) are those which
implement *KEYBOARD and *ALPHABET.  These both use OsByte(71) which is
explained in the document "NOTES ON THE SPANISH INTERNATIONAL ROM" Version
1.00 dated 01may1987.)

   The following calls implement the Arabic system:

OsByte(70,9,0)  -  *COUNTRY Arabic

   Select Country Arabic.  Enable <WHAT KEY?> key to allow rapid switching
into full Arabic display and context analysis.


OsByte(70,9,1)  -  *SCREENFLIP

   Reverse all the pixels on the screen and reverse the text direction. 
The cursor is also re-positioned if possible.

OsByte(70,9,2)  -  *SCREENFLIP Arabic

   As above, but do nothing if already in right-to-left mode.

Osbyte(70,9,2)  -  *SCREENFLIP UK

   Ditto but not if already in left-to-right mode.

OsByte(70,9,3)  -  *FONTFLIP

   This will replace the definitions of all the characters in the
UK/Arabic with their mirror images.

OsByte(70,9,4)  -  *FONTFLIP Arabic

   This will set up the font so that the UK characters (those <= 127) are
mirrored, but the Arabic characters are the correct way round.

OsByte(70,9,5)  -  *FONTFLIP UK

   This will set up the font so that the Arabic characters (those >= 128)
are mirrored and the UK ones are the correct way round.

OsByte(70,9,6)  -  *TEXTFLIP

   This is in fact a subset of *SCREENFLIP above - it reverses the
direction that text is printed, but has no other effect.  If executed in a
text window, the window will remain intact.  This command has no unforseen
side effects: the screen is not changed; the cursor is not moved etc.

OsByte(70,9,7)  -  *TEXTFLIP Arabic

  This forces the text direction to be right-to-left.

OsByte(70,9,8)  -  *TEXTFLIP UK

   This forces text to run left-to-right.

OsByte(70,9,8)  -  *ARABIC Text

   Arabic text will be context analysed for word endings etc.  This
happens by default when Arabic is being displayed.

OsByte(70,9,9)  -  *ARABIC Text off

   The text will not be analysed for word endings, however any other modes
currently active will remain so - for instance the <WHAT KEY?> key will
still cause a screen flip.  This should be contrasted with what happens
when *COUNTRY UK has been selected but with *ALPHABET Arabic.

OsByte(70,9,10)  -  *ARABIC Numerals

   Arabic numerals will be reversed on screen.  This is an expensive
process which is not always wanted, for instance when *DUMPing a file. 
The algorithm for reversing numbers is very simple and does not cope with
such constructs as decimal fractions.

OsByte(70,9,11)  -  *ARABIC Numerals off

   This call disables the automatic reversal of Arabic numbers.  This will
allows program developers who wish to do their own numeric formatting to
do so without interference from the system.

OsByte(70,9,12)  -  *ARABIC Printer

   The low-level Arabic printer driver is installed.  This is entirely
independant of whatever happens on the screen.  The printer will accept
the ISO Arabic 8-bit character set and print all data it receives from now
on in reverse with context analysis enabled.

OsByte(70,9,13)  -  *ARABIC Printer off

   The low-level printer software is disabled.  If you wish to print in
Arabic you must ensure that the printer itself understands ISO codes.

OsByte(70,9,14)  -  (no equivalent)

   This call is provided for software writers to test which version of
Arabic is in use.  If no Arabic is installed, the value 0 will be returned
in the X register.  The first release version of the Arabic Rom will
return 1 in X and so on.  This number will not be the same as the version
number reported by *HELP or *ROMS, but will correspond to the internal
version number in the standard Acorn sideways Rom header.

OsByte(70,9,15:38)  -  ILLEGAL

   Any osbytes in this range will return with the CARRY flag set.  They
may be used in future systems, in which case the CARRY flag must be
cleared on return.

OsByte(70,9,39:255)  - *ARABIC Printer 39:255

   The width of line to be reversed will be set to the parameter given. 
This allows printer widths of between 40 columns and 255 columns to be
used.  (The value of 39 is in case a 40-column printer forces a newline on
the 40th column which would cause alternate blank lines if a value of 40
was used instead.)