--- a/localisation/localesupport/doc/loce32.html Mon Oct 19 15:55:17 2009 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,364 +0,0 @@
-<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
-<!--
- Copyright (c) 1999-2009 Nokia Corporation and/or its subsidiary(-ies).
- All rights reserved.
- This component and the accompanying materials are made available
- under the terms of the License "Eclipse Public License v1.0"
- which accompanies this distribution, and is available
- at the URL "http://www.eclipse.org/legal/epl-v10.html".
-
- Initial Contributors:
- Nokia Corporation - initial contribution.
-
- Contributors:
-
- Description:
-
--->
-
-
-
-<HTML>
- <HEAD>
- <TITLE>LOCE32 notes</TITLE>
- </HEAD>
-
- <BODY>
-
- <H1 ALIGN = CENTER>LOCE32 notes</H1>
-
- Notes about the LOCE32 localisation framework for low-level EPOC
- components.
-
- <H2><A NAME="contents">Contents</A></H2>
-
- <UL>
- <LI><A HREF="#overview">Overview</A></LI>
- <LI><A HREF="#structure">Structure of the LOCE32 component</A></LI>
- <LI><A HREF="#adding">Adding a new locale</A></LI>
- <LI><A HREF="#building">Building LOCE32</A></LI>
- <LI><A HREF="#creating">Creating a LOCE32 for a new EPOC platform</A></LI>
- </UL>
-
- <H2><A NAME="overview">Overview</A></H2>
-
- <P>
- Localisation DLLs conform to an interface defined by <CODE>E32</CODE> and they provide
- support for localisation for components that are too low-level to
- participate in the normal EPOC localisation mechanisms. LOCE32
- provides several implementations of this interface.
- </P>
-
- <H2><A NAME="structure" HREF="#contents">Structure of the LOCE32 component</A></H2>
-
- <H3>Directory structure</H3>
-
- <DL>
- <DT><CODE>\LOCE32</CODE></DT>
- <DD>Contains an overall "Bldmake" project file.</DD>
- <DT><CODE>\LOCE32\DOC</CODE></DT>
- <DD>Contains this file.</DD>
- <DT><CODE>\LOCE32\MMPFILES</CODE></DT>
- <DD>Contains "Makmake" project files for each locale.</DD>
- <DT><CODE>\LOCE32\SRC</CODE></DT>
- <DD>Contains the source code for building the localisation DLLs.</DD>
- </DL>
-
- <H3>Source files</H3>
-
- <P>
- Localisation DLLs are built from variants of the following source files
- in the \LOCE32\SRC directory:
- <DL>
- <DT><CODE>LS_CY<VAR>xx</VAR>.CPP</CODE></DT>
- <DD>Contains default locale settings like distance units, currency symbol, date and time formats,
- etc. (also some code to vary the behaviour of F32's FAT file system).</DD>
- <DT><CODE>LS_LN<VAR>yyy</VAR>.CPP</CODE></DT>
- <DD>Contains things like day names, month names, etc.</DD>
- <DT><CODE>LS_MS<VAR>yyy</VAR>.CPP</CODE></DT>
- <DD>Contains messages that base software may need to issue without the
- benefit of access to compiled resources.</DD>
- <DT><CODE>LS_LAT1.CPP, LS_TABLE.CPP, LS_UNIC.CPP</CODE></DT>
- <DD>Contain standard Latin1, Unicode character encoding and the Collation data for the locale.</DD>
- </DL>
- </P>
- <P>
- Where <VAR>xx</VAR> is a two-letter locale identifier and <VAR>yyy</VAR>
- is a three-letter language identifier.
- </P>
-
- <H3>Build files</H3>
-
- <P>
- Like most EPOC components, LOCE32's build is controlled by two EPOC
- tools, "Makmake" and "Bldmake":
- </P>
-
- <H4>Makmake project files</H4>
-
- <P>
- Each Makmake file describes one locale-specific version of the
- localisation DLL. Makmake files are named:
- <BLOCKQUOTE>ELOCL<VAR>xx</VAR>.MMP</BLOCKQUOTE>
- </P>
- <P>
- Where by convention <VAR>xx</VAR> is a the same two-letter locale
- identifier mentioned above.
- </P>
-
- <H4>Bldmake project file</H4>
-
- <P>
- The Bldmake file <CODE>BLD.INF</CODE> contains a list of names of
- Makmake project files. Bldmake will only build localisation DLLs that
- are described by Makmake project files that are listed in this file.
- </P>
-
- <H3><A NAME="binaries">Binaries</A></H3>
-
- <P>
- LOCE32 builds a number of locale-specific versions of the localisation
- DLL. These DLLs are given filenames of the following form:
- <BLOCKQUOTE><CODE>\epoc32\release\<VAR>platform</VAR>\<VAR>build</VAR>\ELOCL.<VAR>nn</VAR></CODE></BLOCKQUOTE>
- Where <VAR>platform</VAR> is either ARMI, ARM4 or WINS, <VAR>build</VAR> is
- either UDEB or UREL and <VAR>nn</VAR> is a numeric locale
- identifier. Note that THUMB binaries are not built because the code in
- localisation DLLs is run inside the kernel (which is never THUMB). Note also that the
- code in localisation DLLs is also run outside the kernel. Localisation DLLs
- are in this respect the same as <CODE>E32</CODE>'s <CODE>EUSER.DLL</CODE>
- (i.e. in that they are run from both inside and outside the kernel).
- Therefore the localisation-DLL platform to use should match the platform of
- <CODE>EUSER.DLL</CODE> used in the ROM. (This is ARMI for a THUMB or ARMI ROM,
- and ARM4 for an ARM4 ROM.)
- </P>
-
- <H2><A NAME="adding" HREF="#contents">Adding a new locale</A></H2>
-
- <P>
- LOCE32 is supplied with source for a number of locales. Further locales
- may be added by copying and modifying the source for an existing locale
- and by modifying the Makmake and Bldmake files.
- </P>
-
- <H3>Choosing identifiers</H3>
-
- <P>
- Before you start adding a locale you will first need to discover and
- choose appropriate identifiers for the source files and for the filename
- of the resulting localisation DLL.
- </P>
- <P>
- Find the symbolic name for the locale in the file
- <CODE>\epoc32\include\e32std.h</CODE>. The locales supported by EPOC may
- be found inside the <CODE>TLanguage</CODE> list at around line 200 of
- that file. Eg the symbolic name for the American locale is
- <CODE>ELangAmerican</CODE>.
- </P>
- <P>
- Determine the numeric identifier for the locale. The numeric identifier
- is found from the position of the locale in the <CODE>TLanguage</CODE>
- list when couting from zero, eg <CODE>ELangTest</CODE> is the zeroth
- locale and <CODE>ELangAmerican</CODE> is the tenth locale so the numeric
- identifier for American is 10.
- </P>
- <P>
- Choose a new two-letter identifier for the new locale, eg "US" for
- America. If the new locale uses a language not already supplied with
- LOCE32 then also choose a new three-letter language identifier, eg "ENG"
- for English.
- </P>
- <P>
- In summary, you need the following information which will be referred to
- below:
- </P>
- <CENTER><TABLE BORDER=1>
- <TR><TH>Info</TH><TH>Description</TH><TH>Example</TH></TR>
- <TR><TD>LOCALE</TD><TD>The new
- locale</TD><TD><CODE>America</CODE></TD></TR>
- <TR><TD>NAME</TD><TD>Symbolic locale
- name</TD><TD><CODE>ELangAmerican</CODE></TD></TR>
- <TR><TD>NN</TD><TD>Numeric locale
- identifier</TD><TD>10</TD></TR>
- <TR><TD>XX</TD><TD>Two-letter locale identifier</TD><TD>US</TD></TR>
- <TR><TD>YYY</TD><TD>Three-letter language identifier</TD><TD>ENG</TD></TR>
- <TR><TD>0xUUUUUUUU</TD><TD>The UID</TD><TD>0x1000659a</TD></TR>
- </TABLE></CENTER>
-
- <H3>Source files</H3>
-
- <P>
- The source files reside in the <CODE>\LOCE32\SRC</CODE> directory:
- </P>
-
- <H4>Locale settings file</H4>
-
- <P>
- If possible identify an existing locale settings file
- (<CODE>LS_CY*.CPP</CODE>) that is for a locale broadly similar to the
- new locale. Otherwise start with <CODE>LS_CYUK.CPP</CODE> for the UK
- locale. Copy your chosen existing locale settings file to
- <CODE>LS_CY<VAR>xx</VAR>.CPP</CODE>.
- </P>
- <P>
- Modify the new copy of the locale settings file for the new
- locale. The first source code line of the locale settings file should
- use the symbolic locale name obtained from <CODE>e32std.h</CODE>:
-
- <BLOCKQUOTE><CODE>const TLanguage LCountry::Language =
- <VAR>NAME</VAR>;</CODE></BLOCKQUOTE>
- </P>
- <P>
- Note: <CODE>LCountry::CountryCode</CODE> in this file is a redundant
- value that remains for backwards compatibility but is no longer used and
- need not be edited.
- </P>
-
- <H4>Language and message files</H4>
-
- <P>
- If the new locale uses a language not already supplied with LOCE32 then
- copy the English language file <CODE>LS_LNENG.CPP</CODE> and message
- file <CODE>LS_MSENG.CPP</CODE> to <CODE>LS_LN<VAR>yyy</VAR>.CPP</CODE>
- and <CODE>LS_MS<VAR>yyy</VAR>.CPP</CODE> respectively. Replace the
- quoted English text in your copies of these files with translations.
- </P>
-
- <H4>Collation rules and tables</H4>
-
- <P>
- EPOC follows the Unicode Collation algorithm.This system allows almost any kind of collation behaviour to be expressed.
- The collation data are stored in tables.The Collation Method consists of two sets of tables. The first set provides the standard keys,
- the optional second set tailors them for a particular locale.See the definition of TCollationMethod in <code>\e32\include\collate.h</code>:
- </P>
-
- <P>
- The standard rules, which form the base from which the tailoring or tailorings for a given locale differ,
- are encoded as constant static data in <code>\e32\euser\unicode\collate.cpp.</code> The locale-specific rules
- for the default locale are kept in <code>\loce32\src\ls_unic.cpp.</code> Locale-specific rules for other locales are
- kept in other files of the form \loce32\src\ls_unic_<var>yyy</var>.cpp, where <var>yyy</var> is the language name or
- locale code to be decided upon. For example see the collation method for the Japanese locale in: <code>\loce32\src\ls_unic_template_japanese.cpp </code>
- </P>
-
- <P>
- The standard rules might not be sufficient for locales that uses exotic character sets, for example Japanese,
- Arabic, etc. They might have collation rules that are specific to their language. Internationalisation provides a
- tool <var>Coltab</var> that allows the user to create the locale specific tailored collation table.
- To get a better understanding of <var>Coltab</var> read:
-
- <code>//Londata04/Internationalisation/V6/COLTAB.doc</code>
-
- </P>
-
- <H3>Build files</H3>
-
- <P>
- The build files reside in the <CODE>\LOCE32</CODE> directory:
- </P>
-
- <H4>Makmake project file</H4>
-
- <P>
- Copy the Makmake project file for the UK locale <CODE>ELOCLUK.MMP</CODE>
- to <CODE>ELOCL<VAR>xx</VAR>.MMP</CODE> and replace the text
- <B><VAR>marked</VAR></B> below:
- </P>
-
-<PRE>
-// ELOCL<B><VAR>xx</VAR></B>.MMP
-//
-// Copyright (c) 1997-1999 Symbian Ltd. All rights reserved.
-//
-
-//
-// Localisation DLL for <B><VAR>LOCALE</VAR></B>
-//
-
-TARGET elocl.<B><VAR>NN</VAR></B>
-
-TARGETTYPE dll
-
-SOURCEPATH ..\src
-SOURCE ls_cy<B><VAR>xx</VAR></B>.cpp ls_ln<B><VAR>yyy</VAR></B>.cpp ls_ms<B><VAR>yyy</VAR></B>.cpp
-SOURCE ls_lat1.cpp ls_table.cpp ls_unic.cpp
-
-SYSTEMINCLUDE \epoc32\include \epoc32\include\kernel
-
-#if defined(WINS)
-DEFFILE \epoc32\release\wins\elocl.def
-#elif defined(MARM)
-DEFFILE \epoc32\release\marm\elocl.def
-#else
-error
-#endif
-
-LIBRARY euser.lib
-
-START WINS
-BASEADDRESS 0x58000000
-END
-
-UID 0x100039e6 <B><VAR>0xUUUUUUUU</VAR></B>
-</PRE>
-
- <H4>Bldmake project files</H4>
-
- <P>
- Add the name of the new Makmake project file without the .MMP extension
- (ie <CODE>ELOCL<VAR>xx</VAR></CODE>) to the Bldmake project file
- <CODE>BLD.INF</CODE>.
- </P>
-
- <H2><A NAME="building" HREF="#contents">Building LOCE32</A></H2>
-
- <P>
- Building LOCE32 requires a full OAK to be installed. LOCE32 uses the
- standard EPOC build tools (documented elsewhere). In short to build
- all the localisation DLLs change directory to
- <CODE>\LOCE32</CODE> and type:
- <OL>
- <LI><CODE>bldmake bldfiles</CODE></LI>
- <LI><CODE>abld build</CODE> or
- <CODE>abld build <VAR>platform</VAR> <VAR>build</VAR></CODE></LI>
- </OL>
-
- Where <VAR>platform</VAR> is either ARMI, ARM4 or WINS and <VAR>build</VAR> is
- either UDEB or UREL. Note that the THUMB platform are not built
- for the reason outlined <A HREF="#binaries">above</A>.
- </P>
-
- <H2><A NAME="creating" HREF="#contents">Creating a LOCE32 for a new EPOC platform</A></H2>
-
- <P>
- The following source files in <CODE>\LOCE32\SRC</CODE>:
- <UL>
- <LI><CODE>LS_LAT1.CPP</CODE></LI>
- <LI><CODE>LS_TABLE.CPP</CODE></LI>
- <LI><CODE>LS_UNIC.CPP</CODE></LI>
- </UL>
- are direct copies of the corresponding files in the E32 component. When
- modifying LOCE32 for a new EPOC platform these files must be copied from
- the E32 component.
- </P>
-
- <P>
- The locale settings, language and message source files in
- <CODE>\LOCE32\SRC</CODE> are localised copies of the following files in
- the E32 component:
- <UL>
- <LI><CODE>LS_CYUK.CPP</CODE></LI>
- <LI><CODE>LS_LENG.CPP</CODE></LI>
- <LI><CODE>LS_MSG.CPP</CODE></LI>
- </UL>
- When modifying LOCE32 for a new EPOC platform the locale settings,
- language and message source files must be synced with the corresponding
- source files in the E32 component.
- </P>
-
- <P>
- A small point to note. With the Elocl DLLs there is a DLL name <code>ELOCL.LOC</code>.
- This is used as a default locale if the Window Server cannot find the locale DLL that it tries to get from the Hal. Since in WINS Hal returns nothing, <code>ELOCL.LOC</code> is the default locale. To change a locale in WINS, rename the required locale DLL as <code> ELOCL.LOC</code>.
- </P>
- <HR>
-
- </BODY>
-</HTML>