[ESW Wiki] Update of "its0503ReqEntities" by ChristianLieske

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "ESW Wiki" for change notification.

The following page has been changed by ChristianLieske:
http://esw.w3.org/topic/its0503ReqEntities


------------------------------------------------------------------------------
  '''[http://www.w3.org/International/geo/2004/article-devt-process.html Status: Initial Draft]''' 
  ie. please focus on technical content, rather than wordsmithing at this stage.
  
- Author: Yves Savourel
+ Author: Yves Savourel/Christian Liseke
  
  = Requirements related to Entities =
  
  == Challenge/Issue: ==
  
- XML applications (i.e. a combination of DTD/XSD, stylesheets, XML instances) often are subdivided into physical units called entities (see http://www.xml.com/axml/target.html#sec-physical-struct). Various types of entities exist (see http://tech.irt.org/articles/js212/#intro).
+ XML applications (i.e. a combination of DTD/XSD, stylesheets, XML instances) often make use of so-called entities (see http://www.xml.com/axml/target.html#sec-physical-struct). Various types of entities exist (see [http://tech.irt.org/articles/js212/#intro]).
  
  Examples:
  
-  1. A character entity. The entity defines a single Unicode character. 
+  1. A character entity. The entity defines a single Unicode character. Example: <!ENTITY aacute "&#225;" > 
- 
- Example: <!ENTITY aacute "&#225;" > 
- 
-  2. A short element-free text. The entity defines a short text that contains only text (no element or other XML constructs). This is for instance an entity for a product name.
+  2. A short element-free text. The entity defines a short text that contains only text (no element or other XML constructs). This is for instance an entity for a product name. Example: <!ENTITY productName "pictoMagic for Windows" > 
+  3. A longer text with one or more elements. The entity defines a piece of boiler-plate text such as a copyright paragraph. Example: <!ENTITY copyrightInfo "<a href='\copyright.htm'>Copyright</a> 2005 W3C."> 
- 
- Example: <!ENTITY ProductName "PictoMagic for Windows" > 
- 
-  3. A longer text with one or more elements. The entity defines a piece of boiler-plate text such as a copyright paragraph.
- 
- Example: <!ENTITY CopyrightInfo "<a href='\copyright.htm'>Copyright</a> 2005 W3C."> 
  
  Two aspects of entities are of particular importance with regard to internationalization and localization: 
  
-  1.      entities are defined 
+  1. entities are defined 
-  2.      entities are used 
+  2. entities are used 
  
  For example, the snippet 
  
-         <!ENTITY ProductName "PictoMagic for Windows" > 
+         <!ENTITY productName "pictoMagic for Windows" > 
  
- defines an entity called 'ProductName', and the snippet 
+ defines an entity called 'productName', and the snippet 
    
-         The latest version of &ProductName; features many enhancements. 
+         The latest version of &productName; features many enhancements. 
  
  references/uses the entity. 
  
  If internationalization and localization are not addressed for entity-related work several issues may arise: 
  
-  1.      Entity reference cannot be resolved 
+  1. Entity reference cannot be resolved. Example: the definition is not available to the XML processor 
+  2. Entity definition does not fit with the surrounding context language-wise. Example: The context in 'Das Produkt &productName; ist mit vielen Erweiterungen ausgestattet worden' is German whereas the definition may be in English
+  3. Entity definition does not fit with the surrounding context grammar-wise. Example: The syntax in 'The latest version of &productName; features many enhancements' may be incorrect if the definition designates an object in plural.
  
- Example: the definition is not available to the XML processor 
- 
-  2.      Entity definition does not fit with the surrounding context language-wise 
- 
- Example: The context in 'Das Produkt &ProductName; ist mit vielen Erweiterungen ausgestattet worden' is German whereas the definition may be in English
- 
-  3.      Entity definition does not fit with the surrounding context grammar-wise 
- 
- Example: The syntax in 'The latest version of &ProductName; features many enhancements' may be incorrect if the definition designates an object in plural.
- 
- In addition, even if the entity itself is translated there may be significant grammatical problems for inflected languages for nouns. The translation will inevitably follow the case of the original. For example, if the original is genitive, the translation is genitive as well (of course this requires that the original language and the translation language have a concept for ‘genitive’).
+ In addition, even if the entity itself is translated there may be significant grammatical problems for inflected languages for nouns. The translation will inevitably follow the case of the original. For example, if the original is genitive, the translation is genitive as well (of course this requires that the original language and the translation language have a concept for "genitive").
  
  Since entities affect the content of the document, and XSLT processors and other kinds of XML processors act on the content, various processing-related issues may arise. An XSLT stylesheet for example, which is sensitive to content contributed by an entity, may fail to work as expected (e.g. may not be able to generate the 'alt' for HTML pages).
  
@@ -73, +57 @@

  == Quick Guideline Thoughts: ==
  
   1. If possible, XML applications should avoid the use of entities. 
+  2. XML applications which have to make use of entities have to be build in such a way that entities can be localized easily (ie. the XML application has to be internationalized wrt. entities). A rough set of guidelines for this could look like this:
  
-  2. XML applications which have to make use of entities have to be build in such a way that entities can be localized easily (ie. the XML application has to be internationalized wrt. entities).
  
- A rough set of guidelines for this could look like this:
+   a. modularize your DTD
  
- a. modularize your DTD
+   b. work with entity declarations only for linguistically complete texts (ie. text which stands alone and does not rely on any surrounding context)
  
- b. put all entity declarations into a separate module/file
+   c. do not use entity references in #PCDATA (ie. the text content of elements); only use it in the sense of generated text (e.g. the heading which is generated by a stylesheet or contributed by an attribute definition in the DTD)
  
- c. follow a naming scheme for your entity modules which reflects recommendations for locale-specific information (e.g. name your file with English entities 'MyResource_en_US').
+   d. put all entity declarations into a separate module/file
  
-  3. If entities are used, the XML instances should have standalone="no" in their XML declarations (see http://www.w3.org/TR/REC-xml/#sec-rmd).
+   e. follow a naming scheme for your entity modules which reflects recommendations for locale-specific information (e.g. name your file with English entities 'myResource_en_US').
  
+ 
+  3. If entities are used, the XML instances should have standalone="no" in their XML declarations (see [http://www.w3.org/TR/REC-xml/#sec-rmd]).
+

Received on Monday, 18 April 2005 15:48:54 UTC