Mark deprecated apis more clearly

Move them to their own section in the docs.

4 files changed, 24 insertions, 20 deletions

diff --git a/docs/pango-docs.sgml b/docs/pango-docs.sgml
index 3c74d4ad..181f8aba 100644
--- a/docs/pango-docs.sgml
+++ b/docs/pango-docs.sgml
@@ -40,15 +40,19 @@
     <xi:include href="xml/pangofc-fontmap.xml"/>
     <xi:include href="xml/pangofc-font.xml"/>
     <xi:include href="xml/pangofc-decoder.xml"/>
-    <xi:include href="xml/opentype.xml"/>
     <xi:include href="xml/coverage-maps.xml"/>
+    <xi:include href="xml/utils.xml"/>
+    <xi:include href="xml/pango-version.xml"/>
+    </chapter>
+
+  <chapter id="deprecated">
+    <title>Deprecated APIs</title>
+    <xi:include href="xml/opentype.xml"/>
     <xi:include href="xml/engines.xml"/>
     <xi:include href="xml/pango-engine-lang.xml"/>
     <xi:include href="xml/pango-engine-shape.xml"/>
     <xi:include href="xml/modules.xml"/>
-    <xi:include href="xml/utils.xml"/>
-    <xi:include href="xml/pango-version.xml"/>
-    </chapter>
+  </chapter>
 
   <chapter id="pango-hierarchy">
     <title>Object Hierarchy</title>
diff --git a/pango/modules.c b/pango/modules.c
index 35ab2a30..25481bbd 100644
--- a/pango/modules.c
+++ b/pango/modules.c
@@ -24,8 +24,13 @@
  * @short_description:Support for loadable modules
  * @title:Modules
  *
- * Functions and macros in this section are used to support loading dynamic
- * modules that add engines to Pango at run time.
+ * Functions and macros in this section were used to support
+ * loading dynamic modules that add engines to Pango at run time.
+ *
+ * That is no longer the case, and these APIs should not be
+ * used anymore.
+ *
+ * Deprecated: 1.38
  */
 #include "config.h"
 
diff --git a/pango/pango-engine.c b/pango/pango-engine.c
index a22270eb..0cd57407 100644
--- a/pango/pango-engine.c
+++ b/pango/pango-engine.c
@@ -24,19 +24,12 @@
  * @short_description:Language-specific and rendering-system-specific processing
  * @title:Engines
  *
- * Pango utilizes a module architecture in which the language-specific
+ * Pango used to have 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.
+ * modules.
  *
- * Each dynamically-loaded module exports several functions which provide
- * the public API. These functions are script_engine_list(),
- * script_engine_init() and script_engine_exit, and
- * script_engine_create(). The latter three functions are used when
- * creating engines from the module at run time, while the first
- * function is used when building a catalog of all available modules.
+ * This is no longer the case, and all the APIs related
+ * to modules and engines should not be used anymore.
  *
  * Deprecated: 1.38
  */
diff --git a/pango/pango-ot-info.c b/pango/pango-ot-info.c
index 28f5dbc9..6116bf3f 100644
--- a/pango/pango-ot-info.c
+++ b/pango/pango-ot-info.c
@@ -25,9 +25,11 @@
  * @title:OpenType Font Handling
  * @stability:Unstable
  *
- * Functions and macros in this section are used to implement the OpenType Layout
- * features and algorithms.  These are mostly useful when writing Fontconfig-based
- * shaping engines
+ * Functions and macros in this section are used to implement
+ * the OpenType Layout features and algorithms.
+ *
+ * They have been superseded by the harfbuzz library, and should
+ * not be used anymore.
  */
 #include "config.h"