This site has not been maintained for years; For an up-to-date site, click here.



THE HEBREW SUPPORT FOR X-WINDOWS AND MOTIF
VERSION 4.0
EL-MAR SOFTWARE LTD.



Following: a sample screen. The documentation follows this screen. You can scroll down, or alternatively, skip this big image (129K) by clicking here.






TABLE OF CONTENTS:


ABOUT THIS MANUAL

Manual Format

INTRODUCTION

Differences between Version 4.0 and 3.3

CHAPTER 1 - KEYBOARD MANAGER

1.1 Introduction

1.2 Using KM

1.3 Entry of Text Intended for Inversion

1.4 Implicit View of Texts of non-Hebrew Applications

CHAPTER 2 - HTERM - HEBREW SUPPORT OF XTERM

2.1 General

2.2 Modes

2.3 The Hebrew Keyboard

2.4 New Menu Options

2.5 New Control Strings

2.6 Window for Entering "Inverted" Hebrew Text

2.7 Emulation of the Arrow Keys by the Mouse

2.8 Color Support

2.9 Changing Translations

CHAPTER 3 - HEBREW SUPPORT AT THE XLIB LEVEL

3.1 HRebindKeyboard()

3.2 HInitCtrlHebrew()

3.3 HIsKmActive()

3.4 HGetKeyboardLanguage()

3.5 HReverseText()

3.6 HImplicitToVisualSimple()

3.7 HVisualToImplicitSimple()

3.8 HAddCtrlHebrewTester()

3.9 HConvertText()

CHAPTER 4 - LANGUAGE CUSTOMIZATION

4.1 Introduction

4.2 Environment Variables

4.3 Defining the Language

CHAPTER 5: THE MOTIF HEBREW SUPPORT

5.1 General

5.2 XmNlayoutDirection

5.3 XmNtextMode

5.4 XmText and XmTextField

5.5 XmNstringDirection

5.6 Use of Hebrew Features within UIL

CHAPTER 6 - ATTACHED DEMO PROGRAMS

6.1 Bilingual and Bi-directional Editor

6.2 hmdialogs

ANNEX A: INSTALLATION, COMPILATION AND RUNNING ENVIRONMENT

A.1 Installation

A.2 Compilation (at source level)

A.3 Link

A.4 Environment Variables

A.5 Special Keys

ANNEX B: FILES AND FONTS INCLUDED IN THE PACKAGE

Font Names (file names depend on the operating system)

ANNEX C: TROUBLESHOOTING AND LIMITATIONS

X-Server:

Motif Programs, Compilation and Link

KM:

hterm and other emulators

Applications That Run Under hterm and Other Emulators

Specific Platforms

Miscellaneous

ANNEX D: COMPLIANCE WITH ISRAELI AND INTERNATIONAL STANDARDS






ABOUT THIS MANUAL


This manual describes the Hebrew support for workstations, including support of their graphical user interfaces - X/Windows and Motif. In addition to this manual, there is a Reference Manual in English, which includes a summarized formal description of all the software components and exists in standard, on-line manual format of UNIX (man-pages).

The length of the two manuals may misleadingly create the impression that the software is complicated. In fact, all that must be known by an end user working with ready applications is how to press the key combinations of <Extend> (in HP) or <Ctrl><Hebrew> (when there is no <Hebrew> key, then the <Meta> or <Alt> or <Left> or <Right> key replaces it). A smart user must know a number of additional details (like operation of hterm), and the same applies to the system administrator. In contrast, the software developer should learn the entire manual.



Manual Format

The manual is divided into six chapters and six annexes.

Chapter 1 describes the Keyboard Manager, a tool that enables you to dynamically change the language for each application on the screen, using <Ctrl><Hebrew>, without the need for any special support from the application. This tool enables entry of inverted strings for applications on the screen, by clicking the left button of the mouse while pointing to the application to which the string must be entered and pressing the <Ctrl><Shift> keys.

Chapter 2 describes hterm, a tool identical to xterm but with additional Hebrew features, some of them compatible with the Hebrew features of existing terminals (like Digital), and some of them unique. Not all the new features concern Hebrew support (for example, colors).

Chapter 3 describes the Hebrew support at the Xlib level, whose main purpose is to control the language mode at the application level, when the Keyboard Manager is not suitable for these needs. Some of the functions described in this chapter, can be used also by simple programs which are not based on X, by linking them with MSBiDi.o (see also Annex A).

Chapter 4 describes how to customize language, define unusual features (such as key mapping or encoding a non-standard font), and even define additional languages.

Chapter 5 is the most meaningful and describes the Hebrew support of Motif. This is a key chapter for developers in Motif.

Chapter 6 describes the demo software and the auxiliary software included in the package.

Annex A describes the installation, operation and compilation environment, i.e. what values to give to the environment variables, what flags to add during compilation, what programs should be run automatically, etc. This annex also details the special keys and the key combinations necessary for operation. Annex B details the files included in the software. Annex C presents the limitations and offers solutions for unexpected problems which occur while working with the software. Annex D deals with compliance with Israeli and international standards and includes a table describing the set of characters and their features. Annex E presents El-Mar Software's complementary products, and Annex F is the index.

We recommend you to read Annex A thoroughly before using the software!





INTRODUCTION


The first workstations appeared in the beginning of the 80's. They were equipped with large high-resolution screens, mice, connectivity devices, large resources, and the UNIX operating system. Their two most meaningful innovations were: (1) graphics and windowing, and (2) connectivity; however, it was not possible to combine these two innovations, because the graphics and window systems of the various stations did not have a uniform language. The need arose for a graphical interface based on a standard protocol. The cooperation of the leading computer companies was necessary in order to establish a standard and to 'crack' the original code for the whole package to the public and free of charge.

Development of the X Window System began in the mid-80's in a project called "Project Athena." The project was carried out in the Massachusetts Institute of Technology (MIT), with the cooperation of various computer companies, such as IBM and Digital, and was intended to provide graphics and windowing to different computers connected to the network. The original software was distributed to the public free of charge, and within a short period there were no workstations that did not support this interface.

In the framework of the project, no special attention was paid to support of foreign languages. However, it was possible to support most languages without any additions, although certain languages remained problematic, amongst them Hebrew and Arabic, which have unique difficulties.

Following this project, the OSF organization, which unites most of the leading computer companies in the world (including IBM, Digital, and HP), decided to develop a X-Windows-based graphical user interface, which would provide a better, more complete and more convenient solution. In 1989, the first version of the product called Motif was completed, and in a short period, the interface became a de facto standard in workstations. Following the establishment of COSE (at the Uniforum Conference, March 1993), Sun and Novell joined the companies officially supporting Motif.

At the beginning of the project, a foundation was laid for solving problems such as bi-directionality (by compound strings, for example), but later on the subject was neglected, and there was no support in the critical stages (such as entering text). In less critical subjects, the support was generally documented but not applied in practice. So, for example, in most of the cases that were documented as being able to use the feature XmNstringDirection to invert alignment direction, this was not true. Furthermore, even in cases where support of this feature was applied, it was done erroneously and not checked (for example XmList).

The software described in this manual provides Hebrew support for X-Windows and for Motif, in all workstations supporting these standards. The support is composed of three main elements: interactive language-change (<Ctrl><Hebrew>), inserting texts in applications lacking Hebrew support, Hebrew support of xterm (terminal emulation under X-Windows), and Hebrew support of the Motif library (libXm).

Hebrew support of interactive language-change is achieved both by a library enabling attribution of a language to an application separately from other screen applications (thereby controlling the language mode using library functions) and by the Keyboard Manager which enables text pushing.

The Hebrew support of xterm is compatible with the Hebrew support of VT terminals and of DECterm (the DECwindows tool equivalent to xterm), with the addition of new features (text-inverting window, inversion of a whole screen) as well as features not connected with language (emulation of arrow keys by mouse movement).

The Hebrew support of Motif provides a complete solution for developers of Hebrew applications in Motif and for converting existing applications. It is composed of the 'right to left geometry' option for most of the widgets existing in Motif, and applies all the features of this option, which appear in the documentation of Motif but which are not applied in practice.



Differences between Version 4.0 and 3.3





CHAPTER 1 - KEYBOARD MANAGER




1.1 Introduction

This chapter discusses the Keyboard Manager, which enables switching from language to language while working, as well as entry of text intended for inversion. The following two paragraphs describe the switch from language to language, the third paragraph (1.3) describes the entry of text intended for inversion, and the last paragraph (1.4) describes an implicit/logical display of an implicit/logical text which is displayed visually by (for example) a non-Hebrew application.

If there is no need for the feature allowing entry of text intended for inversion, then km_light may be used, which provides faster response.


1.1.1 The Two Mapping Methods

The Hebrew support of dynamic language change (<Ctrl><Hebrew>) is realized both by the Keyboard Manager and by library functions enabling attribution of a language to an application separately from the other applications on the screen. Details of the library functions and how to use them may be found in the chapter on Hebrew support at the Xlib level (see chapter 3, especially 3.2).

This chapter details the Hebrew support of the Keyboard Manager (KM). In contrast with library functions, KM applies to the entire screen (per keyboard), not to a certain application (per application). There are two main implications differentiating this from library functions:

  1. There is no need for the original application software (or to re-link) in order to benefit from <Ctrl><Hebrew>, because KM maps the keyboard for all the applications (except for a few that perform operations forbidden by the X-Windows documentation).
  2. There is no possibility that at any given moment, one program will be in a Latin keyboard mode and another program using the same keyboard will be in a Hebrew keyboard mode.

Note:

It is recommended not to use both methods simultaneously. Both are offered in order to increase the selection, but each one has its advantages and disadvantages and, as a result, its own purpose.


1.1.2 The Hebrew Keyboard

Most of the keys on the original keyboard provide 2 possible characters, one usually obtained by pressing <Shift> together with the key, and the other without pressing <Shift>. However, the Hebrew keyboard contains many keys that have a third meaning: a character (not necessarily a Hebrew letter) that should be obtained when the keyboard is in Hebrew mode.

In order to perform the switch between languages, KM must be active; the switch will be performed by combining the keys <Ctrl><Hebrew> (when there is no <Hebrew> key, it is replaced by <Alt> or <Meta> or <Left> or <Right>. In Sun keyboards, the diamond key may be used). In an HP environment, the switch is performed by using the <Extend> keys on either side of the space bar: the right-hand key switches to Hebrew, and the left-hand key to English.



1.2 Using KM


1.2.1 Operating KM

In order to switch between languages, KM must be operated by the following shell command:

