Part of Bug 325714 – Pango should respect $LANGUAGE

2007-05-13  Behdad Esfahbod  <behdad@gnome.org>

        Part of Bug 325714 – Pango should respect $LANGUAGE

        * pango/pango-ot.h:
        * pango/pango-ot-private.h:
        * pango/pango-ot-tag.c (pango_ot_tag_from_script),
        (pango_ot_tag_from_language):
        * pango/pango-ot-info.c (pango_ot_info_find_script),
        (pango_ot_info_find_language), (pango_ot_info_find_feature),
        (pango_ot_info_list_languages), (pango_ot_info_list_features):
        * pango/pango-ot-ruleset.c (pango_ot_ruleset_new),
        (pango_ot_ruleset_new_for), (pango_ot_ruleset_add_feature),
        (pango_ot_ruleset_maybe_add_feature),
        (pango_ot_ruleset_maybe_add_features):
        Add new engine API:

                PANGO_OT_NO_FEATURE
                PANGO_OT_NO_SCRIPT
                PANGO_OT_TAG_DEFAULT_SCRIPT
                PANGO_OT_TAG_DEFAULT_LANGUAGE
                pango_ot_ruleset_new_for()
                pango_ot_ruleset_maybe_add_feature()
                pango_ot_ruleset_maybe_add_features()

        Using pango_ot_ruleset_new_for() and
        pango_ot_ruleset_maybe_add_features() drastically simplifies ruleset
        building in modules, and does correct script and language selection
        too.  Modules need to be updated to use it though.

        * docs/pango-docs.sgml:
        * docs/pango-sections.txt:
        * docs/tmpl/opentype.sgml:
        Update.


svn path=/trunk/; revision=2284

5 files changed, 116 insertions, 19 deletions

diff --git a/docs/pango-docs.sgml b/docs/pango-docs.sgml
index b8670dec..3c82eeec 100644
--- a/docs/pango-docs.sgml
+++ b/docs/pango-docs.sgml
@@ -18,7 +18,7 @@
 <!ENTITY pango-Win32-Fonts-and-Rendering SYSTEM "xml/win32-fonts.xml">
 <!ENTITY pango-FreeType-Fonts-and-Rendering SYSTEM "xml/freetype-fonts.xml">
 <!ENTITY pango-Xft-Fonts-and-Rendering SYSTEM "xml/xft-fonts.xml">
-<!ENTITY pango-ATSUI-Fonts-and-Rendering SYSTEM "xml/atsui-fonts.xml">
+<!ENTITY pango-ATSUI-Fonts SYSTEM "xml/atsui-fonts.xml">
 <!ENTITY pangocairo SYSTEM "xml/pangocairo.xml">
 <!ENTITY PangoFcFontMap SYSTEM "xml/pangofc-fontmap.xml">
 <!ENTITY PangoFcFont SYSTEM "xml/pangofc-font.xml">
@@ -57,7 +57,7 @@
     &pango-FreeType-Fonts-and-Rendering;
     &pango-Xft-Fonts-and-Rendering;
     &pangocairo;
-    &pango-ATSUI-Fonts-and-Rendering;
+    &pango-ATSUI-Fonts;
     &pango-X-Fonts-and-Rendering;
   </chapter>
 
@@ -87,36 +87,38 @@
     <title>Object Hierarchy</title>
     &pango-tree-index;
   </chapter>
-  <index/>
 
-  <index role="deprecated">
+  <index id="index-all">
+    <title>Index</title>
+  </index>
+  <index id="index-deprecated" role="deprecated">
     <title>Index of deprecated symbols</title>
   </index>
-  <index role="1.2">
+  <index id="index-1.2" role="1.2">
     <title>Index of new symbols in 1.2</title>
   </index>
-  <index role="1.4">
+  <index id="index-1.4" role="1.4">
     <title>Index of new symbols in 1.4</title>
   </index>
-  <index role="1.6">
+  <index id="index-1.6" role="1.6">
     <title>Index of new symbols in 1.6</title>
   </index>
