nlopess Wed Sep 7 15:13:12 2005 EDT
Added files:
/phpdoc/howto scripts.xml
Modified files:
/phpdoc/howto howto.ent howto.xml working.xml
Log:
add a new file to document our scripts. we have lots of them, all
unodocumented till now.
documeting the new purpose, membership and state tags
http://cvs.php.net/diff.php/phpdoc/howto/howto.ent?r1=1.31&r2=1.32&ty=u
Index: phpdoc/howto/howto.ent
diff -u phpdoc/howto/howto.ent:1.31 phpdoc/howto/howto.ent:1.32
--- phpdoc/howto/howto.ent:1.31 Sun Aug 21 09:03:02 2005
+++ phpdoc/howto/howto.ent Wed Sep 7 15:13:10 2005
@@ -91,6 +91,9 @@
<!ENTITY url.user-notes
"http://cvs.php.net/co.php/php-master-web/manage/user-notes.php";>
<!ENTITY url.notes.admin "http://master.php.net/manage/user-notes.php";>
+<!-- Scripts section -->
+<!ENTITY url.extension.cat "http://php.net/manual/en/extensions.php";>
+
<!-- For Misc section -->
<!ENTITY url.rtfs "http://www.fooassociates.com/rtfs/";>
<!ENTITY url.zend.phpfunc "http://www.zend.com/phpfunc/";>
http://cvs.php.net/diff.php/phpdoc/howto/howto.xml?r1=1.49&r2=1.50&ty=u
Index: phpdoc/howto/howto.xml
diff -u phpdoc/howto/howto.xml:1.49 phpdoc/howto/howto.xml:1.50
--- phpdoc/howto/howto.xml:1.49 Sun Apr 3 05:46:01 2005
+++ phpdoc/howto/howto.xml Wed Sep 7 15:13:10 2005
@@ -13,6 +13,7 @@
<!ENTITY howto.cvs SYSTEM "cvs.xml">
<!ENTITY howto.docbook SYSTEM "docbook.xml">
<!ENTITY howto.working SYSTEM "working.xml">
+ <!ENTITY howto.scripts SYSTEM "scripts.xml">
<!ENTITY howto.generating SYSTEM "generating.xml">
<!ENTITY howto.editors SYSTEM "editors.xml">
http://cvs.php.net/diff.php/phpdoc/howto/working.xml?r1=1.59&r2=1.60&ty=u
Index: phpdoc/howto/working.xml
diff -u phpdoc/howto/working.xml:1.59 phpdoc/howto/working.xml:1.60
--- phpdoc/howto/working.xml:1.59 Sun Aug 21 09:03:03 2005
+++ phpdoc/howto/working.xml Wed Sep 7 15:13:10 2005
@@ -494,7 +494,7 @@
<title>A function skeleton (<filename>func-name.xml</filename>)</title>
<programlisting role="xml">
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.59 $ -->
+<!-- $Revision: 1.60 $ -->
<refentry id="function.func-name">
<refnamediv>
<refname>func_name</refname>
@@ -653,7 +653,10 @@
<title>A <filename>reference.xml</filename> skeleton</title>
<programlisting role="xml">
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.59 $ -->
+<!-- $Revision: 1.60 $ -->
+<!-- Purpose: xx -->
+<!-- Membership: xx -->
+<!-- State: xx -->
<reference id="ref.extname">
<title>Extname &Functions;</title>
<titleabbrev>Extname</titleabbrev>
@@ -720,7 +723,7 @@
<title>A <filename>configure.xml</filename> skeleton</title>
<programlisting role="xml">
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.59 $ -->
+<!-- $Revision: 1.60 $ -->
<section id="extname.installation">
&reftitle.install;
<para>
@@ -761,7 +764,7 @@
<title>A <filename>constants.xml</filename> skeleton</title>
<programlisting role="xml">
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.59 $ -->
+<!-- $Revision: 1.60 $ -->
<section id="extname.constants">
&reftitle.constants;
&extension.constants;
@@ -811,7 +814,7 @@
<title>A <filename>ini.xml</filename> skeleton</title>
<programlisting role="xml">
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.59 $ -->
+<!-- $Revision: 1.60 $ -->
<section id="extname.configuration">
&reftitle.runtime;
&extension.runtime;
@@ -824,6 +827,7 @@
<entry>&Name;</entry>
<entry>&Default;</entry>
<entry>&Changeable;</entry>
+ <entry>Changelog</entry>
</row>
</thead>
<tbody>
@@ -831,6 +835,7 @@
<entry>theini_option</entry>
<entry>itsvalue</entry>
<entry>its PHP_INI_* value</entry>
+ <entry>leave this blank. it will be filled
automatically</entry>
</row>
</tbody>
</tgroup>
@@ -1958,6 +1963,8 @@
</para>
</chapter>
+ &howto.scripts;
+
<chapter id="chapter-misc">
<title>Miscellaneous Notes</title>
http://cvs.php.net/co.php/phpdoc/howto/scripts.xml?r=1.1&p=1
Index: phpdoc/howto/scripts.xml
+++ phpdoc/howto/scripts.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<chapter id="chapter-scripts">
<title>Automatization with scripts</title>
<para>
The PHP manual is very big and the PHP sources change every day. To help the
documentation writers's work, we have developed a couple of scripts during
the last years. Below you will find a list of the scripts, as well a short
explanation and usage tips for each one.
</para>
<sect1 id="scripts.extensions.xml.php">
<title>extensions.xml.php</title>
<para>
The <filename>extensions.xml.php</filename> script creates the <ulink
url="&url.extension.cat;">extension categorization appendix</ulink>. It
collects the data from the reference.xml files and updates the
<filename>en/appendices/extensions.xml</filename> file.
</para>
<para>
The tags supported for the <filename>reference/*/reference.xml</filename>
files include:
<table>
<title/>
<tgroup cols="2">
<thead>
<row>
<entry>Tag</entry>
<entry>Explanation</entry>
</row>
</thead>
<tbody>
<row>
<entry><!-- Purpose: xx --></entry>
<entry>
<para>
The purpose of the extension, specified by an ID. There are several
IDs available, which can be consulted in the
<filename>en/entensions.ent</filename> file. They look like
<literal>database.vendors</literal> or <literal>xml</literal>.
</para>
<para>
If none of the available categories fits your extension, you can
create a new one. To do so, you must add a new entity in the
<filename>en/entensions.ent</filename> file, like:
<literal><!ENTITY extcat.purpose.xml '<title>XML
Manipulation</title>'></literal>. After this, you still
need to edit <filename>en/appendices/extensions.xml</filename> and
create a new section for your ID, by copying an already existent
section. This isn't done automatically to allow you to choose the
order of the sections.
</para>
</entry>
</row>
<row>
<entry><!-- Membership: xx, yy --></entry>
<entry>
This tag can have multiple values, that should be separated by commas.
Valid values include: <literal>core</literal> (for PHP core
extensions, like the strings or date extension),
<literal>pecl</literal> (if the extension lives in PECL),
<literal>bundled</literal> (if the extension is bundled with the main
PHP distribution), and <literal>external</literal> (if the extension
relies on external - and not bundled - libraries).
</entry>
</row>
<row>
<entry><!-- State: xx --></entry>
<entry>
This tag is optional and can only have two values, either
<literal>deprecated</literal> or <literal>experimental</literal>.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<note>
<para>
If you mark an extension as deprecated and if it is very old and unusable,
you shouldn't add the purpose and membership tags, so that the extension
doesn't appear in the appendix (to avoid confusing users).
</para>
</note>
<para>
The script should warn you for missing tags or even bogus values, although
it won't report any XML errors. So, you have the responsability to run
<command>make test</command> before running this script. Failing to do so,
may lead to unexpected results.
</para>
<note>
<para>
This script requires PHP >= 5 with SimpleXML.
</para>
</note>
</sect1>
</chapter>
<!-- 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:"howto.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
-->
