--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/localisation/localesupport/doc/loce32.html Mon Oct 19 15:55:17 2009 +0100
@@ -0,0 +1,364 @@
+<!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>