-  <index role="1.8">
+  <index id="index-1.8" role="1.8">
     <title>Index of new symbols in 1.8</title>
   </index>
-  <index role="1.10">
+  <index id="index-1.10" role="1.10">
     <title>Index of new symbols in 1.10</title>
   </index>
-  <index role="1.12">
+  <index id="index-1.12" role="1.12">
     <title>Index of new symbols in 1.12</title>
   </index>
-  <index role="1.14">
+  <index id="index-1.14" role="1.14">
     <title>Index of new symbols in 1.14</title>
   </index>
-  <index role="1.16">
+  <index id="index-1.16" role="1.16">
     <title>Index of new symbols in 1.16</title>
   </index>
-  <index role="1.18">
+  <index id="index-1.18" role="1.18">
     <title>Index of new symbols in 1.18</title>
   </index>
 </book>
diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt
index e7348d31..e016407e 100644
--- a/docs/pango-sections.txt
+++ b/docs/pango-sections.txt
@@ -941,9 +941,13 @@ PangoOTBuffer
 PangoOTGlyph
 PangoOTRuleset
 PangoOTTableType
+PangoOTFeatureMap
 PANGO_OT_ALL_GLYPHS
+PANGO_OT_NO_FEATURE
+PANGO_OT_NO_SCRIPT
 PANGO_OT_DEFAULT_LANGUAGE
-PANGO_OT_DEFAULT_SCRIPT
+PANGO_OT_TAG_DEFAULT_LANGUAGE
+PANGO_OT_TAG_DEFAULT_SCRIPT
 pango_ot_info_get
 pango_ot_info_find_script
 pango_ot_info_find_language
@@ -960,7 +964,10 @@ pango_ot_buffer_set_zero_width_marks
 pango_ot_buffer_get_glyphs
 pango_ot_buffer_output
 pango_ot_ruleset_new
+pango_ot_ruleset_new_for
 pango_ot_ruleset_add_feature
+pango_ot_ruleset_maybe_add_feature
+pango_ot_ruleset_maybe_add_features
 pango_ot_ruleset_substitute
 pango_ot_ruleset_position
 pango_ot_tag_from_language
diff --git a/docs/tmpl/atsui-fonts.sgml b/docs/tmpl/atsui-fonts.sgml
index f838f998..d711d4c3 100644
--- a/docs/tmpl/atsui-fonts.sgml
+++ b/docs/tmpl/atsui-fonts.sgml
@@ -2,7 +2,7 @@
 ATSUI Fonts
 
 <!-- ##### SECTION Short_Description ##### -->
-Font handling and rendering with ATSUI fonts
+Font handling with ATSUI fonts
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
diff --git a/docs/tmpl/opentype.sgml b/docs/tmpl/opentype.sgml
index 1bc78474..6c4f7be0 100644
--- a/docs/tmpl/opentype.sgml
+++ b/docs/tmpl/opentype.sgml
@@ -86,6 +86,17 @@ identify the various OpenType tables in the
 @PANGO_OT_TABLE_GSUB: The GSUB table.
 @PANGO_OT_TABLE_GPOS: The GPOS table.
 
+<!-- ##### STRUCT PangoOTFeatureMap ##### -->
+<para>
+The <type>PangoOTFeatureMap</type> typedef is used to represent an OpenType
+feature with the property bit associated with it.  The feature tag is
+represented as a char array instead of a #PangoOTTag for convenience.
+</para>
+
+@feature_name: feature tag in represented as four-letter ASCII string.
+@property_bit: the property bit to use for this feature.  See
+	       pango_ot_ruleset_add_feature() for details.
+
 <!-- ##### MACRO PANGO_OT_ALL_GLYPHS ##### -->
 <para>
 This is used as the property bit in pango_ot_ruleset_add_feature() when a
@@ -94,18 +105,60 @@ feature should be applied to all glyphs.
 
 
 
