Skip to content

Commit 8e1ef43

Browse files
wezwez
committed
docbook based spec docs
1 parent 2f1ee50 commit 8e1ef43

17 files changed

+1596
-0
lines changed

‎ext/pdo/specs/Makefile.in

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# vim:ts=2:sw=2:noet:
2+
XSLTPROC=@XSLTPROC@ --nonet
3+
HERE=@HERE@
4+
TAR=@TAR@
5+
SED=@SED@
6+
BASH=@BASH@
7+
AWK=@AWK@
8+
BUILDDIR=@srcdir@/build
9+
GMAKE=@GMAKE@
10+
BITS=$(BUILDDIR)/bits
11+
12+
.PHONY: book.xml.in
13+
14+
XML_CATALOG_FILES=$(BUILDDIR)/docbook-xsl/catalog.xml $(BUILDDIR)/docbook-xml/catalog.xml
15+
SGML_CATALOG_FILES=$(XML_CATALOG_FILES)
16+
export XML_CATALOG_FILES FOP SGML_CATALOG_FILES SED TAR
17+
18+
all: docbook-env book.xml html
19+
20+
docbook-env: $(BUILDDIR)/docbook-xsl $(BUILDDIR)/docbook-xml $(BUILDDIR)/bits
21+
22+
$(BUILDDIR)/bits:
23+
mkdir $(BUILDDIR)/bits
24+
25+
# need to touch the dir because the timestamp in the tarball
26+
# is older than that of the tarball :)
27+
build/docbook-xsl: $(BUILDDIR)/docbook-xsl-1.69.1.tgz
28+
cd $(BUILDDIR) && $(TAR) xzf docbook-xsl-1.69.1.tgz && touch docbook-xsl
29+
30+
build/docbook-xml: $(BUILDDIR)/docbook-xml-4.4.tgz
31+
cd $(BUILDDIR) && $(TAR) xzf docbook-xml-4.4.tgz && touch docbook-xml
32+
33+
clean:
34+
-rm *.fo html/*.html book.xml
35+
36+
# Build the docs in HTML format
37+
html: html/index.html html/big.html
38+
39+
html/big.html: book.xml
40+
$(XSLTPROC) --xinclude --output html/big.html $(BUILDDIR)/html-big.xsl book.xml
41+
42+
html/index.html: book.xml
43+
$(XSLTPROC) --xinclude --output html/index.html $(BUILDDIR)/html.xsl book.xml
44+
45+
check: book.xml
46+
xmllint --xinclude --nonet --noout --postvalid book.xml
47+
48+
book.xml: $(BUILDDIR)/docbook-xsl $(BUILDDIR)/docbook-xml book.xml.in
49+
sed -e "s/@PUBDATE@/`date`/g;" < book.xml.in > $(BITS)/book.xml
50+
$(XSLTPROC) --output book.xml $(BUILDDIR)/docbook-xsl/profiling/profile.xsl $(BITS)/book.xml
51+

‎ext/pdo/specs/README

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,11 @@
11
Work on the PDO specification to live here
22

3+
How to build:
4+
5+
You need some unixy tools, including libxml2 (which provides xsltproc), make
6+
and autoconf.
7+
8+
% autoconf
9+
% ./configure
10+
% make
311

‎ext/pdo/specs/book.xml.in

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
<?xml version='1.0' encoding='UTF-8' ?>
2+
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3+
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"
4+
>
5+
<book id="skel" lang="en"
6+
xmlns:xi="http://www.w3.org/2001/XInclude"
7+
>
8+
9+
<bookinfo>
10+
<title>PDO Specification</title>
11+
<!-- subtitle></subtitle -->
12+
<edition>Version 1</edition>
13+
<pubdate>@PUBDATE@</pubdate>
14+
15+
<author>
16+
<firstname>Wez</firstname>
17+
<surname>Furlong</surname>
18+
<affiliation>
19+
<jobtitle>Lead Architect</jobtitle>
20+
<orgname>OmniTI Computer Consulting, Inc.</orgname>
21+
</affiliation>
22+
</author>
23+
24+
<copyright>
25+
<year>2004</year>
26+
<year>2005</year>
27+
<year>2006</year>
28+
<year>2007</year>
29+
<holder>Wez Furlong</holder>
30+
</copyright>
31+
<copyright>
32+
<year>2005</year>
33+
<year>2006</year>
34+
<year>2007</year>
35+
<holder>OmniTI, Inc.</holder>
36+
</copyright>
37+
38+
</bookinfo>
39+
40+
<xi:include href="preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
41+
<xi:include href="overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
42+
<xi:include href="drivers/all.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
43+
<xi:include href="userspace/all.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
44+
45+
<index id="the.index"/>
46+
</book>
47+
<!--
48+
vim:ts=2:sw=2:et:
49+
-->

‎ext/pdo/specs/build/docbook-xml-4.4.tgz

74.2 KB
Binary file not shown.

‎ext/pdo/specs/build/docbook-xsl-1.69.1.tgz

831 KB
Binary file not shown.

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

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
3+
xmlns:fo="http://www.w3.org/1999/XSL/Format"
4+
version="1.0">
5+
6+
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/onechunk.xsl"/>
7+
<xsl:param name="use.extensions">0</xsl:param>
8+
<xsl:param name="use.id.as.filename">0</xsl:param>
9+
<xsl:param name="root.filename">big</xsl:param>
10+
<xsl:param name="base.dir">./</xsl:param>
11+
<xsl:param name="chunk.fast">1</xsl:param>
12+
<xsl:param name="make.valid.html">1</xsl:param>
13+
<xsl:param name="section.autolabel">1</xsl:param>
14+
<xsl:param name="generate.index">1</xsl:param>
15+
<xsl:param name="section.label.includes.component.label">1</xsl:param>
16+
<xsl:param name="chunker.output.indent">yes</xsl:param>
17+
<xsl:param name="chunker.output.encoding">UTF-8</xsl:param>
18+
<xsl:param name="chunk.first.sections">0</xsl:param>
19+
<xsl:param name="chunk.tocs.and.lots">0</xsl:param>
20+
<xsl:param name="html.extra.head.links">1</xsl:param>
21+
<xsl:param name="generate.manifest">0</xsl:param>
22+
<xsl:param name="admon.graphics">0</xsl:param>
23+
<xsl:param name="admon.style"></xsl:param>
24+
<xsl:param name="html.stylesheet">/docbook/style.css</xsl:param>
25+
<xsl:param name="header.rule">0</xsl:param>
26+
<xsl:param name="footer.rule">0</xsl:param>
27+
<xsl:param name="funcsynopsis.style">ansi</xsl:param>
28+
<xsl:param name="callout.graphics.path">/docbook/images/callouts/</xsl:param>
29+
<xsl:param name="admon.graphics.path">/docbook/images/</xsl:param>
30+
31+
32+
33+
<xsl:template match="sect1[@role = 'NotInToc']" mode="toc" />
34+
<xsl:template match="sect2[@role = 'NotInToc']" mode="toc" />
35+
36+
</xsl:stylesheet>
37+
<!--
38+
vim:ts=2:sw=2:et:
39+
-->

‎ext/pdo/specs/build/html.xsl

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
3+
xmlns:fo="http://www.w3.org/1999/XSL/Format"
4+
version="1.0">
5+
6+
<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/chunk.xsl"/>
7+
<!-- xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/profile-chunk.xsl"/ -->
8+
<xsl:param name="use.extensions">0</xsl:param>
9+
<xsl:param name="use.id.as.filename">1</xsl:param>
10+
<xsl:param name="base.dir">./</xsl:param>
11+
<xsl:param name="chunk.fast">1</xsl:param>
12+
<xsl:param name="make.valid.html">1</xsl:param>
13+
<xsl:param name="section.autolabel">1</xsl:param>
14+
<xsl:param name="generate.index">1</xsl:param>
15+
<xsl:param name="section.label.includes.component.label">1</xsl:param>
16+
<xsl:param name="chunker.output.indent">yes</xsl:param>
17+
<xsl:param name="chunker.output.encoding">UTF-8</xsl:param>
18+
<xsl:param name="chunk.first.sections">0</xsl:param>
19+
<xsl:param name="chunk.tocs.and.lots">0</xsl:param>
20+
<xsl:param name="html.extra.head.links">0</xsl:param>
21+
<xsl:param name="generate.manifest">0</xsl:param>
22+
<xsl:param name="admon.graphics">0</xsl:param>
23+
<xsl:param name="admon.style"></xsl:param>
24+
<xsl:param name="html.stylesheet">/docbook/style.css</xsl:param>
25+
<xsl:param name="header.rule">0</xsl:param>
26+
<xsl:param name="footer.rule">0</xsl:param>
27+
<xsl:param name="toc.section.depth">1</xsl:param>
28+
<xsl:param name="funcsynopsis.style">ansi</xsl:param>
29+
<xsl:param name="callout.graphics.path">/docbook/images/callouts/</xsl:param>
30+
<xsl:param name="admon.graphics.path">/docbook/images/</xsl:param>
31+
32+
33+
<xsl:template match="sect1[@role = 'NotInToc']" mode="toc" />
34+
<xsl:template match="sect2[@role = 'NotInToc']" mode="toc" />
35+
36+
</xsl:stylesheet>
37+
<!--
38+
vim:ts=2:sw=2:et:
39+
-->

‎ext/pdo/specs/configure.in

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
dnl vim:ts=2:sw=2:et:
2+
AC_INIT(Makefile.in)
3+
4+
XSLTPROC=xsltproc
5+
GTAR=gtar
6+
TAR=tar
7+
SED=sed
8+
GSED=gsed
9+
BASH=bash
10+
AWK=awk
11+
12+
AC_PATH_PROG(AWK, $AWK)
13+
AC_PATH_PROG(GAWK, gawk)
14+
AC_PATH_PROG(NAWK, nawk)
15+
AC_PATH_PROG(GTAR, $GTAR)
16+
AC_PATH_PROG(GSED, $GSED)
17+
AC_PATH_PROG(BASH, $BASH)
18+
19+
AC_ARG_WITH(xsltproc, [ --with-xsltproc Where to find xsltproc],
20+
[
21+
if test "x$withval" != "xno"; then
22+
XSLTPROC="$withval"
23+
fi
24+
]
25+
)
26+
AC_PATH_PROG(XSLTPROC, $XSLTPROC)
27+
28+
if test -x "$GTAR" ; then
29+
TAR=$GTAR
30+
fi
31+
if test -x "$GSED" ; then
32+
SED=$GSED
33+
fi
34+
if test -x "$GAWK" ; then
35+
AWK=$GAWK
36+
else
37+
if test -x "$NAWK" ; then
38+
AWK=$NAWK
39+
fi
40+
fi
41+
42+
GMAKE=make
43+
case `uname -s` in
44+
SunOS)
45+
GMAKE=gmake
46+
;;
47+
esac
48+
AC_SUBST(GMAKE)
49+
50+
AC_SUBST(TAR)
51+
AC_SUBST(SED)
52+
AC_SUBST(BASH)
53+
AC_SUBST(AWK)
54+
55+
AC_SUBST(XINC)
56+
AC_SUBST(XEP)
57+
AC_SUBST(FOP)
58+
AC_SUBST(XSLTPROC)
59+
AC_SUBST(DBDOCLET)
60+
HERE=`pwd`
61+
AC_SUBST(HERE)
62+
AC_OUTPUT(Makefile)
63+
64+
cat > config.nice <<EOT
65+
#!/bin/sh
66+
./configure \
67+
--with-xsltproc='$XSLTPROC'
68+
EOT
69+
chmod +x config.nice
70+

‎ext/pdo/specs/drivers/all.xml

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
<?xml version='1.0' encoding='UTF-8' ?>
2+
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3+
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
4+
5+
<chapter id="drivers">
6+
<title>Driver Documentation</title>
7+
8+
<para>
9+
Any PHP extension that is linked against the PDO core module can elect to
10+
register a PDO driver. A PDO driver is represented by the
11+
<type>pdo_driver_t</type> type which describes the version of PDO against
12+
which the driver was built, the name of the driver and a factory method
13+
that can be used to instantiate a database connection handle. A
14+
connection handle is represented by the <type>pdo_dbh_t</type> type which
15+
describes, among other things, how to instantiate a prepared statement
16+
handle, represented by the <type>pdo_stmt_t</type> type.
17+
</para>
18+
19+
<para>
20+
These three types are the main interface between the PDO core and a PDO
21+
driver. In this chapter, we'll refer to an imaginary skeleton driver, and
22+
use <literal>SKEL</literal> as a placeholder for its various functions or
23+
types. In practice, a given database vendor will typically choose to use
24+
a short, lowercase, version of the name of their database or client
25+
library in place of <literal>SKEL</literal>.
26+
</para>
27+
28+
<section id="drivers.registration">
29+
<title>Driver Registration</title>
30+
31+
<para>
32+
A driver extension will typically statically define an instance of
33+
<type>pdo_driver_t</type> and pass the address of it to
34+
<function>php_pdo_register_driver</function> during its module
35+
initialization callback (also known as MINIT, for module init), and
36+
again to <function>php_pdo_unregister_driver</function> during its
37+
module shutdown callback (also known as MSHUTDOWN).
38+
</para>
39+
40+
<para>
41+
<filename>php_pdo_driver.h</filename> defines <type>pdo_driver_t</type>,
42+
<function>php_pdo_register_driver</function> and
43+
<function>php_pdo_unregister_driver</function> as follows:
44+
</para>
45+
46+
<programlisting role="C"><![CDATA[
47+
/* This structure is registered with PDO when a PDO driver extension is
48+
* initialized */
49+
typedef struct {
50+
const char *driver_name;
51+
unsigned long driver_name_len;
52+
unsigned long api_version; /* needs to be compatible with PDO */
53+
54+
#define PDO_DRIVER_HEADER(name) \
55+
#name, sizeof(#name)-1, \
56+
PDO_DRIVER_API
57+
58+
/* create driver specific portion of the database handle and stash it into
59+
* the dbh. dbh contains the data source string and flags for this
60+
* instance. You MUST respect dbh->is_persistent and pass that flag to
61+
* pemalloc() for all allocations that are stored in the dbh or your instance
62+
* data in the db, otherwise you will crash PHP when persistent connections
63+
* are used.
64+
*/
65+
int (*db_handle_factory)(pdo_dbh_t *dbh, zval *driver_options TSRMLS_DC);
66+
} pdo_driver_t;
67+
68+
/* call this in MINIT to register your PDO driver */
69+
PDO_API int php_pdo_register_driver(pdo_driver_t *driver);
70+
/* call this in MSHUTDOWN to unregister your PDO driver */
71+
PDO_API void php_pdo_unregister_driver(pdo_driver_t *driver);
72+
]]></programlisting>
73+
74+
<para>
75+
A driver would typically use code like the following to register a
76+
driver:
77+
</para>
78+
79+
<programlisting role="C"><![CDATA[
80+
static pdo_driver_t SKEL_driver = {
81+
PDO_DRIVER_HEADER(SKEL),
82+
SKEL_db_handle_factory
83+
};
84+
85+
PHP_MINIT_FUNCTION(pdo_SKEL)
86+
{
87+
return php_pdo_register_driver(&SKEL_driver);
88+
}
89+
90+
PHP_MSHUTDOWN_FUNCTION(pdo_SKEL)
91+
{
92+
php_pdo_unregister_driver(&SKEL_driver);
93+
return SUCCESS;
94+
}
95+
]]></programlisting>
96+
97+
<para>
98+
The <function>SKEL_db_handle_factory</function> is provided by the
99+
driver; its operation will be discussed in the next section.
100+
</para>
101+
</section>
102+
103+
<xi:include href="connect.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
104+
<xi:include href="dbh_methods.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
105+
<xi:include href="prepare.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
106+
<xi:include href="binding.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
107+
<xi:include href="stmt_methods.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
108+
109+
</chapter>
110+
111+
<!--
112+
vim:ts=2:sw=2:et:tw=78:
113+
-->
114+

‎ext/pdo/specs/drivers/binding.xml

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<?xml version='1.0' encoding='UTF-8' ?>
2+
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3+
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
4+
5+
<section id="drivers.stmt.binding">
6+
<title>Parameter Binding</title>
7+
8+
<para>
9+
This section describes the parameter (and column) binding interface in PDO.
10+
11+
</para>
12+
13+
</section>
14+
15+
<!--
16+
vim:ts=2:sw=2:et:tw=78:
17+
-->
18+

0 commit comments

Comments
 (0)