Port documentation to gi-docgen

21 files changed, 1895 insertions, 2281 deletions

diff --git a/docs/reference/libsecret/libsecret-c-examples.md b/docs/reference/libsecret/libsecret-c-examples.md
new file mode 100644
index 0000000..4eebffb
--- /dev/null
+++ b/docs/reference/libsecret/libsecret-c-examples.md
@@ -0,0 +1,251 @@
+Title: C Examples
+Slug: libsecret-c-example
+
+# C Examples
+
+## Define a password schema
+
+Each stored password has a set of attributes which are later
+used to lookup the password. The names and types of the attributes
+are defined in a schema. The schema is usually defined once globally.
+Here's how to define a schema:
+
+```c
+// in a header: 
+
+const SecretSchema * example_get_schema (void) G_GNUC_CONST;
+
+#define EXAMPLE_SCHEMA  example_get_schema ()
+
+
+// in a .c file: 
+
+const SecretSchema *
+example_get_schema (void)
+{
+    static const SecretSchema the_schema = {
+        "org.example.Password", SECRET_SCHEMA_NONE,
+        {
+            {  "number", SECRET_SCHEMA_ATTRIBUTE_INTEGER },
+            {  "string", SECRET_SCHEMA_ATTRIBUTE_STRING },
+            {  "even", SECRET_SCHEMA_ATTRIBUTE_BOOLEAN },
+            {  "NULL", 0 },
+        }
+    };
+    return &the_schema;
+}
+```
+
+See the [other examples](#store-a-password) for how to use the schema.
+
+## Store a password
+
+Here's how to store a password in the running secret service,
+like gnome-keyring or ksecretservice.
+
+Each stored password has a set of attributes which are later
+used to lookup the password. The attributes should not contain
+secrets, as they are not stored in an encrypted fashion.
+
+These examples use the [example schema](#define-a-password-schema).
+
+This first example stores a password asynchronously, and is
+appropriate for GUI applications so that the UI does not block.
+
+```c
+static void
+on_password_stored (GObject *source,
+                    GAsyncResult *result,
+                    gpointer unused)
+{
+    GError *error = NULL;
+
+    secret_password_store_finish (result, &error);
+    if (error != NULL) {
+        /* ... handle the failure here */
+        g_error_free (error);
+    } else {
+        /* ... do something now that the password has been stored */
+    }
+}
+
+/*
+ * The variable argument list is the attributes used to later
+ * lookup the password. These attributes must conform to the schema.
+ */
+secret_password_store (EXAMPLE_SCHEMA, SECRET_COLLECTION_DEFAULT, "The label",
+                       "the password", NULL, on_password_stored, NULL,
+                       "number", 8,
+                       "string", "eight",
+                       "even", TRUE,
+                       NULL);
+```
+
+This next example stores a password synchronously. The function
+call will block until the password is stored. So this is appropriate for
+non GUI applications.
+
+```c
+GError *error = NULL;
+
+/*
+ * The variable argument list is the attributes used to later
+ * lookup the password. These attributes must conform to the schema.
+ */
+secret_password_store_sync (EXAMPLE_SCHEMA, SECRET_COLLECTION_DEFAULT,
+                            "The label", "the password", NULL, &error,
+                            "number", 9,
+                            "string", "nine",
+                            "even", FALSE,
+                            NULL);
+
+if (error != NULL) {
+    /* ... handle the failure here */
+    g_error_free (error);
+} else {
+    /* ... do something now that the password has been stored */
+}
+```
+
+## Lookup a password
+
+Here's how to lookup a password in the running secret service,
+like gnome-keyring or ksecretservice.
+
+Each stored password has a set of attributes which are
+used to lookup the password. If multiple passwords match the
+lookup attributes, then the one stored most recently is returned.
+
+These examples use the [example schema](#define-a-password-schema).
+
+This first example looks up a password asynchronously, and is
+appropriate for GUI applications so that the UI does not block.
+
+```c
+static void
+on_password_lookup (GObject *source,
+                    GAsyncResult *result,
+                    gpointer unused)
+ {
+    GError *error = NULL;
+
+    gchar *password = secret_password_lookup_finish (result, &error);
+
+    if (error != NULL) {
+        /* ... handle the failure here */
+        g_error_free (error);
+
+    } else if (password == NULL) {
+        /* password will be null, if no matching password found */
+
+    } else {
+        /* ... do something with the password */
+        secret_password_free (password);
+    }
+
+}
+
+/*
+ * The variable argument list is the attributes used to later
+ * lookup the password. These attributes must conform to the schema.
+ */
+secret_password_lookup (EXAMPLE_SCHEMA, NULL, on_password_lookup, NULL,
+                        "string", "nine",
+                        "even", FALSE,
+                        NULL);
+```
+
+This next example looks up a password synchronously. The function
+call will block until the lookup completes. So this is appropriate for
+non GUI applications.
+
+```c
+GError *error = NULL;
+
+/* The attributes used to lookup the password should conform to the schema. */
+gchar *password = secret_password_lookup_sync (EXAMPLE_SCHEMA, NULL, &error,
+                                               "string", "nine",
+                                               "even", FALSE,
+                                               NULL);
+
+if (error != NULL) {
+    /* ... handle the failure here */
+    g_error_free (error);
+
+} else if (password == NULL) {
+    /* password will be null, if no matching password found */
+
+} else {
+    /* ... do something with the password */
+    secret_password_free (password);
+}
+```
+
+
+## Remove a password
+
+Here's how to remove a password from the running secret service,
+like gnome-keyring or ksecretservice.
+
+Each stored password has a set of attributes which are
+used to find which password to remove. If multiple passwords match the
+attributes, then the one stored most recently is removed.
+
+These examples use the [example schema](#define-a-password-schema).
+
+This first example removes a password asynchronously, and is
+appropriate for GUI applications so that the UI does not block.
+
+```c
+static void
+on_password_cleared (GObject *source,
+                     GAsyncResult *result,
+                     gpointer unused)
+ {
+    GError *error = NULL;
+
+    gboolean removed = secret_password_clear_finish (result, &error);
+
+    if (error != NULL) {
+        /* ... handle the failure here */
+        g_error_free (error);
+
+    } else {
+        /* removed will be TRUE if a password was removed */
+    }
+}
+
+/*
+ * The variable argument list is the attributes used to later
+ * lookup the password. These attributes must conform to the schema.
+ */
+secret_password_clear (EXAMPLE_SCHEMA, NULL, on_password_cleared, NULL,
+                       "string", "nine",
+                       "even", FALSE,
+                       NULL);
+```
+
+This next example looks up a password synchronously. The function
+call will block until the lookup completes. So this is appropriate for
+non GUI applications.
+
+```c
+GError *error = NULL;
+
+/*
+ * The variable argument list is the attributes used to later
+ * lookup the password. These attributes must conform to the schema.
+ */
+gboolean removed = secret_password_clear_sync (EXAMPLE_SCHEMA, NULL, &error,
+                                               "string", "nine",
+                                               "even", FALSE,
+                                               NULL);
+
+if (error != NULL) {
+    /* ... handle the failure here */
+    g_error_free (error);
+
+} else {
+    /* removed will be TRUE if a password was removed */
+}
+```
diff --git a/docs/reference/libsecret/libsecret-docs.sgml b/docs/reference/libsecret/libsecret-docs.sgml
deleted file mode 100644
index 210f21a..0000000
--- a/docs/reference/libsecret/libsecret-docs.sgml
+++ /dev/null
@@ -1,47 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-<!ENTITY version SYSTEM "version.xml">
-]>
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
-	<bookinfo>
-		<title>Libsecret Library Reference Manual</title>
-		<releaseinfo>
-			for libsecret &version;.
-			An online version of this documentation can be found at
-			<ulink role="online-location" url="https://developer.gnome.org/libsecret/unstable/">https://developer.gnome.org/libsecret/unstable/</ulink>.
-		</releaseinfo>
-	</bookinfo>
-
-	<part id="simple">
-		<title>Simple API</title>
-		<xi:include href="xml/secret-password.xml"/>
-		<xi:include href="xml/secret-schema.xml"/>
-	</part>
-
-	<xi:include href="libsecret-examples.sgml"/>
-
-	<part id="complete">
-		<title>Complete API</title>
-		<xi:include href="xml/secret-service.xml"/>
-		<xi:include href="xml/secret-collection.xml"/>
-		<xi:include href="xml/secret-item.xml"/>
-		<xi:include href="xml/secret-retrievable.xml"/>
-		<xi:include href="xml/secret-value.xml"/>
-		<xi:include href="xml/secret-attributes.xml"/>
-		<xi:include href="xml/secret-prompt.xml"/>
-		<xi:include href="xml/secret-error.xml"/>
-		<xi:include href="xml/secret-paths.xml"/>
-		<xi:include href="xml/secret-version.xml"/>
-	</part>
-
-	<xi:include href="libsecret-using.sgml"/>
-
-	<xi:include href="libsecret-tpm2.sgml"/>
-
-	<xi:include href="xml/migrating-libgnome-keyring.xml"/>
-
-	<xi:include href="xml/annotation-glossary.xml">
-		<xi:fallback />
-	</xi:include>
-</book>
diff --git a/docs/reference/libsecret/libsecret-examples.sgml b/docs/reference/libsecret/libsecret-examples.sgml
deleted file mode 100644
index e5be51a..0000000
--- a/docs/reference/libsecret/libsecret-examples.sgml
+++ /dev/null
@@ -1,785 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-<!ENTITY version SYSTEM "version.xml">
-]>
-<part id="examples">
-	<title>Examples</title>
-
-	<chapter id="c-examples">
-		<title>C examples</title>
-
-		<section id="c-schema-example">
-			<title>C example: Define a password schema</title>
-
-			<para>Each stored password has a set of attributes which are later
-			used to lookup the password. The names and types of the attributes
-			are defined in a schema. The schema is usually defined once globally.
-			Here's how to define a schema:</para>
-
-			<informalexample><programlisting language="c"><![CDATA[
-			/* in a header: */
-
-			const SecretSchema * example_get_schema (void) G_GNUC_CONST;
-
-			#define EXAMPLE_SCHEMA  example_get_schema ()
-
-
-			/* in a .c file: */
-
-			const SecretSchema *
-			example_get_schema (void)
-			{
-				static const SecretSchema the_schema = {
-					"org.example.Password", SECRET_SCHEMA_NONE,
-					{
-						{  "number", SECRET_SCHEMA_ATTRIBUTE_INTEGER },
-						{  "string", SECRET_SCHEMA_ATTRIBUTE_STRING },
-						{  "even", SECRET_SCHEMA_ATTRIBUTE_BOOLEAN },
-						{  "NULL", 0 },
-					}
-				};
-				return &the_schema;
-			}
-			]]></programlisting></informalexample>
-
-			<para>See the <link linkend="c-store-example">other examples</link> for how
-			to use the schema.</para>
-		</section>
-
-		<section id="c-store-example">
-			<title>C example: Store a password</title>
-
-			<para>Here's how to store a password in the running secret service,
-			like gnome-keyring or ksecretservice.</para>
-
-			<para>Each stored password has a set of attributes which are later
-			used to lookup the password. The attributes should not contain
-			secrets, as they are not stored in an encrypted fashion.</para>
-
-			<para>These examples use <link linkend="c-schema-example">the example
-			schema</link>.</para>
-
-			<para>This first example stores a password asynchronously, and is
-			appropriate for GUI applications so that the UI does not block.</para>
-
-			<informalexample><programlisting language="c"><![CDATA[
-			static void
-			on_password_stored (GObject *source,
-			                    GAsyncResult *result,
-			                    gpointer unused)
-			{
-				GError *error = NULL;
-
-				secret_password_store_finish (result, &error);
-				if (error != NULL) {
-					/* ... handle the failure here */
-					g_error_free (error);
-				} else {
-					/* ... do something now that the password has been stored */
-				}
-			}
-
-			/*
-			 * The variable argument list is the attributes used to later
-			 * lookup the password. These attributes must conform to the schema.
-			 */
-			secret_password_store (EXAMPLE_SCHEMA, SECRET_COLLECTION_DEFAULT, "The label",
-			                       "the password", NULL, on_password_stored, NULL,
-			                       "number", 8,
-			                       "string", "eight",
-			                       "even", TRUE,
-			                       NULL);
-			]]></programlisting></informalexample>
-
-			<para>This next example stores a password synchronously. The function
-			call will block until the password is stored. So this is appropriate for
-			non GUI applications.</para>
-
-			<informalexample><programlisting language="javascript"><![CDATA[
-			GError *error = NULL;
-
-			/*
-			 * The variable argument list is the attributes used to later
-			 * lookup the password. These attributes must conform to the schema.
-			 */
-			secret_password_store_sync (EXAMPLE_SCHEMA, SECRET_COLLECTION_DEFAULT,
-			                            "The label", "the password", NULL, &error,
-			                            "number", 9,
-			                            "string", "nine",
-			                            "even", FALSE,
-			                            NULL);
-
-			if (error != NULL) {
-				/* ... handle the failure here */
-				g_error_free (error);
-			} else {
-				/* ... do something now that the password has been stored */
-			}
-
-			]]></programlisting></informalexample>
-		</section>
-
-		<section id="c-lookup-example">
-			<title>C example: Lookup a password</title>
-
-			<para>Here's how to lookup a password in the running secret service,
-			like gnome-keyring or ksecretservice.</para>
-
-			<para>Each stored password has a set of attributes which are
-			used to lookup the password. If multiple passwords match the
-			lookup attributes, then the one stored most recently is returned.</para>
-
-			<para>These examples use <link linkend="c-schema-example">the example
-			schema</link>.</para>
-
-			<para>This first example looks up a password asynchronously, and is
-			appropriate for GUI applications so that the UI does not block.</para>
-
-			<informalexample><programlisting language="javascript"><![CDATA[
-			static void
-			on_password_lookup (GObject *source,
-			                    GAsyncResult *result,
-			                    gpointer unused)
-			 {
-				GError *error = NULL;
-
-				gchar *password = secret_password_lookup_finish (result, &error);
-
-				if (error != NULL) {
-					/* ... handle the failure here */
-					g_error_free (error);
-
-				} else if (password == NULL) {
-					/* password will be null, if no matching password found */
-
-				} else {
-					/* ... do something with the password */
-					secret_password_free (password);
-				}
-
-			}
-
-			/*
-			 * The variable argument list is the attributes used to later
-			 * lookup the password. These attributes must conform to the schema.
-			 */
-			secret_password_lookup (EXAMPLE_SCHEMA, NULL, on_password_lookup, NULL,
-			                        "string", "nine",
-			                        "even", FALSE,
-			                        NULL);
-			]]></programlisting></informalexample>
-
-			<para>This next example looks up a password synchronously. The function
-			call will block until the lookup completes. So this is appropriate for
-			non GUI applications.</para>
-
-			<informalexample><programlisting language="c"><![CDATA[
-			GError *error = NULL;
-
-			/* The attributes used to lookup the password should conform to the schema. */
-			gchar *password = secret_password_lookup_sync (EXAMPLE_SCHEMA, NULL, &error,
-			                                               "string", "nine",
-			                                               "even", FALSE,
-			                                               NULL);
-			
-			if (error != NULL) {
-				/* ... handle the failure here */
-				g_error_free (error);
-
-			} else if (password == NULL) {
-				/* password will be null, if no matching password found */
-
-			} else {
-				/* ... do something with the password */
-				secret_password_free (password);
-			}
-			]]></programlisting></informalexample>
-		</section>
-
-		<section id="c-remove-example">
-			<title>C example: Remove a password</title>
-
-			<para>Here's how to remove a password from the running secret service,
-			like gnome-keyring or ksecretservice.</para>
-
-			<para>Each stored password has a set of attributes which are
-			used to find which password to remove. If multiple passwords match the
-			attributes, then the one stored most recently is removed.</para>
-
-			<para>These examples use <link linkend="c-schema-example">the example
-			schema</link>.</para>
-
-			<para>This first example removes a password asynchronously, and is
-			appropriate for GUI applications so that the UI does not block.</para>
-
-			<informalexample><programlisting language="c"><![CDATA[
-			static void
-			on_password_cleared (GObject *source,
-			                     GAsyncResult *result,
-			                     gpointer unused)
-			 {
-				GError *error = NULL;
-
-				gboolean removed = secret_password_clear_finish (result, &error);
-
-				if (error != NULL) {
-					/* ... handle the failure here */
-					g_error_free (error);
-
-				} else {
-					/* removed will be TRUE if a password was removed */
-				}
-			}
-
-			/*
-			 * The variable argument list is the attributes used to later
-			 * lookup the password. These attributes must conform to the schema.
-			 */
-			secret_password_clear (EXAMPLE_SCHEMA, NULL, on_password_cleared, NULL,
-			                       "string", "nine",
-			                       "even", FALSE,
-			                       NULL);
-			]]></programlisting></informalexample>
-
-			<para>This next example looks up a password synchronously. The function
-			call will block until the lookup completes. So this is appropriate for
-			non GUI applications.</para>
-
-			<informalexample><programlisting language="c"><![CDATA[
-			GError *error = NULL;
-
-			/*
-			 * The variable argument list is the attributes used to later
-			 * lookup the password. These attributes must conform to the schema.
-			 */
-			gboolean removed = secret_password_clear_sync (EXAMPLE_SCHEMA, NULL, &error,
-			                                               "string", "nine",
-			                                               "even", FALSE,
-			                                               NULL);
-
-			if (error != NULL) {
-				/* ... handle the failure here */
-				g_error_free (error);
-
-			} else {
-				/* removed will be TRUE if a password was removed */
-			}
-			]]></programlisting></informalexample>
-		</section>
-
-	</chapter>
-
-	<chapter id="js-examples">
-		<title>Javascript examples</title>
-
-		<section id="js-schema-example">
-			<title>Javascript example: Define a password schema</title>
-
-			<para>Each stored password has a set of attributes which are later
-			used to lookup the password. The names and types of the attributes
-			are defined in a schema. The schema is usually defined once globally.
-			Here's how to define a schema:</para>
-
-			<informalexample><programlisting language="javascript"><![CDATA[
-			const Secret = imports.gi.Secret;
-
-			/* This schema is usually defined once globally */
-			const EXAMPLE_SCHEMA = new Secret.Schema.new("org.example.Password",
-				Secret.SchemaFlags.NONE,
-				{
-					"number": Secret.SchemaAttributeType.INTEGER,
-					"string": Secret.SchemaAttributeType.STRING,
-					"even": Secret.SchemaAttributeType.BOOLEAN,
-				}
-			);
-			]]></programlisting></informalexample>
-
-			<para>See the <link linkend="js-store-example">other examples</link> for how
-			to use the schema.</para>
-		</section>
-
-		<section id="js-store-example">
-			<title>Javascript example: Store a password</title>
-
-			<para>Here's how to store a password in the running secret service,
-			like gnome-keyring or ksecretservice.</para>
-
-			<para>Each stored password has a set of attributes which are later
-			used to lookup the password. The attributes should not contain
-			secrets, as they are not stored in an encrypted fashion.</para>
-
-			<para>These examples use <link linkend="js-schema-example">the example
-			schema</link>.</para>
-
-			<para>This first example stores a password asynchronously, and is
-			appropriate for GUI applications so that the UI does not block.</para>
-
-			<informalexample><programlisting language="javascript"><![CDATA[
-			const Secret = imports.gi.Secret;
-
-			function on_password_stored(source, result) {
-				Secret.password_store_finish(result);
-				/* ... do something now that the password has been stored */
-			}
-
-			/*
-			 * The attributes used to later lookup the password. These
-			 * attributes should conform to the schema.
-			 */
-			var attributes = {
-				"number": "8",
-				"string": "eight",
-				"even": "true"
-			};
-
-			Secret.password_store(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
-			                      "The label", "the password", null, on_password_stored);
-			]]></programlisting></informalexample>
-
-			<para>This next example stores a password synchronously. The function
-			call will block until the password is stored. So this is appropriate for
-			non GUI applications.</para>
-
-			<informalexample><programlisting language="javascript"><![CDATA[
-			const Secret = imports.gi.Secret;
-
-			/*
-			 * The attributes used to later lookup the password. These
-			 * attributes should conform to the schema.
-			 */
-			var attributes = {
-				"number": "9",
-				"string": "nine",
-				"even": "false"
-			};
-
-			Secret.password_store_sync(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
-			                           "The label", "the password", null);
-			]]></programlisting></informalexample>
-		</section>
-
-		<section id="js-lookup-example">
-			<title>Javascript example: Lookup a password</title>
-
-			<para>Here's how to lookup a password in the running secret service,
-			like gnome-keyring or ksecretservice.</para>
-
-			<para>Each stored password has a set of attributes which are
-			used to lookup the password. If multiple passwords match the
-			lookup attributes, then the one stored most recently is returned.</para>
-
-			<para>These examples use <link linkend="js-schema-example">the example
-			schema</link>.</para>
-
-			<para>This first example looks up a password asynchronously, and is
-			appropriate for GUI applications so that the UI does not block.</para>
-
-			<informalexample><programlisting language="javascript"><![CDATA[
-			const Secret = imports.gi.Secret;
-
-			function on_password_lookup(source, result) {
-				var password = Secret.password_lookup_finish(result);
-				/* password will be null if no matching password found */
-			}
-
-			/* The attributes used to lookup the password should conform to the schema. */
-			Secret.password_lookup(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
-			                       null, on_password_lookup);
-			]]></programlisting></informalexample>
-
-			<para>This next example looks up a password synchronously. The function
-			call will block until the lookup completes. So this is appropriate for
-			non GUI applications.</para>
-
-			<informalexample><programlisting language="javascript"><![CDATA[
-			const Secret = imports.gi.Secret;
-
-			/* The attributes used to lookup the password should conform to the schema. */
-			var password = Secret.password_lookup_sync(EXAMPLE_SCHEMA,
-			                                           { "number": "8", "even": "true" },
-			                                           null);
-
-			/* password will be null, if no matching password found */ 
-			]]></programlisting></informalexample>
-		</section>
-
-		<section id="js-remove-example">
-			<title>Javascript example: Remove a password</title>
-
-			<para>Here's how to remove a password from the running secret service,
-			like gnome-keyring or ksecretservice.</para>
-
-			<para>Each stored password has a set of attributes which are
-			used to find which password to remove. If multiple passwords match the
-			attributes, then the one stored most recently is removed.</para>
-
-			<para>These examples use <link linkend="js-schema-example">the example
-			schema</link>.</para>
-
-			<para>This first example removes a password asynchronously, and is
-			appropriate for GUI applications so that the UI does not block.</para>
-
-			<informalexample><programlisting language="javascript"><![CDATA[
-			const Secret = imports.gi.Secret;
-
-			function on_password_clear(source, result) {
-				var removed = Secret.password_clear_finish(result);
-				/* removed will be true if the password was removed */
-			}
-
-			/* The attributes used to lookup which password to remove should conform to the schema. */
-			Secret.password_clear(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
-			                      null, on_password_clear);
-			]]></programlisting></informalexample>
-
-			<para>This next example removes a password synchronously. The function
-			call will block until the removal completes. So this is appropriate for
-			non GUI applications.</para>
-
-			<informalexample><programlisting language="javascript"><![CDATA[
-			const Secret = imports.gi.Secret;
-
-			/* The attributes used to lookup which password to remove should conform to the schema. */
-			var removed = Secret.password_clear_sync(EXAMPLE_SCHEMA,
-			                                         { "number": "8", "even": "true" },
-			                                         null);
-
-			/* removed will be true if the password was removed */
-			]]></programlisting></informalexample>
-		</section>
-
-	</chapter>
-
-	<chapter id="py-examples">
-		<title>Python examples</title>
-
-		<section id="py-schema-example">
-			<title>Python example: Define a password schema</title>
-
-			<para>Each stored password has a set of attributes which are later
-			used to lookup the password. The names and types of the attributes
-			are defined in a schema. The schema is usually defined once globally.
-			Here's how to define a schema:</para>
-
-			<informalexample><programlisting language="python"><![CDATA[
-			from gi.repository import Secret
-
-			EXAMPLE_SCHEMA = Secret.Schema.new("org.mock.type.Store",
-				Secret.SchemaFlags.NONE,
-				{
-					"number": Secret.SchemaAttributeType.INTEGER,
-					"string": Secret.SchemaAttributeType.STRING,
-					"even": Secret.SchemaAttributeType.BOOLEAN,
-				}
-			)
-			]]></programlisting></informalexample>
-
-			<para>See the <link linkend="py-store-example">other examples</link> for how
-			to use the schema.</para>
-		</section>
-
-		<section id="py-store-example">
-			<title>Python example: Store a password</title>
-
-			<para>Here's how to store a password in the running secret service,
-			like gnome-keyring or ksecretservice.</para>
-
-			<para>Each stored password has a set of attributes which are later
-			used to lookup the password. The attributes should not contain
-			secrets, as they are not stored in an encrypted fashion.</para>
-
-			<para>These examples use <link linkend="py-schema-example">the example
-			schema</link>.</para>
-
-			<para>This first example stores a password asynchronously, and is
-			appropriate for GUI applications so that the UI does not block.</para>
-
-			<informalexample><programlisting language="python"><![CDATA[
-			from gi.repository import Secret
-
-			def on_password_stored(source, result, unused):
-				Secret.password_store_finish(result)
-				# ... do something now that the password has been stored
-
-			# The attributes used to later lookup the password. These
-			# attributes should conform to the schema.
-			attributes = {
-				"number": "8",
-				"string": "eight",
-				"even": "true"
-			}
-
-			Secret.password_store(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
-			                      "The label", "the password", None, on_password_stored)
-			]]></programlisting></informalexample>
-
-			<para>This next example stores a password synchronously. The function
-			call will block until the password is stored. So this is appropriate for
-			non GUI applications.</para>
-
-			<informalexample><programlisting language="python"><![CDATA[
-			from gi.repository import Secret
-
-			# The attributes used to later lookup the password. These
-			# attributes should conform to the schema.
-			attributes = {
-				"number": "8",
-				"string": "eight",
-				"even": "true"
-			}
-
-			Secret.password_store_sync(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
-			                           "The label", "the password", None)
-			]]></programlisting></informalexample>
-		</section>
-
-		<section id="py-lookup-example">
-			<title>Python example: Lookup a password</title>
-
-			<para>Here's how to lookup a password in the running secret service,
-			like gnome-keyring or ksecretservice.</para>
-
-			<para>Each stored password has a set of attributes which are
-			used to lookup the password. If multiple passwords match the
-			lookup attributes, then the one stored most recently is returned.</para>
-
-			<para>These examples use <link linkend="py-schema-example">the example
-			schema</link>.</para>
-
-			<para>This first example looks up a password asynchronously, and is
-			appropriate for GUI applications so that the UI does not block.</para>
-
-			<informalexample><programlisting language="python"><![CDATA[
-			from gi.repository import Secret
-
-			def on_password_lookup(source, result, unused):
-				password = Secret.password_lookup_finish(result)
-				# password will be null, if no matching password found
-
-			Secret.password_lookup(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
-			                       None, on_password_lookup)
-			]]></programlisting></informalexample>
-
-			<para>This next example looks up a password synchronously. The function
-			call will block until the lookup completes. So this is appropriate for
-			non GUI applications.</para>
-
-			<informalexample><programlisting language="python"><![CDATA[
-			from gi.repository import Secret
-
-			password = Secret.password_lookup_sync(EXAMPLE_SCHEMA, { "number": "8", "even": "true" }, None)
-			# password will be null, if no matching password found
-			]]></programlisting></informalexample>
-		</section>
-
-		<section id="py-remove-example">
-			<title>Python example: Remove a password</title>
-
-			<para>Here's how to remove a password from the running secret service,
-			like gnome-keyring or ksecretservice.</para>
-
-			<para>Each stored password has a set of attributes which are
-			used to find which password to remove. If multiple passwords match the
-			attributes, then the one stored most recently is removed.</para>
-
-			<para>These examples use <link linkend="py-schema-example">the example
-			schema</link>.</para>
-
-			<para>This first example removes a password asynchronously, and is
-			appropriate for GUI applications so that the UI does not block.</para>
-
-			<informalexample><programlisting language="python"><![CDATA[
-			from gi.repository import Secret
-
-			def on_password_clear(source, result, unused):
-				removed = Secret.password_clear_finish(result)
-				# removed will be true if the password was removed
-
-			Secret.password_clear(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
-                                              None, on_password_clear)
-			]]></programlisting></informalexample>
-
-			<para>This next example removes a password synchronously. The function
-			call will block until the removal completes. So this is appropriate for
-			non GUI applications.</para>
-
-			<informalexample><programlisting language="python"><![CDATA[
-			from gi.repository import Secret
-
-			removed = Secret.password_clear_sync(EXAMPLE_SCHEMA, { "number": "8", "even": "true" }, None)
-			# removed will be true if the password was removed
-			]]></programlisting></informalexample>
-		</section>
-
-	</chapter>
-
-	<chapter id="vala-examples">
-		<title>Vala examples</title>
-
-		<section id="vala-schema-example">
-			<title>Vala example: Define a password schema</title>
-
-			<para>Each stored password has a set of attributes which are later
-			used to lookup the password. The names and types of the attributes
-			are defined in a schema. The schema is usually defined once globally.
-			Here's how to define a schema:</para>
-
-			<informalexample><programlisting language="vala"><![CDATA[
-			var example = new Secret.Schema ("org.example.Password", Secret.SchemaFlags.NONE,
-			                                 "number", Secret.SchemaAttributeType.INTEGER,
-			                                 "string", Secret.SchemaAttributeType.STRING,
-			                                 "even", Secret.SchemaAttributeType.BOOLEAN);
-			]]></programlisting></informalexample>
-
-			<para>See the <link linkend="vala-store-example">other examples</link> for how
-			to use the schema.</para>
-		</section>
-
-		<section id="vala-store-example">
-			<title>Vala example: Store a password</title>
-
-			<para>Here's how to store a password in the running secret service,
-			like gnome-keyring or ksecretservice.</para>
-
-			<para>Each stored password has a set of attributes which are later
-			used to lookup the password. The attributes should not contain
-			secrets, as they are not stored in an encrypted fashion.</para>
-
-			<para>These examples use <link linkend="vala-schema-example">the example
-			schema</link>.</para>
-
-			<para>This first example stores a password asynchronously, and is
-			appropriate for GUI applications so that the UI does not block.</para>
-
-			<informalexample><programlisting language="vala"><![CDATA[
-			var attributes = new GLib.HashTable<string,string> ();
-			attributes["number"] = "8";
-			attributes["string"] = "eight";
-			attributes["even"] = "true";
-
-			Secret.password_storev.begin (example_schema, attributes, Secret.COLLECTION_DEFAULT,
-			                              "The label", "the password", null, (obj, async_res) => {
-				bool res = Secret.password_store.end (async_res);
-				/* ... do something now that the password has been stored */
-			});
-			]]></programlisting></informalexample>
-
-			<para>If you are already inside of an async function, you can also
-			use the yield keyword:</para>
-
-			<informalexample><programlisting language="vala"><![CDATA[
-			var attributes = new GLib.HashTable<string,string> ();
-			attributes["number"] = "8";
-			attributes["string"] = "eight";
-			attributes["even"] = "true";
-
-			bool res = yield Secret.password_storev (example_schema, attributes,
-			                                         Secret.COLLECTION_DEFAULT, "The label",
-			                                         "the password", null);
-			]]></programlisting></informalexample>
-
-			<para>If you would like to avoid creating a hash table for the
-			attributes you can just use the variadic version:</para>
-
-			<informalexample><programlisting language="vala"><![CDATA[
-			bool res = yield Secret.password_store (example_schema, Secret.COLLECTION_DEFAULT, "The label",
-			                                        "the password", null, "number", 8, "string", "eight",
-			                                        "even", true);
-			]]></programlisting></informalexample>
-
-			<para>This next example stores a password synchronously. The function
-			call will block until the password is stored. So this is appropriate for
-			non GUI applications.</para>
-
-			<informalexample><programlisting language="vala"><![CDATA[
-			Secret.password_store_sync (example_schema, attributes, Secret.COLLECTION_DEFAULT,
-			                            "The label", "the password", null,
-			                            "number", 9, "string", "nine", "even", false);
-			]]></programlisting></informalexample>
-		</section>
-
-		<section id="vala-lookup-example">
-			<title>Vala example: Lookup a password</title>
-
-			<para>Here's how to lookup a password in the running secret service,
-			like gnome-keyring or ksecretservice.</para>
-
-			<para>Each stored password has a set of attributes which are
-			used to lookup the password. If multiple passwords match the
-			lookup attributes, then the one stored most recently is returned.</para>
-
-			<para>These examples use <link linkend="vala-schema-example">the example
-			schema</link>.</para>
-
-			<para>This first example looks up a password asynchronously, and is
-			appropriate for GUI applications so that the UI does not block.</para>
-
-			<informalexample><programlisting language="vala"><![CDATA[
-			var attributes = new GLib.HashTable<string,string> ();
-			attributes["number"] = "8";
-			attributes["string"] = "eight";
-			attributes["even"] = "true";
-
-			Secret.password_lookupv.begin (example_schema, attributes, null, (obj, async_res) => {
-				string password = Secret.password_lookup.end (async_res);
-			});
-			]]></programlisting></informalexample>
-
-			<para>This next example looks up a password synchronously. The function
-			call will block until the lookup completes. So this is appropriate for
-			non GUI applications.</para>
-
-			<informalexample><programlisting language="vala"><![CDATA[
-			string password = Secret.password_lookup_sync (example_schema, attributes, null,
-			                                               "number", 9, "string", "nine", "even", false);
-			/* password will be null, if no matching password found */
-			]]></programlisting></informalexample>
-		</section>
-
-		<section id="vala-remove-example">
-			<title>Vala example: Remove a password</title>
-
-			<para>Here's how to remove a password from the running secret service,
-			like gnome-keyring or ksecretservice.</para>
-
-			<para>Each stored password has a set of attributes which are
-			used to find which password to remove. If multiple passwords match the
-			attributes, then the one stored most recently is removed.</para>
-
-			<para>These examples use <link linkend="vala-schema-example">the example
-			schema</link>.</para>
-
-			<para>This first example removes a password asynchronously, and is
-			appropriate for GUI applications so that the UI does not block.</para>
-
-			<informalexample><programlisting language="vala"><![CDATA[
-			var attributes = new GLib.HashTable<string,string> ();
-			attributes["number"] = "8";
-			attributes["string"] = "eight";
-			attributes["even"] = "true";
-
-			Secret.password_clearv.begin (example_schema, attributes, null, (obj, async_res) => {
-				bool removed = Secret.password_clearv.end (async_res);
-			});
-			]]></programlisting></informalexample>
-
-			<para>This next example removes a password synchronously. The function
-			call will block until the removal completes. So this is appropriate for
-			non GUI applications.</para>
-
-			<informalexample><programlisting language="vala"><![CDATA[
-			var attributes = new GLib.HashTable<string,string> ();
-			attributes["number"] = "8";
-			attributes["string"] = "eight";
-			attributes["even"] = "true";
-
-			bool removed = Secret.password_clear_sync (example_schema, null,
-			                                           "number", 8, "string", "eight", "even", true);
-			/* removed will be true if the password was removed */
-			]]></programlisting></informalexample>
-		</section>
-
-	</chapter>
-
-</part>
diff --git a/docs/reference/libsecret/libsecret-js-examples.md b/docs/reference/libsecret/libsecret-js-examples.md
new file mode 100644
index 0000000..ad98679
--- /dev/null
+++ b/docs/reference/libsecret/libsecret-js-examples.md
@@ -0,0 +1,170 @@
+Title: Javascript Examples
+Slug: libsecret-js-example
+
+# Javascript examples
+
+## Define a password schema
+
+Each stored password has a set of attributes which are later
+used to lookup the password. The names and types of the attributes
+are defined in a schema. The schema is usually defined once globally.
+Here's how to define a schema:
+
+```js
+const Secret = imports.gi.Secret;
+
+/* This schema is usually defined once globally */
+const EXAMPLE_SCHEMA = new Secret.Schema.new("org.example.Password",
+    Secret.SchemaFlags.NONE,
+    {
+        "number": Secret.SchemaAttributeType.INTEGER,
+        "string": Secret.SchemaAttributeType.STRING,
+        "even": Secret.SchemaAttributeType.BOOLEAN,
+    }
+);
+```
+
+See the [other examples](#store-a-password) for how
+to use the schema.
+
+## Store a password
+
+Here's how to store a password in the running secret service,
+like gnome-keyring or ksecretservice.
+
+Each stored password has a set of attributes which are later
+used to lookup the password. The attributes should not contain
+secrets, as they are not stored in an encrypted fashion.
+
+These examples use the [example schema](#define-a-password-schema).
+
+This first example stores a password asynchronously, and is
+appropriate for GUI applications so that the UI does not block.
+
+```js
+const Secret = imports.gi.Secret;
+
+function on_password_stored(source, result) {
+    Secret.password_store_finish(result);
+    /* ... do something now that the password has been stored */
+}
+
+/*
+ * The attributes used to later lookup the password. These
+ * attributes should conform to the schema.
+ */
+var attributes = {
+    "number": "8",
+    "string": "eight",
+    "even": "true"
+};
+
+Secret.password_store(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
+                      "The label", "the password", null, on_password_stored);
+```
+
+This next example stores a password synchronously. The function
+call will block until the password is stored. So this is appropriate for
+non GUI applications.
+
+```js
+const Secret = imports.gi.Secret;
+
+/*
+ * The attributes used to later lookup the password. These
+ * attributes should conform to the schema.
+ */
+var attributes = {
+    "number": "9",
+    "string": "nine",
+    "even": "false"
+};
+
+Secret.password_store_sync(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
+                           "The label", "the password", null);
+```
+
+## Lookup a password
+
+Here's how to lookup a password in the running secret service,
+like gnome-keyring or ksecretservice.
+
+Each stored password has a set of attributes which are
+used to lookup the password. If multiple passwords match the
+lookup attributes, then the one stored most recently is returned.
+
+These examples use the [example schema](#define-a-password-schema).
+
+This first example looks up a password asynchronously, and is
+appropriate for GUI applications so that the UI does not block.
+
+```js
+const Secret = imports.gi.Secret;
+
+function on_password_lookup(source, result) {
+    var password = Secret.password_lookup_finish(result);
+    /* password will be null if no matching password found */
+}
+
+/* The attributes used to lookup the password should conform to the schema. */
+Secret.password_lookup(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
+                       null, on_password_lookup);
+```
+
+This next example looks up a password synchronously. The function
+call will block until the lookup completes. So this is appropriate for
+non GUI applications.
+
+```js
+const Secret = imports.gi.Secret;
+
+/* The attributes used to lookup the password should conform to the schema. */
+var password = Secret.password_lookup_sync(EXAMPLE_SCHEMA,
+                                           { "number": "8", "even": "true" },
+                                           null);
+
+/* password will be null, if no matching password found */ 
+```
+
+
+## Remove a password
+
+Here's how to remove a password from the running secret service,
+like gnome-keyring or ksecretservice.
+
+Each stored password has a set of attributes which are
+used to find which password to remove. If multiple passwords match the
+attributes, then the one stored most recently is removed.
+
+These examples use the [example schema](#define-a-password-schema).
+
+This first example removes a password asynchronously, and is
+appropriate for GUI applications so that the UI does not block.
+
+```js
+const Secret = imports.gi.Secret;
+
+function on_password_clear(source, result) {
+    var removed = Secret.password_clear_finish(result);
+    /* removed will be true if the password was removed */
+}
+
+/* The attributes used to lookup which password to remove should conform to the schema. */
+Secret.password_clear(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
+                      null, on_password_clear);
+```
+
+This next example removes a password synchronously. The function
+call will block until the removal completes. So this is appropriate for
+non GUI applications.
+
+```js
+const Secret = imports.gi.Secret;
+
+/* The attributes used to lookup which password to remove should conform to the schema. */
+var removed = Secret.password_clear_sync(EXAMPLE_SCHEMA,
+                                         { "number": "8", "even": "true" },
+                                         null);
+
+/* removed will be true if the password was removed */
+```
diff --git a/docs/reference/libsecret/libsecret-overrides.txt b/docs/reference/libsecret/libsecret-overrides.txt
deleted file mode 100644
index 13f485f..0000000
--- a/docs/reference/libsecret/libsecret-overrides.txt
+++ /dev/null
@@ -1,2 +0,0 @@
-# These are manually-edited to override or add declarations to those scanned
-# from the header files.
diff --git a/docs/reference/libsecret/libsecret-python-examples.md b/docs/reference/libsecret/libsecret-python-examples.md
new file mode 100644
index 0000000..b9c0b7d
--- /dev/null
+++ b/docs/reference/libsecret/libsecret-python-examples.md
@@ -0,0 +1,152 @@
+Title: Python Examples
+Slug: libsecret-python-example
+
+# Python examples
+
+## Define a password schema
+
+Each stored password has a set of attributes which are later
+used to lookup the password. The names and types of the attributes
+are defined in a schema. The schema is usually defined once globally.
+Here's how to define a schema:
+
+```python
+from gi.repository import Secret
+
+EXAMPLE_SCHEMA = Secret.Schema.new("org.mock.type.Store",
+    Secret.SchemaFlags.NONE,
+    {
+        "number": Secret.SchemaAttributeType.INTEGER,
+        "string": Secret.SchemaAttributeType.STRING,
+        "even": Secret.SchemaAttributeType.BOOLEAN,
+    }
+)
+```
+
+See the [other examples](#store-a-password) for how
+to use the schema.
+
+
+## Store a password
+
+Here's how to store a password in the running secret service,
+like gnome-keyring or ksecretservice.
+
+Each stored password has a set of attributes which are later
+used to lookup the password. The attributes should not contain
+secrets, as they are not stored in an encrypted fashion.
+
+These examples use the [example schema](#define-a-password-schema).
+
+This first example stores a password asynchronously, and is
+appropriate for GUI applications so that the UI does not block.
+
+```python
+from gi.repository import Secret
+
+def on_password_stored(source, result, unused):
+    Secret.password_store_finish(result)
+    # ... do something now that the password has been stored
+
+# The attributes used to later lookup the password. These
+# attributes should conform to the schema.
+attributes = {
+    "number": "8",
+    "string": "eight",
+    "even": "true"
+}
+
+Secret.password_store(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
+                      "The label", "the password", None, on_password_stored)
+```
+
+This next example stores a password synchronously. The function
+call will block until the password is stored. So this is appropriate for
+non GUI applications.
+
+```python
+from gi.repository import Secret
+
+# The attributes used to later lookup the password. These
+# attributes should conform to the schema.
+attributes = {
+    "number": "8",
+    "string": "eight",
+    "even": "true"
+}
+
+Secret.password_store_sync(EXAMPLE_SCHEMA, attributes, Secret.COLLECTION_DEFAULT,
+                           "The label", "the password", None)
+```
+
+## Lookup a password
+
+Here's how to lookup a password in the running secret service,
+like gnome-keyring or ksecretservice.
+
+Each stored password has a set of attributes which are
+used to lookup the password. If multiple passwords match the
+lookup attributes, then the one stored most recently is returned.
+
+These examples use the [example schema](#define-a-password-schema).
+
+This first example looks up a password asynchronously, and is
+appropriate for GUI applications so that the UI does not block.
+
+```python
+from gi.repository import Secret
+
+def on_password_lookup(source, result, unused):
+    password = Secret.password_lookup_finish(result)
+    # password will be null, if no matching password found
+
+Secret.password_lookup(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
+                       None, on_password_lookup)
+```
+
+This next example looks up a password synchronously. The function
+call will block until the lookup completes. So this is appropriate for
+non GUI applications.
+
+```python
+from gi.repository import Secret
+
+password = Secret.password_lookup_sync(EXAMPLE_SCHEMA, { "number": "8", "even": "true" }, None)
+# password will be null, if no matching password found
+```
+
+## Remove a password
+
+Here's how to remove a password from the running secret service,
+like gnome-keyring or ksecretservice.
+
+Each stored password has a set of attributes which are
+used to find which password to remove. If multiple passwords match the
+attributes, then the one stored most recently is removed.
+
+These examples use the [example schema](#define-a-password-schema).
+
+This first example removes a password asynchronously, and is
+appropriate for GUI applications so that the UI does not block.
+
+```python
+from gi.repository import Secret
+
+def on_password_clear(source, result, unused):
+    removed = Secret.password_clear_finish(result)
+    # removed will be true if the password was removed
+
+Secret.password_clear(EXAMPLE_SCHEMA, { "number": "8", "even": "true" },
+                      None, on_password_clear)
+```
+
+This next example removes a password synchronously. The function
+call will block until the removal completes. So this is appropriate for
+non GUI applications.
+
+```python
+from gi.repository import Secret
+
+removed = Secret.password_clear_sync(EXAMPLE_SCHEMA, { "number": "8", "even": "true" }, None)
+# removed will be true if the password was removed
+```
diff --git a/docs/reference/libsecret/libsecret-sections.txt b/docs/reference/libsecret/libsecret-sections.txt
deleted file mode 100644
index 1b225fe..0000000
--- a/docs/reference/libsecret/libsecret-sections.txt
+++ /dev/null
@@ -1,389 +0,0 @@
-<SECTION>
-<FILE>secret-collection</FILE>
-<INCLUDE>libsecret/secret.h</INCLUDE>
-SecretCollection
-SecretCollectionClass
-SecretCollectionFlags
-secret_collection_for_alias
-secret_collection_for_alias_finish
-secret_collection_for_alias_sync
-secret_collection_load_items
-secret_collection_load_items_finish
-secret_collection_load_items_sync
-secret_collection_create
-secret_collection_create_finish
-secret_collection_create_sync
-secret_collection_search
-secret_collection_search_finish
-secret_collection_search_sync
-secret_collection_delete
-secret_collection_delete_finish
-secret_collection_delete_sync
-secret_collection_get_created
-secret_collection_get_service
-secret_collection_get_flags
-secret_collection_get_items
-secret_collection_get_label
-secret_collection_set_label
-secret_collection_set_label_finish
-secret_collection_set_label_sync
-secret_collection_get_locked
-secret_collection_get_modified
-secret_collection_refresh
-<SUBSECTION Standard>
-SECRET_COLLECTION
-SECRET_COLLECTION_CLASS
-SECRET_COLLECTION_GET_CLASS
-SECRET_IS_COLLECTION
-SECRET_IS_COLLECTION_CLASS
-SECRET_TYPE_COLLECTION
-SECRET_TYPE_COLLECTION_FLAGS
-SecretCollectionPrivate
-secret_collection_get_type
-secret_collection_flags_get_type
-SecretCollectionCreateFlags
-SECRET_TYPE_COLLECTION_CREATE_FLAGS
-secret_collection_create_flags_get_type
-</SECTION>
-
-<SECTION>
-<FILE>secret-item</FILE>
-<INCLUDE>libsecret/secret.h</INCLUDE>
-SecretItem
-SecretItemClass
-SecretItemFlags
-SecretItemCreateFlags
-secret_item_create
-secret_item_create_finish
-secret_item_create_sync
-secret_item_delete
-secret_item_delete_finish
-secret_item_delete_sync
-secret_item_get_schema_name
-secret_item_get_attributes
-secret_item_set_attributes
-secret_item_set_attributes_finish
-secret_item_set_attributes_sync
-secret_item_get_created
-secret_item_get_label
-secret_item_set_label
-secret_item_set_label_finish
-secret_item_set_label_sync
-secret_item_get_flags
-secret_item_get_locked
-secret_item_get_modified
-secret_item_get_service
-secret_item_get_secret
-secret_item_load_secret
-secret_item_load_secret_finish
-secret_item_load_secret_sync
-secret_item_load_secrets
-secret_item_load_secrets_finish
-secret_item_load_secrets_sync
-secret_item_set_secret
-secret_item_set_secret_finish
-secret_item_set_secret_sync
-secret_item_refresh
-<SUBSECTION Standard>
-SECRET_IS_ITEM
-SECRET_IS_ITEM_CLASS
-SECRET_ITEM
-SECRET_ITEM_CLASS
-SECRET_ITEM_GET_CLASS
-SECRET_TYPE_ITEM
-SECRET_TYPE_ITEM_FLAGS
-SecretItemPrivate
-secret_item_get_type
-secret_item_flags_get_type
-SECRET_TYPE_ITEM_CREATE_FLAGS
-secret_item_create_flags_get_type
-</SECTION>
-
-<SECTION>
-<FILE>secret-error</FILE>
-<INCLUDE>libsecret/secret.h</INCLUDE>
-SECRET_ERROR
-SecretError
-<SUBSECTION Standard>
-SECRET_TYPE_ERROR
-secret_error_get_quark
-secret_error_get_type
-</SECTION>
-
-<SECTION>
-<FILE>secret-password</FILE>
-<INCLUDE>libsecret/secret.h</INCLUDE>
-SECRET_COLLECTION_DEFAULT
-SECRET_COLLECTION_SESSION
-secret_password_store
-secret_password_storev
-secret_password_store_finish
-secret_password_store_sync
-secret_password_storev_sync
-secret_password_store_binary
-secret_password_store_binary_sync
-secret_password_storev_binary
-secret_password_storev_binary_sync
-secret_password_lookup
-secret_password_lookupv
-secret_password_lookup_finish
-secret_password_lookup_nonpageable_finish
-secret_password_lookup_sync
-secret_password_lookup_nonpageable_sync
-secret_password_lookupv_sync
-secret_password_lookupv_nonpageable_sync
-secret_password_lookup_binary_finish
-secret_password_lookup_binary_sync
-secret_password_lookupv_binary_sync
-secret_password_clear
-secret_password_clearv
-secret_password_clear_finish
-secret_password_clear_sync
-secret_password_clearv_sync
-secret_password_search
-secret_password_search_finish
-secret_password_search_sync
-secret_password_searchv
-secret_password_searchv_sync
-secret_password_wipe
-secret_password_free
-</SECTION>
-
-<SECTION>
-<FILE>secret-retrievable</FILE>
-<INCLUDE>libsecret/secret.h</INCLUDE>
-SECRET_TYPE_RETRIEVABLE
-SecretRetrievable
-SecretRetrievableInterface
-secret_retrievable_get_attributes
-secret_retrievable_get_created
-secret_retrievable_get_label
-secret_retrievable_get_modified
-secret_retrievable_retrieve_secret
-secret_retrievable_retrieve_secret_finish
-secret_retrievable_retrieve_secret_sync
-</SECTION>
-
-<SECTION>
-<FILE>secret-schema</FILE>
-<INCLUDE>libsecret/secret.h</INCLUDE>
-SECRET_SCHEMA_NOTE
-SECRET_SCHEMA_COMPAT_NETWORK
-SecretSchema
-SecretSchemaFlags
-SecretSchemaAttribute
-SecretSchemaAttributeType
-secret_schema_new
-secret_schema_newv
-secret_schema_ref
-secret_schema_unref
-SecretSchemaType
-secret_get_schema
-<SUBSECTION Standard>
-secret_schema_get_type
-secret_schema_attribute_get_type
-secret_schema_attribute_type_get_type
-secret_schema_flags_get_type
-SECRET_TYPE_SCHEMA_FLAGS
-SECRET_TYPE_SCHEMA_ATTRIBUTE_TYPE
-</SECTION>
-
-<SECTION>
-<FILE>secret-prompt</FILE>
-<INCLUDE>libsecret/secret.h</INCLUDE>
-SecretPrompt
-SecretPromptClass
-secret_prompt_perform
-secret_prompt_perform_finish
-secret_prompt_perform_sync
-secret_prompt_run
-<SUBSECTION Standard>
-SECRET_IS_PROMPT
-SECRET_IS_PROMPT_CLASS
-SECRET_PROMPT
-SECRET_PROMPT_CLASS
-SECRET_PROMPT_GET_CLASS
-SECRET_TYPE_PROMPT
-SecretPromptPrivate
-secret_prompt_get_type
-</SECTION>
-
-<SECTION>
-<FILE>secret-service</FILE>
-<INCLUDE>libsecret/secret.h</INCLUDE>
-SecretService
-SecretServiceClass
-SecretServiceFlags
-secret_service_get
-secret_service_get_sync
-secret_service_get_finish
-secret_service_disconnect
-secret_service_open
-secret_service_open_finish
-secret_service_open_sync
-secret_service_get_collections
-secret_service_get_flags
-secret_service_get_session_algorithms
-secret_service_ensure_session
-secret_service_ensure_session_finish
-secret_service_ensure_session_sync
-secret_service_load_collections
-secret_service_load_collections_finish
-secret_service_load_collections_sync
-SecretSearchFlags
-secret_service_search
-secret_service_search_finish
-secret_service_search_sync
-secret_service_lock
-secret_service_lock_finish
-secret_service_lock_sync
-secret_service_unlock
-secret_service_unlock_finish
-secret_service_unlock_sync
-secret_service_store
-secret_service_store_finish
-secret_service_store_sync
-secret_service_lookup
-secret_service_lookup_finish
-secret_service_lookup_sync
-secret_service_clear
-secret_service_clear_finish
-secret_service_clear_sync
-secret_service_prompt
-secret_service_prompt_finish
-secret_service_prompt_sync
-secret_service_set_alias
-secret_service_set_alias_finish
-secret_service_set_alias_sync
-secret_service_get_collection_gtype
-secret_service_get_item_gtype
-<SUBSECTION Standard>
-SECRET_IS_SERVICE
-SECRET_IS_SERVICE_CLASS
-SECRET_SERVICE
-SECRET_SERVICE_CLASS
-SECRET_SERVICE_GET_CLASS
-SECRET_TYPE_SEARCH_FLAGS
-SECRET_TYPE_SERVICE
-SECRET_TYPE_SERVICE_FLAGS
-SecretServicePrivate
-secret_search_flags_get_type
-secret_service_flags_get_type
-secret_service_get_type
-</SECTION>
-
-<SECTION>
-<FILE>secret-paths</FILE>
-<INCLUDE>libsecret/secret.h</INCLUDE>
-secret_collection_new_for_dbus_path
-secret_collection_new_for_dbus_path_finish
-secret_collection_new_for_dbus_path_sync
-secret_item_new_for_dbus_path
-secret_item_new_for_dbus_path_finish
-secret_item_new_for_dbus_path_sync
-secret_service_get_session_dbus_path
-secret_service_search_for_dbus_paths
-secret_service_search_for_dbus_paths_finish
-secret_service_search_for_dbus_paths_sync
-secret_collection_search_for_dbus_paths
-secret_collection_search_for_dbus_paths_finish
-secret_collection_search_for_dbus_paths_sync
-secret_service_get_secrets_for_dbus_paths
-secret_service_get_secrets_for_dbus_paths_finish
-secret_service_get_secrets_for_dbus_paths_sync
-secret_service_get_secret_for_dbus_path
-secret_service_get_secret_for_dbus_path_finish
-secret_service_get_secret_for_dbus_path_sync
-secret_service_lock_dbus_paths
-secret_service_lock_dbus_paths_finish
-secret_service_lock_dbus_paths_sync
-secret_service_unlock_dbus_paths
-secret_service_unlock_dbus_paths_finish
-secret_service_unlock_dbus_paths_sync
-secret_service_prompt_at_dbus_path
-secret_service_prompt_at_dbus_path_finish
-secret_service_prompt_at_dbus_path_sync
-secret_service_create_collection_dbus_path
-secret_service_create_collection_dbus_path_finish
-secret_service_create_collection_dbus_path_sync
-secret_service_create_item_dbus_path
-secret_service_create_item_dbus_path_finish
-secret_service_create_item_dbus_path_sync
-secret_service_delete_item_dbus_path
-secret_service_delete_item_dbus_path_finish
-secret_service_delete_item_dbus_path_sync
-secret_service_read_alias_dbus_path
-secret_service_read_alias_dbus_path_finish
-secret_service_read_alias_dbus_path_sync
-secret_service_set_alias_to_dbus_path
-secret_service_set_alias_to_dbus_path_finish
-secret_service_set_alias_to_dbus_path_sync
-secret_service_encode_dbus_secret
-secret_service_decode_dbus_secret
-</SECTION>
-
-<SECTION>
-<FILE>secret-value</FILE>
-<INCLUDE>libsecret/secret.h</INCLUDE>
-SecretValue
-secret_value_new
-secret_value_new_full
-secret_value_get
-secret_value_get_text
-secret_value_get_content_type
-secret_value_ref
-secret_value_unref
-secret_value_unref_to_password
-<SUBSECTION Standard>
-SECRET_TYPE_VALUE
-secret_value_get_type
-</SECTION>
-
-<SECTION>
-<FILE>secret-attributes</FILE>
-<INCLUDE>libsecret/secret.h</INCLUDE>
-secret_attributes_build
-secret_attributes_buildv
-</SECTION>
-
-<SECTION>
-<FILE>SecretGenService</FILE>
-</SECTION>
-
-<SECTION>
-<FILE>SecretGenCollection</FILE>
-</SECTION>
-
-<SECTION>
-<FILE>SecretGenItem</FILE>
-</SECTION>
-
-<SECTION>
-<FILE>SecretGenSession</FILE>
-</SECTION>
-
-<SECTION>
-<FILE>SecretGenPrompt</FILE>
-</SECTION>
-
-<SECTION>
-<FILE>secret-backend</FILE>
-SECRET_BACKEND_EXTENSION_POINT_NAME
-SECRET_TYPE_BACKEND
-SECRET_TYPE_BACKEND_FLAGS
-SECRET_TYPE_SCHEMA_TYPE
-SecretBackend
-SecretBackendFlags
-SecretBackendInterface
-secret_backend_flags_get_type
-secret_backend_get
-secret_backend_get_finish
-</SECTION>
-
-<SECTION>
-<FILE>secret-version</FILE>
-SECRET_CHECK_VERSION
-SECRET_MAJOR_VERSION
-SECRET_MICRO_VERSION
-SECRET_MINOR_VERSION
-</SECTION>
diff --git a/docs/reference/libsecret/libsecret-simple-api.md b/docs/reference/libsecret/libsecret-simple-api.md
new file mode 100644
index 0000000..b6fda5e
--- /dev/null
+++ b/docs/reference/libsecret/libsecret-simple-api.md
@@ -0,0 +1,95 @@
+Title: Simple API
+Slug: libsecret-simple-api
+
+# Simple API
+
+## SecretPassword
+
+Simple password storage and lookup.
+
+This is a simple API for storing passwords and retrieving passwords in the
+Secret Service.
+
+Each password is associated with a set of attributes. Attribute values can be
+either strings, integers or booleans.
+
+The names and types of allowed attributes for a given password are defined with
+a schema. Certain schemas are predefined. Additional schemas can be defined via
+the [struct@Schema] structure.
+
+Each of the functions accept a variable list of attributes names and their
+values. Include a `NULL` to terminate the list of attributes.
+
+## SecretSchema
+
+Represents a set of attributes that are stored with an item. These schemas are
+used for interoperability between various services storing the same types of
+items.
+
+Each schema has a name like `org.gnome.keyring.NetworkPassword`, and defines a
+set of attributes, and types (string, integer, boolean) for those attributes.
+
+Attributes are stored as strings in the Secret Service, and the attribute types
+simply define standard ways to store integer and boolean values as strings.
+Attributes are represented in libsecret via a [struct@GLib.HashTable] with
+string keys and values. Even for values that defined as an integer or boolean in
+the schema, the attribute values in the [struct@GLib.HashTable] are strings.
+Boolean values are stored as the strings 'true' and 'false'. Integer values are
+stored in decimal, with a preceding negative sign for negative integers.
+
+Schemas are handled entirely on the client side by this library. The name of the
+schema is automatically stored as an attribute on the item.
+
+Normally when looking up passwords only those with matching schema names are
+returned. If the schema @flags contain the `SECRET_SCHEMA_DONT_MATCH_NAME` flag,
+then lookups will not check that the schema name matches that on the item, only
+the schema's attributes are matched. This is useful when you are looking up
+items that are not stored by the libsecret library. Other libraries such as
+libgnome-keyring don't store the schema name.
+
+Additional schemas can be defined via the %SecretSchema structure like this:
+
+```c
+// in a header:
+
+const SecretSchema * example_get_schema (void) G_GNUC_CONST;
+
+#define EXAMPLE_SCHEMA  example_get_schema ()
+
+
+// in a .c file
+
+const SecretSchema *
+example_get_schema (void)
+{
+    static const SecretSchema the_schema = {
+        "org.example.Password", SECRET_SCHEMA_NONE,
+        {
+            {  "number", SECRET_SCHEMA_ATTRIBUTE_INTEGER },
+            {  "string", SECRET_SCHEMA_ATTRIBUTE_STRING },
+            {  "even", SECRET_SCHEMA_ATTRIBUTE_BOOLEAN },
+            {  NULL, 0 },
+        }
+    };
+    return &the_schema;
+}
+```
+
+## Secret Attributes
+
+Each item has a set of attributes, which are used to locate the item later.
+These are not stored or transferred in a secure manner. Each attribute has a
+string name and a string value. These attributes are represented by a
+[struct@GLib.HashTable] with string keys and values.
+
+Use [func@attributes_build] to simply build up a set of attributes.
+
+## DBus Path Related Functions
+
+Secret Service functions which operate on DBus object paths
+
+These are low level functions which operate on DBus object paths of collections
+or items, instead of the [class@Collection] or [class@Item] objects themselves.
+
+You can use these functions if you wish to manage access to the secret service
+using the DBus API directly, and only wish to use a few calls in libsecret.
diff --git a/docs/reference/libsecret/libsecret-tpm2.md b/docs/reference/libsecret/libsecret-tpm2.md
new file mode 100644
index 0000000..b63de75
--- /dev/null
+++ b/docs/reference/libsecret/libsecret-tpm2.md
@@ -0,0 +1,69 @@
+Title: Extending file backend to use a TPM
+Slug: libsecret-tpm2
+
+# Extending file backend to use a TPM
+
+##  Introduction
+
+The current implementation of file backend uses an encryption key derived from
+the user's login password. Security wise this not an ideal situation. Because,
+the entire security of the file backend relies on the user's login password
+(single point of failure). This situation can be improved if the keys are
+protected/generated by hardware. A Trusted Platform Module (TPM) is a such
+hardware security module found in modern computer systems.
+
+The new `EGG_TPM2` API based on the "TSS Enhanced System API (ESAPI)"
+
+```c
+EggTpm2Context *egg_tpm2_initialize               (GError **);
+void            egg_tpm2_finalize                 (EggTpm2Context *);
+GBytes         *egg_tpm2_generate_master_password (EggTpm2Context *,
+                                                   GError **);
+GBytes         *egg_tpm2_decrypt_master_password  (EggTpm2Context *,
+                                                   GBytes *,
+                                                   GError **);
+```
+
+## Build and test libsecret with TPM2 support
+
+In order to try out the `TPM2 support` use the `-Dtpm2=true` build option/flag
+during the `meson _build` process.
+
+You can alter the default build and install process as the following:
+
+```sh
+meson _build -Dtpm2=true
+ninja -C _build
+ninja -C _build install
+```
+
+For testing the TPM2 support you need a physical TPM or a TPM emulator. The
+following sections demonstrate how to setup
+[swtpm](https://github.com/stefanberger/swtpm) emulator and testing out the TPM2
+support. If you have access to a TPM you can ignore the emulator section.
+
+swtpm emulator setup:
+
+```sh
+dnf install swtpm swtpm-tools tpm2-abrmd tpm2-tss-devel
+eval `dbus-launch --sh-syntax`
+export XDG_CONFIG_HOME=$HOME/.config/swtpm
+/usr/share/swtpm/swtpm-create-user-config-files --root
+mkdir -p ${XDG_CONFIG_HOME}/mytpm1
+swtpm_setup --tpm2 --tpmstate $XDG_CONFIG_HOME/mytpm1 --createek --allow-signing --decryption --create-ek-cert --create-platform-cert --lock-nvram --overwrite --display
+swtpm socket --tpm2 --tpmstate dir=$XDG_CONFIG_HOME/mytpm1 --flags startup-clear --ctrl type=tcp,port=2322 --server type=tcp,port=2321 --daemon
+tpm2-abrmd --logger=stdout --tcti=swtpm: --session --allow-root --flush-all &amp;
+export TCTI=tabrmd:bus_type=session
+```
+
+Test TPM2 support:
+
+```sh
+cd libsecret
+meson _build -Dtpm2=true
+ninja -C _build
+export SECRET_BACKEND=file
+export SECRET_FILE_TEST_PATH=$PWD/keyring
+./_build/tool/secret-tool store --label=foo bar baz
+ls # keyring
+```
diff --git a/docs/reference/libsecret/libsecret-tpm2.sgml b/docs/reference/libsecret/libsecret-tpm2.sgml
deleted file mode 100644
index 184e26a..0000000
--- a/docs/reference/libsecret/libsecret-tpm2.sgml
+++ /dev/null
@@ -1,67 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-]>
-<part>
-<title>Extending file backend to use a TPM</title>
-
-<chapter>
-<title>Introduction</title>
-
-<para>The current implementation of file backend uses an encryption key derived from the user's login password. Security wise this not an ideal situation. Because, the entire security of the file backend relies on the user's login password (single point of failure). This situation can be improved if the keys are protected/generated by hardware. A Trusted Platform Module (TPM) is a such hardware security module found in modern computer systems.</para>
-
-<para>The new <application>EGG_TPM2 API</application> based on the <application>TSS Enhanced System API (ESAPI)</application></para>
-
-<informalexample><programlisting>
-EggTpm2Context *egg_tpm2_initialize               (GError **);
-void           egg_tpm2_finalize                  (EggTpm2Context *);
-GBytes         *egg_tpm2_generate_master_password (EggTpm2Context *,
-		                                   GError **);
-GBytes         *egg_tpm2_decrypt_master_password  (EggTpm2Context *,
-		                                   GBytes *,
-						   GError **);
-</programlisting></informalexample>
-</chapter>
-
-<chapter>
-<title>Build and test libsecret with TPM2 support</title>
-
-<para>In order to try out the <application>TPM2 support</application> use the <literal>-Dtpm2=true</literal> build option/flag during the <literal>meson _build</literal> process.</para>
-
-<para>You can alter the default build and install process as the following:</para>
-
-<informalexample><programlisting>
-$ meson _build -Dtpm2=true
-$ ninja -C _build
-$ ninja -C _build install
-</programlisting></informalexample>
-
-<para>For testing the TPM2 support you need a physical TPM or a TPM emulator. The following sections demonstrate how to setup <ulink url="https://github.com/stefanberger/swtpm">swtpm</ulink> emulator and testing out the TPM2 support. If you have access to a TPM you can ignore the emulator section.</para>
-
-<para>swtpm emulator setup:</para>
-
-<informalexample><programlisting>
-$ dnf install swtpm swtpm-tools tpm2-abrmd tpm2-tss-devel
-$ eval `dbus-launch --sh-syntax`
-$ export XDG_CONFIG_HOME=$HOME/.config/swtpm
-$ /usr/share/swtpm/swtpm-create-user-config-files --root
-$ mkdir -p ${XDG_CONFIG_HOME}/mytpm1
-$ swtpm_setup --tpm2 --tpmstate $XDG_CONFIG_HOME/mytpm1 --createek --allow-signing --decryption --create-ek-cert --create-platform-cert --lock-nvram --overwrite --display
-$ swtpm socket --tpm2 --tpmstate dir=$XDG_CONFIG_HOME/mytpm1 --flags startup-clear --ctrl type=tcp,port=2322 --server type=tcp,port=2321 --daemon
-$ tpm2-abrmd --logger=stdout --tcti=swtpm: --session --allow-root --flush-all &amp;
-$ export TCTI=tabrmd:bus_type=session
-</programlisting></informalexample>
-
-<para>Test TPM2 support:</para>
-
-<informalexample><programlisting>
-$ cd libsecret
-$ meson _build -Dtpm2=true
-$ ninja -C _build
-$ export SECRET_BACKEND=file
-$ export SECRET_FILE_TEST_PATH=$PWD/keyring
-$ ./_build/tool/secret-tool store --label=foo bar baz
-$ ls # keyring
-</programlisting></informalexample>
-</chapter>
-</part>
diff --git a/docs/reference/libsecret/libsecret-using.md b/docs/reference/libsecret/libsecret-using.md
new file mode 100644
index 0000000..bc2eae1
--- /dev/null
+++ b/docs/reference/libsecret/libsecret-using.md
@@ -0,0 +1,80 @@
+Title: Using libsecret
+Slug: libsecret-using
+
+# Using libsecret in builds or scripts
+
+## C: Compiling with libsecret
+
+Like other GNOME libraries, libsecret uses `pkg-config` to provide compiler
+options. The package name is `libsecret-1`. So in your `configure.ac` script,you
+might specify something like:
+
+```
+PKG_CHECK_MODULES(LIBSECRET, [libsecret-1 >= 1.0])
+AC_SUBST(LIBSECRET_CFLAGS)
+AC_SUBST(LIBSECRET_LIBS)
+```
+
+Code using libsecret should include the header like this:
+
+```c
+#include <libsecret/secret.h>;
+```
+
+Including individual headers besides the main header files is not permitted and
+will cause an error.
+
+Some parts of the libsecret API are not yet stable. To use them you need use the
+`libsecret-unstable` package. The API contained in this package will change from
+time to time. Here's how you would do it:
+
+```
+PKG_CHECK_MODULES(LIBSECRET, [libsecret-unstable >= 1.0])
+AC_SUBST(LIBSECRET_CFLAGS)
+AC_SUBST(LIBSECRET_LIBS)
+```
+
+## Javascript: Importing libsecret
+
+In Javascript use the standard introspection import mechanism to get at
+libsecret:
+
+```js
+const Secret = imports.gi.Secret;
+
+// ... and here's a sample line of code which uses the import
+var schema = new Secret.Schema.new("org.mock.Schema",
+	Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING });
+```
+
+
+## Python: Importing libsecret
+
+In python use the standard introspection import mechanism to get at libsecret:
+
+```python
+from gi.repository import Secret
+
+# ... and a here's sample line of code which uses the import
+schema = Secret.Schema.new("org.mock.Schema",
+	Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING })
+```
+
+## Vala: Compiling with libsecret
+
+The package name is `libsecret-1`. You can use it like
+this in your `Makefile.am` file:
+
+```
+AM_VALAFLAGS = \
+	--pkg=libsecret-1
+```
+
+Some parts of the libsecret API are not yet stable.
+To use them you need to define the `SECRET_WITH_UNSTABLE` C preprocessor
+macro to use them, or else the build will fail:
+
+```
+AM_CPPFLAGS = \
+	-DSECRET_WITH_UNSTABLE=1
+```
diff --git a/docs/reference/libsecret/libsecret-using.sgml b/docs/reference/libsecret/libsecret-using.sgml
deleted file mode 100644
index 3043e1e..0000000
--- a/docs/reference/libsecret/libsecret-using.sgml
+++ /dev/null
@@ -1,112 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
-]>
-<part id="using">
-<title>Using libsecret in builds or scripts</title>
-
-<chapter id="using-c">
-<title>C: Compiling with libsecret</title>
-
-<para>Like other GNOME libraries, <application>libsecret</application> uses
-<application>pkg-config</application> to provide compiler options. The package
-name is "<literal>libsecret-1</literal>". So in your
-<literal>configure.ac</literal> script,you might specify something like:</para>
-
-<informalexample><programlisting>
-PKG_CHECK_MODULES(LIBSECRET, [libsecret-1 >= 1.0])
-AC_SUBST(LIBSECRET_CFLAGS)
-AC_SUBST(LIBSECRET_LIBS)
-</programlisting></informalexample>
-
-<para>
-Code using <application>libsecret</application> should include the header like this:
-</para>
-
-<informalexample><programlisting>
-#include &lt;libsecret/secret.h&gt;
-</programlisting></informalexample>
-
-<para>
-Including individual headers besides the main header files is not
-permitted and will cause an error.
-</para>
-
-<para>
-Some parts of the <application>libsecret</application> API are not yet stable.
-To use them you need use the <literal>libsecret-unstable</literal> package.
-The API contained in this package will change from time to time. Here's how
-you would do it:
-</para>
-
-<informalexample><programlisting>
-PKG_CHECK_MODULES(LIBSECRET, [libsecret-unstable >= 1.0])
-AC_SUBST(LIBSECRET_CFLAGS)
-AC_SUBST(LIBSECRET_LIBS)
-</programlisting></informalexample>
-
-</chapter>
-
-<chapter id="using-js">
-<title>Javascript: Importing libsecret</title>
-
-<para>
-In javascript use the standard introspection import mechanism to get at
-<application>libsecret</application>:
-</para>
-
-<informalexample><programlisting language="javascript">
-const Secret = imports.gi.Secret;
-
-// ... and here's a sample line of code which uses the import
-var schema = new Secret.Schema.new("org.mock.Schema",
-	Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING });
-</programlisting></informalexample>
-
-</chapter>
-
-<chapter id="using-python">
-<title>Python: Importing libsecret</title>
-
-<para>
-In python use the standard introspection import mechanism to get at
-<application>libsecret</application>:
-</para>
-
-<informalexample><programlisting language="py">
-from gi.repository import Secret
-
-# ... and a here's sample line of code which uses the import
-schema = Secret.Schema.new("org.mock.Schema",
-	Secret.SchemaFlags.NONE, { "name", Secret.SchemaAttributeType.STRING })
-</programlisting></informalexample>
-
-</chapter>
-
-<chapter id="using-vala">
-<title>Vala: Compiling with libsecret</title>
-
-<para>
-The package name is "<literal>libsecret-1</literal>". You can use it like
-this in your <literal>Makefile.am</literal> file:
-</para>
-
-<informalexample><programlisting>
-AM_VALAFLAGS = \
-	--pkg=libsecret-1
-</programlisting></informalexample>
-
-<para>
-Some parts of the <application>libsecret</application> API are not yet stable.
-To use them you need to define the SECRET_WITH_UNSTABLE C preprocessor
-macro to use them, or else the build will fail:
-</para>
-
-<informalexample><programlisting>
-AM_CPPFLAGS = \
-	-DSECRET_WITH_UNSTABLE=1
-</programlisting></informalexample>
-
-</chapter>
-
-</part>
diff --git a/docs/reference/libsecret/libsecret-vala-examples.md b/docs/reference/libsecret/libsecret-vala-examples.md
new file mode 100644
index 0000000..0e64724
--- /dev/null
+++ b/docs/reference/libsecret/libsecret-vala-examples.md
@@ -0,0 +1,157 @@
+Title: Vala Examples
+Slug: libsecret-vala-example
+
+# Vala Examples
+
+## Define a password schema
+
+Each stored password has a set of attributes which are later
+used to lookup the password. The names and types of the attributes
+are defined in a schema. The schema is usually defined once globally.
+Here's how to define a schema:
+
+```vala
+var example = new Secret.Schema ("org.example.Password", Secret.SchemaFlags.NONE,
+                                 "number", Secret.SchemaAttributeType.INTEGER,
+                                 "string", Secret.SchemaAttributeType.STRING,
+                                 "even", Secret.SchemaAttributeType.BOOLEAN);
+```
+
+See the [other examples](#store-a-password) for how
+to use the schema.
+
+
+## Store a password
+
+Here's how to store a password in the running secret service,
+like gnome-keyring or ksecretservice.
+
+Each stored password has a set of attributes which are later
+used to lookup the password. The attributes should not contain
+secrets, as they are not stored in an encrypted fashion.
+
+These examples use the [example schema](#define-a-password-schema).
+
+This first example stores a password asynchronously, and is
+appropriate for GUI applications so that the UI does not block.
+
+```vala
+var attributes = new GLib.HashTable<string,string> ();
+attributes["number"] = "8";
+attributes["string"] = "eight";
+attributes["even"] = "true";
+
+Secret.password_storev.begin (example_schema, attributes, Secret.COLLECTION_DEFAULT,
+                              "The label", "the password", null, (obj, async_res) => {
+    bool res = Secret.password_store.end (async_res);
+    /* ... do something now that the password has been stored */
+});
+```
+
+If you are already inside of an async function, you can also
+use the yield keyword:
+
+```vala
+var attributes = new GLib.HashTable<string,string> ();
+attributes["number"] = "8";
+attributes["string"] = "eight";
+attributes["even"] = "true";
+
+bool res = yield Secret.password_storev (example_schema, attributes,
+                                         Secret.COLLECTION_DEFAULT, "The label",
+                                         "the password", null);
+```
+
+If you would like to avoid creating a hash table for the
+attributes you can just use the variadic version:
+
+```vala
+bool res = yield Secret.password_store (example_schema, Secret.COLLECTION_DEFAULT, "The label",
+                                        "the password", null, "number", 8, "string", "eight",
+                                        "even", true);
+```
+
+This next example stores a password synchronously. The function
+call will block until the password is stored. So this is appropriate for
+non GUI applications.
+
+```vala
+Secret.password_store_sync (example_schema, attributes, Secret.COLLECTION_DEFAULT,
+                            "The label", "the password", null,
+                            "number", 9, "string", "nine", "even", false);
+```
+
+## Lookup a password
+
+Here's how to lookup a password in the running secret service,
+like gnome-keyring or ksecretservice.
+
+Each stored password has a set of attributes which are
+used to lookup the password. If multiple passwords match the
+lookup attributes, then the one stored most recently is returned.
+
+These examples use the [example schema](#define-a-password-schema).
+
+This first example looks up a password asynchronously, and is
+appropriate for GUI applications so that the UI does not block.
+
+```vala
+var attributes = new GLib.HashTable<string,string> ();
+attributes["number"] = "8";
+attributes["string"] = "eight";
+attributes["even"] = "true";
+
+Secret.password_lookupv.begin (example_schema, attributes, null, (obj, async_res) => {
+    string password = Secret.password_lookup.end (async_res);
+});
+```
+
+This next example looks up a password synchronously. The function
+call will block until the lookup completes. So this is appropriate for
+non GUI applications.
+
+```vala
+string password = Secret.password_lookup_sync (example_schema, attributes, null,
+                                               "number", 9, "string", "nine", "even", false);
+/* password will be null, if no matching password found */
+```
+
+## Remove a password
+
+Here's how to remove a password from the running secret service,
+like gnome-keyring or ksecretservice.
+
+Each stored password has a set of attributes which are
+used to find which password to remove. If multiple passwords match the
+attributes, then the one stored most recently is removed.
+
+These examples use the [example schema](#define-a-password-schema).
+
+This first example removes a password asynchronously, and is
+appropriate for GUI applications so that the UI does not block.
+
+```vala
+var attributes = new GLib.HashTable<string,string> ();
+attributes["number"] = "8";
+attributes["string"] = "eight";
+attributes["even"] = "true";
+
+Secret.password_clearv.begin (example_schema, attributes, null, (obj, async_res) => {
+    bool removed = Secret.password_clearv.end (async_res);
+});
+```
+
+This next example removes a password synchronously. The function
+call will block until the removal completes. So this is appropriate for
+non GUI applications.
+
+```vala
+var attributes = new GLib.HashTable<string,string> ();
+attributes["number"] = "8";
+attributes["string"] = "eight";
+attributes["even"] = "true";
+
+bool removed = Secret.password_clear_sync (example_schema, null,
+                                           "number", 8, "string", "eight", "even", true);
+/* removed will be true if the password was removed */
+```
diff --git a/docs/reference/libsecret/libsecret.toml.in b/docs/reference/libsecret/libsecret.toml.in
new file mode 100644
index 0000000..5af2ac4
--- /dev/null
+++ b/docs/reference/libsecret/libsecret.toml.in
@@ -0,0 +1,52 @@
+[library]
+version = "@VERSION@"
+browse_url = "https://gitlab.gnome.org/GNOME/libsecret"
+repository_url = "https://gitlab.gnome.org/GNOME/libsecret.git"
+docs_url = "https://gnome.pages.gitlab.gnome.org/libsecret/"
+website_url = "https://gnome.pages.gitlab.gnome.org/libsecret/"
+authors = "Stef Walter, Daiki Ueno, and Niels De Graef"
+license = "LGPL-2.1-or-later"
+description = "Secret Service D-Bus client library"
+dependencies = [ "GObject-2.0", "GLib-1.0", "Gio-2.0" ]
+devhelp = true
+search_index = true
+
+[dependencies."GObject-2.0"]
+name = "GObject"
+description = "The base type system library"
+docs_url = "https://docs.gtk.org/gobject/"
+
+[dependencies."GLib-2.0"]
+name = "GLib"
+description = "The base type system library"
+docs_url = "https://docs.gtk.org/glib/"
+
+[dependencies."Gio-2.0"]
+name = "GIO"
+description = "GObject Interfaces and Objects, Networking, IPC, and I/O"
+docs_url = "https://docs.gtk.org/gio/"
+
+[theme]
+name = "basic"
+show_index_summary = true
+show_class_hierarchy = true
+
+[source-location]
+base_url = "https://gitlab.gnome.org/GNOME/libsecret/-/blob/master"
+
+[extra]
+# The same order will be used when generating the index
+content_files = [
+  'libsecret-using.md',
+  'libsecret-simple-api.md',
+  "libsecret-c-examples.md",
+  "libsecret-js-examples.md",
+  "libsecret-python-examples.md",
+  "libsecret-vala-examples.md",
+  "libsecret-tpm2.md",
+  "migrating-libgnome-keyring.md",
+]
+
+content_images = [
+]
+urlmap_file = "urlmap.js"
diff --git a/docs/reference/libsecret/libsecret.types b/docs/reference/libsecret/libsecret.types
deleted file mode 100644
index f9bfa7a..0000000
--- a/docs/reference/libsecret/libsecret.types
+++ /dev/null
@@ -1,7 +0,0 @@
-secret_collection_get_type
-secret_error_get_type
-secret_item_get_type
-secret_prompt_get_type
-secret_value_get_type
-secret_service_flags_get_type
-secret_service_get_type
\ No newline at end of file
diff --git a/docs/reference/libsecret/meson.build b/docs/reference/libsecret/meson.build
index d342c58..ac4dfaa 100644
--- a/docs/reference/libsecret/meson.build
+++ b/docs/reference/libsecret/meson.build
@@ -1,39 +1,48 @@
-reference_content_files = [
-  'libsecret-examples.sgml',
-  'libsecret-using.sgml',
-  'libsecret-tpm2.sgml',
-  'migrating-libgnome-keyring.xml',
+expand_content_md_files = [
+  'libsecret-c-examples.md',
+  'libsecret-js-examples.md',
+  'libsecret-python-examples.md',
+  'libsecret-simple-api.md',
+  'libsecret-tpm2.md',
+  'libsecret-using.md',
+  'libsecret-vala-examples.md',
+  'migrating-libgnome-keyring.md',
 ]
 
-# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
-reference_expanded_content_files = [
-  'migrating-libgnome-keyring.xml',
-]
-
-reference_ignore_headers = [
-  'mock-service.h',
-  'secret-dbus-generated.h',
-  'secret-private.h',
-]
+toml_data = configuration_data()
+toml_data.set('VERSION', meson.project_version())
 
-configure_file(
-  input: 'version.xml.in',
-  output: '@BASENAME@',
-  configuration: {'VERSION': meson.project_version()},
+libsecret_toml = configure_file(
+  input: 'libsecret.toml.in',
+  output: 'libsecret.toml',
+  configuration: toml_data
 )
 
-gnome.gtkdoc('libsecret',
-  main_sgml: 'libsecret-docs.sgml',
-  content_files: reference_content_files,
-  src_dir: include_directories('../../../libsecret'),
-  dependencies: libsecret_dep,
-  gobject_typesfile: 'libsecret.types',
-  mkdb_args: '--expand-content-files=' + ' '.join(reference_expanded_content_files),
-  scan_args: [
-    '--deprecated-guards=SECRET_DISABLE_DEPRECATED',
-    '--rebuild-types',
-    '--ignore-headers=' + ' '.join(reference_ignore_headers),
+dependency('gi-docgen', version: '>= 2021.7',
+           fallback: ['gi-docgen', 'dummy_dep'],
+           native: true,
+           required: get_option('gtk_doc'))
+
+gidocgen = find_program('gi-docgen')
+
+docs_dir = get_option('datadir') / 'doc'
+
+custom_target('libsecret-doc',
+  input: [ libsecret_toml, libsecret_gir[0] ],
+  output: 'libsecret-@0@'.format(api_version_major),
+  command: [
+    gidocgen,
+    'generate',
+    '--quiet',
+    '--add-include-path=@0@'.format(meson.current_build_dir() / '../../../libsecret'),
+    '--config=@INPUT0@',
+    '--output-dir=@OUTPUT@',
+    '--no-namespace-dir',
+    '--content-dir=@0@'.format(meson.current_source_dir()),
+    '@INPUT1@',
   ],
-  module_version: api_version_major,
+  depend_files: [ expand_content_md_files ],
+  build_by_default: true,
   install: true,
+  install_dir: docs_dir,
 )
diff --git a/docs/reference/libsecret/migrating-libgnome-keyring.md b/docs/reference/libsecret/migrating-libgnome-keyring.md
new file mode 100644
index 0000000..43de06d
--- /dev/null
+++ b/docs/reference/libsecret/migrating-libgnome-keyring.md
@@ -0,0 +1,823 @@
+Title: Migrating from libgnome-keyring
+Slug: migrating-libgnome-keyring
+
+# Migrating from libgnome-keyring
+
+## Introduction
+
+Conceptually, libgnome-keyring and libsecret are fairly similar. Both
+have keyrings, items, and ways to store and retrieve passwords. In both
+cases items have attributes. The keys and values of attributes are used
+to lookup a password that was stored.
+
+There is a
+<link linkend="libsecret-Password-storage">simple password API for storing and retrieving passwords</link>
+which is the easiest and recommended way to store passwords. And then
+there is a more complicated API which models all the various collections
+and items, along with all the possible actions that can be performed on them.
+
+libsecret uses the
+<ulink url="http://standards.freedesktop.org/secret-service/">Secret Service DBus API</ulink>
+to communicate with gnome-keyring-daemon, and as such exposes features
+based on that DBus API.
+
+libsecret has been designed to be threadsafe, and uses the 'GDBus'
+code in gio to accomplish this.
+
+Keyrings are called 'collections' in libsecret.
+
+See the relevant section for specifics about how to port the
+libgnome-keyring functions or symbols in your project.
+
+## API conversion
+
+Here are some clues on how to migrate various libgnome-keyring
+API functions and their logical equivalents in libsecret.
+
+### Item attributes
+
+Remember that attributes are not, and never have been stored in
+an encrypted fashion. They are not part of the 'secret', but instead
+are a way to lookup a secret item.
+
+All attributes in libsecret are stored as strings. Sets of attributes
+are represented by [struct@GLib.HashTable]s and the keys and values of 
+these hash tables are strings.
+
+libsecret is far more <link linkend="migrating-schemas">focused on schemas</link>,
+and encourages users to define a [struct@Schema] for their password storage.
+The schema defines which attributes are allowed an item. Each schema has
+a name which is usually a dotted string (eg: `org.gnome.MyProject.Password`).
+This schema name is stored internally in the item attributes.
+
+Schemas define whether an attribute should look like an integer,
+a boolean, or a free-form string. These types are used when validating
+the attribute values, even though the attribute values are stored and
+matched as strings. Since attribute values are used primarily
+for lookup of items it's important that the string representations of
+integers and booleans are always identical. Boolean values are stored
+as the strings `true` and `false`.
+Integer values are stored in decimal, with a preceding negative sign
+for negative integers. libsecret facilitates this using the
+[func@attributes_build] and [func@attributes_buildv] functions.
+
+Attributes are meant to be used for lookup of items; they're not
+designed to be used as a generic key/value database. Although you can
+force libsecret to do the latter, it's better to store your account
+information elsewhere if possible, and use libsecret to store the password
+or other secret.
+
+Replacements for related libgnome-keyring functions and types
+are described below:
+
+<table>
+    <tr>
+        <th>libgnome-keyring</th><th>libsecret</th>
+    </tr>
+    <tr>
+        <td>GnomeKeyringAttributeList</td>
+        <td>a [struct@GLib.HashTable] of string keys and values</td>
+    </tr>
+    <tr>
+        <td>GnomeKeyringAttribute</td>
+        <td>a key/value pair in a [struct@GLib.HashTable] of strings</td>
+    </tr>
+    <tr>
+        <td>GnomeKeyringAttributeType</td>
+        <td>[struct@Schema]AttributeType</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_ATTRIBUTE_TYPE_STRING</code></td>
+        <td><code>SECRET_SCHEMA_ATTRIBUTE_STRING</code></td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32</code></td>
+        <td><code>SECRET_SCHEMA_ATTRIBUTE_INTEGER</code></td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_attribute_list_index()</code></td>
+        <td>use [func@GLib.HashTable.lookup] on the attributes hash table</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_attribute_get_string()</code></td>
+        <td>use [func@GLib.HashTable.lookup] on the attributes hash table</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_attribute_get_uint32()</code></td>
+        <td>no equivalent, use [func@GLib.HashTable.lookup]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_attribute_list_append_string()</code></td>
+        <td>[func@attributes_build]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_attribute_list_append_uint32()</code></td>
+        <td>[func@attributes_build]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_attribute_list_copy()</code></td>
+        <td>[func@GLib.HashTable.ref]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_attribute_list_free()</code></td>
+        <td>[func@GLib.HashTable.unref]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_attribute_list_index()</code></td>
+        <td>no equivalent, use [func@GLib.HashTable.lookup]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_attribute_list_new()</code></td>
+        <td>[func@attributes_build]</td>
+    </tr>
+</table>
+
+## Working with schemas
+
+libsecret is far more focused on schemas, and encourages users to
+define a [struct@Schema] for their password storage. The schema defines
+which attributes are allowed an item. Each schema has a name which
+is usually a dotted string (eg: `org.gnome.MyProject.Password`).
+This name is stored in the item attributes. The schema name is also
+used when looking up an item, to make sure that the stored schema
+matches that used during the lookup. If you wish to lookup items that
+were stored by libgnome-keyring, you should specify the 
+`SECRET_SCHEMA_DONT_MATCH_NAME` flag in the schema so that the schema
+name is not matched, since it was not stored by libgnome-keyring.
+
+Schemas define whether an attribute should look like an integer,
+a boolean, or a free-form string. These types are used when validating
+the attribute values stored, even though the attribute values are
+stored and matched as strings.
+
+Replacements for related libgnome-keyring functions and types
+are described below:
+<table>
+    <tr>
+        <th>libgnome-keyring</th><th>libsecret</th>
+    </tr>
+    <tr>
+        <td>GnomeKeyringPasswordSchema</td>
+        <td>[struct@Schema]</td>
+    </tr>
+    <tr>
+        <td>GnomeKeyringPasswordSchemaAttribute</td>
+        <td>[struct@Schema]Attribute</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_ITEM_APPLICATION_SECRET</code></td>
+        <td>no equivalent</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_ITEM_CHAINED_KEYRING_PASSWORD</code></td>
+        <td>no equivalent</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_ITEM_ENCRYPTION_KEY_PASSWORD</code></td>
+        <td>no equivalent</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_ITEM_PK_STORAGE</code></td>
+        <td>no equivalent</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_ITEM_GENERIC_SECRET</code></td>
+        <td>no equivalent, define a specific schema with an appropriate dotted name</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_ITEM_NETWORK_PASSWORD</code></td>
+        <td>the <code>SECRET_SCHEMA_COMPAT_NETWORK</code> schema, although not recommended for new uses</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_ITEM_NOTE</code></td>
+        <td>the <code>SECRET_SCHEMA_NOTE</code> schema</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_NETWORK_PASSWORD</code></td>
+        <td>the <code>SECRET_SCHEMA_COMPAT_NETWORK</code> schema, although not recommended for new uses</td>
+    </tr>
+</table>
+
+## Storing passwords and items
+
+It's encouraged to use a [struct@Schema] when storing items and
+passwords.
+
+By default most ways of storing an item will now overwrite
+another item with the same attributes in the same keyring. To manually
+control this behavior use the [func@Item.create].
+
+Replacements for related libgnome-keyring functions and types
+are described below:
+
+<table>
+    <tr>
+        <th>libgnome-keyring</th><th>libsecret</th>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_DEFAULT</code></td>
+        <td>[const@COLLECTION_DEFAULT]</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_SESSION</code></td>
+        <td>[const@COLLECTION_SESSION]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_store_password()</code></td>
+        <td>[func@password_store]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_store_password_sync()</code></td>
+        <td>[func@password_store_sync]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_set_network_password()</code></td>
+        <td>[func@password_store] with <code>SECRET_SCHEMA_COMPAT_NETWORK</code>
+        although this is not recommended for new uses.</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_set_network_password_sync()</code></td>
+        <td>[func@password_store_sync] with <code>SECRET_SCHEMA_COMPAT_NETWORK</code>
+        although this is not recommended for new uses.</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_create()</code></td>
+        <td>[func@Item.create], although using [func@password_store]
+        is simpler.</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_create_sync()</code></td>
+        <td>[func@Item.create], although using [func@password_store_sync]
+        is simpler.</td>
+    </tr>
+</table>
+
+## Searching for passwords and items
+
+In general libsecret tries not to unlocking keyrings
+where not necessary. Many search methods only return one item or
+password that matches, preferring already unlocked items, and recently stored
+items.
+
+Attributes are meant to be used for lookup of items; they're not
+designed to be used as a generic key/value database. Although you can
+force libsecret to do the latter, it's better to store your account
+information elsewhere if possible, and use libsecret to store the password
+or other secret. Because of this many search methods return just the
+password or secret.
+
+Replacements for related libgnome-keyring functions and types
+are described below:
+
+<table>
+    <tr>
+        <th>libgnome-keyring</th><th>libsecret</th>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_find_password()</code></td>
+        <td>[func@password_lookup]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_find_password_sync()</code></td>
+        <td>[func@password_lookup_sync]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_find_items()</code></td>
+        <td>[method@Service.search], with flags to fine tune behavior</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_find_itemsv()</code></td>
+        <td>[method@Service.search], with flags to fine tune behavior</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_find_items_sync()</code></td>
+        <td>[method@Service.search_sync], with flags to fine tune behavior</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_find_itemsv_sync()</code></td>
+        <td>[method@Service.search], with flags to fine tune behavior</td>
+    </tr>
+    <tr>
+        <td>GnomeKeyringFound</td>
+        <td>no equivalent, [method@Service.search] returns a [struct@GLib.List] of
+        [class@Item]<!-- -->s, and other methods return passwords directly.</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_found_copy()</code></td>
+        <td>no equivalent</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_found_free()</code></td>
+        <td>[method@GObject.Object.unref] on the each of the items returned from
+        [method@Service.search]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_found_list_free()</code></td>
+        <td>[func@GLib.List.free_full] used with [method@GObject.Object.unref] on the items returned from
+        [method@Service.search]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_find_network_password()</code></td>
+        <td>[func@password_lookup] with <code>SECRET_SCHEMA_COMPAT_NETWORK</code>,
+        although this only returns one password and no attributes</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_find_network_password_sync()</code></td>
+        <td>[func@password_lookup_sync] with <code>SECRET_SCHEMA_COMPAT_NETWORK</code>,
+        although this only returns one password and no attributes</td>
+    </tr>
+    <tr>
+        <td>GnomeKeyringNetworkPasswordData</td>
+        <td>no equivalent, [func@password_lookup] gets the password directly
+        and no attributes</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_network_password_free()</code></td>
+        <td>no equivalent</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_network_password_list_free()</code></td>
+        <td>no equivalent</td>
+    </tr>
+</table>
+
+## Removing passwords and icons
+
+Neither libgnome-keyring or libsecret allow deletion of locked
+items. libsecret tries to make it easier to delete all unlocked items
+matching certain attributes.
+
+Replacements for related libgnome-keyring functions and types
+are described below:
+
+<table>
+    <tr>
+        <th>libgnome-keyring</th><th>libsecret</th>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_delete_password()</code></td>
+        <td>[func@password_clear], although we now try to delete
+        all unlocked matching items</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_delete_password_sync()</code></td>
+        <td>[func@password_clear_sync], although we now try to delete
+        all unlocked matching items</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_delete()</code></td>
+        <td>[method@Item.delete]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_delete_sync()</code></td>
+        <td>[method@Item.delete_sync]</td>
+    </tr>
+</table>
+
+##  Item management
+
+In libsecret items are no longer identified by an unsigned integer.
+Applications should retrieve items based on their attributes. It is also
+possible to identify an item by its DBus object path.
+
+Replacements for related libgnome-keyring functions and types
+are described below:
+
+<table>
+    <tr>
+        <th>libgnome-keyring</th><th>libsecret</th>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_create()</code></td>
+        <td>[func@Item.create], although [func@password_store] may be simpler</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_create_sync()</code></td>
+        <td>[func@Item.create_sync], although [func@password_store_sync] may be simpler</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_delete()</code></td>
+        <td>[method@Item.delete], although [func@password_clear] may be simpler</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_delete_sync()</code></td>
+        <td>[method@Item.delete_sync], although [func@password_clear_sync] may be simpler</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_get_info()</code></td>
+        <td>properties are loaded on a [class@Item] automatically, use
+        [method@Item.load_secret] to load the secret</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_get_info_sync()</code></td>
+        <td>properties are loaded on a [class@Item] automatically, use
+        [method@Item.load_secret_sync] to load the secret</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_get_info_full()</code></td>
+        <td>properties are loaded on a [class@Item] automatically, use
+        [method@Item.load_secret] to load the secret</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_get_info_full_sync()</code></td>
+        <td>properties are loaded on a [class@Item] automatically, use
+        [method@Item.load_secret_sync] to load the secret</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_set_info()</code></td>
+        <td>use the appropriate setter methods on [class@Item]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_set_info_sync()</code></td>
+        <td>use the appropriate setter methods on [class@Item]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_get_attributes()</code></td>
+        <td>[method@Item.get_attributes]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_get_attributes_sync()</code></td>
+        <td>[method@Item.get_attributes]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_set_attributes()</code></td>
+        <td>[method@Item.set_attributes]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_set_attributes_sync()</code></td>
+        <td>[method@Item.set_attributes_sync]</td>
+    </tr>
+    <tr>
+        <td>GnomeKeyringItemType</td>
+        <td>replaced by the name of a [struct@Schema]</td>
+    </tr>
+    <tr>
+        <td>GnomeKeyringItemInfo</td>
+        <td>[class@Item]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_info_new()</code></td>
+        <td>no equivalent</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_info_copy()</code></td>
+        <td>no equivalent</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_info_free()</code></td>
+        <td>[method@GObject.Object.unref] on the [class@Item]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_info_get_display_name()</code></td>
+        <td>[method@Item.get_label]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_info_set_display_name()</code></td>
+        <td>[method@Item.set_label]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_info_get_ctime()</code></td>
+        <td>[method@Item.get_created]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_info_get_mtime()</code></td>
+        <td>[method@Item.get_modified]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_info_get_type()</code></td>
+        <td>[method@Item.get_schema_name]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_info_set_type()</code></td>
+        <td>[method@Item.set_attributes] with appropriate schema</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_info_get_secret()</code></td>
+        <td>[method@Item.get_secret]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_info_set_secret()</code></td>
+        <td>[method@Item.set_secret] and [method@Item.set_secret_sync]</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_ITEM_INFO_BASICS</code></td>
+        <td>no equivalent, all basic item properties are loaded on [class@Item]
+        automatically</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_ITEM_INFO_SECRET</code></td>
+        <td>use [method@Item.load_secret] and [method@Item.load_secret_sync] to load
+        the secret for an item.</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_item_info_set_display_name()</code></td>
+        <td></td>
+    </tr>
+</table>
+
+## Keyring management
+
+In libsecret keyrings are called 'collections'. This is the same
+lingo as the underlying Secret Service DBus API. Keyrings are no longer
+identified by simple keyring names. Normally applications just use the
+default keyrings and these are identified by the aliases
+[const@COLLECTION_DEFAULT] and [const@COLLECTION_SESSION]. It is also
+possible to identify collections by their DBus object paths.
+
+Replacements for related libgnome-keyring functions and types
+are described below:
+
+<table>
+    <tr>
+        <th>libgnome-keyring</th><th>libsecret</th>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_create()</code></td>
+        <td>[func@Collection.create]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_create_sync()</code></td>
+        <td>[func@Collection.create_sync]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_delete()</code></td>
+        <td>[method@Collection.delete]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_delete_sync()</code></td>
+        <td>[method@Collection.delete_sync]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_change_password()</code></td>
+        <td>no equivalent, use platform specific DBus APIs</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_change_password_sync()</code></td>
+        <td>no equivalent, use platform specific DBus APIs</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_list_keyring_names()</code></td>
+        <td>[method@Service.load_collections] and [method@Service.get_collections]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_list_keyring_names_sync()</code></td>
+        <td>[method@Service.load_collections_sync] and [method@Service.get_collections]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_set_default_keyring()</code></td>
+        <td>[method@Service.set_alias]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_set_default_keyring_sync()</code></td>
+        <td>[method@Service.set_alias_sync]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_get_default_keyring()</code></td>
+        <td>[func@Collection.for_alias] with [const@COLLECTION_DEFAULT]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_get_default_keyring_sync()</code></td>
+        <td>[func@Collection.for_alias_sync] with [const@COLLECTION_DEFAULT]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_list_item_ids()</code></td>
+        <td>[method@Collection.load_items] and [method@Collection.get_items]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_list_item_ids_sync()</code></td>
+        <td>[method@Collection.load_items_sync] and [method@Collection.get_items]</td>
+    </tr>
+    <tr>
+        <td>GnomeKeyringInfo</td>
+        <td>[class@Collection] and properties</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_get_info()</code></td>
+        <td>no equivalent</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_get_info_sync()</code></td>
+        <td>no equivalent</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_set_info()</code></td>
+        <td>no equivalent, use property setters on [class@Collection]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_set_info_sync()</code></td>
+        <td>no equivalent, use property setters on [class@Collection]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_info_free()</code></td>
+        <td>no equivalent</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_info_copy()</code></td>
+        <td>no equivalent</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_info_set_lock_on_idle()</code></td>
+        <td>no equivalent</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_info_get_lock_on_idle()</code></td>
+        <td>no equivalent</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_info_set_lock_timeout()</code></td>
+        <td>no equivalent</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_info_get_lock_timeout()</code></td>
+        <td>no equivalent</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_info_get_mtime()</code></td>
+        <td>[method@Collection.get_modified]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_info_get_ctime()</code></td>
+        <td>[method@Collection.get_created]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_info_get_is_locked()</code></td>
+        <td>[method@Collection.get_locked]</td>
+    </tr>
+</table>
+
+## Locking and unlocking
+
+In libsecret you can unlock items directly, and the result is
+(with gnome-keyring daemon) that the enclosing collection will be unlocked.
+
+It is no longer possible to pass a password to unlock keyrings.
+These are automatically prompted for.
+
+Replacements for related libgnome-keyring functions and types
+are described below:
+
+<table>
+    <tr>
+        <th>libgnome-keyring</th><th>libsecret</th>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_unlock()</code></td>
+        <td>[method@Service.unlock]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_unlock_sync()</code></td>
+        <td>[method@Service.unlock_sync]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_lock()</code></td>
+        <td>[method@Service.lock]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_lock_sync()</code></td>
+        <td>[method@Service.lock_sync]</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_lock_all()</code></td>
+        <td>no equivalent, use platform specific DBus APIs</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_lock_all_sync()</code></td>
+        <td>no equivalent, use platform specific DBus APIs</td>
+    </tr>
+</table>
+
+## Non-pageable memory
+
+libsecret no longer provides a full API for using non-pageable
+memory. Use the <ulink url="http://developer.gnome.org/gcr/stable/gcr-Non-pageable-Memory.html">equivalent API in the Gcr library</ulink>.
+
+You can request that passwords are returned in non-pageable
+memory by using the [func@password_lookup_nonpageable_sync] and
+[func@password_lookup_nonpageable_finish] functions.
+In addition the contents of [struct@Value] items is stored in
+non-pageable memory, unless the system doesn't support this.
+
+Replacements for related libgnome-keyring functions and types
+are described below:
+
+<table>
+    <tr>
+        <th>libgnome-keyring</th><th>libsecret</th>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_memory_alloc()</code></td>
+        <td>no equivalent, use Gcr</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_memory_free()</code></td>
+        <td>[func@password_free], although this only works on strings</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_memory_is_secure()</code></td>
+        <td>no equivalent, use Gcr</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_memory_new()</code></td>
+        <td>no equivalent, use Gcr</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_memory_realloc()</code></td>
+        <td>no equivalent, use Gcr</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_memory_strdup()</code></td>
+        <td>no equivalent, use [struct@Value] which is ref-counted, or use Gcr</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_memory_try_alloc()</code></td>
+        <td>no equivalent, use Gcr</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_memory_try_realloc()</code></td>
+        <td>no equivalent, use Gcr</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_free_password()</code></td>
+        <td>[func@password_free]</td>
+    </tr>
+</table>
+
+## Errors and cancellation
+
+libsecret uses standard the standard [class@Gio.Cancellable] idiom
+to cancel operations.
+
+It is not necessary to check whether the keyring daemon is
+available before using it. It is started automatically.
+
+Errors are returned as standard [struct@GLib.Error] in the usual way.
+There are fewer errors that are worth handling in an intelligent way,
+exceptions are in the #SecretError enumeration. It is not recommended
+to display any [struct@GLib.Error] message returned by libsecret to the user. Most
+of the possible errors are DBus communication problems or similar.
+
+Replacements for related libgnome-keyring functions and types
+are described below:
+
+<table>
+    <tr>
+        <th>libgnome-keyring</th><th>libsecret</th>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_cancel_request()</code></td>
+        <td>[method@Gio.Cancellable.cancel] on a [class@Gio.Cancellable] passed to the relevant operation</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_is_available()</code></td>
+        <td>no equivalent, the secret service is autostarted as necessary</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_result_to_message()</code></td>
+        <td>use the message in the [struct@GLib.Error], although most failures are not appropriate for display to the user</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_RESULT_OK</code></td>
+        <td>no [struct@GLib.Error] returned</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_RESULT_DENIED</code></td>
+        <td>no longer used, item or collection is simply not unlocked</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_RESULT_NO_KEYRING_DAEMON</code></td>
+        <td><code>G_DBUS_ERROR_SPAWN_SERVICE_NOT_FOUND</code></td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_RESULT_ALREADY_UNLOCKED</code></td>
+        <td>no error, success returned</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_RESULT_NO_SUCH_KEYRING</code></td>
+        <td>keyrings no longer have names, accessing an missing DBus object has usual failure</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_RESULT_BAD_ARGUMENTS</code></td>
+        <td><code>G_DBUS_ERROR_INVALID_ARGS</code> or precondition failure in libsecret, this is always
+        a programmer error</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_RESULT_IO_ERROR</code></td>
+        <td>relevant DBus errors, or <code>SECRET_ERROR_PROTOCOL</code></td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_RESULT_CANCELLED</code></td>
+        <td><code>G_IO_ERROR_CANCELLED</code></td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_RESULT_KEYRING_ALREADY_EXISTS</code></td>
+        <td>no error, simply returns already existing keyring</td>
+    </tr>
+    <tr>
+        <td><code>GNOME_KEYRING_RESULT_NO_MATCH</code></td>
+        <td>on error, an empty list is returned</td>
+    </tr>
+    <tr>
+        <td><code>gnome_keyring_string_list_free()</code></td>
+        <td>no equivalent</td>
+    </tr>
+</table>
diff --git a/docs/reference/libsecret/migrating-libgnome-keyring.xml b/docs/reference/libsecret/migrating-libgnome-keyring.xml
deleted file mode 100644
index 7f727ec..0000000
--- a/docs/reference/libsecret/migrating-libgnome-keyring.xml
+++ /dev/null
@@ -1,839 +0,0 @@
-<part id="migrating">
-<title>Migrating from libgnome-keyring</title>
-
-<chapter id="migrating-introduction">
-	<title>Introduction</title>
-
-	<para>Conceptually, libgnome-keyring and libsecret are fairly similar. Both
-	have keyrings, items, and ways to store and retrieve passwords. In both
-	cases items have attributes. The keys and values of attributes are used
-	to lookup a password that was stored.</para>
-
-	<para>There is a
-	<link linkend="libsecret-Password-storage">simple password API for storing and retrieving passwords</link>
-	which is the easiest and recommended way to store passwords. And then
-	there is a more complicated API which models all the various collections
-	and items, along with all the possible actions that can be performed on them.</para>
-
-	<para>libsecret uses the
-	<ulink url="http://standards.freedesktop.org/secret-service/">Secret Service DBus API</ulink>
-	to communicate with gnome-keyring-daemon, and as such exposes features
-	based on that DBus API.</para>
-
-	<para>libsecret has been designed to be threadsafe, and uses the 'GDBus'
-	code in gio to accomplish this.</para>
-
-	<para>Keyrings are called 'collections' in libsecret.</para>
-
-	<para>See the relevant section for specifics about how to port the
-	libgnome-keyring functions or symbols in your project.</para>
-</chapter>
-
-<chapter id="migrating-api">
-	<title>API conversion</title>
-	<para>Here are some clues on how to migrate various libgnome-keyring
-	API functions and their logical equivalents in libsecret.</para>
-
-<section id="migrating-attributes">
-	<title>Item attributes</title>
-
-	<para>Remember that attributes are not, and never have been stored in
-	an encrypted fashion. They are not part of the 'secret', but instead
-	are a way to lookup a secret item.</para>
-
-	<para>All attributes in libsecret are stored as strings. Sets of attributes
-	are represented by #GHashTable<!-- -->s and the keys and values of 
-	these hash tables are strings.</para>
-
-	<para>libsecret is far more <link linkend="migrating-schemas">focused on schemas</link>,
-	and encourages users to define a #SecretSchema for their password storage.
-	The schema defines which attributes are allowed an item. Each schema has
-	a name which is usually a dotted string (eg: <literal>org.gnome.MyProject.Password</literal>).
-	This schema name is stored internally in the item attributes.</para>
-
-	<para>Schemas define whether an attribute should look like an integer,
-	a boolean, or a free-form string. These types are used when validating
-	the attribute values, even though the attribute values are stored and
-	matched as strings. Since attribute values are used primarily
-	for lookup of items it's important that the string representations of
-	integers and booleans are always identical. Boolean values are stored
-	as the strings <literal>true</literal> and <literal>false</literal>.
-	Integer values are stored in decimal, with a preceding negative sign
-	for negative integers. libsecret facilitates this using the
-	secret_attributes_build() and secret_attributes_buildv() functions.</para>
-
-	<para>Attributes are meant to be used for lookup of items; they're not
-	designed to be used as a generic key/value database. Although you can
-	force libsecret to do the latter, it's better to store your account
-	information elsewhere if possible, and use libsecret to store the password
-	or other secret.</para>
-
-	<para>Replacements for related libgnome-keyring functions and types
-	are described below:
-	<table><tgroup cols="2">
-	<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
-	<tbody>
-		<row>
-			<entry>#GnomeKeyringAttributeList</entry>
-			<entry>a #GHashTable of string keys and values</entry>
-		</row>
-		<row>
-			<entry>#GnomeKeyringAttribute</entry>
-			<entry>a key/value pair in a #GHashTable of strings</entry>
-		</row>
-		<row>
-			<entry>#GnomeKeyringAttributeType</entry>
-			<entry>#SecretSchemaAttributeType</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_ATTRIBUTE_TYPE_STRING</entry>
-			<entry>%SECRET_SCHEMA_ATTRIBUTE_STRING</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_ATTRIBUTE_TYPE_UINT32</entry>
-			<entry>%SECRET_SCHEMA_ATTRIBUTE_INTEGER</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_attribute_list_index()</entry>
-			<entry>use g_hash_table_lookup() on the attributes hash table</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_attribute_get_string()</entry>
-			<entry>use g_hash_table_lookup() on the attributes hash table</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_attribute_get_uint32()</entry>
-			<entry>no equivalent, use g_hash_table_lookup()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_attribute_list_append_string()</entry>
-			<entry>secret_attributes_build()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_attribute_list_append_uint32()</entry>
-			<entry>secret_attributes_build()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_attribute_list_copy()</entry>
-			<entry>g_hash_table_ref()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_attribute_list_free()</entry>
-			<entry>g_hash_table_unref()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_attribute_list_index()</entry>
-			<entry>no equivalent, use g_hash_table_lookup()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_attribute_list_new()</entry>
-			<entry>secret_attributes_build()</entry>
-		</row>
-	</tbody>
-	</tgroup></table></para>
-</section>
-
-<section id="migrating-schemas">
-	<title>Working with schemas</title>
-
-	<para>libsecret is far more focused on schemas, and encourages users to
-	define a #SecretSchema for their password storage. The schema defines
-	which attributes are allowed an item. Each schema has a name which
-	is usually a dotted string (eg: <literal>org.gnome.MyProject.Password</literal>).
-	This name is stored in the item attributes. The schema name is also
-	used when looking up an item, to make sure that the stored schema
-	matches that used during the lookup. If you wish to lookup items that
-	were stored by libgnome-keyring, you should specify the 
-	%SECRET_SCHEMA_DONT_MATCH_NAME flag in the schema so that the schema
-	name is not matched, since it was not stored by libgnome-keyring.</para>
-
-	<para>Schemas define whether an attribute should look like an integer,
-	a boolean, or a free-form string. These types are used when validating
-	the attribute values stored, even though the attribute values are
-	stored and matched as strings.</para>
-
-	<para>Replacements for related libgnome-keyring functions and types
-	are described below:
-	<table><tgroup cols="2">
-	<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
-	<tbody>
-		<row>
-			<entry>#GnomeKeyringPasswordSchema</entry>
-			<entry>#SecretSchema</entry>
-		</row>
-		<row>
-			<entry>#GnomeKeyringPasswordSchemaAttribute</entry>
-			<entry>#SecretSchemaAttribute</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_ITEM_APPLICATION_SECRET</entry>
-			<entry>no equivalent</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_ITEM_CHAINED_KEYRING_PASSWORD</entry>
-			<entry>no equivalent</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_ITEM_ENCRYPTION_KEY_PASSWORD</entry>
-			<entry>no equivalent</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_ITEM_PK_STORAGE</entry>
-			<entry>no equivalent</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_ITEM_GENERIC_SECRET</entry>
-			<entry>no equivalent, define a specific schema with an appropriate dotted name</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_ITEM_NETWORK_PASSWORD</entry>
-			<entry>the %SECRET_SCHEMA_COMPAT_NETWORK schema, although not recommended for new uses</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_ITEM_NOTE</entry>
-			<entry>the %SECRET_SCHEMA_NOTE schema</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_NETWORK_PASSWORD</entry>
-			<entry>the %SECRET_SCHEMA_COMPAT_NETWORK schema, although not recommended for new uses</entry>
-		</row>
-	</tbody>
-	</tgroup></table></para>
-</section>
-
-
-<section id="migrating-storing">
-	<title>Storing passwords and items</title>
-
-	<para>It's encouraged to use a #SecretSchema when storing items and
-	passwords.</para>
-
-	<para>By default most ways of storing an item will now overwrite
-	another item with the same attributes in the same keyring. To manually
-	control this behavior use the secret_item_create().</para>
-
-	<para>Replacements for related libgnome-keyring functions and types
-	are described below:
-	<table><tgroup cols="2">
-	<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
-	<tbody>
-		<row>
-			<entry>%GNOME_KEYRING_DEFAULT</entry>
-			<entry>%SECRET_COLLECTION_DEFAULT</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_SESSION</entry>
-			<entry>%SECRET_COLLECTION_SESSION</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_store_password()</entry>
-			<entry>secret_password_store()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_store_password_sync()</entry>
-			<entry>secret_password_store_sync()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_set_network_password()</entry>
-			<entry>secret_password_store() with %SECRET_SCHEMA_COMPAT_NETWORK
-			although this is not recommended for new uses.</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_set_network_password_sync()</entry>
-			<entry>secret_password_store_sync() with %SECRET_SCHEMA_COMPAT_NETWORK
-			although this is not recommended for new uses.</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_create()</entry>
-			<entry>secret_item_create(), although using secret_password_store()
-			is simpler.</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_create_sync()</entry>
-			<entry>secret_item_create(), although using secret_password_store_sync()
-			is simpler.</entry>
-		</row>
-	</tbody>
-	</tgroup></table></para>
-</section>
-
-<section id="migrating-searching">
-	<title>Searching for passwords and items</title>
-
-	<para>In general libsecret tries not to unlocking keyrings
-	where not necessary. Many search methods only return one item or
-	password that matches, preferring already unlocked items, and recently stored
-	items.</para>
-
-	<para>Attributes are meant to be used for lookup of items; they're not
-	designed to be used as a generic key/value database. Although you can
-	force libsecret to do the latter, it's better to store your account
-	information elsewhere if possible, and use libsecret to store the password
-	or other secret. Because of this many search methods return just the
-	password or secret.</para>
-
-	<para>Replacements for related libgnome-keyring functions and types
-	are described below:
-	<table><tgroup cols="2">
-	<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
-	<tbody>
-		<row>
-			<entry>gnome_keyring_find_password()</entry>
-			<entry>secret_password_lookup()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_find_password_sync()</entry>
-			<entry>secret_password_lookup_sync()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_find_items()</entry>
-			<entry>secret_service_search(), with flags to fine tune behavior</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_find_itemsv()</entry>
-			<entry>secret_service_search(), with flags to fine tune behavior</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_find_items_sync()</entry>
-			<entry>secret_service_search_sync(), with flags to fine tune behavior</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_find_itemsv_sync()</entry>
-			<entry>secret_service_search(), with flags to fine tune behavior</entry>
-		</row>
-		<row>
-			<entry>GnomeKeyringFound</entry>
-			<entry>no equivalent, secret_service_search() returns a #GList of
-			#SecretItem<!-- -->s, and other methods return passwords directly.</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_found_copy()</entry>
-			<entry>no equivalent</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_found_free()</entry>
-			<entry>g_object_unref() on the each of the items returned from
-			secret_service_search()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_found_list_free()</entry>
-			<entry>g_list_free_full() used with g_object_unref() on the items returned from
-			secret_service_search()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_find_network_password()</entry>
-			<entry>secret_password_lookup() with %SECRET_SCHEMA_COMPAT_NETWORK,
-			although this only returns one password and no attributes</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_find_network_password_sync()</entry>
-			<entry>secret_password_lookup_sync() with %SECRET_SCHEMA_COMPAT_NETWORK,
-			although this only returns one password and no attributes</entry>
-		</row>
-		<row>
-			<entry>#GnomeKeyringNetworkPasswordData</entry>
-			<entry>no equivalent, secret_password_lookup() gets the password directly
-			and no attributes</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_network_password_free()</entry>
-			<entry>no equivalent</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_network_password_list_free()</entry>
-			<entry>no equivalent</entry>
-		</row>
-	</tbody>
-	</tgroup></table></para>
-</section>
-
-<section id="migrating-removing">
-	<title>Removing passwords and icons</title>
-
-	<para>Neither libgnome-keyring or libsecret allow deletion of locked
-	items. libsecret tries to make it easier to delete all unlocked items
-	matching certain attributes.</para>
-
-	<para>Replacements for related libgnome-keyring functions and types
-	are described below:
-	<table><tgroup cols="2">
-	<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
-	<tbody>
-		<row>
-			<entry>gnome_keyring_delete_password()</entry>
-			<entry>secret_password_clear(), although we now try to delete
-			all unlocked matching items</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_delete_password_sync()</entry>
-			<entry>secret_password_clear_sync(), although we now try to delete
-			all unlocked matching items</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_delete()</entry>
-			<entry>secret_item_delete()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_delete_sync()</entry>
-			<entry>secret_item_delete_sync()</entry>
-		</row>
-	</tbody>
-	</tgroup></table></para>
-</section>
-
-<section id="migrating-items">
-	<title>Item management</title>
-
-	<para>In libsecret items are no longer identified by an unsigned integer.
-	Applications should retrieve items based on their attributes. It is also
-	possible to identify an item by its DBus object path.</para>
-
-	<para>Replacements for related libgnome-keyring functions and types
-	are described below:
-	<table><tgroup cols="2">
-	<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
-	<tbody>
-		<row>
-			<entry>gnome_keyring_item_create()</entry>
-			<entry>secret_item_create(), although secret_password_store() may be simpler</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_create_sync()</entry>
-			<entry>secret_item_create_sync(), although secret_password_store_sync() may be simpler</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_delete()</entry>
-			<entry>secret_item_delete(), although secret_password_clear() may be simpler</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_delete_sync()</entry>
-			<entry>secret_item_delete_sync(), although secret_password_clear_sync() may be simpler</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_get_info()</entry>
-			<entry>properties are loaded on a #SecretItem automatically, use
-			secret_item_load_secret() to load the secret</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_get_info_sync()</entry>
-			<entry>properties are loaded on a #SecretItem automatically, use
-			secret_item_load_secret_sync() to load the secret</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_get_info_full()</entry>
-			<entry>properties are loaded on a #SecretItem automatically, use
-			secret_item_load_secret() to load the secret</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_get_info_full_sync()</entry>
-			<entry>properties are loaded on a #SecretItem automatically, use
-			secret_item_load_secret_sync() to load the secret</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_set_info()</entry>
-			<entry>use the appropriate setter methods on #SecretItem</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_set_info_sync()</entry>
-			<entry>use the appropriate setter methods on #SecretItem</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_get_attributes()</entry>
-			<entry>secret_item_get_attributes()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_get_attributes_sync()</entry>
-			<entry>secret_item_get_attributes()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_set_attributes()</entry>
-			<entry>secret_item_set_attributes()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_set_attributes_sync()</entry>
-			<entry>secret_item_set_attributes_sync()</entry>
-		</row>
-		<row>
-			<entry>#GnomeKeyringItemType</entry>
-			<entry>replaced by the name of a #SecretSchema</entry>
-		</row>
-		<row>
-			<entry>#GnomeKeyringItemInfo</entry>
-			<entry>#SecretItem</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_info_new()</entry>
-			<entry>no equivalent</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_info_copy()</entry>
-			<entry>no equivalent</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_info_free()</entry>
-			<entry>g_object_unref() on the #SecretItem</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_info_get_display_name()</entry>
-			<entry>secret_item_get_label()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_info_set_display_name()</entry>
-			<entry>secret_item_set_label()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_info_get_ctime()</entry>
-			<entry>secret_item_get_created()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_info_get_mtime()</entry>
-			<entry>secret_item_get_modified()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_info_get_type()</entry>
-			<entry>secret_item_get_schema_name()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_info_set_type()</entry>
-			<entry>secret_item_set_attributes() with appropriate schema</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_info_get_secret()</entry>
-			<entry>secret_item_get_secret()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_info_set_secret()</entry>
-			<entry>secret_item_set_secret() and secret_item_set_secret_sync()</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_ITEM_INFO_BASICS</entry>
-			<entry>no equivalent, all basic item properties are loaded on #SecretItem
-			automatically</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_ITEM_INFO_SECRET</entry>
-			<entry>use secret_item_load_secret() and secret_item_load_secret_sync() to load
-			the secret for an item.</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_item_info_set_display_name()</entry>
-			<entry></entry>
-		</row>
-	</tbody>
-	</tgroup></table></para>
-</section>
-
-<section id="migrating-keyrings">
-	<title>Keyring management</title>
-
-	<para>In libsecret keyrings are called 'collections'. This is the same
-	lingo as the underlying Secret Service DBus API. Keyrings are no longer
-	identified by simple keyring names. Normally applications just use the
-	default keyrings and these are identified by the aliases
-	%SECRET_COLLECTION_DEFAULT and %SECRET_COLLECTION_SESSION. It is also
-	possible to identify collections by their DBus object paths.</para>
-
-	<para>Replacements for related libgnome-keyring functions and types
-	are described below:
-	<table><tgroup cols="2">
-	<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
-	<tbody>
-		<row>
-			<entry>gnome_keyring_create()</entry>
-			<entry>secret_collection_create()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_create_sync()</entry>
-			<entry>secret_collection_create_sync()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_delete()</entry>
-			<entry>secret_collection_delete()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_delete_sync()</entry>
-			<entry>secret_collection_delete_sync()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_change_password()</entry>
-			<entry>no equivalent, use platform specific DBus APIs</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_change_password_sync()</entry>
-			<entry>no equivalent, use platform specific DBus APIs</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_list_keyring_names()</entry>
-			<entry>secret_service_load_collections() and secret_service_get_collections()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_list_keyring_names_sync()</entry>
-			<entry>secret_service_load_collections_sync() and secret_service_get_collections()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_set_default_keyring()</entry>
-			<entry>secret_service_set_alias()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_set_default_keyring_sync()</entry>
-			<entry>secret_service_set_alias_sync()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_get_default_keyring()</entry>
-			<entry>secret_collection_for_alias() with %SECRET_COLLECTION_DEFAULT</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_get_default_keyring_sync()</entry>
-			<entry>secret_collection_for_alias_sync() with %SECRET_COLLECTION_DEFAULT</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_list_item_ids()</entry>
-			<entry>secret_collection_load_items() and secret_collection_get_items()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_list_item_ids_sync()</entry>
-			<entry>secret_collection_load_items_sync() and secret_collection_get_items()</entry>
-		</row>
-		<row>
-			<entry>#GnomeKeyringInfo</entry>
-			<entry>#SecretCollection and properties</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_get_info()</entry>
-			<entry>no equivalent</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_get_info_sync()</entry>
-			<entry>no equivalent</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_set_info()</entry>
-			<entry>no equivalent, use property setters on #SecretCollection</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_set_info_sync()</entry>
-			<entry>no equivalent, use property setters on #SecretCollection</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_info_free()</entry>
-			<entry>no equivalent</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_info_copy()</entry>
-			<entry>no equivalent</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_info_set_lock_on_idle()</entry>
-			<entry>no equivalent</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_info_get_lock_on_idle()</entry>
-			<entry>no equivalent</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_info_set_lock_timeout()</entry>
-			<entry>no equivalent</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_info_get_lock_timeout()</entry>
-			<entry>no equivalent</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_info_get_mtime()</entry>
-			<entry>secret_collection_get_modified()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_info_get_ctime()</entry>
-			<entry>secret_collection_get_created()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_info_get_is_locked()</entry>
-			<entry>secret_collection_get_locked()</entry>
-		</row>
-	</tbody>
-	</tgroup></table></para>
-</section>
-
-<section id="migrating-locking">
-	<title>Locking and unlocking</title>
-
-	<para>In libsecret you can unlock items directly, and the result is
-	(with gnome-keyring daemon) that the enclosing collection will be unlocked.</para>
-
-	<para>It is no longer possible to pass a password to unlock keyrings.
-	These are automatically prompted for.</para>
-
-	<para>Replacements for related libgnome-keyring functions and types
-	are described below:
-	<table><tgroup cols="2">
-	<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
-	<tbody>
-		<row>
-			<entry>gnome_keyring_unlock()</entry>
-			<entry>secret_service_unlock()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_unlock_sync()</entry>
-			<entry>secret_service_unlock_sync()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_lock()</entry>
-			<entry>secret_service_lock()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_lock_sync()</entry>
-			<entry>secret_service_lock_sync()</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_lock_all()</entry>
-			<entry>no equivalent, use platform specific DBus APIs</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_lock_all_sync()</entry>
-			<entry>no equivalent, use platform specific DBus APIs</entry>
-		</row>
-	</tbody>
-	</tgroup></table></para>
-</section>
-
-<section id="migrating-memory">
-	<title>Non-pageable memory</title>
-
-	<para>libsecret no longer provides a full API for using non-pageable
-	memory. Use the <ulink url="http://developer.gnome.org/gcr/stable/gcr-Non-pageable-Memory.html">equivalent API in the Gcr library</ulink>.</para>
-
-	<para>You can request that passwords are returned in non-pageable
-	memory by using the secret_password_lookup_nonpageable_sync() and
-	secret_password_lookup_nonpageable_finish() functions.
-	In addition the contents of #SecretValue items is stored in
-	non-pageable memory, unless the system doesn't support this.</para>
-
-	<para>Replacements for related libgnome-keyring functions and types
-	are described below:
-	<table><tgroup cols="2">
-	<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
-	<tbody>
-		<row>
-			<entry>gnome_keyring_memory_alloc()</entry>
-			<entry>no equivalent, use Gcr</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_memory_free()</entry>
-			<entry>secret_password_free(), although this only works on strings</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_memory_is_secure()</entry>
-			<entry>no equivalent, use Gcr</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_memory_new()</entry>
-			<entry>no equivalent, use Gcr</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_memory_realloc()</entry>
-			<entry>no equivalent, use Gcr</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_memory_strdup()</entry>
-			<entry>no equivalent, use #SecretValue which is ref-counted, or use Gcr</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_memory_try_alloc()</entry>
-			<entry>no equivalent, use Gcr</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_memory_try_realloc()</entry>
-			<entry>no equivalent, use Gcr</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_free_password()</entry>
-			<entry>secret_password_free()</entry>
-		</row>
-	</tbody>
-	</tgroup></table></para>
-</section>
-
-<section id="migrating-misc">
-	<title>Errors and cancellation</title>
-
-	<para>libsecret uses standard the standard #GCancellable idiom
-	to cancel operations.</para>
-
-	<para>It is not necessary to check whether the keyring daemon is
-	available before using it. It is started automatically.</para>
-
-	<para>Errors are returned as standard #GError in the usual way.
-	There are fewer errors that are worth handling in an intelligent way,
-	exceptions are in the #SecretError enumeration. It is not recommended
-	to display any #GError message returned by libsecret to the user. Most
-	of the possible errors are DBus communication problems or similar.</para>
-
-	<para>Replacements for related libgnome-keyring functions and types
-	are described below:
-	<table><tgroup cols="2">
-	<thead><row><entry>libgnome-keyring</entry><entry>libsecret</entry></row></thead>
-	<tbody>
-		<row>
-			<entry>gnome_keyring_cancel_request()</entry>
-			<entry>g_cancellable_cancel() on a #GCancellable passed to the relevant operation</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_is_available()</entry>
-			<entry>no equivalent, the secret service is autostarted as necessary</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_result_to_message()</entry>
-			<entry>use the message in the #GError, although most failures are not appropriate for display to the user</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_RESULT_OK</entry>
-			<entry>no #GError returned</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_RESULT_DENIED</entry>
-			<entry>no longer used, item or collection is simply not unlocked</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_RESULT_NO_KEYRING_DAEMON</entry>
-			<entry>%G_DBUS_ERROR_SPAWN_SERVICE_NOT_FOUND</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_RESULT_ALREADY_UNLOCKED</entry>
-			<entry>no error, success returned</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_RESULT_NO_SUCH_KEYRING</entry>
-			<entry>keyrings no longer have names, accessing an missing DBus object has usual failure</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_RESULT_BAD_ARGUMENTS</entry>
-			<entry>%G_DBUS_ERROR_INVALID_ARGS or precondition failure in libsecret, this is always
-			a programmer error</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_RESULT_IO_ERROR</entry>
-			<entry>relevant DBus errors, or %SECRET_ERROR_PROTOCOL</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_RESULT_CANCELLED</entry>
-			<entry>%G_IO_ERROR_CANCELLED</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_RESULT_KEYRING_ALREADY_EXISTS</entry>
-			<entry>no error, simply returns already existing keyring</entry>
-		</row>
-		<row>
-			<entry>%GNOME_KEYRING_RESULT_NO_MATCH</entry>
-			<entry>on error, an empty list is returned</entry>
-		</row>
-		<row>
-			<entry>gnome_keyring_string_list_free()</entry>
-			<entry>no equivalent</entry>
-		</row>
-	</tbody>
-	</tgroup></table></para>
-</section>
-
-</chapter>
-
-</part>
diff --git a/docs/reference/libsecret/urlmap.js b/docs/reference/libsecret/urlmap.js
new file mode 100644
index 0000000..67e8a25
--- /dev/null
+++ b/docs/reference/libsecret/urlmap.js
@@ -0,0 +1,6 @@
+// A map between namespaces and base URLs for their online documentation
+baseURLs = [
+    [ 'GLib', 'https://docs.gtk.org/glib/' ],
+    [ 'GObject', 'https://docs.gtk.org/gobject/' ],
+    [ 'Gio', 'https://docs.gtk.org/gio/' ],
+]
diff --git a/docs/reference/libsecret/version-major.xml.in b/docs/reference/libsecret/version-major.xml.in
deleted file mode 100644
index e9450db..0000000
--- a/docs/reference/libsecret/version-major.xml.in
+++ /dev/null
@@ -1 +0,0 @@
-@SECRET_MAJOR@
\ No newline at end of file
diff --git a/docs/reference/libsecret/version.xml.in b/docs/reference/libsecret/version.xml.in
deleted file mode 100644
index 27323da..0000000
--- a/docs/reference/libsecret/version.xml.in
+++ /dev/null
@@ -1 +0,0 @@
-@VERSION@
\ No newline at end of file