Remove color_set() virtual function ... it's not absolutely necessary for

Fri Nov 19 17:44:33 2004  Owen Taylor  <otaylor@redhat.com>

        * pango/pango-renderer.[ch]: Remove color_set() virtual
        function ... it's not absolutely necessary for chaining
        renderers, and it's not clear that chaining renderers
        is actually useful, anyways.

        * pango/pango-renderer.[ch] (pango_renderer_set_color): Constify
        color argument.

        * pango/pango-render.c: Fix various bugs.

        * pango/pango-attributes.[ch] (pango_attr_shape_new_with_data):
        Add the ability to create a shape attribute with user data.

        * pango/pango-renderer.[ch] (PangoRendererClass): Add a draw_shape
        virtual function, to draw content for PangoAttrShape.

        * pango/pangoxft-fontmap.c (pango_xft_shutdown_display):
        Add note to docs that XCloseDisplay() will automatically take care
        of releasing Pango's allocated resources for the display.

        * docs/Makefile.am (SCAN_OPTIONS): Add the appropriate
        --deprecated-guards option.

        * docs/tmpl/xft-fonts.sgml: Add long description.

        * docs/tmpl/x-fonts.sgml: Document as dead.

6 files changed, 63 insertions, 9 deletions

diff --git a/docs/Makefile.am b/docs/Makefile.am
index aefc843f..e04dfaed 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -9,7 +9,7 @@ DOC_MODULE=pango
 DOC_MAIN_SGML_FILE=pango-docs.sgml
 
 # Extra options to supply to gtkdoc-scan
-SCAN_OPTIONS=
+SCAN_OPTIONS=--deprecated-guards="PANGO_DISABLE_DEPRECATED"
 
 # The directory containing the source code. Relative to $(srcdir)
 DOC_SOURCE_DIR=../pango
diff --git a/docs/pango-docs.sgml b/docs/pango-docs.sgml
index ea014a5e..21498e6e 100644
--- a/docs/pango-docs.sgml
+++ b/docs/pango-docs.sgml
@@ -45,10 +45,10 @@
 
   <chapter id="rendering">
     <title>Rendering with Pango</title>
-    &pango-X-Fonts-and-Rendering;
     &pango-Win32-Fonts-and-Rendering;
     &pango-FreeType-Fonts-and-Rendering;
     &pango-Xft-Fonts-and-Rendering;
+    &pango-X-Fonts-and-Rendering;
   </chapter>
 
   <chapter id="lowlevel">
diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt
index d0e9c938..939952c2 100644
--- a/docs/pango-sections.txt
+++ b/docs/pango-sections.txt
@@ -307,6 +307,8 @@ pango_attr_underline_new
 PangoUnderline
 PANGO_TYPE_UNDERLINE
 pango_attr_shape_new
+pango_attr_shape_new_with_data
+PangoAttrDataCopyFunc
 pango_attr_scale_new
 pango_attr_fallback_new
 PANGO_SCALE_XX_SMALL
@@ -728,6 +730,7 @@ pango_xft_font_get_glyph
 pango_xft_font_get_unknown_glyph
 PangoXftRenderer
 PangoXftRendererClass
+
 pango_xft_renderer_new
 pango_xft_renderer_set_draw
 pango_xft_renderer_set_default_color
diff --git a/docs/tmpl/text-attributes.sgml b/docs/tmpl/text-attributes.sgml
index 7072b0f0..5aee1e0a 100644
--- a/docs/tmpl/text-attributes.sgml
+++ b/docs/tmpl/text-attributes.sgml
@@ -143,6 +143,9 @@ impose shape restrictions.
 @attr: the common portion of the attribute
 @ink_rect: the ink rectangle to restrict to
 @logical_rect: the logical rectangle to restrict to
+@data: 
+@copy_func: 
+@destroy_func: 
 
 <!-- ##### FUNCTION pango_parse_markup ##### -->
 <para>
@@ -347,6 +350,28 @@ The GObject type for #PangoUnderline.
 @Returns: 
 
 
+<!-- ##### FUNCTION pango_attr_shape_new_with_data ##### -->
+<para>
+
+</para>
+
+@ink_rect: 
+@logical_rect: 
+@data: 
+@copy_func: 
+@destroy_func: 
+@Returns: 
+
+
+<!-- ##### USER_FUNCTION PangoAttrDataCopyFunc ##### -->
+<para>
+
+</para>
+
+@data: 
+@Returns: 
+
+
 <!-- ##### FUNCTION pango_attr_scale_new ##### -->
 <para>
 
diff --git a/docs/tmpl/x-fonts.sgml b/docs/tmpl/x-fonts.sgml
index 161040f6..bd5a9a6d 100644
--- a/docs/tmpl/x-fonts.sgml
+++ b/docs/tmpl/x-fonts.sgml
@@ -1,14 +1,15 @@
 <!-- ##### SECTION Title ##### -->
-X Fonts and Rendering
+Deprecated X font backend
 
 <!-- ##### SECTION Short_Description ##### -->
-Functions for shape engines to manipulate X fonts
+Font handling and rendering with the deprecated X font backend
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-The functions and macros in this section are used by shape
-engines to look up glyphs for particular character
-sets within an #PangoFont for the X rendering system.
+The functions and macros in this section are for use with the old
+X font backend which used server-side bitmap fonts. This font backend
+is no longer supported, and attempts to use it will produce
+unpredictable results. Use the <link linkend="pango-Xft-Fonts-and-Rendering">Xft backend</link> instead.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
diff --git a/docs/tmpl/xft-fonts.sgml b/docs/tmpl/xft-fonts.sgml
index 00c7090c..50a6e02a 100644
--- a/docs/tmpl/xft-fonts.sgml
+++ b/docs/tmpl/xft-fonts.sgml
@@ -2,11 +2,36 @@
 Xft Fonts and Rendering
 
 <!-- ##### SECTION Short_Description ##### -->
-Functions for shape engines to manipulate Xft fonts
+Font handling and rendering with the Xft backend
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+The Xft library is a library for displaying fonts on the X window
+system; internally it uses the fontconfig library to locate font
+files, and the FreeType library to load and render fonts. The
+Xft backend is the recommended Pango font backend for screen
+display with X.
+</para>
+<para>
+Using the Xft backend is generally straightforward;
+pango_xft_get_context() creates a context for a specified display
+and screen. You can then create a #PangoLayout with that context
+and render it with pango_xft_render_layout(). At a more advanced
+level, the lowlevel fontconfig options used for rendering fonts
+can be affected using pango_xft_set_default_substitute(), and
+pango_xft_substitute_changed().
+</para>
+<para>
+A range of functions for drawing pieces of a layout, such as
+individual layout lines and glyphs strings are provided.  You can also
+directly create a #PangoXftRenderer. Finally, in some advanced cases, it
+is useful to derive from #PangoXftRenderer. Deriving from
+#PangoXftRenderer is useful for two reasons. One reason is be to
+support custom attributes by overriding #PangoRendererClass virtual
+functions like 'prepare_run' or 'draw_shape'. The reason is to
+customize exactly how the final bits are drawn to the destination by
+overring the #PangoXftRendererClass virtual functions
+'composite_glyphs' and 'composite_trapezoids'.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->