--- /dev/null
+<?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 major SYSTEM "version-major.xml">
+]>
+<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-&major;</literal>". So in your
+<literal>configure.ac</literal> script,you might specify something like:</para>
+
+<informalexample><programlisting>
+PKG_CHECK_MODULES(LIBSECRET, [libsecret-&major; >= 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 <libsecret/secret.h>
+</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>
+
+<para>
+Some parts of the <application>libsecret</application> API are not yet stable.
+It is <emphasis>not</emphasis> recommended that you use these unstable parts
+from javascript. Your code <emphasis>will break</emphasis> when the unstable API
+changes, and due to the lack of a compiler you will have no way of knowing when
+it does. If you must use the unstable API, you would do it like this:
+</para>
+
+<informalexample><programlisting language="javascript">
+// Warning: if you use the unstable API from javascript, your're going to have a bad time
+const SecretUnstable = imports.gi.SecretUnstable;
+
+// ... and a here's sample line of code which uses the import
+var collection = SecretUnstable.Collection.for_alias(null, "default", null);
+</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>
+
+<para>
+Some parts of the <application>libsecret</application> API are not yet stable.
+It is <emphasis>not</emphasis> recommended that you use these unstable parts
+from python. Your code <emphasis>will break</emphasis> when the unstable API
+changes, and due to the lack of a compiler you will have no way of knowing when
+it does. If you must use the unstable API, you would do it like this:
+</para>
+
+<informalexample><programlisting language="py">
+# Warning: if you use the unstable API from python, your're going to have a bad time
+from gi.repository import SecretUnstable
+
+# ... and a here's sample line of code which uses the import
+collection = SecretUnstable.Collection.for_alias(None, "default", None);
+</programlisting></informalexample>
+
+</chapter>
+
+<chapter id="using-vala">
+<title>Vala: Compiling with libsecret</title>
+
+<para>
+The package name is "<literal>libsecret-&major;</literal>". You can use it like
+this in your <literal>Makefile.am</literal> file:
+</para>
+
+<informalexample><programlisting>
+AM_VALAFLAGS = \
+ --pkg=libsecret-&major;
+</programlisting></informalexample>
+
+<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>
+AM_VALAFLAGS = \
+ --pkg=libsecret-unstable
+</programlisting></informalexample>
+
+</chapter>
+
+</part>