cvs: phpdoc / README /RFC book.xml constants.xml setup.xml /RFC/skeletons .cvsignore book.xml classname.xml configure.xml constants.xml function.xml
ini.xml method.xml reference.xml setup.xml
| From: | Hannes Magnusson | Date: | Fri, 28 Dec 2007 18:03:26 +0000 |
| Subject: | cvs: phpdoc / README /RFC book.xml constants.xml setup.xml /RFC/skeletons .cvsignore book.xml classname.xml configure.xml constants.xml function.xml ini.xml method.xml reference.xml setup.xml |
||
| Groups: | php.doc.cvs | ||
| Request: | Send a blank email to doc-cvs+get-900@lists.php.net to get a copy of this message | ||
bjori Fri Dec 28 18:03:26 2007 UTC
Added files:
/phpdoc/RFC/skeletons .cvsignore book.xml classname.xml
configure.xml constants.xml function.xml
ini.xml method.xml reference.xml setup.xml
Removed files:
/phpdoc/RFC book.xml constants.xml setup.xml
Modified files:
/phpdoc README
Log:
Add phpdoc skeletons to RFC/skeletons/
http://cvs.php.net/viewvc.cgi/phpdoc/README?r1=1.38&r2=1.39&diff_format=u Index: phpdoc/README diff -u phpdoc/README:1.38 phpdoc/README:1.39 --- phpdoc/README:1.38 Fri Dec 28 01:31:17 2007 +++ phpdoc/README Fri Dec 28 18:03:25 2007 @@ -36,16 +36,17 @@ FILE LOCATIONS --------------------------------------------------------------------------- The file locations are as follows: - + {lang}/reference/{extension} + /book.xml /setup.xml /configure.xml [often part of setup.xml] /constants.xml /ini.xml [often part of setup.xml] When the extension defines functions: - /functions/{function}.xml /reference.xml + /functions/{function}.xml When the exetnsion defines classess: /{classname}.xml @@ -54,6 +55,7 @@ /entities.*.xml (autogenerated) Translated files live within their own CVS modules. + (Skeletons for these files are available in RFC/skeletons/) --------------------------------------------------------------------------- QUICK REFERENCE http://cvs.php.net/viewvc.cgi/phpdoc/RFC/skeletons/.cvsignore?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/.cvsignore +++ phpdoc/RFC/skeletons/.cvsignore entities.*.xml http://cvs.php.net/viewvc.cgi/phpdoc/RFC/skeletons/book.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/book.xml +++ phpdoc/RFC/skeletons/book.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <book xml:id="book.extname" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <title>Extname</title> <titleabbrev>Extname...</titleabbrev> <!-- {{{ preface --> <preface xml:id="intro.extname"> &reftitle.intro; <para> Extension introduction. </para> </preface> <!-- }}} --> &reference.extname.setup; &reference.extname.constants; &reference.extname.reference; </book> <!-- 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/RFC/skeletons/classname.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/classname.xml +++ phpdoc/RFC/skeletons/classname.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <reference xml:id="class.classname" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> <title>The ClassName class</title> <titleabbrev>ClassName</titleabbrev> <partintro> <!-- {{{ ClassName intro --> <section xml:id="classname.intro"> &reftitle.intro; <para> Description of the class. </para> </section> <!-- }}} --> <section xml:id="classname.synopsis"> &reftitle.classsynopsis; <!-- {{{ Synopsis --> <classsynopsis> <ooclass><classname>ClassName</classname></ooclass> <!-- {{{ Class synopsis --> <classsynopsisinfo> <ooclass> <classname>ClassName</classname> </ooclass> <!-- If the class extends another one, use this <ooclass> <modifier>extends</modifier> <classname>BaseClassName</classname> </ooclass> --> <!-- If the class implements an interface, or two, use this (one oointerface element per interface) <oointerface> <interfacename>InterfaceName</interfacename> </oointerface> --> </classsynopsisinfo> <!-- }}} --> <classsynopsisinfo role="comment">Properties</classsynopsisinfo> <!-- If the property is documented below (xml:id=classname.props) use this <fieldsynopsis> <modifier>public</modifier> <type>string</type> <varname linkend="classname.props.name">name</varname> </fieldsynopsis> --> <!-- If properties are documented "as a method", use this <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.classname')/db:refentry/db:refsect1[@role='description']/descendant::db:fieldsynopsis[1])" /> --> <classsynopsisinfo role="comment">Methods</classsynopsisinfo> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.classname')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" /> <!-- If the class extends a class use this <classsynopsisinfo role="comment">Inherited methods</classsynopsisinfo> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.baseclassname')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" /> </classsynopsis> --> <!-- }}} --> </section> <!-- {{{ ClassName properties <section xml:id="classname.props"> &reftitle.properties; <variablelist> <varlistentry xml:id="classname.props.name"> <term><varname>name</varname></term> <listitem> <para>Prop description</para> </listitem> </varlistentry> </variablelist> </section> --> <!-- }}} --> </partintro> &reference.extname.classname.entities; </reference> <!-- 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/RFC/skeletons/configure.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/configure.xml +++ phpdoc/RFC/skeletons/configure.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <section xml:id="extname.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> &reftitle.install; <!-- If the extension doesn't need to be installed (built-in extension) use this entity --> <!-- &no.install; --> <!-- There are various PECL related entities in language-snippets.ent --> <para> To enable extname support, configure PHP with <option role="configure">theconfigoption</option> </para> <para> Windows users ... </para> </section> <!-- 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/RFC/skeletons/constants.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/constants.xml +++ phpdoc/RFC/skeletons/constants.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <appendix xml:id="extname.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> &reftitle.constants; &extension.constants; <!-- If the extension doesn't define any constants, use this entity --> <!-- &no.constants; --> <para> <variablelist> <varlistentry> <term> <constant>CONSTANT_NAME</constant> (<type>itstype</type>) </term> <listitem> <simpara> The constant description. </simpara> </listitem> </varlistentry> <varlistentry> <term> <constant>CONSTANT2_NAME</constant> (<type>itstype</type>) </term> <listitem> <simpara> The description. </simpara> </listitem> </varlistentry> </variablelist> </para> </appendix> <!-- 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/RFC/skeletons/function.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/function.xml +++ phpdoc/RFC/skeletons/function.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <refentry xml:id="function.func-name" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <refnamediv> <refname>func_name</refname> <refpurpose>The func_name purpose</refpurpose> </refnamediv> <refsect1 role="description"><!-- {{{ --> &reftitle.description; <methodsynopsis> <!-- Example: All functions have this --> <type>thereturned type</type><methodname>func_name</methodname> <!-- Example: Required parameter --> <methodparam><type>param1type</type><parameter>firstparameter</parameter></methodparam> <!-- Example: Optional parameter, also by reference --> <methodparam choice="opt"><type>int</type><parameter role="reference">secondparameter</parameter></methodparam> <!-- Example: If no methodparams exist (void), use this --> <void /> </methodsynopsis> <para> The function description goes here. </para> </refsect1><!-- }}} --> <refsect1 role="parameters"><!-- {{{ --> &reftitle.parameters; <para> <variablelist> <varlistentry> <term><parameter>firstparameter</parameter></term> <listitem> <para> Its description </para> </listitem> </varlistentry> <varlistentry> <term><parameter>secondparameter</parameter></term> <listitem> <para> Its description </para> </listitem> </varlistentry> </variablelist> </para> </refsect1><!-- }}} --> <refsect1 role="returnvalues"><!-- {{{ --> &reftitle.returnvalues; <para> What this function returns, first on success, then failure. If simply true on success and false on failure, just use &return.success; here. </para> </refsect1><!-- }}} --> <refsect1 role="errors"><!-- {{{ --> &reftitle.errors; <para> When does this function issue E_* level errors, and/or throw exceptions. </para> </refsect1><!-- }}} --> <refsect1 role="unicode"><!-- {{{ --> &reftitle.unicode; <para> Information specific to unicode, from the PHP 6 changes. </para> </refsect1><!-- }}} --> <refsect1 role="changelog"><!-- {{{ --> &reftitle.changelog; <para> <informaltable> <tgroup cols="2"> <thead> <row> <entry>&Version;</entry> <entry>&Description;</entry> </row> </thead> <tbody> <row> <entry>Enter the version of change here</entry> <entry> Describe the change </entry> </row> </tbody> </tgroup> </informaltable> </para> </refsect1><!-- }}} --> <refsect1 role="examples"><!-- {{{ --> &reftitle.examples; <para> <example xml:id="function-name.example.basic"><!-- {{{ --> <title><function>function-name</function> example</title> <para> Any text that describes the purpose of the example, or what goes on in the example should be here. (Inside the <example> tag, not out). </para> <programlisting role="php"> <![CDATA[ <?php if ($anexample === true) { echo 'Use the PEAR Coding standards'; } if ($thereisoutput === 'and it is multiple lines') { echo 'Use a screen like we did below'; } ?> ]]> </programlisting> &example.outputs.similar; <screen> <![CDATA[ Use the PEAR Coding standards Use a screen like we did below ]]> </screen> </example><!-- }}} --> </para> </refsect1><!-- }}} --> <refsect1 role="notes"><!-- {{{ --> &reftitle.notes; <caution> <para> Any notes that don't fit anywhere else should go here. 90% of the time, notes, warnings or cautions are better placed in the parameters section. Consider that before using this section! </para> </caution> ¬e.language-construct; ¬e.not-bin-safe; ¬e.registerglobals; </refsect1><!-- }}} --> <refsect1 role="seealso"><!-- {{{ --> &reftitle.seealso; <para> <simplelist> <member><function>somefunc</function></member> <member><function>another_func</function></member> <member>The <link linkend="something">something appendix</link></member> </simplelist> </para> </refsect1><!-- }}} --> </refentry> <!-- 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/RFC/skeletons/ini.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/ini.xml +++ phpdoc/RFC/skeletons/ini.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <section xml:id="extname.configuration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> &reftitle.runtime; &extension.runtime; <!-- If the extension doesn't define any ini options, use this entity --> <!-- &no.config; --> <para> <table> <title>Extname &ConfigureOptions;</title> <tgroup cols="4"> <thead> <row> <entry>&Name;</entry> <entry>&Default;</entry> <entry>&Changeable;</entry> <entry>Changelog</entry> </row> </thead> <tbody> <row> <entry>theini_option</entry> <entry>itsvalue</entry> <entry>its PHP_INI_* value</entry> <entry>leave empty. this will be fiiled by an automatic script</entry> </row> <row> <entry>anotherini_option</entry> <entry>itsvalue</entry> <entry>its PHP_INI_* value</entry> <entry></entry> </row> </tbody> </tgroup> </table> &php_ini_constants; </para> &ini.descriptions.title; <para> <variablelist> <varlistentry xml:id="ini.extname.theini-option"> <term> <parameter>theini_option</parameter> <type>thetype</type> </term> <listitem> <para> Fill in the description of theini-option. </para> </listitem> </varlistentry> <varlistentry xml:id="ini.extname.anotherini-option"> <term> <parameter>anotherini_option</parameter> <type>thetype</type> </term> <listitem> <para> Fill in the description of anotherini-option. </para> </listitem> </varlistentry> </variablelist> </para> </section> <!-- 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/RFC/skeletons/method.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/method.xml +++ phpdoc/RFC/skeletons/method.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <refentry xml:id="classname.methodname" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <refnamediv> <refname>ClassName::methodName</refname> <refpurpose>The methodName purpose</refpurpose> </refnamediv> <refsect1 role="description"> &reftitle.description; <methodsynopsis> <!-- Example: All methods have this --> <type>thereturned type</type><methodname>ClassName::methodName</methodname> <!-- Example: Required parameter --> <methodparam><type>param1type</type><parameter>firstparameter</parameter></methodparam> <!-- Example: Optional parameter, also by reference --> <methodparam choice="opt"><type>int</type><parameter role="reference">secondparameter</parameter></methodparam> <!-- Example: If no methodparams exist (void), use this --> <void /> </methodsynopsis> <!-- If this is an property, not a method, use this instead <classsynopsis> <ooclass><classname>className</classname></ooclass> <fieldsynopsis><type>string</type><varname>name</varname></fieldsynopsis> </classsynopsis> --> <!-- Note: If the method/property has an alternate procedural mapping then the method/property synopsis MUST be listed BEFORE the function synopsis. See function.xml/refentry/refsect1[@role=descript]/methodsynopsis for how to describe the function synopsis. --> <para> The function description goes here. </para> </refsect1> <refsect1 role="parameters"> &reftitle.parameters; <para> <variablelist> <varlistentry> <term><parameter>firstparameter</parameter></term> <listitem> <para> Its description </para> </listitem> </varlistentry> <varlistentry> <term><parameter>secondparameter</parameter></term> <listitem> <para> Its description </para> </listitem> </varlistentry> </variablelist> </para> </refsect1> <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> What this function returns, first on success, then failure. If simply true on success and false on failure, just use &return.success; here. </para> </refsect1> <refsect1 role="errors"> &reftitle.errors; <para> When does this function issue E_* level errors, and/or throw exceptions. </para> </refsect1> <refsect1 role="unicode"> &reftitle.unicode; <para> Information specific to unicode, from the PHP 6 changes. </para> </refsect1> <refsect1 role="changelog"> &reftitle.changelog; <para> <informaltable> <tgroup cols="2"> <thead> <row> <entry>&Version;</entry> <entry>&Description;</entry> </row> </thead> <tbody> <row> <entry>Enter the version of change here</entry> <entry> Describe the change </entry> </row> </tbody> </tgroup> </informaltable> </para> </refsect1> <refsect1 role="examples"> &reftitle.examples; <para> <example> <title><function>functionname</function> example</title> <para> Any text that describes the purpose of the example, or what goes on in the example should be here. (Inside the <example> tag, not out). </para> <programlisting role="php"> <![CDATA[ <?php if ($anexample === true) { echo 'Use the PEAR Coding standards'; } if ($thereisoutput === 'and it is multiple lines') { echo 'Use a screen like we did below'; } ?> ]]> </programlisting> &example.outputs.similar; <screen> <![CDATA[ Use the PEAR Coding standards Use a screen like we did below ]]> </screen> </example> </para> </refsect1> <refsect1 role="notes"> &reftitle.notes; <caution> <para> Any notes that don't fit anywhere else should go here. 90% of the time, notes, warnings or cautions are better placed in the parameters section. Consider that before using this section! </para> </caution> ¬e.language-construct; ¬e.not-bin-safe; ¬e.registerglobals; </refsect1> <refsect1 role="seealso"> &reftitle.seealso; <para> <simplelist> <member><function>somefunc</function></member> <member><function>another_func</function></member> <member>The <link linkend="something">something appendix</link></member> </simplelist> </para> </refsect1> </refentry> <!-- 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/RFC/skeletons/reference.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/reference.xml +++ phpdoc/RFC/skeletons/reference.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <reference xml:id="ref.extname" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <title>Extname &Functions;</title> <titleabbrev>Extname</titleabbrev> <!-- Generally should not be used, only in rare cases where you find no other place for it. <partintro> <section xml:id="extname.foobar"> &reftitle.foobar; <para> Some text here. </para> </section> </partintro> --> &reference.extname.entities.functions; </reference> <!-- 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/RFC/skeletons/setup.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/setup.xml +++ phpdoc/RFC/skeletons/setup.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <chapter xml:id="extname.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> &reftitle.setup; <!-- {{{ Requirements --> <section xml:id="extname.requirements"> &reftitle.required; &no.requirement; </section> <!-- }}} --> <!-- {{{ Installation --> <section xml:id="extname.installation"> &reftitle.install; &no.install; </section> <!-- or &reference.extname.entities.configure; --> <!-- }}} --> <!-- {{{ Configuration --> <section xml:id="extname.configuration"> &reftitle.runtime; &no.config; </section> <!-- or &reference.extname.entities.ini; --> <!-- }}} --> <!-- {{{ Resources --> <section xml:id="extname.resources"> &reftitle.resources; &no.resource; </section> <!-- }}} --> </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:"../../../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/README?r1=1.38&r2=1.39&diff_format=u Index: phpdoc/README diff -u phpdoc/README:1.38 phpdoc/README:1.39 --- phpdoc/README:1.38 Fri Dec 28 01:31:17 2007 +++ phpdoc/README Fri Dec 28 18:03:25 2007 @@ -36,16 +36,17 @@ FILE LOCATIONS --------------------------------------------------------------------------- The file locations are as follows: - + {lang}/reference/{extension} + /book.xml /setup.xml /configure.xml [often part of setup.xml] /constants.xml /ini.xml [often part of setup.xml] When the extension defines functions: - /functions/{function}.xml /reference.xml + /functions/{function}.xml When the exetnsion defines classess: /{classname}.xml @@ -54,6 +55,7 @@ /entities.*.xml (autogenerated) Translated files live within their own CVS modules. + (Skeletons for these files are available in RFC/skeletons/) --------------------------------------------------------------------------- QUICK REFERENCE http://cvs.php.net/viewvc.cgi/phpdoc/RFC/skeletons/.cvsignore?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/.cvsignore +++ phpdoc/RFC/skeletons/.cvsignore entities.*.xml http://cvs.php.net/viewvc.cgi/phpdoc/RFC/skeletons/book.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/book.xml +++ phpdoc/RFC/skeletons/book.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <book xml:id="book.extname" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <title>Extname</title> <titleabbrev>Extname...</titleabbrev> <!-- {{{ preface --> <preface xml:id="intro.extname"> &reftitle.intro; <para> Extension introduction. </para> </preface> <!-- }}} --> &reference.extname.setup; &reference.extname.constants; &reference.extname.reference; </book> <!-- 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/RFC/skeletons/classname.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/classname.xml +++ phpdoc/RFC/skeletons/classname.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <reference xml:id="class.classname" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> <title>The ClassName class</title> <titleabbrev>ClassName</titleabbrev> <partintro> <!-- {{{ ClassName intro --> <section xml:id="classname.intro"> &reftitle.intro; <para> Description of the class. </para> </section> <!-- }}} --> <section xml:id="classname.synopsis"> &reftitle.classsynopsis; <!-- {{{ Synopsis --> <classsynopsis> <ooclass><classname>ClassName</classname></ooclass> <!-- {{{ Class synopsis --> <classsynopsisinfo> <ooclass> <classname>ClassName</classname> </ooclass> <!-- If the class extends another one, use this <ooclass> <modifier>extends</modifier> <classname>BaseClassName</classname> </ooclass> --> <!-- If the class implements an interface, or two, use this (one oointerface element per interface) <oointerface> <interfacename>InterfaceName</interfacename> </oointerface> --> </classsynopsisinfo> <!-- }}} --> <classsynopsisinfo role="comment">Properties</classsynopsisinfo> <!-- If the property is documented below (xml:id=classname.props) use this <fieldsynopsis> <modifier>public</modifier> <type>string</type> <varname linkend="classname.props.name">name</varname> </fieldsynopsis> --> <!-- If properties are documented "as a method", use this <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.classname')/db:refentry/db:refsect1[@role='description']/descendant::db:fieldsynopsis[1])" /> --> <classsynopsisinfo role="comment">Methods</classsynopsisinfo> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.classname')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" /> <!-- If the class extends a class use this <classsynopsisinfo role="comment">Inherited methods</classsynopsisinfo> <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.baseclassname')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[1])" /> </classsynopsis> --> <!-- }}} --> </section> <!-- {{{ ClassName properties <section xml:id="classname.props"> &reftitle.properties; <variablelist> <varlistentry xml:id="classname.props.name"> <term><varname>name</varname></term> <listitem> <para>Prop description</para> </listitem> </varlistentry> </variablelist> </section> --> <!-- }}} --> </partintro> &reference.extname.classname.entities; </reference> <!-- 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/RFC/skeletons/configure.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/configure.xml +++ phpdoc/RFC/skeletons/configure.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <section xml:id="extname.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> &reftitle.install; <!-- If the extension doesn't need to be installed (built-in extension) use this entity --> <!-- &no.install; --> <!-- There are various PECL related entities in language-snippets.ent --> <para> To enable extname support, configure PHP with <option role="configure">theconfigoption</option> </para> <para> Windows users ... </para> </section> <!-- 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/RFC/skeletons/constants.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/constants.xml +++ phpdoc/RFC/skeletons/constants.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <appendix xml:id="extname.constants" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> &reftitle.constants; &extension.constants; <!-- If the extension doesn't define any constants, use this entity --> <!-- &no.constants; --> <para> <variablelist> <varlistentry> <term> <constant>CONSTANT_NAME</constant> (<type>itstype</type>) </term> <listitem> <simpara> The constant description. </simpara> </listitem> </varlistentry> <varlistentry> <term> <constant>CONSTANT2_NAME</constant> (<type>itstype</type>) </term> <listitem> <simpara> The description. </simpara> </listitem> </varlistentry> </variablelist> </para> </appendix> <!-- 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/RFC/skeletons/function.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/function.xml +++ phpdoc/RFC/skeletons/function.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <refentry xml:id="function.func-name" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <refnamediv> <refname>func_name</refname> <refpurpose>The func_name purpose</refpurpose> </refnamediv> <refsect1 role="description"><!-- {{{ --> &reftitle.description; <methodsynopsis> <!-- Example: All functions have this --> <type>thereturned type</type><methodname>func_name</methodname> <!-- Example: Required parameter --> <methodparam><type>param1type</type><parameter>firstparameter</parameter></methodparam> <!-- Example: Optional parameter, also by reference --> <methodparam choice="opt"><type>int</type><parameter role="reference">secondparameter</parameter></methodparam> <!-- Example: If no methodparams exist (void), use this --> <void /> </methodsynopsis> <para> The function description goes here. </para> </refsect1><!-- }}} --> <refsect1 role="parameters"><!-- {{{ --> &reftitle.parameters; <para> <variablelist> <varlistentry> <term><parameter>firstparameter</parameter></term> <listitem> <para> Its description </para> </listitem> </varlistentry> <varlistentry> <term><parameter>secondparameter</parameter></term> <listitem> <para> Its description </para> </listitem> </varlistentry> </variablelist> </para> </refsect1><!-- }}} --> <refsect1 role="returnvalues"><!-- {{{ --> &reftitle.returnvalues; <para> What this function returns, first on success, then failure. If simply true on success and false on failure, just use &return.success; here. </para> </refsect1><!-- }}} --> <refsect1 role="errors"><!-- {{{ --> &reftitle.errors; <para> When does this function issue E_* level errors, and/or throw exceptions. </para> </refsect1><!-- }}} --> <refsect1 role="unicode"><!-- {{{ --> &reftitle.unicode; <para> Information specific to unicode, from the PHP 6 changes. </para> </refsect1><!-- }}} --> <refsect1 role="changelog"><!-- {{{ --> &reftitle.changelog; <para> <informaltable> <tgroup cols="2"> <thead> <row> <entry>&Version;</entry> <entry>&Description;</entry> </row> </thead> <tbody> <row> <entry>Enter the version of change here</entry> <entry> Describe the change </entry> </row> </tbody> </tgroup> </informaltable> </para> </refsect1><!-- }}} --> <refsect1 role="examples"><!-- {{{ --> &reftitle.examples; <para> <example xml:id="function-name.example.basic"><!-- {{{ --> <title><function>function-name</function> example</title> <para> Any text that describes the purpose of the example, or what goes on in the example should be here. (Inside the <example> tag, not out). </para> <programlisting role="php"> <![CDATA[ <?php if ($anexample === true) { echo 'Use the PEAR Coding standards'; } if ($thereisoutput === 'and it is multiple lines') { echo 'Use a screen like we did below'; } ?> ]]> </programlisting> &example.outputs.similar; <screen> <![CDATA[ Use the PEAR Coding standards Use a screen like we did below ]]> </screen> </example><!-- }}} --> </para> </refsect1><!-- }}} --> <refsect1 role="notes"><!-- {{{ --> &reftitle.notes; <caution> <para> Any notes that don't fit anywhere else should go here. 90% of the time, notes, warnings or cautions are better placed in the parameters section. Consider that before using this section! </para> </caution> ¬e.language-construct; ¬e.not-bin-safe; ¬e.registerglobals; </refsect1><!-- }}} --> <refsect1 role="seealso"><!-- {{{ --> &reftitle.seealso; <para> <simplelist> <member><function>somefunc</function></member> <member><function>another_func</function></member> <member>The <link linkend="something">something appendix</link></member> </simplelist> </para> </refsect1><!-- }}} --> </refentry> <!-- 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/RFC/skeletons/ini.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/ini.xml +++ phpdoc/RFC/skeletons/ini.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <section xml:id="extname.configuration" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> &reftitle.runtime; &extension.runtime; <!-- If the extension doesn't define any ini options, use this entity --> <!-- &no.config; --> <para> <table> <title>Extname &ConfigureOptions;</title> <tgroup cols="4"> <thead> <row> <entry>&Name;</entry> <entry>&Default;</entry> <entry>&Changeable;</entry> <entry>Changelog</entry> </row> </thead> <tbody> <row> <entry>theini_option</entry> <entry>itsvalue</entry> <entry>its PHP_INI_* value</entry> <entry>leave empty. this will be fiiled by an automatic script</entry> </row> <row> <entry>anotherini_option</entry> <entry>itsvalue</entry> <entry>its PHP_INI_* value</entry> <entry></entry> </row> </tbody> </tgroup> </table> &php_ini_constants; </para> &ini.descriptions.title; <para> <variablelist> <varlistentry xml:id="ini.extname.theini-option"> <term> <parameter>theini_option</parameter> <type>thetype</type> </term> <listitem> <para> Fill in the description of theini-option. </para> </listitem> </varlistentry> <varlistentry xml:id="ini.extname.anotherini-option"> <term> <parameter>anotherini_option</parameter> <type>thetype</type> </term> <listitem> <para> Fill in the description of anotherini-option. </para> </listitem> </varlistentry> </variablelist> </para> </section> <!-- 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/RFC/skeletons/method.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/method.xml +++ phpdoc/RFC/skeletons/method.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <refentry xml:id="classname.methodname" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <refnamediv> <refname>ClassName::methodName</refname> <refpurpose>The methodName purpose</refpurpose> </refnamediv> <refsect1 role="description"> &reftitle.description; <methodsynopsis> <!-- Example: All methods have this --> <type>thereturned type</type><methodname>ClassName::methodName</methodname> <!-- Example: Required parameter --> <methodparam><type>param1type</type><parameter>firstparameter</parameter></methodparam> <!-- Example: Optional parameter, also by reference --> <methodparam choice="opt"><type>int</type><parameter role="reference">secondparameter</parameter></methodparam> <!-- Example: If no methodparams exist (void), use this --> <void /> </methodsynopsis> <!-- If this is an property, not a method, use this instead <classsynopsis> <ooclass><classname>className</classname></ooclass> <fieldsynopsis><type>string</type><varname>name</varname></fieldsynopsis> </classsynopsis> --> <!-- Note: If the method/property has an alternate procedural mapping then the method/property synopsis MUST be listed BEFORE the function synopsis. See function.xml/refentry/refsect1[@role=descript]/methodsynopsis for how to describe the function synopsis. --> <para> The function description goes here. </para> </refsect1> <refsect1 role="parameters"> &reftitle.parameters; <para> <variablelist> <varlistentry> <term><parameter>firstparameter</parameter></term> <listitem> <para> Its description </para> </listitem> </varlistentry> <varlistentry> <term><parameter>secondparameter</parameter></term> <listitem> <para> Its description </para> </listitem> </varlistentry> </variablelist> </para> </refsect1> <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> What this function returns, first on success, then failure. If simply true on success and false on failure, just use &return.success; here. </para> </refsect1> <refsect1 role="errors"> &reftitle.errors; <para> When does this function issue E_* level errors, and/or throw exceptions. </para> </refsect1> <refsect1 role="unicode"> &reftitle.unicode; <para> Information specific to unicode, from the PHP 6 changes. </para> </refsect1> <refsect1 role="changelog"> &reftitle.changelog; <para> <informaltable> <tgroup cols="2"> <thead> <row> <entry>&Version;</entry> <entry>&Description;</entry> </row> </thead> <tbody> <row> <entry>Enter the version of change here</entry> <entry> Describe the change </entry> </row> </tbody> </tgroup> </informaltable> </para> </refsect1> <refsect1 role="examples"> &reftitle.examples; <para> <example> <title><function>functionname</function> example</title> <para> Any text that describes the purpose of the example, or what goes on in the example should be here. (Inside the <example> tag, not out). </para> <programlisting role="php"> <![CDATA[ <?php if ($anexample === true) { echo 'Use the PEAR Coding standards'; } if ($thereisoutput === 'and it is multiple lines') { echo 'Use a screen like we did below'; } ?> ]]> </programlisting> &example.outputs.similar; <screen> <![CDATA[ Use the PEAR Coding standards Use a screen like we did below ]]> </screen> </example> </para> </refsect1> <refsect1 role="notes"> &reftitle.notes; <caution> <para> Any notes that don't fit anywhere else should go here. 90% of the time, notes, warnings or cautions are better placed in the parameters section. Consider that before using this section! </para> </caution> ¬e.language-construct; ¬e.not-bin-safe; ¬e.registerglobals; </refsect1> <refsect1 role="seealso"> &reftitle.seealso; <para> <simplelist> <member><function>somefunc</function></member> <member><function>another_func</function></member> <member>The <link linkend="something">something appendix</link></member> </simplelist> </para> </refsect1> </refentry> <!-- 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/RFC/skeletons/reference.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/reference.xml +++ phpdoc/RFC/skeletons/reference.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <reference xml:id="ref.extname" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> <title>Extname &Functions;</title> <titleabbrev>Extname</titleabbrev> <!-- Generally should not be used, only in rare cases where you find no other place for it. <partintro> <section xml:id="extname.foobar"> &reftitle.foobar; <para> Some text here. </para> </section> </partintro> --> &reference.extname.entities.functions; </reference> <!-- 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/RFC/skeletons/setup.xml?view=markup&rev=1.1 Index: phpdoc/RFC/skeletons/setup.xml +++ phpdoc/RFC/skeletons/setup.xml <?xml version="1.0" encoding="utf-8"?> <!-- $Revision: 1.1 $ --> <chapter xml:id="extname.setup" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"> &reftitle.setup; <!-- {{{ Requirements --> <section xml:id="extname.requirements"> &reftitle.required; &no.requirement; </section> <!-- }}} --> <!-- {{{ Installation --> <section xml:id="extname.installation"> &reftitle.install; &no.install; </section> <!-- or &reference.extname.entities.configure; --> <!-- }}} --> <!-- {{{ Configuration --> <section xml:id="extname.configuration"> &reftitle.runtime; &no.config; </section> <!-- or &reference.extname.entities.ini; --> <!-- }}} --> <!-- {{{ Resources --> <section xml:id="extname.resources"> &reftitle.resources; &no.resource; </section> <!-- }}} --> </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:"../../../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 -->