[seed] [docs] Initial gtk-doc about the importer (from JS-side)

[Tim Horton <hortont src gnome org>]

commit e4992b7a74635d3bd9b592d675d3cedaa4506fc7
Author: Tim Horton <hortont424 gmail com>
Date:   Wed Jul 22 15:47:30 2009 -0400

    [docs] Initial gtk-doc about the importer (from JS-side)
    
    This and all subsequent commits should be reviewed later or by
    other eyes, as this documentation is being written on a bus...

 doc/reference/imports.sgml   |   59 ++++++++++++++++++++++++++++++++++++++++++
 doc/reference/seed-docs.sgml |    8 +++--
 2 files changed, 64 insertions(+), 3 deletions(-)
---
diff --git a/doc/reference/imports.sgml b/doc/reference/imports.sgml
new file mode 100644
index 0000000..600f1a1
--- /dev/null
+++ b/doc/reference/imports.sgml
@@ -0,0 +1,59 @@
+<refentry id="seed-importer" revision="05 Jul 2009">
+<refmeta>
+<refentrytitle>Importer</refentrytitle>
+<manvolnum>3</manvolnum>
+<refmiscinfo>SEED Library</refmiscinfo>
+</refmeta>
+
+<refnamediv>
+<refname>Importer</refname>
+<refpurpose>
+Importing gobject-introspection namespaces, native modules, and JavaScript modules
+</refpurpose>
+</refnamediv>
+  
+    <refsect1 id="git">
+      <title>Overview</title>
+      <para>The Seed importer provides a way for applications written in JavaScript to reference functions outside of the current file. This is the heart of Seed's ability to work with other parts of the GNOME stack, as well as a way to write reasonably structured and sensible complex applications from JavaScript. The importer allows access to four types of external objects:</para>
+
+      <itemizedlist>                                                                                                                                                  
+	<listitem>GObject-Introspection namespaces, which provide access to functiosn and data which were scanned using gobject-introspection from other C libraries; this is how one accesses most of the libraries of the GNOME stack from JavaScript</listitem> 
+	<listitem>Native modules, which provide a way to load arbitrary shared libraries tailored explicitly to the Seed API, which often offer much higher performance for critical code, or provide an easy way to bind code (by hand) which the introspection scanner cannot parse.</listitem>
+	<listitem>JavaScript modules, which provide a way to access (in a namespaced manner) the global object of another script, offering a simple way to modularize code written against Seed.</listitem>
+	<listitem>Directories, which simply contain, as properties on the object the importer returns, the contents of the directory. (expand, fix. this is confusing and misplaced)</listitem>
+      </itemizedlist>
+    </refsect1>
+
+    <refsect1>
+      <title>Importing GObject-Introspection namespaces</title>
+      <para>GObject-Introspection provides the metadata required in order to call functions, connect to signals, and interact with properties within any library which has been scanned. The hows and whys of introspection are outside of the scope of this article, but how to utilize this data is central to the very tenents of Seed (the minimal platform possible to interact with GObject-based libraries from a pleasant language).</para>
+      <para>The global 'imports' object represents the runtime-side portion of the importer; all of your interactions with the importer will take place through this object. Namespaces are loaded as requested, and are loaded only once throughout the lifetime of a Seed program (subsequent requests for the same namespace will return the same object provided previously). The special property 'gi' on the imports global represents the interface for loading these namespaces. A request to import Gtk might look like the following:</para>
+
+      <example>
+	<title>Using 'imports.gi' to import the Gtk namespace</title>
+<programlisting>
+Gtk = imports.gi.Gtk;
+</programlisting>
+      </example>
+
+      <para>This will import the Gtk namespace from GObject-Introspection, and assign it to the global "Gtk" object. Afterwards, Gtk-related functions can be accessed as properties of said object. Imports will <emphasis>never</emphasis> add values to the global object or affect anything outside of their namespace.</para>
+      <para>By default, 'imports.gi.NameSpace' will return the most recent installed version of the imported namespace; in order to request a different version, or to mark your program as requiring a particular version, the "imports.gi.versions.NameSpace" property can be set; the import will raise an exception if the requested version could not be loaded:</para>
+
+      <example>
+	<title>Using 'imports.gi.version' to require Clutter 0.8</title>
+<programlisting>
+imports.gi.versions.Clutter = "0.8";
+
+try
+{
+    Clutter = imports.gi.Clutter;
+}
+catch(e)
+{
+    print("Clutter 0.8 is not installed!");
+}
+</programlisting>
+      </example>
+    </refsect1>
+
+</refentry>
diff --git a/doc/reference/seed-docs.sgml b/doc/reference/seed-docs.sgml
index d725815..41d1f71 100644
--- a/doc/reference/seed-docs.sgml
+++ b/doc/reference/seed-docs.sgml
@@ -19,13 +19,15 @@
     <xi:include href="contact.sgml"/>
   </part>
   
-  <!--<part id="js">
+  <part id="js">
     <title>Seed JavaScript Reference</title>
-  </part>-->
+    <para>This is the documentation for the JavaScript runtime side of Seed.</para>
+    <xi:include href="imports.sgml" />
+  </part>
   
   <part id="api">
     <title>Seed API Reference</title>
-    <para>This is the documentation for the C API of Seed, used for embedding, and creating native C modules. For documentation on the JavaScript interface of Seed, see <ulink role="online-location" url="http://library.gnome.org/devel/seed/";>http://library.gnome.org/devel/seed/</ulink>.</para>
+    <para>This is the documentation for the C API of Seed, used for embedding, and creating native C modules.</para>
     <xi:include href="xml/seed-main.xml"/>
     <xi:include href="xml/seed-context.xml"/>
     <xi:include href="xml/seed-eval.xml"/>