km [-push] [+push] [-toggle] [+toggle] [-led #] &

or (see introduction at the beginning of the chapter, 1.1):

km_light [-push] [+push] [-toggle] [+toggle] [-led #] &

"-push" causes the pushing mode to be active (KM's default), "+push" neutralizes this mode, "-toggle" causes the language switching mode to be active (default), "+toggle" neutralizes this mode, and, to cause one of the keyboard lamps to illuminate when Hebrew is active, its number should be provided after the next flag: "-led 2" (this must not be done when using the Irix system!!!).

For this operation to be performed automatically when operating X-Windows, this command may be entered in one of the shell scripts which are run automatically when X-Windows is operated (for example, .xinitrc, .xsession, or .xstart.sh, depending on the environment).

This command opens a small window on the screen, which contains a pushbutton labeled "English". When the language is switched, the contents of the window change from "English" to "Hebrew" and vice versa, depending on the language. The window may be changed to an icon (using the standard method of the window manager that is active on the screen), but even then, KM will continue to be active, and the icon contents will be identical to the contents that would have been in the window (i.e. "English" or "Hebrew", depending on the language). If KM is already active, running this command will cause an error message, and a new KM will not be operated. The existing KM will continue operating without change.

When KM completes its job, by a 'kill' other than 'kill -9' or by closing its window by means of the windows manager (MWM), it checks if the keyboard is in Hebrew mode, and if so, KM returns the keyboard to Latin mode.


1.2.2 Switching the Language

When KM is active, the language switch can be performed in two ways:

  1. Pressing the key combination <Ctrl><Hebrew> (when there is no <Hebrew> key, it is replaced by <Alt> or <Meta> or <Left> or <Right>, or in Sun keyboards, the diamond key may be used). In an HP environment, the switch is performed by using the <Extend> keys on either side of the space bar: the right-hand key switches to Hebrew, and the left-hand to English. This operation can be performed anywhere on the screen, regardless of the window that is active at that moment (focused).
  2. Pointing the mouse to the KM pushbutton and pressing <Button1>.


1.2.3 Limitations

Each key is totally mapped when switching to Hebrew, so that if we try to press <Ctrl>-'C' in Hebrew mode, we will receive <Ctrl>-'' (the second letter of the Hebrew Alphabet). This feature enables the combination of the <Ctrl> key with the Hebrew letters also (for example, for accelerators).



1.3 Entry of Text Intended for Inversion

There are applications for which it is impossible to provide Hebrew support, for example, applications that are in binary format without the source code. As we have seen, KM enables the application user to switch between languages. Now we will see how KM enables the application user to enter text from right to left, with transfer of the text to the application's input in the reverse order from insertion.


1.3.1

When KM is active, it is possible to point the mouse pointer to the window of the application to which we wish to enter input, and to click the left button of the mouse while pressing the key <Alt> (or <Ctrl> and <Shift>) (i.e. <Ctrl><Shift>Button1). This operation opens a window on the screen with a field for right-to-left input. It is possible to enter characters from right to left in this field, but if the present language (see 1.1, 1.2) is English, the characters will be entered by pushing. There are two possibilities after entering:

  1. To press the middle pushbutton ("Cancel") or <Esc> to cancel the operation.
  2. To press the right pushbutton ("OK") or <Enter> to close the window, but this, in addition, will invert the entered text, and send the result as input to the specific application pointed to at the beginning of the operation.

Example:

Entering the letter '', then '', and finally '' will appear as follows:

Pressing <Enter> or "OK" will cause the window to disappear and the input of the letters in the application to be in the following order: '', '', ''.


1.3.2 Limitations

This feature is available only in applications in which it is possible to perform 'paste' by the middle button (Button2) - for example, all the applications of Motif and Xaw - as opposed to applications using private 'paste' methods, such as some of the Open-Look applications (using the copy-paste keys).

This feature depends on the application accepting a simulated press that is sent to it (SendEvent). In xterm, in contract with other applications, the default is not to accept it, so the option "Allow SendEvents" in the menu opened by <Ctrl>Button1 must be switched on, or alternatively, the default must be changed by adding the following line to the ".Xdefaults" file (or ".Xresources", according to the system) in the home directory:

*.allowSendEvents: true

(This line is already included in the "/usr/H/Xdefaults" file, so if you follow the guidelines in Annex A.4, the above operations are unnecessary).

It is not possible to enter Hebrew characters to applications that do not support 8 bit, therefore, the following must be performed under xterm (applicable to most of the operating systems):

stty -istrip cs8



1.4 Implicit View of Texts of non-Hebrew Applications

When KM is active, it is possible to mark a specific text on the screen (as in copy-paste), and then to click the middle button of the mouse while pressing the key (or and ) (i.e. Button2). This operation opens a window on the screen with a field with the marked text, but after conversion to implicit directionality. You can cancel this window and continue your work by two options:

  1. By pressing the middle pushbutton ("Cancel") or <Esc>.
  2. By pressing the right pushbutton ("OK") or <Enter>.

Example:

Assuming we have a non-Hebrew application (i.e. without support for BiDi), marking a word with the letter '' on its left edge, then '', and finally '' on the right edge of the word, will cause the window of KM to look as follows:





CHAPTER 2 - HTERM - HEBREW SUPPORT OF XTERM




2.1 General

When VT-220 terminals first arrived in Israel, various Hebrew features were added to them, some of these based on features that already existed in VT-100 terminals, and within a short period most of the software used these features and they became standard. It is no wonder that these features were added also to VT-320/420 terminals and to the DECterm emulator which is supposed to emulate VT terminals (and ANSI generally) under DECwindows.

As the DECterm emulator is for DECwindows, so the xterm emulator is for X-Windows, and as there is Hebrew support of DECterm, so there is Hebrew support of xterm, called hterm, which includes identical Hebrew additions to the additions to the VT terminals and DECterm. The similarity is sometimes broken because their definitions cannot be identical - for example, new options for menus which were not added to the same menus of DECterm, because xterm has its own menus in which these options were placed. Most of the additions are controlled by the end user (for example, by menus) and by applied software (for example, by control strings).

Apart from coordination of VT terminals and DECterm, various other useful features were added to xterm, such as the possibility of inputting a string from right to left and inverting it before transferring it as input to the application (see 2.6), as well as inverting the entire screen. Regular inversion of a screen compatible with Digital's definitions is incomplete and affects only some of the functions on the screen. This is also supported (to preserve compatibility), but in addition, complete inversion is also supported.

An additional feature which is not related to language enables the user to use the mouse to perform tasks that usually demand the use of the arrow keys. This feature performs emulation of the arrow keys by means of the mouse movements. Another feature not related to Hebrew is color support; by escape sequences that are compatible with standard ISO DP 6429, it is possible to control the background and the foreground colors of a character in each square on the screen.



2.2 Modes

Many features of a terminal are specified by 'modes,' wherein any of them may be found in one of two modes: 'switched on' or 'switched off' (Set or Reset). Example: whether the terminal will perform scrolling at the end of each row.

Five new features have been added to the list of features, and their description follows.


2.2.1 Displaying the Cursor (DECTCEM)

Set:Text Cursor is Enabled (Shown)
Reset:Text Cursor is Disabled (not Shown)

In 'Set' mode, the text cursor will appear. In 'Reset' mode, it will not appear. The default is 'Set.' This feature is compatible with VT terminals and ANSI standard, but was omitted from the original xterm.


2.2.2 Cursor Direction (DECRLM)

Set:Right to Left Direction
Reset:Left to Right Direction

When the terminal is in this mode, the cursor will move in the opposite direction (from right to left). Any string written to the screen will appear from right to left, and the string to be displayed after will appear to its left.

The cursor direction (as opposed to inverting the whole screen, see 2.2.5) does not affect the cursor address, so the location (1;1) for example, will always be the upper left corner of the screen.

The following screen functions are not influenced by the cursor direction:

  • Tab
  • Margin Bell
  • CUP (CUrsor Position)
  • HVP (Horizontal and Vertical Position)
  • CUF (CUrsor Forward)
  • CUB (CUrsor Backward)
  • ICH (Insert CHaracter)
  • DCH (Delete CHaracter)
  • ED (Erase in Display)
  • DECSED (Selective Erase in Display)
  • DECSEL (Selective Erase in Line)
  • ECH (Erase Character)

Screen functions influenced by this mode:

  • IRM (Insert/Replace Mode)
  • DECAWM (Auto Wrap Mode)
  • BS (BackSpace)
  • LF/VT/FF (Line Feed, Vertical Tab, Form Feed)
  • CR (Carriage Return)

Note:

The screen function SUB is not supported by xterm, therefore there is no need for the Hebrew support to refer to it.

When a character is received and the screen is in right-to-left mode:

If the screen is in Insert mode, then all the characters from the current location leftward will move one place left.

BS will move the cursor one place to the right (instead of one place to the left).

CR will bring the cursor to the right end of the line.

The same applies to FF, VT, LF - when the screen is in "New Line" mode.

NEL will bring the cursor to the right end of the next line.


2.2.3 Mapping to Hebrew (DECHEBM)

Set:Hebrew Mapping is Active
Reset:No Hebrew Mapping

When the screen is in this mode, the following operations are performed:

  1. All the keyboard keys will be mapped to corresponding keys characters according to the Hebrew keyboard (for example, 'a' to '' and so forth). When mapping is to a Hebrew letter, it may to be to either 7-bit characters of ISO 646 (old code) or to 8-bit characters of ISO 8859/8, according to the encoding mode (DECHEM, see 2.2.4).
  2. If the encoding mode (DECHEM) is 7 bits, then the characters sent to output as Hebrew characters will be displayed as Hebrew, even though they are in the 7-bit range (0X60-0X7A). Therefore, 'a' will be displayed as ''. In other words, like the process of encoding Hebrew characters to 7 bits in input, characters are encoded back to 8 bits in output.
  3. The user will be given an indication by the additional word "(Hebrew)" in the window title.

When KM is active (see Chapter 1), DECHEBM mode is switched Off and neutralized. The <Ctrl><Hebrew> key continues to be active, but through KM (see chapter 1).


2.2.4 Encoding Mode (DECHEM)

Set:Multinational (8 bit)
Reset:National (7 bit)

Usually, the 8th bit is truncated from the characters sent to the screen (and, of course, is not included in the characters inputted from the keyboard). When the terminal changes to international encoding mode (8-bit), the 8th bit will not be truncated. An additional influence on the encoding mode will be in the case of mapping to Hebrew (DECHEBM, see 2.2.3). In this case, if the encoding mode is 7 bits, the keys will be mapped to 7-bit Hebrew characters according to ISO 646 (old code), and if the encoding mode is 8 bits, then the keys will be mapped to 8-bit Hebrew characters according to ISO 8859/8.

In regard to mapping to Hebrew mode, there will be further consequences to the encoding mode when set to 7-bit:

  1. If non-Hebrew characters are sent to the screen encoded in values of 0x60-0x7A, they will be mapped as 8-bit in the case of mapping to Hebrew mode. In this manner, the 8th bit which was truncated in input is returned in output and enables the application to work as if there was no Hebrew.
  2. Each press on the key combination that changes the mapping between Hebrew and English (see 2.3) will exchange all the characters on the screen that are in the range 0x60-0x7A with the equivalent 0xE0-0xFA, and vice versa, in accordance with the mapping language (English or Hebrew). When a switch is made from Hebrew to English, all the characters in the range 0xE0-0xFA will be exchanged with characters 0x60-0x7A accordingly, and when a switch is made from English to Hebrew, all the characters in the range 0x60-0x7A will be exchanged with characters 0xE0-0xFA accordingly.
  3. The "Convert Display" menu option (see 2.4.4) will become active. However, in 8-bit mode it is blocked.


2.2.5 Mirror Mode

Set:Right to Left Direction
Reset:Left to Right Direction

When the terminal is in this mode, the cursor will move in the opposite direction (from right to left). Any string written to the screen will appear from right to left, and the next displayed string will appear to its left. In contrast with "cursor direction" mode (DECRLM, see 2.2.2), the inversion here is complete and affects all the screen functions.


2.2.6 Implicit Mode

Set:Implicit Directionality
Reset:Visual Directionality

When the terminal is in this mode, the logical content of each line will be converted to appropriate order while it is drawn on the screen, according to the bidirectional algorithm of Microsoft. The main direction, which is an important parameter that this algorithm needs, is taken from Mirror-Mode.

When the directionality is Implicit, it is forbidden to have DECRLM on too.



2.3 The Hebrew Keyboard

Most of the keys on an original keyboard provide two possible characters, one usually obtained by simultaneously pressing <Shift> and the key, and the other without <Shift>. However, the Hebrew xterm keyboard (similar to Hebrew terminals) contains many keys that have a third meaning: a character (not necessarily a Hebrew letter) that should be received when the keyboard is in Hebrew mode.

An indication to Hebrew mode also exists. As opposed to most terminals which use LED indication, here indication is given (for obvious reasons) by an addition to the window title:

instead of:

In addition to the control strings that enable the program to switch automatically from Latin mode to Hebrew mode and vice versa (see 2.5), it is also possible to perform this by the key combination <Ctrl><Hebrew> (when there is no <Hebrew> key, it is replaced by <Alt> or <Meta> or <Left> or <Right>, and in Sun keyboards, the diamond key). In an HP environment, the switch is performed by using the <Extend> keys on either side of the space bar.

These combinations do not affect the encoding mode (7-bit or 8-bit), therefore the application can place the terminal in a certain encoding mode, knowing that the terminal will remain in this mode regardless of the end user's switching dynamically between the languages.

When KM is active (see chapter 1), the <Ctrl><Hebrew> key is neutralized but continues to be active through KM, which manages the language mode for all the screen applications. KM may be bypassed by <Ctrl><Shift><Hebrew>, which changes the application's private language mode.

There is also a key combination for reversing the screen's direction (Mirror Mode). This is done similarly to the way used by the Hebrew version of Microsoft Windows, i.e. by a click on the appropriate <Shift> key (right Shift for right to left direction, left Shift for left to right direction) while the <Ctrl> key is pressed.



2.4 New Menu Options


2.4.1

No new menus were added to xterm, but six new options were added to existing menus. The existing menus (their titles) are:

  1. VT Options
  2. Main Options
  3. VT Fonts

Five options were added to the first menu, and one option to the second menu.


2.4.2 Right-to-Left Mode

This option was added to "VT Options" menu. Every selection of this option changes the cursor direction - DECRLM (for the consequences of this mode, see 2.2.2).

In addition, when the cursor direction is right to left, indication will be given by the symbol '' next to the option (as for the other options in this menu).


2.4.3 Multinational Mode (8-bit)

This option was added to "VT Options" menu. Every selection of this option changes the encoding mode - DECHEM (for the consequences of this mode, see 2.2.4).

In addition, when the encoding mode is Multinational (8-bit), indication will be given by the symbol '' next to the option (as for the other options in this menu).


2.4.4 Mirror Mode

This option was added to "VT Options" menu. Every selection of this option changes the screen's Mirror Mode (for the consequences of this mode, see 2.2.5).

In addition, when the screen is in mirror mode, indication will be given by the symbol '' next to the option (as for the other options in this menu).


2.4.5 Implicit Mode

This option was added to "VT Options" menu. Every selection of this option changes the screen's Implicit Mode (for the consequences of this mode, see 2.2.6).

In addition, when the screen is in implicit mode, indication will be given by the symbol '' next to the option (as for the other options in this menu).


2.4.6 X Evenets Mode

This option was added to "VT Options" menu. Every selection of this option changes the events mode in the input - X Events Mode. In ordinary mode, most of the events are translated into one character, some of them to escape sequences, and these characters are sent as input to an application running under hterm. When this feature is set, the events are translated into strings describing the event in the syntax of X translations, and these strings are sent as input. If you would like to use this feature interactively to see how to relate to a certain event in translations, then it is recommended to run the following command before switching to this mode:

cat > /dev/null

Otherwise, the shell will try to relate to the input it receives as commands for running. In addition, when this feature is set, indication will be given by the symbol '' next to the option (as for the other options in this menu).


2.4.6 Convert Display

This option was added to "Main Options" menu. It is active only when the encoding mode (DECHEM) is national (7-bit). Otherwise, it is marked as inactive (weaker font, as for other inactive options) and is not available for selection.

Every selection of this option performs the following operation:

This operation differs from the operation performed (amongst others) by the key combination that switches languages (see 2.3, 2.2.4). Here, every selection of the option performs the two operations that were described (replacing characters in both directions), whereas there, character replacement is only according to language replacement: when switching from Hebrew to English, only the Hebrew characters will be replaced, and when switching from English to Hebrew, only the Latin characters will be replaced.



2.5 New Control Strings


2.5.1 Set/Reset Private Modes

The additional control strings are from a group of control strings called "private" (Private Escape Sequences). These strings have a standard general structure:

printf("\033[?%dh", mode_num);  /*   Set mode <mode_num> */

printf("\033[?%dl", mode_num);  /* Reset mode <mode_num> */

Details of the new control strings:
Escape SequenceFunction
<Esc>[?34hSet DECRLM
<Esc>[?34lReset DECRLM
<Esc>[?35hSet DECHEBM (not effective when KM is active)
<Esc>[?35lReset DECHEBM
<Esc>[?36hSet DECHEM
<Esc>[?36lReset DECHEM
<Esc>[?37hSet MIRROR
<Esc>[?37lReset MIRROR
<Esc>[?39hSet IMPLICIT
<Esc>[?39lReset IMPLICIT
<Esc>[?25hSet DECTCEM
<Esc>[?25lReset DECTCEM

For details of the consequences of these modes, see 2.2.


2.5.2 Save/Restore Private Modes

Other operations that may be performed on private modes (such as save and restore) may also be performed on the new features. The strings that perform these operations have a standard general structure:

printf("\033[?%ds",mode_num); /* Save mode <mode_num>
*/

printf("\033[?%dr",mode_num); /* Restore mode <mode_num>
*/

Details of the new control strings:
Escape SequenceFunction
<Esc>[?34sSave DECRLM
<Esc>[?34rRestore DECRLM
<Esc>[?35sSave DECHEBM (not effective when KM is active)
<Esc>[?35rRestore DECHEBM
<Esc>[?36sSave DECHEM
<Esc>[?36rRestore DECHEM
<Esc>[?37sSave MIRROR
<Esc>[?37rRestore MIRROR
<Esc>[?39sSave IMPLICIT
<Esc>[?39rRestore IMPLICIT
<Esc>[?25sSave DECTCEM
<Esc>[?25rRestore DECTCEM


2.5.3 Changing Mouse Sensitivity

These are control strings to change mouse sensitivity for emulation of the arrow keys using the mouse (see 2.7):

printf("\033[?62;%dh",v_sensitivity); /* Set vertical
sensitivity */

printf("\033[?63;%dh",h_sensitivity); /* Set horizontal
sensitivity */

printf("\033[?62s");                  /* Save vertical
sensitivity */

printf("\033[?62r");                  /* Restore
vertical sensitivity */

printf("\033[?63s");                  /* Save horizontal
sensitivity */

printf("\033[?63r");                  /* Restore
horizontal sensitivity */

Escape SequenceFunction
<Esc>[?62;nhSet verical sensitivity to n when n represents a number
<Esc>[?63;nhSet horizontal sensitivity to n when n represents a number
<Esc>[?62sSave vertical sensitivity
<Esc>[?62rRestore vertical sensitivity
<Esc>[?63sSave horizontal sensitivity
<Esc>[?63rRestore horizontal sensitivity


2.5.4 Changing Background and Character Color

These are control strings to change background and foreground colors of everything sent to the screen after input of the control strings (see 2.8):

printf("\033[3%dm", n);  /* Set foreground. 0 <=
n <= 7 */

printf("\033[4%dm", n);  /* Set background. 0 <=
n <= 7 */

Escape SequenceFunction
<Esc>[30mSet foreground to black
<Esc>[40mSet background to black
<Esc>[31mSet foreground to red
<Esc>[41mSet background to red
<Esc>[32mSet foreground to green
<Esc>[42mSet background to green
<Esc>[33mSet foreground to yellow
<Esc>[43mSet background to yellow
<Esc>[34mSet foreground to blue
<Esc>[44mSet background to blue
<Esc>[35mSet foreground to magenta
<Esc>[45mSet background to magenta
<Esc>[36mSet foreground to cyan
<Esc>[46mSet background to cyan
<Esc>[37mSet foreground to white
<Esc>[47mSet background to white



2.6 Window for Entering "Inverted" Hebrew Text

This window is an addition that does not exist in the Hebrew support of VT terminals and DECterm emulations. This addition is not usually intended for the end user, but for smarter users and developers.

The window is created by pressing the key combination <Ctrl><Shift><Button1> (one must combine use of keys and the mouse - see note at the end of Annex C) or the key combination <Alt><Button1>. When KM is active (see chapter 1), this key combination is neutralized but operates a similar KM feature (see 1.3).

The window width is as the width of the screen and it includes one line to which text may be entered from right to left, including editing of the row (similar to the AsciiText widget) and switching to English and back (see note that follows). On completion of writing, this text may be transferred as input to the application running underneath by pressing <Enter>. When this key is pressed, the window will disappear and its contents will be received in an inverted manner by the application, i.e. in the reverse order from that entered.

Example:

Typing the letters , then , and finally will appear in the window as follows:

Pressing the <Enter> key will cause the window to disappear and the letters to be received by the application in the following order: , then , and then .

To cancel the window without transferring the line to input, press <Esc> instead of <Enter>.

Note:

In order to create a window, AsciiText is used, while assigning a true value to XtNdirectionRtoL and a suitable value in XtNhebm, according to the value of DECHEM (see 2.2.4). Because of this, the window is influenced by the encoding mode. When the encoding mode is 8-bit, the characters will be received as 8-bit characters, and therefore, switching to English and back will be enabled while entering the string. However, when the encoding mode is 7-bit, the characters will be received as old code, and therefore, switching to English will not be enabled while entering the string.



2.7 Emulation of the Arrow Keys by the Mouse


2.7.1

This feature enables you to take advantage of the easy use of the mouse in places where arrow keys are necessary. The emulation translates the mouse movements to a series of escape sequences, which are transferred as input to the application running under hterm and understood by it as a series of arrow keys that will bring the cursor to where the mouse would have brought it. This feature is especially useful while editing a file, for example in vi. The emulation is operated by pressing <Shift><Button1> and works by two methods: absolute and relative emulation.


2.7.2 Absolute Emulation

In this method, the mouse cursor is brought to the same place that the operation's cursor should be brought, and <Shift><Button1> is pressed without moving the mouse at all. Pressing the keys will be translated into a series of escape sequences according to the distance between the two cursors and the direction to be passed.


2.7.3 Relative Emulation

In this method, <Shift><Button1> are pressed, and while they are pressed the mouse is moved. The hterm cursor will move parallel to the mouse cursor. When the mouse cursor reaches the end of the hterm window, it will 'jump' inside the window and will not be able to leave the window while the operation is being performed; the hterm cursor, however, will continue to move in the direction of the mouse movements, to enable emulation of the scrolling performed by the editors when the user deviates from the part of the file included in the screen. The movement will be translated into a series of escape sequences according to the distance and direction traveled by the mouse cursor.

Note:

For convenience, it is recommended to put the mouse cursor on the hterm cursor before starting this operation. Their movement will almost overlap.


2.7.4 Miscellaneous

Emulation of the arrow keys by the mouse is a very important and useful feature. It is not clear why this feature is not included in the standard xterm, but there are cases with certain problems, cases in which the resolution must be adjusted, and cases in which it is impossible to use this feature. We will try to analyze the problems:



2.8 Color Support

Through color support, it is possible to control the foreground and bacground colors of the character. The control strings are detailed in paragraph 2.5. These control strings are compatible with the standard ISO DP 6429. Following a change of color of the background or the foreground, there is no change in the foreground or backround colors of characters already on the screen, but new characters to be sent to the screen will be colored in the new foreground or background colors. Thus it is possible to simultaneously include, in one screen, foreground and background with any combination of the 8 possible colors, for a total of 64 combinations.

When the character color is identical to the background color, the character will not be seen. (Warning! This feature must not be used for entering passwords, because copy or cut may be performed on a password and pasted to another window, thereby revealing the password!).

Color Numbers:

0 - Black
1 - Red
2 - Green
3 - Yellow
4 - Blue
5 - Magenta
6 - Cyan
7 - White



2.9 Changing Translations


2.9.1 ev_printf()

A new action was added to the hterm action list, which may be connected to any event by translation. Translation may be added either by the Xdefaults mechanism or by a new escape sequence defined for this purpose (see 2.9.2).

The name of the action is ev-printf(), and it receives any number of parameters. It goes through the parameters one by one and 'spills' them as input to the application running under hterm.

Every parameter is a string of ASCII characters, which in addition to the regular characters can also include two additional types of special expressions.

The first type are expressions beginning with '%', which refer to the event that operated the action, and primarily to the key that is contained in the event:
%dThe decimal value of the KeySym
%oThe octal value of the KeySym
%xThe hexa-decimal value of the KeyCode
%DThe decimal value of the KeyCode
%OThe octal value of the KeyCode
%XThe hexa-decimal value of the KeySym
%cThe KeySym name (e.g. "Shift_L")
%sThe string which would be generated by this string
%%The character "%"

The second type are expressions beginning with '/':
\tTab
\bBackspace
\rCarriage return
\fForm feed
\dddASCII character which is coded by the octal value ddd
\\The character "\"


2.9.2 Changing Translations while Running

A new escape sequence was added to hterm that enables changing of hterm's internal translations while running. Combined with ev-printf() (see 2.9.1), a new dimension of possibilities is received for key mapping:

printf("\033]7;%s\007",xlation); /* Override the
xlations*/

printf("\033]7;\007");           /* Reset the xlations
*/

Escape SequenceFunction
<Esc>]7;xlation<007>xlation overrides current translations
<Esc>]7;<007>Reset the translations

An example of use of this feature together with ev-printf() may be demonstrated by the following string, which is written in C and maps every key press combined with <Ctrl> and <Shift> to "<Esc>K" which will be followed by the name of the key:

"\033]7;~Alt Ctrl Shift<KeyPress>: ev-printf(\\033K%c)\007"

Additional information on actions and translations may be found in the X-Windows documentation.





CHAPTER 3 - HEBREW SUPPORT AT THE XLIB LEVEL




Note: The paragraphs 3.1, 3.2, 3.3, 3.4 and 3.8 can be used only by X and Motif proograms. The rest are relevant to any program; In order to allow a non-X program the access to them, it is required to add:

#include <MSBiDi.h>

in the beginning of the program, and to link in according to the instructions of Annex A.3.



3.1 HRebindKeyboard()

This function changes the mapping of the keyboard keys:

HRebindKeyboard(display, w, is_hebm, is_hem)
Display *display;
Window w;
int is_hebm, is_hem;

w is the top-level window of the application. If is_hebm has a non-zero value, then the new mapping will be to Hebrew (and will be noted as such in the application title - see 2.3). In this case, the third parameter (is_hem) will determine if the Hebrew characters will be transferred as 8-bit characters (when is_hem has a non-zero value) or be truncated to 7-bit (when is_hem has a zero value).

When is_hebm has a zero value, the original mapping will be returned (Latin keyboard), and is_hem will not have any influence.

This function is meaningless when KM is active (see chapter 1).

In addition to this function, there is another function:

HToggleKeyboard(display, w)
Display *display;
Window w;

This function switches the mapping mode. If the mapping was to Hebrew, calling the function will change the mapping to English, and if the mapping was to English, calling the function will change the mapping to Hebrew.

This function does not influence the encoding mode and does not require follow-up of the mapping mode to Hebrew.

This function is meaningless when KM is active (see chapter 1).

The functions that complete the picture are:
HIsHebm()Returns current boolean value of is_hebm
HIsHem()Returns current boolean value of is_hem



3.2 HInitCtrlHebrew()

This function initializes the automatic language switch when <Ctrl><Hebrew> is pressed:

HInitCtrlHebrew(display, w, func)
Display *display;
Window w;
int (*func)();

w is a top-level window of the application. From the moment this function is called, each press of <Ctrl><Hebrew> switches the language. The result is identical to HToggleKeyboard() (see 3.1). The language switch is also indicated to the user (see 2.3).

func in normal mode will be NULL. When it is necessary to perform any user code while switching languages, a function including this code may be supplied (by func). When func is not NULL, a call to func will be performed after each language switch.

Since X-Windows does not work in real time, the influence of <Ctrl><Hebrew> depends on the application receiving a report from the X-Server. Such report can be anything - a request, error, event - and by any function - XPeekIfEvent(), XPeekEvent(), XMaskEvent(), XIfEvent(), XNextEvent(). (Note: X-Toolkit uses all these functions intensively and, therefore, the condition always exists in programs based on X-Toolkit or Motif).

There is an additional condition: the user (i.e. the developer) is responsible for ensuring that the application receives KeyPress-type events in its window range. If the application asks the server not to send events of this type, <Ctrl><Hebrew> will not be accepted by it. Since the language switch is necessary only in applications receiving entered text (therefore KeyPress must be received), this condition is only theoretical.

When there is no <Hebrew> key, it is replaced by <Alt> or <Meta> or <Left> or <Right>. In Sun keyboards, the diamond key must be used. It is recommended to affix a "Hebrew" label to this key.

In applications using the Hebrew support for Motif, this function is automatic, and therefore, there is no need to call it.

This function is meaningless when KM is active (see chapter 1).

Starting from the call to HInitCtrlHebrew(), additional functions may be used:

HOffCtrlHebrew()

HOnCtrlHebrew(func)
int (*func)();

HOffCtrlHebrew() temporarily 'switches off' support of <Ctrl><Hebrew>.

HOnCtrlHebrew() 'resets' the support of <Ctrl><Hebrew>. func is a user function called after each language switch (see 3.2) or NULL when there is no need for this function.

HOnCtrlHebrew() may also be called when the support of <Ctrl><Hebrew> is already set. In this method, the value of func may be changed.

These functions are meaningless when KM is active (see chapter 1).



3.3 HIsKmActive()

This function returns a non-zero value if KM is active (see chapter 1):

HIsKmActive()

This function may be called only after Hebrew is initialized by HInitCtrlHebrew() (see 3.2).



3.4 HGetKeyboardLanguage()

This function returns a non-zero value if KM is active (see chapter 1), and it is found during the call in Hebrew mode:

HGetKeyboardLanguage(display)
Display *display;



3.5 HReverseText()

This function inverts the character order of the string:

HReverseText(str, len)
char *str;
int len;

The character order of the string str whose length is len is inverted. If the text contains a number of lines, each one will be handled separately.



3.6 HImplicitToVisualSimple()

This function translates a string from the logical order of the characters as understood from the private directionality of the characters in the string (Implicit) to a visual order of the characters intended for display on the screen (Visual):

char *HImplicitToVisualSimple(str, is_heb_direction)
char *str;
Boolean is_heb_direction;

The string: str.

Is the main direction of the string from right to left: is_heb_direction.

HImplicitToVisualSimple() returns str.



3.7 HVisualToImplicitSimple()

This function translates a string from visual order of characters intended for display on the screen (Visual) to a logical order of the characters understood from the private directionality of the characters in the string (Implicit):

HVisualToImplicitSimple(str, is_heb_direction)
char *str;
Boolean is_heb_direction;

The string: str.

Is the main direction of the string from right to left: is_heb_direction.

HVisualToImplicitSimple() returns str.



3.8 HAddCtrlHebrewTester()

This function adds a user function to be operated every time the application receives an event from the keyboard. This user function may check the event and return an answer whether to perform a language switch following this event:

#include <X11/H.h>

HAddCtrlHebrewTester(proc)
int (*proc)(XEvent *event);

The function proc() will be operated every time the application receives a KeyPress event. The parameter it receives, event, will be the actual event. It should return one of three possible values, according to which a language switch will (or will not) be performed. These values are:

If proc() 'decides' that the language must be switched, it returns H_CTRL_HEBREW_CONTINUE_TO_TEST. If you do not wish to perform the regular tests (for example, the test whether <Alt> is pressed when <Ctrl> is pressed), then H_CTRL_HEBREW_NO must be returned.

Each time there is a KeyPress event, the Hebrew support will call all the functions that were registered in this manner, from the end to the beginning. The last function registered will be the first function to be called. The regular tests (for example, the test whether <Alt> is pressed when <Ctrl> is pressed) are also registered in this manner, so it is possible to replace tests and not only add new tests. The regular tests are registered by the function HInitCtrlHebrew() (automatically called by XtRealizeWidget() in the Motif programs), and therefore functions returning H_CTRL_HEBREW_NO that are registered after the call to HInitCtrlHebrew() (or after the call to XtRealizeWidget in Motif programs) will replace the original functions.

To demonstrate the use of this function, we will emulate the Hebrew support of MS Windows using this function. In contrast to the Hebrew support of workstations, in which pressing the key combination <Ctrl><Hebrew> switches the present language, in Windows the key press performs a substitution of a certain language. <Alt><LeftShift> always switches to English, and <Alt><RightShift> to Hebrew.

#include <X11/Xlib.h>
#include <X11/keysymdef.h>
#include <X11/H.h>

KeyCode LeftShift, RightShift;

int is_ms_windows_ctrl_hebrew(event)
Xevent *event;
{
  if (event->xkey.state & Mod1Mask)       /* Is <Alt> pressed?   */
    if (HIsHebm()) {                      /* Is in Hebrew mode?  */
      if (event->xkey.keycode==LeftShift) /* Toggle to English   */
        return (H_CTRL_HEBREW_YES);
    } else                                /* Is in English mode? */
      if (event->xkey.keycode==RightShift)/* Toggle to Hebrew    */
        return (H_CTRL_HEBREW_YES);
  return (H_CTRL_HEBREW_CONTINUE_TO_TEST);
}

What remains is to add the following lines to the program, so that they will run at the beginning of the program run. display is the display of the application:

LeftShift  = XKeysymToKeycode(display, XK_Shift_L);
RightShift = XKeysymToKeycode(display, XK_Shift_R);
HAddCtrlHebrewTester(is_ms_windows_ctrl_hebrew);

Note:

The function is_ms_windows_ctrl_hebrew is meaningless when KM is active, and will therefore not be called.



3.9 HConvertText()

Using this function, it is possible to convert a string from any storage and directionality method to any storage and directionality method:

HConvertText(from, to, line_width, tab_width, simple_digits)

HHebrewText *from, *to;
unsigned int line_width, tab_width;
Boolean simple_digits;

HHebrewText is defined in the <X11/H.h> file in the following manner:

typedef struct {
   char              *str;
   XmLayoutDirection layout_direction;
   XmTextMode        text_mode;
} HHebrewText;

from->str contains a NULL terminated string on which the conversion will be performed. The result will be stored in to->str, and XtFree() must be performed to this field after use.

The text_mode field contains the storage methods of the original and the result, and can contain one of the following values: XmTEXT_MODE_MICROSOFT, XmTEXT_MODE_VISUAL, XmTEXT_MODE_IMPLICIT. The layout_direction field contains the directionality of the original and the result, and can contain one of the following values: XmLEFT_DOWN, XmRIGHT_DOWN.

line_width is used to add spaces when you wish to align text to the end of the line, for example, when you want to send the contents of Text Widget, whose main direction is from right to left to the printer, and the printout text should be aligned to the right edge of the page. By using the value of line_width, the function knows how many spaces to add to place the text close to the right edge. When the value of line_width is 0, no spaces are added.

For the line_width to be supported also when the text includes tabs, the tab width may be defined using tab_width, and the function replaces them with a suitable number of spaces. Of course, the number of spaces replacing the tab is not fixed and can range from one space to tab_width spaces, in accordance with the location of the specific tab in the line. When the value of tab_width is 0, no tabs are converted to spaces.

When the Microsoft mode is active, the Hebrew support translates strings from Implicit storage to Visual storage in a manner that enables reconversion to the original storage. Because of this, digits included in Hebrew strings are converted to Hebrew digits (see table in Annex D), and these are converted back when translating to Implicit. This conversion may be avoided by assigning 'True' to the simple_digits parameter. This is especially important when converting an implicit string to a visual mode for display on a printer, for example.

The function works as follows: It first checks if the text_mode and the layout_direction of the original and the result are identical, and if so, it copies the original string to the result and completes the operation. Otherwise, it checks whether from->text_mode is different from XmTEXT_MODE_VISUAL, and if so, it performs a conversion to this storage, in consideration of the value simple_digits.

Afterwards, the values of the original and resulting layout_direction are compared, and if necessary, a conversion is performed between the two, in consideration of the values line_width and tab_width.

Finally, the function checks whether to->text_mode is different from XmTEXT_MODE_VISUAL, and if so, it performs a conversion to to->text_mode, in consideration of the value simple_digits.

This function is extremely useful for displaying text on devices that are not bi-directional (such as printers, dumb terminals, etc.).





CHAPTER 4 - LANGUAGE CUSTOMIZATION




4.1 Introduction

This chapter dicusses control of the language's components and how to change them, a feature that is provided to the user to enable him to support unusual options, unusual encoding, and even additional languages. The Arabic support added as an option to the Hebrew support uses this mechanism.

This mechanism is composed of two levels. The first enables determination of which languages will be supported and what the default will be, and it is described in the following paragraph. The paragraph following that describes the second level, which enables control of the components of a certain language of the languages noted in the first level, and change in the encoding, key mapping, etc.



4.2 Environment Variables

When an application is moving from English mode to Hebrew mode, the titles of its windows are changed, in a way which gives the user an indication about the current language. The default is addition of " (Hebrew)" to the original content of each title. In order to change this default, the H_TITLE_FORMAT environment variable should be assigned to a value, as follows. This value, will be used by the Hebrew Support as a format string for the function sprintf(3S), that will be called to create the final content of the title during moving from English to Hebrew. The other parameters which will be passed to sprintf() will be the original content of the title, the name of the language ("Hebrew" in our case), and then the original content of the title again. In order to clear it, let's examine a few examples (under csh). In all the examples, the original title is "Title", and the name of the language is "Hebrew":

H_LANGUAGES, an environment variable, may be set to a list of alternative languages to English. This case-sensitive list is composed of names of languages, separated by the symbol ':'. For example (under csh):

setenv H_LANGUAGES "Hebrew:persian"

This list determines which languages will replace English in the switch from English to the alternative language (by <Ctrl><Hebrew>). The first name is the default. For example, in the above example, the applications will begin the run when the active languages are English and Hebrew. To replace the Hebrew with another language, the representative character of the language must be pressed while pressing <Ctrl> (for example, <Ctrl><h> in Hebrew). The character representing the language is defined by the second level, described in the following paragraph.



4.3 Defining the Language


4.3.1 Loading a Language Definition File

The Hebrew support loads language after language (while the application is being loaded), according to the languages set in H_LANGUAGES (see 4.2). When this environment variable is not defined, the languages list loaded is: "Hebrew:Arabic". The order of operations performed on each of these languages is:

  1. Search for an environment variable whose name is the language name (e.g. $Hebrew) and use its value as a file name. If an environment variable of this name does not exist, or if the Hebrew support did not succeed in opening the file, proceed to operation 2.
  2. Search for a file in the user's home directory whose name is the language name (e.g. /users/eli/Hebrew) and open it. If the Hebrew support did not succeed in opening the file, proceed to operation 3:
  3. As in the previous paragraph, but the search is in /usr/H instead of in the home directory.
  4. If none of the operations succeeded, and the name of the language is Hebrew (in an Arabic environment, "Arabic"), an internal string of Hebrew support characters is loaded instead of a file.

After opening the file (or the internal string), the Hebrew support reads it (according to the structure described in the following sub-paragraph) and loads it as the language definition.


4.3.2 Language Definition File Structure

This file must open with the line:

#!H

This file contains a long list of values, divided into sub-lists. Each value may be referred to, both as a number and as a character, in accordance with its place. Each value may be noted both as a number and as a character, thus the meanings of 'A' and 65 will be identical. The various possibilities are a hexadecimal number (a number beginning with the characters 0x), an octal number (a number beginning with the digit 0), a decimal number (a number beginning with the digits 1-9), or a character (starting with '). A number of sub-possibilities for noting a character exist: an ordinary character (e.g. 'A'), an octal character (e.g. '\377'), and a special character (e.g. '\n'). When the Hebrew support encounters a character or an illegal combination, it skips over them, so it is possible to plant spaces, new lines and even explanations into the file, because the Hebrew support will ignore them. When the Hebrew support encounters a '#', '!', or '//', it skips to the end of the line, so notes may be added.

Each sub-list starts with a character denoting the sub-list type. Following 'a' is a sub-list that defines the character through which this language passes (e.g. 'h' for Hebrew, 'a' for Arabic). In order to do this, this character must be pressed together with the <Ctrl> key. This sub-list contains only one character.

Following 'k' is the sub-list (optional) that describes the key mapping. It is composed of character pairs. In each pair, the first character defines the original character received from the key, and the second character defines the character to be received when the language is active and not when in English mode. For example: 'a' '\0371' or: 'a' 249 are pairs that define that in place of 'a', we will receive the letter '' when in Hebrew mode. This sub-list ends with the value 0.

Following 'f'' is a sub-list (optional) that describes the font encoding. It is composed of character pairs. In each pair, the first character defines the logical character, and the second character defines the encoding of this character in the font. For example: 224 128 is a pair that defines that the letter '' is encoded in the font in the old-code encoding of PC-DOS. This sub-list ends with the value 0. Additional sub-lists handle specific subjects for Arabic and languages with joined letters, and are not described in this framework.

Following 'd' is a sub-list (optional) that describes the directionality of the various characters. It is composed of value pairs. The first value is the character whose directionality we define, and the second value is the character's classification in the operated algorithm. The default is compatible with the Hebrew support of MS Windows and includes 9 directionality types, from 2 to 10, defined in the /usr/H/include/X11/H.h file and at the end of Annex D. Most of the characters have a default (e.g. directionality from left to right for Latin characters, etc.).

If the language list has encoded font languages alongside unencoded font languages, the active encoded font will be loaded from the first language in the list that has an encoded font. This rule also applies to sub-lists intended for directionality and for Arabic.

It is recommended to use the "/usr/H/Hebrew" file as an example.





CHAPTER 5: THE MOTIF HEBREW SUPPORT




5.1 General

In applications using the Motif Hebrew support, the HInitCtrlHebrew() function is called automatically (see 3.2), therefore there is no need to call it again. In addition, new resources have been added to the three basic widgets (XmPrimitive, XmManager and XmGadget), affecting their subclasses:
NameTypeDefaultDescription
XmNlayoutDirectionXmLayoutDirectionXmRIGHT_DOWNlayout-direction
XmNtextModeXmTextModeXmTEXT_MODE_IMPLICITlogical-order

In those programs in which the user can define widget-illustrated objects, for which only their names and some of their attributes can be controlled, but not their resources (as for some of the databases), the user can be provided a tool of such power that it will allow determination of the object's directionality through its name prefix. This is performed by assigning a value to either one or two environment variables H_HEBREW_PREFIX and H_LATIN_PREFIX. For instance, the following command (under csh):

setenv H_HEBREW_PREFIX H_

will cause all widgets beginning with the H_ string to adopt Hebrew directionality (right to left) by automatically changing to the XmNlayoutDirection and XmNstringDirection values.



5.2 XmNlayoutDirection


5.2.1 XmNstringDirection Default

The following widgets have a XmNstringDirection resource:

XmManager, XmList, XmLabel, XmLabelGadget.

When a XmLEFT_DOWN value is assigned to XmNlayoutDirection, the XmNstringDirection default for those widgets is XmSTRING_DIRECTION_R_TO_L, instead of XmSTRING_DIRECTION_L_TO_R.

This feature applies to their subclasses as well:

XmBulletinBoard, XmSelectionBox, XmCommand, XmFileSelectionBox,
XmForm, XmMessageBox, XmDrawingArea, XmFrame, XmPanedWindow, XmRowColumn,
XmScale, XmScrolledWindow, XmMainWindow, XmCascadeButtonGadget,
XmPushButtonGadget, XmToggleButtonGadget, XmCascadeButton, XmDrawnButton,
XmPushButton, XmToggleButton.

XmNstringDirection is a resource which according to Motif's official documentation should affect the behvior of many Motif widgets, although in most cases this is not actually correct (except in particular cases, such as XmList, in which the alignment directionality is actually influenced by this resource, but causing other bugs which have been resolved in the Hebrew support). This serious bug is solved in the Hebrew support for Motif, while other features controlled by this resource have been added as well.

Since the XmNlayoutDirection value affects the XmNstringDirection default, it is possible to assign a XmLEFT_DOWN value to it for every application (by means of the resources file, for example), thereby affecting the features controlled by XmNlayoutDirection and those controlled by XmNstringDirection.

For more information on XmNstringDirection, see 5.5.


5.2.2 XmCommand

When the XmLEFT_DOWN value is assigned to XmNlayoutDirection, the prompt string is aligned to the right edge (instead of to the left). For more information on inherited Hebrew features, see XmSelectionBox, 5.2.6.


5.2.3 XmMessageBox

When the XmLEFT_DOWN value is assigned to XmNlayoutDirection, the Pixmap denoting the XmMessageBox type is placed to the right of the message (instead of to its left) and the buttons are arranged right to left (instead of vice versa) - so that the OK button is located to the right (instead of to the left), and the defaults of the various strings change in the following manner:
NameEnglish DefaultHebrew Default
XmNcancelLabelStringCancel
XmNhelpLabelStringHelp
XmNokLabelStringOK


5.2.4 XmRowColumn

When the XmLEFT_DOWN value is assigned to XmNlayoutDirection, the order of all the inner widgets is symmetrically reversed: whatever was to the right is now placed to the left and vice versa. In addition, in terms of menus, the following changes apply as well, according to the menu type:

XmPulldownMenu pulled down from XmMenuBar or another horizontal menu:

Its right edge is aligned to the right edge of the XmCascadeButton pulling it down (instead of left edge to left edge).

XmPulldownMenu pulled down from a XmPulldownMenu or another vertical menu:

Opens to the left of the XmCascadeButton pulling it down (instead of to its right).

XmOptionMenu:

The label is placed to the right of the XmCascadeButtonGadget, and the Pixmap to its left (instead of vice versa).

XmMenuBar:

The Help button is aligned to the left edge (instead of to the right).


5.2.5 XmScrolledWindow

When the value XmLEFT_DOWN is assigned to XmNlayoutDirection, the XmNscrollBarPlacement default is XmBOTTOM_LEFT (instead of XmBOTTOM_RIGHT). This feature is relevant to subclasses, such as XmMainWindow and XmScrolledList.


5.2.6 XmSelectionBox

When the XmLEFT_DOWN value is assigned to XmNlayoutDirection, the buttons are arranged right to left (instead of vice versa), so that, for instance, the OK button is placed to the right (instead of to the left), and the various string defaults change in the following manner:
NameEnglish DefaultHebrew Default
XmNapplyLabelStringApply
XmNcancelLabelStringCancel
XmNhelpLabelStringHelp
XmNlistLabelStringItems
XmNokLabelStringOK
XmNselectionLabelStringSelection


5.2.7 XmText

A separate paragraph, 5.4, is dedicated to XmText and XmTextField.


5.2.8 XmTextField

A separate paragraph, 5.4, is dedicated to XmText and XmTextField.



5.3 XmNtextMode


5.3.1 General

This resource allows storage of strings in a logical character order, rather than the physical order in which these strings are displayed on the screen. This feature is essential for many operations, such as sorting, use of strings when the main directionality changes, compatibility with other systems (MS Windows), etc. However, in many cases, strings must be stored according to their physical order, so this is allowed as well.

The possible values of this resource are XmTEXT_MODE_IMPLICIT (by default) and XmTEXT_MODE_VISUAL. When the value is XmTEXT_MODE_IMPLICIT, every string which should be displayed on screen undergoes a relevant conversion. In addition, every input string undergoes the opposite inversion.

The algorithm performed on the strings is out of the scope of this document, therefore we shall now concentrate only on examples.

Let's begin with the textual widgets (XmText, XmTextField). (*) represents the character order in the memory when XmNtextMode is XmTEXT_MODE_VISUAL, and (**) represents the character order in the memory when XmNtextMode is XmTEXT_MODE_IMPLICIT. When the main direction is Latin (XmNlayoutDirection = XmRIGHT_DOWN), we get the following:
visual(*):012345678910111213
Mynameis
implicit(**):012345678910131211

When the main direction is Hebrew (XmNlayoutDirection = XmLEFT_DOWN), we get the following:
109876543210visual(*)
Eli
891076543210implicit(**)


5.3.2 Compound Strings

The possibility to store the characters in a logical (implicit) order is supported not only for textual widgets (see 5.4), but for the following widgets:

XmLabel, XmLabelGadget, XmList

and their subclasses as well, but with a difference: this case refers to compound strings, which contain an explicit directionality. Therefore, when XmNtextMode is XmTEXT_MODE_VISUAL, ignore the directionality of XmNstringDirection (although it will continue to affect the compound string segment display order); the string will be displayed only according to its internal directionality. However, when XmNtextMode is XmTEXT_MODE_IMPLICIT, the directionality will be set according to XmNstringDirection, and in the transition between storage mode to display and vice versa, the string will undergo both inversion and conversion: In the transition between storage to display, the characters will be converted to visual mode, the value of XmNStringDirection will be checked, and if it is found to be Hebrew, the characters will be inverted. In the transition between display to storage, the value of XmNStringDirection will be checked, if it is found to be Hebrew, the characters will be inverted and in any case, the characters will be converted to implicit mode.

The following are examples of the above. (*) represents the character order in the memory when XmNtextMode is XmTEXT_MODE_VISUAL, and (**) represents the character order in the memory when XmNtextMode is XmTEXT_MODE_IMPLICIT. When the main direction is Latin (XmNlayoutDirection = XmRIGHT_DOWN), we get the following:
visual(*):012345678910111213
Mynameis
implicit(**):012345678910131211

When the main direction is Hebrew (XmNstringDirection = XmSTRING_DIRECTION_R_TO_L), we get the following:
012345678910visual(*)
Eli
891076543210implicit(**)



5.4 XmText and XmTextField

In this section we will refer in parallel to two widgets, XmText and XmTextField. Actually, in regard to Hebrew, there is almost no difference between the two, although we recommend preference of XmTextField whenever the special features of XmText (such as multiple lines) are not required, since the <Ctrl><Hebrew> response time might be longer whenever the application is loaded with many XmText widgets. In the following paragraphs, we will refer to both of them together - whenever XmText is mentioned, the information applies to XmTextField as well, accordingly, except in those cases specified otherwise.

The widget described in this section corresponds to the original XmText, but adds bi-directionality to it. When XmTEXT_MODE_VISUAL is assigned to XmNtextMode, the character order in the memory will be according to their physical order on the screen, according to the widget's main direction. If the string "" ("Hebrew") is received by the widget from right to left, the "" will be placed first in storage, while the "" will be placed last. However, if the string is received by the widget whose main directionality runs from left to right, and it is received in pushing mode, the "" will be placed first, and the "" last. When XmTEXT_MODE_IMPLICIT is assigned to XmNtextMode (as default is), the "" will be placed first in storage in any event, and the "" will be placed last. For more information, see 5.3.


New Resources:

NameTypeDefaultDescription
XmNeditingPathXmLayoutDirectiondynamiccurrent text editing path
XmNbidiModeXmTextModeimplicituser-interface directionality
XmNinitialLanguageBooleanfalseautomatic language toggle
XmNlineWidthInteger0opt. alignment by leading spaces
XmNtabWidthInteger8# of spaces per tab for alignment


5.4.1 XmNlayoutDirection (inherited from XmPrimitive)

When XmLEFT_DOWN is assigned to this resource, the widget's directionality will be inverted right to left. The alignment will be performed to the right, and the character flow main direction will be right to left. However, when XmRIGHT_DOWN is the assigned value, the main direction and alignment will be as with the original XmText and XmTextField.


5.4.2 XmNtextMode (inherited from XmPrimitive)

When XmTEXT_MODE_VISUAL is assigned to this resource, the character storage order in the memory will be according to their display on the screen. For example, if the character combination "" is included in the widget whose main direction is from right to left, the character order in the memory will be "", "", "", "". If this character combination is included in the widget whose main direction is from left to right, the character order in the memory will be "", "", "", "". Appropriately, in order to display the above-mentioned character combination on screen, the character order described above must be assigned to the widget.

When XmTEXT_MODE_IMPLICIT is assigned to this resource (as the default is), the storage character order in the memory will not be according to their display on screen, but according to their logical order. Between the memory storage and the screen display, the character string will undergo a HImplicitToVisual() process (see 3.6), and between the screen display and the memory storage, the character string will undergo a HVisualToImplicit() process (see 3.7). For example, if the character combination "" is included in the widget whose main direction is right to left, the character order in the memory will be "", " ", "", "". If this character combination is included in the widget whose main direction is from left to right, the character order in the memory will be "", "", "", "". Appropriately, in order to display the above-mentioned character combination on screen, the character order described above must be assigned to the widget.

This resource affects the paste and cut/copy functions, the actions that get the widget's value or part of it (for example, XmTextGetString() ), the actions that alter the widget's value or part of it (for example, XmTextSetString()), and all the actions that use XmNvalue (such as XmCreateText(), XtSetValues()). For more information, see 5.3.


5.4.3 XmNeditingPath

When the value of XmLEFT_DOWN is assigned to this resource, the widget's current character flow direction is from right to left, while when XmRIGHT_DOWN is the assigned value, the direction will be as with the original XmText and XmTextField. When the value of this resource contradicts the XmNlayoutDirection value, the current direction will contradict the widget's main direction, and a "character push" is performed. When this action is completed, as soon as the value of XmNeditingPath is changed, the cursor will jump to its place at the end of the 'pushed' segment. The default value of this resource is loaded from the primary value of XmNlayoutDirection (see 5.4.1) or according to the current language.


5.4.4 XmNbidiMode

When the value XmTEXT_MODE_VISUAL is assigned to this resource, the user interface is visual, i.e. mono-directional. This means that the directionality is not language-dependent, and that the only way to change the direction is by using <F11>, which activates the toggle-editing-path action.

When the value XmTEXT_MODE_EXPLICIT is assigned to this resource, the user interface is explicit, i.e. affected by language switching. The switch to a language whose directionality is opposed to the widget's directionality will cause transition to pushing mode, and the transition back will end it. Language switching is performed by <Ctrl><Hebrew> (or <Extend> in HP environment). Every entry and exit from pushing mode affects the current character flow direction value (XmNeditingPath, see 5.4.3).

When the value XmTEXT_MODE_IMPLICIT is assigned to this resource, the user interface is implicit, i.e. affected not only by language switching, but causing a direction change even when the typed character language is opposed to the current one. This interface is very similar to the previous one; the main difference is that while typing in Hebrew, you can type Latin numbers or capital Latin letters without having to switch languages. In the previous mode, this would have not caused language switching, while here it does.

In any case, the <F11> key activates the toggle-editing-path action, which changes the direction independent of the mode and language.

When the compatibility mode to Microsoft is on, this resource is neutralized (see 5.3.1).


5.4.5 XmNinitialLanguage

When the 'True' value is assigned to this resource, every widget entry (i.e. FocusIn) will cause language switching to the language suitable to the widget's main direction (i.e. XmNlayoutDirection). For example, if the current language is English, and FocusIn is performed to a widget whose main direction is right to left and 'True' is assigned to this resource, the language will automatically change to Hebrew. During exit (FocusOut), the language will change back to English. If the user changes the language while in the widget, the language will not change upon exit. In the above example, if the language was already Hebrew upon entry, no language change will be performed either upon entry or exit.

This feature is inconsistent with the Hebrew support, according to which the language is exclusively set according to the user's requirements (<Ctrl><Hebrew>). We recommend not using this feature, unless there is no choice.


5.4.6 XmNlineWidth, XmNtabWidth

When a non-zero value is assigned to XmNlineWidth, every content retrieval from XmText (but not from XmTextField) whose main direction is right to left and which has the value XmTEXT_MODE_VISUAL assigned to its XmTextMode, will supply a special text in which space characters are added at the beginning of every line, causing the text to be displayed as if it were aligned to the right, although it may be printed left to right (if this is performed by mono-spaced fonts, i.e. every font requires the same width). In addition to the space characters, the text itself will be adapted to left to right display, i.e. the left-edge text characters will precede those at the right edge.

The value assigned to XmNlineWidth represents the selected line width. For example, if a value of 80 will be assigned to XmNlineWidth of line containing 73 characters, 7 spaces will be added at the beginning, so the line will be displayed as if aligned to the right. When the number of characters per line is greater or equal to the value assigned to XmNlineWidth, no spaces will be added to the line. Israeli standard 1904 recommends use of a 72 line width for electronic mail messages.

When the line to be right-aligned by XmNlineWidth includes tabs, their width will be calculated according to the value assigned to XmNtabWidth (default=8) and according to their place in the line as well.



5.5 XmNstringDirection

This is an existing resource, which according to Motif's official documentation should affect the behavior of many Motif widget classes, although this is not actually true in most cases (except individual cases such as XmList, in which the alignment direction is indeed affected by this resource, although with more than a few bugs). This serious bug is corrected in Motif's Hebrew support. In addition, many features affected by this resource have been added as well.

The primary value of this resource is affected by the value XmNlayoutDirection (see 5.2.1), and we recommend use of XmNlayoutDirection.


5.5.1 XmCascadeButton

When the value XmSTRING_DIRECTION_R_TO_L is assigned to XmNstringDirection, the following features are added to the Hebrew features inherited by this widget from XmLabel (see 5.5.4):

  1. The arrow (from a drop-down or pop-up menu) will point to the left, not to the right.
  2. The cascading pixmap will be drawn in the widget's left edge, instead of the right.

For information on the location of the sub-menu pulled down by XmCascadeButton, see 5.2.4.


5.5.2 XmCascadeButtonGadget

When the value XmSTRING_DIRECTION_R_TO_L is assigned to XmNstringDirection, the following features are added to the Hebrew features inherited by this widget from XmLabelGadget (see 5.5.5):

  1. The arrow (from a pull-down or pop-up menu) will point to the left, not to the right.
  2. The cascading pixmap will be drawn in the widget's left edge, instead of the right.

For information on the location of the sub-menu dropped down by XmCascadeButtonGadget, see 5.2.4.


5.5.3 XmForm

When the value XmSTRING_DIRECTION_R_TO_L is assigned to XmNstringDirection, the following resource notations are changed:
XmNleftAttachementXmNrightAttachment
XmNleftOffsetXmNrightOffset
XmNleftPositionXmNrightPosition
XmNleftWidgetXmNrightWidget


5.5.4 XmLabel

When the value XmSTRING_DIRECTION_R_TO_L is assigned to XmNstringDirection, the value of XmALIGNMENT_BEGINNING in XmNalignment will cause right alignment (instead of left), and XmALIGNMENT_END will cause left alignment (instead of right).

In addition, in this case (XmSTRING_DIRECTION_R_TO_L value), when values are assigned both to XmNlabelString and XmNacceleratorText, and the value assigned to XmNacceleratorText should be displayed (i.e. it refers to XmPushButton or XmToggleButton under PULLDOWN or POPUP), it will be displayed to the left of the XmNlabelString value (instead of to its right).

These behaviors are also relevant to all XmLabel subclasses, such as XmCascadeButton, XmDrawnButton, XmToggleButton, XmPushButton.


5.5.5 XmLabelGadget

When the value XmSTRING_DIRECTION_R_TO_L is assigned to XmNstringDirection, a XmALIGNMENT_BEGINNING value in XmNalignment will cause right alignment (instead of left), and a XmALIGNMENT_END value will cause left alignment.

In addition, in this case (XmSTRING_DIRECTION_R_TO_L value), when values are assigned both to XmNlabelString and XmNacceleratorText, and the value assigned to XmNacceleratorText should be displayed (i.e. it refers to XmPushButtonGadget or XmToggleButtonGadget under PULLDOWN or POPUP), it will be displayed to the left of the XmNlabelString value (instead of to its right).

These behaviors are also relevant to all XmLabel subclasses, such as XmCascadeButtonGadget, XmPushButtonGadget, XmToggleButtonGadget.


5.5.6 XmToggleButton

When the value XmSTRING_DIRECTION_R_TO_L is assigned to XmNstringDirection, the following feature is added to the Hebrew features inherited by this widget from XmLabel (see 5.5.4): the indicator will be displayed to the right of the label (and not to its left).


5.5.7 XmToggleButtonGadget

When the value XmSTRING_DIRECTION_R_TO_L is assigned to XmNstringDirection, the following feature is added to the Hebrew features inherited by this widget from XmLabelGadget (see 5.5.5): the indicator will be displayed to the right of the label (and not to its left).



5.6 Use of Hebrew Features within UIL

You can use XmNstringDirection, XmSTRING_DIRECTION_R_TO_L and XmSTRING_DIRECTION_L_TO_R within the UIL program without any further changes or additions.

To use the following Hebrew features within the UIL program:

XmRIGHT_DOWN, XmLEFT_DOWN
XmTEXT_MODE_VISUAL, XmTEXT_MODE_IMPLICIT
XmNlayoutDirection, XmNtextMode
XmNeditingPath, XmNbidiMode, XmNinitialLanguage
XmNlineWidth, XmNtabWidth

it is necessary to include the following command at its beginning:

include 'Hm.uil'

For more information, see also Annex A.2.





CHAPTER 6 - ATTACHED DEMO PROGRAMS




6.1 Bilingual and Bi-directional Editor

Two executable files (amongst others) are found in /usr/H/asedit:

asedit    -   a bi-directional editor with menus in English

asorech   -   a bi-directional editor with menus in Hebrew


Invocation:

asorech [-direction <dir>] [-textMode <text_mode>] [optional file-name]

or:

asedit [-direction <dir>] [-textMode <text_mode>] [optional file-name]

<dir> can be right_down (for left-to-right directionality) or left_down (for right-to-left directionality). <text_mode> can be text_mode_visual or text_mode_implicit. In addition, it is possible to set the priniting command used by these programs to print files. Assigning a UNIX command in the PRINT_CMD environment variable, will cause the contents of the printing to be passed (by a UNIX pipe) to this command. For example (under csh):

setenv PRINT_CMD "lpr -Pmy_printer"

Additional explanations about the manner of work may be found by context-sensistive help based on hypertext (from the software) and the asedit.man.

The rest of the files in the directory are sources that may be compiled by make. The changes for the Hebrew support are delimited by the following macros:

#ifdef HEBREW
...
#endif

The changes in asorech relative to asedit are delimited in a similar manner, but by the word ASORECH instead of the word HEBREW.



6.2 hmdialogs

Two executable files (amongst others) are found in /usr/H/demos:

xmdialogs   -    a standard Motif demo with a number of additional
                features and a performed link together with Hebrew
                support libraries

hmdialogs   -    the same, but compiled with an additional flag:
                -DHMDIALOGS


By running hmdialogs alongside xmdialogs, it is possible to see the differences between software whose main direction is from right to left and software whose main direction is from left to right.

The rest of the files in the directory are sources that may be compiled by make. The changes in hmdialogs relative to xmdialogs are delimited by the following macros:

#ifdef HMDIALOGS
...
#endif





ANNEX A: INSTALLATION, COMPILATION AND RUNNING ENVIRONMENT




A.1 Installation

After moving the H.Dist.tar.Z file from the magnetic medium into a directory labeled /usr/H, open it by the following command:

zcat H.Dist.tar.Z | tar xovf -

The installation phase is actually finished; nevertheless, we must now ensure that the various environments will indeed use the Hebrew support (this is achieved by following the instructions detailed in the other sections of this annex). It is also necessary to correct flaws in the installation of X and/or Motif, according to the instructions noted below in this section. All the instructions in this section must be performed by the super-user. Please perform the checks and commands in their given order. These instructions are designed to correct a system in which X was improperly installed. Failure to comply with command 1 might cause the X server to generally crash while running most of the Motif programs. Failure to comply with commands 2, 3, or 4 might cause many malfunctions, and the Motif programs might also crash (for example, during pasting). Failure to comply with command 5 might cause the appearance of various warning messages when running Motif programs, and the special keys (for example, the arrow keys) might not function. Most systems (except for some Sun systems) are properly installed, therefore these instructions are irrelevant to them.

  1. In order to run Motif-1.2 under Openwin-3.0, it is compulsory to install SunSoft's Patch#100444.
  2. If there is no /usr/lib/X11/nls directory in the system, create it using the following command:
    mkdir -p /usr/lib/X11/nls
  3. If there is no /usr/lib/X11/nls/C file in the system, create it using the following command:
    cp /usr/H/C /usr/lib/X11/nls
  4. If there is no /usr/lib/X11/nls.dir file in the system, create it using the following command:
    cp /usr/H/nls.dir /usr/lib/X11/nls
  5. If there is no /usr/lib/X11/XKeysymDB file in the system, create it using the following command:
    cp /usr/H/XKeysymDB /usr/lib/X11

In addition, if there is no /usr/lib/X11/nls/C.7bit file in the system, create it using the following commands:

cp /usr/lib/X11/nls/C /usr/lib/X11/nls/C.7bit
cp /usr/H/C /usr/lib/X11/nls

Otherwise, operations such as cut & paste, or drag & drop, will not function in Hebrew character strings.



A.2 Compilation (at source level)

In order to include the Hebrew support include files in the compilation (which are under /usr/H/include/X11 and /usr/H/include/Xm), add the following flag after the cc and uil commands:

-I/usr/H/include

For example (the rest of the flags are according to the system):

cc -I/usr/H/include -I/usr/X11 -DSYSV -DSVR4_0
-O -c try.c



A.3 Link

In order to link the Hebrew support libraries and object files (/usr/H/lib/*/*.o), add them during the link using their full name, before the library names. The files to be added are according to the program type compiled:

Non-Xt Programs:

/usr/H/lib/X11/MSBiDi.o

Motif Programs (before any other -L, no need for any object file):

-L/usr/H/lib/Xm



A.4 Environment Variables

To enable the user to enjoy the Hebrew support, some lines must be added to his ".xinitrc" file or to some other file containing Shell Script run during X-Windows startup (in some systems, ".xsession" or "xstart.sh"). These lines affect the default values of various resources, and add Hebrew fonts (correspondingly). These lines can be found at "/usr/H/xinitrc":

xset +fp /usr/H/fonts
xrdb -merge /usr/H/Xdefaults

This file (/usr/H/xinitrc ) must be planted within ".xinitrc", ".xsession" or "xstart.sh" (according to the operating system), after all the startup calls (for example, xset fp or xrdb calls), but before calling the various clients (for example, mwm or xterm). When using applications not supported in Hebrew, it is possible to add a call to km or km_light (see chapter 1).

In addition, it is highly recommended that the first referral of the environment variable LD_LIBRARY_PATH always be to the Hebrew Motif library directory, /usr/H/lib/Xm. This is achieved (under csh) as follows:

setenv LD_LIBRARY_PATH /usr/H/lib/Xm:$LD_LIBRARY_PATH

when this variable holds a previous value. If it lacks one:

setenv LD_LIBRARY_PATH /usr/H/lib/Xm

The same applies to addition of the /usr/H/bin value to the PATH environment variable.

H_LAYOUT_ALGORITHM: This is another environment variable that might affect the behavior of Hebrew Motif programs. Assigning the value OLD to it will cause all the implicit storing method widgets to use the old bidirectional algorithm, instead of the the new algorithm used by the Hebrew version of Microsoft Windows.

It is recommended to add the directory "/usr/H/man" to the directories listed in the "MANPATH" environment variable, so the man command will have an access to the documentation of the Hebrew Support, too.



A.5 Special Keys

FunctionKey Combination
toggle the language<Ctrl><Alt> or <Ctrl><Meta>
enter into push-mode (km/hterm)<Alt>Left-Button or <Shift><Ctrl>Left-Button
return from push-mode (km/hterm)<Enter>
cancel push-mode (km/hterm)<Esc>
reverse current Text Widget to Hebrew<Ctrl><Right-Shift>
reverse current Text Widget to Latin<Ctrl><Left-Shift>
LRM<Alt><Left-Shift> or <Left-Alt><Backspace>
RLM<Alt><Right-Shift> or <Right-Alt><Backspace>





ANNEX B: FILES AND FONTS INCLUDED IN THE PACKAGE


/usr/H/COPYRIGHT
/usr/H/H-Windows
/usr/H/XdefaultsExamples of resources-values
/usr/H/xinitrcTo be inserted to $HOME/.xinitrc
/usr/H/HebrewCustomization file for Hebrew
/usr/H/XKeysymDBKeysyms database for corrupt Motif installation
/usr/H/nls.dirNLS file for corrupt X11 installation
/usr/H/CNLS file for corrupt X11 installation
__________________________________________________________________
Asedit:
/usr/H/asedit/aseditBilingual editor, English as main language
/usr/H/asedit/asorechBilingual editor, Hebrew as main language
/usr/H/asedit/MakefileMakefile for compiling asedit and asorech
/usr/H/asedit/Asedit.ad.hDefaults for asedit and asorech
/usr/H/asedit/asedit.hlpHelp file for asedit and asorech
/usr/H/asedit/asedit.manAsedit user's manual
/usr/H/asedit/asedit_icon
/usr/H/asedit/asedit.h
/usr/H/asedit/clipbrd.h
/usr/H/asedit/as_menuh.c
/usr/H/asedit/asedit.c
/usr/H/asedit/asutil.c
/usr/H/asedit/clipbrd.c
/usr/H/asedit/file_rw.c
/usr/H/asedit/find_pos.c
/usr/H/asedit/ht_help.c
/usr/H/asedit/undo.c
/usr/H/asedit/write_lw.c
__________________________________________________________________
Demos:
/usr/H/demos/MakefileMakefile for compiling demos with Hebrew
/usr/H/demos/xmdialogs.cA standard demo of Motif, in English/Hebrew
/usr/H/demos/xmdialogsExecutable file for xmdialogs.c
/usr/H/demos/hmdialogsThe same, but Hebrew version
__________________________________________________________________
Executables:
/usr/H/bin/replace_strReplaces strings in binary files
/usr/H/bin/kmKeyboard Manager
/usr/H/bin/km_lightFaster than km, but only for <Ctrl><Hebrew>
/usr/H/bin/htermxterm + Hebrew Support
__________________________________________________________________
Object Files and Libraries:
/usr/H/lib/X11/H.oAn object file to be linked with X programs
/usr/H/lib/Xaw/*.oThe same, but for Xaw programs
/usr/H/lib/Xm/libXm.*Motif libraries with Hebrew support (static and dynamic)
__________________________________________________________________
Man Pages:
/usr/H/man/man1/hterm.1
/usr/H/man/man1/km.1
/usr/H/man/man1/replace_str.1
/usr/H/man/man1/uil.1
/usr/H/man/man3/HAddCtrlHebr.3
/usr/H/man/man3/HGetKeyboard.3
/usr/H/man/man3/HImplicitToV.3
/usr/H/man/man3/HInitCtrlHeb.3
/usr/H/man/man3/HIsKmActive.3
/usr/H/man/man3/HRebindKeybo.3
/usr/H/man/man3/HReverseText.3
/usr/H/man/man3/Intro.3
/usr/H/man/man3/XmCascadeBut.3
/usr/H/man/man3/XmCascadeBuG.3
/usr/H/man/man3/XmForm.3
/usr/H/man/man3/XmGadget.3
/usr/H/man/man3/XmLabel.3
/usr/H/man/man3/XmLabelGadge.3
/usr/H/man/man3/XmList.3
/usr/H/man/man3/XmManager.3
/usr/H/man/man3/XmMessageBox.3
/usr/H/man/man3/XmPrimitive.3
/usr/H/man/man3/XmRowColumn.3
/usr/H/man/man3/XmScrolledWi.3
/usr/H/man/man3/XmSelectionB.3
/usr/H/man/man3/XmText.3
/usr/H/man/man3/XmTextField.3
/usr/H/man/man3/XmToggleButt.3
/usr/H/man/man3/XmToggleButG.3
/usr/H/man/H.docHebrew documentation (Word for Windows file)
__________________________________________________________________
Include Files:
/usr/H/include/MakefileHeader file for all the makefiles in the package
/usr/H/include/X11/H.hAn include file to be included in X programs
/usr/H/include/X11/Xaw/*.h
/usr/H/include/Xm/*.hThe same, but for Motif programs
/usr/H/include/Hm.uilThe same, but for UIL programs



Font Names (file names depend on the operating system)

Notes: These fonts are public domain and do not belong to the package. Most of them have been developed by Eli Marmor, while others derive from diverse sources (for example, X11R5); all of them may be copied and used free of charge, even without the Hebrew support package, but provided that nothing will be modified in them, including their full names and copyright notes. In addition to the following fonts, other fonts might be found in some workstations, according to the vendor's policy.

Each line in the following tables contains the full name of a font (in the first column), and an optional alias (in the second column). Fonts marked with '' (in the third column) are recommended for daily use (for example, xterm). In order to show a font, click on its name.


Non-Proportional Fonts (Monospace/CharCell):

In the following fonts, the character width is constant; therefore, they can be used for programs requiring this (as xterm):
Small Fonts:
-hebrew-bible-medium-r-normal--8-80-75-75-m-80-iso8859-8heb-bible8x8
-hebrew-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso8859-8heb6x13
-hebrew-fixed-medium-r-normal--13-120-75-75-c-80-iso8859-8heb8x13
-hebrew-fixed-bold-r-normal--13-120-75-75-c-80-iso8859-8
-hebrew-fixed-medium-r-normal--14-130-75-75-c-70-iso8859-8heb7x14
Medium Fonts:
-hebrew-bible-medium-r-normal--14-140-75-75-m-80-iso8859-8heb-bible8x14
-hebrew-bible-medium-r-normal--16-160-75-75-m-80-iso8859-8heb-bible8x16
-hebrew-new-medium-r-normal--14-140-75-75-m-80-iso8859-8heb-new8x14
-hebrew-new-medium-r-normal--16-160-75-75-m-80-iso8859-8heb-new8x16
-hebrew-rashi-bold-r-normal--16-160-75-75-m-80-iso8859-8heb-rashi
-hebrew-rashi-medium-r-normal--16-160-75-75-m-80-iso8859-8
-hebrew-bible-bold-r-normal--18-180-75-75-m-11-iso8859-8heb-bible18
-hebrew-fixed-medium-r-normal--16-150-75-75-c-80-iso8859-8heb8x16
-hebrew-fixed-medium-r-normal--20-200-75-75-c-100-iso8859-8heb10x20
-hebrew-fixed-medium-r-normal--24-170-75-75-c-120-iso8859-8heb12x24
Big Fonts:
-hebrew-maariv-bold-r-normal--36-360-75-75-c-22-iso8859-8heb-maariv
-hebrew-maariv-outline-r-normal--36-360-75-75-c-22-iso8859-8heb-maariv-outline
-hebrew-maariv-shadow-r-normal--36-360-75-75-c-22-iso8859-8heb-maariv-shadow
-hebrew-terminal-bold-r-normal--36-360-75-75-c-22-iso8859-8heb-term
-hebrew-terminal-cut-r-normal--36-360-75-75-c-22-iso8859-8
-hebrew-terminal-outline-r-normal--36-360-75-75-c-22-iso8859-8heb-term-outline
-hebrew-terminal-shadow-r-normal--36-360-75-75-c-22-iso8859-8heb-term-shadow


Proportional Fonts (variable pitch):

In the following fonts, the character width is not constant; therefore, they can not be used for programs requiring this (as xterm):
-hebrew-script-medium-i-normal--14-140-75-75-p-73-iso8859-8heb-script-small
-hebrew-script-bold-i-normal--24-240-75-75-p-128-iso8859-8heb-script
-hebrew-bible-medium-r-normal--7-70-75-75-p-80-iso8859-8heb-bible-variable7x8
-hebrew-bible-bold-r-normal--18-180-75-75-p-11-iso8859-8heb-bible-variable18
-hebrew-bible-bold-r-normal--28-280-75-75-p-150-iso8859-8heb-bible28
-hebrew-bible-outline-r-normal--28-280-75-75-p-150-iso8859-8heb-bible-outline28
-hebrew-bible-bold-r-normal--45-450-75-75-p-150-iso8859-8
-hebrew-bible-outline-r-normal--45-450-75-75-p-150-iso8859-8
-hebrew-menu-medium-r-normal--13-100-100-100-p-77-iso8859-8heb-variable13
-hebrew-menu-medium-r-normal--16-120-100-100-p-92-iso8859-8heb-variable16
-hebrew-maariv-bold-r-normal--36-360-75-75-p-22-iso8859-8heb-maariv-variable
-hebrew-maariv-outline-r-normal--36-360-75-75-p-22-iso8859-8heb-variable-outline
-hebrew-maariv-shadow-r-normal--36-360-75-75-p-22-iso8859-8heb-variable-shadow





ANNEX C: TROUBLESHOOTING AND LIMITATIONS




X-Server:

  • The Hebrew support can be used even when the screen which the windows are displayed on is an X terminal or an X emulator for PC or Windows. Ensure that the server recognizes the Hebrew fonts. In some X terminals, Hebrew fonts can be directly provided by the vendor; in others, they must be loaded. The font files formats are not always the same between the workstation and the X terminal. The ideal solution in most environments is to run a font server at one of the network workstations.
  • Using the X server for an MS-Windows environment (which shows strings via the regular Windows mechanism) might cause a string- inversion problem when using the Hebrew support for Windows, since this support inverts Hebrew character strings sent to the screen, although these strings have already been inverted by this package. To solve this problem, only X Hebrew fonts must be used (some of the servers require conversion of these fonts to the Windows format. Otherwise, they can be loaded from a font server). In the multilingual Microsoft version, there is another problem: Hebrew characters sent to the screen for display using an X Hebrew font are exchanged with the corresponding Windows Hebrew fonts, recognized as Hebrew by the multilingual Microsoft version. Therefore, the previous solution is neutralized and irrelevant. In this case, the mouse cursor must be pointed to the at the upper left window corner and the right-hand mouse button clicked. This method is specially efficient when windows of X are not directly displayed on MS-Windows but condensed through a special window or screen of the X-server, so that one click on its corner will do.
  • Some X emulators for Windows have a bug causing X to perceive the <Alt> key as constantly being pressed when the <Alt> and <Ctrl> keys are simultaneously released. Please avoid such a release. If the above occurred nevertheless, press <Ctrl><Alt> again and release them one by one (i.e. pres <Ctrl>, press <Alt>, release <Alt>, release <Ctrl>).



Motif Programs, Compilation and Link

  • A dynamically-linked Motif program opened without Hebrew: Ensure that it is using the Hebrew library and not the system's original library. In most environments, this can be checked through the Idd command or the environment variable LD_LIBRARY_PATH (which must contain either "/usr/H/lib/Xm" or "/usr/H/lib/Xm:...", where "..." stands for the other directories searched).
  • The compiler cannot find various definitions: Check whether all the include files required for the compilation have been included, and also check whether the A.2 instructions have been followed.
  • The compiler can not find Hebrew include files: Check whether A.2 instructions have been followed.
  • Id can not find Hebrew functions or widgets: Check whether A.3 instructions have been followed.
  • Language switching (<Ctrl><Hebrew>) in a heavy application running under a loaded system is not immediate and your response time is too long: Prefer XmTextField over XmText whenever possible.
  • In Hebrew dialog boxes there is a problem with tab groups, sometimes causing the transition order between the inner widgets to remain from left to right.
  • It is not possible to combine Hebrew mnemonics within UIL programs, since the library libMrm has no Hebrew support, therefore it reports that it is impossible to convert the keysym.
  • Transition from Hebrew to English might neutralize previous calls of the XRebindKeysym() application.



KM:

  • KM refuses to open: Check whether there is another active KM; if so, it is unnecessary to open another KM.
  • KM has been "killed" by mistake: Reactivate with the km command (see 3.2.1).
  • Some platforms have clients (such as 4Dwm or the inner NCD Window Manager) using <Ctrl><Shift>Button1 or <Alt>Button1; therefore, in order to open a Hebrew input field, these two combinations exist in parallel, so although one of them may be neutralized, the other one may still be used. In any case, you can work at NCD terminals without a Window Manager, or with another computer's Window Manager. You can also use your own Window Manager, temporarily turning it off while setting up the Hebrew support and reactivating it following setup.
  • Text typing and inversion pasting by the Keyboard Manager are possible only with those applications that are able to receive text from the cut buffer (i.e. paste) through Button2 (all Motif and X-Windows applications), unlike Open-Look applications. Furthermore, the only applications supported are those that respect Button2, although it may have been sent from SendEvent. Most of the applications do, but some of them (such as xterm) do so only when a certain resource requires it. To this end, the /usr/H/Xdefaults file includes the following line:
    *allowSendEvents: true
    For the same reason, the "-WS" flag must be added to the xview application (in order to use the km_light).
  • Since km is Motif-based, it is large and clumsy. In particularly slow or loaded platforms, its response time might not be immediate, so "km_light" can be run in its place, as it is based on Xaw, which is small and fast.



hterm and other emulators

  • A much-too-quick click on <Ctrl><Shift>Button1 in old Sun platforms "jammed" the hterm: This problem is not related to the Hebrew support and exists in the xterm as well. To end this situation, click Button1 (left button).
  • xterm displays Hebrew characters through Latin ones ("a" instead of ""): Change it to 8 bits. In most operating systems this is performed by "stty -istrip" (hterm performs this automatically).
  • The who command supplies another user's name: Ensure that the bit "set-uid on execution" is switched on in the file /usr/H/bin/hterm (-rwsr-xr-x) and that the file owner is set to root.



Applications That Run Under hterm and Other Emulators

  • Although vi receives 8-bit characters, in some platforms they are octally displayed (for example, "\340" for ""). This does not affect typing, and ""can be typed directly instead of typing the octal value.
  • For emacs to receive 8-bit characters: In some emacs installations, run the macro "(standard-display-8bit 160 255)"; in others, run the "(standard-display-European)" macro.
  • Korn-Shell (ksh) and Bourne-Shell (sh) function well with 8 bits. In some old platforms, C-Shell (csh) cannot do that: although it displays 8 bits, it "turns off" the eighth bit of every character it receives before moving it to the application. For example:
    % echo
    y
    %
  • Some programs support 8 bits through NLS. Ensure they support a correct code set (through the NLS environment variables), including Hebrew characters. Most NLS's include the most basic code set, which supports 8 bits. For NLS to use it, run the following command (from csh or tcsh):
    setenv LC_CTYPE en_US
    or under some platforms:
    setenv LC_CTYPE C

    Usually, activate this command before running the program using NLS, except for tcsh, for which this command can be activated from within, even during its running. In some platforms, tcsh does not support NLS, and therefore it cannot support 8 bits as well.



Specific Platforms

  • In an HP environment, language switching can be done through the <Extend> keys found on either side of the space bar, whereby the right key always toggles to Hebrew, and the left to English.



Miscellaneous

  • As mentioned earlier in Annex A.4, "planting" the contents of file "/usr/H/xinitrc" in your own ".xinitrc" file (or ".xsession" or "xstart.sh", according to your environment and site) is vital to proper operation of the Hebrew support. Without it, the Hebrew fonts will not be recognized (unless they are manually loaded through the relevant xset command), the Hebrew X defaults will not be loaded (unless manually loaded by the relevant xrdb command, which will not support applications that already running, such as Window Manager or Terminal-Emulators), and the path will not include "/usr/H/bin".
  • To run the demos, it is recommended to use a 800x600 pixels color screen (minimum).





ANNEX D: COMPLIANCE WITH ISRAELI AND INTERNATIONAL STANDARDS


  • Character encoding (code set) is performed according to two standards: 8-bit encoding is performed in compliance with ISO8859/8, wherein the compatibility refers to all the characters defined in the original part of the ASCII as well as to the Hebrew characters defined according to ISO8859/8. The 7-bit encoding complies with ISO646.
  • Chapter 8 of Israeli standard 1489 notes three possible methods to support the content directionality: the visual directionality, implicit directionality, and explicit directionality. Motif's textual widgets (XmText, XmTextField) also comply with the standard required for implicit directionality (level 0, level 1, and level 2, when XmTEXT_MODE_IMPLICIT is assigned to XmNtextMode), and for visual directionality as well (when XmTEXT_MODE_VISUAL is assigned to XmNtextMode).
  • Motif's textual widgets interface (XmText, XmTextField) can be either visual, explicit, or implicit, as defined in Israeli standard 1489, Chapter 9, according to the value of XmNbidiMode.
  • Although the OSF standard "Application Environment Specification" (which defines the XmNstringDirection) and Hebrew support systems developed in the past (which defined the XmNlayoutDirection) seem to be contradictory, both possibilities are simultaneously supported by the program.
  • hterm complies downwards with xterm and ANSI. The color feature complies with the ANSI and ISO DP 6429 definitions. Hebrew features (except those features designed for multilingual functions) comply with the Hebrew features of VT and DECterm terminals.
  • The program complies downwards with its previous versions, beginning from version 2.0. In addition, the various versions designed for dozens of different platforms on which this program run are also compatible.
  • When the environment variable H_LAYOUT_ALGORITHM is not defined, the implicit directionality widgets will behave in accordance with the Microsoft-Windows Hebrew support.

Notes for the table in the following page:

  • The first row of every cell displays the character form, except in the following cases:
    tab, NL = new line, SP = space, lrm = Left to Right Mark, rlm = Right to Left Mark.
  • The second row of every cell displays the character's directionality (in the language customization file, use the numbers 2-10):
    2LLeft to right
    3RRight to left
    4ENEuropean Number
    5ANArabic Number
    6CSCommon number Separator (or NUMeric DELIMiter)
    7ETEuropean number Terminator
    8delDELimiter
    9ONOther Neutral (or White Space)
    10EPEuropean number Precursor (or NUMber PREcursor)
  • The third row (in some of the cells) displays the character received when clicking on the original character (in the cell's first row) in Hebrew mode.

0
0
16
1
32
2
48
3
64
4
80
5
96
6
112
7
128
8
144
9
160
A
176
B
192
C
208
D
224
E
240
F
0

SP
ON

0
EN

@
ON

P
L

`
ON
;
p
L






0
AN






R


R

1

!
ON

1
EN

A
L

Q
L

a
L
q
L
/






1
AN






R


R

2

"
ON

2
EN

B
L

R
L

b
L
r
L






2
AN






R


R

3

#
ON

3
EN

C
L

S
L

c
L
s
L






3
AN






R


R

4

$
EP

4
EN

D
L

T
L

d
L
t
L




$
AN

4
AN






R


R

5

%
ON

5
EN

E
L

U
L

e
L
u
L






5
AN






R


R

6

&
ON

6
EN

F
L

V
L

f
L
v
L






6
AN






R


R

7

'
ON
,
7
EN

G
L

W
L

g
L
w
L
'






7
AN






R


R

8

(
ON

8
EN

H
L

X
L

h
L
x
L






8
AN






R


R

9

)
ON

9
EN

I
L

Y
L

i
L
y
L






9
AN






R


R

A

*
ON

:
CS

J
L

Z
L

j
L
z
L













R


R

B

+
CS

;
ON
K
L

[
ON

k
L
{
ON














R



C

,
CS
<
ON

L
L

\
ON

l
L
|
ON














R



D

-
CS

=
ON

M
L

]
ON

m
L
}
ON














R

lrm
L

E

.
CS
>
ON

N
L

^
ON

n
L
~
ON














R

rlm
R

F

/
CS
.
?
ON

O
L

_
ON

o
L















R