Action Item: paragraph on "need to document" for BP14 (cf. http://www.w3.org/2007/08/15-i18nits-minutes.html#action03)

Dear all,

I worked on my action item 'Christian to come up with a paragraph on "need
to document" for BP14 [recorded in
http://www.w3.org/2007/08/15-i18nits-minutes.html#action03])'.
 
Here's my proposal:

===
Why do this?

Although some XML vocabularies are easy to understand or process, often
explicit information about the vocabularies is helpful or even necessary. If
the vocabulary is to be used in a multilingual context (eg. kept when
translating during languages) it is usually of high importance to provide
specific information which pertains to aspects such as which elements
contain translatable content. General information on purpose, general
structure, and semantics of node types (elements and attributes in most
cases) very often is not sufficient. In a way, this need for explicit
information boils down to the "Document your code" dictum which is being
hammered into anyone involved in computer science.

In an XML world it should come naturally to use a well-defined structured
format to capture information. Accordingly, DocBook for example has been
used to document XSL. With regard to information related
internationalization and translation, ITS rules files are a good choice for
providing information:

1. ITS rules cover many important aspects related to internationalization
and translation.

2. ITS rules capture information precisely (selectors for example identify
to which nodes a data category pertains).

3. ITS rules can be processed by ITS-aware applications.

4. ITS rules can easily be combined with additional structured information
(e.g. related to version control; see example below).

<myFormatInfo
  xmlns:its="http://www.w3.org/2005/11/its" >
 <desc>ITS rules used by the Open University</desc>
 <hostVoc>http://www.tei-c.org/ns/1.0</hostVoc>
 <rulesId>98ECED99DF63D511B1250008C784EFB1</rulesId>
 <rulesVersion>v 1.81 2006/03/28 07:43:21</rulesVersion> ...
 <its:rules version="1.0">
  <its:translateRule selector="//header" translate="no"/>
  <its:translateRule selector="//term" translate="no"/>
  <its:termRule selector="//term" term="yes"/>
  <its:withinTextRule withinText="yes" selector="//term | //b"/>
 </its:rules>
</myFormatInfo>
=== 
Cheers,
Christian

Christian Lieske
MultiLingual Technology Solutions (MLT)
SAP Language Services (SLS)
SAP Globalization Services
SAP AG
Dietmar-Hopp-Allee 16
D-69190 Walldorf
Germany
T   +49 (62 27) 7 - 6 13 03
F   +49 (62 27) 7 – 2 54 18
christian.lieske@sap.com
http://www.sap.com

Sitz der Gesellschaft/Registered Office: Walldorf, Germany

Vorstand/SAP Executive Board: Henning Kagermann (Sprecher/CEO), Léo
Apotheker (stellvertretender Sprecher/Deputy CEO), Werner Brandt, Claus
Heinrich, Gerhard Oswald, Peter Zencke

Vorsitzender des Aufsichtsrats/Chairperson of the SAP Supervisory Board:
Hasso Plattner 

Registergericht/Commercial Register Mannheim No HRB 350269

 

Diese E-Mail kann Betriebs- oder Geschäftsgeheimnisse oder sonstige
vertrauliche Informationen enthalten. Sollten Sie diese E-Mail irrtümlich
erhalten haben, ist Ihnen eine Kenntnisnahme des Inhalts, eine
Vervielfältigung oder Weitergabe der E-Mail ausdrücklich untersagt.

Bitte benachrichtigen Sie uns und vernichten Sie die empfangene E-Mail.
Vielen Dank.

 

This e-mail may contain trade secrets or privileged, undisclosed, or
otherwise confidential information. If you have received this e-mail in
error, you are hereby notified that any review, copying, or distribution of
it is strictly prohibited. Please inform us immediately and destroy the
original transmittal. Thank you for your cooperation.