cvs: phpdoc /howto howto.ent howto.xml scripts.xml working.xml

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"> &lt;?xml version="1.0" encoding="iso-8859-1"?&gt; -&lt;!-- $Revision: 1.59 $ --&gt; +&lt;!-- $Revision: 1.60 $ --&gt; &lt;refentry id="function.func-name"&gt; &lt;refnamediv&gt; &lt;refname&gt;func_name&lt;/refname&gt; @@ -653,7 +653,10 @@ <title>A <filename>reference.xml</filename> skeleton</title> <programlisting role="xml"> &lt;?xml version="1.0" encoding="iso-8859-1"?&gt; -&lt;!-- $Revision: 1.59 $ --&gt; +&lt;!-- $Revision: 1.60 $ --&gt; +&lt;!-- Purpose: xx --&gt; +&lt;!-- Membership: xx --&gt; +&lt;!-- State: xx --&gt; &lt;reference id="ref.extname"&gt; &lt;title&gt;Extname &amp;Functions;&lt;/title&gt; &lt;titleabbrev&gt;Extname&lt;/titleabbrev&gt; @@ -720,7 +723,7 @@ <title>A <filename>configure.xml</filename> skeleton</title> <programlisting role="xml"> &lt;?xml version="1.0" encoding="iso-8859-1"?&gt; -&lt;!-- $Revision: 1.59 $ --&gt; +&lt;!-- $Revision: 1.60 $ --&gt; &lt;section id="extname.installation"&gt; &amp;reftitle.install; &lt;para&gt; @@ -761,7 +764,7 @@ <title>A <filename>constants.xml</filename> skeleton</title> <programlisting role="xml"> &lt;?xml version="1.0" encoding="iso-8859-1"?&gt; -&lt;!-- $Revision: 1.59 $ --&gt; +&lt;!-- $Revision: 1.60 $ --&gt; &lt;section id="extname.constants"&gt; &amp;reftitle.constants; &amp;extension.constants; @@ -811,7 +814,7 @@ <title>A <filename>ini.xml</filename> skeleton</title> <programlisting role="xml"> &lt;?xml version="1.0" encoding="iso-8859-1"?&gt; -&lt;!-- $Revision: 1.59 $ --&gt; +&lt;!-- $Revision: 1.60 $ --&gt; &lt;section id="extname.configuration"&gt; &amp;reftitle.runtime; &amp;extension.runtime; @@ -824,6 +827,7 @@ &lt;entry&gt;&amp;Name;&lt;/entry&gt; &lt;entry&gt;&amp;Default;&lt;/entry&gt; &lt;entry&gt;&amp;Changeable;&lt;/entry&gt; + &lt;entry&gt;Changelog&lt;/entry&gt; &lt;/row&gt; &lt;/thead&gt; &lt;tbody&gt; @@ -831,6 +835,7 @@ &lt;entry&gt;theini_option&lt;/entry&gt; &lt;entry&gt;itsvalue&lt;/entry&gt; &lt;entry&gt;its PHP_INI_* value&lt;/entry&gt; + &lt;entry&gt;leave this blank. it will be filled automatically&lt;/entry&gt; &lt;/row&gt; &lt;/tbody&gt; &lt;/tgroup&gt; @@ -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>&lt;!-- Purpose: xx --&gt;</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>&lt;!ENTITY extcat.purpose.xml '&lt;title&gt;XML Manipulation&lt;/title&gt;'&gt;</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>&lt;!-- Membership: xx, yy --&gt;</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>&lt;!-- State: xx --&gt;</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 &gt;= 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 -->