gwynne Thu Jun 21 00:30:22 2007 UTC
Added files:
/phpdoc/en/internals2/structure files.xml globals.xml lifecycle.xml
modstruct.xml tests.xml
Modified files:
/phpdoc/en/internals2 intro.xml
/phpdoc/en/internals2/structure index.xml
/phpdoc/entities global.ent
Log:
- Finish DocBook5 updates in internals
- Add new content for internals2.structure section (bjori: new IDs
internals2.structure.[files|globals|lifecycle|modstruct|tests])
- Add a few entities to globals.ent for commonly repeated links
- Resurrect comments from manual.xml.in for informational purposes
http://cvs.php.net/viewvc.cgi/phpdoc/en/internals2/intro.xml?r1=1.2&r2=1.3&diff_format=u
Index: phpdoc/en/internals2/intro.xml
diff -u phpdoc/en/internals2/intro.xml:1.2 phpdoc/en/internals2/intro.xml:1.3
--- phpdoc/en/internals2/intro.xml:1.2 Wed Jun 20 22:39:07 2007
+++ phpdoc/en/internals2/intro.xml Thu Jun 21 00:30:22 2007
@@ -1,5 +1,23 @@
<?xml version="1.0" encoding="ISO-8859-1"?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
+
+<!--
+ &internals2.buildsys.index; configure options, ext_skel, config.m4,
config.w32, static vs. dynamic builds
+ &internals2.structure.index; ext_skel, module structure, globals, lifecycle,
tests
+ &internals2.memory.index; management, persistence, TSRM
+ &internals2.variables.index; zval, hashtable, references, constants
+ &internals2.funcs.index; defining, arguments, return values, passthru,
aliasing, exceptions
+ &internals2.objects.index; classes, inheritance, properties, methods,
method-function mapping
+ &internals2.resources.index; defining, creating, retrieving, destroying
+ &internals2.ini.index; defining, retrieving, changing
+ &internals2.streams.index; using, wrappers, contexts, filters
+ &internals2.pdo.index; direct port of existing PDO docs
+ &internals2.faq.index; FAQ
+ &internals2.apiref.index; full index of all APIs, constants, macros, etc.
+ &internals2.ze1.index; old docs, quick list of major differences,
short discussion re: OOP
+ &internals2.ze3.index; quick discussion of major changes, some details
on Unicode
+-->
+
<partintro xmlns="http://docbook.org/ns/docbook";>
<para>
The Zend API has evolved considerably over time, as PHP has become a more
http://cvs.php.net/viewvc.cgi/phpdoc/en/internals2/structure/index.xml?r1=1.2&r2=1.3&diff_format=u
Index: phpdoc/en/internals2/structure/index.xml
diff -u phpdoc/en/internals2/structure/index.xml:1.2
phpdoc/en/internals2/structure/index.xml:1.3
--- phpdoc/en/internals2/structure/index.xml:1.2 Wed Jun 20 22:39:08 2007
+++ phpdoc/en/internals2/structure/index.xml Thu Jun 21 00:30:22 2007
@@ -1,9 +1,24 @@
<?xml version="1.0" encoding="ISO-8859-1" ?>
-<!-- $Revision: 1.2 $ -->
- <chapter xml:id="internals2.structure" xmlns="http://docbook.org/ns/docbook";>
+<!-- $Revision: 1.3 $ -->
+ <chapter xml:id="internals2.structure" xmlns="http://docbook.org/ns/docbook";
xmlns:xlink="http://www.w3.org/1999/xlink";>
+
<title>Extension structure</title>
<para>
+ Many extension-writing guides focus on simple examples first and ignore the
+ requirements of more complex implementations until later. Often such guides
+ must repeat themselves over and over in order to describe these new
+ features. This section describes extension structure from the perspective of
+ a mature, practical implementation, in order to prepare users for needs and
+ issues they will almost always encounter in the process of extension
+ development.
</para>
+
+ &internals2.structure.files;
+ &internals2.structure.modstruct;
+ &internals2.structure.globals;
+ &internals2.structure.lifecycle;
+ &internals2.structure.tests;
+
</chapter>
<!-- Keep this comment at the end of the file
http://cvs.php.net/viewvc.cgi/phpdoc/entities/global.ent?r1=1.299&r2=1.300&diff_format=u
Index: phpdoc/entities/global.ent
diff -u phpdoc/entities/global.ent:1.299 phpdoc/entities/global.ent:1.300
--- phpdoc/entities/global.ent:1.299 Wed Jun 20 22:25:41 2007
+++ phpdoc/entities/global.ent Thu Jun 21 00:30:22 2007
@@ -1,6 +1,6 @@
<!-- -*- SGML -*-
- $Id: global.ent,v 1.299 2007/06/20 22:25:41 bjori Exp $
+ $Id: global.ent,v 1.300 2007/06/21 00:30:22 gwynne Exp $
Contains global "macros" for all the XML documents.
@@ -261,6 +261,7 @@
<!ENTITY url.pdf.phppdflib "http://www.potentialtech.com/ppl.php";>
<!ENTITY url.pdf.ros "http://www.ros.co.nz/pdf/";>
<!ENTITY url.pdflib.merz "http://www.pdflib.com/corporate/people/tm.html";>
+<!ENTITY url.pear "http://pear.php.net/";>
<!ENTITY url.pear.package "http://pear.php.net/package/";>
<!-- linking to specific pear packages is done like so:
&url.pear.package;package_name -->
<!ENTITY url.pecl "http://pecl.php.net/";>
@@ -444,6 +445,9 @@
<!ENTITY link.superglobals '<link
linkend="language.variables.predefined">superglobals</link>'>
<!ENTITY link.autoload '<link
linkend="language.oop5.autoload">__autoload</link>'>
+<!ENTITY link.pear '<link xmlns:xlink="http://www.w3.org/1999/xlink";
xlink:href="&url.pear;">PEAR</link>'>
+<!ENTITY link.pecl '<link xmlns:xlink="http://www.w3.org/1999/xlink";
xlink:href="&url.pecl;">PECL</link>'>
+
<!ENTITY spec.cookies 'http://wp.netscape.com/newsref/std/cookie_spec.html'>
<!ENTITY spec.strftime
'http://www.opengroup.org/onlinepubs/007908799/xsh/strftime.html'>
<!ENTITY spec.hyperwave 'http://citeseer.ist.psu.edu/andrews95serving.html'>
http://cvs.php.net/viewvc.cgi/phpdoc/en/internals2/structure/files.xml?view=markup&rev=1.1
Index: phpdoc/en/internals2/structure/files.xml
+++ phpdoc/en/internals2/structure/files.xml
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!-- $Revision: 1.1 $ -->
<sect1 xml:id="internals2.structure.files"
xmlns="http://docbook.org/ns/docbook";
xmlns:xlink="http://www.w3.org/1999/xlink";>
<title>Files which make up an extension</title>
<para>
Whether created by hand, using <command>ext_skel</command>, or by an
alternate extension generator, such as
<link xlink:href="http://codegenerators.php-baustelle.de/";>CodeGen</link>,
all extensions will have at least four files:
</para>
<variablelist>
<varlistentry>
<term><filename>config.m4</filename></term>
<listitem>
<para>
UNIX build system configuration (see
<xref linkend="internals2.buildsys.configunix"/>)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>config.w32</filename></term>
<listitem>
<para>
Windows buildsystem configuration (see
<xref linkend="internals2.buildsys.configwin"/>)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>php_example.h</filename></term>
<listitem>
<para>
Main extension header file. By convention, the name of this file is
<literal>php_</literal> prepended to the extension name, but this is not
a requirement. This file contains macros, prototypes, and globals, just
like any header.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>example.c</filename></term>
<listitem>
<para>
Main extension source file. Again by convention, this name of this file
is the extension name, but again this is not a requirement. This file
contains the module structure declaration, INI entries, management
functions, userspace functions, and other requirements of an extension.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
The buildsystem files are discussed elsewhere; this section concentrates on
the rest. These four files make up the bare minimum for an extension, which
may also contain any number of headers, source files, unit tests, and other
support files. The list of files in a realistic extension might look like
this:
</para>
<example xml:id="internals2.structure.files.ex1">
<title>Files in an example "real" extension, in no particular
order</title>
<screen>
<![CDATA[
ext/
example/
.cvsignore
config.m4
config.w32
example_util.h
example_util.c
php_example.h
example.c
package.xml
CREDITS
tests/
critical_function_001.phpt
critical_function_002.phpt
optional_function_001.phpt
optional_function_002.phpt
]]>
</screen>
</example>
<sect2 xml:id="internals2.structure.files.misc-files">
<title>Non-source files</title>
<para>
The <filename>.cvsignore</filename> file is used for extensions which are
checked into one of the PHP <command>CVS</command> repositories (usually
&link.pecl;); the one generated by <command>ext_skel</command> contains:
</para>
<informalexample>
<programlisting role="cvsignore">
<![CDATA[..deps
*.lo
*.la
]]>
</programlisting>
</informalexample>
<para>
These lines tell <command>CVS</command> to ignore interim files generated
by the PHP buildsystem. This is only a convenience, and can be omitted
completely without ill effect.
</para>
<para>
The <filename>CREDITS</filename> file lists the contributors and/or
maintainers of the extension in plain text format, preferably including
contact information, and sometimes a website for the extension. This file
is only one way to document this information. In a &link.pecl; package,
this information is already maintained in <filename>package.xml</filename>,
for example. This is another file which can be omitted without ill effect.
</para>
<para>
The <filename>package.xml</filename> file is specific to &link.pecl;-based
extensions; it is a metainformation file which gives details about an
extension's dependencies, authors, installation requirements, and other
tidbits. In an extension not being hosted in &link.pecl;, this file is
extraneous.
</para>
</sect2>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
http://cvs.php.net/viewvc.cgi/phpdoc/en/internals2/structure/globals.xml?view=markup&rev=1.1
Index: phpdoc/en/internals2/structure/globals.xml
+++ phpdoc/en/internals2/structure/globals.xml
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!-- $Revision: 1.1 $ -->
<sect1 xml:id="internals2.structure.globals"
xmlns="http://docbook.org/ns/docbook";
xmlns:xlink="http://www.w3.org/1999/xlink";>
<title>Extension globals</title>
<para/>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
http://cvs.php.net/viewvc.cgi/phpdoc/en/internals2/structure/lifecycle.xml?view=markup&rev=1.1
Index: phpdoc/en/internals2/structure/lifecycle.xml
+++ phpdoc/en/internals2/structure/lifecycle.xml
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!-- $Revision: 1.1 $ -->
<sect1 xml:id="internals2.structure.lifecycle"
xmlns="http://docbook.org/ns/docbook";
xmlns:xlink="http://www.w3.org/1999/xlink";>
<title>Life cycle of an extension</title>
<para/>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
http://cvs.php.net/viewvc.cgi/phpdoc/en/internals2/structure/modstruct.xml?view=markup&rev=1.1
Index: phpdoc/en/internals2/structure/modstruct.xml
+++ phpdoc/en/internals2/structure/modstruct.xml
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!-- $Revision: 1.1 $ -->
<sect1 xml:id="internals2.structure.modstruct"
xmlns="http://docbook.org/ns/docbook";
xmlns:xlink="http://www.w3.org/1999/xlink";>
<title>The zend_module structure</title>
<para/>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
http://cvs.php.net/viewvc.cgi/phpdoc/en/internals2/structure/tests.xml?view=markup&rev=1.1
Index: phpdoc/en/internals2/structure/tests.xml
+++ phpdoc/en/internals2/structure/tests.xml
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!-- $Revision: 1.1 $ -->
<sect1 xml:id="internals2.structure.tests"
xmlns="http://docbook.org/ns/docbook";
xmlns:xlink="http://www.w3.org/1999/xlink";>
<title>Testing an extension</title>
<para/>
</sect1>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
