Initial revision

14 files changed, 1297 insertions, 0 deletions

diff --git a/docs/.cvsignore b/docs/.cvsignore
new file mode 100644
index 00000000..569dc9d8
--- /dev/null
+++ b/docs/.cvsignore
@@ -0,0 +1,4 @@
+sgml
+html
+gscript-decl-list.txt
+gscript-decl.txt
diff --git a/docs/Makefile.am b/docs/Makefile.am
new file mode 100644
index 00000000..255916d5
--- /dev/null
+++ b/docs/Makefile.am
@@ -0,0 +1,45 @@
+## Process this file with automake to create Makefile.in.
+
+if HAVE_GTK_DOC
+
+# The name of the module.
+DOC_MODULE=pango
+
+# The top-level SGML file.
+DOC_MAIN_SGML_FILE=pango-docs.sgml
+
+INCLUDE_DIR=../libpango
+SOURCE_DIR=../libpango
+
+scan:
+	gtkdoc-scan --module=$(DOC_MODULE) $(INCLUDE_DIR)/pango*.h
+
+templates: scan
+	gtkdoc-mktmpl --module=$(DOC_MODULE)
+
+sgml:
+	gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(SOURCE_DIR)
+
+html:
+	if ! test -d html ; then mkdir html ; fi
+	-cd html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE)
+
+clean-local:
+	rm -f *~ *.bak *.hierarchy *.signals *.args *-unused.txt
+
+maintainer-clean-local: clean
+	rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt 
+
+.PHONY: scan sgml html templates 
+
+endif
+
+EXTRA_DIST=pango-sections.txt pango-docs.sgml
+
+dist-hook:
+	mkdir $(distdir)/tmpl
+	cp -p $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
+	mkdir $(distdir)/TEXT
+	for i in $(srcdir)/TEXT/* ; do \
+	  test -f $$i && cp -p $$i $(distdir)/TEXT ;\
+        done
diff --git a/docs/TEXT/glossary b/docs/TEXT/glossary
new file mode 100644
index 00000000..aa1d1f58
--- /dev/null
+++ b/docs/TEXT/glossary
@@ -0,0 +1,49 @@
+CFont:   A font component. This is a rendering-specific entity
+         which is paired with a glyph index to uniquely indentify
+         a glyph. Each abstract Font maps to one or more CFonts;
+         the method for obtaining CFonts from Fonts is also
+         rendering system specific.
+
+Cluster: A cluster is a small portion of text that is rendered
+         as typographically intertwined glyphs.
+
+         A number of properties are associated with clusters
+         and cluster boundaries.
+
+         1) Clusters are the smallest unit of text that is guaranteed to
+         progress in reading order. Within a cluster, reordering
+         of glyphs may occur.
+
+         2) At the boundaries of clusters, character boundaries
+         and glyph boundaries are guaranteed to coincide.
+
+	 3) There will be a cursor position between every two clusters.
+         There may not be a cursor position at some positions
+         inside a cluster.
+
+	 4) The cluster boundary is the only place where information
+         about the correspondence between character position
+         and screen position is conveyed from the shape-engine
+         to the layers above. 
+
+Engine:  A script-specific object that is responsible for 
+         converting Unicode text into glyphs or resolving
+         the properties of the text. Engines may be 
+	 rendering-system specific or independent of rendering
+	 system.
+
+Font:    An abstract font. The method in which a font is
+         created is dependent on the rendering system.
+
+Item:    An item is a portion of text in a single script, handled
+         by a single shaping engine, and with a single directional
+         level. g_script_itemize() returns a list of items.
+
+Module:  A dynamically loaded shared object containing one
+         or more Engines.
+
+Range:   A subportion of an item. You pass a range into
+         g_script_shape() by passing in the analysis structure
+         for the item and some subportion of the text.
+
+
diff --git a/docs/TEXT/modules b/docs/TEXT/modules
new file mode 100644
index 00000000..5e250bc8
--- /dev/null
+++ b/docs/TEXT/modules
@@ -0,0 +1,42 @@
+General points
+==============
+
+One global entry point for each module:
+
+g_i18n_list_functions()
+
+ function : language : vtable
+
+
+Tool:
+
+ gi18n-updatedb
+
+Input Method Module
+===================
+
+ Functions:
+
+ Callbacks:
+
+   Set the status area contents
+   Set the preedit string contents
+   Position the caret
+   Begin preediting
+   End preediting
+
+Shaping Module
+=============
+
+ Segment input text
+ Turn characters into glyphs
+ Provide line-break information 
+ 
+
+Output Modules
+==============
+
+ Position/justify glyphs
+
+
+
diff --git a/docs/TEXT/questions b/docs/TEXT/questions
new file mode 100644
index 00000000..a74b8649
--- /dev/null
+++ b/docs/TEXT/questions
@@ -0,0 +1,19 @@
+- Is it worth splitting off display-font independent stuff
+  from display dependent stuff. How do we do that?
+
+- Can we abandon XIM? Can we support XIM in backwards-compatibility
+  mode? Just in RootWindow mode?
+
+- Are input methods windowing system independent? What do
+  we gain/lose?
+
+- Do we need to worry about glyph changes at line breaks?
+
+- Do we ever need to break clusters on line breaks?
+
+- Do input methods need attributed strings for displaying
+  feedback? If so, do we build such support into GDK?
+  Into GTK+?
+
+- How do we index positions in a string 
+  (By character? By byte?)
diff --git a/docs/TEXT/western-design b/docs/TEXT/western-design
new file mode 100644
index 00000000..57c81dba
--- /dev/null
+++ b/docs/TEXT/western-design
@@ -0,0 +1,34 @@
+Issues that this engine needs to handle:
+
+ - Picking the right character based on language/character
+ - Composition of combining diacriticals - should use precomposed
+   diacriticals when possible
+ - Finding word/line/breaks
+
+For each sequence of character + combining marks
+
+ - Find combined representations from most combined to least combined.
+ - If there are particular characters for this combination, use
+   them, otherwise 
+
+==========
+
+Ligature table per font.
+Pick fonts in order of preference according to LANG
+
+Characterstics of western/basic:
+
+ Consistent LTR
+ No reordering
+ Many characters => one glyph
+ Character/Word/Line breaking dependent only on character properties
+
+Issues
+ 
+ Accent placement for Greek, Vietnamese
+ How do we handle a case where lang == en_US, we have a glyph
+   combination with a combined form in iso-8859-2 but not
+   in iso-8859-1?
+
+
+
diff --git a/docs/pango-docs.sgml b/docs/pango-docs.sgml
new file mode 100644
index 00000000..dfa790c9
--- /dev/null
+++ b/docs/pango-docs.sgml
@@ -0,0 +1,25 @@
+<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
+<!entity pango-main SYSTEM "sgml/main.sgml">
+<!entity pango-glyphs SYSTEM "sgml/glyphs.sgml">
+<!entity pango-fonts SYSTEM "sgml/fonts.sgml">
+<!entity pango-engines SYSTEM "sgml/engines.sgml">
+<!entity pango-x SYSTEM "sgml/pango-x.sgml">
+]>
+<book>
+  <bookinfo>
+    <title>Pango Reference Manual</title>
+  </bookinfo>
+
+  <chapter id="pango">
+    <title>Basic Pango Interfaces</title>
+    &pango-main;
+    &pango-glyphs;
+    &pango-fonts;
+    &pango-engines;
+  </chapter>
+
+  <chapter id="pango-x">
+    <title>Rendering under X with Pango</title>
+    &pango-x;
+    </chapter>
+</book>
\ No newline at end of file
diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt
new file mode 100644
index 00000000..f4e41f2f
--- /dev/null
+++ b/docs/pango-sections.txt
@@ -0,0 +1,83 @@
+<SECTION>
+<TITLE>Text Processing</TITLE>
+<FILE>main</FILE>
+<SUBSECTION>
+pango_itemize
+PangoContext
+PangoItem
+PangoAnalysis
+PangoLangRange
+pango_reorder_items
+<SUBSECTION>
+pango_break
+PangoLogAttr
+<SUBSECTION>
+pango_shape
+pango_justify
+<SUBSECTION>
+pango_cp_to_x
+pango_x_to_cp
+</SECTION>
+
+<SECTION>
+<TITLE>Glyph Storage</TITLE>
+<FILE>glyphs</FILE>
+PangoGlyph
+PangoGlyphIndex
+PangoGlyphGeometry
+PangoGlyphUnit
+PangoGlyphVisAttr
+PangoGlyphString
+pango_glyph_string_new
+pango_glyph_string_set_size
+pango_glyph_string_free
+</SECTION>
+
+<SECTION>
+<TITLE>Fonts</TITLE>
+<FILE>fonts</FILE>
+PangoFont
+PangoFontClass
+pango_font_init
+pango_font_ref
+pango_font_unref
+pango_font_get_data
+pango_font_set_data
+PangoCFont
+PangoCFontClass
+pango_cfont_init
+pango_cfont_ref
+pango_cfont_unref
+</SECTION>
+
+<SECTION>
+<TITLE>Engines</TITLE>
+<FILE>engines</FILE>
+PangoEngineInfo
+PangoEngineRange
+PangoEngine
+PangoEngineLang
+PangoEngineShape
+PANGO_ENGINE_TYPE_LANG
+PANGO_ENGINE_TYPE_SHAPE
+PANGO_RENDER_TYPE_NONE
+script_engine_list
+script_engine_load
+script_engine_unload
+</SECTION>
+
+<SECTION>
+<FILE>pango-x</FILE>
+<TITLE>X Rendering</TITLE>
+PANGO_RENDER_TYPE_X
+PangoXCFont
+pango_x_load_font
+pango_x_render
+pango_x_extents
+pango_x_glyph_extents
+pango_x_find_cfont
+pango_x_list_cfonts
+pango_x_load_xlfd
+pango_x_xlfd_get_ranges
+</SECTION>
+
diff --git a/docs/tmpl/engines.sgml b/docs/tmpl/engines.sgml
new file mode 100644
index 00000000..17402dfd
--- /dev/null
+++ b/docs/tmpl/engines.sgml
@@ -0,0 +1,248 @@
+<!-- ##### SECTION Title ##### -->
+Engines
+
+<!-- ##### SECTION Short_Description ##### -->
+Modules to do language-specific and rendering-system-specific
+processing.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+Pango utilizes a module architecture in which
+the language-specific and render-system-specific
+components are provided by loadable modules. Each
+loadable module supplies one or more
+<firstterm>engines</firstterm>. 
+Each <firstterm>engine</firstterm> has an associated
+<firstterm>engine type</firstterm> and 
+<firstterm>render type</firstterm>. These two
+types are represented by strings.
+</para>
+<para>
+Each dynamically-loaded module exports several
+functions which provide the public API. These
+functions are script_engine_list(), 
+script_engine_load() and script_engine_unload().
+The latter two functions are used for loading
+and unloading modules, while the first function
+is used when building a catalog of all available
+modules.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### STRUCT PangoEngineInfo ##### -->
+<para>
+The #PangoEngineInfo structure contains
+information about a particular engine. It
+contains the following fields:
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>gchar *id;</entry>
+<entry>a unique string ID for the engine.</entry>
+</row>
+<row>
+<entry>gchar *engine_type;</entry>
+<entry>a string identifying the engine type.</entry>
+</row>
+
+<row>
+<entry>gchar *render type;</entry>
+<entry>a string identifying the render type.</entry>
+</row>
+
+<row>
+<entry>#PangoEngineRange *ranges;</entry>
+<entry>a pointer to an array of #PangoEngineRange
+       structures. Each structure contains information
+       about a range of Unicode code points that
+       this engine handles.</entry>
+</row>
+
+<row>
+<entry>gint n_ranges;</entry>
+<entry>the number of elements in <structfield>ranges</structfield>.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+<!-- ##### STRUCT PangoEngineRange ##### -->
+<para>
+The PangoEngineRange structure contains
+information about a range of Unicode code
+points. It contains the following fields:
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>guint32 start;</entry>
+<entry>the first code point in the range.</entry>
+</row>
+
+<row>
+<entry>guint32 end;</entry>
+<entry>the last code point for the range.</entry>
+</row>
+
+<row>
+<entry>gchar *langs;</entry>
+<entry>A semicolon separated list of languages that this
+       engine handles for this range. This may be empty, 
+       in which case the engine is saying that it is a
+       fallback choice for all languages for this range,
+       but should not be used if another engine provides
+       indicates that it is specific for the language for
+       a given code point. A  entry in this list of "*"
+       indicates that this engine is specific to all
+       languages for this range.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+<!-- ##### STRUCT PangoEngine ##### -->
+<para>
+The #PangoEngine structure contains basic
+information common to all script engines. It
+contains the following fields:
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>gchar *id;</entry>
+<entry>a unique string ID for this language engine.</entry>
+</row>
+
+<row>
+<entry>gchar *type;</entry>
+<entry>The "type" of the engine. (Is this engine type or render type??).</entry>
+</row>
+
+<row>
+<entry>gint length;</entry>
+<entry>the length of the entire structure in bytes. This is 
+       provided so that new functions can be added at the
+       end of subtypes of #PangoEngine without breaking
+       older modules.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+<!-- ##### STRUCT PangoEngineLang ##### -->
+<para>
+The #PangoEngineLang structure extents the
+basic #PangoEngine structure to engines that
+deal with the rendering-system independent part
+of of the rendering pipeline. It contains the following fields:
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>#PangoEngine engine;</entry>
+<entry>A nested structure containing basic engine data.</entry>
+</row>
+
+<row>
+<entry>void (*script_break) (...);</entry>
+<entry>A function that provides an implementation
+       for pango_break().</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+<!-- ##### STRUCT PangoEngineShape ##### -->
+<para>
+The #PangoEngineShape structure extents the
+basic #PangoEngine structure to engines that
+deal with the rendering-system dependent part
+of of the rendering pipeline. It contains the following fields:
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>#PangoEngine engine;</entry>
+<entry>A nested structure containing basic engine data.</entry>
+</row>
+
+<row>
+<entry> void (*script_shape) (...);</entry>
+<entry>A function that provides an implementation
+       for pango_shape.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+
+<!-- ##### MACRO PANGO_ENGINE_TYPE_LANG ##### -->
+<para>
+A string constant defining the engine type
+for <firstterm>language engines</firstterm>.
+These engines have a engine structure of 
+type #PangoEngineLang.
+</para>
+
+
+
+<!-- ##### MACRO PANGO_ENGINE_TYPE_SHAPE ##### -->
+<para>
+A string constant defining the engine type
+for <firstterm>shaping engines</firstterm>.
+These engines have a engine structure of 
+type #PangoEngineShape.
+</para>
+
+<!-- ##### MACRO PANGO_RENDER_TYPE_NONE ##### -->
+<para>
+A string constant defining the render type
+for engines that are not rendering-system 
+specific.
+</para>
+
+<!-- ##### FUNCTION script_engine_list ##### -->
+<para>
+Function to be provided by a module to list
+the engines that the module supplies.
+</para>
+
+@engines: location to store a pointer to an array of engines.
+@n_engines: location to store the number of elements in @engines.
+
+
+<!-- ##### FUNCTION script_engine_load ##### -->
+<para>
+Function to be provided by a module to load
+a particular engine.
+</para>
+
+@id: the ID from the #ScriptEngineInfo structure of the
+     module to load.
+@Returns: the newly created script engine.
+
+
+<!-- ##### FUNCTION script_engine_unload ##### -->
+<para>
+Function to be provided by a module to unload
+an engine.
+</para>
+
+@engine: the engine to unload.
+
+
diff --git a/docs/tmpl/fonts.sgml b/docs/tmpl/fonts.sgml
new file mode 100644
index 00000000..70592fed
--- /dev/null
+++ b/docs/tmpl/fonts.sgml
@@ -0,0 +1,192 @@
+<!-- ##### SECTION Title ##### -->
+Fonts
+
+<!-- ##### SECTION Short_Description ##### -->
+Structures representing abstract fonts.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+Pango supports a flexible architecture where a
+particular rendering architecture can supply an
+implementation of fonts. The #PangoFont and
+#PangoCFont structures represent an abstract
+rendering-system-indepent font, and a
+<firstterm>component</firstterm> of such a font,
+respectively.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### STRUCT PangoFont ##### -->
+<para>
+The #PangoFont structure is used to represent
+a font in a rendering-system-independent matter.
+To create an implementation of a #PangoFont,
+the rendering-system specific code should malloc
+a larger structure that contains a nested
+#PangoFont, fill in the klass member of
+the nested #PangoFont with a pointer to
+a appropriate #PangoFontClass, then call
+pango_font_init() on the structure.
+</para>
+<para>
+The #PangoFont structure contains one member
+that may be accessed by derived classes:
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>#PangoFontClass *klass;</entry>
+<entry>a pointer to the <firstterm>class structure</firstterm>
+       for this font.</entry>
+</row>
+</tbody></tgroup></informaltable>
+</para>
+
+
+<!-- ##### STRUCT PangoFontClass ##### -->
+<para>
+The PangoFontClass structure contains the virtual
+functions for an implementation of a a PangoFont.
+
+It contains the following member:
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>void (*destroy) (#PangoFont *font);</entry>
+<entry>a function to free the font structure and associated resources.</entry>
+</row>
+</tbody></tgroup></informaltable>
+</para>
+
+
+<!-- ##### FUNCTION pango_font_init ##### -->
+<para>
+
+</para>
+
+@font: 
+
+
+<!-- ##### FUNCTION pango_font_ref ##### -->
+<para>
+
+</para>
+
+@font: 
+
+
+<!-- ##### FUNCTION pango_font_unref ##### -->
+<para>
+
+</para>
+
+@font: 
+
+
+<!-- ##### FUNCTION pango_font_get_data ##### -->
+<para>
+
+</para>
+
+@font: 
+@key: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_font_set_data ##### -->
+<para>
+
+</para>
+
+@font: 
+@key: 
+@data: 
+@destroy_func: 
+
+
+<!-- ##### STRUCT PangoCFont ##### -->
+<para>
+The #PangoCFont structure is used to represent a single componenent
+of a font n a rendering-system-independent matter. A component of a
+font is an opaque object that makes sense only to the rendering
+system. A glyph (the #PangoGlyph structure) is stored as a #PangoCFont
+and a numeric glyph index.
+</para>
+<para>
+To create an implementation of a #PangoCFont,
+the rendering-system specific code should malloc
+a larger structure that contains a nested
+#PangoCFont, fill in the klass member of
+the nested #PangoCFont with a pointer to
+a appropriate #PangoCFontClass, then call
+pango_cfont_init() on the structure.
+</para>
+<para>
+The #PangoCFont structure contains one member
+that may be accessed by derived classes:
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>#PangoCFontClass *klass;</entry>
+<entry>a pointer to the <firstterm>class structure</firstterm>
+       for this font.</entry>
+</row>
+</tbody></tgroup></informaltable>
+</para>
+
+
+<!-- ##### STRUCT PangoCFontClass ##### -->
+<para>
+The PangoCFontClass structure contains the virtual
+functions for an implementation of a a PangoCFont.
+
+It contains the following member:
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>void (*destroy) (#PangoFont *font);</entry>
+<entry>a function to free the font structure and associated resources.</entry>
+</row>
+</tbody></tgroup></informaltable>
+</para>
+
+
+<!-- ##### FUNCTION pango_cfont_init ##### -->
+<para>
+
+</para>
+
+@font: 
+
+
+<!-- ##### FUNCTION pango_cfont_ref ##### -->
+<para>
+
+</para>
+
+@font: 
+
+
+<!-- ##### FUNCTION pango_cfont_unref ##### -->
+<para>
+
+</para>
+
+@font: 
+
+
diff --git a/docs/tmpl/glyphs.sgml b/docs/tmpl/glyphs.sgml
new file mode 100644
index 00000000..a764f2ef
--- /dev/null
+++ b/docs/tmpl/glyphs.sgml
@@ -0,0 +1,180 @@
+<!-- ##### SECTION Title ##### -->
+Glyph Storage
+
+<!-- ##### SECTION Short_Description ##### -->
+Structures for storing information about glyphs.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+pango_shape() produces a string of glyphs which
+can be measured or drawn to the screen. The following
+structures are used to store information about
+glyphs.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### STRUCT PangoGlyph ##### -->
+<para>
+The #PangoGlyph structure represents a single glyph in the output
+form of a string. It contains the following fields.
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>#PangoGlyphIndex glyph;</entry>
+<entry>the index of the glyph into the font. (Rendering system
+       dependent).</entry>
+</row>
+
+<row>
+<entry>#PangoCFont *font;</entry>
+<entry>the rendering-system-specific font information for this glyph.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+
+<!-- ##### TYPEDEF PangoGlyphIndex ##### -->
+<para>
+The #PangoGlyphIndex type is an integral type used to store glyph
+indices.
+</para>
+
+
+<!-- ##### STRUCT PangoGlyphGeometry ##### -->
+<para>
+The #PangoGlyphGeometry structure contains width and positioning
+information for a single glyph. Distances are in
+1/64ths of a point.
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>#PangoGlyphUnit width;</entry>
+<entry>the logical width to use for the the character.</entry>
+</row>
+
+<row>
+<entry>#PangoCFont *x_offset;</entry>
+<entry>horizontal offset from nominal character position.</entry>
+</row>
+
+<row>
+<entry>#PangoCFont *y_offset;</entry>
+<entry>vertical offset from nominal character position.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+
+<!-- ##### TYPEDEF PangoGlyphUnit ##### -->
+<para>
+The #PangoGlyphUnit type is used to store dimensions within
+Pango. Dimensions are stored in 1/64ths of a point.
+</para>
+
+
+<!-- ##### STRUCT PangoGlyphVisAttr ##### -->
+<para>
+The PangoGlyphVisAttr is used to communicate information between
+the shaping phase and the rendering phase. It's contents
+are still evolving.
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>#guint is_cluster_start : 1;</entry>
+<entry>set for the first logical glyph in each cluster. (Clusters
+       are stored in visual order, within the cluster, glyphs
+       are always ordered in logical order, since visual
+       order is meaningless; that is, in Arabic text, accent glyphs
+       follow the glyphs for the base character.)
+</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+
+<!-- ##### STRUCT PangoGlyphString ##### -->
+<para>
+The #PangoGlyphString structure is used to store strings
+of glyphs with geometry and visual attribute information.
+The storage for the glyph information is owned
+by the structure which simplifies memory management.
+</para>
+<para>
+#PangoGlyphString contains the following publically
+accessible fields
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>gint #num_glyphs;</entry>
+<entry>the number of glyphs in the string.</entry>
+</row>
+
+<row>
+<entry>PangoGlyph *#glyphs;</entry>
+<entry>an array of glyphs of length <structfield>num_glyphs</structfield>.</entry>
+</row>
+
+<row>
+<entry>PangoGlyphGeometry *#geometry;</entry>
+<entry>an array of #PangoGlyphGeometry structures corresponding to <structfield>glyphs</structfield>.</entry>
+</row>
+
+<row>
+<entry>PangoGlyphVisAttr *#attrs;</entry>
+<entry>an array of #PangoGlyphVisAttr structures corresponding to <structfield>glyphs</structfield>.</entry>
+</row>
+
+<row>
+<entry>gint *#log_clusters;</entry>
+<entry>for each glyph, the character index (should this be byte
+       index?) of the starting character for the cluster.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+
+<!-- ##### FUNCTION g_glyph_string_new ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION g_glyph_string_set_size ##### -->
+<para>
+
+</para>
+
+@string: 
+@new_len: 
+
+
+<!-- ##### FUNCTION g_glyph_string_free ##### -->
+<para>
+
+</para>
+
+@string: 
+
+
diff --git a/docs/tmpl/main.sgml b/docs/tmpl/main.sgml
new file mode 100644
index 00000000..f251783b
--- /dev/null
+++ b/docs/tmpl/main.sgml
@@ -0,0 +1,229 @@
+<!-- ##### SECTION Title ##### -->
+Rendering
+
+<!-- ##### SECTION Short_Description ##### -->
+Functions to run the rendering pipeline.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+The Pango rendering pipeline takes a string of
+Unicode characters and converts it into glyphs.
+The functions described in this section accomplish
+various steps of this process.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### FUNCTION pango_itemize ##### -->
+<para>
+
+</para>
+
+@context: 
+@text: 
+@length: 
+@lang_info: 
+@n_langs: 
+@Returns: 
+
+
+<!-- ##### STRUCT PangoContext ##### -->
+<para>
+The #PangoContext structure stores global information
+used to control the itemization process. It contains
+the following fields:
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>gchar *lang;</entry>
+<entry>the global default language in the standard form
+       "fr" or "fr_FR". (This may be overriden
+       with the @lang_info parameter to pango_itemize().)</entry>
+</row>
+
+<row>
+<entry>gchar *render_type;</entry>
+<entry>a string identifier for the rendering system to use,
+       for instance %PANGO_RENDER_TYPE_X</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+
+<!-- ##### STRUCT PangoItem ##### -->
+<para>
+The #PangoItem structure stores information about
+a segment of text. It contains the following fields:
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>gint offset;</entry>
+<entry>the offset of the segment from the beginning of the
+       string in bytes.</entry>
+</row>
+
+<row>
+<entry>gint length;</entry>
+<entry>the length of the segment in bytes.</entry>
+</row>
+
+<row>
+<entry>gint num_chars;</entry>
+<entry>the length of the segment in characters.</entry>
+</row>
+
+<row>
+<entry>gint analysis;</entry>
+<entry>the properties of the segment.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+
+<!-- ##### STRUCT PangoAnalysis ##### -->
+<para>
+The #PangoAnalysis structure stores information about
+the properties of a segment of text. It has the following
+fields:
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>#PangoEngineShape *shape_engine;</entry>
+<entry>the engine for doing rendering-system-dependent processing</entry>
+</row>
+
+<row>
+<entry>#PangoEngineLang *lang_engine;</entry>
+<entry>the engine for doing rendering-system-independent processing</entry>
+</row>
+
+<row>
+<entry>guint8 level;</entry>
+<entry>the bidrectional level for this segment.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+
+<!-- ##### STRUCT PangoLangRange ##### -->
+<para>
+The #PangoLangRange structure stores language tagging
+information for a range of character positions of text. 
+It contains the following fields:
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry>gint start;</entry>
+<entry>the start position of this tagged range in bytes.</entry>
+</row>
+
+<row>
+<entry>gint length;</entry>
+<entry>the length of this tagged range in bytes.</entry>
+</row>
+
+<row>
+<entry>gchar *lang;</entry> 
+<entry>the language for this range, in the standard form 
+       "fr" or "fr_FR".</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+
+<!-- ##### FUNCTION pango_reorder_items ##### -->
+<para>
+
+</para>
+
+@logical_items: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_break ##### -->
+<para>
+
+</para>
+
+@text: 
+@length: 
+@analysis: 
+@attrs: 
+
+
+<!-- ##### STRUCT PangoLogAttr ##### -->
+<para>
+The #PangoLogAttr structure stores information
+about the attributes of a single character.
+</para>
+
+
+<!-- ##### FUNCTION pango_shape ##### -->
+<para>
+
+</para>
+
+@font: 
+@text: 
+@length: 
+@analysis: 
+@glyphs: 
+
+
+<!-- ##### FUNCTION pango_justify ##### -->
+<para>
+
+</para>
+
+@glyphs: 
+@new_line_width: 
+@min_kashida_width: 
+
+
+<!-- ##### FUNCTION pango_cp_to_x ##### -->
+<para>
+
+</para>
+
+@text: 
+@length: 
+@analysis: 
+@glyphs: 
+@char_pos: 
+@trailing: 
+@x_pos: 
+
+
+<!-- ##### FUNCTION pango_x_to_cp ##### -->
+<para>
+
+</para>
+
+@text: 
+@length: 
+@analysis: 
+@glyphs: 
+@x_pos: 
+@char_pos: 
+@trailing: 
+
+
diff --git a/docs/tmpl/pango-unused.sgml b/docs/tmpl/pango-unused.sgml
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/docs/tmpl/pango-unused.sgml
diff --git a/docs/tmpl/pango-x.sgml b/docs/tmpl/pango-x.sgml
new file mode 100644
index 00000000..b3f18eed
--- /dev/null
+++ b/docs/tmpl/pango-x.sgml
@@ -0,0 +1,147 @@
+<!-- ##### SECTION Title ##### -->
+X Rendering
+
+<!-- ##### SECTION Short_Description ##### -->
+Functions for rendering and measuring glyphs on
+the X Window system.
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### MACRO PANGO_RENDER_TYPE_X ##### -->
+<para>
+%PANGO_RENDER_TYPE_X is a string constant that
+is used to identify shaping modules for the
+X Window System.
+</para>
+
+
+
+<!-- ##### STRUCT PangoXCFont ##### -->
+<para>
+The PangoXCFont represents a component of a
+composite font for the X window system. It
+has the following publically accessible fields:
+
+<informaltable pgwide=1 frame="none" role="struct">
+<tgroup cols="2"><colspec colwidth="2*"><colspec colwidth="8*">
+<tbody>
+
+<row>
+<entry><structname>Display</structname> *display;</entry>
+<entry>the X Display for which this font component was created.</entry>
+</row>
+
+<row>
+<entry><structname>XFontStruct</structname> *font_struct;</entry>
+<entry>the X font information for the corresponding X font.</entry>
+</row>
+
+</tbody></tgroup></informaltable>
+</para>
+
+
+<!-- ##### FUNCTION pango_x_load_font ##### -->
+<para>
+
+</para>
+
+@display: 
+@spec: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_x_render ##### -->
+<para>
+
+</para>
+
+@display: 
+@d: 
+@gc: 
+@glyphs: 
+@x: 
+@y: 
+
+
+<!-- ##### FUNCTION pango_x_extents ##### -->
+<para>
+
+</para>
+
+@glyphs: 
+@lbearing: 
+@rbearing: 
+@width: 
+@ascent: 
+@descent: 
+@logical_ascent: 
+@logical_descent: 
+
+
+<!-- ##### FUNCTION pango_x_glyph_extents ##### -->
+<para>
+
+</para>
+
+@glyph: 
+@lbearing: 
+@rbearing: 
+@width: 
+@ascent: 
+@descent: 
+@logical_ascent: 
+@logical_descent: 
+
+
+<!-- ##### FUNCTION pango_x_find_cfont ##### -->
+<para>
+
+</para>
+
+@font: 
+@charset: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_x_list_cfonts ##### -->
+<para>
+
+</para>
+
+@font: 
+@charsets: 
+@n_charsets: 
+@xlfds: 
+@n_xlfds: 
+
+
+<!-- ##### FUNCTION pango_x_load_xlfd ##### -->
+<para>
+
+</para>
+
+@font: 
+@xlfd: 
+@Returns: 
+
+
+<!-- ##### FUNCTION pango_x_xlfd_get_ranges ##### -->
+<para>
+
+</para>
+
+@font: 
+@xlfd: 
+@ranges: 
+@n_ranges: 
+@Returns: 
+
+