docbook based spec docs

ext/pdo/specs/Makefile.in

@@ -0,0 +1,51 @@
+# vim:ts=2:sw=2:noet:
+XSLTPROC=@XSLTPROC@ --nonet
+HERE=@HERE@
+TAR=@TAR@
+SED=@SED@
+BASH=@BASH@
+AWK=@AWK@
+BUILDDIR=@srcdir@/build
+GMAKE=@GMAKE@
+BITS=$(BUILDDIR)/bits
+
+.PHONY: book.xml.in
+
+XML_CATALOG_FILES=$(BUILDDIR)/docbook-xsl/catalog.xml $(BUILDDIR)/docbook-xml/catalog.xml
+SGML_CATALOG_FILES=$(XML_CATALOG_FILES)
+export XML_CATALOG_FILES FOP SGML_CATALOG_FILES SED TAR
+
+all: docbook-env book.xml html
+
+docbook-env: $(BUILDDIR)/docbook-xsl $(BUILDDIR)/docbook-xml $(BUILDDIR)/bits
+
+$(BUILDDIR)/bits:
+	mkdir $(BUILDDIR)/bits
+
+# need to touch the dir because the timestamp in the tarball
+# is older than that of the tarball :)
+build/docbook-xsl: $(BUILDDIR)/docbook-xsl-1.69.1.tgz
+	cd $(BUILDDIR) && $(TAR) xzf docbook-xsl-1.69.1.tgz && touch docbook-xsl
+
+build/docbook-xml: $(BUILDDIR)/docbook-xml-4.4.tgz
+	cd $(BUILDDIR) && $(TAR) xzf docbook-xml-4.4.tgz && touch docbook-xml
+
+clean:
+	-rm *.fo html/*.html book.xml
+
+# Build the docs in HTML format
+html: html/index.html html/big.html
+
+html/big.html: book.xml
+	$(XSLTPROC) --xinclude --output html/big.html $(BUILDDIR)/html-big.xsl book.xml
+
+html/index.html: book.xml
+	$(XSLTPROC) --xinclude --output html/index.html $(BUILDDIR)/html.xsl book.xml
+
+check: book.xml
+	xmllint --xinclude --nonet --noout --postvalid book.xml
+
+book.xml: $(BUILDDIR)/docbook-xsl $(BUILDDIR)/docbook-xml book.xml.in
+	sed -e "s/@PUBDATE@/`date`/g;" < book.xml.in > $(BITS)/book.xml
+	$(XSLTPROC) --output book.xml $(BUILDDIR)/docbook-xsl/profiling/profile.xsl $(BITS)/book.xml
+

ext/pdo/specs/README

@@ -1,3 +1,11 @@
 Work on the PDO specification to live here
 
+How to build:
+
+You need some unixy tools, including libxml2 (which provides xsltproc), make
+and autoconf.
+
+% autoconf
+% ./configure
+% make
 

ext/pdo/specs/book.xml.in

@@ -0,0 +1,49 @@
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
+>
+<book id="skel" lang="en"
+    xmlns:xi="http://www.w3.org/2001/XInclude" 
+  >
+
+  <bookinfo>
+    <title>PDO Specification</title>
+    <!-- subtitle></subtitle -->
+    <edition>Version 1</edition>
+    <pubdate>@PUBDATE@</pubdate>
+
+    <author>
+      <firstname>Wez</firstname>
+      <surname>Furlong</surname>
+      <affiliation>
+        <jobtitle>Lead Architect</jobtitle>
+        <orgname>OmniTI Computer Consulting, Inc.</orgname>
+      </affiliation>
+    </author>
+
+    <copyright>
+      <year>2004</year>
+      <year>2005</year>
+      <year>2006</year>
+      <year>2007</year>
+      <holder>Wez Furlong</holder>
+    </copyright>
+    <copyright>
+      <year>2005</year>
+      <year>2006</year>
+      <year>2007</year>
+      <holder>OmniTI, Inc.</holder>
+    </copyright>
+
+  </bookinfo>
+
+  <xi:include href="preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+  <xi:include href="overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+  <xi:include href="drivers/all.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+  <xi:include href="userspace/all.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
+  <index id="the.index"/>
+</book>
+<!--
+vim:ts=2:sw=2:et:
+-->

ext/pdo/specs/build/html-big.xsl

@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
+                xmlns:fo="http://www.w3.org/1999/XSL/Format"   
+				version="1.0">
+
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/onechunk.xsl"/>
+	<xsl:param name="use.extensions">0</xsl:param>
+	<xsl:param name="use.id.as.filename">0</xsl:param>
+	<xsl:param name="root.filename">big</xsl:param>
+	<xsl:param name="base.dir">./</xsl:param>
+	<xsl:param name="chunk.fast">1</xsl:param>
+	<xsl:param name="make.valid.html">1</xsl:param>
+	<xsl:param name="section.autolabel">1</xsl:param>
+	<xsl:param name="generate.index">1</xsl:param>
+	<xsl:param name="section.label.includes.component.label">1</xsl:param>
+	<xsl:param name="chunker.output.indent">yes</xsl:param>
+	<xsl:param name="chunker.output.encoding">UTF-8</xsl:param>
+	<xsl:param name="chunk.first.sections">0</xsl:param>
+	<xsl:param name="chunk.tocs.and.lots">0</xsl:param>
+	<xsl:param name="html.extra.head.links">1</xsl:param>
+	<xsl:param name="generate.manifest">0</xsl:param>
+	<xsl:param name="admon.graphics">0</xsl:param>
+	<xsl:param name="admon.style"></xsl:param>
+	<xsl:param name="html.stylesheet">/docbook/style.css</xsl:param>
+	<xsl:param name="header.rule">0</xsl:param>
+	<xsl:param name="footer.rule">0</xsl:param>
+	<xsl:param name="funcsynopsis.style">ansi</xsl:param>
+	<xsl:param name="callout.graphics.path">/docbook/images/callouts/</xsl:param>
+	<xsl:param name="admon.graphics.path">/docbook/images/</xsl:param>
+
+
+
+<xsl:template match="sect1[@role = 'NotInToc']"  mode="toc" />
+<xsl:template match="sect2[@role = 'NotInToc']"  mode="toc" />
+
+</xsl:stylesheet>
+<!--
+vim:ts=2:sw=2:et:
+-->

ext/pdo/specs/build/html.xsl

@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 
+                xmlns:fo="http://www.w3.org/1999/XSL/Format"   
+				version="1.0">
+
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"/>
+<!-- xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/profile-chunk.xsl"/ -->
+	<xsl:param name="use.extensions">0</xsl:param>
+	<xsl:param name="use.id.as.filename">1</xsl:param>
+	<xsl:param name="base.dir">./</xsl:param>
+	<xsl:param name="chunk.fast">1</xsl:param>
+	<xsl:param name="make.valid.html">1</xsl:param>
+	<xsl:param name="section.autolabel">1</xsl:param>
+	<xsl:param name="generate.index">1</xsl:param>
+	<xsl:param name="section.label.includes.component.label">1</xsl:param>
+	<xsl:param name="chunker.output.indent">yes</xsl:param>
+	<xsl:param name="chunker.output.encoding">UTF-8</xsl:param>
+	<xsl:param name="chunk.first.sections">0</xsl:param>
+	<xsl:param name="chunk.tocs.and.lots">0</xsl:param>
+	<xsl:param name="html.extra.head.links">0</xsl:param>
+	<xsl:param name="generate.manifest">0</xsl:param>
+	<xsl:param name="admon.graphics">0</xsl:param>
+	<xsl:param name="admon.style"></xsl:param>
+	<xsl:param name="html.stylesheet">/docbook/style.css</xsl:param>
+	<xsl:param name="header.rule">0</xsl:param>
+	<xsl:param name="footer.rule">0</xsl:param>
+	<xsl:param name="toc.section.depth">1</xsl:param>
+	<xsl:param name="funcsynopsis.style">ansi</xsl:param>
+	<xsl:param name="callout.graphics.path">/docbook/images/callouts/</xsl:param>
+	<xsl:param name="admon.graphics.path">/docbook/images/</xsl:param>
+
+
+<xsl:template match="sect1[@role = 'NotInToc']"  mode="toc" />
+<xsl:template match="sect2[@role = 'NotInToc']"  mode="toc" />
+
+</xsl:stylesheet>
+<!--
+vim:ts=2:sw=2:et:
+-->

ext/pdo/specs/configure.in

@@ -0,0 +1,70 @@
+dnl vim:ts=2:sw=2:et:
+AC_INIT(Makefile.in)
+
+XSLTPROC=xsltproc
+GTAR=gtar
+TAR=tar
+SED=sed
+GSED=gsed
+BASH=bash
+AWK=awk
+
+AC_PATH_PROG(AWK, $AWK)
+AC_PATH_PROG(GAWK, gawk)
+AC_PATH_PROG(NAWK, nawk)
+AC_PATH_PROG(GTAR, $GTAR)
+AC_PATH_PROG(GSED, $GSED)
+AC_PATH_PROG(BASH, $BASH)
+
+AC_ARG_WITH(xsltproc, [  --with-xsltproc  Where to find xsltproc],
+  [
+    if test "x$withval" != "xno"; then
+      XSLTPROC="$withval"
+    fi
+  ]
+)
+AC_PATH_PROG(XSLTPROC,  $XSLTPROC)
+
+if test -x "$GTAR" ; then
+  TAR=$GTAR
+fi
+if test -x "$GSED" ; then
+  SED=$GSED
+fi
+if test -x "$GAWK" ; then
+  AWK=$GAWK
+else
+  if test -x "$NAWK" ; then
+    AWK=$NAWK
+  fi
+fi
+
+GMAKE=make
+case `uname -s` in
+  SunOS)
+    GMAKE=gmake
+    ;;
+esac
+AC_SUBST(GMAKE)
+
+AC_SUBST(TAR)
+AC_SUBST(SED)
+AC_SUBST(BASH)
+AC_SUBST(AWK)
+
+AC_SUBST(XINC)
+AC_SUBST(XEP)
+AC_SUBST(FOP)
+AC_SUBST(XSLTPROC)
+AC_SUBST(DBDOCLET)
+HERE=`pwd`
+AC_SUBST(HERE)
+AC_OUTPUT(Makefile)
+
+cat > config.nice <<EOT
+#!/bin/sh
+./configure \
+    --with-xsltproc='$XSLTPROC'
+EOT
+chmod +x config.nice
+

ext/pdo/specs/drivers/all.xml

@@ -0,0 +1,114 @@
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+
+<chapter id="drivers">
+  <title>Driver Documentation</title>
+
+  <para>
+    Any PHP extension that is linked against the PDO core module can elect to
+    register a PDO driver.  A PDO driver is represented by the
+    <type>pdo_driver_t</type> type which describes the version of PDO against
+    which the driver was built, the name of the driver and a factory method
+    that can be used to instantiate a database connection handle.  A
+    connection handle is represented by the <type>pdo_dbh_t</type> type which
+    describes, among other things, how to instantiate a prepared statement
+    handle, represented by the <type>pdo_stmt_t</type> type.
+  </para>
+
+  <para>
+    These three types are the main interface between the PDO core and a PDO
+    driver.  In this chapter, we'll refer to an imaginary skeleton driver, and
+    use <literal>SKEL</literal> as a placeholder for its various functions or
+    types.  In practice, a given database vendor will typically choose to use
+    a short, lowercase, version of the name of their database or client
+    library in place of <literal>SKEL</literal>.
+  </para>
+
+  <section id="drivers.registration">
+    <title>Driver Registration</title>
+
+    <para>
+      A driver extension will typically statically define an instance of
+      <type>pdo_driver_t</type> and pass the address of it to
+      <function>php_pdo_register_driver</function> during its module
+      initialization callback (also known as MINIT, for module init), and
+      again to <function>php_pdo_unregister_driver</function> during its
+      module shutdown callback (also known as MSHUTDOWN).
+    </para>
+
+    <para>
+      <filename>php_pdo_driver.h</filename> defines <type>pdo_driver_t</type>,
+      <function>php_pdo_register_driver</function> and
+      <function>php_pdo_unregister_driver</function> as follows:
+    </para>
+
+    <programlisting role="C"><![CDATA[
+/* This structure is registered with PDO when a PDO driver extension is
+ * initialized */
+typedef struct {
+    const char      *driver_name;
+    unsigned long   driver_name_len;
+    unsigned long   api_version; /* needs to be compatible with PDO */
+
+#define PDO_DRIVER_HEADER(name) \
+    #name, sizeof(#name)-1, \
+    PDO_DRIVER_API
+
+    /* create driver specific portion of the database handle and stash it into
+     * the dbh.  dbh contains the data source string and flags for this
+     * instance.  You MUST respect dbh->is_persistent and pass that flag to
+     * pemalloc() for all allocations that are stored in the dbh or your instance
+     * data in the db, otherwise you will crash PHP when persistent connections
+     * are used.
+     */
+    int (*db_handle_factory)(pdo_dbh_t *dbh, zval *driver_options TSRMLS_DC);
+} pdo_driver_t;
+
+/* call this in MINIT to register your PDO driver */
+PDO_API int php_pdo_register_driver(pdo_driver_t *driver);
+/* call this in MSHUTDOWN to unregister your PDO driver */
+PDO_API void php_pdo_unregister_driver(pdo_driver_t *driver);
+]]></programlisting>
+
+    <para>
+      A driver would typically use code like the following to register a
+      driver:
+    </para>
+
+    <programlisting role="C"><![CDATA[
+static pdo_driver_t SKEL_driver = {
+  PDO_DRIVER_HEADER(SKEL),
+  SKEL_db_handle_factory
+};
+
+PHP_MINIT_FUNCTION(pdo_SKEL)
+{
+  return php_pdo_register_driver(&SKEL_driver);
+}
+
+PHP_MSHUTDOWN_FUNCTION(pdo_SKEL)
+{
+  php_pdo_unregister_driver(&SKEL_driver);
+  return SUCCESS;
+}
+]]></programlisting>
+
+    <para>
+      The <function>SKEL_db_handle_factory</function> is provided by the
+      driver; its operation will be discussed in the next section.
+    </para>
+  </section>
+
+  <xi:include href="connect.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+  <xi:include href="dbh_methods.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+  <xi:include href="prepare.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+  <xi:include href="binding.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+  <xi:include href="stmt_methods.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+
+</chapter>
+
+<!--
+vim:ts=2:sw=2:et:tw=78:
+-->
+

ext/pdo/specs/drivers/binding.xml

@@ -0,0 +1,18 @@
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+
+<section id="drivers.stmt.binding">
+  <title>Parameter Binding</title>
+
+  <para>
+    This section describes the parameter (and column) binding interface in PDO.
+
+  </para>
+
+</section>
+
+<!--
+vim:ts=2:sw=2:et:tw=78:
+-->
+