GNOME.org
 

[seed] docs: Docbookify sqlite documentation

commit eacea92416403210cec9552338b579bf945728b2
Author: Robert Carr <racarr svn gnome org>
Date:   Mon May 18 22:30:23 2009 -0400

    docs: Docbookify sqlite documentation
---
 configure.ac                      |    1 -
 doc/modules/Makefile.am           |    5 ++-
 doc/modules/book.xml              |    3 +-
 doc/modules/readline/Makefile.am  |    1 +
 doc/modules/readline/readline.xml |    2 +-
 doc/modules/sqlite/Makefile.am    |   19 ++++++++--
 doc/modules/sqlite/sqlite.html.in |   68 -------------------------------------
 doc/modules/sqlite/sqlite.js      |   21 +++++++++++
 doc/modules/sqlite/sqlite.xml     |   58 +++++++++++++++++++++++++++++++
 9 files changed, 102 insertions(+), 76 deletions(-)

diff --git a/configure.ac b/configure.ac
index b6d34ed..444d9f7 100644
--- a/configure.ac
+++ b/configure.ac
@@ -319,7 +319,6 @@ doc/tutorial-standalone/tutorial.html
 
 doc/modules/canvas/canvas.html
 doc/modules/multiprocessing/multiprocessing.html
-doc/modules/sqlite/sqlite.html
 doc/modules/sandbox/sandbox.html
 
 doc/modules/canvas/Makefile
diff --git a/doc/modules/Makefile.am b/doc/modules/Makefile.am
index 6c103d9..b275705 100644
--- a/doc/modules/Makefile.am
+++ b/doc/modules/Makefile.am
@@ -1,7 +1,7 @@
 SUBDIRS=canvas multiprocessing readline sandbox sqlite
 
 if ENABLE_GTK_DOC
-html/index.html:
+html/index.html: book.xml sqlite/sqlite.xml sqlite/sqlite-funcs.xml readline/readline.xml readline/readline-funcs.xml
 	mkdir -p html;
 	gtkdoc-mkhtml "Seed" book.xml;
 	mv *.html *.css *.png *.sgml *.devhelp* html
@@ -12,6 +12,9 @@ book_DATA = html/index.html
 
 install-data-local:
 	cp -r html $(datadir)/doc/seed/modules
