localisation/localesupport/doc/loce32.html
changeset 0 a41df078684a
--- /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>