--- a/Symbian3/SDK/Source/GUID-141633B8-A3D4-5BBB-97C5-3D928746ECE7.dita Fri Jul 16 17:23:46 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,303 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- Copyright (c) 2007-2010 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:
--->
-<!DOCTYPE concept
- PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
-<concept id="GUID-141633B8-A3D4-5BBB-97C5-3D928746ECE7" xml:lang="en"><title>Resource
-localisable strings</title><prolog><metadata><keywords/></metadata></prolog><conbody>
-<p>Resource localisable strings (RLS) are defined in the resource files. Each
-RLS item definition is a new-line separated entry in the resource file, using
-literals to define a localisable string, number or character. </p>
-<p><b>Defining RLS items </b> </p>
-<p>The following literals can be used to define an RLS item: </p>
-<table id="GUID-F30AE1BF-B383-5A66-99C1-AD2110C41368">
-<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
-<thead>
-<row>
-<entry>Name</entry>
-<entry>Description</entry>
-</row>
-</thead>
-<tbody>
-<row>
-<entry><p> <i>rls_string</i> </p> </entry>
-<entry><p>Use this literal to define a 16-bit Unicode string </p> </entry>
-</row>
-<row>
-<entry><p> <i>rls_string8</i> </p> </entry>
-<entry><p>Use this literal to define an 8-bit Unicode string </p> </entry>
-</row>
-<row>
-<entry><p> <i>rls_byte</i> </p> </entry>
-<entry><p>Use this literal to define an 8-bit number </p> </entry>
-</row>
-<row>
-<entry><p> <i>rls_word</i> </p> </entry>
-<entry><p>Use this literal to define a 16-bit number </p> </entry>
-</row>
-<row>
-<entry><p> <i>rls_long</i> </p> </entry>
-<entry><p>Use this literal to define a long number </p> </entry>
-</row>
-<row>
-<entry><p> <i>rls_double</i> </p> </entry>
-<entry><p>Use this literal to define a decimal number </p> </entry>
-</row>
-</tbody>
-</tgroup>
-</table>
-<p><b>BNF description </b> </p>
-<p><i><codeph><rls-file></codeph></i>
-</p>
-<p><b>rls-file ::=</b>
- </p>
-<p><i><codeph><rls-entry>* <rls-entry></codeph></i>
-</p>
-<p><b>rls-entry ::=</b>
- </p>
-<p> <i><codeph><rls-item> <rls-item></codeph></i>
-</p>
-<p><b>rls-item ::=</b>
- </p>
-<p><i><codeph><type>[<length> <cardinality>] <symbolic-identifier>
-<value> <type></codeph></i>
-</p>
-<p><b>type ::=</b>
- </p>
-<p><b><codeph> rls_string | rls_string8 | rls_byte | rls_word | rls_long |
-rls_double</codeph></b> <i><codeph><value></codeph></i>
-</p>
-<p><b>value ::=</b>
- </p>
-<p> <i><codeph><text> | <number></codeph></i></p>
-<p>where, </p>
-<table id="GUID-1B30B956-E495-5EE7-B5FA-33A336712087">
-<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
-<tbody>
-<row>
-<entry><p> <varname>length</varname> </p> </entry>
-<entry><p>The optional maximum length of the <codeph>text</codeph> applicable
-to <codeph>rls_string</codeph> or <codeph>rls_string8</codeph> types only </p> </entry>
-</row>
-<row>
-<entry><p> <varname>cardinality</varname> </p> </entry>
-<entry><p>You can use the optional keyword qualifier "multi", which indicates
-that the localisable item may be used by more than one resource </p> </entry>
-</row>
-<row>
-<entry><p> <varname>symbolic-identifier</varname> </p> </entry>
-<entry><p>A unique ID for the localisable string or number </p> </entry>
-</row>
-<row>
-<entry><p> <varname>text</varname> </p> </entry>
-<entry><p>This is a string expression, which may include a string enclosed
-in double quotes (") and a character code enclosed in angle brackets (<>) </p> </entry>
-</row>
-<row>
-<entry><p> <varname>number</varname> </p> </entry>
-<entry><p>A numeric value for the literals <codeph>rls_byte</codeph>, <codeph>rls_word</codeph>, <codeph>rls_long</codeph> and <codeph>rls_double</codeph> </p> </entry>
-</row>
-</tbody>
-</tgroup>
-</table>
-<p>The following example shows how to define an RLS string and number: </p>
-<codeblock id="GUID-2B139C40-7B9C-502B-A709-ABEC93D3200E" xml:space="preserve">rls_string<32> STRING_1 "Example menu item"<0x2026>
-rls_byte multi NUMBER_1 17
-</codeblock>
-<p>Characters are declared using the RLS type identifiers <codeph>rls_byte</codeph>, <codeph>rls_word</codeph> or <codeph>rls_long</codeph>.
-The type identifier to be used depends on the type of the structure member
-they will be included into. However, the value can be declared within single
-quotes. For example: </p>
-<codeblock id="GUID-A6595588-C05D-5883-B2A7-A7645270F657" xml:space="preserve">
- rls_long hotkey_zoomin 'M'</codeblock>
-<p><b>Commenting RLS items </b> </p>
-<p>RLS items can be tagged with appropriate comments, which are placed just
-before each RLS item declaration. Optionally, if a <codeph>RESOURCE</codeph> declaration
-contains localisable data, a comment can precede the <codeph>RESOURCE</codeph> declaration. </p>
-<p>These comments save time and cost in localisation, and improve quality
-of localised text. If you supply more context information to the translators
-(maximum string length allowed, the details of the GUI in which their text
-will be displayed), the quality of the localised text is better. This will
-also reduce the need for re-translating the text. </p>
-<p>The localisation comments must be enclosed within the comment brackets
-/*&...*/. These comment brackets include a set of tags to provide more
-details about the RLS item. </p>
-<p>The resource compiler (<codeph>epocrc</codeph>) can warn if comments are
-missing. A Symbian platform licensee can configure the <codeph>epocrc</codeph> tool
-to emit warnings for missing comments through the <xref href="GUID-5FFBC0B0-FC6E-5D60-868B-064DBEB632E0.dita#GUID-5FFBC0B0-FC6E-5D60-868B-064DBEB632E0/GUID-014671B6-C19E-528A-984C-D8226375AC5A">epocrc configuration file</xref>. </p>
-<p>The following is a list of tags used within the comment brackets: </p>
-<ul>
-<li id="GUID-23B9063B-ED0F-538C-AAB2-6AAE1E2993E5"><p> <codeph>@localize</codeph>:
-This is an optional tag used to specify whether to allow the translator to
-change the string or not. The translator is allowed to change the RLS item,
-only if the tag is set to '<codeph>yes</codeph>'. To disallow any change to
-the RLS item, set it to '<codeph>no</codeph>'. By default, the translator
-is allowed to change an RLS item, if the corresponding localisation comment
-does not include this tag. </p> <p>For example: </p> <codeblock id="GUID-1FCD24E2-7F1A-59DA-BF72-6612D9ABF22A" xml:space="preserve">/*&
-@localize yes
-*/
-rls_string STRING_1 "Device locked"
-</codeblock> </li>
-<li id="GUID-C674C795-950D-5432-8908-89F20F85A891"><p> <codeph>@description</codeph>:
-This is mandatory tag used to provide a description about the RLS item. This
-tag is used to provide the following information to the translator: </p> <ul>
-<li id="GUID-D0519085-B8A6-5658-A7F5-D2891B033B89"><p>The context in which
-the string is used and the purpose of the dialog or views using the string. </p> </li>
-<li id="GUID-9591133E-65C3-5D7B-9B72-DE1D1B790FEE"><p>Its relationships with
-other strings. </p> </li>
-<li id="GUID-E8405E4E-A0AC-53B9-A6B5-630B276B7B7E"><p>If the localisable strings
-represent file names or URIs that must point to existing objects, describe
-those objects briefly. </p> </li>
-<li id="GUID-11F95E12-CECE-5311-8800-673FF4B3C059"><p>If the RLS items are
-tagged with <codeph>@restriction other</codeph>, describe the restriction. </p> </li>
-</ul> </li>
-<li id="GUID-A84221B4-5327-551A-8F92-ECC5B8D13F33"><p> <codeph>@restriction</codeph>:
-This is an optional tag used to specify the scope of the RLS item. The possible
-values for this tag are: </p> <ul>
-<li id="GUID-4C0C8F25-F6D0-550C-9A31-B96B483AD408"><p> <codeph>uri</codeph> to
-specify that the localisable item is an URI. If the URI changes, the resulting
-URI should be a valid URI pointing to the correct object. The description
-in the comment bracket can be used to give more details about the URI. </p> </li>
-<li id="GUID-F5FEC94D-DA1C-509E-A0BD-E35260F399E6"><p> <codeph>file</codeph> to
-specify that the localisable item is a file name. If the file changes, the
-ROM must be rebuilt to accommodate the change. If the full path of the file
-is not given, the description for the localisable item can be used to provide
-more details. </p> </li>
-<li id="GUID-1115504D-14E8-5997-9FF8-F79EC650943A"><p> <codeph>trademark</codeph> to
-specify that the localisable item is a trademark. The trademark differs from
-country to country, but any change to it must be subject to trademark owner's
-rules. The description for the localisable item can be used to provide more
-details. </p> </li>
-<li id="GUID-FF6ABAD0-2BC3-5445-842A-282CBEC7DBFE"><p> <codeph>other</codeph> to
-specify that the localisable item is none of the above. In such a case, the
-description should include the effects of changing the localisable item and
-the constraints. </p> </li>
-</ul> <p>For example: </p> <codeblock id="GUID-BD4F8548-23BD-5945-882E-54ABE0AF4468" xml:space="preserve">/*& @description Must point to the happy bugle wave file, used as a ring tone and displayed to the user in the ring-tone selection dialog.
-@localize yes
-@restriction file
-*/
-rls_string STRING_2 "happy bugle.wav"
-</codeblock> </li>
-<li id="GUID-E2630A48-BC17-51FD-B6F0-EA425DD64318"><p> <codeph>@uicontext</codeph>:
-This is a mandatory tag for RLS items defined using <codeph>rls_string</codeph> and <codeph>rls_string8</codeph>.
-It is used to specify the type of widget in which the localisable item is
-used. There is a list of UI contexts for Symbian developers, which are extended
-by the platform suppliers. The Symbian developers must use the values defined
-for the platforms on which they are developing. </p> <p>The possible values
-for this tag are: </p> <ul>
-<li id="GUID-E21387AA-B4DA-59CD-9C96-783DEA10529B"><p> <codeph>notvisible</codeph> to
-specify that the item does not appear in the UI. </p> </li>
-<li id="GUID-800536F2-9524-5A8F-8919-A57962346F91"><p> <codeph>pluginname</codeph> to
-specify that the string is the name of an ECOM (or other) plug-in. </p> </li>
-<li id="GUID-26670A96-7A7C-558F-8747-5D77F24EA2EE"><p> <codeph>system</codeph> to
-specify that the item may appear in the UI, but the component that supplies
-the UI does not mandate where. </p> </li>
-<li id="GUID-1E32422C-C7AE-59CE-9E55-956614395349"><p> <codeph>errortext</codeph> to
-specify that the string is used by the error resolver. </p> </li>
-<li id="GUID-C3AAA814-0117-5083-A272-81968E7399E9"><p> <codeph>fragment</codeph> to
-specify that the item is part of a string that appears in the UI. For example,
-a list separator. </p> </li>
-<li id="GUID-4A0EADED-7CB0-5105-AEBF-B0ACC10A1F21"><p> <codeph>appname</codeph> to
-specify the application name in the <codeph>APP_REGISTRATION_INFO</codeph> structure. </p> </li>
-<li id="GUID-7527BBBE-3AA6-5CCD-A124-4977316B5814"><p> <codeph>appgroup</codeph> to
-specify the application group in the <codeph>APP_REGISTRATION_INFO</codeph> structure. </p> </li>
-</ul> <p>For example: </p> <codeblock id="GUID-876F09BF-98DA-5CFD-8E8F-C5CB57A60A52" xml:space="preserve">/*&
-@uicontext pluginname
-*/
-rls_string STRING_1 "Device locked"
-</codeblock> </li>
-<li id="GUID-9E1F9CBA-14EC-52F1-8A8B-6AA3C6B07762"><p> <codeph>@group</codeph>:
-This is an optional tag used to group strings together. For example, you can
-group all strings that appear in the same view together. To group strings
-under a group, you have to define a group using the following syntax: </p> <codeblock id="GUID-05A63AFD-99A4-5C8E-9C62-8BB8F70D10DD" xml:space="preserve">@tagvalue group <your-group-name> [group-description]</codeblock> <p>Where, <varname>your-group-name</varname> is a name for the group, and <varname>group-description</varname> is an
-optional description about the group. </p> <p>For example, </p> <codeblock id="GUID-425EEBDF-432B-5D2E-A524-EBF0DB8A7187" xml:space="preserve">/*&
-@tagvalue group lock_dialog
-*/
-</codeblock> <p>You can use the group defined above as follows: </p> <codeblock id="GUID-1A81832F-679D-5DC0-A237-C4496A3610CA" xml:space="preserve">/*&
-@localize yes
-@group lock_dialog
-*/
-rls_string STRING_1 "Device locked"
-</codeblock> </li>
-<li id="GUID-A2E5B5EB-8EC1-5632-A576-DFBE1DD879C5"><p> <codeph>@uispec</codeph>:
-This is an optional tag used to specify where in the specifications document
-the RLS item appears. </p> <p>For example: </p> <codeblock id="GUID-E7E2A822-6840-5F69-A5F7-864882AABC4F" xml:space="preserve">/*&
-@uispec UIQ/ringtones-specification.doc/4.31
-*/
-rls_string STRING_2 "happy bugle.wav"
-</codeblock> </li>
-</ul>
-<p><b>Creating new RLS comment tags </b> </p>
-<p>Apart from the pre-defined set of tags listed above, you can also declare
-a new tag and use it in the localisation comments. Tags are declared in resource
-header files (<filepath>.rh</filepath>). You can configure the <codeph>epocrc</codeph> tool
-to recognise the comment definitions from such files through the <filepath>epocrc.config</filepath> configuration
-file. For more information, refer to <xref href="GUID-5FFBC0B0-FC6E-5D60-868B-064DBEB632E0.dita#GUID-5FFBC0B0-FC6E-5D60-868B-064DBEB632E0/GUID-014671B6-C19E-528A-984C-D8226375AC5A">epocrc
-configuration file format</xref>. </p>
-<p>The following is the BNF description for declaring a new tag: </p>
-<p><i><codeph><tag-declaration></codeph></i>
-</p>
-<p><b>tag-declaration ::=</b>
- </p>
-<p><b><codeph>@declaretag </codeph></b><i><codeph><tag-type> <new-tag-name>
-[<description>] <tag-type></codeph></i>
-</p>
-<p><b>tag-type ::=
-</b> </p>
-<p><b><codeph>single | multiple | text | void</codeph></b></p>
-<p>Where, <varname>tag-type</varname> is used to specify the type value the
-tag can take. If you want the tag to take a single value, use "<codeph>single</codeph> "
-as the tag type. If you want the tag to take a single value from a set of
-values, use "<codeph>multiple</codeph> " as the tag type. For example, the <codeph>@uicontext</codeph> tag
-is of <codeph>multiple</codeph> type. If you want the tag not to take any
-value, use "<codeph>void</codeph> " as the tag type. If you want the tag to
-take free text, use "<codeph>text</codeph> " as the tag type. For example,
-the <codeph>@description</codeph> tag is of <codeph>text</codeph> type. </p>
-<p>For example, the following declares a tag called “visible” of type single: </p>
-<codeblock id="GUID-8C1F4921-CF51-57FA-8DDB-A9106B0AAF26" xml:space="preserve">@declaretag single visible</codeblock>
-<p>If you had declared the tag as <codeph>single</codeph> or <codeph>multiple</codeph>,
-you must declare its values. Value declaration is not required for other tag
-types. </p>
-<p>The following is the BNF description for declaring values for a tag: </p>
-<p><i><codeph><tag-value-declaration></codeph></i></p>
-<p>
-<b>tag-value-declaration ::=</b></p>
-<p>
- <b>@tagvalue</b> <i><codeph><tag-name> <list-of-values></codeph></i></p>
-<p>Where, <varname>tag-name</varname> is the name of the tag declared earlier.
-If the tag is of multiple type, the <varname>list-of-values</varname> lists
-a set of values for the tag, otherwise a single value must be specified. </p>
-<p>For example, the following declares that the permitted value for the visible
-tag is "yes": </p>
-<codeblock id="GUID-EE092FF4-FA7A-591B-9103-5875CE422224" xml:space="preserve">@tagvalue visible yes</codeblock>
-<p>After declaring the values for the tag, you must specify whether the tag
-is required or optional for an RLS item. The BNF description for this is as
-follows: </p>
-<p><i><codeph><tag-required-statement></codeph></i></p>
-<p><b>
-tag-required-statement ::=</b></p>
-<p>
- <b>@tagrequired</b><i><codeph> <tag-name> <rls-type-identifier>
-<tag-optional-statement></codeph></i>
-</p>
-<p><b>tag-optional-statement ::=</b></p>
-<p>
- <b>@tagoptional</b> <i><codeph><tag-name>=[<default-value>] <rls-type-identifier>
-<rls-type-identifier></codeph></i>
-</p>
-<p><b>rls-type-identifier ::=</b></p>
-<p>
- <b><codeph>rls_string | rls_string8 | rls_byte | rls_word | rls_long |
-rls_double</codeph></b></p>
-<p>Where, <varname>tag-name</varname> is the name of the declared tag, <varname>default-value</varname> is
-the default value used for optional tags. </p>
-<p>For example, the following declares that the visible tag is optional, and
-has a default value of “yes” for rls_string items: </p>
-<codeblock id="GUID-8793CE31-6D00-5607-AD69-77E7FC7B5D54" xml:space="preserve">@tagoptional visible=yes rls_string</codeblock>
-</conbody></concept>
\ No newline at end of file