Document how to build with or use libsecret

4 files changed, 151 insertions, 1 deletions

diff --git a/docs/reference/libsecret/Makefile.am b/docs/reference/libsecret/Makefile.am
index 5f05319..1ffa191 100644
--- a/docs/reference/libsecret/Makefile.am
+++ b/docs/reference/libsecret/Makefile.am
@@ -71,6 +71,7 @@ HTML_IMAGES=
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
 content_files = \
 	libsecret-examples.sgml \
+	libsecret-using.sgml \
 	migrating-libgnome-keyring.xml
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
@@ -95,7 +96,7 @@ include $(top_srcdir)/gtk-doc.make
 # e.g. EXTRA_DIST += version.xml.in
 EXTRA_DIST += \
 	version.xml.in \
-	migrating-libgnome-keyring.xml
+	version-major.in
 
 # Files not to distribute
 # for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
diff --git a/docs/reference/libsecret/libsecret-docs.sgml b/docs/reference/libsecret/libsecret-docs.sgml
index 428725a..b49a70e 100644
--- a/docs/reference/libsecret/libsecret-docs.sgml
+++ b/docs/reference/libsecret/libsecret-docs.sgml
@@ -33,6 +33,8 @@
 		<xi:include href="xml/secret-paths.xml"/>
 	</part>
 
+	<xi:include href="libsecret-using.sgml"/>
+
 	<xi:include href="xml/migrating-libgnome-keyring.xml"/>
 
 	<xi:include href="xml/annotation-glossary.xml">
diff --git a/docs/reference/libsecret/libsecret-using.sgml b/docs/reference/libsecret/libsecret-using.sgml
new file mode 100644
index 0000000..c531b15
--- /dev/null
+++ b/docs/reference/libsecret/libsecret-using.sgml
@@ -0,0 +1,146 @@
+<?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 &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>
+
+<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>
diff --git a/docs/reference/libsecret/version-major.xml.in b/docs/reference/libsecret/version-major.xml.in
new file mode 100644
index 0000000..e9450db
--- /dev/null
+++ b/docs/reference/libsecret/version-major.xml.in
@@ -0,0 +1 @@
+@SECRET_MAJOR@
\ No newline at end of file