















        Chapter 11.  IInntteerrnnaattiioonnaalliizzaattiioonn








             Internationalization is a method of application
             development that allows the application to be run in
             many different languages without rewriting the code or
             recompiling.  This chapter describes how to design
             applications to utilize Motif's internationalization
             capability.  It is not a general discussion of
             internationalization.



        11.1  IIssssuueess iinn IInntteerrnnaattiioonnaalliizzeedd AApppplliiccaattiioonnss


             There are several important issues to keep in mind when
             considering the design of an application so that it
             takes advantage of Motif's internationalization
             capabilities.



        11.1.1  IInntteerrnnaattiioonnaalliizzaattiioonn aanndd LLooccaalliizzaattiioonn


             An internationalized application contains no code that
             is dependent on the user's language, the characters
             needed to represent that language, or any formats (such
             as date and currency) that the user expects to see and
             interact with.  Motif accomplishes this by separating
             language and custom dependent information from the
             application and saving it outside the application.




        May 9, 1992                                             11-1








        OSF/Motif Programmer's Guide


             The next figure shows the kinds of information that
             should be external to an application to simplify
             internationalization.
             FFiigguurree 1111--11..  Information External to the Application














             By keeping the language and culture dependent
             information apart from the application source code, the
             application does not need to be rewritten or recompiled
             to be marketed in a different countries.  Instead, the
             only requirement is for the external information to be
             llooccaalliizzeedd to accommodate local language and custom.

             Localizing the application includes the process of
             translating certain parts of the external information
             into the appropriate language and storing the
             translated information in files that are then accessed
             by the application.  In addition, the application may
             be told the format to use to display time, date, and
             the other language or culture dependent formats shown
             in the previous figure.

             Every language consists of a set of characters that,
             either individually or in combination, represents
             meaningful words or concepts in the language.  The set
             of characters is called a cchhaarraacctteerr sseett.  The set of
             binary values needed to represent all the characters in
             a language is called a coded character set or, more
             simply, a ccooddee sseett.  Several attempts were started long
             ago to standardize character sets and continue to this
             day.  The most commonly used code set for English is
             the American National Standard Code for Information
             Interchange, more familiarly known as ASCII.  It
             originally used a 7-bit encoding scheme plus an eighth
             bit for error control.  Using 7 bits for character
             representation allows 128 unique binary values.  Later
             versions use the eighth bit as a code bit allowing 255
             characters.  Both are fine for English and some other
             alphabetic languages, but neither is suitable for



        11-2                                             May 9, 1992








                                                Internationalization


             ideographic languages such as Chinese, Japanese, and
             Korean.  Ideographic languages represent a concept or
             an idea as a single character, consequently there are
             thousands of characters in the language and two or more
             bytes are needed to represent the characters.

             Other standard code sets have been developed to
             accommodate other languages.  The ISO8859 standard is
             perhaps the most commonly used of these.  Different
             versions of the ISO8859 standard exist for various
             areas of the world.  The following table shows a
             typical language and character set relationship for
             various areas.
               TTAABBLLEE 1111--11..  Areas and Typical Character Sets

                      AArreeaa oorr LLaanngguuaaggee    CChhaarraacctteerr SSeett
                      ____________________________________
                      English             ASCII, ISO8859-1
                      Western Europe      ISO8859-1
                      Eastern Europe      ISO8859-2
                      Northern Europe     ISO8859-3
                      Russia (Cyrillic)   ISO8859-5
                      Hebrew              ISO8859-6
                      Greek               ISO8859-7, 8, 9
                      Japan               Shift JIS
                      Japan               UJIS

             See the specifications for the American National
             Standards Institute (ANSI) C and the X/Open Portability
             Guide, Issue 3 (XPG3) for more information on standards
             involved in internationalization.



        11.1.2  OObbttaaiinniinngg IInnppuutt


             Special considerations must be made for the user of an
             application to input characters in the local written
             language.  Virtually all applications require some
             action on the part of the user, often asking for input
             in one form or another.  For example, an application
             can ask the user to input information in text form,
             such as name, home address, and so on.  The user must
             then enter this information by typing it on the
             keyboard in the normal manner.  This is done with
             relative ease in an English-based application but can
             become more complex when other language text is
             desired.





        May 9, 1992                                             11-3








        OSF/Motif Programmer's Guide


             Motif uses Xlib functions to provide the basic support
             for obtaining input in a Text widget.



        11.1.2.1  TThhee PPrroobblleemmss


             Many languages are expressed by means of an alphabet
             made up of characters or letters.  The letters are
             arranged in groups to form meaningful words.  A
             keyboard suitable for the language normally contains
             all the letters of the alphabet, plus the standard
             numerals and punctuation marks.  The problem arises
             when the keyboard does _n_o_t have all the alphabet
             characters.  This can happen when a German user is
             using an English-based keyboard and needs a German
             character such as ",B."

             A far more involved example is the case of defining a
             keyboard to use for the ideographic languages.  There
             are literally thousands of characters needed to
             represent an ideograqphic language.  Obviously, no
             reasonable keyboard can be constructed with a single
             key for each character.



        11.1.2.2  TThhee SSoolluuttiioonn


             Motif solves these input problems by using an iinnppuutt
             mmeetthhoodd, which is a layer of mapping between the
             keyboard keys (or combinations of keys) that the user
             types and the text data that is passed to the
             application.  For example, the Swedish user with an
             English keyboard who needs the letter "O/" must enter a
             _c_o_m_b_i_n_a_t_i_o_n of keystrokes (this varies among vendors
             but could be <<EExxtteenndd cchhaarr>> <<OO>> <<//>> as an example)
             rather than just one keystroke.  This is very similar
             to the act of using the <<SShhiifftt>> key to access upper
             case letters.

             An ideographic language's input method is often based
             on the language's phonetics but there are also input
             methods based on a common graphics property of certain
             characters.  The latter method involves defining a key
             to map to a common graphic symbol that is the basis for
             multiple characters.  The phonetic method is more
             commonly used.  It requires a phonetic (alphabet-based)
             writing system.  The number of phonetic signs or



        11-4                                             May 9, 1992








                                                Internationalization


             characters is few enough that a unique key is assigned
             to each phoneme. Characters are entered by pressing the
             appropriate phonetic keys.  In several popular input
             methods, the user types a phonetic representation of a
             spoken word and the input method determines which
             characters are pronounced that way.  If only one
             character meets this criterion, it is displayed.  If
             more than one character meets the criterion, a list of
             all characters found is displayed and the user chooses
             the desired one.  It is then passed to the application.
             See the section "Internationalization and Text Input"
             for more information on input methods.



        11.1.3  DDiissppllaayyiinngg OOuuttppuutt


             Displaying the output produced by an application
             intended for international use also requires some
             consideration.  To display text, it must have the
             appropriate content, encoding and fonts.  For example,
             many languages, especially ideographic ones, require
             more than one font.  Bitmaps and pixmaps must be
             localized as well.  An icon that is an appropriate or
             meaningful symbol in one country may be totally
             inappropriate or meaningless in another.



        11.1.4  LLooccaalleess aanndd LLooccaalliizzaattiioonn


             A locale is the language environment determined by the
             application at run time.  XPG3 defines locale as a
             means of specifying three characteristics of a language
             environment that may be needed for localization:
             language, territory, and code set.  Motif supports only
             one locale per application; that is, an application can
             set the locale only once, at start-up time.

             Motif uses the locale to help find:

                +o Resource files.

                +o UID files.

                +o Bitmap files.

                +o Fonts used to display text and labels.




        May 9, 1992                                             11-5








        OSF/Motif Programmer's Guide


                +o Text input method.

             The ANSI C method of setting the locale in an
             application is to use the function sseettllooccaallee.  How
             sseettllooccaallee obtains a language when the language is not
             explicitly referenced in the call to sseettllooccaallee is
             system dependent.  For example, on POSIX systems, the
             environment variable LLAANNGG is used.  The locale name is
             also used to establish a path to the localized files of
             information.  How this is actually accomplished is
             explained in the section "Localizing Applications".



        11.2  CCoommppoouunndd SSttrriinnggss,, FFoonnttss,, aanndd TTeexxtt DDiissppllaayy


             A compound string is a means of encoding text so that
             it can be displayed in many different languages or
             fonts without changing anything in the program. Motif
             uses compound strings to display all text except that
             in the Text and TextField widgets.  This section
             explains the structure of a compound string, the
             interaction with it and a font list, and then focuses
             on those aspects that are important to the
             internationalization process.  This section describes
             the structure of a compound string and the interaction
             between a compound string and a font list that
             determines how the compound string is displayed.



        11.2.1  CCoommppoouunndd SSttrriinngg CCoommppoonneennttss


             A compound string is a byte stream in ASN.1 encoding,
             consisting of tag-length-value segments.  Semantically,
             a compound string has components that contain the text
             to be displayed, a tag (called a font list element tag)
             that will be matched with an element of a font list,
             and an indicator denoting the direction in which it is
             to be displayed.

             A compound string component can be one of four types:

                +o A font list element tag.

                     - The font list element tag
                       XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG indicates that the
                       text is encoded in the codeset of the current
                       locale.



        11-6                                             May 9, 1992








                                                Internationalization


                     - Other font list element tags are used later
                       to match text with particular entries in a
                       font list.

                +o A direction identifier.

                +o The text of the string.  For internationalized
                  applications, the text falls into two broad
                  categories: either the text requires localized
                  treatment or it does not.

                +o Separator.

             The following section describes each of the compound
             string components:

                  Font list element tag The font list element tag is
                                     a string value that correlates
                                     the text component of a
                                     compound string to a font or a
                                     font set in a font list.

                  Direction          The relationship between the
                                     order in which characters are
                                     entered on the keyboard and the
                                     order in which the characters
                                     are displayed on the screen.
                                     For example, the display order
                                     is left to right in English,
                                     French, German, and Italian and
                                     right to left in Hebrew and
                                     Arabic.

                  Text               The text to be displayed.

                  Separator          A separator is a special form
                                     of a compound string component
                                     that has no value.  It is used
                                     to separate other segments.

             Motif uses the specified font list element tag
             identified in the text component to display the
             compound string.  A specified font list element tag is
             used until a new font list element tag is encountered.
             Motif provides a special font list element tag,
             XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG, that matches a font that is
             correct for the current codeset.  It identifies the
             default entry in a font list.  See the section
             "Compound Strings and Font Lists" for more information.





        May 9, 1992                                             11-7








        OSF/Motif Programmer's Guide


             The direction segment of a compound string specifies
             the direction in which the text is displayed.
             Direction can be left-to-right or right-to-left.



        11.2.1.1  CCoommppoouunndd SSttrriinnggss aanndd RReessoouurrcceess


             Compound strings are used to display all text except
             that in the Text and TextField widgets.  The compound
             string is set into the appropriate widget resource so
             that it can be displayed.  For example, the label for
             the PushButton widget is inherited from the Label
             widget, and the resource is XXmmNNllaabbeellSSttrriinngg, which is
             type XXmmSSttrriinngg.  This means that the resource expects a
             value that is a compound string.  A compound string can
             be created programmatically or defined in a resource
             file.



        11.2.1.1.1  SSeettttiinngg aa CCoommppoouunndd SSttrriinngg PPrrooggrraammmmaattiiccaallllyy

             An application can set this resource programmatically
             by creating the compound string using one of the
             compound string convenience functions.  There are
             several such functions:

                  XXmmSSttrriinnggCCrreeaattee                This function
                                                creates a compound
                                                string with text and
                                                a font list element
                                                tag, both of which
                                                are arguments in the
                                                function call.

                  XXmmSSttrriinnggCCrreeaatteeLLooccaalliizzeedd       This function
                                                creates a compound
                                                string in the
                                                encoding of the
                                                current locale and
                                                automatically sets
                                                the font list entry
                                                tag to
                                                XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.

             The following code segment shows one way to set
             XXmmNNllaabbeellSSttrriinngg for a PushButton programmatically:





        11-8                                             May 9, 1992








                                                Internationalization


             Widget    button;
             Args      args[10];
             int       n;
             XmString  button_label;
                     .
                     .
             button_label = XmStringCreateLocalized (locvar, XmFONTLIST_DEFAULT_TAG);
             /* locvar is a variable assumed to contain locale-encoded text. *
             /* Create an argument list for the button */
             n = 0;
             XtSetArg (args[n], XmNlabelString, button_label); n++;

             /* Create and manage the button */
             button = XmCreatePushButton (toplevel, "button", args, n);
             XtManageChild (button);
             XmStringFree (button_label);



        11.2.1.1.2  SSeettttiinngg aa CCoommppoouunndd SSttrriinngg iinn aa DDeeffaauullttss FFiillee

             In an internationalized program, the label string for
             the button label should be obtained from an external
             source.  For example, the button label can come from a
             resource file instead of the program.  For this
             example, assume that the PushButton is a child of a
             Form widget called _f_o_r_m_1.

             *form1.button.labelString:  Push Here

             Here, Motif's string-to-compound-string converter
             produces a compound string from the resource file text.
             This converter always uses XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.



        11.2.1.2  CCoommppoouunndd SSttrriinnggss iinn UUIILL



             Three basic mechanisms exist for specifying strings in
             UIL files:

                +o As string literals, which may be stored in UID
                  files as either NULL-terminated strings or
                  compound strings

                +o As compound strings

                +o As wide-character strings




        May 9, 1992                                             11-9








        OSF/Motif Programmer's Guide


             Both string literals and compound strings consist of
             text, a character set, and a writing direction.  For
             string literals and for compound strings with no
             explicit direction, UIL infers the writing direction
             from the character set.  The UIL concatenation operator
             (&&) concatenates both string literals and compound
             strings.

             Whether UIL stores string literal in UID files as
             NULL-terminated strings or as compound strings, it
             stores information about each string's character set
             and writing direction along with the text.  In general
             UIL stores string literals or string expressions as
             compound strings in UID files under the following
             conditions:

                +o When a string expression consists of two or more
                  literals with different character sets or writing
                  directions

                +o When the literal or expression is used as a value
                  that has a compound string data type (such as the
                  value of a resource whose data type is compound
                  string)

             UIL recognizes a number of keywords specifying
             character sets.  UIL associates parsing rules,
             including parsing direction and whether characters have
             8 or 16 bits, for each character set it recognizes.  It
             is also possible to define a character set using the
             UIL CCHHAARRAACCTTEERR__SSEETT function.

             The syntax of a string literal is one of the following:

                  ''[_c_h_a_r_a_c_t_e_r__s_t_r_i_n_g]''
                  [##_c_h_a_r__s_e_t]""[_c_h_a_r_a_c_t_e_r__s_t_r_i_n_g]""

             For each syntax, the character set of the string is
             determined as follows:

                +o For a string declared as ''_s_t_r_i_n_g'', the character
                  set is the codeset component of the LLAANNGG
                  environment variable if it is set in the UIL
                  compilation environment, or the value of
                  XXmmFFAALLLLBBAACCKK__CCHHAARRSSEETT if LLAANNGG is not set or has no
                  codeset.  By default the value of
                  XXmmFFAALLLLBBAACCKK__CCHHAARRSSEETT is ISO8859-1, but vendors may
                  supply different values.

                +o For a string declared as ##_c_h_a_r__s_e_t""_s_t_r_i_n_g"", the
                  character set is _c_h_a_r__s_e_t.



        11-10                                            May 9, 1992








                                                Internationalization


                +o For a string declared as ""_s_t_r_i_n_g"", the character
                  set depends on whether or not the module has a
                  CCHHAARRAACCTTEERR__SSEETT clause and on whether or not the UIL
                  compiler's uussee__sseettllooccaallee__ffllaagg is set:

                     - If the module has a CCHHAARRAACCTTEERR__SSEETT clause, the
                       character set is the one specified in that
                       clause.

                     - If the module has no CCHHAARRAACCTTEERR__SSEETT clause but
                       the uuiill command was invoked with the --ss
                       option or the UUiill function was invoked with
                       the uussee__sseettllooccaallee__ffllaagg set, UIL calls
                       sseettllooccaallee and parses the string in the
                       current locale.  The character set of the
                       resulting string is XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.

                     - If the module has no CCHHAARRAACCTTEERR__SSEETT clause and
                       the uuiill command was invoked without the --ss
                       option or the UUiill function was invoked
                       without the uussee__sseettllooccaallee__ffllaagg, the character
                       set is the codeset component of the LLAANNGG
                       environment variable if it is set in the UIL
                       compilation environment, or the value of
                       XXmmFFAALLLLBBAACCKK__CCHHAARRSSEETT if LLAANNGG is not set or has
                       no codeset.

             UIL always stores a string specified using the
             CCOOMMPPOOUUNNDD__SSTTRRIINNGG function as a compound string.  This
             function takes as arguments a string expression and
             optional specifications of a character set, direction,
             and whether or not to append a separator to the string.
             If no character set or direction is specified, UIL
             derives it from the string expression, as described
             above.

             Note that certain predefined escape sequences,
             beginning with a backslash, may appear in string
             literals, with these exceptions:

                +o A string in single quotes can span multiple lines,
                  with each newline escaped by a backslash.  A
                  string in double quotes cannot span multiple
                  lines.

                +o Escape sequences are processed literally inside a
                  string that is parsed in the current locale (a
                  localized string).

             For more information on UIL string and compound string
             syntax, see the UUIILL((55XX)) reference page.



        May 9, 1992                                            11-11








        OSF/Motif Programmer's Guide


        11.2.2  FFoonnttss,, FFoonntt LLiissttss,, aanndd FFoonntt SSeettss


             Motif uses font sets and font lists to display text. A
             font defines set of glyphs that represent the
             characters in a given language.  A font set is a group
             of fonts that are needed to display text for a given
             locale.  A font list is a list of fonts, font sets, or
             a combination of the two, that may be used.  Motif has
             convenience functions to create a font list.



        11.2.2.1  FFoonntt LLiisstt SSttrruuccttuurree


             Motif requires a font list for text display.  A font
             list is a list of font structures, font sets, or both,
             each of which has a tag to identify it.  A font set
             ensures that all characters in the current languaage
             can be displayed.  With font structures, the
             responsibility for ensuring that all characters can be
             displayed rests with the programmer.

             Each entry in a font list is in the form of a {tag,
             element} pair, where _e_l_e_m_e_n_t can be either a single
             font or a font set.  The application can create a font
             list entry from either a single font or a font set.
             For example, the following code segment creates a font
             list entry for a font set:

             char font1[] = "-adobe-courier-medium-r-normal--10-100-75-75-M-60";
             font_list_entry = XmFontListEntryLoad (display, font1,
                XmFONT_IS_FONT, "font_tag");

             XXmmFFoonnttLLiissttEEnnttrryyLLooaadd loads a font or creates and loads a
             font set.  There are four arguments to the function:

                  _d_i_s_p_l_a_y   The display on which the font list is to
                            be used

                  _f_o_n_t__n_a_m_e A string that represents either a font
                            name or a base font name list, depending
                            on the _t_y_p_e argument

                  _t_y_p_e      A value that specifies whether _f_o_n_t__n_a_m_e
                            refers to a font name or a base font
                            name list

                  _t_a_g       A string that represents the tag for
                            this font list entry



        11-12                                            May 9, 1992








                                                Internationalization


             If _t_y_p_e is XXmmFFOONNTT__IISS__FFOONNTTSSEETT,, XXmmFFoonnttLLiissttEEnnttrryyLLooaadd
             creates a font set in the current locale from the value
             in _f_o_n_t__n_a_m_e.  The character set(s) of the fonts
             specified in the font set are dependent on the locale.
             If _t_y_p_e is XXmmFFOONNTT__IISS__FFOONNTT,, XXmmFFoonnttLLiissttEEnnttrryyLLooaadd opens
             the font found in _f_o_n_t__n_a_m_e.  In either case, the font
             or font set is placed into a font list entry.

             Now, the following code creates a font list, using the
             _f_o_n_t__l_i_s_t__e_n_t_r_y just created:

             XmFontList font_list;
             XmFontListEntry font_list_entry;
                .
                .
             font_list = XmFontListAppendEntry (NULL, font_list_entry);
             XmFontListEntryFree (font_list_entry);

             The code example above creates a new font list and
             appends the entry _f_o_n_t__l_i_s_t__e_n_t_r_y to it.

             Once a font list has been created,
             XXmmFFoonnttLLiissttEEnnttrryyAAppppeenndd adds a new entry to it.  The
             following example uses XXmmFFoonnttLLiissttEEnnttrryyCCrreeaattee to create
             a new font list entry for an existing font list:

             XFontSet font2;
             char *font_tag;
             XmFontListEntry font_list_entry2;
                .
                .
             font_list_entry2 = XmFontListEntryCreate (font_tag, XmFONT_IS_FONT_SET,
                      (XtPointer)font2);

             _f_o_n_t_2 specifies an XXFFoonnttSSeett returned by XXCCrreeaatteeFFoonnttSSeett.
             The arguments to XXmmFFoonnttLLiissttEEnnttrryyCCrreeaattee are _f_o_n_t__t_a_g,
             XXmmFFOONNTT__IISS__FFOONNTT__SSEETT, and _f_o_n_t_2, which are the tag, type,
             and font, respectively.  The tag and the font set are
             the {tag, element} pair of the font list entry.

             Now, to add this entry to the font list, use
             XXmmFFoonnttLLiissttAAppppeennddEEnnttrryy again, only this time its first
             parameter specifies the existing font list:

             font_list = XmFontListAppendEntry(font_list, font_list_entry2);
             XmFontListEntryFree(font_list_entry2);








        May 9, 1992                                            11-13








        OSF/Motif Programmer's Guide


        11.2.2.2  FFoonntt LLiissttss aanndd RReessoouurrcceess


             The syntax for specifying a font list in a resource
             file depends on whether the list contains fonts, font
             sets, or both.

                +o To obtain a font, specify a font and an optional
                  font list element tag.  If the tag is present, it
                  should be preceded by an equal sign (=).  If the
                  tag is not present, do not use the equal sign.
                  Entries specifying more than one font are
                  separated by commas.

                +o To obtain a font set, specify a base font list and
                  an optional font list element tag.  The tag should
                  be preceded by a colon (:) instead of an equal
                  sign.  If the tag is not present, the colon _m_u_s_t
                  still be present as this is what distinguishes a
                  font from a font set in the resource declaration.
                  Fonts specified in the base font list are
                  separated by semicolons (;).  Entries specifying
                  more than one font set are separated by commas.

             If the font list element tag is not present in either
             case, Motif uses the default XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.
             Here are some examples:

                +o Specifying a font:

                     - Using the default font list element tag:

                       *fontList:  fixed
                       *fontList:\
                         -adobe-courier-medium-r-normal--10-100-75-75-M-60-iso8859-1

                     - Specifying a font list element tag:

                       *fontList:  fixed=ROMAN, 8x13bold=BOLD

                     - Specifying two fonts, one with the default
                       font list element tag and one with an
                       explicit tag:

                       *fontList:  fixed, 8x13bold=BOLD

                +o Specifying a font set:

                     - List the fonts explicitly without specifying
                       a font list element tag:




        11-14                                            May 9, 1992








                                                Internationalization


                       *fontList:  -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240;\
                                   -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120;\
                                   -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240;\
                                   -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150:

                     - Let Xlib select the fonts without specifying
                       a font list element tag:

                       *fontList:  -*-*-*-R-Normal--*-180-100-100-*-*:

                     - List the fonts explicitly and specify a font
                       list element tag as MY_TAG:

                       *fontList:  -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240;\
                                   -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120;\
                                   -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240;\
                                   -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150:MY_TAG

                     - Let Xlib select the fonts and specify a font
                       list element tag as MY_TAG:

                       *fontList:  -*-*-*-R-Normal--*-180-100-100-*-*:MY_TAG

                     - List the fonts explicitly and specify a font
                       list element tag for bold fonts but use the
                       default font list element tag for medium
                       fonts:

                       *fontList:  -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240;\
                                   -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120;\
                                   -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240;\
                                   -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150:,\
                                   -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240;\
                                   -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120;\
                                   -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240;\
                                   -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150:BOLD

                     - Let Xlib select the fonts and specify a font
                       list element tag for bold fonts and use the
                       default font list element tag for the others:

                       *fontList:  -*-*-*-R-Normal--*-180-100-100-*-*:,\
                                   -*-*-Bold-R-Normal--*-180-100-100-*-*:BOLD











        May 9, 1992                                            11-15








        OSF/Motif Programmer's Guide


        11.2.2.3  FFoonntt LLiisstt RReessoouurrccee DDeeffaauullttss


             A font list resource exists for a number of different
             widgets.  Motif uses a hierarchy system to determine
             the font list it should use.  There are several font
             list resources for VVeennddoorrSShheellll, XXmmBBuulllleettiinnBBooaarrdd, and
             XXmmMMeennuuSShheellll.  These resources can be set, either
             programmatically or in resource files.  VVeennddoorrSShheellll and
             XXmmMMeennuuSShheellll have some common font list resources but
             one of them, XXmmNNddeeffaauullttFFoonnttLLiisstt, exists only for
             compatibility with earlier Motif releases.  The widgets
             that have a font list resource (or resources) are
             listed in the following table.  Note that in some cases
             the resource is _n_o_t named XXmmNNffoonnttLLiisstt.
               TTAABBLLEE 1111--22..  Widgets With A Font List Resource

                          WWiiddggeett          RReessoouurrccee NNaammee
                      ____________________________________
                      VVeennddoorrSShheellll       XXmmNNddeeffaauullttFFoonnttLLiisstt
                      VVeennddoorrSShheellll       XXmmNNbbuuttttoonnFFoonnttLLiisstt
                      VVeennddoorrSShheellll       XXmmNNllaabbeellFFoonnttLLiisstt
                      VVeennddoorrSShheellll       XXmmNNtteexxttFFoonnttLLiisstt
                      XXmmMMeennuuSShheellll       XXmmNNbbuuttttoonnFFoonnttLLiisstt
                      XXmmMMeennuuSShheellll       XXmmNNddeeffaauullttFFoonnttLLiisstt
                      XXmmMMeennuuSShheellll       XXmmNNllaabbeellFFoonnttLLiisstt
                      XXmmLLaabbeell           XXmmNNffoonnttLLiisstt
                      XXmmLLaabbeellGGaaddggeett     XXmmNNffoonnttLLiisstt
                      XXmmLLiisstt            XXmmNNffoonnttLLiisstt
                      XXmmSSccaallee           XXmmNNffoonnttLLiisstt
                      XXmmTTeexxtt            XXmmNNffoonnttLLiisstt
                      XXmmTTeexxttFFiieelldd       XXmmNNffoonnttLLiisstt
                      XXmmBBuulllleettiinnBBooaarrdd   XXmmNNbbuuttttoonnFFoonnttLLiisstt
                      XXmmBBuulllleettiinnBBooaarrdd   XXmmNNllaabbeellFFoonnttLLiisstt
                      XXmmBBuulllleettiinnBBooaarrdd   XXmmNNtteexxttFFoonnttLLiisstt

             The three resources XXmmNNbbuuttttoonnFFoonnttLLiisstt,
             XXmmNNllaabbeellFFoonnttLLiisstt, and XXmmNNtteexxttFFoonnttLLiisstt are used to
             specify a font list for descendants of a type
             associated with the resource.  For example,
             XXmmNNbbuuttttoonnFFoonnttLLiisstt specifies the font list used for
             button descendants of VVeennddoorrSShheellll, XXmmBBuulllleettiinnBBooaarrdd, and
             XXmmMMeennuuSShheellll.  If a button's XXmmNNffoonnttLLiisstt is NULL at
             initialization, the font list for the button is set by
             searching the parent hierarchy of the button widget or
             gadget for an ancestor that is a subclass of
             VVeennddoorrSShheellll, XXmmBBuulllleettiinnBBooaarrdd, or XXmmMMeennuuSShheellll.  If such
             an ancestor is found, the button's font list is set to
             the value of XXmmNNbbuuttttoonnFFoonnttLLiisstt in the ancestor widget.
             If no such ancestor is found, the result is
             implementation dependent.



        11-16                                            May 9, 1992








                                                Internationalization


        11.2.2.4  FFoonntt LLiissttss iinn UUIILL



             UIL has three functions for use in creating font lists:
             FFOONNTT, FFOONNTTSSEETT, and FFOONNTT__TTAABBLLEE.  FFOONNTT and FFOONNTTSSEETT create
             font list entries.  FFOONNTT__TTAABBLLEE creates a font list from
             these font list entries.

             The FFOONNTT function creates a font list entry containing
             a font specification.  The argument is a string
             representing an XLFD font name.  The FFOONNTTSSEETT function
             creates a font list entry containing a font set
             specification.  The argument is a comma-separated list
             of XLFD font names representing a base name font list.

             Both FFOONNTT and FFOONNTTSSEETT have optional CCHHAARRAACCTTEERR__SSEETT
             parameters that specify the font list element tag for
             the font list entry.  In both cases, if no
             CCHHAARRAACCTTEERR__SSEETT parameter is specified, UIL determines
             the font list element tag as follows:

                +o If the module contains no CCHHAARRAACCTTEERR__SSEETT
                  declaration and if the uuiill command was invoked
                  with the --ss option or the UUiill function was invoked
                  with the uussee__sseettllooccaallee__ffllaagg set, the font list
                  element tag is XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.

                +o Otherwise, the font list element tag is the
                  codeset component of the LLAANNGG environment variable
                  if it is set in the UIL compilation environment,
                  or the value of XXmmFFAALLLLBBAACCKK__CCHHAARRSSEETT if LLAANNGG is not
                  set or has no codeset.

             The FFOONNTT__TTAABBLLEE function creates a font list from a
             comma-separated list of font list entries, created by
             FFOONNTT or FFOONNTTSSEETT.  The resulting font list can be used
             as the value of a font list resource.  If a single font
             list entry is supplied as the value for such a
             resource, UIL converts the entry to a font list.



        11.2.3  CCoommppoouunndd SSttrriinnggss aanndd FFoonntt LLiissttss


             When Motif displays a compound string, it associates
             each segment with a font or font set by means of the
             font list element tag for that segment.  The
             application must have loaded the desired font or font
             set, created a font list that contains that font or



        May 9, 1992                                            11-17








        OSF/Motif Programmer's Guide


             font set and its associated font list element tag, and
             created the compound string segment with the same tag.

             Motif follows a set search procedure when when it binds
             a compound string to a font list entry:

               1.  Motif searches the font list for an exact match
                   with the font list element tag specified in the
                   compound string.  If it finds a match, the
                   compound string is bound to that font list entry.

               2.  If the above does not provide a binding between
                   the compound string and the font list, Motif
                   binds the compound string to the first element in
                   the font list, regardless of its font list
                   element tag.

             For backward compatibility, if an exact match is not
             found, XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG in either a compound
             string or a font list matches the tag that would result
             from creating a compound string or font list entry with
             a tag of XXmmSSTTRRIINNGG__DDEEFFAAUULLTT__CCHHAARRSSEETT.

             The next figure shows the relationships between a
             compound string, a font set, and a font list when the
             font list element tag is set to something other than
             XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.
          FFiigguurree 1111--22..  Compound String Relationships With Explicit
                        Tag











             The next example shows how to use a tag we'll call
             _t_a_g_b.

             XFontStruct     *font1;
             XmFontListEntry font_list_entry;
             XmFontList font_list;
             XmString  label_text;
             char *tagb;  /* Font list element tag */
             char *fontx; /* Initialize to XLFD or font alias */
             char *button_label;   /* Contains button label text */
                     .



        11-18                                            May 9, 1992








                                                Internationalization


                     .
             font1 = XLoadQueryFont (XtDisplay(toplevel), fontx);
             font_list_entry = XmFontListEntryCreate (tagb, XmFONT_IS_FONT,
                     (XtPointer)font1);
             font_list = XmFontListAppendEntry (NULL, font_list_entry);
             XmFontListEntryFree (font_list_entry);

             label_text = XmStringCreate (button_label, tagb);

             XXLLooaaddQQuueerryyFFoonntt loads the font and then
             XXmmFFoonnttLLiissttEEnnttrryyCCrreeaattee creates a font list entry.  The
             application must create an entry and then append it to
             an existing font list or create a new font list.  In
             either case, use XXmmFFoonnttLLiissttAAppppeennddEEnnttrryy.  Since there is
             no font list in place, the code example above has NULL
             for the font list argument.  XXmmFFoonnttLLiissttAAppppeennddEEnnttrryy
             creates a new font list called _f_o_n_t__l_i_s_t with a single
             entry, _f_o_n_t__l_i_s_t__e_n_t_r_y.  To add another entry to
             _f_o_n_t__l_i_s_t, follow the same procedure but supply a non-
             NULL font list argument.

             The following figure shows the relationships between a
             compound string, a font set, and a font list when the
             font list element tag is set to XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.
             In this case the value field is locale text.
          FFiigguurree 1111--33..  Compound String Relationships With
                        XmFONTLIST_DEFAULT_TAG
















             The previous figure shows how a compound string is
             related to a font list and a font set when the font
             list element tag is XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.  Here, the
             default tag points to FFoonntt__SSeett__AA, which in turn
             identifies the fonts needed to display the characters
             in the language.





        May 9, 1992                                            11-19








        OSF/Motif Programmer's Guide


        11.2.4  TTeexxtt aanndd TTeexxttFFiieelldd WWiiddggeettss aanndd FFoonntt LLiissttss


             The Text and TextField widgets display text
             information.  To do so, they must be able to select the
             correct font in which to display the information.  The
             Text and TextField widgets follow a set search pattern
             to find the correct font.

               1.  Search the font list for an entry that is a font
                   set and has a font list element tag of
                   XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.  If a match is found, use
                   that font list entry.  No further searching
                   occurs.

               2.  Search the font list for an entry that specifies
                   a font set.  Use the first one found.

               3.  If no font set is found, use the first font in
                   the font list.

             A font set is desired because that insures that there
             are glyphs for every character in the locale.



        11.3  LLooccaalliizziinngg AApppplliiccaattiioonnss


             An internationalized application can be tailored to
             operate in many areas of the world, each with its own
             requirements for the language and customs to be used.
             This section explains some methods for localizing an
             application.



        11.3.1  TTeecchhnniiqquueess ffoorr LLooccaalliizzaattiioonn


             Although there are different methods to localize an
             application, there are some common considerations:

                +o The application should not explicitly code any
                  language-dependent information in the application.
                  This includes strings, fonts and language-
                  dependent pixmaps.

                +o The application should isolate text, fonts, and
                  pixmaps, and translate them into the languages
                  needed.  Usually this information is stored in



        11-20                                            May 9, 1992








                                                Internationalization


                  separate directories by language.

             This section describes how the user, the application
             developer, and the implementation combine to establish
             the language environment of the application.  It then
             discusses two general approaches to localizing
             applications.  Succeeding sections focus on four
             aspects of localizing information in Motif programs:

                +o Resource files

                +o UID files

                +o Message catalogs

                +o X bitmap files

             Many aspects of localization depend on the particular
             operating system, Motif implementation, and user
             environment in which the application runs.  The
             following must all cooperate for correct localization
             to occur:

                +o The operating system's locale mechanism, if any

                +o The Motif implementation

                +o The application itself

                +o The user's system administrator

                +o The user's language environment



        11.3.1.1  EEssttaabblliisshhiinngg tthhee LLaanngguuaaggee EEnnvviirroonnmmeenntt


             The term language environment refers to the set of
             localized data that the application needs in order to
             run correctly in the user specified locale.  A language
             environment supplies the rules associated with a
             specific language.  In addition, the language
             environment consists of any externally stored data,
             such as localized strings or text used by the
             application.  For example, the menu items displayed by
             an application might be stored in separate files for
             each language supported by the application.  This type
             of data can be stored in resource files, UID files, or,
             on XPG3-compliant systems, message catalogs.




        May 9, 1992                                            11-21








        OSF/Motif Programmer's Guide


             A single language environment is established when an
             application executes.  The actual language environment
             in which an application operates is specified by the
             application user, often either by setting an
             environment variable (LLAANNGG on POSIX-based systems) or
             by setting the xxnnllLLaanngguuaaggee resource.  The application
             then sets the language environment based on the user's
             specification.  The application can do this either by
             using sseettllooccaallee in a language procedure established by
             XXttSSeettLLaanngguuaaggeePPrroocc, or by using a method that does not
             call sseettllooccaallee.  In either case, Xt caches a per-
             display language string that is used by
             XXttRReessoollvveePPaatthhnnaammee to find resource, bitmap, and UIL
             files.

             An application that supplies a language procedure may
             either provide its own or use an Xt default procedure.
             In either case, the application establishes the
             language procedure by calling XXttSSeettLLaanngguuaaggeePPrroocc before
             calling XXttAAppppIInniittiiaalliizzee.  When a language procedure is
             installed, Xt calls it in the process of constructing
             the initial resource database.  Xt uses the value
             returned by the language procedure as its per-display
             language string.

             The default language procedure performs the following
             tasks:

                +o Sets the locale.  On ANSI C-based systems, this is
                  done by using this code:

                  setlocale(LC_ALL, _l_a_n_g_u_a_g_e);

                  where _l_a_n_g_u_a_g_e is the value of xxnnllLLaanngguuaaggee or the
                  empty string ("") if xxnnllLLaanngguuaaggee is not set.  When
                  xxnnllLLaanngguuaaggee is not set, the locale is generally
                  derived from an environment variable (LLAANNGG on
                  POSIX-based systems).

                +o Calls XXSSuuppppoorrttssLLooccaallee to verify that the locale
                  just set is supported.  If not, a warning message
                  is issued and the locale is set to "C."

                +o Calls XXSSeettLLooccaalleeMMooddiiffiieerrss specifying the empty
                  string.

                +o Returns the value of the current locale.  On ANSI
                  C-based systems, this is the result of calling:

                  setlocale(LC_ALL, NULL);




        11-22                                            May 9, 1992








                                                Internationalization


             The application can use the default language procedure
             by making the call to XXttSSeettLLaanngguuaaggeePPrroocc in this manner:

             XtSetLanguageProc(NULL, NULL, NULL);
                .
                .
             toplevel = XtAppinitialize(...);

             By default Xt does not install any language procedure.
             If the application does not call XXttSSeettLLaanngguuaaggeePPrroocc, Xt
             uses as its per-display language string the value of
             the xxnnllLLaanngguuaaggee resource if it is set.  If xxnnllLLaanngguuaaggee
             is not set, Xt derives the language string from the
             environment.  On POSIX-based systems, this is the value
             of the LLAANNGG environment variable.

             It is important to note that the per-display language
             string that results from this process is implementation
             dependent and that Xt provides no public means of
             examining the language string once it is established.
             The following vary by operating system and by Motif
             implementation:

                +o The mechanism, if any, used to set the locale

                +o On ANSI C-based systems, the value returned by
                  sseettllooccaallee

                +o The possible values of any environment variables
                  used to establish the language environment

                +o Whether or not xxnnllLLaanngguuaaggee is used and, if so, its
                  possible values

             Furthermore, by supplying its own language procedure,
             an application may use any procedure it wants for
             setting the language string.



        11.3.1.2  UUssiinngg LLooccaalleess


             The locale provides local information to an application
             based on the user's language, territory, and codeset.
             Both language and territory are needed because some
             languages are spoken in more than one country and more
             than one language may be spoken in some countries
             (Belgium, Canada, and Switzerland are examples).





        May 9, 1992                                            11-23








        OSF/Motif Programmer's Guide


             Information in resource, UID, and image files can be
             localized and stored in separate directories by
             language.  The Xt function XXttRReessoollvveePPaatthhnnaammee uses the
             run-time locale to determine the proper directory to
             use.

             On XPG3-compliant systems, an application can use
             message catalogs to localize text and messages.  A
             message catalog file exists for each language, and each
             is usually stored in a separate directory by language.

             The locale method of localizing compound strings and
             font lists consists of the following steps:

               1.  Establish a language procedure before calling
                   XXttAAppppIInniittiiaalliizzee.  The language procedure calls
                   sseettllooccaallee.

               2.  Localize the compound strings and font lists
                   using resource files, message catalogs, or UID
                   files.  Normally, do not specify any font list
                   element tags other than XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.

               3.  Use font sets in resource or UID file font lists.

               4.  Use XXmmSSttrriinnggCCrreeaatteeLLooccaalliizzeedd to create compound
                   strings in the program.  This function only has
                   one argument, a text string, and automatically
                   sets the font list element tag to
                   XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.

             The run-time locale determines which fonts are used to
             display text.  This is accomplished in the following
             manner:

                +o Motif calls XXttRReessoollvveePPaatthhnnaammee to load resource or
                  UID files that specify the names of fonts for font
                  sets.  XXttRReessoollvveePPaatthhnnaammee uses a file search path
                  that may vary depending on the display's language
                  string.

                +o XXCCrreeaatteeFFoonnttSSeett uses the locale to determine the
                  fonts to be used from the base font name and the
                  locale charset.

             In this method the application usually does not specify
             font list element tags other than
             XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.  It is possible to supply
             explicit font list element tags with locale-dependent
             text.  For example, text might be displayed using large
             and small fonts or bold and italic fonts.  The



        11-24                                            May 9, 1992








                                                Internationalization


             application can do this with special tags in both the
             compound string and the font list associated with it.
             In the font list, match the tag with a font set
             specification that supplies the desired attribute
             (point size, for example).  When the application
             creates the font set, the charset comes from the
             locale.  For example, a resource file might specify a
             font list in the following manner to obtain fonts with
             a different point size:

             *fontList:  -*-*-*-R-Normal--*-120-100-100-*-*:,\
                         -*-*-*-R-Normal--*-180-100-100-*-*:BIG,\
                         -*-*-*-R-Normal--*-80-100-100-*-*:SMALL

             In this case the application should also map the tags
             to XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG in the Motif registry of font
             list element tags.  See the section "Compound Strings
             and Compound Text" for more information.



        11.3.1.3  LLooccaalliizzaattiioonn wwiitthhoouutt LLooccaalleess



             In this method, the locale is not set in the program,
             and a language procedure is not needed.  Instead, the
             user specifies the language environment using either
             xxnnllLLaanngguuaaggee or an environment variable such as LLAANNGG.
             As when the application uses locales, resource, UID,
             and image files are localized and stored in separate
             directories by language.  XXttRReessoollvveePPaatthhnnaammee uses the
             display's language string in the same way to determine
             the proper locations of these files.

             Message catalogs are not used in this method.  Also, in
             this case Text and TextField cannot accommodate 16-bit
             data.

             The non-locale method of localizing compound strings
             and font lists consists of these steps:

               1.  Localize compound strings using UIL files.  Note
                   that resource files cannot be used for compound
                   strings because the string-to-compound-string
                   converter always uses XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG
                   Localized font lists can appear in resource
                   files.

               2.  Specify explicit font list element tags _o_t_h_e_r
                   than XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG in both compound



        May 9, 1992                                            11-25








        OSF/Motif Programmer's Guide


                   strings and font lists.

               3.  Use font names with explicit charset components
                   in resource or UIL files.  Do not use font sets.

               4.  To create compound strings in the program, use
                   XXmmSSttrriinnggCCrreeaattee with the font list element tag set
                   to something other than XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.



        11.3.2  RReessoouurrcceess aanndd LLooccaalliizzaattiioonn


             The resources used in an application that are subject
             to internationalization are stored in files external to
             the application.  These resources include

                +o All labels, particularly those that identify
                  controls.  Such labels are defined as type
                  XXmmSSttrriinngg, meaning they are compound strings.

                +o Text strings, that is strings of text that are not
                  compound strings.

                +o Font lists.



        11.3.2.1  IInniittiiaall RReessoouurrccee DDaattaabbaassee


             The information in the external resource files is used
             when Xt builds the initial resource database.  The
             XXttDDiissppllaayyIInniittaalliizzee function loads the resource database
             by merging in resources from these sources, in order of
             precedence (that is, each component takes precedence
             over the following components):

                +o The application command line

                +o Per-host user environment resource file on the
                  local host

                +o Screen-specific resources for the default screen
                  of the display

                +o Resource property on the server or user preference
                  resource file on the local host





        11-26                                            May 9, 1992








                                                Internationalization


                +o Application-specific user resource file on the
                  local host

                +o Application-specific class resource file on the
                  local host

             Localization applies to two components of the initial
             resource database:  the application-specific user and
             class resources.  Localized resources that are
             controlled by the programmer are in the application
             class resource file, and localized resources that are
             controlled by the user are in the user resource file.
             Note that the user resources take precedence over the
             application class resources.



        11.3.2.2  RReessoouurrccee FFiillee LLooccaattiioonnss



             XXttDDiissppllaayyIInniittiiaalliizzee calls XXttRReessoollvveePPaatthhnnaammee to load
             both the user and the class resources.

             To load the user's application resource file,
             XXttDDiissppllaayyIInniittiiaalliizzee uses the value of the
             XXUUSSEERRFFIILLEESSEEAARRCCHHPPAATTHH environment variable as the search
             path.  If that variable is not set or if the search
             path fails to find the file, and if the environment
             variable XXAAPPPPLLRREESSDDIIRR is defined, XXttDDiissppllaayyIInniittiiaalliizzee
             next tries an implementation-dependent search path with
             a number of entries that include XXAAPPPPLLRREESSDDIIRR and the
             user's home directory.  If XXAAPPPPLLRREESSDDIIRR is not set or if
             that search path fails, XXttDDiissppllaayyIInniittiiaalliizzee tries
             another implementation-dependent search path with a
             number of entries that include the user's home
             directory.

             To load the application-specific class resource file,
             XXttDDiissppllaayyIInniittiiaalliizzee uses the value of the
             XXFFIILLEESSEEAARRCCHHPPAATTHH environment variable as the search
             path.  If that variable is not set or if the search
             path fails to find the file, XXttDDiissppllaayyIInniittiiaalliizzee tries
             an implementation-dependent search path.

             The search paths for both files may contain any
             substitutions recognized by XXttRReessoollvveePPaatthhnnaammee.  That
             routine substitutes the display's language string for
             %L.  In an implementation-dependent manner, it
             substitutes the language, territory, and codeset
             components of the language string for %l, %t, and %c,



        May 9, 1992                                            11-27








        OSF/Motif Programmer's Guide


             respectively.  This mechanism allows Xt to load
             different resource files for different languages, as
             specified by the display's language string.

             The display's language string is determined by the
             application's language procedure, if present, or else
             by the value of the xxnnllLLaanngguuaaggee resource or by the
             environment.  The language string associated with any
             particular language and the search paths used to find
             the resource files depend on the system vendor, the
             Motif vendor, the application, and the user's system
             administrator.  Determining the actual directories in
             which localized resource files reside requires
             coordination among all these sources.

             In general, an application developer prepares a set of
             localized application class resource files, one for
             each language the application supports.  The developer
             may also need to supply a language procedure
             appropriate for one or more of the systems on which the
             application will run.  The application vendor must
             arrange for the resource files to be installed in the
             correct directories, depending on the operating system
             and the Motif implementation on which the application
             will run.



        11.3.2.3  AAnn EExxaammppllee



             Following is an example of an application class
             defaults file for a simple program that creates a
             MainWindow with a Text widget.  The font list
             specification includes a single font set with a default
             tag.  This resource file would be appropriate for an
             application that uses locales.

             *fontList:                      -*-*-*-R-Normal--*-180-100-100-*-*:
             *Text1.value:                   Hier ist etwas Text fur das Text Widget.\n
              Gemischter 8-und 16-bit Text.
             *version_box.messageString:     Dies ist i18n Demo Version
             *version_box.okLabelString:     Schliessen
             *version_box.dialogTitle:       I18n Demo Version
             *pgm_ver_btn.labelString:       I18n Demo Version
             *events_btn.labelString:        Aktionen
             *help_btn_menu.labelString:     Hilfe
             *help_btn_cascade.labelString:  Hilfe
             *help_box.messageString:        Leider ist keine Hilfe hier.
             *help_box.okLabelString:        Schliessen



        11-28                                            May 9, 1992








                                                Internationalization


             *help_box.dialogTitle:          i18n Demo Hilfe
             *stop_btn.labelString:          Enden



        11.3.3  UUIILL aanndd LLooccaalliizzaattiioonn



             The general models for localizing applications using
             UIL are the same as those for applications that do not
             use UIL.  An application developer creates separate UIL
             files, each containing string and resource values for a
             particular language.  UIL files can also be used in
             conjuction with localized resource and pixmap files.
             As with localization of resource files, there are two
             basic approaches to localizing UIL files: one that uses
             locales and one that does not.



        11.3.3.1  PPrreeppaarriinngg LLooccaalliizzeedd UUIIDD FFiilleess



             When using locales with UIL, an application developer
             should take the following steps:

                +o Do not use a CCHHAARRAACCTTEERR__SSEETT declaration for the
                  module.

                +o When creating compound strings in a UIL file, use
                  double quotes and no character set specification
                  for the text.

                +o When creating font lists in a UIL file, use font
                  sets, not fonts.  Do not specify character sets
                  for the font sets.

                +o Before compiling a UIL file using the uuiill command,
                  set up any environment variables (such as LLAANNGG) or
                  other mechanisms the system vendor recommends to
                  establish the locale that is appropriate for the
                  UIL file to be compiled.  Invoke the uuiill command
                  with the --ss option.  This enables the UIL compiler
                  to set the locale and parse double quoted strings
                  without explicit character sets in the locale's
                  encoding.  It also ensures that localized compound
                  strings and font list entries are created with
                  font list element tags of XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG.




        May 9, 1992                                            11-29








        OSF/Motif Programmer's Guide


                +o Before using the UUiill function to compile a UIL
                  file, set the locale that is appropriate for the
                  UIL file to be compiled.  In the UUiill__ccoommmmaanndd__ttyyppee
                  structure that is the first argument to the UUiill
                  function, set the uussee__sseettllooccaallee__ffllaagg member to 1.
                  This has the same effect as invoking the uuiill
                  command with the --ss option.

             When localizing UIL files without using locales, an
             application developer should take the following steps:

                +o When using single quotes for the text of compound
                  strings, supply a CCHHAARRAACCTTEERR__SSEETT declaration for
                  the module.

                +o When using double quotes for the text of compound
                  strings, supply an explicit character set for each
                  segment.

                +o When creating font lists in a UIL file, use fonts,
                  not font sets.  Specify an explicit character set
                  for each font.

                +o When compiling a UIL file using the uuiill command,
                  do not invoke the command with the --ss option.  The
                  UIL compiler does not set the locale, and it
                  parses each string using rules derived from the
                  explicitly specified character set for that
                  string.

                +o When compiling a UIL file using the UUiill function,
                  set the uussee__sseettllooccaallee__ffllaagg member of the
                  UUiill__ccoommmmaanndd__ttyyppee structure to 0.  This has the
                  same effect as invoking the uuiill command without
                  the --ss option.

             The UIL compiler processes a single source file for
             each invocation of the uuiill command or the UUiill function.
             However, UIL has an IINNCCLLUUDDEE FFIILLEE directive that is
             similar to the C preprocessor's ##iinncclluuddee directive.  If
             the file argument for this directive is not an absolute
             pathname, the compiler searches for the file in a
             series of directories.  These include the directory of
             the main UIL source file and any directories specified
             via the --II option to the uuiill command or the iinncclluuddee__ddiirr
             member of the UUiill__ccoommmmaanndd__ttyyppee structure for the UUiill
             function.

             One strategy for maintaining localized UIL source files
             is to place only language-independent information in
             the main UIL source file and to put all language-



        11-30                                            May 9, 1992








                                                Internationalization


             dependent information in included files that are in
             separate directories for each language.  Then a
             developer can compile the UIL files for different
             languages without editing any UIL files.  When using
             locales, set up the environment for the intended
             locale.  Whether using locales or not, then invoke the
             UIL compiler with the proper include directory for the
             intended language.

             In general, a developer can mix localized UIL files
             with localized resource files.  For example, the
             developer might specify compound strings in UIL files
             and font lists in resource files.  Note one exception:
             it is not practical to use resource files to localize
             compound strings without using locales.  This is
             because no resource file syntax exists for supplying an
             explicit font list element tag for a compound string.

             For resource values that the user may override, the
             developer must use resource files or fallback resources
             or must in some way ensure that the user's resource
             settings can override the developer's settings from the
             UIL file.



        11.3.3.2  MMRRMM aanndd LLooccaalliizzeedd UUIIDD FFiilleess



             Once the developer has generated localized UID files,
             the vendor and the user's system administrator must
             arrange for these files to be installed in the
             appropriate directories for the system where the
             program is to run.  As with resource files, these
             directories depend on configurations established by the
             operating system vendor, the Motif vendor, and the
             system administrator.

             MMrrmmOOppeennHHiieerraarrcchhyyPPeerrDDiissppllaayy takes as an argument a list
             of names of UID files.  It calls XXttRReessoollvveePPaatthhnnaammee to
             find each file the list.  If a file name is an absolute
             pathname, that pathname is the search path for
             XXttRReessoollvveePPaatthhnnaammee.  Otherwise,
             MMrrmmOOppeennHHiieerraarrcchhyyPPeerrDDiissppllaayy constructs a search path in
             the following way:

                +o If the environment variable UUIIDDPPAATTHH is set, the
                  value of that variable is the search path





        May 9, 1992                                            11-31








        OSF/Motif Programmer's Guide


                +o If UUIIDDPPAATTHH is not set but XXAAPPPPLLRREESSDDIIRR is set,
                  MMrrmmOOppeennHHiieerraarrcchhyyPPeerrDDiissppllaayy uses a default search
                  path with entries that include $$XXAAPPPPLLRREESSDDIIRR, the
                  user's home directory, and vendor-dependent system
                  directories

                +o If neither UUIIDDPPAATTHH nor XXAAPPPPLLRREESSDDIIRR is set,
                  MMrrmmOOppeennHHiieerraarrcchhyyPPeerrDDiissppllaayy uses a default search
                  path with entries that include the user's home
                  directory and vendor-dependent system directories

             These paths may include the substitution field %U.  In
             each call to XXttRReessoollvveePPaatthhnnaammee,
             MMrrmmOOppeennHHiieerraarrcchhyyPPeerrDDiissppllaayy substitutes the current file
             name from the list of UID files for %U.  The paths may
             also include other substitution fields accepted by
             XXttRReessoollvveePPaatthhnnaammee.  In particular, XXttRReessoollvveePPaatthhnnaammee
             substitutes the display's language string for %L, and
             it substitutes the components of the display's language
             string (in a vendor-dependent way) for %l, %t, and %c.
             If necessary MMrrmmOOppeennHHiieerraarrcchhyyPPeerrDDiissppllaayy searches the
             path twice, first with %S mapped to ..uuiidd and then with
             %S mapped to NULL.  The substitution field %T is always
             mapped to uuiidd.

             The usual mechanism for employing localized UID files
             is to use a search path that contains one of the
             substitutions derived from the display's language
             string.  As with resource files, the vendor and system
             administrator must ensure that the directories where
             the localized UID files reside match the display's
             language string (or the appropriate component of the
             language string).



        11.3.4  MMeessssaaggee CCaattaallooggss aanndd LLooccaalliizzaattiioonn



             On an XPG3-compliant system, an application can use
             message catalogs to localize text.  The format of
             message catalogs is implementation dependent, and the
             application must take steps to coordinate the locations
             of the message catalogs with the locations of resource,
             UID, and image files.  Use of message catalogs requires
             these steps:

                +o Using an implementation-dependent method, prepare
                  a separate message catalog containing text to be
                  localized for each language.



        11-32                                            May 9, 1992








                                                Internationalization


                +o Arrange to have the message catalogs installed in
                  the appropriate directories on the systems on
                  which the application will run.

                +o Arrange for the user's environment to be set up
                  correctly so that the application can read the
                  message catalog appropriate to the language.

                +o In the program, use the ccaattooppeenn function to open a
                  message catalog and the ccaattcclloossee function to close
                  it.

                +o Use the ccaattggeettss function to read text from an open
                  message catalog.

                +o If necessary, convert the text to the target
                  format (such as a compound string) and, for
                  resources, supply the text in the appropriate
                  widget creation argument list or call to
                  XXttSSeettVVaalluueess.

             The ccaattooppeenn function takes as an argument the name of
             the message catalog file.  If this is an absolute
             pathname, ccaattooppeenn opens that file.  Otherwise, ccaattooppeenn
             uses the value of the NNLLSSPPAATTHH environment variable as a
             search path.  This path can contain a number of
             substitution fields.  The file name passed to ccaattooppeenn
             is substituted for %N.  The value of the LLAANNGG
             environment variable is substituted for %L, and its
             language, territory, and codeset components are
             substituted for %l, %t, and %c, respectively.

             Note that these values may not be the same as the
             display's language string or its components.  An
             application and software vendor that use message
             catalogs must coordinate the locations of message
             catalogs with those of localized resource, UID, and
             image files, which usually depend on the display's
             language string.  One possible strategy is to call
             ccaattooppeenn with an absolute pathname constructed by
             calling XXttRReessoollvveePPaatthhnnaammee with the value of NNLLSSPPAATTHH as
             the search path argument.  XXttRReessoollvveePPaatthhnnaammee
             substitutes the display's language string and its
             components for %L, %l, %t, and %c in $$NNLLSSPPAATTHH.  In this
             way the application can use a single mechanism, the
             display's language string, to distinguish file
             locations by language.  The software vendor must still
             arrange for the user's system administrator to install
             the message catalogs in the correct locations and to
             ensure that NNLLSSPPAATTHH is appropriately set in the user's
             environment.



        May 9, 1992                                            11-33








        OSF/Motif Programmer's Guide


        11.3.5  IImmaaggeess,, PPiixxmmaappss,, aanndd LLooccaalliizzaattiioonn


             A pixmap is a screen image that is stored in memory so
             that it can be recalled and displayed when needed.
             Motif has a number of pixmap resources that allow the
             application to supply pixmaps for backgrounds, borders,
             shadows, label and button faces, drag icons, and other
             uses.  As with text, some pixmaps may be specific to
             particular language environments; these pixmaps need to
             be localized.

             Motif maintains caches of pixmaps and images.  The
             function XXmmGGeettPPiixxmmaappBByyDDeepptthh searches these caches for a
             requested pixmap.  If the requested pixmap is not in
             the pixmap cache and a corresponding image is not in
             the image cache, XXmmGGeettPPiixxmmaappBByyDDeepptthh searches for an X
             bitmap file whose name matches the requested image
             name.  XXmmGGeettPPiixxmmaappBByyDDeepptthh calls XXttRReessoollvveePPaatthhnnaammee to
             search for the file.  If the requested image name is an
             absolute pathname, that pathname is the search path for
             XXttRReessoollvveePPaatthhnnaammee.  Otherwise, XXmmGGeettPPiixxmmaappBByyDDeepptthh
             constructs a search path in the following way:

                +o If the environment variable XXBBMMLLAANNGGPPAATTHH is set,
                  the value of that variable is the search path

                +o If XXBBMMLLAANNGGPPAATTHH is not set but XXAAPPPPLLRREESSDDIIRR is set,
                  XXmmGGeettPPiixxmmaappBByyDDeepptthh uses a default search path with
                  entries that include $$XXAAPPPPLLRREESSDDIIRR, the user's home
                  directory, and vendor-dependent system directories

                +o If neither XXBBMMLLAANNGGPPAATTHH nor XXAAPPPPLLRREESSDDIIRR is set,
                  XXmmGGeettPPiixxmmaappBByyDDeepptthh uses a default search path with
                  entries that include the user's home directory and
                  vendor-dependent system directories

             These paths may include the substitution field %B.  In
             each call to XXttRReessoollvveePPaatthhnnaammee, XXmmGGeettPPiixxmmaappBByyDDeepptthh
             substitutes the requested image name for %B.  The paths
             may also include other substitution fields accepted by
             XXttRReessoollvveePPaatthhnnaammee.  In particular, XXttRReessoollvveePPaatthhnnaammee
             substitutes the display's language string for %L, and
             it substitutes the components of the display's language
             string (in a vendor-dependent way) for %l, %t, and %c.
             The substitution field %T is always mapped to bbiittmmaappss,
             and %S is always mapped to NULL.

             As with resource and UID files, the usual mechanism for
             employing localized X bitmap files is to use a search
             path that contains one of the substitutions derived



        11-34                                            May 9, 1992








                                                Internationalization


             from the display's language string.  As with resource
             and UID files, the vendor and system administrator must
             ensure that the directories where the localized X
             bitmap files reside match the display's language string
             (or the appropriate component of the language string).

             See chapter 12 for more information on images and
             pixmaps.



        11.3.6  CCoommppaarriinngg AApppprrooaacchheess ttoo LLooccaalliizzaattiioonn


             The locale approach allows an application to use
             existing internationalization routines.  On the other
             hand, the application is limited in portability to
             systems that support the same internationalization
             standards (XPG3, POSIX, or ANSI).  This approach is
             also only applicable to applications using a single
             language.

             The non-locale approach only addresses the aspect of
             isolating information from the application and insuring
             that it uses the proper localized version of this
             information.  The disadvantage is that there is more
             work for the programmer and there may be non-standard
             functionality.  The advantages are that there is
             guaranteed portability across all platforms that
             support Motif, and that it allows handling of multiple
             character sets for specialized applications that
             require this functionality.



        11.4  AAddvvaanncceedd TTooppiiccss iinn IInntteerrnnaattiioonnaalliizzaattiioonn


             This section covers some advanced topics dealing with
             internationalization.



        11.4.1  IInntteerrnnaattiioonnaalliizzaattiioonn aanndd TTeexxtt IInnppuutt


             An application subject to internationalization presents
             some unique problems when it deals with text input.
             The application must be able to correctly interpret and
             process text input in any language.  This section
             explains how an application accomplishes this.



        May 9, 1992                                            11-35








        OSF/Motif Programmer's Guide


        11.4.1.1  IInnppuutt MMeetthhoodd


             Although there are many different keyboards in use,
             sometimes certain characters in an alphabetic language
             are not directly available on any keyboard.  In this
             case, the user must type a combination of keys to input
             the desired character.  The number of characters in an
             ideographic language far exceeds the capability of any
             keyboard and makes it impossible to have a keyboard
             with all of the language's symbols.  In this case,
             input is usually accomplished based on the language's
             phonetics.  These cases illustrate the concept of an
             input method.  An input method is simply the mechanism
             that is used to map between the keys typed by a user
             and the resulting characters that are input to the
             application.  A common feature of many input methods is
             that the application user may type combinations of keys
             to create a single character.  Creating characters from
             keystrokes is called pprree--eeddiittiinngg.

             Input methods may require several areas to display the
             actual keystrokes.

                +o The SSttaattuuss AArreeaa is an output-only window that
                  identifies the style of input (phonetic, numeric,
                  stroke and radial, etc.) and the current status of
                  an input method interaction.

                +o The PPrree--EEddiitt AArreeaa displays the intermediate text
                  for languages that are composed before the
                  application acts on the data. There are several
                  possible locations for the pre-edit area.  These
                  are:

                     - OOvveerr--tthhee--ssppoott displays the data in an input
                       method window that is placed over the point
                       of insertion.

                     - OOffff--tthhee--ssppoott displays the pre-edit window
                       inside the application window (usually at the
                       bottom) but not at the point of insertion.

                     - RRoooott--wwiinnddooww uses a pre-edit window that is a
                       child of the root window.

                  A VendorShell resource, XXmmNNpprreeeeddiittTTyyppee determines
                  which style is used for a Text or TextField input
                  method.  The syntax, possible values, and default
                  value of this resource are implementation
                  dependent.



        11-36                                            May 9, 1992








                                                Internationalization


                +o The AAuuxxiilliiaarryy AArreeaa is used for popup menus and
                  customizing dialogs that some input methods use.

             Input methods are supplied by vendors and are
             implementation dependent.  The VendorShell resource
             XXmmNNiinnppuuttMMeetthhoodd is an implementation-dependent string
             that specifies the input method portion of the locale
             modifiers.  If a value is supplied for this resource,
             Motif uses it to set the locale modifiers before
             opening an input method for Text or TextField.

             The following figure shows one possible program window
             with a Text widget using over-the-spot interaction for
             Japanese text input.  The status area indicates that
             phonetic input is in use and insert mode is enabled.
             The pre-edit area shows that the letter "H" has been
             entered.  Since there is no Hiragana phonetic
             equivalent, the "H" appears in the pre-edit window.
          FFiigguurree 1111--44..  Text Widget Pre-Edit and Status Areas Using
                        over-the-spot

















             The following figure shows the same window after a "u"
             has been entered following the "H" shown in the
             previous figure.














        May 9, 1992                                            11-37








        OSF/Motif Programmer's Guide


          FFiigguurree 1111--55..  Text Widget Pre-Edit Area After Next Character
                        Entry

















             Here the pre-edit area is displaying the phonetic
             equivalent of the English letters "hu" in Hiragana.



        11.4.1.2  IInnppuutt CCoonntteexxtt


             An iinnppuutt ccoonntteexxtt is the mechanism used to provide the
             state information needed to manage the information flow
             between the application and the input method.  It is a
             combination of an input method, a locale specifying the
             encoding of character strings to be returned, an
             application window, and internal state information.
             The following figure shows the relationships involved.
             The input method is determined by the locale specified
             by the application user.


















        11-38                                            May 9, 1992








                                                Internationalization


                 FFiigguurree 1111--66..  Input Method and Input Contexts


















        11.4.1.3  IInnppuutt aanndd tthhee MMoottiiff TTeexxtt wwiiddggeett


             The Motif Text and TextField widgets, when editable,
             provide a transparent connection to the locale-specific
             input method for text input.  The application
             programmer specifies an appropriate font set in the
             Text or TextField XXmmNNffoonnttLLiisstt resource and creates
             either widget as a descendant of VVeennddoorrSShheellll.
             VendorShell provides geometry management of the status
             and pre-edit areas.  It also supplies a visual
             separator between the status area window and the
             application's top level window.

             Setting the VVeennddoorrSShheellll resource XXmmNNpprreeeeddiittTTyyppee
             dictates the location of the input method window.  With
             an off-the-spot input method, the pre-edit and status
             area windows appear at the bottom of the application
             window.



        11.4.1.4  TTeexxtt IInnppuutt UUssiinngg aa DDrraawwiinnggAArreeaa



             An application that needs special text processing may
             use a DrawingArea for text input and output.  For
             internationalized text input with any widget other than
             Text or TextField, the application must use the Xlib
             input method facilities.  These allow the application
             to open an input method and input context and to obtain



        May 9, 1992                                            11-39








        OSF/Motif Programmer's Guide


             input from the input method.  When using these
             facilities, an application may also need to handle
             input method geometry management, focus management,
             event filtering, and other issues.  For more
             information, see _X_l_i_b-_C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e.



        11.4.1.5  GGeeoommeettrryy MMaannaaggeemmeenntt ooff PPrree--eeddiitt aanndd SSttaattuuss AArreeaass


             When using an off-the-spot input method with the Text
             or TextField widget, the pre-edit and status areas are
             below the client's main window but inside the
             VendorShell.  VendorShell accomplishes the necessary
             geometry management.  If the application uses either
             XXttGGeettVVaalluueess or XXttSSeettVVaalluueess to get or set the height
             (XXmmNNhheeiigghhtt) of VVeennddoorrSShheellll, the height includes the
             height of the input method area.

             The following figure shows a Text widget using an off-
             the-spot input method.  The distance "h" is the
             additional height that the input manager needs to
             display the status and pre-edit areas.  Note that in
             off-the-spot, the pre-edit area is at the bottom of the
             interaction.
          FFiigguurree 1111--77..  Text Widget Pre-Edit and Status Areas Using
                        off-the-spot


























        11-40                                            May 9, 1992








                                                Internationalization


        11.4.2  CCoommppoouunndd SSttrriinnggss aanndd CCoommppoouunndd TTeexxtt


             Compound text is the standard format for exchanging
             textual data between X window system applications.
             This is necessary when the user moves text displayed in
             one codeset to another window with text in a different
             codeset.  For example, the following figure shows two
             windows, one titled "UJIS" and the other titled "Shift
             JIS."
                     FFiigguurree 1111--88..  Reason for Compound Text




















             Both windows represent a Motif Text widget, one with
             some Japanese UJIS characters displayed, and the other
             with some Shift JIS characters.  If the user wants to
             cut text from one window and paste it in the other
             window, compound text is used to pass data between the
             two.  The Motif Text widget does this automatically.

             If one of the widgets in the previous figure is a Label
             widget instead of a Text widget, a different situation
             exists.  This is because the Label widget has its text
             data in compound string format, while the text widget
             data is a simple character string.  In order to pass
             text data between a Text or TextField widget and any
             other widget, the application needs to convert the
             compound string to compound text.

             Motif has two functions, XXmmCCvvttXXmmSSttrriinnggTTooCCTT and
             XXmmCCvvttCCTTTTooXXmmSSttrriinngg, for converting between compound
             strings and compound text.




        May 9, 1992                                            11-41








        OSF/Motif Programmer's Guide


             XXmmCCvvttXXmmSSttrriinnggTTooCCTT converts a compound string to
             compound text.  The converter uses the font list tag
             associated with a given compound string segment to
             select a compound text format for that segment.  A
             registry defines a mapping between font list tags and
             compound text encoding formats.  The converter uses the
             following algorithm for each compound string segment:

               1.  If the compound string segment tag is mapped to
                   XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG in the registry, the
                   converter passes the text of the compound string
                   segment to XXmmbbTTeexxttLLiissttTTooTTeexxttPPrrooppeerrttyy with an
                   encoding style of XXCCoommppoouunnddTTeexxttSSttyyllee and uses the
                   resulting compound text for that segment.

               2.  If the compound string segment tag is mapped to
                   an MIT registered charset in the registry, the
                   converter creates the compound text for that
                   segment using the charset (from the registry) and
                   the text of the compound string segment as
                   defined in the X Consortium Standard _C_o_m_p_o_u_n_d
                   _T_e_x_t _E_n_c_o_d_i_n_g.

               3.  If the compound string segment tag is mapped to a
                   charset in the registry that is neither
                   XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG nor an MIT registered
                   charset, the converter creates the compound text
                   for that segment using the charset (from the
                   registry) and the text of the compound string
                   segment as an "extended segment" with a variable
                   number of octets per character.

               4.  If the compound string segment tag is not mapped
                   in the registry, the result is implementation
                   dependent.

             An application can use XXmmRReeggiisstteerrSSeeggmmeennttEEnnccooddiinngg to map
             a font list element tag to a compound text encoding
             format.  For example, the application may be using a
             font list element tag of "BOLD" to identify a compound
             text segment consisting of localized text to be
             displayed in a bold font.  To ensure that the segment
             is treated as localized text when converted to compound
             text, the tag "BOLD" should be mapped to
             XXmmFFOONNTTLLIISSTT__DDEEFFAAUULLTT__TTAAGG as follows:

             char *old_encoding = XmRegisterSegmentEncoding("BOLD",
                 XmFONTLIST_DEFAULT_TAG);
             XtFree(old_encoding);





        11-42                                            May 9, 1992








                                                Internationalization


             XXmmCCvvttCCTTTTooXXmmSSttrriinngg converts compound text to a compound
             string.  This function is implementation dependent.

             See chapter 16 for more information on transferring
             data between applications.  The compound text format is
             described in the X Consortium Standard _C_o_m_p_o_u_n_d _T_e_x_t
             _E_n_c_o_d_i_n_g.















































        May 9, 1992                                            11-43






 g