+
+CLEANFILES = html/*
 endif 
 
 
+
diff --git a/doc/modules/book.xml b/doc/modules/book.xml
index b1a9de6..3a71218 100644
--- a/doc/modules/book.xml
+++ b/doc/modules/book.xml
@@ -3,7 +3,7 @@
  <bookinfo>
     <title>Seed Modules Reference Manual</title>
     <releaseinfo>
-      Documentation for Seed 0.7.
+      Documentation for Seed 0.7 modules.
       The latest version of this documentation can be found on-line at
       <ulink role="online-location" url="http://www.gnome.org/~racarr/seed/gtk-\
 doc/index.html">http://www.gnome.org/~racarr/seed/modules/</ulink>.
@@ -11,5 +11,6 @@ doc/index.html">http://www.gnome.org/~racarr/seed/modules/</ulink>.
   </bookinfo>
  
  <xi:include href="readline/readline.xml"/>
+ <xi:include href="sqlite/sqlite.xml"/>
 
 </book>
diff --git a/doc/modules/readline/Makefile.am b/doc/modules/readline/Makefile.am
index ddcf748..4d6d5ed 100644
--- a/doc/modules/readline/Makefile.am
+++ b/doc/modules/readline/Makefile.am
@@ -3,6 +3,7 @@ EXTRA_DIST = \
 
 readline-funcs.xml: readline.js
 	../make-functions.js readline.js > readline-funcs.xml
+CLEANFILES=readline-funcs.xml
 
 readlinedocsdir = \
 	$(datadir)/doc/seed/modules/readline/html
diff --git a/doc/modules/readline/readline.xml b/doc/modules/readline/readline.xml
index 60f28cf..ab30889 100644
--- a/doc/modules/readline/readline.xml
+++ b/doc/modules/readline/readline.xml
@@ -11,7 +11,7 @@
       </affiliation>
     </author>
   </chapterinfo>
-  <title> Seed readline module documentation. </title>
+  <title>readline module.</title>
 
   <section>
     <title>API Reference</title>
diff --git a/doc/modules/sqlite/Makefile.am b/doc/modules/sqlite/Makefile.am
index 9aa5a69..7580447 100644
--- a/doc/modules/sqlite/Makefile.am
+++ b/doc/modules/sqlite/Makefile.am
@@ -1,5 +1,16 @@
-modulesdir = $(datadir)/doc/seed/modules
-modules_DATA = \
-	sqlite.html
 EXTRA_DIST = \
-	sqlite.html.in
+	sqlite.js
+
+sqlite-funcs.xml: sqlite.js
+	../make-functions.js sqlite.js > sqlite-funcs.xml
+CLEANFILES=sqlite-funcs.xml
+
+sqlitedocsdir = \
+	$(datadir)/doc/seed/modules/sqlite/html
+sqlitedocs_DATA = sqlite-funcs.xml
+
+#index.html: sqlite-funcs.xml
+#	gtkdoc-mkhtml "sqlite" sqlite.xml;
+#	mv *.html *.css *.png html
+
+#sqlitedocs_DATA = html/*
diff --git a/doc/modules/sqlite/sqlite.html.in b/doc/modules/sqlite/sqlite.html.in
deleted file mode 100644
index f4d104e..0000000
--- a/doc/modules/sqlite/sqlite.html.in
+++ /dev/null
@@ -1,68 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd";>
-<html xmlns="http://www.w3.org/1999/xhtml"; lang="en" xml:lang="en">
-<head>
-	<title>Seed sqlite Module Documentation</title>
-	<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
-	<link rel="stylesheet" href="../style.css" type="text/css" charset="utf-8" />
-	<script type="text/javascript" src="../sh.js"></script>
-    <script type="text/javascript" src="../sh_js.js"></script>
-    <link type="text/css" rel="stylesheet" href="../sh.css" />
-</head>
-<body onload="sh_highlightDocument();">
-<div id="header">Seed <i>sqlite</i> Module</div>
-<div id="subheader">v  VERSION@</div>
-<div class="section"><b>Usage</b></div>
-<p>
-In order to use functions from the sqlite module, you must first import it:
-</p>
-<pre class="sh_javascript">
-sqlite = imports.sqlite;
-</pre>
-<div class="section"><b>Enums</b></div>
-<p>
-The SQLite module provides a selection of status enums which are used as the return values of functions, and inform the calling function of the result of the operation.
-</p>
-<pre class="sh_javascript">
-sqlite.[OK, ERROR, INTERNAL, PERM ABORT, BUSY,
-        LOCKED, NOMEM, READONLY, INTERRUPT, CORRUPT,
-        NOTFOUND, FULL, CANTOPEN, PROTOCOL, EMPTY,
-        SCHEMA, TOOBIG, CONSTRAINT, MISMATCH, MISUSE,
-        NOLFS, AUTH, FORMAT, RANGE, NOTADB, ROW, DONE]
-</pre>
-<div class="section"><b>new sqlite.Database</b>(filename)</div>
-<p>
-Constructs a new sqlite.Database, opening the SQLite database in the given file (and creating the file if it doesn't exist). Returns an object; the <i>status</i> property on the returned object is one of the SQLite status enums.
-</p>
-<pre class="sh_javascript">
-var db = new sqlite.Database("people.db");
-</pre>
-<div class="section">database.<b>exec</b>(command, <i>callback</i>)</div>
-<p>
-Executes the SQLite <i>command</i> on the given database. If <i>callback</i> is defined, it is called with each table entry returned from the given command, with a single argument. The callback argument has properties on it for each value in the returned table entry.
-</p>
-<p>
-Keep in mind that, just like in C, you have to sanitize user input in your SQL before passing it to the database, otherwise it's <i>very</i> easy to craft input that can wreak havoc on your database. We plan to have a sanitization function, as well as an API similar to the C one, where you can pass values into <b>exec</b> after the command string, and they are substituted into the command <i>by</i> SQLite, so as to avoid potential injection problems.
-</p>
-<pre class="sh_javascript">
-db.exec("create table people (key INTEGER PRIMARY KEY, name TEXT," +
-                             "age INTEGER, phone TEXT);");
-db.exec("insert into people(name, age, phone) " + 
-                    "values('John Smith', 24, '555-123-4567');");
-
-function cb_print_phone(results)
-{
-    Seed.print(results.phone);
-}
-
-db.exec("select from people where name='John Smith';", cb_print_phone);
-</pre>
-<div class="section">database.<b>close</b>()</div>
-<p>
-Closes a SQLite database and syncs.
-</p>
-<pre class="sh_javascript">
-db.close();
-</pre>
-</body>
-</html>
diff --git a/doc/modules/sqlite/sqlite.js b/doc/modules/sqlite/sqlite.js
new file mode 100644
index 0000000..4489d98
--- /dev/null
+++ b/doc/modules/sqlite/sqlite.js
@@ -0,0 +1,21 @@
+funcs = [{id: "sqlite-database",
+	  title: "new sqlite.Database(filename)",
+	  description: "Constructs a new sqlite.Database",
+	  params: [
+	      {name: "filename", description: "The SQLite database to be opened (or constructed if it does not exist"}
+	  ],
+	  returns: "A new sqlite.Database object, the <parameter>status</parameter> property will be one of the SQLite status enums"
+	 },
+	 {id: "sqlite-exec",
+	  title:"database.exec(command, callback)",
+	  description: "<para>Executes the SQLite <parameter>command</parameter> on the given database. If <parameter>callback</parameter> is defined, it is called with each table entry from the given command, with a single argument. The argument has properties for each value in the returned table entry.</para><para>Keep in mind that, just like in C, it is necessary to sanitize user input in your SQL before passing it to the database.</para>",
+	  params: [
+	      {name: "command", description: "The SQLite command to evaluate"},
+	      {name: "callback", description: "The callback to invoke, should expect one argument and return nothing. <parameter>optional</parameter>"}
+	  ],
+	  returns: "An SQLite status enum representing the result of the operation"},
+	 {id: "sqlite-close",
+	  title: "database.close()",
+	  description: "Closes an SQLite database and syncs"}];
+
+
diff --git a/doc/modules/sqlite/sqlite.xml b/doc/modules/sqlite/sqlite.xml
new file mode 100644
index 0000000..d7b8a78
--- /dev/null
+++ b/doc/modules/sqlite/sqlite.xml
@@ -0,0 +1,58 @@
+<?xml version="1.0"?>
+<chapter id="sqlite-module" xmlns:xi="http://www.w3.org/2003/XInclude";>
+    <chapterinfo>
+    <author>
+      <firstname>Robert</firstname>
+      <surname>Carr</surname>
+      <affiliation>
+	<address>
+	  <email>racarr@<parameter>gnome.org</parameter></email>
+	</address>
+      </affiliation>
+    </author>
+  </chapterinfo>
+  <title>SQLite module.</title>
+  
+  <section>
+    <title>API Reference</title>
+    <para>
+      The sqlite module allows for manipulation and querying of sqlite databases.
+      <programlisting>
+	sqlite = imports.sqlite;
+      </programlisting>
+    </para>
+    
+    The SQLite module provides a selection of status enums, to be used as the return values of functions. For meanings, consult the SQLite C documentation.
+    <programlisting>
+sqlite.[OK, ERROR, INTERNAL, PERM ABORT, BUSY,
+        LOCKED, NOMEM, READONLY, INTERRUPT, CORRUPT,
+        NOTFOUND, FULL, CANTOPEN, PROTOCOL, EMPTY,
+        SCHEMA, TOOBIG, CONSTRAINT, MISMATCH, MISUSE,
+        NOLFS, AUTH, FORMAT, RANGE, NOTADB, ROW, DONE]
+    </programlisting>
+    <xi:include href="sqlite-funcs.xml"/>
+  </section>
+  <section>
+    <title>Examples</title>
+    <para>Below are several examples of using the Seed sqlite module. For additional resources, consult the examples/ folder of the Seed source</para>
+    <example id="readline-repl-example">
+      <para>This demonstrates creating a new table, populating it, and querying it for results</para>
+      <programlisting>
+sqlite = imports.sqlite;
+var db = new sqlite.Database("people.db");
+db.exec("create table people (key INTEGER PRIMARY KEY, name TEXT," +
+                             "age INTEGER, phone TEXT);");
+db.exec("insert into people(name, age, phone) " + 
+                    "values('John Smith', 24, '555-123-4567');");
+
+function cb_print_phone(results){
+    Seed.print(results.phone);
+}
+
+db.exec("select from people where name='John Smith';", cb_print_phone);
+db.close();
+      </programlisting>
+    </example>
+  </section>
+</chapter>
+
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]