Added ITS conformance page and stubs for i18n and l10n pages

4 files changed, 347 insertions, 0 deletions

diff --git a/doc/mallard/C/explore.xml b/doc/mallard/C/explore.xml
index 4c45c8f..9d1b21f 100644
--- a/doc/mallard/C/explore.xml
+++ b/doc/mallard/C/explore.xml
@@ -24,4 +24,8 @@
   <p>Add content</p>
 </comment>
 
+<section id="i18n">
+  <title>Internationalization and Localization</title>
+</section>
+
 </page>
diff --git a/doc/mallard/C/i18n.xml b/doc/mallard/C/i18n.xml
new file mode 100644
index 0000000..38dd099
--- /dev/null
+++ b/doc/mallard/C/i18n.xml
@@ -0,0 +1,22 @@
+<page xmlns="http://www.gnome.org/~shaunm/mallard"
+      type="topic"
+      id="i18n">
+
+<info>
+  <link type="guide" xref="explore#i18n"/>
+
+  <version number="0.1" date="2009-05-26" status="stub"/>
+
+  <credit type="author">
+    <name>Shaun McCance</name>
+    <email>shaunm@gnome.org</email>
+  </credit>
+  <copyright>
+    <year>2009</year>
+    <name>Shaun McCance</name>
+  </copyright>
+</info>
+
+<title>Internationalization Notes</title>
+
+</page>
diff --git a/doc/mallard/C/its.xml b/doc/mallard/C/its.xml
new file mode 100644
index 0000000..bf15d50
--- /dev/null
+++ b/doc/mallard/C/its.xml
@@ -0,0 +1,299 @@
+<page xmlns="http://www.gnome.org/~shaunm/mallard"
+      type="topic"
+      id="its">
+
+<info>
+  <link type="guide" xref="explore#i18n"/>
+
+  <version number="0.1" date="2009-05-26" status="incomplete"/>
+
+  <credit type="author">
+    <name>Shaun McCance</name>
+    <email>shaunm@gnome.org</email>
+  </credit>
+  <copyright>
+    <year>2009</year>
+    <name>Shaun McCance</name>
+  </copyright>
+</info>
+
+<title>ITS Conformance</title>
+
+<p>This page discusses Mallard's conformance to the requirements in the
+<link href="http://www.w3.org/TR/itsreq/">W3C Internationalization
+and Localization Markup Requirements</link>, as well as its usage of
+attributes from the <link href="http://www.w3.org/TR/its/">W3C
+Internationalization Tag Set</link>.</p>
+
+<section id="R002">
+  <title>R002: Span-Like Element</title>
+
+  <quote>
+    <cite href="http://www.w3.org/TR/itsreq/#span">W3C
+    Internationalization and Localization Markup Requirements</cite>
+    <p>[R002] span-like element is required to allow authors to mark sections
+    text that may have special properties, from a localization and
+    internationalization point of view.</p>
+  </quote>
+
+  <p>Mallard provides the <code xref="mal_inline_span">span</code> element,
+  a general-purpose span-like element.  The <code>span</code> element accepts
+  attributes from external namespaces, allowing attributes such as
+  <code>xml:lang</code> and
+  <code href="http://www.w3.org/TR/its/#trans-datacat">its:translate</code>
+  to be used in Mallard documents.</p>
+</section>
+
+<section id="R004">
+  <title>R004: Unique Identifier</title>
+
+  <quote>
+    <cite href="http://www.w3.org/TR/itsreq/#uid">W3C
+    Internationalization and Localization Markup Requirements</cite>
+    <p>[R004] It should be possible to attach a unique identifier to any
+    localizable item. This identifier should be unique within a document set,
+    but should be identical across all translations of the same item.</p>
+  </quote>
+
+  <p>While the <code>id</code> attribute is only allowed on
+  <code xref="mal_page">page</code> and <code xref="mal_section">section</code>
+  elements, Mallard does allow attributes from external namespaces to be used
+  on all elements.  If necessary for translation purposes, any attribute from
+  an external attribute may be used as a unique identifier.  In particular,
+  Mallard does not use the common <code>xml:id</code> for page and section
+  IDs, but it may be used on any element to provide a unique identifier for
+  translation or any other purposes.</p>
+</section>
+
+<section id="R006">
+  <title>R006: Identifying Language/Locale</title>
+
+  <quote>
+    <cite href="http://www.w3.org/TR/itsreq/#langlocale">W3C
+    Internationalization and Localization Markup Requirements</cite>
+    <p>[R006] Any document at its beginning should declare a language/locale
+    that is applied to both main content and external content stored separately.
+    While the language/locale may be declared for the whole document, when an
+    element or a text span is in a different language/locale from the
+    document-level language, it should be labeled appropriately. Therefore,
+    DTD/Schema should allow any elements to have a language/locale specifying
+    attribute. The language/locale declaration should use industry standard
+    approaches.</p>
+  </quote>
+
+  <p>Mallard allows the standard <code>xml:lang</code> attribute to be used
+  on all elements.</p>
+
+  <p>Note that there are two different methods of identifying language and locale
+  information that are likely to be encountered by those working with Mallard.
+  Since Mallard is an XML format, language identifiers are expected to conform
+  to <link href="http://tools.ietf.org/html/rfc3066">IETF RFC 3066</link>.
+  Since Mallard is designed to be used in a desktop help system,
+  <link href="http://en.wikipedia.org/wiki/Locale">POSIX locale identifiers</link>
+  are more convenient.  This is a potentially serious interchange issue, and this
+  document currently offers no solutions to this problem.</p>
+</section>
+
+<section id="R007">
+  <title>R007: Identifying Terms</title>
+
+  <quote>
+    <cite href="http://www.w3.org/TR/itsreq/#termid">W3C
+    Internationalization and Localization Markup Requirements</cite>
+    <p>[R007] It should be possible to identify terms inside an element or a
+    span and to provide data for terminology management and index generation.
+    Terms should be either associated with attributes for related term
+    information or linked to external terminology data.</p>
+  </quote>
+
+  <comment>
+    <cite date="2009-05-26">shaunm</cite>
+    <p>FIXME: not sure what this is asking for.  Is this something we need
+    to address directly, or something we get for free with external attrs?</p>
+  </comment>
+</section>
+
+<section id="R008">
+  <title>R008: Purpose Specification/Mapping</title>
+
+  <quote>
+    <cite href="http://www.w3.org/TR/itsreq/#mapping">W3C
+    Internationalization and Localization Markup Requirements</cite>
+    <p>[R008] Currently, it does not appear to be realistic that all XML
+    vocabularies tag localization-relevant information identical (e.g. all
+    use the "term" tag for terms). One way to take care of diverse
+    localization-relevant markup in localization environments is a mapping
+    mechanism which maps localization-relevant markup onto a canonical
+    representation (such as the Internationalization Tag Set).</p>
+  </quote>
+
+  <comment>
+    <cite date="2009-05-26">shaunm</cite>
+    <p>FIXME: need to look into this more.</p>
+  </comment>
+</section>
+
+<section id="R011">
+  <title>R011: Bidirectional Text Support</title>
+
+  <quote>
+    <cite href="http://www.w3.org/TR/itsreq/#bidi">W3C
+    Internationalization and Localization Markup Requirements</cite>
+    <p>[R011] Markup should be available to support the needs of bidirectional
+    scripts.</p>
+  </quote>
+
+  <p>Mallard allows attributes from external namespaces to be used on all
+  elements.  Consequently, the
+  <code href="http://www.w3.org/TR/its/#directionality">its:dir</code>
+  attribute may be used to specify text directionality.</p>
+</section>
+
+<section id="R012">
+  <title>R012: Indicator of Translatability</title>
+
+  <quote>
+    <cite href="http://www.w3.org/TR/itsreq/#transinfo">W3C
+    Internationalization and Localization Markup Requirements</cite>
+    <p>[R012] Methods must exist to allow to specify the parts of a document
+    that are to be translated or not.</p>
+  </quote>
+
+  <p>Mallard allows attributes from external namespaces to be used on all
+  elements.  Consequently, the
+  <code href="http://www.w3.org/TR/its/#trans-datacat">its:translate</code>
+  attribute may be used to specify whether parts of a document are to be
+  translated.</p>
+
+  <p>Additionally, the
+  <code href="http://www.w3.org/TR/its/#trans-datacat">its:rules</code>
+  element may be used in any <code xref="mal_info">info</code> element to
+  provide translatability rules for a page or section.</p>
+</section>
+
+<section id="R014">
+  <title>R014: Limited Impact</title>
+
+  <quote>
+    <cite href="http://www.w3.org/TR/itsreq/#impact">W3C
+    Internationalization and Localization Markup Requirements</cite>
+    <p>[R014] All solutions proposed should be designed to have as less impact
+    as possible on the tree structure of the original document and on the
+    content models in the original schema.</p>
+  </quote>
+
+  <p>Mallard allows tool-specific extensibility using attributes and elements
+  from external namespaces.  Mallard has
+  <link xref="mal_external">clearly defined rules</link> for how attributes
+  and elements from external namespaces are to be processed in various contexts.
+  Tools writers are expected to be aware of these issues.  Whenever possible,
+  this document issues that can arise from extensions, including those for
+  translation purposes.</p>
+
+  <p>While it is impossible to predict all issues one might encounter, Mallard
+  was developed after years of developing translation tools for other formats.
+  Internationalization and localization were primary concerns in the design
+  of Mallard.</p>
+</section>
+
+<section id="R017">
+  <title>R017: Localization Notes</title>
+
+  <quote>
+    <cite href="http://www.w3.org/TR/itsreq/#locnotes">W3C
+    Internationalization and Localization Markup Requirements</cite>
+    <p>[R017] A method must exist for authors to communicate information to
+    localizers about a particular item of content.</p>
+  </quote>
+
+  <p>Mallard allows attributes from external namespaces to be used on all
+  elements.  Consequently, the
+  <code href="http://www.w3.org/TR/its/#trans-datacat">its:locNote</code> and
+  <code href="http://www.w3.org/TR/its/#trans-datacat">its:locNoteRule</code>
+  attributes may be used to provide localization notes.</p>
+
+  <p>If more extensive localization notes are needed, the
+  <code xref="mal_block_comment">comment</code> element may be used.  Using a
+  <code href="http://www.w3.org/TR/its/#trans-datacat">its:rules</code>
+  element in an <code xref="mal_info">info</code> element, one can clearly
+  specify which editorial comments are localization notes.</p>
+</section>
+
+<section id="R020">
+  <title>R020: Annotation Markup</title>
+
+  <quote>
+    <cite href="http://www.w3.org/TR/itsreq/#annomark">W3C
+    Internationalization and Localization Markup Requirements</cite>
+    <p>[R020] There must be a way to support markup up of text annotations of
+    the 'ruby' type.</p>
+  </quote>
+
+  <p>Elements from external namespaces may be used in all
+  <link xref="mal_inline">inline contexts</link>.  While this allows Ruby
+  annotations to be embedded within a Mallard document, the
+  <link xref="mal_inline#processing">fallback processing expectations</link>
+  are unlikely to produce satisfactory results for tools that do not support
+  Ruby.  Future versions of this document should address this issue.</p>
+</section>
+
+<section id="R025">
+  <title>R025: Elements and Segmentation</title>
+
+  <quote>
+    <cite href="http://www.w3.org/TR/itsreq/#elemseg">W3C
+    Internationalization and Localization Markup Requirements</cite>
+    <p>[R025] Methods, independent of the semantic, of the elements must
+    exist to provide hints on how to break down document content into
+    meaningful runs of text.</p>
+  </quote>
+
+  <p>Making meaningful distinctions is ultimately the job of a processing
+  tool, although the design of an XML vocabulary can have a significant
+  impact on implementation difficulty.  The following notes will be relevant
+  to most tool implementors.</p>
+
+  <list>
+    <item>
+      <p>In Mallard, no elements contain “pernicious mixed content”: a
+      problematic content model wherein an element can contain either
+      inline content or block content, but not both.  Resolving such
+      content models generally involves testing for the existence of
+      one of a certain set of elements, which can be difficult as
+      content models grow.</p>
+      <p>In Mallard, pernicious mixed content would be particularly
+      problematic, since certain element names are used in both block
+      and inline contexts.</p>
+    </item>
+
+    <item>
+      <p>In Mallard, elements generally contain either block content or
+      inline content.  Thus, for example, you cannot place a paragraph
+      inside a paragraph.  This is simpler for translators, as well as
+      for translation tool implementors, because it reduces the need
+      to use placeholders for separate translation units.</p>
+    </item>
+
+    <item>
+      <p>One notable exception to the above is the <code>item</code>
+      element in <link xref="mal_block_tree">tree lists</link>.  To
+      simplify writing, tree list items simply take inline content
+      followed by any number of nested tree list items.  Since the
+      block-like items are not interspersed with the inline content,
+      however, translation tools should be able to handle this case
+      without placeholders.</p>
+    </item>
+
+    <item>
+      <p>It is noteworthy that Mallard reuses some element names in both block
+      and inline contexts.  The <code xref="mal_block_code">code</code> and
+      <code xref="mal_block_media">media</code> elements are two examples of
+      this.  Since Mallard never allows general block content to be mixed with
+      general inline content, the purpose of these elements is unambiguous when
+      processed in context.  Thus, it is important that tools always process
+      elements in context to handle them correctly.</p>
+    </item>
+  </list>
+</section>
+
+</page>
diff --git a/doc/mallard/C/l10n.xml b/doc/mallard/C/l10n.xml
new file mode 100644
index 0000000..3bfda21
--- /dev/null
+++ b/doc/mallard/C/l10n.xml
@@ -0,0 +1,22 @@
+<page xmlns="http://www.gnome.org/~shaunm/mallard"
+      type="topic"
+      id="l10n">
+
+<info>
+  <link type="guide" xref="explore#i18n"/>
+
+  <version number="0.1" date="2009-05-26" status="stub"/>
+
+  <credit type="author">
+    <name>Shaun McCance</name>
+    <email>shaunm@gnome.org</email>
+  </credit>
+  <copyright>
+    <year>2009</year>
+    <name>Shaun McCance</name>
+  </copyright>
+</info>
+
+<title>Translation Notes</title>
+
+</page>