+<!-- ##### MACRO PANGO_OT_NO_FEATURE ##### -->
+<para>
+This is used as a feature index that represent no feature, that is, should be
+skipped.  It may be returned as feature index by pango_ot_info_find_feature()
+if the feature is not found, and pango_ot_rulset_add_feature() function
+automatically skips this value, so no special handling is required by the
+user.
+</para>
+
+
+
+<!-- ##### MACRO PANGO_OT_NO_SCRIPT ##### -->
+<para>
+This is used as a script index that represent no script, that is, when the
+requested script was not found, and a default ('DFLT') script was not found
+either.  It may be returned as script index by pango_ot_info_find_script()
+if the script or a default script are not found, all other functions
+taking a script index essentially return if the input script index is
+this value, so no special handling is required by the user.
+</para>
+
+
+
 <!-- ##### MACRO PANGO_OT_DEFAULT_LANGUAGE ##### -->
 <para>
 This is used as the language index in pango_ot_info_find_feature() when
 the default language system of the script is desired.
+
+It is also returned by pango_ot_info_find_language() if the requested language
+is not found, or the requested language tag was PANGO_OT_TAG_DEFAULT_LANGUAGE.
+The end result is that one can always call pango_ot_tag_from_language()
+followed by pango_ot_info_find_language() and pass the result to
+pango_ot_info_find_feature() without having to worry about falling back to
+default language system explicitly.
+</para>
+
+
+
+<!-- ##### MACRO PANGO_OT_TAG_DEFAULT_LANGUAGE ##### -->
+<para>
+This is a #PangoOTTag representing a special language tag 'dflt'.  It is
+returned as language tag by pango_ot_tag_from_language() if the requested
+language is not found.  It is safe to pass this value to
+pango_ot_info_find_language() as that function falls back to returning default
+language-system if the requested language tag is not found.
 </para>
 
 
 
-<!-- ##### MACRO PANGO_OT_DEFAULT_SCRIPT ##### -->
+<!-- ##### MACRO PANGO_OT_TAG_DEFAULT_SCRIPT ##### -->
 <para>
-Expands to the #PangoOTTag corresponding to the special OpenType
-script tag 'DFLT'.
+This is a #PangoOTTag representing the special script tag 'DFLT'.  It is
+returned as script tag by pango_ot_tag_from_script() if the requested script
+is not found.
 </para>
 
 
@@ -276,6 +329,17 @@ script tag 'DFLT'.
 @Returns: 
 
 
+<!-- ##### FUNCTION pango_ot_ruleset_new_for ##### -->
+<para>
+
+</para>
+
+@info: 
+@script: 
+@language: 
+@Returns: 
+
+
 <!-- ##### FUNCTION pango_ot_ruleset_add_feature ##### -->
 <para>
 
@@ -287,6 +351,30 @@ script tag 'DFLT'.
 @property_bit: 
 
 
+<!-- ##### FUNCTION pango_ot_ruleset_maybe_add_feature ##### -->
+<para>
+
+</para>
+
+@ruleset: 
+@table_type: 
+@feature_tag: 
+@property_bit: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_ot_ruleset_maybe_add_features ##### -->
+<para>
+
+</para>
+
+@ruleset: 
+@table_type: 
+@features: 
+@n_features: 
+@Returns: 
+
+
 <!-- ##### FUNCTION pango_ot_ruleset_substitute ##### -->
 <para>
 
diff --git a/docs/tmpl/pangocairo.sgml b/docs/tmpl/pangocairo.sgml
index 1a07574d..0299893d 100644
--- a/docs/tmpl/pangocairo.sgml
+++ b/docs/tmpl/pangocairo.sgml
@@ -132,7 +132,7 @@ int main (int argc, char **argv)
 }
 </programlisting>
 </example>
-<figure>
+<figure id="rotated-example-output">
   <title>Output of <xref linkend="rotated-example"/></title>
   <graphic fileref="rotated-text.png" format="PNG"/>
 </figure>