[gedit/zbrown/deteplification-src: 35/633] docs: add API breaks page

[Zander Brown <zbrown src gnome org>]

commit c3c9e4d3e7f23727169e10c362b81ee261ff8481
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Tue Nov 19 06:18:05 2019 +0100

    docs: add API breaks page
    
    The previous API breaks were documented on the wiki:
    https://wiki.gnome.org/Apps/Gedit/API-Changes
    
    But I prefer to have the API breaks documented alongside the gedit API,
    and links to symbols can be added.

 docs/reference/api-breaks.xml | 52 +++++++++++++++++++++++++++++++++++++++++++
 docs/reference/gedit-docs.xml |  2 ++
 docs/reference/meson.build    |  3 +++
 3 files changed, 57 insertions(+)
---
diff --git a/docs/reference/api-breaks.xml b/docs/reference/api-breaks.xml
new file mode 100644
index 000000000..6d8c2531d
--- /dev/null
+++ b/docs/reference/api-breaks.xml
@@ -0,0 +1,52 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+   "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
+[
+ <!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+
+<part id="api-breaks">
+  <title>API Breaks</title>
+
+  <para>
+    gedit is a quite old piece of software (created in 1998, at the beginnings
+    of the GNOME project), and as every software, the code evolves during its
+    lifetime. So there are sometimes API breaks for gedit plugins, there are no
+    API stability guarantees.
+  </para>
+
+  <para>
+    When it is possible, instead of directly removing an API, that API is first
+    marked as deprecated, and then removed for the next API break. See the
+    <link linkend="api-index-deprecated">index of deprecated symbols</link>.
+  </para>
+
+  <refsect1>
+    <title>3.34.0 -> 3.35.2</title>
+    <itemizedlist>
+      <listitem>
+        <para>
+          All previously deprecated APIs have been removed.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The <code>GeditDocument:use-gvfs-metadata</code> property has been
+          removed. But there was anyway a warning for not using that property in
+          a gedit plugin.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          For <link linkend="gedit-document-get-metadata">gedit_document_get_metadata()</link>
+          and <link linkend="gedit-document-set-metadata">gedit_document_set_metadata()</link>,
+          the key names should now have the prefix <code>"gedit-"</code> with
+          possibly an additional namespace for the plugin name, for example
+          <code>"gedit-spell-foobar"</code>. So the key names are now the same
+          regardless of the operating system, and the key names should no longer
+          start with <code>"metadata::"</code>.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </refsect1>
+</part>
diff --git a/docs/reference/gedit-docs.xml b/docs/reference/gedit-docs.xml
index 856ef271e..dd44439fd 100644
--- a/docs/reference/gedit-docs.xml
+++ b/docs/reference/gedit-docs.xml
@@ -27,6 +27,8 @@
     <xi:include href="xml/gedit-utils.xml"/>
   </chapter>
 
+  <xi:include href="api-breaks.xml"/>
+
   <chapter id="object-tree">
     <title>Object Hierarchy</title>
      <xi:include href="xml/tree_index.sgml"/>
diff --git a/docs/reference/meson.build b/docs/reference/meson.build
index 48e9020a6..1e33bbe99 100644
--- a/docs/reference/meson.build
+++ b/docs/reference/meson.build
@@ -95,6 +95,9 @@ gnome.gtkdoc(
   scan_args: libgedit_reference_scan_args,
   mkdb_args: libgedit_reference_mkdb_args,
   fixxref_args: libgedit_reference_fixxref_args,
+  content_files : [
+    'api-breaks.xml'
+  ],
   install: true,
   install_dir: join_paths(
     gtkdocdir,